İade ve İptal

Başarılı bir ödemenin tamamını ya da bir kısmını iade edebilirsiniz. Üç ayrı uç sunulur: yöntemi (iptal mi, iade mi) platformun seçmesini isterseniz varsayılan uca, yöntemi siz belirlemek isterseniz void ya da credit ucuna istek gönderirsiniz. Üçü de aynı istek ve yanıt gövdesini kullanır.

Uç	Yöntem	Kullanım
POST /v1/payments/{paymentCode}/refunds	Platform seçer	Varsayılan; mevcut entegrasyonlar bunu değiştirmeden kullanmaya devam edebilir.
POST /v1/payments/{paymentCode}/refunds/void	Her zaman iptal	Yalnızca tam tutar; kısmi iptal yoktur.
POST /v1/payments/{paymentCode}/refunds/credit	Her zaman iade	Tam ya da kısmi tutar serbesttir.

İade başlatma

POST /v1/payments/{paymentCode}/refunds
Authorization: Bearer ldg_live_…
Content-Type: application/json

İstek gövdesi (üç uçta da birebir aynı şema):

{
  "amount": 40000,
  "partnerRefundCode": "REF-2026-8841-1"
}

Alan	Zorunlu	Açıklama
amount	Hayır	İade edilecek tutar (kuruş). Verilmezse kalan bakiyenin tamamı iade edilir. void ucunda tutar verilirse kalan bakiyenin tamamına eşit olmalıdır.
partnerRefundCode	Evet	Sizin tarafınızda üretilen benzersiz iade kodu (idempotency).

Yanıt (201 Created, üç uçta da birebir aynı şema):

{
  "refundId": "ref_5Tg8p",
  "method": "void",
  "status": "approved"
}

Alan	Açıklama
refundId	İadenin kimliği; durum sorgusunda kullanılır.
method	Kullanılan yöntem: void (iptal) veya credit (iade). Otomatik uçta platformun seçtiği yöntemi, zorlamalı uçlarda gönderdiğiniz uca karşılık gelen yöntemi şeffaf olarak döner.
status	approved (onaylandı), pending (sonuç henüz kesinleşmedi) veya declined (banka senkron olarak reddetti).

Otomatik uç: yöntemi platform seçer

POST /v1/payments/{paymentCode}/refunds isteğinin iptal (void) mi yoksa iade (credit) mi olacağını Lydia Gate, satışın zamanlamasına göre belirler. Bu, satışın ve iade isteğinin aynı işlem günü (işlem sağlayıcısının gün sonu kesimine göre — takvim gününe göre değil) içinde olup olmadığına bakar. Kural şudur:

Satış ve istek	İstenen tutar	Yöntem	Sonuç
Aynı işlem günü	Tam (kalan bakiyenin tamamı)	void	İşlem henüz banka tarafına yansımadan iptal edilir.
Aynı işlem günü	Kısmi	(yok)	Henüz yapılamaz → refund_not_yet_available. Gün sonundan sonra credit ile dener.
Farklı işlem günü	Tam veya kısmi	credit	İade işlenir.

Pratik sonuç: aynı işlem günü kısmi iade isteği yaparsanız refund_not_yet_available alırsınız; isteği gün sonundan sonra tekrarladığınızda credit olarak işlenir. Aynı işlem günü tam iade ise anında void olur.

Doğrudan-tahsilat terminallerinde Credit iadesi yok

Bazı terminaller doğrudan-tahsilat (direct) modundadır; bu terminallerdeki ödemelerde Credit iadesi yapılamaz, yalnızca gün içi tam iptal (void) mümkündür. Bu terminallerde Credit iade talebi (otomatik uçta da, /refunds/credit ucunda da) 422 direct_refund_not_allowed döner.

Yöntem-zorlamalı uçlar: void ve credit

Yöntemi platformun tahminine bırakmak istemiyorsanız /refunds/void ya da /refunds/credit ucuna doğrudan istek gönderebilirsiniz. Bu iki uç, aynı işlem günü kısıtına tabi değildir; her biri kendi yapısal kurallarına göre çalışır.

POST /v1/payments/{paymentCode}/refunds/void

Her zaman iptal (void) dener. Yapısal kurallar:

• Daima tam ve dokunulmamış tutar: amount gönderirseniz kalan bakiyenin tamamına eşit olmalıdır; kısmi bir tutar kabul edilmez.
• Ödemede daha önce onaylanmış bir Credit iadesi varsa (partially_refunded durumundaysa) artık void edilemez.

Bu kurallardan biri sağlanmıyorsa istek bankaya hiç ulaşmadan 422 refund_method_not_available ile reddedilir.

Yapısal kurallar sağlansa bile zamanlama bankaya kalır: işlem gün sonu kesimine girdikten sonra gönderilen bir void isteğini banka reddedebilir (status: "declined"). Credit’teki gibi bu da hata değil, bilinçli kullanım sonucudur.

POST /v1/payments/{paymentCode}/refunds/credit

