# BINLookupAPI Documentation

Complete API documentation for BINLookupAPI - a RESTful API for payment card BIN lookup.

---

## Overview

BINLookupAPI is a RESTful API that provides detailed information about payment card Bank Identification Numbers (BINs). The BIN is the first 4 to 8 digits of a payment card number. Use it to:

- Identify card networks and issuing banks
- Detect card types (credit, debit, prepaid)
- Verify country of issuance
- Enhance fraud prevention
- Improve payment routing

**API Endpoint:**

```
POST https://api.binlookupapi.com/v1/bin
```

**Quick Example:**

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

**Response:**

```json
{
  "data": {
    "bin": "42467101",
    "scheme": "visa",
    "funding": "debit",
    "brand": "VISA",
    "category": "CLASSIC",
    "country": {
      "code": "PL",
      "name": "POLAND"
    },
    "issuer": {
      "name": "ING BANK SLASKI SA",
      "website": null,
      "phone": null
    },
    "currency": "PLN",
    "prepaid": false,
    "commercial": false
  }
}
```

---

## Quickstart

Get from zero to your first BIN lookup in four steps.

### 1. Sign Up

Go to the dashboard and sign in with Google. An organisation is created for you automatically. You'll start on the **Development plan** with unlimited requests and mock responses.

### 2. Create an API Key

Go to **API Keys** and click **Create Key**. Give it an optional name (e.g. "Development") and copy the key when it appears — it's only shown once.

### 3. Make Your First Request

> **Note:** Development accounts return mock responses. The data structure matches production, but values are sample data. Upgrade to a paid plan for real BIN data.

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

A successful response looks like this:

```json
{
  "data": {
    "bin": "42467101",
    "scheme": "visa",
    "funding": "debit",
    "brand": "VISA",
    "category": "CLASSIC",
    "country": {
      "code": "PL",
      "name": "POLAND"
    },
    "issuer": {
      "name": "ING BANK SLASKI SA",
      "website": null,
      "phone": null
    },
    "currency": "PLN",
    "prepaid": false,
    "commercial": false
  }
}
```

### 4. Upgrade for Production Data

When you're ready for real BIN data, navigate to **Billing** and choose a paid plan. Changes take effect immediately.

### Language Guides

Complete integration guides with production-ready code, error handling, and real-world examples:

| Language | Guide |
|----------|-------|
| JavaScript / Node.js | https://binlookupapi.com/blog/javascript-bin-lookup-api-guide/ |
| Python | https://binlookupapi.com/blog/python-bin-lookup-api-guide/ |
| PHP | https://binlookupapi.com/blog/php-bin-lookup-api-guide/ |
| cURL / Bash | https://binlookupapi.com/blog/curl-bin-lookup-api-guide/ |
| Java | https://binlookupapi.com/blog/java-bin-lookup-api-guide/ |
| C# / .NET | https://binlookupapi.com/blog/csharp-bin-lookup-api-guide/ |
| Go | https://binlookupapi.com/blog/go-bin-lookup-api-guide/ |

---

## API Reference

Complete documentation for the BIN Lookup API endpoint.

### Overview

The BIN Lookup API provides card metadata from a Bank Identification Number (BIN) — the first 4 to 8 digits of a payment card number.

**Base URL:** `https://api.binlookupapi.com`

**Endpoint:** `POST /v1/bin`

### Authentication

All requests must include an API key in the `Authorization` header using the Bearer scheme:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are created in the dashboard under **API Keys**. The full key is shown only once at creation — store it securely. You can revoke keys at any time from the same page.

### Making a Request

Send a `POST` request with a JSON body containing the BIN as an integer.

**Request:**

