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

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

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 parametresiAçıklama
bin_prefixİlk 1-6 hane — bu prefix ile başlayan BIN aralıklarını döner
bank_idBelirli bir bankanın tüm BIN’lerini listele
card_schemevisa, mastercard, troy, amex
card_typecredit, debit, prepaid
page, page_sizeSayfalama (default 1, 50; max 200)

​
Yanıt

{
  "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: 
// 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): 
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: 
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.