İ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ı) veya `pending` (sonuç henüz kesinleşmedi).

void / credit: yöntemi sistem seçer

İade isteğinin iptal (void) mi yoksa iade (credit) mi olacağını Paytalya, 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.

İ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; sistem kesin sonucu kendisi çözer. Nihai durumu GET /v1/payments/{paymentCode}/refunds/{refundId} ile öğrenin.

Aynı ödeme için pending bir iade varken yeni iade isteği refund_in_progress ile reddedilir (tek uçuş kuralı); önceki iade kesinleşene kadar bekleyin.

İ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).

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.

Tam liste: Hata Kodları.