Ödeme Linkleri

Ödeme linki, Kart Handoff entegrasyonu kurmadan tek bir ödeme talebi için paylaşılabilir bir URL oluşturmanızı sağlar. Alıcı bu URL’i kendi tarayıcısında açar, taksit seçer (varsa) ve ödemeyi kendisi tamamlar; kartı sizin checkout’unuz toplamaz. POST /v1/payments + handoff akışına alternatiftir; kart yüzeyiyle hiç uğraşmak istemediğiniz durumlarda (örn. bir siparişi telefonda/mesajla paylaşmak) kullanışlıdır.

POST /v1/payment-links
Authorization: Bearer ldg_live_…
Content-Type: application/json

İstek gövdesi

{
  "amount": 125050,
  "terminalId": "trm_3Kd9x",
  "customerCommissionShareBps": 0,
  "description": "Sipariş #8841",
  "redirectUrl": "https://magazan.example/odeme"
}

Alan	Zorunlu	Açıklama
amount	Evet	Talep edeceğiniz taban tutar, kuruş cinsinden tamsayı (1.250,50 TL → 125050). Bkz. Tutar ve Para Birimi.
terminalId	Evet	Ödemenin yönlendirileceği terminal. Size ait ve aktif olmalıdır; aksi halde terminal_not_allowed döner.
customerCommissionShareBps	Hayır	Komisyonun alıcıya yansıtılacak payı, baz puan tamsayı (0-10000; %2,5 → 250). Verilmezse 0 (komisyonun tamamı size ait olur).
description	Hayır	Link açıklaması.
redirectUrl	Hayır	Ödeme sonuçlandıktan sonra alıcının yönlendirileceği adresin tabanı; oluşturma anında doğrulanır (bkz. redirectUrl davranışı).
allowedInstallmentCounts	Hayır	Bu link için kabul edilecek taksit sayılarının listesi. Verilmezse (ya da null) kısıtlama yoktur ve terminalinizin efektif taksit kümesi (Taksit Seçenekleri) geçerli olur. Verirseniz liste boş olamaz ve terminalinizin efektif taksit kümesinin bir alt kümesi olmalıdır; aksi halde 422 installment_not_allowed ile reddedilir. Link oluşturulduktan sonra bu kısıt değiştirilemez.
items	Hayır	Ödeme sayfasında “Toplam” satırının üstünde listelenecek gösterim kalemleri. Format, toplam kuralı ve sterillik uyarısı için bkz. Gösterim kalemleri ve ödeyen adı.
payerName	Hayır	Alıcının adı; bu alanı siz sağlarsınız, alıcı kendisi girmez. En fazla 120 karakter. Ödeme sayfasında maskelenerek gösterilir; bkz. Gösterim kalemleri ve ödeyen adı.

Nihai taksit kümesi: kart × terminal ∩ link

Alıcı linki açtığında sunulan taksit seçenekleri iki kümenin kesişimidir: (1) kartın bu terminalde gerçekten ödenebilir taksitleri — Taksit Seçenekleri ucunun aynı kart ve terminal için döndürdüğü küme (kartın taksit markası ile terminalinizin efektif taksit kümesi bunun içinde hesaba katılır) ve (2) varsa bu linkin allowedInstallmentCounts kısıtı. allowedInstallmentCounts göndermek yalnızca bu linke özgü ek bir daraltmadır — terminalinizde zaten sunulmayan bir taksit sayısını bu alanla açamazsınız.

amount her zaman sizin talep ettiğiniz taban tutardır

customerCommissionShareBps sıfırdan büyükse, alıcıdan seçtiği taksit sayısına göre hesaplanan ek tutar linkin sayfasında ayrıca gösterilir; siz her durumda amount alanına girdiğiniz tutarı alırsınız.

İdempotency anahtarı yok

POST /v1/payments’ın aksine link oluşturmanın bir idempotency anahtarı (partnerTxCode benzeri) yoktur; her çağrı yeni bir link üretir. Aynı sipariş için birden fazla link oluşturmamak üzere tekrarlı istekleri kendi tarafınızda önleyin.

Yanıt

201 Created:

{
  "id": "01J9K5QATN6M1PXG7VYSD3HZWB",
  "token": "plk_EXAMPLE0000000000…",
  "url": "https://pay.lydiagate.example/link/plk_EXAMPLE0000000000…",
  "partnerReference": 42,
  "status": "pending",
  "amount": 125050,
  "customerCommissionShareBps": 0,
  "description": "Sipariş #8841",
  "redirectUrl": "https://magazan.example/odeme",
  "firstOpenedAt": null,
  "lastOpenedAt": null,
  "expiresAt": "2026-06-21T12:00:00Z",
  "createdAt": "2026-06-14T12:00:00Z",
  "updatedAt": "2026-06-14T12:00:00Z",
  "allowedInstallmentCounts": null,
  "items": null,
  "payerName": null
}

