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

# İptal (Void)

> Mutabakat öncesi yapılmış bir ödemeyi tam tutarda iptal edin.

Void, mutabakat öncesinde **tam tutarlı** ödeme iptalidir. İade'den (refund) farkı: void işlemi banka tarafında **muhasebe hareketi yaratmaz**, ödeme hiç olmamış gibi kayıttan düşer. Müşterinin kart ekstresinde işlem **görünmez**.

## Endpoint

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

## İstek

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/payments/8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6/void \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001-void" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Stok kalmadı"
  }'
```

| Alan               | Tip    | Zorunluluk | Açıklama                        |
| ------------------ | ------ | ---------- | ------------------------------- |
| `reason`           | string | Opsiyonel  | İptal sebebi (raporlama için)   |
| `extra_properties` | object | Opsiyonel  | Konnektör-spesifik özel alanlar |

Request body tamamen opsiyoneldir — sadece header'lar yeterlidir.

## Başarılı response

```json theme={null}
{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "canceled",
  "extra_properties": {
    "processed_at":            "2026-05-03T16:00:01.234+00:00",
    "host_reference":          "VOID-REF-789",
    "provider_transaction_id": "VOID-9f3d2b8e"
  }
}
```

<Note>
  İşlem durumunun wire değeri **`canceled`** (önceki ad "voided" değiştirildi, eski isimlendirme tüm enum genelinde temizlendi). Asenkron void senaryosunda geçici olarak `canceled_processing` durumu görülebilir; final durum webhook (`void.completed`) ile gelir.
</Note>

## Void mu, refund mu?

| Kriter              | Void                                     | Refund                                 |
| ------------------- | ---------------------------------------- | -------------------------------------- |
| Tutar               | Yalnız tam tutar                         | Tam veya kısmi                         |
| Mutabakat           | Öncesinde — gün içi                      | Öncesi veya sonrası                    |
| Banka komisyonu     | Yansımaz                                 | Mutabakat sonrasında çoğunlukla yansır |
| Müşteri ekstresinde | Hareket görünmez                         | "İade" satırı olarak görünür           |
| Süre                | Genelde gün sonuna kadar (banka bağımlı) | 180 güne kadar                         |

**Pratik kural:** Aynı gün içinde, **tam tutar** iade edilecekse → **void**. Diğer durumlarda → [refund](/sanal-pos/payments/refund).

<Note>
  **Pratikte tek endpoint yeterli:** Hangi yöntemin uygun olduğunu Payven banka durumuna göre otomatik karar verir. `/refund` çağırdığınızda mutabakat öncesi ise void, sonrası ise refund satırı oluşur. Yine de "kesin void" istiyorsanız bu endpoint'i kullanın.
</Note>

## Pre-Auth iptali

Henüz capture edilmemiş bir Pre-Auth (ön provizyon) bu endpoint ile iptal edilebilir — rezervasyon serbest bırakılır:

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/payments/8e3f5c12-.../void \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: hotel-1001-void"
```

Detay: [Pre-Auth ve Capture](/sanal-pos/payments/pre-auth-capture).

## Hata response'ları

| HTTP  | `code`                              | Anlam                                                                   |
| ----- | ----------------------------------- | ----------------------------------------------------------------------- |
| `404` | `payment_not_found`                 | İşlem bulunamadı                                                        |
| `422` | `void_not_allowed_after_settlement` | Mutabakat sonrası void yapılamaz — `/refund` kullanın                   |
| `422` | `payment_already_voided`            | İşlem zaten iptal edilmiş                                               |
| `422` | `payment_not_voidable`              | Bu durumdaki işlem iptal edilemez (örn. başarısız, iade edilmiş)        |
| `422` | `bank_declined`                     | Banka iptal isteğini 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                                               |
| ---------------- | ------------------------------------------------------ |
| `void.completed` | İptal başarıyla tamamlandı (`data.status: "canceled"`) |
| `void.failed`    | İptal banka tarafından reddedildi                      |

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