TahsilatE Logo
Geliştirici Ortamı

Ödeme Sayfası

Ödeme sayfası, müşterinizin kart bilgilerini TahsilatE'nin güvenli sayfasında girdiği hazır bir ödeme ekranıdır. Kart bilgisi sitenize hiç gelmez, bu yüzden PCI DSS yükümlülüğünüz oluşmaz. Taksit seçenekleri, 3D doğrulama ve reddedilen kartla tekrar deneme bu sayfada yönetilir. E-ticaret siteleri ve hazır altyapılar (WooCommerce vb.) için önerilen entegrasyon budur.

İşlem Akışı

  1. Sunucunuz sipariş için bir oturum açar ve paymentUrl alır.
  2. Müşterinizi paymentUrl adresine yönlendirirsiniz.
  3. Müşteri taksidini seçer, kart bilgilerini girer ve 3D doğrulamayı tamamlar. Kart reddedilirse aynı sayfada başka bir kartla tekrar deneyebilir.
  4. Ödeme sonuçlanınca müşteri imzalı parametrelerle successUrl'e, vazgeçerse failUrl'e döner. callbackUrl verdiyseniz sonuç ayrıca webhook ile gelir.
  5. İmzayı doğrular ve siparişi onaylarsınız.
Test ortamında oluşturulan oturumlar ödeme sayfasının test kopyasını açar; test kartları ve senaryolar Test Ortamı sayfasındadır.

1. Oturum Açma

İstek

MethodEndpointBody
POST/external/vpos/v1/checkout-sessionsJSON

Gövde

ParametreTipZorunluAçıklama
order
object
Evet Sipariş bilgileri.
customer
object
Evet Müşteri bilgileri.
items
array
Evet Ödeme sayfasında fiş olarak gösterilen sepet. Gönderilirse productPrice × quantity toplamı order.amount'a eşit olmalıdır.
urls
object
Evet Dönüş ve bildirim adresleri.

order

ParametreTipZorunluAçıklama
orderId
string
Evet Sizdeki sipariş numarası, en fazla 64 karakter.
amount
number
Evet Sipariş tutarı (TL), en fazla 2 ondalık. Komisyonu müşterinin ödediği taksitlerde vade farkı bunun üzerine eklenir; ödeme sayfası müşteriye ödemeden önce toplamı gösterir. Dönüşteki ve webhook'taki amount her zaman bu sipariş tutarıdır.
currency
string
Evet Yalnızca TRY desteklenir. Varsayılan TRY.
description
string
Evet Ödeme açıklaması, en fazla 255 karakter.
maxInstallment
number
Evet Müşteriye sunulacak en yüksek taksit, 1-12. Varsayılan 1 (tek çekim).
expiresInMinutes
number
Evet Oturumun geçerlilik süresi, 5-1440 dakika. Varsayılan 60.

customer

ParametreTipZorunluAçıklama
name
string
Evet Ad.
surname
string
Evet Soyad.
email
string
Evet E-posta adresi.
phoneNumber
string
Evet Telefon numarası.
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.

urls

ParametreTipZorunluAçıklama
successUrl
string
Evet Ödeme başarılı veya bankanın onayı bekleniyorsa müşterinin döneceği adres.
failUrl
string
Evet Müşteri ödemeden vazgeçerse veya oturum kapanırsa döneceği adres.
callbackUrl
string
Evet Ödeme sonuçlanınca imzalı webhook gönderilecek adres. Müşteri tarayıcıyı kapatsa bile sonucu buradan alırsınız.
  • Canlı ortamda adresler https olmalı; IP adresi veya localhost kabul edilmez.
  • Panelde API anahtarınız için alan adı tanımladıysanız adresler bu alan adlarından (veya alt alan adlarından) birinde olmalıdır.

Örnek İstek

Ürünlerin toplamı (649.90 + 2 × 150 + 300) order.amount'a (1249.90) eşittir.

