Ö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 ldg_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 oluşturduğunuz, siparişe özgü işlem kodu. Idempotency anahtarı olarak çalışır (aşağıya bkz.): cevap kaybolduğunda yeni bir kod üretmek yerine aynı kodla tekrar deneyin.
terminalId	Evet	Ödemenin yönlendirileceği terminal. Size ait ve aktif olmalıdır; aksi halde terminal_not_allowed döner. Terminaller onboarding sırasında size tanımlanır; size verilen terminalId’yi kullanırsınız.
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

İlk create’te 201 Created, aynı isteğin idempotent tekrarında 200 OK döner — bkz. Idempotency: partnerTxCode. Her iki durumda da 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",
  "idempotentReplay": false
}

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.
idempotentReplay	false ise bu istek yeni bir ödeme oluşturdu (HTTP 201). true ise yanıt daha önce oluşturulmuş bir ödemenin tekrarıdır (HTTP 200): hiçbir yeni kayıt yazılmadı ve dönen paymentCode ve paymentRef ilk çağrıyla birebir aynıdır; status ise ödemenin o anki güncel durumudur (ilk çağrıdan sonra 3D akışı ilerlediyse initiated olmayabilir). Bkz. Idempotency: partnerTxCode.

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 varsayılan olarak 30 dakikadır; HalkÖde altyapısına yönlenen terminallerde bu pencere 135 dakikadır. Alıcı bu süre içinde tamamlamazsa ödeme expired durumuna geçer.

Hız limitleri

POST /v1/payments için her API anahtarının dakikada 60 istek bütçesi vardır. Ayrıca aynı kaynak IP için dakikada 30 ve saatte 1.800 istek sınırı uygulanır. Aynı hesaba ait farklı API anahtarlarının 60/dk bütçeleri birbirinden bağımsızdır; ancak aynı kaynak IP’den gelen istekler IP bütçelerini paylaşır. Bir API anahtarının kaynak IP’yi değiştirmesi kendi 60/dk bütçesini sıfırlamaz.

Yüksek hacimli entegrasyonlarda hem API anahtarı bütçesi hem IP sınırları hesap bazında birlikte yükseltilebilir; bunun için bizimle iletişime geçin.

İdempotent tekrarlar dahil her create denemesi bu bütçeleri tüketir. Bir sınır aşıldığında ödeme okunmadan ya da oluşturulmadan 429 rate_limited döner. Yanıttaki Retry-After header’ı daima 60’tır (hangi sınırın dolduğu ayrıca belirtilmez); 60 saniye sonra tekrar deneyebilirsiniz.

Ayrıca bütün API-key /v1 uçları, API anahtarı veritabanında aranmadan önce aynı kaynak IP için ortak 240/dk ve platform genelinde 600/dk kaba kötüye-kullanım supabından geçer. Bunlar bu ucun iş kotası değildir: farklı /v1 uçları aynı üst-katman IP bütçesini paylaşır ve anormal toplam yükte daha erken 429 rate_limited dönebilir.

Idempotency: partnerTxCode

partnerTxCode bir idempotency anahtarıdır: aynı kodla, aynı içerikte gönderdiğiniz bir istek yeni bir ödeme oluşturmaz — ilk çağrının cevabını tekrar eder.

Senaryo	Yanıt
İlk create	201 Created + idempotentReplay: false
Aynı partnerTxCode + aynı istek	200 OK + idempotentReplay: true — ilk çağrıyla birebir aynı paymentCode/paymentRef; status güncel durum
Aynı partnerTxCode + farklı istek	409 duplicate_partner_tx_code

“Aynı istek” ne demek: aşağıdaki alanların hepsi birebir eşleşiyorsa istek aynı sayılır: partnerId (API anahtarınızdan gelir, gövdede yer almaz), terminalId, amount, installment ve para birimi (bugün her zaman TRY, istekte ayrı bir alan olarak gönderilmez). returnUrl ve description bu karşılaştırmaya girmez — aynı sipariş için farklı bir dönüş adresi göndermek meşrudur ve replay’i bozmaz.

Cevap kaybolduğunda ne yapmalısınız

