> ## 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.

# IBAN Doğrulama

> Transfer oluşturmadan önce IBAN'ın geçerliliğini ve banka bilgisini doğrulayın.

IBAN doğrulama, kullanıcı UI'da girilen IBAN'ı **transfer oluşturmadan önce** kontrol etmek için kullanılır. Geçersiz IBAN, hangi bankaya ait olduğu, beklenen alıcı bilgileri gibi sorulara cevap verir. Transfer akışında **opsiyonel** bir adımdır; transfer oluştururken zaten otomatik doğrulama yapılır, ancak proaktif kullanıcı geri bildirimi için bu endpoint UX'i iyileştirir.

## Endpoint

```http theme={null}
POST /api/v1/validation/iban
```

**Yetki:** `transfer-admin`, `transfer-operator` veya `transfer-viewer` rolü.

## İstek

```bash theme={null}
curl -X POST https://transfer.payven.com.tr/api/v1/validation/iban \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "TR330006100519786457841326"
  }'
```

| Alan   | Tip    | Zorunluluk | Açıklama                                             |
| ------ | ------ | ---------- | ---------------------------------------------------- |
| `iban` | string | Zorunlu    | Boşluksuz veya boşluklu IBAN — Payven normalize eder |

## Başarılı response

```json theme={null}
{
  "is_valid":         true,
  "iban":             "TR330006100519786457841326",
  "iban_formatted":   "TR33 0006 1005 1978 6457 8413 26",
  "iban_masked":      "TR33 **** **** **** **** 1326",

  "country_code":     "TR",
  "bank_id":          "bank-garanti-uuid",
  "bank_code":        "GARANTI",
  "bank_name":        "Garanti BBVA",
  "bank_swift":       "TGBATRIS",

  "branch_code":      "00006",
  "account_number":   "1978645784",

  "supported_transfer_types": ["fast", "eft", "remittance"]
}
```

| Alan                                              | Açıklama                                                           |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| `is_valid`                                        | IBAN checksum'ı geçti mi?                                          |
| `iban_formatted`                                  | 4'lü gruplama ile gösterilebilir hâl (UI için)                     |
| `iban_masked`                                     | İlk 4 + son 4 hane görünen, ortası maskeli (loglar için)           |
| `country_code`                                    | ISO ülke kodu — `TR` dışındaki IBAN'larda Payven kabul etmeyebilir |
| `bank_id`, `bank_code`, `bank_name`, `bank_swift` | IBAN'ın 5-6. hanelerinden çözülen banka bilgisi                    |
| `branch_code`, `account_number`                   | Banka ve hesap kısımları (raporlama için)                          |
| `supported_transfer_types`                        | Bu IBAN'a hangi transfer tipleriyle gönderim yapılabileceği        |

## Geçersiz IBAN

Yanıt yine `200 OK` döner; `is_valid: false` ile birlikte sebep:

```json theme={null}
{
  "is_valid":      false,
  "iban":          "TR330006100519786457841327",
  "error_code":    "checksum_failed",
  "error_message": "IBAN checksum'ı geçmiyor — son hane(ler) hatalı olabilir."
}
```

Olası `error_code` değerleri:

| Kod                   | Anlam                                                |
| --------------------- | ---------------------------------------------------- |
| `invalid_format`      | Format hatası (uzunluk, karakter)                    |
| `unsupported_country` | TR dışı IBAN, Payven kabul etmiyor                   |
| `checksum_failed`     | Mod-97 checksum doğrulaması başarısız                |
| `bank_not_found`      | IBAN sentaks doğru ama banka kataloğunda yok (nadir) |

<Note>
  Endpoint **`200 OK`** ile döner; `is_valid` alanını kontrol edin. Bu, "doğrulama başarısız" durumunu ayrı bir HTTP hata kodu olarak göstermez — UX akışında "kullanıcı yanlış girdi" sıradan bir durumdur, hata değildir.
</Note>

## UI entegrasyonu — debounce

IBAN alanına yazılırken her karakter için doğrulama atmayın; debounce uygulayın (örn. 500ms beklemeli, IBAN tam yazıldıktan sonra):

```javascript theme={null}
let debounceTimer;
ibanInput.addEventListener("input", (e) => {
  clearTimeout(debounceTimer);
  const iban = e.target.value.replace(/\s+/g, "");
  if (iban.length < 26) {
    setBankBadge(null);
    return;
  }
  debounceTimer = setTimeout(async () => {
    const res = await fetch("/api/payven/validate-iban", {
      method: "POST",
      body: JSON.stringify({ iban }),
    });
    const result = await res.json();
    if (result.is_valid) {
      setBankBadge(result.bank_name, result.bank_logo_url);
    } else {
      setError(result.error_message);
    }
  }, 500);
});
```

## Hata response'ları

Burada listelenen `4xx` hataları **endpoint kullanımı** ile ilgilidir; IBAN doğrulama mantıksal sonucu için yukarıdaki `is_valid` alanına bakın.

| HTTP  | `code`                | Anlam                                           |
| ----- | --------------------- | ----------------------------------------------- |
| `400` | `validation_failed`   | `iban` alanı eksik                              |
| `403` | `forbidden`           | Yetki yok                                       |
| `429` | `rate_limit_exceeded` | Çok fazla doğrulama isteği — debounce uygulayın |