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

# Kart Doğrulama

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

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

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

Bearer access token gerektirir.

## İstek

```bash theme={null}
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" }'
```

| Alan     | Tip    | Zorunluluk | Açıklama                                                           |
| -------- | ------ | ---------- | ------------------------------------------------------------------ |
| `number` | string | Zorunlu    | Tam kart numarası (boşluksuz, 13-19 hane). Bu değer **saklanmaz**. |

## Yanıt

`200 OK` — `CardValidationResultDto`:

```json theme={null}
{
  "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
}
```

| Alan            | Açıklama                                        |
| --------------- | ----------------------------------------------- |
| `is_valid`      | Genel geçerlilik (`luhn_valid && length_valid`) |
| `luhn_valid`    | Luhn checksum geçerli mi                        |
| `length_valid`  | Uzunluk kart birliğine uygun mu                 |
| `bin`           | İlk 6 hane                                      |
| `masked_number` | `BIN******SON4` formatı — loglarda saklanabilir |
| `schema_type`   | `visa`, `mastercard`, `troy`, `amex`, vb.       |
| `bank_bin`      | BIN aralığı + program bilgisi                   |
| `bank`          | BIN'den çözümlenen banka                        |
| `error_message` | `is_valid: false` ise sebep                     |

<Warning>
  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.
</Warning>

## Geçersiz kart örnegi

```json theme={null}
{
  "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

```javascript theme={null}
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:

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