Skip to main content
Bankalar, ödeme yanıtında ISO 8583 standardına dayanan 2 haneli kod döner. Banka reddi durumunda Payven application/problem+json (RFC 9457) yanıtı döner; bankanın orijinal kodu response body’sindeki detail alanında, sonrasında GET /payments/{id} ile sorgulandığında provider_error_code alanında bulunur. 
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type":          "https://docs.payven.com.tr/errors/bank_declined",
  "title":         "Banka işlemi reddetti",
  "status":        422,
  "code":          "bank_declined",
  "detail":        "Yetersiz bakiye (banka kodu: 51)",
  "instance":      "/api/v1/payments",
  "correlation_id": "9f1c8e76-..."
}

​
Sık karşılaşılan kodlar

Aşağıdaki tabloda provider_error_code (banka kodu) → eşleşen Payven code ve müşteriye gösterilebilecek mesaj örnekleri var.
Banka koduAçıklamaPayven codeMüşteriye gösterim
00Onaylandı—(Başarılı)
01Bankanızı arayınbank_declined”Lütfen bankanızla iletişime geçin.”
04Karta el konuldubank_declined”Bu kart kullanılamaz.”
05Do not honor (reddedildi)do_not_honor”Bankanız işlemi onaylamadı.”
12Geçersiz işlembank_declinedGenel red mesajı
13Geçersiz tutarinvalid_amountGenel red mesajı
14Kart numarası geçersizinvalid_card”Kart bilgilerinizi kontrol edin.”
15Tanınmayan bankabank_declinedGenel red mesajı
30Format hatasıbank_declinedGenel red mesajı
41Kart kayıp/çalıntıbank_declined”Bu kart kullanılamaz.”
43Çalıntı kartbank_declined”Bu kart kullanılamaz.”
51Yetersiz bakiyeinsufficient_funds”Yetersiz bakiye.”
54Kart süresi dolmuşcard_expired”Kartınızın son kullanma tarihi geçmiş.”
55Hatalı PINbank_declined”Bilgilerinizi kontrol edin.”
57Kart sahibi bu işlemi yapamazbank_declinedGenel red mesajı
58Terminal bu işlemi yapamazconfig_error(Konfigürasyon — destek)
59Şüpheli sahtecilikfraud_suspected”Bankanızla iletişime geçin.”
61Limit aşımılimit_exceeded”Kart limitiniz yeterli değil.”
62Kısıtlı kartbin_restrictedGenel red mesajı
63Güvenlik ihlalifraud_suspected(İzleme — destek)
65Aktivite limit aşımılimit_exceeded”Çok fazla deneme yaptınız, lütfen sonra tekrar deneyin.”
75PIN deneme limiti aşıldıbank_declined”Bilgilerinizi kontrol edin.”
82Geçersiz CVVinvalid_cvv”Güvenlik kodunuz (CVV) yanlış.”
91Banka sistemi yanıt vermedibank_timeout(Smart Retry devreye girer)
92Yönlendirme hatasıconfig_error(Konfigürasyon — destek)
96Sistem hatasıbank_system_error(Smart Retry)

​
Banka-spesifik kodlar

Her bankanın kendi özel kodları da olabilir (örn. Garanti’nin “fraud kuralı kategorisi 2”). Bu kodlar konsoldaki Hata Kodları ekranında banka bazında listelenir: dashboard.payven.com.tr/connector-error-codes

​
Müşteriye gösterme prensibi

Hassas kodları gizleyin. “Şüpheli sahtecilik” gibi kodlar müşteriye direkt gösterilmemelidir — fraud filterları açık etmenize neden olabilir.
Yönlendirici mesaj verin. “Reddedildi” yerine “Bankanız işlemi onaylamadı, başka bir kart denemek ister misiniz?”
Smart Retry zaten devrede. 91, 96 gibi geçici kodlar için Smart Retry alternatif konnektör dener — kullanıcıya genelde göstermenize gerek yok.

​
Örnek müşteri mesajı eşleme

function userMessageFromCode(code) {
  const map = {
    "51": "Bakiyeniz yeterli değil, başka bir kart denemek ister misiniz?",
    "54": "Kartınızın son kullanma tarihi geçmiş.",
    "61": "İşlem tutarı kart limitinizi aşıyor.",
    "82": "Güvenlik kodunuz (CVV) yanlış.",
    "14": "Kart bilgilerinizde hata var.",
    "01": "Bankanızla iletişime geçmeniz gerekiyor.",
    "59": "Bankanız işlemi onaylamadı.",
    "65": "Çok fazla deneme yapıldı. Lütfen daha sonra tekrar deneyin.",
  };
  return map[code] || "İşleminiz gerçekleştirilemedi. Lütfen tekrar deneyin.";
}