Ödeme Oluştur

Bu sayfa ödeme oluşturma ucunu alan alan anlatır. Tekrar güvenliği ve hata kodları da buradadır.

Bir tahsilat başlatmak için POST /v1/payments çağrılır. Bu istek kart sahibinden çekilecek toplam tutarı, taksit sayısını, terminali ve dönüş adresini taşır. İstekte kart yoktur. Yanıtta kart sahibinin tarayıcısını yönlendireceğiniz handoffUrl ve ona bağlı tek kullanımlık paymentRef döner. Kart bir sonraki adımda kart sahibinin tarayıcısından LydiaGate 3DS Relay’e taşınır. Bu adıma handoff denir. Ayrıntı: Kart Handoff.

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

İstek

{
  "amount": 15563,
  "partnerTxCode": "SU-2026-10-000123",
  "terminalId": "trm_3Kd9x",
  "installment": 1,
  "description": "Su faturası Ekim 2026",
  "returnUrl": "https://ebelediye.example/odeme/sonuc"
}

Alan	Zorunlu	Anlamı
amount	Evet	Kart sahibinden çekilecek toplam tutar, kuruş cinsinden tamsayı. Taksit ve toplam tutar sorgusundan gelen totalAmount değerini olduğu gibi yazın. Komisyon bu tutarın içindedir. Değer 1 ile 1.000.000.000 kuruş arasında olmalıdır. Aralık dışı değer 400 ve validation_error ile reddedilir. Ayrıntı: Tutar ve Para Birimi.
partnerTxCode	Evet	Sizin tarafınızda bu tahsilata özgü işlem kodu. En fazla 128 karakter. Tahakkuk, sicil ya da fatura numaranızı kullanın. Tekrar güvenliği anahtarıdır. Ayrıntı: Tekrar güvenliği.
terminalId	Evet	Ödemenin yönlendirileceği terminal. Size ait ve aktif olmalıdır. Aksi halde terminal_not_allowed döner. Terminali LydiaGate tanımlar ve kimliğini size iletir.
installment	Hayır	Taksit sayısı. Sorguda kart sahibinin seçtiği installmentCount değerini yazın. Göndermezseniz 1 sayılır. Terminalinizde bu sayı için izin yoksa istek bu çağrıda installment_not_allowed ile reddedilir.
description	Hayır	İşlem açıklaması. En fazla 512 karakter.
returnUrl	Evet	3D Secure sonrası kart sahibinin HTTP 303 yönlendirmesiyle döneceği adres. En fazla 2048 karakter. http ya da https ile başlamalıdır. Hesabınıza izinli dönüş adresi listesi tanımlıysa listede olmayan alan adı 400 ve validation_error ile reddedilir. Ayrıntı: Hesap Açılışı ve İlk Giriş.

Not

POST /v1/payments kart alanı almaz. Kartı Kart Handoff adımında kart sahibinin tarayıcısından handoffUrl adresine iletirsiniz. Kart LydiaGate’in API yanıtlarına, webhook gövdesine, sorgu sonuçlarına ya da loglarına hiçbir zaman yansımaz.

Yanıt

İlk istekte 201 Created döner. Aynı isteğin tekrarında 200 OK döner. Ayrıntı: Tekrar güvenliği. İki durumda da yanıtta kart ya da banka formu bulunmaz.

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

Alan	Anlamı
paymentCode	Ödemenin kalıcı kimliği. Sorgu ve iade çağrılarında kullanılır.
status	Başlangıç durumu her zaman initiated. Ayrıntı: Ödeme Durumları.
paymentRef	Tek kullanımlık ödeme referansı. Handoff isteğinde kartla birlikte taşınır. paymentCode değerinden ayrıdır. Sorgu ve iade çağrılarında kullanılmaz.
handoffUrl	Kart sahibinin tarayıcısının kart ve paymentRef ile yönlendirileceği LydiaGate 3DS Relay adresi. Yanıttan olduğu gibi kullanın.
idempotentReplay	false ise bu istek yeni bir ödeme oluşturdu. true ise yanıt daha önce oluşturulmuş bir ödemenin tekrarıdır. Yeni kayıt yazılmamıştır. paymentCode ve paymentRef ilk çağrıyla aynıdır. status ödemenin o anki durumudur.

Not

Kart handoff’u yapılmadan önce sorgu yanıtında maskedPan, cardFamily, appliedRateBps, commissionAmount ve netToPartner alanları null döner. Kart LydiaGate 3DS Relay’e ulaşınca bu alanlar dolar. Ödeme bu sırada hâlâ initiated durumundadır. Ayrıntı: Ödeme Sorgula.

Kart sahibini yönlendirme

Yanıttaki handoffUrl adresine, kendi ekranınızda topladığınız kartı ve paymentRef değerini taşıyacak biçimde kart sahibinin tarayıcısını yönlendirirsiniz. Banka formunu siz kurmazsınız. Ayrıntı: Kart Handoff.

Süre

Kart sahibinin 3D Secure adımını tamamlaması için 135 dakika süresi vardır. Bu süre içinde tamamlanmayan ö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 her API anahtarı ve kaynak IP adresi çifti için dakikada 30 ve saatte 1.800 istek sınırı uygulanır. Aynı hesaba ait farklı API anahtarlarının bütçeleri birbirinden bağımsızdır. Kimlik doğrulamadan önce uygulanan ortak bir IP tavanı da ayrıca geçerlidir.

Tekrar istekleri dahil her istek bu bütçeleri tüketir. Bir sınır aşıldığında ödeme oluşturulmadan 429 ve rate_limited döner. Yanıttaki Retry-After başlığı her zaman 60 değerini taşır. 60 saniye sonra aynı partnerTxCode ile tekrar deneyebilirsiniz.

