Ödeme Oluştur

Bir ödeme başlatmak için POST /v1/payments çağrılır. Bu istekle bir ödeme isteği oluşturursunuz (tutar, terminal, returnUrl); istek kartsızdır, kart bu çağrıda yer almaz. Yanıtta, alıcının tarayıcısını yönlendireceğiniz bir handoffUrl ve buna bağlı bir paymentRef döner. Kart, sonraki adımda alıcının tarayıcısından handoff sayfasına taşınır; bkz. Kart Handoff.

POST /v1/payments
Authorization: Bearer ptk_live_…
Content-Type: application/json

İstek gövdesi

{
  "amount": 125050,
  "partnerTxCode": "ORD-2026-8841",
  "terminalId": "trm_3Kd9x",
  "installment": 1,
  "description": "Sipariş #8841",
  "returnUrl": "https://magazan.example/odeme/sonuc"
}

Alan	Zorunlu	Açıklama
amount	Evet	Tahsil edilecek tutar, kuruş cinsinden tamsayı (1.250,50 TL → 125050). Bkz. Tutar ve Para Birimi.
partnerTxCode	Evet	Sizin tarafınızda üretilen benzersiz işlem kodu. Idempotency anahtarı olarak kullanılır (aşağıya bkz.).
terminalId	Evet	Ödemenin yönlendirileceği terminal. Size ait ve aktif olmalıdır; aksi halde terminal_not_allowed döner. Bugün terminalleri Paytalya sizin için sağlar; size verilen terminalId’yi kullanırsınız (kendi panelinizden self-servis terminal oluşturma ileriki bir sürümde planlanıyor).
installment	Hayır	Taksit sayısı; tek çekim için 1 (varsayılan).
description	Hayır	İşlem açıklaması.
returnUrl	Evet	3D dönüşünden sonra alıcının 303 ile yönlendirileceği adres. Paytalya bu adresi doğrular (open-redirect koruması).

İstek gövdesinde kart yok

POST /v1/payments kart alanı almaz. Kartı, Kart Handoff adımında alıcının tarayıcısından handoffUrl’e iletirsiniz. Kart Paytalya’nın API yanıtlarına, webhook gövdesine, sorgu sonuçlarına ya da loglarına asla yansımaz.

Yanıt

201 Created: yanıtta kart ya da banka 3D form verisi bulunmaz; bir paymentRef ve bir handoffUrl döner:

{
  "paymentCode": "pay_7Hq2bL",
  "status": "initiated",
  "paymentRef": "pr_3Kd9xQ1w2E",
  "handoffUrl": "https://pay.paytalya.example/checkout"
}

Alan	Açıklama
paymentCode	Ödemenin kalıcı kimliği; sorgu ve iade çağrılarında kullanılır.
status	Başlangıç durumu daima initiated. Bkz. Ödeme Yaşam Döngüsü.
paymentRef	Tek-kullanımlık ödeme referansı; handoff POST’unda kartla birlikte taşınır. paymentCode’dan ayrıdır; sorgu/iade çağrılarında kullanılmaz.
handoffUrl	Alıcının tarayıcısının/WebView’inin kart + paymentRef ile yönlendirileceği handoff sayfası adresi.

INITIATED’da kart/komisyon alanları henüz yok

Ödeme initiated durumundayken kart henüz handoff’ta gelmediği için sorgu yanıtında maskedPan, cardFamily, appliedRateBps, commissionAmount, netToPartner gibi karta-bağlı alanlar null döner. Bunlar 3D devri başladıktan sonra belirlenir. Bkz. Ödeme Sorgula.

Alıcıyı handoff’a yönlendirme

Yanıttaki handoffUrl’e, kendi checkout’unuzda topladığınız kartı ve paymentRef’i taşıyacak şekilde alıcının tarayıcısını/WebView’ini yönlendirirsiniz. Banka 3D formunu siz kurmazsınız; auto-submit formunu handoff sayfası üretir. Detay (web form-POST ve mobil WebView): Kart Handoff.

Süre (TTL)

Ödemenin 3D’yi tamamlamak için geçerli süresi 30 dakikadır. Alıcı bu süre içinde tamamlamazsa ödeme expired durumuna geçer.

Idempotency: partnerTxCode

partnerTxCode sizin tarafınızda benzersiz olmalıdır. Aynı kodla zaten aktif veya başarılı bir ödeme varsa istek duplicate_partner_tx_code hatası ile reddedilir. Bu, ağ tekrarları ya da çift tıklama gibi durumlarda mükerrer tahsilatı önler.

Aynı partnerTxCode ile daha önce oluşturduğunuz ödemeyi GET /v1/payments?partnerTxCode=… ile sorgulayabilirsiniz.

Olası hatalar

Kod	Sebep
duplicate_partner_tx_code	Aynı partnerTxCode ile aktif/başarılı ödeme var.
terminal_not_allowed	Terminal size ait değil ya da pasif.
amount_limit_exceeded	Tutar min/maks sınır dışında.
installment_not_allowed	Kart taksite uygun değil ya da terminalin taksit izni yok.

Tam liste: Hata Kodları.