Kart Handoff

POST /v1/payments kartsız çalışır: yalnızca bir ödeme isteği oluşturur ve size bir paymentRef (tek-kullanımlık ödeme referansı) ile bir handoffUrl döner. Kartı banka 3D Secure devrine sokmak için, alıcının tarayıcısını/WebView’ini kartla birlikte bu handoffUrl’e yönlendirirsiniz.

handoffUrl, Paytalya’nın ayrı handoff sayfasıdır (pay.* origin): kartı sizin yerinize toplamaz; topladığınız kartı + paymentRef’i alır, banka 3D Secure formunu kendisi üretir ve banka 3D devrini yürütür. Kart, bu sayfaya alıcının tarayıcısından form-POST ile gelir. Merchant’a gönderdiğiniz hazır bir link/payUrl yoktur; sayfaya kart + paymentRef ile geçilir.

Handoff hedefi

Alan	Değer
Hedef	`POST /v1/payments` yanıtındaki `handoffUrl` (`pay.*` origin, Paytalya handoff sayfası).
Metot	`POST` (navige eden form gönderimi).
Gövde	`paymentRef` + topladığınız kart alanları (`pan`, `expireMonth`, `expireYear`, `cv2`).

Gönderilen alanlar:

Alan	Açıklama
`paymentRef`	`POST /v1/payments` yanıtından gelen tek-kullanımlık ödeme referansı. Tutar/terminal/`returnUrl` buna bağlıdır; tarayıcı bunları değiştiremez.
`pan`	Kart numarası: kendi checkout’unuzda topladığınız değer.
`expireMonth` / `expireYear`	Son kullanma ayı/yılı (`MM` / `YY`).
`cv2`	Kart güvenlik kodu.

Tutar, terminal ve returnUrl handoff’a gönderilmez; bunlar paymentRef’e bağlı olarak Paytalya tarafında sabittir. Handoff yalnızca kart + paymentRef taşır.

Web: form gönderimi

Alıcının tarayıcısı handoffUrl’e bir form ile POST eder. Aşağıdaki örnekte kart maskelidir (gerçek değer alıcının tarayıcısının belleğinden gelir); gerçek kart numarasını dokümana ya da loga yazmayın:

<form id="paytalya-handoff" method="POST" action="https://pay.paytalya.example/checkout">
  <input type="hidden" name="paymentRef" value="pr_3Kd9xQ1w2E" />
  <input type="hidden" name="pan" value="4242 42** **** 4242" />
  <input type="hidden" name="expireMonth" value="12" />
  <input type="hidden" name="expireYear" value="28" />
  <input type="hidden" name="cv2" value="***" />
</form>
<script>document.getElementById('paytalya-handoff').submit();</script>

Gönderimden sonra her şey handoff sayfasında yürür: sayfa banka 3D devrini başlatır, alıcı 3D Secure’ü tamamlar, callback işlenir ve sonunda alıcının tarayıcısı sizin returnUrl’inize 303 ile döner. Banka 3D formunu siz kurmazsınız; auto-submit formunu handoff sayfası üretir.

Mobil: WebView

Mobil uygulamada akış aynıdır; tek fark tarayıcı bağlamını bir WebView ile yaratmanızdır:

Kartı uygulamanızın native ekranında toplayın.
Bir WebView açın ve kart + paymentRef ile handoffUrl’e POST edin:
- Android: WebView.postUrl(handoffUrl, body); gövde, application/x-www-form-urlencoded kodlanmış paymentRef + kart alanları.
- iOS: httpMethod = "POST" ayarlı bir URLRequest ile WebView’i yükleyin (pay.* hedefine).
3D Secure WebView içinde tamamlanır; sonunda WebView sizin returnUrl’inize iner.

Başarısız 3D = yeni ödeme

Bir paymentRef tek kullanımlıktır ve 3D yalnızca bir kez başlatılabilir:

Aynı paymentRef ile ikinci kez handoff denenirse istek reddedilir (payment_prepare_already_started).
paymentRef bilinmiyorsa/geçersizse veya süresi dolmuşsa handoff reddedilir (payment_ref_invalid / payment_ref_expired); bu durumda kart işlenmez.

Alıcı 3D’yi terk eder ya da başarısız olursa, aynı paymentRef’i tekrar kullanmayın; ilgili ödeme failed/expired olur. Yeniden denemek için yeni bir ödeme isteği (POST /v1/payments) oluşturun ve yeni paymentRef/handoffUrl ile baştan handoff yapın.