Ağ hatası, timeout ya da aradaki bir bileşenin (load balancer, proxy) kesmesi yüzünden POST /v1/payments çağrınızın cevabını alamadığınızda ödemenin gerçekten oluşup oluşmadığını bilemezsiniz. Doğru davranış tektir: aynı partnerTxCode ile aynı isteği tekrar gönderin; asla yeni bir kod üretmeyin. Ödeme daha önce yazılmışsa 200 + idempotentReplay: true alırsınız ve ikinci bir tahsilat oluşmaz; yazılmamışsa istek normal şekilde 201 ile yeni bir ödeme oluşturur — her iki dalda da tam olarak bir ödeme vardır. Yeni bir partnerTxCode üretip tekrar denemek bu korumayı devre dışı bırakır ve aynı sipariş için ikinci bir tahsilat riski doğurur.

Üç sınır:

1. failed/expired bir ödeme anahtarı serbest bırakır. Bir ödeme bu durumlardan birine geçtikten sonra aynı partnerTxCode ile gönderdiğiniz istek replay değildir; normal şekilde yeni bir ödeme oluşturur (201).
2. İdempotent tekrar, ödemeyi oluşturduğunuz arayüzle sınırlıdır. Bir ödeme merchant panelinden oluşturulduysa aynı partnerTxCode ile yapılan API çağrısı replay değildir (409 döner) — ve tersi. Her arayüz kendi tekrarını görür; API entegrasyonunuz yalnız API’den oluşturduğu ödemeleri tekrarlayabilir.
3. Ödeme linkiyle doğan ödemeler replay edilmez. Ödeme linki ile tamamlanan bir ödemenin partnerTxCode’u otomatik üretilir (PL- öneki, örn. PL-42-1); link ödemesi hâlâ aktifken bu kodu POST /v1/payments’a gönderirseniz yanıt 409 duplicate_partner_tx_code’dur — ödeme linki akışı idempotent tekrar kapsamının dışındadır. (Link ödemesi failed/expired olduysa 1. maddedeki kural işler: anahtar serbest kalır ve yeni bir ödeme oluşur.)

duplicate_partner_tx_code’un anlamı daraldı

Bu hata artık “bu kod daha önce kullanıldı” anlamına gelmez: aynı kod + aynı istek artık hata değil, 200 idempotent tekrardır. 409 yalnızca “bu kod başka bir tahsilat için kullanımda” demektir — kayıtlı istekten farklı bir istek gönderdiniz, kod başka bir arayüzde oluşturulmuş bir ödemeye ait ya da bir ödeme linkine ait.

Aynı partnerTxCode ile daha önce oluşturduğunuz ödemenin güncel durumunu öğrenmek için (örn. cevap kaybolduktan sonra tekrar denemeden önce durumu kontrol etmek isterseniz) GET /v1/payments?partnerTxCode=… kullanabilirsiniz — 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
rate_limited	API anahtarı ya da kaynak-IP hız limiti aşıldı (429). Retry-After süresi dolduktan sonra aynı partnerTxCode ile tekrar deneyin.
duplicate_partner_tx_code	Aynı partnerTxCode farklı bir istekle kullanılmış (ya da başka bir arayüzde oluşturulmuş bir ödemeye, ya da bir ödeme linkine ait) — kod başka bir tahsilat için kullanımda. Aynı istek tekrarlanırsa bu hata değil, 200 idempotent tekrar döner. Bkz. Idempotency: partnerTxCode.
terminal_not_allowed	Terminal size ait değil ya da pasif.
amount_limit_exceeded	Hesabınıza tek-işlem için bir min/maks tutar sınırı tanımlanmışsa, bu aralığın dışındaki tutar 422 ile reddedilir. Sınır tanımlı değilse (varsayılan) tutar kontrolü yalnızca pozitifliktir: negatif ya da 0 tutar 400 validation_error ile reddedilir.
pos_per_tx_limit_exceeded, pos_daily_limit_exceeded, pos_weekly_limit_exceeded, pos_monthly_limit_exceeded, pos_time_window_limit_exceeded	Terminalinizin bağlı olduğu banka bağlantısına tanımlı bir limit (işlem-başı, günlük, haftalık, aylık ya da belirli bir saat aralığı) doldu (422). Ödeme oluşturulmaz; partnerTxCode tüketilmez, aynı istekle daha sonra tekrar deneyebilirsiniz. Bu limitler 3D başlangıcında da devreye girebilir; bkz. Ödeme Akışı ve Hata Kodları.
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ı.