Bütün API uçları ayrıca kaynak IP adresi için dakikada 240 ve platform genelinde dakikada 600 isteklik ortak bir üst tavandan geçer. Bu tavan bu ucun iş kotası değildir. Farklı uçlar aynı IP bütçesini paylaşır.

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

Tekrar güvenliği: partnerTxCode

partnerTxCode bir tekrar güvenliği anahtarıdır. Aynı kodla ve aynı içerikle gönderdiğiniz istek yeni bir ödeme oluşturmaz. İlk çağrının yanıtını tekrar eder.

Durum	Yanıt
İlk istek	201 Created ve idempotentReplay: false
Aynı partnerTxCode ve aynı istek	200 OK ve idempotentReplay: true. paymentCode ve paymentRef ilk çağrıyla aynı. status güncel durum.
Aynı partnerTxCode ve farklı istek	409 ve duplicate_partner_tx_code

“Aynı istek” şu alanların hepsinin eşleşmesi demektir: terminalId, amount, installment ve para birimi. Hesabınız API anahtarınızdan gelir. returnUrl ve description bu karşılaştırmaya girmez. Aynı tahsilat için farklı bir dönüş adresi göndermek tekrarı bozmaz.

Dikkat

Ağ hatası ya da zaman aşımı yüzünden POST /v1/payments yanıtını alamadığınızda ödemenin oluşup oluşmadığını bilemezsiniz. Doğru davranış tektir: aynı partnerTxCode ile aynı isteği tekrar gönderin. Yeni bir kod üretmeyin. Ödeme daha önce yazılmışsa 200 ve idempotentReplay: true alırsınız ve ikinci bir tahsilat oluşmaz. Yazılmamışsa istek 201 ile yeni bir ödeme oluşturur. İki durumda da tam olarak bir ödeme vardır. Yeni kod üretmek bu korumayı devre dışı bırakır ve aynı borç için iki tahsilat riski doğurur.

Anahtar ne zaman serbest kalır: Ödeme failed ya da expired durumuna geçtikten sonra aynı partnerTxCode ile gönderdiğiniz istek tekrar sayılmaz. Normal şekilde yeni bir ödeme oluşturur ve 201 döner. Böylece aynı borç için yeni bir deneme aynı kodla yapılabilir.

Aynı partnerTxCode ile daha önce oluşturduğunuz ödemenin güncel durumunu GET /v1/payments?partnerTxCode=… ile öğrenebilirsiniz. Bu sorgu yalnız aktif ödemeleri bulur.

Olası hatalar

Kod	HTTP	Sebep
validation_error	400	Bir alan eksik ya da biçimi geçersiz. amount aralık dışı. returnUrl izinli listede olmayan bir alan adı taşıyor.
rate_limited	429	API anahtarı ya da kaynak IP hız limiti aşıldı. Retry-After süresi dolduktan sonra aynı partnerTxCode ile tekrar deneyin.
duplicate_partner_tx_code	409	Aynı partnerTxCode farklı bir istekle kullanımda. Aynı istek tekrarlanırsa bu hata değil, 200 tekrar döner.
terminal_not_allowed	403	Terminal size ait değil ya da pasif.
partner_not_active	403	Hesabınız askıda ya da kapalı. Aynı partnerTxCode ile tekrar gönderilen istek de bu durumda reddedilir. Ayrıntı: API Anahtarı ile Erişim.
payment_acceptance_held	403	Hesabınız için ödeme alımı şu anda durdurulmuş. Ödeme oluşturulmaz. partnerTxCode tüketilmez. Aynı partnerTxCode ile tekrar gönderilen istek de bu durumda reddedilir. Nedenleri ödeme kabul durumu ucundan öğrenin.
amount_limit_exceeded	422	Hesabınıza tek işlem için bir alt ya da üst tutar sınırı tanımlıysa tutar bu aralığın dışında.
pos_per_tx_limit_exceeded, pos_daily_limit_exceeded, pos_weekly_limit_exceeded, pos_monthly_limit_exceeded, pos_time_window_limit_exceeded	422	Terminalinizin banka bağlantısına tanımlı bir limit doldu: işlem başı, günlük, haftalık, aylık ya da belirli bir saat aralığı. Ödeme oluşturulmaz. partnerTxCode tüketilmez. Daha sonra aynı istekle tekrar deneyebilirsiniz. Bu limitler 3D Secure başlangıcında da devreye girebilir. Ayrıntı: Ödeme Akışı.
installment_not_allowed	422	Terminalinizde bu taksit sayısı için izin yok. Bu neden bu çağrıda değerlendirilir. Kartın markasına bağlı nedenler kart bu çağrıda bilinmediği için yalnız 3D Secure adımında ortaya çıkar. Kurtarma yolu: installment_not_allowed kurtarma yolu.

Tam liste: Hata Kodları.

installment_not_allowed kurtarma yolu

installment değeri ödeme oluşturulurken sabitlenir ve aynı ödemede değiştirilemez. Bu hatayı alırsanız farklı bir taksit sayısıyla yeni bir ödeme oluşturun. Aynı ödemede yalnız farklı bir kartla tekrar denenebilir. Kartın markasına bağlı retler 3D Secure adımında ortaya çıktığı için her deneme ödemenin kart deneme hakkından düşer. Hak bitince ödeme failed olur ve paymentRef bir daha kullanılamaz. Bu hatayı önceden görmek için ödeme ekranınızda Taksit ve Toplam Tutar Sorgusu ucunu kullanın ve yalnız dönen listedeki taksit sayılarını sunun.