İçeriğe geç
Paytalya Paytalya Gateway

Genel Bakış

Paytalya Gateway, kart ödemelerinizi yöneten bir ödeme orkestrasyon sistemidir. Entegrasyon iki adımlıdır: sunucunuzdan bir ödeme isteği oluşturursunuz, sonra alıcının tarayıcısını/WebView’ini kartla birlikte Paytalya’nın ayrı handoff sayfasına (pay.* origin) yönlendirirsiniz. Banka 3D Secure devri, callback ve tahsilat bu sayfada ve Paytalya tarafında yürür.

Paytalya kartı sizin yerinize toplamaz: kartı kendi checkout’unuzda toplarsınız. Ardından alıcıyı Paytalya’nın ayrı handoff sayfasına yönlendirirsiniz; bu sayfa topladığınız kartı ve tek-kullanımlık ödeme referansını (paymentRef) alarak banka 3D devrini yürütür.

Temel kavramlar

Bölüm başlığı “Temel kavramlar”
  • Merchant (Üye işyeri): Ödeme kabul eden taraf, yani siz.
  • Terminal: Ödemenin yönlendirildiği banka POS tanımı. Her ödeme bir terminale bağlıdır (terminalId zorunludur). Terminaller onboarding sırasında size tanımlanır. Bugün terminalleri Paytalya sizin için sağlar ve size verilen terminalId’yi kullanırsınız; kendi panelinizden self-servis terminal/sanal POS oluşturma ileriki bir sürümde planlanmaktadır.
  • Payment (Ödeme): Bir kart işleminin baştan sona yaşam döngüsü. Her ödemenin bir paymentCode kimliği ve bir durumu vardır (initiated → captured → ...). Bkz. Ödeme Yaşam Döngüsü.
  • paymentRef: POST /v1/payments yanıtında dönen tek-kullanımlık ödeme referansı. Kartı handoff sayfasına taşırken kullanılır; paymentCode’dan ayrıdır.
  • handoffUrl: Alıcının tarayıcısını/WebView’ini yönlendireceğiniz Paytalya handoff sayfası adresi (pay.*).

Sunulan yetenekler

Bölüm başlığı “Sunulan yetenekler”

Paytalya API dört temel yetenek sunar:

  1. Ödeme oluştur: POST /v1/payments ile (tutar + terminalId + returnUrl) ödeme başlatır, yanıtta paymentRef + handoffUrl alırsınız. Bkz. Ödeme Oluştur.
  2. Ödeme sorgula: GET /v1/payments/{paymentCode} veya partnerTxCode ile ödemenin güncel durumunu, tutarını, komisyonunu ve iade dökümünü çekersiniz. Bkz. Ödeme Sorgula.
  3. İade / iptal: POST /v1/payments/{paymentCode}/refunds ile tam veya kısmi iade başlatırsınız. Bkz. İade ve İptal.
  4. Webhook: Ödeme durumu değiştikçe Paytalya sizin uç noktanıza bildirim gönderir. Bkz. Webhooks.

Uçtan uca akış

Bölüm başlığı “Uçtan uca akış”
1. POST /v1/payments              →  { paymentRef, handoffUrl, status: initiated } alırsınız
2. Alıcıyı handoff sayfasına yönlendir →  kart + paymentRef ile handoffUrl'e (pay.*) form-POST
3. Handoff sayfası 3D'yi yürütür    →  banka 3D, callback ve tahsilat Paytalya tarafında işlenir
4. Geri dönüş                     →  alıcı returnUrl'ine 303 ile döner (taşınan sonuç nihai değil)
5. Sonucu doğrula                 →  webhook + GET /v1/payments ile kesin durumu öğrenirsiniz

Handoff sayfasına ve 3D’ye yönlendirmeyi alıcının tarayıcısı/WebView’i yapar; siz sunucu tarafında yalnızca ödemeyi başlatır ve sonucu doğrularsınız. Web ile mobil arasındaki tek fark tarayıcı bağlamıdır (native tarayıcı vs WebView); akış aynıdır, mobilde deep-link yoktur. Adım adım detay: Ödeme Akışı ve Kart Handoff.

Sonraki adımlar

Bölüm başlığı “Sonraki adımlar”