Alan	Açıklama
id	Linkin kalıcı kimliği; tekil sorgu, iptal çağrıları ve webhook gövdesindeki paymentLinkId alanında kullanılır.
token	url alanının gizli bileşeni. Ayrıca saklamanız gerekmez; url zaten bunu içerir.
url	Alıcıyla paylaşacağınız tam adres.
partnerReference	Hesabınıza özel, artan sıra numarası (görüntüleme/referans amaçlıdır).
status	Linkin güncel durumu. Bkz. Yaşam döngüsü.
amount	Talep ettiğiniz taban tutar (kuruş).
firstOpenedAt / lastOpenedAt	Alıcının linki ilk/son açtığı an; henüz açılmadıysa null.
expiresAt	Linkin son geçerlilik anı. Bkz. Süre (TTL).
createdAt / updatedAt	Zaman damgaları (UTC).
allowedInstallmentCounts	İstekte gönderdiğiniz taksit kısıtı, artan sıralı; kısıtlama yoksa null.
items	İstekte gönderdiğiniz gösterim kalemleri, aynı sırayla; kalem göndermediyseniz null.
payerName	İstekte gönderdiğiniz ödeyen adı, ham hâliyle; göndermediyseniz null. Ödeme sayfasında bunun yerine maskelenmiş hâli gösterilir; bkz. Gösterim kalemleri ve ödeyen adı.

token’ı yalnızca link adresi olarak kullanın

token, url’in gizli parçasıdır: kim bu değeri bilirse ödemeyi tamamlayabilir. Loglamayın ve url dışında bir kanalda paylaşmayın.

Yaşam döngüsü

Durum	Anlam
pending	Link oluşturuldu; alıcı henüz açmadı.
launched	Alıcı linki açtı.
initiated	Bir ödeme denemesi 3D Secure’da; uçuşta. Bu durumdayken yeni bir deneme başlatılamaz. Deneme tamamlanmadan başarısız olursa link yeniden ödenebilir hale gelir.
completed	Ödeme tamamlandı (terminal — sonraki bir geçiş yok).
expired	Süresi (TTL) doldu, link ödenmeden geçersiz oldu (terminal).
failed	Bir ödeme denemesi başarısız oldu; terminal değildir — link yeniden ödenebilir.
cancelled	Siz iptal ettiniz (terminal).

Başarısız denemeden sonra tekrar deneme

Bir deneme failed ile sonuçlandığında linkin kendisi terminal duruma geçmez: alıcı aynı linki tekrar açıp yeni bir kartla ödemeyi deneyebilir.

Link ödemeleri idempotent tekrar kapsamı dışındadır

Bir ödeme linkiyle tamamlanan ödemenin partnerTxCode’u otomatik üretilir; POST /v1/payments’ın idempotent tekrar sözleşmesi bu kodları kapsamaz — bu kodla create çağırmak her zaman 409 duplicate_partner_tx_code döner.

Süre (TTL)

Bir linkin varsayılan geçerlilik süresi, oluşturulduğu andan itibaren 7 gündür. expiresAt anı geçtiğinde link expired durumuna düşer ve artık ödenemez.

Linkleri listeleme

GET /v1/payment-links?status=pending&status=launched&page=0&size=20
Authorization: Bearer ldg_live_…

Parametre	Açıklama
status	Bir ya da daha fazla durumla filtreleme; parametreyi tekrarlayın (status=pending&status=launched).
minAmount / maxAmount	Tutar aralığı (kuruş).
createdFrom / createdTo	Oluşturulma zaman aralığı (UTC, ISO 8601).
page / size	Sayfalama; varsayılan page=0, size=20. Aralık dışı değerler sessizce düzeltilir: page negatifse 0, size 1..200 aralığına kırpılır (ör. size=500 → 200). Yanıt her zaman uygulanan page/size değerlerini döner. Tek sınır page × size ≤ 100000’dir; bu aşılırsa 400 validation_error döner (o kadar derin bir sayfa yoktur).

Yanıt (200 OK):

