Ödeme Akışları

Kaptan Partner API ile kurabileceğiniz gelişmiş ödeme akışlarının özeti. Her akış, ilgili uçların dokümanına bağlanır — burada hangi akışı ne zaman seçeceğinize karar verirsiniz.

1. Tek Çekim (Direkt Satış)

En basit akış: Kart Ödemesi tek çağrıdır. Yanıt zarfı isteğin işlendiğini söyler; tahsilatın gerçekleştiğini status: "COMPLETED" gösterir.

Müşteriye nihai tutarı önceden göstermek için Komisyon Önizleme kullanın — aynı installment ile sorgulayın.

commission/quote (opsiyonel)  →  card/pay  →  status: COMPLETED
                                          ↘ status: FAILED (tahsilat yok)

2. 3D Secure ile Ödeme

Kart Ödemesi isteğinde threeDsEnabled: true gönderin; müşteri banka doğrulamasından geçer.

Yanıt status: "AWAITING_3DS" döner ve redirectUrl (ya da htmlContent) dolar — müşteriyi oraya yönlendirin. Yanıttaki transactionRef bu aşamada da doludur; saklayın.

Sonuç, müşteri bankadan döndükten sonra kesinleşir — saklayıp transaction/detail ile sorgulayacağınız değer transactionReftir.

Bazı POS yapılandırmaları 3D'siz işleme kapalıdır: pos.non.secure.not.allowed alırsanız threeDsEnabled: true göndermek zorundasınız.

3. Ön Provizyon + Kapatma

Gerçekleşecek tutarın peşinen bilinmediği işler (otel, araç kiralama, kargo) için: önce tutar bloke edilir, hizmet tamamlanınca gerçekleşen tutar çekilir.

Akış: card/pay preAuth: true → transaction/capture (tam veya kısmi) → COMPLETED.
Vazgeçerseniz transaction/cancel blokeyi çözer.
Kapatılmayan provizyon banka süresi dolunca kendiliğinden düşer.

card/pay (preAuth: true)  →  PRE_AUTHORIZED  →  transaction/capture  →  COMPLETED
                                             ↘  transaction/cancel   →  bloke çözülür

4. Kart Saklama & Kayıtlı Karttan Ödeme

Kart iki yoldan saklanır: ödeme sırasında (card/pay + saveCard: true) veya ödemesiz (card/save).

Sonraki ödemelerde card/list ile kartı bulun, card/pay çağrısını savedCardId ile yapın — paymentMethod boşsa sunucu SAVED_CARD olarak türetir.

PAN hiçbir zaman Kaptan tarafında durmaz; kart sağlayıcıda tokenize edilir ve sağlayıcı seçimi sunucuda yapılır. Elinizde tutmanız gereken tek değer kartın id'sidir. Detay: Kayıtlı Kart.

card/pay + saveCard:true   →  ödeme sırasında saklanır
card/save                  →  ödeme almadan saklanır
                           ↓
        card/list  →  card/pay (savedCardId ile)

5. Taksitli Ödeme

Müşterinin kartına uygun taksitleri göstermek için Taksit Listeleme kullanın.
Taksit komisyon oranını değiştirir: nihai tutarı Komisyon Önizleme ile aynı installment üzerinden gösterin.
Ödemeyi card/pay installment alanıyla çekin.

Taksit senaryolarını denemek için Komisyon / Taksit Hesaplayıcı aracını kullanabilirsiniz.

installment/list  →  taksit seçenekleri
commission/quote (installment: N)  →  customerPays
card/pay (installment: N)  →  tahsilat

6. Ödeme Linki ile Tahsilat

Kart bilgisine hiç dokunmadan tahsilat: link oluşturun, yanıttaki paymentUrl adresini alıcıya gönderin; ödeme Kaptan ödeme sayfasında tamamlanır.

Taksit seçenekleri enableInstallment + availableInstallments ile sınırlandırılabilir.
allowPartialPayment: true ile link, toplam tutara ulaşana dek birden fazla ödemeyle tahsil edilebilir.
Sepet gönderecekseniz kalemler katalog varyantı ya da serbest (name + unitPrice) olabilir.
Durumu detail / search ile izleyin, gerekirse iptal edin.

Link ödendiğinde transactionRef dolar; o andan sonra iptal ve iade normal işlem uçlarından yürür.

payment/link/create  →  paymentUrl  →  müşteri öder
                                        ↓
            link/detail.transactionRef  →  pos/transaction/{detail,cancel,refund}

7. Tekrarlayan Tahsilat (Abonelik)

Sabit aralıklarla otomatik çekim için plan kurun; tahsilatlar Kaptan tarafından denenir. Sonuçları plana verdiğiniz orderNumber ile transaction/search üzerinden izleyin.

Kart bazlı planda önce kartı saklayın, sonra plan isteğine savedCardId verin — sağlayıcı token'ı gönderilmez.

Detaylı yaşam döngüsü: Tekrarlayan Tahsilat.

Hangi Akış?

Senaryo	Akış
Tutar belli, anında tahsilat	Tek çekim
Tutar sonradan kesinleşecek	Provizyon + kapatma
Kart bilgisini kendim almak istemiyorum	Ödeme linki
Aynı müşteriden düzenli tahsilat	Tekrarlayan plan
Tek tık ödeme deneyimi	Kayıtlı kart

Not

card/pay, transaction/capture, payment/link/create ve recurring/create Idempotency-Key header'ı gerektirir — bkz. Idempotency.