Başarılı bir ödemenin tamamını veya bir kısmını iade edebilirsiniz. İade banka tarafında gerçekleşir; tutar müşterinin kartına geri yansır. Mutabakat öncesi yapılan iadeler “void/cancel” mantığıyla, mutabakat sonrası iadeler ise “refund” satırıyla işlenir — Payven bu kararı banka durumuna göre otomatik verir.
Endpoint
POST /api/v1/payments/{transaction_id}/refund
İstek
curl -X POST https://vpos.payven.com.tr/api/v1/payments/8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6/refund \
-H "Authorization: Bearer $PAYVEN_TOKEN" \
-H "Idempotency-Key: order-1001-refund-1" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"currency": "TRY",
"reason": "Musteri iade talebi",
"reason_code": "customer_request"
}'
| Alan | Tip | Zorunluluk | Açıklama |
|---|
amount | int (kuruş) | Opsiyonel | İade tutarı. Boş bırakılırsa kalan tüm tutar iade edilir. |
currency | string | Opsiyonel | Para birimi. Belirtilmezse orijinal işlemin para birimi kullanılır. |
reason | string | Opsiyonel | Serbest metin iade notu (max 500 karakter). Raporlamada görünür. |
reason_code | enum | Opsiyonel | Yapılandırılmış iade sebebi: customer_request, out_of_stock, duplicate_charge, product_defect, fraud, wrong_amount, other |
extra_properties | object | Opsiyonel | Konnektör-spesifik özel alanlar |
Idempotency-Key kullanın. Operatör arayüzünde butonun iki kez basılması veya client tarafı retry sırasında iki kez iade gerçekleşmesini engeller. Önerilen pattern: refund-{transaction_id}-{slot} (slot = 1, 2, 3 … her kısmi iade için artar).
Başarılı response
{
"transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
"status": "completed",
"extra_properties": {
"processed_at": "2026-05-03T15:00:01.234+00:00",
"host_reference": "REFUND-REF-789",
"provider_transaction_id": "REFUND-9f3d2b8e",
"refund_amount": "5000",
"remaining_refundable": "10000"
}
}
status sonucu | Anlam |
|---|
completed | Kısmi iade — ana işlem completed kalır, ayrı bir refund alt-Transaction’ı yazılır. Kalan tutar yine iade edilebilir. |
refunded | Tüm tutar iade edildi (cumulative) |
refund_processing | İade konnektörde, asenkron — webhook ile takip edin |
Wire seviyesinde partially_refunded adında bir status yoktur. Kısmi iade, ana Transaction’ın status’unu değiştirmez (completed kalır); her iade ayrı alt-Transaction kaydı olarak yazılır. Kalan iade edilebilir tutarı extra_properties.remaining_refundable veya GET /payments/{id} yanıtındaki refunded_amount alanından okuyun.
Çoklu kısmi iade
Bir işleme birden fazla kısmi iade yapabilirsiniz. Toplam iade tutarı orijinal işlem tutarını aşamaz.
| İade no | Tutar | Toplam iade | Ana işlem status | Alt iade kaydı |
|---|
| 1 | 5000 | 5000 | completed | yeni refunded |
| 2 | 5000 | 10000 | completed | yeni refunded |
| 3 | 5000 | 15000 | refunded (toplam = orijinal) | yeni refunded |
GET /api/v1/payments/{transaction_id} ile sorgulayarak kalan iade edilebilir tutarı extra_properties.remaining_refundable alanında görebilirsiniz.
Süre kısıtları
| Durum | İade davranışı |
|---|
| Mutabakat öncesi (gün içi) | Banka iptal (void) ile işlenir — komisyon yansımaz |
| Mutabakat sonrası | Banka iade (refund) satırı oluşur — komisyon iade politikası bankaya bağlı |
| 180 gün sonrası | Çoğu banka iade kabul etmez (bank_refund_period_expired) |
Mutabakat öncesi iadelerde banka komisyonu çoğu durumda yansımaz; mutabakat sonrası iadelerde komisyon iadesi banka anlaşmanıza tabidir. Anlaşma detayı için müşteri başarısı ekibine ulaşın.
Hata response’ları
| HTTP | code | Anlam |
|---|
404 | payment_not_found | İşlem bulunamadı |
422 | payment_not_refundable | İşlem iade edilemez durumda (örn. zaten iade edilmiş, başarısız, iptal edilmiş) |
422 | payment_already_refunded | Tüm tutar zaten iade edilmiş |
422 | refund_exceeds_original | İade tutarı kalan tutardan büyük |
422 | bank_refund_period_expired | Banka iade süresi dolmuş |
422 | bank_declined | Banka iadeyi reddetti — yanıttaki provider_error_code’a bakın |
Webhook olayları
| Olay | Açıklama |
|---|
refund.completed | İade başarıyla tamamlandı (tam veya kısmi). data.status yeni durumu (partially_refunded / refunded) yansıtır. |
Test
Sandbox’ta test kartlarıyla yapılan ödemeler iade edilebilir. Banka iade reddi senaryolarını tetiklemek için özel test kartlarını kullanın: Test Kartları. 
