Kartla Ödeme — 3D Secure

3D Secure, kart çekilmeden önce alıcının işlemi kendi bankasıyla onaylamasını sağlar (SMS kodu, banka uygulaması onayı, biyometri). Sorumluluk devri (liability shift) istediğinizde, 3D politikanız gerektirdiğinde ya da banka doğrulama istediğinde bu akış çalışır. Platform işlemi uygun sağlayıcıya yönlendirir ve banka gidiş-dönüşünü sizin yerinize yürütür.

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

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

Nasıl çalışır

Form 3D Secure'u ne zaman kullanır

Hangi ucun çalışacağını intent'in 3D kararı belirler. Karar intent oluşturulurken force3D, settings.threeD ve panel 3D politikasından çözülür ve intent'e sabitlenir → Kartla Ödeme — 2D › 3D kararı.

Form şu durumlarda 3D Secure ile çeker:

• Intent'in 3D kararı 3D'dir. SDK doğrudan POST /payments/form/3d çağırır.
• Karar 2D'dir ama ödemeyi yönlendiren sağlayıcı 2D satış yapamaz. Platform çekimi 3D Secure'a yükseltir ve ödemeyi escalationReason: "PROVIDER_2D_UNSUPPORTED" ile işaretler → Kartla Ödeme — 2D › Sağlayıcı 2D yapamadığında.

İki durumda da akış bu sayfada anlatıldığı gibi ilerler.

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

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

Kimlik doğrulama Authorization başlığıyla değil, gövdedeki form token'ı ve oturum kanıtıyla (pg_checkout_session çerezi ya da checkoutSessionProof) yapılır. Gövde POST /payments/form/2d ile aynıdır → alan tablosu.

Örnek gövde

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

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

installmentQuoteToken taksitli ödemede gönderilir; çekilen tutar, alıcıya gösterilen teklife bağlanır.

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

Banka gidiş-dönüşü tamamlanana kadar ödeme AWAITING_3D durumunda bekler. Yanıt status: "partial" (HTTP 202) ile döner:

{
  "status": "partial",
  "code": "AWAITING_3D",
  "message": "Payment processed",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-9988",
    "amount": 10350,
    "currency": "TRY",
    "status": "AWAITING_3D",
    "threeDRedirectUrl": "/api/v1/payments/threed/<tek kullanımlık token>"
  },
  "statusCode": 202,
  "requestId": "…"
}

data.amount çekilen tutardır: intent'teki amount ile sistemin taksit teklifinden eklediği vade farkının toplamı. Örnekte intent amount'u 10050, 3 taksitte çekilen tutar 10350'dir.

SDK yönlendirmeyi kendisi yapar. AWAITING_3D'de terk edilen ödemeyi arka plandaki temizlik işi devralır: sağlayıcıya gerçek sonucu sorar ve ödemeyi gerçek nihai durumuna bağlar (çekim yoksa FAILED, çekim gerçekleşmişse CAPTURED).

Sonuç sayfanıza gelen imzalı POST

Banka gidiş-dönüşünden sonra alıcının tarayıcısı, intent'te verdiğiniz callbackUrl'e bir HTML form POST'uyla (application/x-www-form-urlencoded) gönderilir. Aynı POST, başarılı 2D çekimden sonra da gelir. Gövde şu alanları taşır:

Kanonik dizgi (canonical), _signature dışındaki bütün alanların (_timestamp dahil) anahtara göre sıralanıp key=value biçiminde yazılması ve satır sonuyla (\n) birleştirilmesiyle oluşur.

Bu POST'u alıcının arayüzünü yönetmek için kullanın (sonuç sayfası göstermek, oturumu sürdürmek). Tarayıcı callbackUrl'inize hiç ulaşamayabilir (kapatılan sekme, bağlantı kaybı); webhook ise her durumda gönderilir.

Durum geçişleri

Kart saklama

Formda kart, alıcı "kartımı kaydet" kutusunu işaretlediğinde ve çekim 3D Secure ile başarıyla tamamlandığında saklanır. Bunun için:

• Kart saklama, panelinizdeki form ayarlarında açık olmalıdır.
• Intent'i customerId (ya da cardUserKey) ile oluşturmalısınız; kart bu anahtarın altına kaydedilir.

Ödeme yanıtı alıcının tarayıcısına gittiği için kalıcı kart referansı burada dönmez. Ödeme tamamlandıktan sonra kartları sunucunuzdan GET /payments/cards ile okuyun → Kart Saklama.

Ön provizyon

Formda ön provizyonu ayrıca istemezsiniz: intent'i POST /payments/intents ile oluştururken "preauth": true gönderin. Alıcı banka doğrulamasını tamamladığında para çekilmez; ödeme CAPTURED yerine AUTHORIZED olur ve payment.authorized gönderilir.

• Sağlayıcının ön provizyonu 3D Secure ile de desteklemesi gerekir. Uygun sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu PREAUTH_3DS_NOT_SUPPORTED'dır.
• 3D Secure ile ön provizyonu destekleyen hiçbir sağlayıcı yoksa istek 422 payment.preauth.three_ds_unsupported ile reddedilir. Talimat hiçbir koşulda anında çekime dönüştürülmez.

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 — 2D: banka doğrulaması olmadan çekim ve 3D kararının kaynakları
• Checkout Formu: intent oluşturma, callbackUrl, force3D ve settings.threeD
• Kart Saklama: kayıtlı kartları okuma ve formda gösterme
• Taksit & BIN: gösterilen tutar, çekilen tutardır
• İade: çekim sonrası para iadesi