Ö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ışı
- Sunucunuz sipariş için bir oturum açar ve paymentUrl alır.
- Müşterinizi paymentUrl adresine yönlendirirsiniz.
- Müşteri taksidini seçer, kart bilgilerini girer ve 3D doğrulamayı tamamlar. Kart reddedilirse aynı sayfada başka bir kartla tekrar deneyebilir.
- Ödeme sonuçlanınca müşteri imzalı parametrelerle successUrl'e, vazgeçerse failUrl'e döner. callbackUrl verdiyseniz sonuç ayrıca webhook ile gelir.
- İmzayı doğrular ve siparişi onaylarsınız.
1. Oturum Açma
İstek
| Method | Endpoint | Body |
|---|---|---|
| POST | /external/vpos/v1/checkout-sessions | JSON |
Gövde
| Parametre | Tip | Zorunlu | Açı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
| Parametre | Tip | Zorunlu | Açı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
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| name | string | Evet | Ad. |
| surname | string | Evet | Soyad. |
string | Evet | E-posta adresi. | |
| phoneNumber | string | Evet | Telefon numarası. |
| 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. |
urls
| Parametre | Tip | Zorunlu | Açı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.
Cevap (content)
| Parametre | Tip | Açı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
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
| Parametre | Açıklama |
|---|---|
| checkoutToken | Oturumun token'ı. |
| orderId | Oturumu açarken gönderdiğiniz sipariş numarası. |
| status | successUrl'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. |
| amount | Oturum tutarı, 2 ondalıkla (örn. 1249.90). |
| signature | Tüm parametreleri kapsayan imza. |
Dönüş İmzasını Doğrulama
Karşılaştırmayı sabit zamanlı yapın
TypeScript4. 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
| Method | Endpoint | Body |
|---|---|---|
| GET | /external/vpos/v1/checkout-sessions/{token} | - |
Cevap (content)
| Parametre | Tip | Açı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
