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

# BIN Sorgulama

> Kart numarasının ilk 6 hanesinden banka, kart birliği ve tipi öğrenin.

**BIN** (Bank Identification Number), kart numarasının ilk 6 hanesidir. Bu sayılar bankayı, kart birliğini (Visa, Mastercard, Troy) ve kart tipini (kredi / banka / prepaid) tanımlar.

Identity servisi tüm Türk bankalarının BIN aralıklarını içerir. Checkout sırasında müşteriye dinamik olarak banka logosu, taksit seçenekleri ve kart kampanyaları göstermek için kullanılır.

## Endpoint'ler

```http theme={null}
GET    /api/v1/lookups/bank-bins                 # Liste (sayfalı)
GET    /api/v1/lookups/bank-bins/{id}            # Tek BIN aralığı
POST   /api/v1/lookups/bank-bins                 # Yeni BIN aralığı (admin)
PUT    /api/v1/lookups/bank-bins/{id}            # Güncelleme (admin)
DELETE /api/v1/lookups/bank-bins/{id}            # Silme (admin)
POST   /api/v1/lookups/bank-bins/import          # Toplu import (admin)
```

Bearer access token gerektirir. CRUD operasyonları `tenant-admin` veya `platform-admin` rolü gerektirir.

## Liste / arama

```bash theme={null}
curl "https://identity.payven.com.tr/api/v1/lookups/bank-bins?bin_prefix=454671&page=1&page_size=20" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

| Query parametresi   | Açıklama                                                     |
| ------------------- | ------------------------------------------------------------ |
| `bin_prefix`        | İlk 1-6 hane — bu prefix ile başlayan BIN aralıklarını döner |
| `bank_id`           | Belirli bir bankanın tüm BIN'lerini listele                  |
| `card_scheme`       | `visa`, `mastercard`, `troy`, `amex`                         |
| `card_type`         | `credit`, `debit`, `prepaid`                                 |
| `page`, `page_size` | Sayfalama (default `1`, `50`; max `200`)                     |

## Yanıt

```json theme={null}
{
  "items": [
    {
      "id":           "abc-...",
      "bin_start":    "454671",
      "bin_end":      "454671",
      "bank_id":      "8e3f5c12-...",
      "bank_code":    "GARANTI",
      "bank_name":    "Garanti BBVA",
      "card_scheme":  "visa",
      "card_type":    "credit",
      "card_program": "bonus",
      "country":      "TR",
      "is_commercial": false,
      "is_active":    true
    }
  ],
  "page":              1,
  "total_pages":       1,
  "total_count":       1,
  "has_previous_page": false,
  "has_next_page":     false
}
```

## Tipik kullanım: dinamik checkout

Müşteri kart numarası alanına yazarken, ilk 6 hane tamamlandığında tetikleyin:

```javascript theme={null}
// Frontend
async function onCardNumberChange(value) {
  const digits = value.replace(/\D/g, "");
  if (digits.length < 6) return;
  const prefix = digits.slice(0, 6);

  // Kendi backend'iniz üzerinden çağırın — frontend'den Identity'e direkt token taşımayın
  const response = await fetch(`/api/bin/${prefix}`);
  const card = await response.json();
  if (card) {
    showBankLogo(card.bank_code);
    loadInstallmentOptions(prefix, currentAmount);
  }
}
```

Backend (BFF):

```javascript theme={null}
app.get("/api/bin/:bin", authenticate, async (req, res) => {
  const lookup = await fetch(
    `${IDENTITY_BASE}/api/v1/lookups/bank-bins?bin_prefix=${req.params.bin}&page_size=1`,
    { headers: { Authorization: `Bearer ${await getServiceToken()}` } },
  );
  const data = await lookup.json();
  res.json(data.items[0] ?? null);
});
```

## Toplu import (admin)

Organizasyon yöneticisi yeni BIN aralıklarını toplu olarak yükleyebilir:

```bash theme={null}
curl -X POST https://identity.payven.com.tr/api/v1/lookups/bank-bins/import \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "bin_start": "454671", "bin_end": "454671", "bank_code": "GARANTI", "card_scheme": "visa", "card_type": "credit", "card_program": "bonus" },
      { "bin_start": "540063", "bin_end": "540063", "bank_code": "AKBANK",  "card_scheme": "mastercard", "card_type": "credit", "card_program": "axess" }
    ]
  }'
```

Yanıtta her satır için durum (`inserted`, `updated`, `skipped_duplicate`, `error`) raporlanır.

## Caching

BIN tablosu nadiren değişir — istemcinizde **24 saatlik** cache önerilir.