İade ve İptal

Başarılı bir ödemenin tamamını ya da bir kısmını iade edebilirsiniz. İade ve iptal aynı uç nokta ile yapılır; yöntemi (iptal mi, iade mi) sistem seçer, siz seçmezsiniz.

İade başlatma

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

İstek gövdesi:

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

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

Yanıt (201 Created):

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

Alan	Açıklama
refundId	İadenin kimliği; durum sorgusunda kullanılır.
method	Sistemin seçtiği yöntem: void (iptal) veya credit (iade). Şeffaf olarak döner.
status	approved (onaylandı), pending (sonuç henüz kesinleşmedi) veya declined (banka senkron olarak reddetti).

void / credit: yöntemi sistem seçer

İade isteğinin iptal (void) mi yoksa iade (credit) mi olacağını Lydia Gate, satışın zamanlamasına göre belirler. Partner bu seçimi yapamaz; yalnızca sonucu method alanında şeffaf olarak görür. Kural şudur:

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

Pratik sonuç: aynı 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ı 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 422 direct_refund_not_allowed döner.

İade durumunun ödemeye etkisi

Onaylanan bir iade, ödemenin durumunu günceller:

Yöntem ve kapsam	Ödeme yeni durumu
void (aynı gün 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. Ö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 ptk_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	Sistemin seçtiği 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	Aynı gün kısmi iade; gün sonu sonrasında yapılabilir.
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ı.