Hata Kodları

Sanal POS hata kodları üç kategoriye ayrılır. Tüm Payven kodları lowercase snake_case formatındadır.

Kategori	Kaynak	Örnek değerler
Payven domain kodları	Payven iş kuralı + konnektör katmanı	`insufficient_funds`, `bank_declined`, `three_ds_verify_failed`, `refund_exceeds_original`
HTTP canonical kodlar	Generic 4xx/5xx altyapı	`bad_request`, `unauthorized`, `validation_failed`, `rate_limit_exceeded`, `idempotency_key_in_use`
Provider (banka) kodları	İşlemi yürüten banka — ISO 8583 spec’i	`00` (başarı), `51` (yetersiz bakiye), `54` (süresi geçmiş kart)

Yanıttaki alan eşleşmesi:

Yanıt alanı	Kategori
`code` (problem+json hata yanıtının body’sinde)	Payven domain veya HTTP canonical
`error_code` (failed ödeme sorgusunda data alanı olarak)	Payven domain
`provider_error_code` (failed ödeme sorgusunda data alanı olarak)	Banka — ISO 8583

Detay sayfaları

Payven Domain Kodları

Tüm domain kodlarının kategorize edilmiş tam listesi.

Banka Yanıt Kodları

Bankaların döndürdüğü ISO 8583 standardı + bankaya özgü kodlar.

Hata yanıt formatı

Tüm hatalar — banka reddi dahil — RFC 9457 problem+json formatında uygun HTTP durum koduyla döner:

{
  "type":          "https://docs.payven.com.tr/errors/insufficient_funds",
  "title":         "Yetersiz bakiye",
  "status":        422,
  "code":          "insufficient_funds",
  "detail":        "Banka kart bakiyesinin yetersiz olduğunu bildirdi (banka kodu: 51).",
  "instance":      "/api/v1/payments",
  "correlation_id": "9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8"
}

Sonradan GET /api/v1/payments/{id} ile sorgulanan failed ödemenin yanıtı 200 OK döner; banka detayları error_code ve provider_error_code data alanlarında taşınır — bkz. Payment Objesi.

Konsoldaki canlı katalog

Sürekli güncellenen konnektör hata kodu kataloğu konsolda mevcuttur: → Konsol → Konnektör Hata Kodları Bu ekran her bankanın özel kod açıklamalarını, Payven domain kodu eşlemesini ve önerilen kullanıcı mesajlarını içerir.

Hata yönetimi pratik kılavuz

Durum	Yapılacak
`validation_failed`, `invalid_*`	İsteği düzeltip yeniden gönderin (retry yok)
`unauthorized`, `invalid_token`	Token alın / refresh edin
`forbidden`, `merchant_inactive`, `product_not_licensed`	İlgili organizasyon yöneticisi / Payven satış ile iletişime geçin
`rate_limit_exceeded`	`Retry-After` header’ına uyup backoff ile retry edin
`idempotency_key_in_use`	Aynı anahtarla farklı body göndermeyi durdurun veya farklı anahtar üretin
`bank_declined`	Müşteriye nazik mesaj gösterip başka kart önerin (`provider_error_code` daha spesifik bilgi)
`bank_timeout`	Smart Retry zaten devreye girer — istemci tarafında ek bir şey yapmayın
`fraud_suspected`, `fraud_blocked`	Müşteriye genel “işlem onaylanmadı” mesajı gösterin (spesifik sebep paylaşmayın — fraud sinyalini sızdırır)
`5xx` (sunucu hatası)	Aynı `Idempotency-Key` ile exponential backoff retry

Genel hata yönetimi prensibi ve retry kodu örnekleri: Hata Yönetimi (Konsept).

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları — Genel Bakış

Detay sayfaları

Payven Domain Kodları

Banka Yanıt Kodları

Hata yanıt formatı

Konsoldaki canlı katalog

Hata yönetimi pratik kılavuz

​Detay sayfaları

Payven Domain Kodları

Banka Yanıt Kodları

​Hata yanıt formatı

​Konsoldaki canlı katalog

​Hata yönetimi pratik kılavuz

Detay sayfaları

Hata yanıt formatı

Konsoldaki canlı katalog

Hata yönetimi pratik kılavuz