123456789101112131415161718192021222324252627282930313233343536373839
Kart denemelerine karşı bir oturumda en fazla 5 sonuçlanmamış ödeme denemesi yapılabilir (reddedilen veya 3D'de yarım bırakılan). Sınır dolunca oturum ödeme kabul etmez, müşteri failUrl'e status=FAILED ile döner; siparişi yeniden ödemeye açmak için yeni oturum açın. Ayrıca aynı IP adresinden saatte en fazla 20 ödeme denemesi kabul edilir.
Aynı orderId için yeni bir oturum açarsanız o siparişin açık oturumları iptal edilir. Böylece müşteri iki sekmeden aynı siparişi iki kez ödeyemez.

Cevap (content)

ParametreTipAçıklama
token
string
Oturumun kimliği. Sonuç doğrulamada ve durum sorgulamada kullanılır.
paymentUrl
string
Müşteriyi yönlendireceğiniz ödeme sayfası adresi.
expiresAt
string
Oturumun kapanacağı an (ISO 8601).

Örnek Cevap

12345678

2. Müşteriyi Yönlendirme

Müşterinizi paymentUrl adresine tam sayfa yönlendirin. Ödeme sayfası iframe içinde açılmaz.

3. Dönüşü Doğrulama

Müşteri successUrl veya failUrl adresinize GET ile, aşağıdaki parametrelerle döner. Adresinizde query string varsa parametreler onun sonuna eklenir.

Dönüş Parametreleri

ParametreAçıklama
checkoutTokenOturumun token'ı.
orderIdOturumu açarken gönderdiğiniz sipariş numarası.
statussuccessUrl'de SUCCESSFUL veya PENDING; failUrl'de FAILED (oturum süresi doldu veya deneme sınırına ulaşıldı) ya da CANCELLED (müşteri vazgeçti).
transactionIdÖdemenin işlem ID'si. Müşteri hiç ödeme denemeden vazgeçtiyse boştur.
amountOturum tutarı, 2 ondalıkla (örn. 1249.90).
signatureTüm parametreleri kapsayan imza.
signature = HMAC-SHA256(checkoutToken|orderId|status|transactionId|amount, secretKey)

Dönüş İmzasını Doğrulama

Karşılaştırmayı sabit zamanlı yapın

TypeScript logoTypeScript
Siparişi yalnızca imza doğruysa ve status SUCCESSFUL ise onaylayın. PENDING'de banka sonucu sonradan bildirir; siparişi beklemede tutup webhook'u veya durum sorgusunu bekleyin.

4. Webhook

callbackUrl verdiyseniz ödeme sonuçlanınca bu adrese imzalı bir payment.completed bildirimi gönderilir. Gövdede orderId ve checkoutToken alanları da bulunur. Paneldeki webhook adreslerinize de aynı bildirim gider. Doğrulama ve tekrar deneme kuralları Webhook sayfasındadır.

5. Durum Sorgulama

İstek

MethodEndpointBody
GET/external/vpos/v1/checkout-sessions/{token}-

Cevap (content)

ParametreTipAçıklama
token
string
Oturumun token'ı.
orderId
string
Sipariş numarası.
status
string
OPEN (ödeme bekleniyor), COMPLETED (ödendi), CANCELLED (vazgeçildi veya aynı sipariş için yeni oturum açıldı), EXPIRED (süresi doldu), FAILED (deneme sınırına ulaşıldı).
amount
number
Oturum tutarı.
currency
string
TRY.
expiresAt
string
Oturumun kapanacağı an.
payment
object | null
Siparişi ödeyen başarılı ödeme: transactionId, status, amount, installment, maskedCardNumber, date. Ödenmediyse null.
attempts
array
Tüm ödeme denemeleri (en yenisi önce): transactionId, status, installment, resultMessage, date.

Örnek Cevap

12345678910111213141516171819202122232425262728