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ıtstatus: "AWAITING_3DS"ile döner. - 2. Yanıttaki
redirectUrlya dahtmlContentmüş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.
| threeDsEnabled | Sonuç |
|---|---|
gönderilmez / true | 3D Secure akışı başlar. |
false | 3D'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. |
İ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ı
{
"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-…"
}| Alan | Anlam |
|---|---|
requires3ds | true ise müşteri doğrulamaya gönderilmelidir. |
redirectUrl | Banka doğrulama sayfasının adresi. Doluysa bunu açın. |
htmlContent | Bazı sağlayıcılar adres yerine kendiliğinden gönderilen bir HTML formu döner. redirectUrl boşsa bunu çizin. |
transactionRef | Bu 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": "…" }// 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
});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ı.
| Olay | Ne zaman |
|---|---|
PAYMENT_SUCCEEDED | Tahsilat gerçekleşti (COMPLETED). |
PAYMENT_AUTHORIZED | Ön provizyon alındı (PRE_AUTHORIZED), kapatma bekliyor. |
PAYMENT_FAILED | Doğ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` | Anlam | Yapılacak |
|---|---|---|
PENDING | Doğrulama sürüyor ya da sonuç henüz netleşmedi. | Siparişi bekletin; kısa aralıklarla yeniden sorgulayın. |
COMPLETED | Tahsilat gerçekleşti. | Siparişi onaylayın. |
PRE_AUTHORIZED | Tutar bloke edildi. | transaction/capture ile kapatın. |
FAILED | Tahsilat yok. | Müşteriye yeniden deneme sunun. |
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
transactionRefveorderNumberdeğerlerinicard/payyanıtından hemen saklayın.redirectUrlboşsahtmlContentçizin; ikisi de boşsa vestatusAWAITING_3DSdeğilse 3DS yoktur — sonucu doğrudanstatusalanından okuyun.- Siparişi postMessage ile değil, webhook veya
transaction/detailile onaylayın. PENDINGiş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.