{
  "items": [
    {
      "id": "01J9K5QATN6M1PXG7VYSD3HZWB",
      "token": "plk_EXAMPLE0000000000…",
      "url": "https://pay.lydiagate.example/link/plk_EXAMPLE0000000000…",
      "partnerReference": 42,
      "status": "pending",
      "amount": 125050,
      "customerCommissionShareBps": 0,
      "description": "Sipariş #8841",
      "redirectUrl": "https://magazan.example/odeme",
      "firstOpenedAt": null,
      "lastOpenedAt": null,
      "expiresAt": "2026-06-21T12:00:00Z",
      "createdAt": "2026-06-14T12:00:00Z",
      "updatedAt": "2026-06-14T12:00:00Z",
      "allowedInstallmentCounts": null,
      "items": null,
      "payerName": null
    }
  ],
  "page": 0,
  "size": 20,
  "hasMore": false
}

Alan	Açıklama
items	Bu sayfadaki linkler; her öğe oluşturma yanıtıyla aynı alanları taşır. ⚠ Bu dış zarfın items’ı linklerin listesidir; her linkin kendi gösterim kalemleri o linkin nesnesi içindeki items alanındadır (bkz. Gösterim kalemleri ve ödeyen adı) — iki alan aynı adı taşır ama farklı şeyleri ifade eder.
hasMore	Sayfa (uygulanan size kadar) doluysa ve sonraki sayfanın offset’i 100000 güvenlik ufku içindeyse true. true olduğunda sonraki sayfa için page’i bir artırın; ufkun sonundaki dolu sayfada false döner.

Tekil link sorgulama

GET /v1/payment-links/{id}
Authorization: Bearer ldg_live_…

{id}, oluşturma ya da listeleme yanıtındaki id alanıdır (token değil).

Link iptali

DELETE /v1/payment-links/{id}
Authorization: Bearer ldg_live_…

Yalnızca terminal olmayan durumdaki linkler (pending / launched / initiated / failed) iptal edilebilir; başarılı çağrı linki cancelled durumuna geçirir ve güncel link kaydını döner. Zaten tamamlanmış, süresi dolmuş ya da daha önce iptal edilmiş bir linki tekrar iptal etmeye çalışmak hataya düşer (aşağıya bkz.).

Hız limitleri

Public payment-link uçları iki ayrı API anahtarı bütçesi kullanır:

• POST /v1/payment-links ve DELETE /v1/payment-links/{id} ortak 30/dk oluşturma/iptal bütçesini,
• tekil GET /v1/payment-links/{id} ve liste GET /v1/payment-links ortak 120/dk okuma bütçesini paylaşır.

Dört uç ayrıca aynı kaynak IP için ortak 120/dk sınırını paylaşır. Aynı hesaba ait farklı API anahtarlarının API-anahtarı bütçeleri bağımsızdır; aynı kaynak IP’den geliyorlarsa IP bütçesi yine ortaktır. Okuma bütçesini tüketmek oluşturma/iptal bütçesini, oluşturma/iptal de okuma bütçesini tüketmez.

Bir sınır aşıldığında link okunmadan, oluşturulmadan veya değiştirilmeden 429 rate_limited döner. Retry-After: 60 header’ı yeniden denemeden önce beklenecek süreyi saniye cinsinden verir.

Bunlardan önce bütün API-key /v1 uçları, API anahtarı veritabanında aranmadan aynı kaynak IP için ortak 240/dk ve platform genelinde 600/dk kaba kötüye-kullanım supabından geçer. Bu üst-katman koruması payment-link iş kotası değildir; farklı /v1 uçları aynı IP bütçesini paylaştığı için anormal toplam yükte daha erken 429 rate_limited dönebilir. Temiz bir kaynakta 240/dk tavan, 120/dk payment-link IP bütçesini gölgelemez.

redirectUrl davranışı

redirectUrl verdiyseniz Lydia Gate bunu link oluşturma anında doğrular:

• Adres, şeması http ya da https olan mutlak bir URL olmalıdır; değilse istek 400 validation_error ile reddedilir.
• Hesabınız için izinli bir host listesi tanımlıysa, redirectUrl’in host’u bu listede yer almalıdır; listede olmayan bir host aynı şekilde 400 validation_error ile reddedilir. Böyle bir liste tanımlı değilse yalnızca şema kontrol edilir. Bu, POST /v1/payments’taki returnUrl doğrulamasıyla aynı open-redirect korumasıdır.

Doğrulamadan geçen redirectUrl için, alıcı ödeme sonucunu gördükten sonra:

• Ödeme tamamlandığında → {redirectUrl}/payment/success adresine,
• Deneme başarısız olduğunda → {redirectUrl}/payment/failure adresine yönlendirilir.

redirectUrl göndermezseniz alıcı, sonucu Lydia Gate’in barındırdığı sayfada görür.

Gösterim kalemleri ve ödeyen adı

