> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# İade

> Bir ödemenin tamamını veya bir kısmını müşteriye geri ödeme.

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

```http theme={null}
POST /api/v1/payments/{transaction_id}/refund
```

## İstek

```bash theme={null}
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                                                                                                         |

<Warning>
  **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).
</Warning>

## Başarılı response

```json theme={null}
{
  "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                                                                    |

<Note>
  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.
</Note>

## Ç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` |

İşlem detayını [`GET /api/v1/payments/{transaction_id}`](/sanal-pos/inquiries/payment-detail) 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`)                 |

<Tip>
  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.
</Tip>

## 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                 |

Hata yanıtı RFC 9457 problem+json formatındadır. Detay: [Hata Yönetimi](/documentation/concepts/errors).

## 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. |

Detay: [Webhook Olayları](/sanal-pos/webhooks/events).

## 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ı](/sanal-pos/test/test-cards).