3DS Simulation
Secure mode, requires_action, nextAction, challenge, resume ve callback akışlarının sandbox testi.
Bu sayfa neyi anlatır? HSRC Pay sandbox ortamında 3DS, secure mode ve requires_action akışlarının nasıl simüle edildiğini açıklar.
Ödeme her zaman direkt success dönmez. Bazı ödemeler kullanıcı aksiyonu, redirect, HTML render, challenge veya resume/callback flow gerektirebilir. HSRC Pay bu durumu normalized requires_action modeliyle temsil eder.
Important: 3DS simulation gerçek authentication garanti etmez; integration davranışını test eder. Sandbox 3DS gerçek card network authentication veya gerçek issuer ACS bağlantısı değildir.
3DS Simulation Nedir?
3DS simulation, merchant entegrasyonunun multi-step ödeme akışlarına hazır olup olmadığını test eden sandbox-only challenge davranışıdır.
Bu akışta sandbox provider adapter direct authorization yerine requires_action dönebilir. Merchant veya checkout frontend bu next action'ı kullanıcıya gösterir, challenge tamamlanınca resume/callback flow ile ödeme sonucu finalize edilir.
Secure Mode Ne Zaman Kullanılır?
Secure mode şu durumlarda test edilmelidir:
- Merchant API request içinde secure mode istiyorsa
- Provider capability 3DS destekliyorsa
- Payment
secure_mode: trueile confirm ediliyorsa ve sandbox provider bu akışı destekliyorsa - Routing veya ürün konfigürasyonu secure provider gerektiriyorsa
Confirm sonucu: requires_action
Adapter latestResult.kind === "requires_action" olduğunda Payment REQUIRES_ACTION olur. Merchant yönlendirme için confirmResult.paymentNextAction kullanır:
{
"payment": { "id": "pay_sandbox_123", "status": "REQUIRES_ACTION" },
"confirmResult": {
"ok": true,
"latestResult": { "kind": "requires_action" },
"paymentNextAction": {
"action": "redirect_user_to_url",
"url": "https://sandbox.hsrcpay.com/..."
}
}
}Provider adapter içindeki nextAction (ör. render_html) checkout veya dashboard tarafında işlenebilir; public API yönlendirmesi için paymentNextAction esas alınır.
Next Action Tipleri
| Tip | Açıklama |
|---|---|
render_html | Checkout veya merchant frontend HTML challenge içeriğini render eder |
redirect | Kullanıcı sandbox challenge URL'ine yönlendirilir |
collect_input | Conceptual model: kullanıcıdan ek test input'u alınabilir |
sdk_action | Conceptual model: SDK tarafından yönetilen aksiyonlar için kullanılabilir |
Mevcut public anlatımda render_html ve redirect benzeri modeller esas alınmalıdır; diğer tipler future-compatible conceptual model olarak düşünülmelidir.
HTML Render / Redirect Flow
Hosted checkout kullanılıyorsa HSRC Pay challenge rendering davranışını checkout deneyimi içinde yönetebilir. API-only entegrasyonda merchant kendi frontendinde nextAction sonucunu handle etmelidir.
Merchant frontend:
- HTML render ederken raw payload logging yapmamalıdır.
- Redirect URL'i sadece sandbox context içinde kullanmalıdır.
- Challenge tamamlandıktan sonra resume/callback sonucunu beklemelidir.
Resume / callback akışı
Challenge tamamlanınca provider, HSRC Pay gateway'deki GET|POST /v1/gateway/three-d-secure-callback-urls/:chargeId adresine döner. Bu akış resumeThreeDSecure use case'ini çalıştırır; merchant'ın ayrıca resumePayment(paymentId) çağırması gerekmez.
const { data } = await api.post("/v1/payments/pay_sandbox_123/confirm", {
payment_method: { id: "pm_sandbox" },
payer_identity: { ip_address: clientIp, user_agent: ua },
});
if (data.confirmResult.paymentNextAction?.url) {
redirectUser(data.confirmResult.paymentNextAction.url);
}
// Callback sonrası: GET payment veya webhook ile nihai statusBaşarılı 3DS Sonrası Authorization
Challenge başarıyla tamamlandığında Payment SUCCEEDED veya AUTHORIZED olur; Charge CAPTURED veya AUTHORIZED. Webhook: payment.succeeded, payment.authorized, charge.captured vb.
Başarısız veya İptal Edilmiş Challenge
Challenge başarısızsa adapter error + declined dönebilir; Charge DECLINED, Payment REQUIRES_PAYMENT_METHOD kalır. Merchant kontrollü yeniden confirm veya farklı yöntem sunmalıdır.
Webhook ve Event Beklentileri
Merchant webhook handler idempotent olmalıdır. Aynı payment için birden fazla event gelebileceğini düşünmelidir.
Beklenen event family:
payment.requires_actionpayment.succeededpayment.authorizedcharge.declinedcheckout_session.completed(hosted checkout)
Frontend sonucu tek başına nihai muhasebe kaydı olarak kullanmayın; server-side status ve webhook/event akışıyla doğrulayın.
Testing Checklist
requires_actionresponse'unu handle edin.- Hosted checkout ve API-only entegrasyon farkını test edin.
- Gateway 3DS callback ve callback sonrası payment GET/webhook doğrulamasını test edin.
- Başarılı ve başarısız challenge sonucunu ayrı test edin.
- Webhook idempotency davranışını kontrol edin.
- Raw HTML, card data ve transaction metadata logging'i maskeleyin.
Sınırlamalar ve Güvenlik Notları
- 3DS simulation gerçek card network authentication değildir.
- Gerçek issuer ACS bağlantısı kurulmaz.
- CAVV/ECI/XID/MD benzeri alanlar sandbox'ta test metadata'sı olarak ele alınmalıdır.
- Raw challenge payload, HTML ve transaction metadata loglarda dikkatli maskelenmelidir.
- Production authentication sonucu garanti edilmez; yalnızca integration flow test edilir.