items ve payerName, ödeme sayfasında gösterilen ek bilgilerdir; ikisi de opsiyoneldir ve hiçbiri tutar hesabına ya da bankaya giden isteğe girmez.

Kalemler (items)

Kalem gönderirseniz, tutarlarının toplamı amount alanına tam olarak eşit olmalıdır:

{
  "amount": 125050,
  "terminalId": "trm_3Kd9x",
  "items": [
    { "name": "Yıllık üyelik", "amount": 100000 },
    { "name": "Kargo", "note": "Standart teslimat", "amount": 25050 }
  ]
}

Alan	Zorunlu	Açıklama
items[].name	Evet	Kalem adı, en fazla 120 karakter.
items[].note	Hayır	Kalem için alt açıklama, en fazla 200 karakter.
items[].amount	Evet	Kalem tutarı, kuruş cinsinden tamsayı, en az 1.

Toplam amount’a eşit değilse istek 422 payment_link_items_amount_mismatch ile reddedilir. Kısmi gösterim desteklenmez: siparişin tüm kalemlerini gönderemiyorsanız items alanını hiç göndermeyin. Gönderdiğiniz sıra korunur; kalemler ödeme sayfasında aynı sırayla listelenir. Liste en az 1, en fazla 50 kalem içerebilir; boş liste ([]) 400 validation_error ile reddedilir.

Kalem adı ve notuna kişisel veri yazmayın

Kalem adı ve notuna üçüncü kişilerin kişisel verisini yazmayın; bu alanlar ödeme sayfasında olduğu gibi gösterilir.

Ödeyen adı (payerName)

payerName, alıcının adına dair bir bilgidir ve bu alanı siz sağlarsınız; alıcı kendisi girmez. En fazla 120 karakterdir.

Ödeme sayfasında payerName maskelenmiş hâliyle görünür: her kelimenin ilk iki karakteri açık kalır (tek harfli kelimede bir karakter), kalanı * ile değiştirilir ve kelime uzunluğu korunur — örneğin MUSTAFA ALI AYDIN görüntülenirken MU***** AL* AY*** olur. Bu API’nin oluşturma, sorgulama ve listeleme yanıtlarında ise payerName ham hâliyle döner, çünkü bu yanıtlara yalnızca siz (API anahtarınızla) ya da merchant panelinizden erişirsiniz — değeri zaten siz göndermiştiniz. Maskeleme yalnızca linkin adresini (url) paylaştığınız alıcı tarafında uygulanır; bu adresi ele geçiren üçüncü bir kişi alıcının tam adını görmemelidir.

Sterillik kontrolü

items[].name, items[].note ve payerName alanlarına kart numarasına ya da IBAN’a benzeyen bir değeri tek başına girerseniz (örn. "4111111111111111"), istek 400 sensitive_data_not_allowed ile reddedilir. Bu kontrol yalnızca alanın tamamı bu kalıba uyduğunda tetiklenir; kart numarası ya da IBAN başka bir metnin içine gömülüyse (örn. "Aidat ödemesi, kart: 4111111111111111") istek reddedilmez. Bu alanlara zaten kart ya da banka hesap bilgisi yazmamalısınız; bu kontrol yalnızca ek bir güvenlik katmanıdır.

Olası hatalar

Kod	HTTP	Sebep
rate_limited	429	API anahtarı ya da ortak kaynak-IP bütçesi aşıldı. Retry-After süresi dolduktan sonra tekrar deneyin.
payment_link_not_found	404	Link bulunamadı ya da bu partnere ait değil.
payment_link_already_paid	409	Link zaten tamamlanmış. (Nadiren: iptal isteğiniz tam o anda tamamlanan bir ödemeyle yarışırsa da aynı hata döner.)
payment_link_expired	409	Linkin süresi dolmuş; artık iptal edilemez.
payment_link_cancelled	409	Link zaten iptal edilmiş.
payment_link_items_amount_mismatch	422	items gönderildi ama tutarlarının toplamı amount alanına eşit değil.
installment_not_allowed	422	allowedInstallmentCounts boş gönderildi ya da terminalinizin efektif taksit kümesinin alt kümesi değil.

Tam liste: Hata Kodları.

Webhook’lar

Bir link tamamlandığında ya da süresi dolduğunda Lydia Gate size bir webhook gönderir (payment_link.completed / payment_link.expired); gövdede paymentCode yerine bu sayfadaki id alanı (paymentLinkId adıyla) taşınır. Detay ve örnek gövde: Webhooks.

İlgili

• Ödeme Oluştur: kart handoff ile doğrudan S2S akışı
• Webhooks
• Hata Kodları