Overview

The BIN Lookup API allows you to retrieve detailed information about a payment card based on its Bank Identification Number (BIN). This endpoint provides real-time card metadata including issuer, brand, type, category, and country of origin.

📚 What is a BIN?

Definition

A BIN (Bank Identification Number), also known as IIN (Issuer Identification Number), is the first 4 to 8 digits of a payment card number that identifies:

• Card Brand (Visa, Mastercard, American Express, etc.)
• Issuing Bank (Chase, Bank of America, Santander, etc.)
• Card Type (Credit, Debit, Prepaid)
• Card Category (Classic, Gold, Platinum, Corporate)
• Country of Issue

Structure

Card Number: 4532 1234 5678 9010

┌─────────┬──────────────────┬─────┐
│   BIN   │   Account Number │ CVV │
│ 4532 12 │  34 5678 901     │ 0   │
└─────────┴──────────────────┴─────┘
   ↑
   6 digits (Traditional BIN)
   
Modern cards may use 8-digit BINs:
┌───────────┬────────────────┬─────┐
│    BIN    │ Account Number │ CVV │
│ 4532 1234 │  5678 901      │ 0   │
└───────────┴────────────────┴─────┘
   ↑
   8 digits (Modern BIN)

Common Use Cases

✅ Fraud Prevention - Verify card origin matches customer location
✅ Payment Routing - Route to specific processor based on card type
✅ User Experience - Auto-detect card brand and display appropriate logo
✅ Compliance - Validate card category for business rules
✅ Analytics - Track card usage patterns by issuer/country

🚀 API Endpoint

Request

GET /api/v1/bank/wallet/bin/{card_bin}

Path Parameters

Validation Rules

• Format: Must be 4 to 6 numeric digits
• Pattern: ^[0-9]{4,6}$
• Examples:
  • ✅ 4532 (4 digits - minimum)
  • ✅ 453212 (6 digits - standard)
  • ❌ 123 (too short)
  • ❌ 4532123 (too long)
  • ❌ 45a2 (contains letters)

Headers

Authorization: Bearer {your_access_token}
Content-Type: application/json

Response

Success Response (200 OK)

{
  "bin": "453212",
  "brand": "VISA",
  "type": "CREDIT",
  "category": "CLASSIC",
  "issuer": "BANCO SANTANDER S.A.",
  "code": "BR",
  "country": "BRAZIL"
}

Response Fields

Error Responses

400 Bad Request - Invalid BIN Format

{
  "code": "card_bin_invalid"
}

Causes:

• BIN contains letters or special characters
• BIN is shorter than 4 digits
• BIN is longer than 6 digits

401 Unauthorized

{
  "code": "unauthorized"
}

404 Not Found - BIN Not in Database

{
  "code": "bin_not_found"
}

Note: Our BIN database is regularly updated, but some newer or regional cards may not be included yet.

🌍 Supported Card Brands

🧪 Testing

Test BINs (Sandbox Environment)

Use these test BINs in your development/staging environment:

453212 - VISA Credit 
531234 - Mastercard Debit
374512 - American Express
650432 - Elo Credit
401178 - Elo Debit