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
POST /api/v1/validation/iban
transfer-admin, transfer-operator veya transfer-viewer rolü.
İstek
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
{
"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:
{
"is_valid": false,
"iban": "TR330006100519786457841327",
"error_code": "checksum_failed",
"error_message": "IBAN checksum'ı geçmiyor — son hane(ler) hatalı olabilir."
}
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) |
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.
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):
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 |
