İade ve İptal

Bu sayfa bir tahsilatın nasıl geri alındığını anlatır. Aynı gün iptal ile sonraki günlerde yapılan iade arasındaki farkı burada görürsünüz.

Başarılı bir ödemenin tamamını ya da bir kısmını kart sahibine geri verebilirsiniz. Üç uç vardır. Uçlar POST isteğiyle çağrılır. Yöntemi LydiaGate’in seçmesini isterseniz varsayılan uca istek gönderirsiniz. Yöntemi kendiniz belirlemek isterseniz void ya da credit ucunu kullanırsınız. void iptal, credit iade demektir. Üçü de aynı istek ve yanıt gövdesini kullanır. İade ve iptali panelden de yapabilirsiniz: Panel Kılavuzu.

Uç	Yöntem	Kullanım
POST /v1/payments/{paymentCode}/refunds	LydiaGate seçer	Varsayılan uç.
POST /v1/payments/{paymentCode}/refunds/void	Her zaman iptal	Yalnız tam tutar. Kısmi iptal yoktur.
POST /v1/payments/{paymentCode}/refunds/credit	Her zaman iade	Tam ya da kısmi tutar.

İptal ve iade farklı işlemlerdir. İşlem günü, bankanın gün sonu kesimine göre belirlenen gündür. İptal, aynı işlem günü içinde satışın bankada hiç gerçekleşmemiş sayılmasıdır. İade, bankaya yansımış bir satışın parasının kart sahibine geri gönderilmesidir. Kullanılan yöntem yanıtta method alanında döner: void iptal, credit iade.

İade tutarı

amount alanı kart sahibine geri dönecek tutardır. Kart sahibinden ne çekildiyse iade aynı birimde yapılır. Komisyon bu tutarın içindedir. Ayrıca bir hesap yapmazsınız.

• Tam iade: amount göndermeyin ya da ödemenin amount değerini gönderin. Kart sahibine çekilen tutarın tamamı döner.
• Kısmi iade: geri vermek istediğiniz tutarı amount alanına yazın. Kart sahibine bu tutar döner.
• Üst sınır: bir ödemede iade edilebilecek toplam, ödemenin amount değeridir. Kısmi iadeler bu sınıra kadar toplanır.
• Son iade: kalan tutarı kapatırken amount göndermeyin. LydiaGate kalanın tamamını iade eder ve kuruş farkı oluşmaz.

Örnek: anapara 500,00 TL, komisyon 10,00 TL ve kart sahibinden çekilen toplam 510,00 TL olsun. Ödemenin amount değeri 51000 olur.

İade	Gönderilen amount	Kart sahibine dönen	Bankaya bildirilen komisyon ters kaydı
Tam iade	gönderilmez ya da 51000	510,00 TL	10,00 TL
Kısmi iade	25500	255,00 TL	5,00 TL
Kısmi iadeden sonra kalan	gönderilmez	255,00 TL	5,00 TL

Komisyonun bankaya ters kaydı

İade ile birlikte LydiaGate, iade edilen tutarın komisyon payını bankaya ters kayıt olarak bildirir. Pay, satışta bildirilen komisyonun iade oranına göre hesaplanır ve en yakın kuruşa yuvarlanır. Toplam iade ödemenin tutarına ulaştığında kalan komisyon payı da son iadeyle kapanır. Böylece bildirilen ters kayıtların toplamı satışta bildirilen komisyona eşit olur.

İptalde ayrı bir ters kayıt bildirilmez. İptal satışın tamamını geri alır. Ters kayıt tutarı API yanıtlarında görünmez. Gün sonu raporunun iade satırında komisyon kolonunda, bankanın geri verdiği komisyon görünür. İptalde bu, ödemenin komisyonunun tamamıdır.

İade başlatma

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

İstek gövdesi üç uçta da aynıdır:

{
  "amount": 51000,
  "partnerRefundCode": "IADE-2026-10-000123-1"
}

