Ö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 ptk_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.

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
}

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.

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.

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 ptk_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; page 0’dan başlar, size varsayılan 20’dir.

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
    }
  ],
  "page": 0,
  "size": 20,
  "hasMore": false
}

Alan	Açıklama
items	Bu sayfadaki linkler; her öğe oluşturma yanıtıyla aynı alanları taşır.
hasMore	Dönen öğe sayısı size’a eşitse true. Sonraki sayfa için page’i bir artırın.

Tekil link sorgulama

GET /v1/payment-links/{id}
Authorization: Bearer ptk_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 ptk_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.).

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.

Olası hatalar

Kod	HTTP	Sebep
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ş.
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ı