```
POST /v1/bin
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

```json
{
  "number": 42467101
}
```

The `number` field must be an integer between 4 and 8 digits (range: `1000` to `99999999`). Do not pass the full card number.

**cURL Example:**

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

### Response

**Success (200):**

```json
{
  "data": {
    "bin": "42467101",
    "scheme": "visa",
    "funding": "debit",
    "brand": "VISA",
    "category": "CLASSIC",
    "country": {
      "code": "PL",
      "name": "POLAND"
    },
    "issuer": {
      "name": "ING BANK SLASKI SA",
      "website": null,
      "phone": null
    },
    "currency": "PLN",
    "prepaid": false,
    "commercial": false
  }
}
```

Every successful response includes quota headers — see Subscriptions for details.

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `bin` | `string` | The BIN that was looked up |
| `scheme` | `string` | Card network: `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, `diners`, or `unknown` |
| `funding` | `string` | Funding type: `credit`, `debit`, `prepaid`, or `unknown` |
| `brand` | `string \| null` | Card brand or product name (e.g. `"VISA"`, `"PLATINUM"`) |
| `category` | `string \| null` | Card category (e.g. `"CLASSIC"`, `"GOLD"`, `"PLATINUM"`) |
| `country.code` | `string` | ISO 3166-1 alpha-2 country code |
| `country.name` | `string` | Country name |
| `issuer.name` | `string \| null` | Issuing bank name |
| `issuer.website` | `string \| null` | Issuing bank website |
| `issuer.phone` | `string \| null` | Issuing bank phone number |
| `currency` | `string \| null` | ISO 4217 currency code |
| `prepaid` | `boolean` | Whether the card is prepaid |
| `commercial` | `boolean` | Whether the card is a commercial/business card |

### Test Mode

Test mode organisations receive mock BIN data. The following test BINs return specific responses:

| BIN | Scheme | Funding | Country | Notes |
|-----|--------|---------|---------|-------|
| `45839201` | Visa | Credit | Japan | Minimal issuer data |
| `52741836` | Mastercard | Credit | Mauritius | Full issuer data |
| `41928374` | Visa | Credit | Azerbaijan | Commercial card |
| `55012847` | Mastercard | Prepaid | Cameroon | Prepaid card |

All other BINs return the default mock response (Polish Visa debit card).

Test mode has a daily limit of 500 requests. Quota headers are included in all responses.

### Errors

All error responses follow this format:

```json
{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}
```

**Error Codes:**

| Status | Error Code | Description |
|--------|-----------|-------------|
| `400` | `BAD_REQUEST` | Invalid or missing request body. The `number` field must be an integer between 4 and 8 digits. |
| `401` | `UNAUTHORIZED` | Missing, invalid, revoked, or expired API key. |
| `402` | `PAYMENT_REQUIRED` | No active subscription. Subscribe to a plan in the dashboard under **Billing**. |
| `403` | `FORBIDDEN` | API key lacks required permissions. Contact support if you believe this is an error. |
| `404` | `NOT_FOUND` | The requested BIN was not found. |
| `429` | `QUOTA_EXCEEDED` | Daily request quota exceeded. Quota resets at midnight UTC. |
| `502` | `SERVICE_ERROR` | An internal error occurred. Try again later. |

### Quota Headers

Every successful response includes quota headers:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Total daily request allowance for the plan |
| `X-Quota-Remaining` | Requests remaining for the current day |
| `X-Quota-Reset` | Unix timestamp (seconds) when the quota resets |

These same headers are returned on `429` responses when the quota is exceeded, with `X-Quota-Remaining` set to `0`.

**Example headers:**

```
X-Quota-Limit: 10000
X-Quota-Remaining: 7482
X-Quota-Reset: 1706400000
```

### Best Practices

**BIN Length:**
- Use 8 digits when available for better accuracy
- The API supports 4-8 digit lookups
- Longer BINs provide more precise results

**Caching:**
- BIN data changes infrequently — cache results for 24-48 hours
- Implement cache invalidation based on your needs
- Reduces API costs and improves performance

**Error Handling:**
- Check the HTTP status code for errors
- Implement retry logic for 5xx errors
- Handle rate limits gracefully with exponential backoff