Alan	Zorunlu	Anlamı
amount	Hayır	İade edilecek toplam tutar, kuruş. Göndermezseniz kalan tutarın tamamı iade edilir. void ucunda gönderirseniz kalan tutarın tamamına eşit olmalıdır.
partnerRefundCode	Evet	Sizin tarafınızda üretilen, bu iadeye özgü kod. Aynı kodu tekrar göndermeniz ikinci bir iadeyi önler. Tekrar istek, ödemenin ve önceki iadenin durumuna göre 409 ve refund_in_progress ya da 422 ve payment_not_refundable ile reddedilir.

Yanıt 201 Created. Üç uçta da aynı şema:

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

Alan	Anlamı
refundId	İadenin kimliği. Durum sorgusunda kullanılır.
method	Kullanılan yöntem: void iptal, credit iade. Varsayılan uçta LydiaGate’in seçtiği yöntem döner.
status	approved onaylandı, pending sonuç henüz kesinleşmedi, declined banka reddetti.

Varsayılan uç: yöntemi LydiaGate seçer

POST /v1/payments/{paymentCode}/refunds isteğinin iptal mi iade mi olacağını LydiaGate satışın zamanlamasına göre belirler. Ölçüt, satışın ve iade isteğinin aynı işlem günü içinde olup olmadığıdır. İşlem günü bankanın gün sonu kesimine göre belirlenir. Takvim günü değildir. Kesim Türkiye saatiyle 22.00’dir. Bu saatte ve sonrasında yapılan işlemler ertesi işlem gününe sayılır.

Satış ve istek	İstenen tutar	Yöntem	Sonuç
Aynı işlem günü	Tam	void	Satış bankaya yansımadan iptal edilir.
Aynı işlem günü	Kısmi	Yok	Henüz yapılamaz. refund_not_yet_available döner. Gün sonundan sonra tekrar deneyin.
Farklı işlem günü	Tam ya da kısmi	credit	İade işlenir.

Aynı işlem günü kısmi iade isteği refund_not_yet_available alır. İsteği gün sonundan sonra tekrarladığınızda credit olarak işlenir. Aynı işlem günü tam iade anında void olur.

Yöntemi siz belirleyin: void ve credit

Yöntemi LydiaGate’e bırakmak istemiyorsanız /refunds/void ya da /refunds/credit ucuna doğrudan istek gönderebilirsiniz. Bu iki uç aynı işlem günü kuralına bağlı değildir. Her biri kendi kurallarına göre çalışır.

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

Her zaman iptal dener. Kurallar:

• Tutar her zaman tam ve dokunulmamış olmalıdır. amount gönderirseniz kalan tutarın tamamına eşit olmalıdır.
• Ödemede daha önce onaylanmış bir iade varsa iptal yapılamaz. Böyle bir ödeme partially_refunded durumundadır.

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

Kurallar sağlansa bile zamanlama bankaya kalır. Satış gün sonu kesimine girdikten sonra gönderilen bir iptal isteğini banka reddedebilir. Bu durumda yanıt status: "declined" olur. Bu bir hata değildir.

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

Her zaman iade dener. Tam ya da kısmi tutar serbesttir. Aynı işlem günü içinde de gönderebilirsiniz. Satış henüz gün sonu kesimine girmediyse banka bu isteği reddedebilir. Bu durumda yanıt status: "declined" olur. Bu bir hata değildir.

Not

Uçlar arasında otomatik geçiş yoktur. /refunds/void isteğiniz refund_method_not_available ile reddedilirse LydiaGate kendiliğinden /refunds/credit denemez. İkinci uca istek göndermek size kalır.

İadenin ödemeye etkisi

Onaylanan bir iade ödemenin durumunu günceller:

Yöntem ve kapsam	Ödemenin yeni durumu
void	voided
credit kısmi	partially_refunded
credit tam ya da toplam iade ödeme tutarına eşit	refunded

