Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.eximpe.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

BIN Lookup allows you to retrieve card information by providing the first 8 digits of a card number. This helps you identify card network, type, bank, and issuance details before processing a payment, enabling better user experience and payment flow optimization.

Card Network Detection

Identify card network (visa, mastercard, rupay, etc.) instantly

Card Type Identification

Determine if the card is credit or debit

Bank Information

Get bank name and domestic/international status

​
Use Cases

  • Pre-validation: Validate card details before submitting payment
  • UI Enhancement: Display card network logo or bank name as user types
  • Payment Flow Optimization: Determine payment method eligibility
  • Fraud Prevention: Identify potentially suspicious cards early

​
Prerequisites

Before you begin, ensure you have:
  • Credentials: Your Client ID and Client Secret
  • API Access: BIN lookup endpoint access enabled for your account
Production Requirement: In production, this feature needs to be enabled for your account to receive BIN lookup values. Please contact support to enable BIN lookup functionality for your production environment.

​
Step 1: Lookup BIN

Send a POST request to /pg/bin/ with the BIN code (first 8 digits of the card number).

​
Request Example

curl -X POST https://api-pacb-uat.eximpe.com/pg/bin/ \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -d '{
    "bin": "41111111"
  }'

​
JavaScript Example

async function lookupBIN(binCode) {
  const response = await fetch('https://api-pacb-uat.eximpe.com/pg/bin/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Client-ID': getConfigValue('CLIENT_ID'),
      'X-Client-Secret': getConfigValue('AUTH_KEY'),
      ...(getConfigValue('IS_PSP') && getConfigValue('MERCHANT_ID') 
        ? { 'X-Merchant-ID': getConfigValue('MERCHANT_ID') } 
        : {})
    },
    body: JSON.stringify({
      bin: binCode
    })
  });

  const data = await response.json();
  
  if (data.success) {
    const binData = data.data;
    console.log('Network:', binData.network);
    console.log('Card Type:', binData.card_type);
    console.log('Bank:', binData.bank);
    console.log('Domestic:', binData.is_domestic);
    return binData;
  } else {
    throw new Error(data.error?.message || 'BIN lookup failed');
  }
}

// Usage: Extract BIN from card number (first 8 digits)
const cardNumber = '4111111111111111';
const bin = cardNumber.substring(0, 8);
lookupBIN(bin);

​
Python Example

import requests

def lookup_bin(bin_code, client_id, client_secret, merchant_id=None):
    url = "https://api-pacb-uat.eximpe.com/pg/bin/"
    headers = {
        "Content-Type": "application/json",
        "X-Client-ID": client_id,
        "X-Client-Secret": client_secret
    }
    
    if merchant_id:
        headers["X-Merchant-ID"] = merchant_id
    
    payload = {"bin": bin_code}
    
    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    
    if data.get("success"):
        return data["data"]
    else:
        raise Exception(data.get("error", {}).get("message", "BIN lookup failed"))

# Usage
bin_code = "41111111"
bin_data = lookup_bin(bin_code, "your-client-id", "your-client-secret")
print(f"Network: {bin_data.get('network')}")
print(f"Card Type: {bin_data.get('card_type')}")

​
Step 2: Handle Response

​
Success Response

{
  "success": true,
  "message": "BIN lookup successful",
  "data": {
    "bank": "hdfc bank",
    "network": "visa",
    "card_type": "credit_card",
    "is_domestic": true
  }
}

​
Response Fields

  • bank: Bank name that issued the card
  • network: Card network - visa, mastercard, rupay, amex, diners, maestro, sbi_maestro
  • card_type: Card type - credit_card or debit_card
  • is_domestic: Boolean indicating if card is issued in India

​
Error Handling

try {
  const binData = await lookupBIN('41111111');
  // Use binData.network, binData.card_type, etc.
} catch (error) {
  if (error.response?.status === 400) {
    console.error('Invalid BIN code');
  } else if (error.response?.status === 401) {
    console.error('Authentication failed');
  } else {
    console.error('BIN lookup failed:', error.message);
  }
}

​
Integration Example: Real-time Card Detection

Here’s a complete example of integrating BIN lookup in a card input form: 
// HTML: <input type="text" id="cardNumber" placeholder="Card Number" />

document.getElementById('cardNumber').addEventListener('input', async function(e) {
  const cardNumber = e.target.value.replace(/\s/g, '');
  
  // Extract BIN (first 8 digits)
  if (cardNumber.length >= 6 && cardNumber.length <= 8) {
    try {
      const binData = await lookupBIN(cardNumber);
      
      // Display card network logo
      if (binData.network) {
        document.getElementById('cardNetwork').src = `/logos/${binData.network.toLowerCase()}.png`;
        document.getElementById('cardNetwork').style.display = 'block';
      }
      
      // Show card type
      if (binData.card_type) {
        document.getElementById('cardType').textContent = 
          binData.card_type === 'credit_card' ? 'Credit Card' : 'Debit Card';
      }
      
      // Display bank name
      if (binData.bank) {
        document.getElementById('bankName').textContent = 
          binData.bank.charAt(0).toUpperCase() + binData.bank.slice(1);
      }
      
      // Show domestic/international indicator
      if (binData.is_domestic !== null) {
        document.getElementById('cardIssuance').textContent = 
          binData.is_domestic ? 'Domestic Card' : 'International Card';
      }
      
    } catch (error) {
      // Hide card info on error
      document.getElementById('cardNetwork').style.display = 'none';
      document.getElementById('cardType').textContent = '';
      document.getElementById('bankName').textContent = '';
    }
  }
});

​
Best Practices

  1. Debounce Requests: Wait for user to stop typing before making BIN lookup requests
  2. Cache Results: Cache BIN lookup results to reduce API calls
  3. Handle Errors Gracefully: Don’t block payment flow if BIN lookup fails
  4. Validate BIN Format: Ensure BIN is 8 digits before making request
  5. Show Loading State: Display loading indicator during lookup

​
Error Codes

Error CodeDescriptionSolution
ERR_BIN_001Invalid BIN formatEnsure BIN is 8 digits
ERR_AUTH_000Missing credentialsCheck Client ID and Secret
ERR_SERVICE_ERROR_000Service unavailableRetry after a few seconds