Banka Yanıt Kodları

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 kodu	Açıklama	Payven `code`	Müşteriye gösterim
`00`	Onaylandı	—	(Başarılı)
`01`	Bankanızı arayın	`bank_declined`	”Lütfen bankanızla iletişime geçin.”
`04`	Karta el konuldu	`bank_declined`	”Bu kart kullanılamaz.”
`05`	Do not honor (reddedildi)	`do_not_honor`	”Bankanız işlemi onaylamadı.”
`12`	Geçersiz işlem	`bank_declined`	Genel red mesajı
`13`	Geçersiz tutar	`invalid_amount`	Genel red mesajı
`14`	Kart numarası geçersiz	`invalid_card`	”Kart bilgilerinizi kontrol edin.”
`15`	Tanınmayan banka	`bank_declined`	Genel red mesajı
`30`	Format hatası	`bank_declined`	Genel red mesajı
`41`	Kart kayıp/çalıntı	`bank_declined`	”Bu kart kullanılamaz.”
`43`	Çalıntı kart	`bank_declined`	”Bu kart kullanılamaz.”
`51`	Yetersiz bakiye	`insufficient_funds`	”Yetersiz bakiye.”
`54`	Kart süresi dolmuş	`card_expired`	”Kartınızın son kullanma tarihi geçmiş.”
`55`	Hatalı PIN	`bank_declined`	”Bilgilerinizi kontrol edin.”
`57`	Kart sahibi bu işlemi yapamaz	`bank_declined`	Genel red mesajı
`58`	Terminal bu işlemi yapamaz	`config_error`	(Konfigürasyon — destek)
`59`	Şüpheli sahtecilik	`fraud_suspected`	”Bankanızla iletişime geçin.”
`61`	Limit aşımı	`limit_exceeded`	”Kart limitiniz yeterli değil.”
`62`	Kısıtlı kart	`bin_restricted`	Genel red mesajı
`63`	Güvenlik ihlali	`fraud_suspected`	(İzleme — destek)
`65`	Aktivite limit aşımı	`limit_exceeded`	”Çok fazla deneme yaptınız, lütfen sonra tekrar deneyin.”
`75`	PIN deneme limiti aşıldı	`bank_declined`	”Bilgilerinizi kontrol edin.”
`82`	Geçersiz CVV	`invalid_cvv`	”Güvenlik kodunuz (CVV) yanlış.”
`91`	Banka sistemi yanıt vermedi	`bank_timeout`	(Smart Retry devreye girer)
`92`	Yönlendirme hatası	`config_error`	(Konfigürasyon — destek)
`96`	Sistem 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.";
}

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Sık karşılaşılan kodlar

Banka-spesifik kodlar

Müşteriye gösterme prensibi

Örnek müşteri mesajı eşleme

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

​Banka-spesifik kodlar

​Müşteriye gösterme prensibi

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

Sık karşılaşılan kodlar

Banka-spesifik kodlar

Müşteriye gösterme prensibi

Örnek müşteri mesajı eşleme