3-D Secure

3-D Secure (3DS), kart sahibinin kartı veren bankaya karşı kimliğini, genellikle bir SMS kodu veya bankacılık uygulamasıyla doğruladığı adımdır. Platform bunu sizin yerinize çalıştırır; entegrasyonunuz müşteriyi yönlendirir ve sonuca tepki verir.

3DS ne zaman uygulanır

Ödeme başına payment_method_options.card.three_d_secure ile denetleyin:

Değer	Davranış
`automatic` (varsayılan)	Platform karar verir. Güvenli olmayan (non-secure) limitleriniz dahilinde olan ve fraud taramasını geçen ödemeler 3DS'yi atlayabilir; diğer her ödeme 3DS kullanır.
`required`	Her zaman doğrulama yapılır.
`none`	Hiçbir zaman doğrulama yapılmaz. Yalnızca hesabınıza güvenli olmayan ödeme izni verilmişse ve tutar limitleriniz dahildeyse mümkündür; aksi halde çağrı `400 non_secure_not_allowed` ile başarısız olur.

Ödeme, istenen ve uygulanan değeri three_d_secure.requested ve three_d_secure.effective alanlarında bildirir.

Önce dönüş adresini kaydedin

Doğrulamadan sonra müşteri return_url adresinize geri yönlendirilir. Bu adres, kayıtlı bir web sitesinde bulunmalı veya üye işyeri panelinde Ayarlar → Web siteleri ve geri dönüş adresleri altında kaydettiğiniz bir geri dönüş (callback) adresiyle eşleşmelidir (kimlik doğrulama kılavuzuna bakın). Aksi halde ödeme 400 return_url_not_allowed ve param: return_url ile reddedilir. 3DS gerekebiliyorsa return_url değerini her zaman POST /v1/payment_intents veya POST /v1/payment_intents/{id}/confirm çağrısında gönderin.

Akış

Ödemeyi onaylayın (confirm: true ile oluşturun veya /confirm çağırın).
Doğrulama gerekiyorsa yanıtta status: requires_action ve bir next_action bulunur.
Müşteriyi, next_action içinde belirtilen yere yönlendirin.
Müşteri bankada kimliğini doğrular. Banka sonucu platforma bildirir ve platform ödemeyi tamamlar.
Platform, sorgu dizesine payment_intent=pi_… ekleyerek müşteriyi return_url adresinize yönlendirir.
Dönüş sayfanızda ödemeyi sunucunuzda okuyun ve sonucu gösterin. Yönlendirmenin kendisine güvenmeyin.

Adım 2 ve 3: next_action

next_action.type şunlardan biridir:

redirect_to_url: müşterinin tarayıcısını next_action.redirect_to_url.url adresine yönlendirin (bir HTTP yönlendirmesi veya bir bağlantı).
html_form: tarayıcıya döndürdüğünüz sayfada next_action.html_form.html çıktısını verin; müşteriyi bankanın sayfasına gönderir. Olduğu gibi işleyin.

{
  "id": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5B",
  "object": "payment_intent",
  "amount": 12500,
  "currency": "try",
  "status": "requires_action",
  "capture_method": "automatic",
  "three_d_secure": {"requested": "automatic", "effective": "required"},
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://pay.example.com/3ds/start/att_01J9ZQ4V8K2M3N5P7R9T1W3Y5C",
      "return_url": "https://shop.example.com/pay/return"
    }
  },
  "return_url": "https://shop.example.com/pay/return",
  "created": 1790000000,
  "livemode": false
}

Adım 6: dönüş sayfanız

curl https://pay.example.com/v1/payment_intents/pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5B \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

`status`	Anlamı
`succeeded`	Ödendi (otomatik capture). Siparişi yerine getirin.
`requires_capture`	Provizyon alındı, `POST /v1/payment_intents/{id}/capture` çağrınızı bekliyor (`capture_method: manual`).
`processing`	Banka henüz yanıt vermedi. Webhook'u bekleyin; yeniden tahsilat yapmayın.
`requires_payment_method`	Doğrulama veya ödeme başarısız oldu. `last_payment_error` nedeni içerir (örneğin `authentication_failed`); müşterinin başka bir kart denemesine izin verin.
`requires_action`	Müşteri hâlâ bankada.

Müşteri hiç geri dönmezse

Müşteriler sekmeleri kapatır. Dönüş yönlendirmesine bağımlı kalmayın: payment_intent.succeeded, payment_intent.payment_failed ve payment_intent.requires_action webhook'larına abone olun (webhook kılavuzuna bakın) ve mutabakatı bunlar üzerinden yapın. Bir siparişi açık tutuyorsanız, stoku serbest bırakmadan önce GET /v1/payment_intents/{id} ile kontrol edin.

Test etme

Sandbox'ta test kartları; başarılı doğrulamayı, başarısız doğrulamayı, 3DS gerektiren bir kartı ve terk edilmiş bir doğrulamayı kapsar. Sandbox kılavuzuna bakın.