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

# BIN Lookup

> Lookup card network, type, bank, and issuance information from BIN (Bank Identification Number).

## Overview

The BIN Lookup endpoint allows you to retrieve card information by providing the first 8 digits of a card number (BIN). This is useful for identifying card details before processing a payment, enabling you to:

* Determine card network (visa, mastercard, rupay, amex, etc.)
* Identify card type (credit or debit)
* Get bank information
* Check if the card is domestic or international

This endpoint helps you provide better user experience by pre-validating card information and displaying appropriate payment options.

## Use Cases

* **Pre-validation**: Validate card details before submitting payment
* **UI Enhancement**: Show card network logo or bank name as user types
* **Payment Flow Optimization**: Determine payment method eligibility based on card type
* **Fraud Prevention**: Identify potentially suspicious cards before processing

## Request

### Endpoint

```
POST /pg/bin/
```

### Headers

| Header            | Required      | Description                                                    |
| ----------------- | ------------- | -------------------------------------------------------------- |
| `X-Client-ID`     | Yes           | Your Client ID                                                 |
| `X-Client-Secret` | Yes           | Your Client Secret                                             |
| `X-Merchant-ID`   | Conditionally | Required for PSP merchants managing multiple merchant accounts |
| `X-API-Version`   | No            | API version (defaults to latest)                               |
| `Content-Type`    | Yes           | Must be `application/json`                                     |

### Request Body

| Parameter | Type   | Required | Description                              | Constraints             |
| --------- | ------ | -------- | ---------------------------------------- | ----------------------- |
| `bin`     | string | Yes      | BIN code (first 8 digits of card number) | Pattern: `^[0-9]{6,9}$` |

### Example Request

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

## Response

### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "message": "BIN lookup successful",
  "data": {
    "bank": "hdfc bank",
    "network": "visa",
    "card_type": "credit_card",
    "is_domestic": true
  }
}
```

### Response Fields

| Field              | Type    | Description                                                                 |
| ------------------ | ------- | --------------------------------------------------------------------------- |
| `success`          | boolean | Indicates if the request was successful                                     |
| `message`          | string  | Response message                                                            |
| `data`             | object  | BIN lookup data                                                             |
| `data.bank`        | string  | Bank name that issued the card                                              |
| `data.network`     | string  | Card network (visa, mastercard, rupay, amex, diners, maestro, sbi\_maestro) |
| `data.card_type`   | string  | Card type (`credit_card` or `debit_card`)                                   |
| `data.is_domestic` | boolean | Whether the card is domestic (issued in India) or international             |

### Error Responses

#### 400 Bad Request - Invalid BIN

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERR_BIN_001",
    "message": "Validation error",
    "details": {
      "bin": "BIN code must be 8 digits"
    }
  }
}
```

#### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERR_AUTH_000",
    "message": "Missing credentials",
    "details": {
      "authentication": "Missing credentials."
    }
  }
}
```

#### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERR_SERVICE_ERROR_000",
    "message": "Payment gateway error",
    "details": {
      "error": "An unexpected error occurred. Please try again later"
    }
  }
}
```

## Examples

### JavaScript/TypeScript

```javascript theme={null}
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': 'your-client-id',
      'X-Client-Secret': 'your-client-secret'
    },
    body: JSON.stringify({
      bin: binCode
    })
  });

  const data = await response.json();
  
  if (data.success) {
    console.log('Network:', data.data.network);
    console.log('Card Type:', data.data.card_type);
    console.log('Bank:', data.data.bank);
    console.log('Domestic:', data.data.is_domestic);
  } else {
    console.error('Error:', data.error);
  }
  
  return data;
}

// Usage
lookupBIN('41111111');
```

### Python

```python theme={null}
import requests

def lookup_bin(bin_code):
    url = "https://api-pacb-uat.eximpe.com/pg/bin/"
    headers = {
        "Content-Type": "application/json",
        "X-Client-ID": "your-client-id",
        "X-Client-Secret": "your-client-secret"
    }
    payload = {
        "bin": bin_code
    }
    
    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    
    if data.get("success"):
        bin_data = data["data"]
        print(f"Network: {bin_data.get('network')}")
        print(f"Card Type: {bin_data.get('card_type')}")
        print(f"Bank: {bin_data.get('bank')}")
        print(f"Domestic: {bin_data.get('is_domestic')}")
    else:
        print(f"Error: {data.get('error')}")
    
    return data

# Usage
lookup_bin("41111111")
```

## Notes

* BIN code must be 8 digits
* The endpoint returns `null` values for fields that cannot be determined
* Card network values (visa, mastercard, etc.)
* Bank names are returned
* `is_domestic` is `true` for cards issued in India, `false` for international cards


