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

> IBAN formatını doğrulayın ve banka bilgilerini çözümleyin.

IBAN (International Bank Account Number) formatı **mod-97** algoritmasıyla doğrulanır. TR IBAN'larında 5-9. karakterler banka kodu ile eşleşir → banka bilgisi de aynı yanıtta döner.

## Endpoint

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

Bearer access token gerektirir.

## İstek

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

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

## Yanıt

`200 OK` — `IbanValidationResultDto`:

```json theme={null}
{
  "is_valid":       true,
  "checksum_valid": true,
  "format_valid":   true,
  "country_code":   "TR",
  "check_digits":   "32",
  "bank_code":      "00010",
  "formatted_iban": "TR32 0010 0099 9990 1234 5678 90",
  "masked_iban":    "TR32 **** **** **** **** **78 90",
  "bank": {
    "id":            "8e3f5c12-...",
    "code":          "ZIRAAT",
    "name":          "T.C. Ziraat Bankası",
    "bkm_member_id": "10"
  },
  "error_message": null
}
```

| Alan             | Açıklama                                                                     |
| ---------------- | ---------------------------------------------------------------------------- |
| `is_valid`       | Genel geçerlilik (`format_valid && checksum_valid`)                          |
| `checksum_valid` | mod-97 doğrulaması                                                           |
| `format_valid`   | Uzunluk + karakter formatı (TR için 26 hane)                                 |
| `country_code`   | İlk 2 karakter (`TR`)                                                        |
| `check_digits`   | 3-4. hane (mod-97 sonucu)                                                    |
| `bank_code`      | TR IBAN için 5-9. hane (5 haneli banka kodu)                                 |
| `formatted_iban` | İnsan-okur format (4'lü gruplar)                                             |
| `masked_iban`    | Görüntüleme için maskeli format                                              |
| `bank`           | TR IBAN'larında banka kodundan çözümlenmiş banka (yabancı IBAN'larda `null`) |

## Geçersiz örnek

```json theme={null}
{
  "is_valid":       false,
  "checksum_valid": false,
  "format_valid":   true,
  "country_code":   "TR",
  "check_digits":   "33",
  "bank_code":      null,
  "formatted_iban": "TR33 0010 0099 9990 1234 5678 90",
  "masked_iban":    "TR33 **** **** **** **** **78 90",
  "bank":           null,
  "error_message":  "IBAN mod-97 checksum'ı geçmiyor."
}
```

## Tipik kullanım: alıcı hesabı kaydı

Para Transferi entegrasyonunda alıcı hesabı kaydederken IBAN'ı doğrularsınız:

```javascript theme={null}
async function onIbanBlur(iban) {
  const cleaned = iban.replace(/\s/g, "").toUpperCase();

  const res = await fetch("/api/validation/iban", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ iban: cleaned }),
  });
  const result = await res.json();

  if (!result.is_valid) {
    showError(result.error_message);
    return;
  }

  setRecipientBank(result.bank?.name);
  setIbanFormatted(result.formatted_iban);
}
```

## Hata response'ları (HTTP)

`is_valid: false` durumu `200 OK` ile döner — `error_message` alanı sebebi içerir. Aşağıdaki HTTP hataları yalnızca istek formatı hatalı olduğunda döner:

| HTTP  | `code`              | Anlam                       |
| ----- | ------------------- | --------------------------- |
| `400` | `validation_failed` | `iban` alanı eksik veya boş |
| `400` | `bad_request`       | Request body geçersiz JSON  |

## Yabancı IBAN desteği

Format ve checksum doğrulaması ISO 13616 kapsamındaki **tüm ülkeler** için çalışır. Banka çözümlemesi şu an yalnızca **TR IBAN** için aktiftir — diğer ülkelerde `bank: null` döner. Yabancı banka çözümlemesi yol haritasındadır.