İptal (Void)

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

Request body tamamen opsiyoneldir — sadece header’lar yeterlidir.

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

Pratik kural: Aynı gün içinde, tam tutar iade edilecekse → void. Diğer durumlarda → refund.

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"

Detay: Pre-Auth ve 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.

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

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Endpoint

İstek

Başarılı response

Void mu, refund mu?

Pre-Auth iptali

Hata response’ları

Webhook olayları

​Endpoint

​İstek

​Başarılı response

​Void mu, refund mu?

​Pre-Auth iptali

​Hata response’ları

​Webhook olayları

Endpoint

İstek

Başarılı response

Void mu, refund mu?

Pre-Auth iptali

Hata response’ları

Webhook olayları