## OpenAPI

````yaml POST /pg/bin/
openapi: 3.0.0
info:
  title: Eximpe Payment Gateway API
  description: >-
    API for payment processing and order management through Eximpe payment
    gateway. This specification includes v1, v2, and v3 API versions.
  license:
    name: Proprietary
  version: 2.0.0
servers:
  - url: https://api-pacb-uat.eximpe.com
    description: Payment Gateway Sandbox URL
security:
  - clientAuth: []
    clientSecretAuth: []
    apiVersionHeader: []
tags:
  - name: Card Tokens
  - name: Merchants
  - name: Orders
  - name: Payment Links
  - name: Payments
  - name: Refunds
  - name: Settlements
  - name: Subscriptions
paths:
  /pg/bin/:
    post:
      tags:
        - Payments
      summary: BIN Lookup
      description: >-
        Lookup card network, type, bank, and issuance information from BIN (Bank
        Identification Number). BIN is typically the first 6-8 digits of a card
        number. This endpoint helps identify card details before processing a
        payment.
      operationId: v1_post_pg_bin_
      requestBody:
        description: BIN lookup request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1_BINLookupRequest'
            example:
              bin: '41111111'
      responses:
        '200':
          description: BIN lookup successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_BINLookupResponse'
              example:
                success: true
                message: BIN lookup successful
                data:
                  bank: hdfc bank
                  network: visa
                  card_type: credit_card
                  is_domestic: true
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              example:
                success: false
                error:
                  code: ERR_BIN_001
                  message: Validation error
                  details:
                    bin: BIN code must be 8 digits
        '401':
          description: Unauthorized - Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              example:
                success: false
                error:
                  code: ERR_AUTH_000
                  message: Missing credentials
                  details:
                    authentication: Missing credentials.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              example:
                success: false
                error:
                  code: ERR_SERVICE_ERROR_000
                  message: Payment gateway error
                  details:
                    error: An unexpected error occurred. Please try again later
      security:
        - clientAuth: []
          clientSecretAuth: []
          merchantAuth: []
          apiVersionHeader: []
components:
  schemas:
    v1_BINLookupRequest:
      type: object
      required:
        - bin
      properties:
        bin:
          type: string
          description: BIN code (first 6-8 digits of card number)
          pattern: ^[0-9]{6,9}$
          example: '41111111'
    v1_BINLookupResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        message:
          type: string
          description: Response message
        data:
          $ref: '#/components/schemas/v1_BINLookupData'
    v1_ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
          description: >-
            Indicates if the request was successful. Always false for error
            responses.
        error:
          $ref: '#/components/schemas/v1_ErrorDetails'
    v1_BINLookupData:
      type: object
      properties:
        bank:
          type: string
          description: Bank name that issued the card
          example: hdfc bank
        network:
          type: string
          description: Card network (visa, mastercard, rupay, amex, diners)
          example: visa
        card_type:
          type: string
          description: Card type (credit_card, debit_card)
          example: credit_card
        is_domestic:
          type: boolean
          description: Whether the card is domestic (issued in India) or international
          example: true
    v1_ErrorDetails:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code (e.g., ERR_ORDER_002)
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Detailed validation error information with field-specific errors
          additionalProperties:
            type: string
            description: Error message for the specific field
  securitySchemes:
    clientAuth:
      type: apiKey
      name: X-Client-ID
      in: header
      description: >-
        **Client Application ID** - Your unique application identifier used to
        authenticate API requests. You can find your Client ID in the Developer
        Settings section of the merchant dashboard.
      x-displayName: Client ID
      x-example: your-client-id
    clientSecretAuth:
      type: apiKey
      name: X-Client-Secret
      in: header
      description: >-
        **Client Secret Key** - Your secret key used alongside the Client ID for
        secure authentication. Keep this confidential and never expose it in
        client-side code. Available in the Developer Settings section of the
        merchant dashboard.
      x-displayName: Client Secret
      x-example: your-client-secret
    apiVersionHeader:
      type: apiKey
      name: X-API-Version
      in: header
      description: >-
        **API Version** - Specifies which version of the API to use (e.g.,
        '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which
        API version your integration uses. Default version information is
        available in the Developer Settings.
      x-displayName: API Version
      x-example: 3.0.0
    merchantAuth:
      type: apiKey
      name: X-Merchant-ID
      in: header
      description: >-
        **Merchant Identifier** - The unique ID for the merchant account. This
        is required for PSP (Payment Service Provider) merchants who manage
        multiple merchant accounts. You can find merchant IDs in the Merchant
        Management section of the dashboard.
      x-displayName: Merchant ID
      x-example: your-merchant-id

````