---

## Subscriptions

### Plans

**Development (Free):**

Build and test your integration at no cost with mock responses.

| | |
|------|-------|
| Monthly Quota | 15,000 requests |
| Daily Limit | 500/day |
| Data | Mock responses |
| Price | $0/mo |

**Production Plans:**

| SKU | Monthly Quota | Daily Limit | Price |
|-----|--------------|-------------|-------|
| BLAPI-30KPM | 30,000 | 1,000/day | $10/mo |
| BLAPI-150KPM | 150,000 | 5,000/day | $50/mo |
| BLAPI-500KPM | 500,000 | 10,000/day | $100/mo |

All plans are billed monthly.

### Development Plan

The Development plan is designed for building and testing your integration. It provides:

- **15,000 requests/month** (500/day) at no cost
- **Mock responses** — data structure matches production, but values are sample data
- **No credit card required** to get started

When you're ready for production data, upgrade to a paid plan.

### Daily Limits

Each organisation's API usage is tracked per calendar day. The counter resets at **midnight UTC** (start of the next day).

When a request is made, the system counts all requests logged for that organisation since the start of the current UTC day. If the count meets or exceeds the plan's daily limit, the API returns:

```
HTTP 429 Too Many Requests

{
  "error": "QUOTA_EXCEEDED",
  "message": "Daily request quota exceeded"
}
```

### Dashboard

**Billing:**

Go to **Billing** to view your current plan, subscription status, and billing period. From this page you can:

- **Subscribe** to a plan if you don't have one yet
- **Switch plans** — upgrade or downgrade at any time; changes take effect at the next billing cycle
- **Manage billing** — open the customer portal to update payment methods or cancel your subscription

**Usage:**

Go to **Usage** to monitor your API activity. The usage page shows:

- **Total requests**, **failed requests**, **success rate**, and **average response time** for the selected period
- **Request history** — a paginated log of individual API requests
- **Date filtering** — narrow results to a specific date range

---

## API Keys

API keys authenticate your requests to the BIN Lookup API. Each key is scoped to an organisation and passed as a Bearer token in the `Authorization` header.

### Creating a Key

1. Go to **API Keys** in your organisation dashboard.
2. Optionally enter a name (e.g. "Production", "Staging") to help identify the key later.
3. Click **Create Key**.

The full API key is displayed once immediately after creation. Copy it and store it somewhere secure — you won't be able to view it again.

### Using Your Key

Include your API key in the `Authorization` header using the Bearer scheme:

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

### Managing Keys

The API Keys page lists all keys for your organisation. Each entry shows:

| Column | Description |
|--------|-------------|
| **Name** | The label you gave the key, if any |
| **Key** | A prefix of the key (e.g. `blapi_live_abc1...`) for identification |
| **Created** | Date the key was created |
| **Status** | `active`, `revoked`, or `expired` |

The full key is never displayed after creation. Use the prefix to identify which key is which.

### Revoking a Key

To revoke a key, click **Revoke** next to it in the table and confirm the prompt. Revocation is immediate and permanent — the key stops working right away and cannot be reactivated.

If you need to replace a revoked key, create a new one.

### Security Best Practices

- **Copy once, store securely.** The key is shown only at creation. Use a secrets manager or environment variable — not source control.
- **Use separate keys per environment.** Create distinct keys for development, staging, and production so you can revoke one without affecting the others.
- **Revoke unused keys.** If a key is no longer needed, revoke it. There's no cost to creating new ones.
- **Don't share keys.** Each team member or service that needs access should use its own key.

### Error Responses

Invalid or missing authentication will return a 401 error:

```json
{
  "error": "UNAUTHORIZED",
  "message": "Missing, invalid, revoked, or expired API key"
}
```

---

## Contact

- Website: https://binlookupapi.com
- Support: https://binlookupapi.com/contact/
- Sign up: https://app.binlookupapi.com/sign-in