Skip to main content
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

POST /api/v1/validation/iban
Bearer access token gerektirir.

​
İstek

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" }'
AlanTipZorunlulukAçıklama
ibanstringZorunluBoşluklu veya boşluksuz IBAN — Payven normalize eder

​
Yanıt

200 OK — IbanValidationResultDto: 
{
  "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
}
AlanAçıklama
is_validGenel geçerlilik (format_valid && checksum_valid)
checksum_validmod-97 doğrulaması
format_validUzunluk + karakter formatı (TR için 26 hane)
country_codeİlk 2 karakter (TR)
check_digits3-4. hane (mod-97 sonucu)
bank_codeTR IBAN için 5-9. hane (5 haneli banka kodu)
formatted_ibanİnsan-okur format (4’lü gruplar)
masked_ibanGörüntüleme için maskeli format
bankTR IBAN’larında banka kodundan çözümlenmiş banka (yabancı IBAN’larda null)

​
Geçersiz örnek

{
  "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: 
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:
HTTPcodeAnlam
400validation_failediban alanı eksik veya boş
400bad_requestRequest 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.