Kartla Ödeme — 2D

2D ödeme, kartı tek istekte çeker; banka tarafında 3D Secure doğrulaması ve yönlendirme yoktur. Alıcı formdan ayrılmaz, sonuç anında döner. Bedeli şudur: 3D doğrulaması olmadığından sorumluluk devri (liability shift) yoktur.

Bu sayfa Checkout Formu yolu içindir. POST /payments/form/2d ucunu Checkout Form SDK'sı alıcının tarayıcısından kendisi çağırır; sizin bu uca istek yazmanız gerekmez. Yazacağınız kod, sunucunuzda intent oluşturmak ve formu sayfanıza mount etmektir → Checkout Formu.

Kart verisini kendi sunucunuzdan gönderiyorsanız bu sayfa sizin için değildir → Kart — 2D.

Nasıl çalışır

3D kararı: form 2D'yi ne zaman çağırmaz

2D bir istektir, garanti değildir. Hangi ucun çalışacağını intent'in 3D kararı belirler. Karar intent oluşturulurken aşağıdaki kaynaklardan çözülür ve intent'e sabitlenir:

Karar 3D ise SDK doğrudan 3D Secure ucunu kullanır. Aynı intent için POST /payments/form/2d çağrısı 409 THREE_D_REQUIRED ile reddedilir; 3D'ye sessiz bir geçiş yapılmaz. SDK bu yanıtı alırsa aynı gövdeyi bir kez POST /payments/form/3d ucuna gönderir ve akış 3D Secure olarak sürer.

Bu alanları intent oluştururken verirsiniz; ayrıntılı anlatım → Checkout Formu.

Sağlayıcı 2D yapamadığında: otomatik 3D Secure

Politikanız 2D dese bile ödemeyi yönlendiren sağlayıcı, anlaşması gereği 2D (non-secure) satış yapamıyor olabilir. Checkout Formu'nda alıcı ekran başında olduğu için platform çekimi reddetmez, 3D Secure'a yükseltir:

• POST /payments/form/2d çağrısı CAPTURED yerine bir 3D yönlendirme yanıtı döner. SDK alıcıyı banka doğrulamasına gönderir; akış oradan itibaren 3D Secure akışı gibi ilerler.
• Ödeme escalationReason: "PROVIDER_2D_UNSUPPORTED" ile işaretlenir. Böylece ödemenin 2D istendiğini ama sağlayıcı yeteneği nedeniyle 3D'ye çıktığını ayırt edebilirsiniz.
• Intent 3D'ye döner. Aynı intent'e yeniden POST /payments/form/2d göndermek 409 THREE_D_REQUIRED ile reddedilir.

Uç başvurusu — POST /payments/form/2d

Bu bölüm başvuru içindir: gövdeyi SDK kurar ve gönderir.

Kimlik doğrulama Authorization başlığıyla değil, iki parçayla yapılır:

• Gövdedeki token: intent yanıtındaki form token'ı.
• Oturum kanıtı: pg_checkout_session çerezi. Çerez taşınamayan ortamlarda (WebView, üçüncü taraf çerez engeli) aynı kanıt gövdede checkoutSessionProof alanıyla gönderilir.

Alanlar

POST /payments/form/3d aynı gövdeyi kullanır.

2D çekimde kart kaydedilmez. Alıcı "kartımı kaydet" kutusunu işaretlese de ödeme etkilenmez; kart kaydı yalnız 3D Secure ile yapılır.

Örnek gövde

SDK'nın gönderdiği gövde (secure-fields modunda):

{
  "token": "<intent yanıtındaki form token'ı>",
  "installment": 1,
  "paymentCards": {
    "secureCardToken": "<tokenize yanıtındaki cardToken>"
  },
  "paymentChannel": "WEB",
  "browserFingerprint": "<parmak izi>"
}

Gövdeyi Checkout Form SDK'sı kurar. SDK, alıcıya gösterdiği toplamı da formun iç alanı olarak ekler; bu sizin göndereceğiniz bir tutar değildir. Çekilen tutarı sunucu, intent'teki amount'tan ve taksitte bağlayıcı teklifteki vade farkından hesaplar.

Yanıt

Başarılı çekim 200 döner:

{
  "status": "success",
  "code": "PAYMENT_CAPTURED",
  "message": "Payment processed",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-9988",
    "amount": 10050,
    "currency": "TRY",
    "status": "CAPTURED"
  },
  "statusCode": 200,
  "requestId": "…"
}

• data.status 2D'de normalde nihaidir: başarıda CAPTURED, retde FAILED.
• data.amount çekilen tutardır: intent'teki amount, taksitli ödemede sistemin eklediği vade farkıyla birlikte.
• callbackUrl verdiyseniz yanıt, alıcıyı sonuç sayfanıza taşıyan imzalı formu da içerir. SDK bu formu kendisi gönderir. Gelen alanlar 3D Secure dönüşüyle aynıdır → Sonuç sayfanıza gelen imzalı POST.
• Sağlayıcı yeteneği nedeniyle 3D'ye yükseltilen çekim, 3D Secure ucunun yanıtını döner (status: "partial", AWAITING_3D) → Kartla Ödeme — 3D Secure › Yanıt.
• Sonucu henüz kesinleşmemiş bir işlem status: "partial" (HTTP 202) ile döner; nihai durumu webhook teslim eder.

Ön provizyon

Formda ön provizyonu ayrıca istemezsiniz: intent'i POST /payments/intents ile oluştururken "preauth": true gönderin. Form çekimi bu karara göre yapar; ödeme başarılı olursa CAPTURED yerine AUTHORIZED olur ve payment.authorized gönderilir. Ön provizyonu desteklemeyen sağlayıcılar adaylardan çıkarılır; uygun sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu PREAUTH_NOT_SUPPORTED'dır.

Capture, void ve 7 günlük süre: Ön Provizyon, Capture & İptal.

Hatalar

Hata yanıtları ortak hata zarfını kullanır; message'a göre değil code'a göre dallanın → Hata Yönetimi.

Webhook'lar

Teslimat ve imza doğrulaması → Webhook'lar.

Sonraki adımlar

• Kartla Ödeme — 3D Secure: 3D kararı ya da sağlayıcı yeteneği 3D gerektirdiğinde akış
• Checkout Formu: intent oluşturma, force3D ve settings.threeD
• Taksit & BIN: gösterilen tutar, çekilen tutardır
• İade: çekim sonrası para iadesi