Ödeme Akışı

Paytalya entegrasyonu iki adımlı bir modeldir:

Sunucu tarafı (siz): POST /v1/payments ile bir ödeme isteği oluşturursunuz (tutar, terminal, returnUrl). Kart bu istekte yer almaz. Yanıtta bir paymentRef (tek-kullanımlık ödeme referansı) ve bir handoffUrl alırsınız.
Tarayıcı tarafı (alıcı): Alıcının tarayıcısını/WebView’ini, kartı ve paymentRef’i taşıyacak şekilde handoffUrl’e (Paytalya’nın ayrı handoff sayfası, pay.* origin) yönlendirirsiniz. 3D Secure devri, banka 3D sayfasına POST ve callback bu sayfada yürür; tamamlanınca alıcı sizin returnUrl’inize döner.

Hash üretimi, banka 3D devri, callback işleme ve tahsilat Paytalya tarafındadır. Kesin sonucu sunucu tarafında GET /v1/payments ve webhook ile alırsınız.

Akış

Ödeme isteği oluşturma: POST /v1/payments ile tutar, terminalId ve returnUrl gönderirsiniz (kart YOK). Yanıtta paymentCode, status: initiated, paymentRef ve handoffUrl alırsınız. Bkz. Ödeme Oluştur.
Handoff sayfasına geçiş: alıcının tarayıcısını/WebView’ini, topladığınız kart + paymentRef ile handoffUrl’e form-POST ile gönderirsiniz. Detay: Kart Handoff.
3D Secure: handoff sayfası banka 3D devrini başlatır; alıcının tarayıcısı banka 3D Secure sayfasına POST eder ve alıcı doğrulamayı tamamlar. Bu adımlar handoff sayfasında otomatik yürür; siz bir form kurmazsınız.
Callback + tahsilat: banka 3D sonucunu Paytalya’ya bildirir; Paytalya callback’i işler ve tahsilatı yapar.
Geri dönüş: handoff sayfası alıcının tarayıcısını/WebView’ini sizin returnUrl’inize 303 ile yönlendirir. returnUrl’e taşınan sonuç, istemci (tarayıcı) üzerinden geldiği için nihai/güvenilir kabul edilmemelidir.
Sonucu doğrulama: kesin durumu GET /v1/payments ve webhook ile öğrenirsiniz. Karar (sipariş onayı vb.) daima bu nihai sonuca dayanır.

sunucu: POST /v1/payments (KARTSIZ)  ──►  { paymentRef, handoffUrl, status: initiated }
                                                  │
tarayıcı/WebView: kart + paymentRef ──POST──►  [Paytalya handoff sayfası (pay.*)]
                                                  │  (handoff sayfası banka 3D'sine POST eder)
                                                  ▼
                                          [banka 3D Secure]
                                                  │
                              banka callback ──►  [Paytalya: callback + tahsilat]
                                                  │
                       303 (handoff sayfasından) ──►  returnUrl (sonuç nihai DEĞİL)
                                                  │
sunucu: webhook + GET /v1/payments  ──────────────►  kesin durum

Web ve mobil

Akış her iki kanalda da aynıdır; tek fark tarayıcı bağlamını nasıl yarattığınızdır:

Web: alıcının native tarayıcısı handoffUrl’e form-POST eder; dönüşte tarayıcı returnUrl’e 303 ile navige olur.
Mobil: merchant uygulaması kartı kendi native ekranında toplar, bir WebView açar ve kart + paymentRef ile handoffUrl’e POST eder. 3D, WebView içinde tamamlanır; sonunda WebView returnUrl’e iner.

Tek deneme: bir ödeme = bir kart denemesi

Bir paymentRef için 3D yalnızca bir kez başlatılabilir. Alıcı 3D’yi terk eder ya da başarısız olursa, o ödeme failed/expired olur ve paymentRef yeniden kullanılamaz. Tekrar denemek için yeni bir ödeme isteği (POST /v1/payments) oluşturursunuz: “tekrar = yeni ödeme” yaklaşımı. Detay: Kart Handoff.