Ö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 Lydia Gate 3DS Relay’e 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 Lydia Gate 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). Terminalinizde bu sayı için izin yoksa istek create anında installment_not_allowed ile reddedilir. Kartın hangi taksitlere uygun olduğunu ve komisyon oranlarını önceden görmek için Taksit Seçenekleri ucunu kullanabilirsiniz.
description	Hayır	İşlem açıklaması.
returnUrl	Evet	3D dönüşünden sonra alıcının 303 ile yönlendirileceği adres. Lydia Gate 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 Lydia Gate’in 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.lydiagate.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 Lydia Gate 3DS Relay 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 Lydia Gate 3DS Relay ü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 — bu alias yalnızca aktif ödemeleri çözer; failed/expired bir ödeme için kesin sorgu paymentCode’la yapılır (bkz. Ödeme Sorgula).

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. Şu an uygulanmıyor (rezerve alan — tutar sınırı bugün yalnızca pozitiflik doğrulamasıdır; negatif ya da 0 tutar 400 validation_error ile reddedilir).
installment_not_allowed	Terminalinizde bu taksit sayısı için izin yoksa istek create anında (bu çağrıda) reddedilir. Kartın markasına bağlı diğer nedenler (kart takside uygun değil, bu marka × taksit sayısı terminalinizde sunulmuyor) kart bu çağrıda henüz bilinmediğinden hâlâ yalnızca handoff/3D devri sırasında değerlendirilir. Kurtarma yolu: Hata Kodları.

Tam liste: Hata Kodları.