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
POST /api/v1/payments/{transaction_id}/void
İstek
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 |
Başarılı response
{
"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"
}
}
İş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.
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 |
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.
Pre-Auth iptali
Henüz capture edilmemiş bir Pre-Auth (ön provizyon) bu endpoint ile iptal edilebilir — rezervasyon serbest bırakılır:
curl -X POST https://vpos.payven.com.tr/api/v1/payments/8e3f5c12-.../void \
-H "Authorization: Bearer $PAYVEN_TOKEN" \
-H "Idempotency-Key: hotel-1001-void"
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 |
Webhook olayları
| Olay | Açıklama |
|---|
void.completed | İptal başarıyla tamamlandı (data.status: "canceled") |
void.failed | İptal banka tarafından reddedildi |
