Skip to main content
Sanal POS hata kodları üç kategoriye ayrılır. Tüm Payven kodları lowercase snake_case formatındadır.
KategoriKaynakÖ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 kodlarGeneric 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’i00 (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

DurumYapılacak
validation_failed, invalid_*İsteği düzeltip yeniden gönderin (retry yok)
unauthorized, invalid_tokenToken alın / refresh edin
forbidden, merchant_inactive, product_not_licensedİlgili organizasyon yöneticisi / Payven satış ile iletişime geçin
rate_limit_exceededRetry-After header’ına uyup backoff ile retry edin
idempotency_key_in_useAynı anahtarla farklı body göndermeyi durdurun veya farklı anahtar üretin
bank_declinedMüşteriye nazik mesaj gösterip başka kart önerin (provider_error_code daha spesifik bilgi)
bank_timeoutSmart Retry zaten devreye girer — istemci tarafında ek bir şey yapmayın
fraud_suspected, fraud_blockedMüş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).