> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Banka Yanıt Kodları

> Bankaların döndürdüğü ISO 8583 standardı 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 theme={null}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
```

```json theme={null}
{
  "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](https://dashboard.payven.com.tr/connector-error-codes)

## Müşteriye gösterme prensibi

<Check>**Hassas kodları gizleyin.** "Şüpheli sahtecilik" gibi kodlar müşteriye direkt gösterilmemelidir — fraud filterları açık etmenize neden olabilir.</Check>
<Check>**Yönlendirici mesaj verin.** "Reddedildi" yerine "Bankanız işlemi onaylamadı, başka bir kart denemek ister misiniz?"</Check>
<Check>**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.</Check>

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

```javascript theme={null}
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.";
}
```