Skip to main content
Bu endpoint, kart numarasının Luhn algoritması + uzunluk kontrolü yapar ve aynı zamanda BIN’den banka/kart bilgilerini çözümler. Tek istek, iki iş.

Endpoint

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

İstek

curl -X POST https://identity.payven.com.tr/api/v1/validation/card \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "number": "4546711234567894" }'
AlanTipZorunlulukAçıklama
numberstringZorunluTam kart numarası (boşluksuz, 13-19 hane). Bu değer saklanmaz.

Yanıt

200 OKCardValidationResultDto:
{
  "is_valid":     true,
  "luhn_valid":   true,
  "length_valid": true,
  "length":       16,
  "bin":          "454671",
  "masked_number":"454671******7894",
  "schema_type":  "visa",
  "bank_bin": {
    "id":           "abc-...",
    "bin_start":    "454671",
    "bin_end":      "454671",
    "card_scheme":  "visa",
    "card_type":    "credit",
    "card_program": "bonus",
    "country":      "TR"
  },
  "bank": {
    "id":            "8e3f5c12-...",
    "code":          "GARANTI",
    "name":          "Garanti BBVA",
    "bkm_member_id": "62"
  },
  "error_message": null
}
AlanAçıklama
is_validGenel geçerlilik (luhn_valid && length_valid)
luhn_validLuhn checksum geçerli mi
length_validUzunluk kart birliğine uygun mu
binİlk 6 hane
masked_numberBIN******SON4 formatı — loglarda saklanabilir
schema_typevisa, mastercard, troy, amex, vb.
bank_binBIN aralığı + program bilgisi
bankBIN’den çözümlenen banka
error_messageis_valid: false ise sebep
Kart numarası bu istekte saklanmaz ve sunucu loglarına yazılmaz. Yine de PCI-DSS kuralları gereği kart numarasını yalnızca güvenli kanal (TLS) üzerinden iletin ve sızıntıya neden olabilecek loglara (ör. APM trace) yazmaktan kaçının.

Geçersiz kart örnegi

{
  "is_valid":     false,
  "luhn_valid":   false,
  "length_valid": true,
  "length":       16,
  "bin":          "454671",
  "masked_number":"454671******7895",
  "schema_type":  "visa",
  "bank_bin":     null,
  "bank":         null,
  "error_message":"Kart numarası Luhn checksum'ı geçmiyor."
}

Tipik kullanım: inline form validasyonu

async function validateCardOnBlur(cardNumber) {
  const digits = cardNumber.replace(/\D/g, "");
  if (digits.length < 13) return;

  // Backend BFF üzerinden — frontend Identity'e direkt token taşımayın
  const res = await fetch("/api/validation/card", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ number: digits }),
  });
  const result = await res.json();

  if (!result.is_valid) {
    showFieldError("card_number", result.error_message);
    return;
  }

  showBankLogo(result.bank?.code);
  showSchemeIcon(result.schema_type);
  if (result.bank_bin?.card_type === "debit") {
    hideInstallmentDropdown();
  }
}

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_failednumber alanı eksik veya boş
400bad_requestRequest body geçersiz JSON