TahsilatE Logo
Geliştirici Ortamı

3D Ödeme

3D Ödeme Servisi İstek Modeli

MethodEndpointBody
POST/external/vpos/v1/paymentsJSON
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ışı

  1. Ü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.
  2. TahsilatE, isteği doğrular ve ödemeyi banka tarafında başlatır.
  3. Ö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.
  4. 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

ParametreTipZorunluAçı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

ParametreTipZorunluAçı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

ParametreTipZorunluAçıklama
name
string
Evet Ad.
surname
string
Evet Soyad.
email
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

ParametreTipZorunluAçı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.

ParametreTipAçı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ı

HTTPTürAçı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.

ParametreTipAçı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.