3D Secure Akışı

Kart Ödemesi varsayılan olarak 3D Secure ile yürür: müşteri bankasının doğrulama sayfasından (SMS / uygulama onayı) geçer, tahsilat sonucu bu adımdan sonra kesinleşir.

Bu rehber; yanıtı nasıl karşılayacağınızı, müşteriyi nasıl yönlendireceğinizi ve kesin sonucu nereden öğreneceğinizi anlatır.

Akışın Özeti

Sunucunuz              Kaptan                  Banka (ACS)           Müşteri tarayıcısı
    │  card/pay            │                          │                        │
    ├─────────────────────►│                          │                        │
    │  AWAITING_3DS +      │                          │                        │
    │  redirectUrl |       │                          │                        │
    │  htmlContent         │                          │                        │
    │◄─────────────────────┤                          │                        │
    │  iframe / popup'ta aç ──────────────────────────────────────────────────►│
    │                      │                          │◄──── SMS doğrulama ────┤
    │                      │◄──── sonuç (callback) ───┤                        │
    │                      ├──── sonuç sayfası + postMessage ─────────────────►│
    │◄──── webhook: PAYMENT_SUCCEEDED / PAYMENT_FAILED                         │
    │  transaction/detail  │                          │                        │
    ├─────────────────────►│  (kesin sonuç)           │                        │
  • 1. Sunucunuz card/pay çağırır; yanıt status: "AWAITING_3DS" ile döner.
  • 2. Yanıttaki redirectUrl ya da htmlContent müşteriye gösterilir.
  • 3. Müşteri bankada doğrular; banka sonucu Kaptan'a iletir.
  • 4. Kesin sonuç size webhook ile bildirilir; transaction/detail ile de sorgulanabilir.

1. İstek

3DS için ek alan göndermeniz gerekmez: threeDsEnabled gönderilmezse veya true ise işlem 3D Secure ile başlar. 3D'siz ödeme yalnızca threeDsEnabled: false açıkça gönderildiğinde ve POS yapılandırmanız izin verdiğinde yapılır.

threeDsEnabledSonuç
gönderilmez / true3D Secure akışı başlar.
false3D'siz ödeme. POS 3D'siz işleme kapalıysa pos.non.secure.not.allowed, 3D'siz tutar limiti aşılırsa transaction.amount.exceeds.non.secure.limit döner.
Dönüş adresi (returnUrl) yok

İstekte returnUrl / callbackUrl alanı bulunmaz. Banka sonucu Kaptan'a döner ve müşteri sizin sitenize yönlendirilmez. Bu yüzden 3DS sayfasını kendi sayfanızın içinde (iframe veya popup) açmanız önerilir — bkz. Müşteriyi yönlendirme.

2. AWAITING_3DS Yanıtı

card/pay yanıtı
{
  "code": 200,
  "message": "İşlem Başarılı",
  "content": {
    "orderNumber": "ORD-1001",
    "transactionRef": "eb334ec5-…",
    "status": "AWAITING_3DS",
    "amount": 100.00,
    "currency": "TRY",
    "installment": 1,
    "requires3ds": true,
    "redirectUrl": "https://…/3ds/…",
    "htmlContent": null,
    "capturedDate": null
  },
  "correlationId": "3f6d1c2e-…"
}
AlanAnlam
requires3dstrue ise müşteri doğrulamaya gönderilmelidir.
redirectUrlBanka doğrulama sayfasının adresi. Doluysa bunu açın.
htmlContentBazı sağlayıcılar adres yerine kendiliğinden gönderilen bir HTML formu döner. redirectUrl boşsa bunu çizin.
transactionRefBu aşamada da doludur — saklayın; sonucu bununla sorgularsınız.

3. Müşteriyi Yönlendirme

Doğrulama bitince Kaptan kısa bir sonuç sayfası gösterir ve üst pencereye (iframe'in sahibi ya da popup'ı açan pencere) şu mesajı gönderir:

{ "source": "pos-3ds", "status": "SUCCESS" | "FAILED", "message": "…" }
Tarayıcı tarafı örnek
// content: card/pay yanıtının content alanı (sunucunuzdan tarayıcıya aktarılır)
const frame = document.getElementById('threeds-frame');

if (content.redirectUrl) {
  frame.src = content.redirectUrl;          // banka sayfası iframe içinde
} else if (content.htmlContent) {
  frame.srcdoc = content.htmlContent;       // sağlayıcının otomatik gönderilen formu
}

// Kaptan sonuç sayfası üst pencereye haber verir. Bu mesaj İMZASIZDIR:
// yalnızca arayüzü ilerletmek için kullanın, sonucu sunucunuzdan doğrulayın.
window.addEventListener('message', async (event) => {
  if (event.data?.source !== 'pos-3ds') return;
  frame.hidden = true;
  const res = await fetch('/checkout/status?orderNumber=ORD-1001'); // sizin ucunuz
  const {status} = await res.json();        // sunucunuz transaction/detail'e sorar
  showResult(status);                       // COMPLETED | PRE_AUTHORIZED | FAILED | PENDING
});
postMessage sonuca kanıt değildir

Mesaj imzasızdır ve herhangi bir sayfa aynı biçimde mesaj üretebilir. Siparişi yalnızca sunucu tarafında doğruladığınız sonuca göre onaylayın: imzalı webhook ya da transaction/detail.

4. Kesin Sonucu Öğrenme

Webhook (önerilen): İşletme panelinde Entegrasyon → Webhook tanımlıysa 3DS tamamlanınca olay gönderilir. İmzayı X-Kaptan-Signature-256 başlığıyla doğrulayın — bkz. Webhook İmza Doğrulayıcı.

OlayNe zaman
PAYMENT_SUCCEEDEDTahsilat gerçekleşti (COMPLETED).
PAYMENT_AUTHORIZEDÖn provizyon alındı (PRE_AUTHORIZED), kapatma bekliyor.
PAYMENT_FAILEDDoğrulama veya banka onayı başarısız (FAILED).

Sorgulama: Webhook kullanmıyorsanız ya da postMessage aldıktan sonra, sunucunuzdan transaction/detail çağırın.

transaction/detail `status`AnlamYapılacak
PENDINGDoğrulama sürüyor ya da sonuç henüz netleşmedi.Siparişi bekletin; kısa aralıklarla yeniden sorgulayın.
COMPLETEDTahsilat gerçekleşti.Siparişi onaylayın.
PRE_AUTHORIZEDTutar bloke edildi.transaction/capture ile kapatın.
FAILEDTahsilat yok.Müşteriye yeniden deneme sunun.
AWAITING_3DS ve PENDING aynı durumdur

card/pay yanıtı AWAITING_3DS der; aynı işlem transaction/detail ve transaction/search sonuçlarında doğrulama bitene dek PENDING görünür.

Müşteri doğrulamayı yarıda bırakırsa veya bankadan net sonuç alınamazsa işlem PENDING kalır; Kaptan bu işlemleri arka planda periyodik olarak sağlayıcıya sorar ve sonuç netleşince durumu günceller, webhook'u gönderir.

Kontrol Listesi

  • transactionRef ve orderNumber değerlerini card/pay yanıtından hemen saklayın.
  • redirectUrl boşsa htmlContent çizin; ikisi de boşsa ve status AWAITING_3DS değilse 3DS yoktur — sonucu doğrudan status alanından okuyun.
  • Siparişi postMessage ile değil, webhook veya transaction/detail ile onaylayın.
  • PENDING işlemi başarısız saymayın; aynı sipariş için yeni ödeme başlatmadan önce durumu sorgulayın.
  • Sandbox testlerinde test kartlarını kullanın.