Durum yalnız iade onaylandığında 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 durum onay ya da ret olarak güncellenir. Belirsiz bir iadeyi kendiliğinden başarısız saymayın. Belirsizlik çoğunlukla banka yanıtının gecikmesinden kaynaklanır. Çözülme gecikebilir. Kesin durumu iade sorgusundan takip edin. Bir iade uzun süre pending kalırsa LydiaGate destek ekibiyle iletişime geçin.

409 ve refund_in_progress hatasının iki ayrı nedeni vardır:

1. Bekleyen iade: aynı ödeme için pending bir iade varken yeni bir iade isteği gönderdiniz. Önceki iade kesinleşene kadar bekleyin.
2. Tekrarlanan iade kodu: reddedilmemiş bir iade için daha önce kullandığınız partnerRefundCode değerini tekrar gönderdiniz. İstek işlenmez. O iadenin durumunu iade sorgusuyla öğrenin.

Bir iadenin durumunu sorgulama

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

Yanıt 200 OK:

{
  "refundId": "ref_5Tg8p",
  "method": "credit",
  "status": "approved",
  "amount": 51000,
  "procReturnCode": "00",
  "authCode": "123456",
  "errMsg": null,
  "bankReference": "241024091203",
  "createdAt": "2026-10-24T09:12:00Z",
  "updatedAt": "2026-10-24T09:12:03Z"
}

Alan	Anlamı
refundId	İadenin kimliği.
method	Kullanılan yöntem: void ya da credit.
status	İade durumu: pending, approved ya da declined.
amount	İade tutarı, kuruş.
procReturnCode	Bu iadeye ait banka sonuç kodu. Yoksa null.
authCode	Bu iadeye ait banka onay kodu. Yoksa null.
errMsg	Bu iadeye ait banka hata mesajı. Yoksa null.
bankReference	Bu iadeye ait banka referansı. Yoksa null.
createdAt	İadenin oluşturulduğu an.
updatedAt	Son güncelleme anı. UTC.

Not

Bu uçtaki banka sonuç alanları yalnız sizin iade işleminize aittir ve mutabakat içindir. Hepsi null olabilir. Bu alanlar yalnız iade sorgusunda bulunur. İade başlatma yanıtında yoktur. Ham kart verisi hiçbir yanıtta dönmez.

Ödemenin güncel iade dökümünü GET /v1/payments/{paymentCode} yanıtındaki refunds listesinde de görürsünüz.

Webhook

İade sonucu refund.approved ya da refund.declined olayıyla bildirilir. Banka onayı gecikebilir. Bu yüzden refund.approved olayı iade isteğinizden dakikalar, hatta saatler sonra gelebilir. Olay geldiğinde ödemenin yeni durumunu sorguyla öğrenin. Ayrıntı: Webhooks.

Olası hatalar

Kod	HTTP	Sebep
validation_error	400	partnerRefundCode eksik ya da amount geçersiz.
partner_not_active	403	Hesabınız askıda ya da kapalı. İade istekleri reddedilir.
refund_not_found	404	İade bulunamadı ya da hesabınıza ait değil.
payment_not_refundable	422	Ödeme bulunamadı, hesabınıza ait değil ya da iade için uygun durumda değil. Tam iadesi ya da iptali tamamlanmış ödeme de bu kodu alır.
refund_amount_exceeds_remaining	422	İstenen tutar kalan iade edilebilir tutarı aşıyor.
refund_not_yet_available	422	Varsayılan uçta aynı işlem günü kısmi iade. Gün sonundan sonra yapılabilir.
refund_method_not_available	422	/refunds/void ucunda tutar kalan tutarın tamamına eşit değil ya da ödemede daha önce onaylanmış bir iade var.
refund_in_progress	409	Bu ödeme için pending bir iade var ya da bu partnerRefundCode daha önce kullanıldı.

Tam liste: Hata Kodları.