Her zaman iade (credit) dener; tam ya da kısmi tutar serbesttir. Aynı işlem günü içinde de gönderebilirsiniz — ancak işlem henüz gün sonu kesimine girmediyse banka bu isteği reddedebilir (status: "declined"). Bu, bilinçli bir kullanım tercihidir; hata değildir.

Ödeme doğrudan-tahsilat (direct) bir terminaldeyse bu uç her zaman 422 direct_refund_not_allowed döner (bkz. yukarıdaki not).

Uçlar arasında otomatik geçiş yoktur

/refunds/void isteğiniz refund_method_not_available ile reddedilirse platform kendiliğinden /refunds/credit denemez. İkinci uca istek göndermek size kalır.

İade durumunun ödemeye etkisi

Onaylanan bir iade, ödemenin durumunu günceller:

Yöntem ve kapsam	Ödeme yeni durumu
void (tam iptal)	voided
credit kısmi (kümülatif iade < satış)	partially_refunded
credit tam ya da kümülatif iade = satış	refunded

Durum yalnızca iade onaylandığında (status: "approved") değişir; pending bir iade ödeme durumunu henüz değiştirmez.

pending: belirsiz iade

status: "pending" dönen bir iade henüz kesinleşmemiştir; sonuç çözülünce (onay ya da ret) durumu güncellenir. Belirsiz bir iadeyi kendiliğinden başarısız saymayın. Belirsizlik çoğunlukla banka yanıtının gecikmesinden kaynaklanır; iade, sonuç kesinleşene kadar pending kalır ve bu çözülme gecikebilir. Nihai durumu GET /v1/payments/{paymentCode}/refunds/{refundId} ile takip edin. Bir iade uzun süre pending kalırsa destek ekibiyle iletişime geçin.

refund_in_progress (409) hatasının iki ayrı tetikleyicisi vardır:

1. Tek uçuş: aynı ödeme için hâlâ pending bir iade varken yeni bir iade isteği gönderdiniz (hangi uca gönderdiğinizden bağımsız). Önceki iade kesinleşene kadar bekleyin.
2. Mükerrer iade kodu (idempotency): reddedilmemiş bir iade için daha önce kullandığınız bir partnerRefundCode’u tekrar gönderdiniz. İstek işlenmez; ilgili iadenin durumunu GET /v1/payments/{paymentCode}/refunds/{refundId} ile sorgulayın (kod zaten kayıtlıdır).

İade durumunu sorgulama

GET /v1/payments/{paymentCode}/refunds/{refundId}
Authorization: Bearer ldg_live_…

Yanıt (200 OK):

{
  "refundId": "ref_5Tg8p",
  "method": "void",
  "status": "approved",
  "amount": 40000,
  "procReturnCode": "00",
  "authCode": "123456",
  "errMsg": null,
  "bankReference": "240615091203",
  "createdAt": "2026-06-15T09:12:00Z",
  "updatedAt": "2026-06-15T09:12:03Z"
}

Alan	Açıklama
refundId	İadenin kimliği.
method	Kullanılan yöntem (void / credit).
status	İade durumu (pending / approved / declined).
amount	İade tutarı (kuruş).
procReturnCode	Bu iadeye ait banka sonuç kodu (varsa; yoksa null).
authCode	Bu iadeye ait banka onay kodu (varsa; yoksa null).
errMsg	Bu iadeye ait banka hata mesajı (varsa; yoksa null).
bankReference	Bu iadeye ait banka referansı (varsa; yoksa null).
createdAt / updatedAt	Zaman damgaları (UTC).

İade detayında banka sonuç alanları

Bu uçta dönen procReturnCode, authCode, errMsg ve bankReference alanları, sizin kendi iade işleminize ait banka sonuç kodlarını taşıyabilir (mutabakat/raporlama içindir; hepsi null olabilir). Bu alanlar yalnızca iade detayı sorgusunda bulunur; POST iade yanıtında değildir. Yine de ham kart/3D verisi (PAN/CVV/md/cavv) asla dönmez.

Bu uç, iadenin nihai sonucunu öğrenmek için kullanılır; pending bir iadenin çözümünü buradan takip edersiniz. Ödemenin güncel iade dökümünü (toplam/kalan) GET /v1/payments ile de görebilirsiniz.

İlgili hata kodları

Kod	Sebep
payment_not_refundable	Ödeme iade için uygun durumda değil.
refund_amount_exceeds_remaining	İstenen tutar kalan iade edilebilir bakiyeyi aşıyor.
refund_not_yet_available	Otomatik uçta, aynı işlem günü kısmi iade; gün sonu sonrasında yapılabilir.
refund_method_not_available	/refunds/void ucunda zorlanan yöntem bu ödemede uygulanamaz: gönderilen tutar kalan bakiyenin tamamına eşit değil ya da ödemede daha önce onaylanmış bir Credit iadesi var.
refund_in_progress	Bu ödeme için pending bir iade zaten var (tek uçuş) ya da bu partnerRefundCode daha önce kullanıldı (mükerrer kod).
direct_refund_not_allowed	Ödeme doğrudan-tahsilat (direct) bir terminalde yapıldı; Credit iadesi yapılamaz, yalnızca gün içi tam iptal (void) mümkündür.

Tam liste: Hata Kodları.