3D Ödeme
3D Ödeme Servisi İstek Modeli
| Method | Endpoint | Body |
|---|---|---|
| POST | /external/vpos/v1/payments | JSON |
Bu servis kart bilgisini sizin sunucunuzdan alır; bu yüzden sisteminizin PCI DSS uyumlu olması gerekir. Kart bilgisini hiç almadan ödeme almak için Ödeme Sayfası entegrasyonunu kullanın.
3D Ödeme Servisi İşlem Akışı
- Üye işyeri, kart, sepet, tutar ve taksit bilgilerini, ödeme sonucunda kullanıcının döneceği kendi web adresiyle (returnUrl) birlikte sunucusundan TahsilatE 3D ödeme servisine gönderir.
- TahsilatE, isteği doğrular ve ödemeyi banka tarafında başlatır.
- Ödeme başlatıldıysa cevapta 3D doğrulama için bir form ya da url döner. Üye işyeri, threeD.type alanına göre kullanıcıyı 3D doğrulama ekranına yönlendirir.
- 3D doğrulamadan sonra TahsilatE ödemeyi sonuçlandırır ve kullanıcının tarayıcısını imzalı sonuç parametreleriyle returnUrl adresine yönlendirir (GET).
Detaylı işlem akışını buradan inceleyebilirsiniz.
3D Ödeme Servisi İstek Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| transactionId | string | Evet | Sizin ürettiğiniz benzersiz işlem ID'si, en fazla 64 karakter. Kullanılmış bir değer HTTP 409 alır; başarısız ödemeyi tekrar denerken yeni bir ID üretin. |
| amount | number | Evet | Komisyonsuz ödeme tutarı (TL). 0.1 ile 1.000.000.000 arasında, en fazla 2 ondalık. Komisyonu müşterinin ödediği (CUSTOMER) taksitlerde vade farkını ödeme kuruluşu ekler; müşteriye ödemeden önce Taksit Listeleme'deki totalAmount'u gösterin. |
| installment | number | Evet | Taksit sayısı, 1-12. Tek çekim için 1. |
| description | string | Evet | Ödeme açıklaması, en fazla 255 karakter. |
| returnUrl | string | Evet | 3D doğrulamadan sonra kullanıcının yönlendirileceği adresiniz. Sonuç parametreleri query string olarak eklenir; adresin kendi query string'i varsa korunur. |
| card | object | Evet | Kart bilgileri. |
| customer | object | Evet | Müşteri bilgileri. |
| items | array | Evet | Sepet. Gönderilirse productPrice × quantity toplamı amount'a eşit olmalıdır. |
card
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| holderName | string | Evet | Kart sahibi adı. |
| number | string | Evet | Kart numarası, 13-19 hane, boşluksuz. |
| expiryMonth | string | Evet | Son kullanma ayı, 2 hane (örn. "07"). |
| expiryYear | string | Evet | Son kullanma yılı, 4 hane (örn. "2030"). |
| cvv | string | Evet | Güvenlik kodu, 3 veya 4 hane. |
customer
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| name | string | Evet | Ad. |
| surname | string | Evet | Soyad. |
string | Evet | E-posta adresi. | |
| phoneNumber | string | Evet | Telefon numarası. |
| ip | string | Evet | Kart sahibinin IP adresi (sizin sunucunuzun değil). Banka dolandırıcılık kontrolünde kullanır. |
| city | string | Evet | Şehir. |
| district | string | Evet | İlçe. |
| address | string | Evet | Adres. |
items
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| productId | string | Evet | Ürün kodu. |
| productName | string | Evet | Ürün adı. |
| productCategory | string | Evet | Ürün kategorisi. |
| productPrice | number | Evet | Birim fiyat (indirimler dahil), negatif olamaz. |
| quantity | number | Evet | Adet, en az 1. |
Örnek İstek JSON
Ürünlerin toplamı (40.25 × 2) ödeme tutarına (80.5) eşittir.
123456789101112131415161718192021222324252627282930313233
Başarılı Cevap (content)
HTTP 200. Ödeme başlatıldı; kullanıcıyı 3D ekranına yönlendirin.
| Parametre | Tip | Açıklama |
|---|---|---|
| transactionId | string | İstekte gönderdiğiniz işlem ID'si. |
| amount | number | Ödeme tutarı. |
| installment | number | Taksit sayısı. |
| threeD.type | string | "form" ise threeD.form'daki HTML'i sayfada çalıştırın, "url" ise kullanıcıyı threeD.url adresine yönlendirin. |
| threeD.form | string | Kullanıcıyı bankanın 3D doğrulama ekranına götüren, kendiliğinden gönderilen HTML form (type "form" ise). |
| threeD.url | string | Bankanın 3D doğrulama ekranı adresi (type "url" ise). |
Örnek Başarılı Cevap
123456789101112
Hata Durumları
| HTTP | Tür | Açıklama |
|---|---|---|
| 400 | Doğrulama / iş kuralı | Eksik veya geçersiz alan, son kullanma tarihi geçmiş kart, taksit bu tutar veya kart için kapalı, sepet toplamı tutara eşit değil. |
| 401 | Kimlik doğrulama | İmza, zaman damgası veya API anahtarı geçersiz. |
| 409 | Çakışma | transactionId daha önce kullanılmış. |
| 422 | Banka reddi | Banka ödemeyi başlatmadı. İşlem FAILED olarak kaydedilir; mesajı kullanıcıya gösterin ve tekrar denerken yeni bir transactionId kullanın. |
Banka Ödemeyi Başlatmadığında (HTTP 422)
1234
Doğrulama Hatası (content alanı)
HTTP 400. Eksik veya hatalı alanlar listelenir.
| Parametre | Tip | Açıklama |
|---|---|---|
| field | string | Hatalı alan. İç içe alanlarda nokta ile yazılır, örn. card.number. |
| message | string | Alanın neden hatalı olduğu. |
Doğrulama Hatası Örnek JSON
123456789
3D Ödeme Sonrası Yönlendirme
3D doğrulamadan sonra kullanıcı returnUrl adresinize status, transactionId, message, amount, installment, rnd ve signature parametreleriyle yönlendirilir.
Siparişi bu parametrelere göre onaylamadan önce imzayı doğrulayın ve ödemenin durumunu sunucunuzdan sorgulayın. Parametrelerin listesi, imza formülü ve örnek kodlar Sonuç Doğrulama sayfasındadır.
