# Add BIN lookup to your app

> Add BIN lookup with ScreenlyyID: the instance call, the request, the response fields, the decision rule, working Node, Python and Next.js code, and a checklist.

Canonical URL: https://www.screenlyyid.com/docs/guides/bin-lookup/

## Summary

BIN lookup takes the first 6 to 10 digits of a payment card number and returns the card's brand, type, issuing country, issuer and whether it is prepaid or commercial. Use it before or during checkout to catch cards that do not match your customer, your region or your risk rules.

## When to use it / when not to

**Use it for:**

- a card payment at checkout, to check card type, issuing country and prepaid status before you authorise it
- you want to compare the card's country with the customer's IP address (send `CustomerIpAddress`)

**Do not use it for:**

- You want to verify the cardholder's identity: use [Identity verification](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/).
- You want to check an email, phone or IP: see [Email](https://www.screenlyyid.com/docs/guides/email-validation/), [Phone](https://www.screenlyyid.com/docs/guides/phone-validation/) and [Device and IP](https://www.screenlyyid.com/docs/guides/device-ip-intelligence/).
- Never send a full card number. Send only the first 6 to 10 digits (8 or more digits gives the most accurate result).

## Before you start

- **API key:** read it from the environment variable `SCREENLYYID_API_KEY` on your **server only**. Use a `test_` key for the sandbox and a `prod_` key for live. Never put it in browser or mobile code. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key).
- **Base URL:** `https://api.screenlyyid.com`. HTTPS only.
- **Activation and plan:** The first BIN lookups are free; after that BIN lookups need a BIN check pack or a plan allowance (see [Pricing](https://www.screenlyyid.com/pricing/)). The API answers `402` when the free allowance or the credits are used up and `429` when a daily cap is reached.
- **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`bin`) in `CustomerIntelligence`. It returns a `CorrelationId` that you send as `x-correlation-id` on the product call, along with `x-api-key`. A product call can be accepted only **once per correlation id**: repeating it with the same id can return `409 duplicate_correlation_id`. Create a new instance for each check (for example one per checkout or per sign-up).

```bash
curl --request POST --url 'https://api.screenlyyid.com/api/v1/instance/create' \
  --header "x-api-key: $SCREENLYYID_API_KEY" --header 'Content-Type: application/json' \
  --data '{"GlobalScreening": [], "CustomerIntelligence": ["bin"]}'
# { "CorrelationId": "...", "webEnrolmentUrl": "..." }   (webEnrolmentUrl is only used by the hosted identity verification flow)
```

## Use it on its own or stacked

This product can be called on its own (one instance with just `bin`, as above) or stacked with other products for the same customer: list several product codes in the one instance call and send the same `CorrelationId` on each product's call. See [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/). Example pairing: BIN + email + IP at checkout (`CustomerIntelligence`: `["bin", "emv", "ipv"]`).

Document and selfie identity verification is **not** part of this product. It only goes through the Instance API and the hosted capture page: see [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) and [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/). Do not use the direct identity verification endpoints.

## Implementation steps

1. **Create the instance** in your server code, right before the check. Keep the `CorrelationId` with your own record (the user, the order). Do this on the server.
2. **Call the endpoint** `POST /api/v1/bin-lookup` with `x-api-key`, `x-correlation-id` and a JSON body (next section). In a typical app this is the checkout route, before you authorise payment.
3. **Read the response** and apply the [decision logic](https://www.screenlyyid.com/docs/guides/bin-lookup/#decision-logic): the fields marked ★ are the ones to base a decision on.
4. **Act on the result:** accept, ask the customer to correct their input, flag for review, or block. Store the `CorrelationId` and the outcome: it is your audit trail, and the same id shows the check in the dashboard.
5. **Handle failures** (below) so a provider outage never breaks your flow.

## Request and response

### Request
```json
{
  "BinNumber": "45717360",
  "CustomerIpAddress": "203.0.113.7"
}
```

| Field | Type | Meaning | Example |
|---|---|---|---|
| `BinNumber` | string | The first 6, 8 or 10 digits of the card number. Required. | 45717360 |
| `CustomerIpAddress` | string | The customer's IP address. Optional. When sent, the `Ip*` fields and `IpMatchesBin` are filled in. | 203.0.113.7 |

### Response
```json
{
  "BinNumber": "45717360",
  "CardBrand": "VISA/DANKORT",
  "CardCategory": "DANKORT",
  "CardType": "DEBIT",
  "Country": "DENMARK",
  "CountryCode": "DK",
  "CountryCode3": "DNK",
  "CurrencyCode": "DKK",
  "IpBlocklisted": null,
  "IpCity": "",
  "IpCountry": "",
  "IpCountryCode": "",
  "IpCountryCode3": "",
  "IpMatchesBin": false,
  "IpRegion": "",
  "IsCommercial": false,
  "IsPrepaid": false,
  "Issuer": "JYSKE BANK A/S",
  "IssuerPhone": "",
  "IssuerWebsite": null,
  "Valid": true
}
```

| Field | Type | Meaning | Example |
|---|---|---|---|
| `Valid` | boolean | ★ `false` when the BIN is not recognised (all other fields are empty). | true |
| `CardType` | string | ★ `DEBIT`, `CREDIT` and so on. | DEBIT |
| `CardBrand` | string | Card scheme. | VISA/DANKORT |
| `CardCategory` | string | Card category. | DANKORT |
| `IsPrepaid` | boolean | ★ `true` for prepaid cards. | false |
| `IsCommercial` | boolean | ★ `true` for commercial or corporate cards. | false |
| `CountryCode` | string | ★ Issuing country, ISO 3166 alpha-2. Compare with the billing country. | DK |
| `Issuer` | string | Issuing bank. | JYSKE BANK A/S |
| `IpMatchesBin` | boolean | ★ Only meaningful when you sent `CustomerIpAddress`: whether the IP's country matches the card's. | false |
| `IpBlocklisted` | boolean or null | Whether the IP is on a blocklist. `null` when not checked. | null |

★ = base your decision on this field.

## Decision logic

1. `Valid` is `false`: ask for another card. The BIN does not exist.
2. `IsPrepaid` is `true`: flag for review, or apply your prepaid policy.
3. `CountryCode` differs from the billing country: flag for review.
4. You sent `CustomerIpAddress` and `IpMatchesBin` is `false`: flag for review.
5. Otherwise accept.

`IpMatchesBin` `false` is a risk signal, not proof of fraud: travellers and VPN users trigger it.

```javascript
function binDecision(bin) {
  if (!bin.Valid) return { action: "reject", reason: "unknown_bin" };
  const flags = [];
  if (bin.IsPrepaid) flags.push("prepaid");
  if (bin.CountryCode !== billingCountryCode) flags.push("country_mismatch");
  if (customerIp && !bin.IpMatchesBin) flags.push("ip_country_mismatch");
  return flags.length ? { action: "review", reason: flags } : { action: "accept" };
}
```

## Errors and limits

| Status | When | Body |
|---|---|---|
| `400` | A required field is missing or the body is not valid JSON | A problem-details object: `{"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}}` |
| `401` | `x-api-key` is missing or malformed, or the product is not activated on the account | Empty body with a `WWW-Authenticate` header |
| `409` | The same `x-correlation-id` was already used for this product | `{"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."}` |
| `500` | The upstream data provider failed | `{"error": "internal_error", "message": "An unexpected error occurred"}` |
| `402` | `bin_free_allowance_used` or `bin_credits_exhausted` | `{"error": "bin_free_allowance_used", "message": "You have used your free BIN lookups. Buy a BIN check pack to keep going."}`. Buy a BIN check pack or wait for the allowance to renew. |
| `429` | `bin_daily_cap_reached` | `{"error": "bin_daily_cap_reached", ...}` with a `Retry-After` header (seconds until 00:00 UTC). |

There is no documented per-minute rate limit for BIN lookup. There is a daily cap per account that resets at 00:00 UTC. Use a 15 second timeout and do not retry `4xx` responses. Retry a `500` or a timeout at most once.

## Code

Minimal working server-side code. It creates the instance, makes the call with a timeout and throws on a non-`2xx` response with the status and error body attached. The key is read from `SCREENLYYID_API_KEY`.

### JavaScript (Node 18+, fetch)
```javascript
// server only: this reads your API key. Node 18 or later, no dependencies.
const API = "https://api.screenlyyid.com";
const apiKey = process.env.SCREENLYYID_API_KEY; // test_ while building, prod_ in production
if (!apiKey) throw new Error("SCREENLYYID_API_KEY is not set");

// Step 1: one instance per check. It lists this product's code and returns the CorrelationId.
export async function createInstance() {
  const r = await fetch(`${API}/api/v1/instance/create`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({ GlobalScreening: [], CustomerIntelligence: ["bin"] }),
  });
  if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`);
  const { CorrelationId } = await r.json(); // spelled exactly like this
  return CorrelationId;
}

// Step 2: BIN lookup takes the first 6 to 10 digits of a payment card number and returns the card's brand, type, issuing country, issuer and whether it is prepaid or commercial
export async function binLookup(binNumber, customerIp) {
  const correlationId = await createInstance();
  const r = await fetch(`${API}/api/v1/bin-lookup`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" },
    body: JSON.stringify({ BinNumber: binNumber, ...(customerIp && { CustomerIpAddress: customerIp }) }),
    signal: AbortSignal.timeout(15000),
  });
  if (!r.ok) {
    const error = new Error(`/bin-lookup failed (HTTP ${r.status})`);
    error.status = r.status;
    error.body = await r.json().catch(() => null);
    throw error;
  }
  return { correlationId, result: await r.json() };
}
```

### Python (requests)
```python
# server only: this reads your API key. Python 3.9 or later, pip install requests
import os
import requests

API = "https://api.screenlyyid.com"
API_KEY = os.environ["SCREENLYYID_API_KEY"]  # test_ while building, prod_ in production


def create_instance():
    """Step 1: one instance per check. It lists this product's code and returns the CorrelationId."""
    r = requests.post(
        f"{API}/api/v1/instance/create",
        headers={"x-api-key": API_KEY},
        json={"GlobalScreening": [], "CustomerIntelligence": ["bin"]},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["CorrelationId"]  # spelled exactly like this


def bin_lookup(bin_number, customer_ip=None):
    """Step 2: BIN lookup takes the first 6 to 10 digits of a payment card number and returns the card's brand, type, issuing country, issuer and whether it is prepaid or commercial"""
    correlation_id = create_instance()
    r = requests.post(
        f"{API}/api/v1/bin-lookup",
        headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id},
        json={"BinNumber": bin_number, **({"CustomerIpAddress": customer_ip} if customer_ip else {})},
        timeout=15,
    )
    r.raise_for_status()  # a requests.HTTPError carries r.status_code and r.json() for the error body
    return correlation_id, r.json()
```

### Next.js route handler
```javascript
// app/api/binLookup/route.js (Next.js App Router). The key is read on the server only.
import { binLookup } from "@/lib/screenlyyid";

export const dynamic = "force-dynamic";

export async function POST(request) {
  const input = await request.json();
  try {
    const { result } = await binLookup(input);
    return Response.json(result); // send the browser only what it needs, never the API key or the CorrelationId
  } catch (e) {
    // a provider outage or timeout must not break your own flow: decide fail-open or fail-closed here
    return Response.json({ error: "check_unavailable", status: e.status ?? null }, { status: 502 });
  }
}
```

## Test it

The sandbox runs real lookups, so there are no special test BINs: use the public example BINs below. Free BIN lookups are limited: once they are used the API answers `402 bin_free_allowance_used`.

| Input | Expected result |
|---|---|
| 45717360 | Valid `true`, `CardType` `DEBIT`, `CountryCode` `DK`, `IsPrepaid` `false`, `Issuer` `JYSKE BANK A/S`. |
| 411111 | Valid `true`, `CardBrand` `VISA`, `CountryCode` `PL`, `CardType` `DEBIT`. |
| 000000 | `200` with `Valid` `false` and empty strings: an unknown BIN is not an HTTP error. |

## Done when

- [ ] The API key is read only on the server, from `SCREENLYYID_API_KEY`, and a `test_` key is used while building
- [ ] A new instance is created for each lookup and its `CorrelationId` is sent as `x-correlation-id`
- [ ] Only the first 6 to 10 digits of the card are sent, never the full number
- [ ] `Valid: false` asks the customer for another card, and a prepaid or country-mismatch result is flagged for review
- [ ] `402`, `429`, timeouts and `5xx` do not break checkout (a defined fail-open or fail-closed rule applies)
- [ ] A test call with `45717360` returns `200` with `CountryCode` `DK`

## Related

- [BIN lookup (API reference)](https://www.screenlyyid.com/docs/api-reference/bin-lookup/)
- [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/)
- [Free BIN checker](https://www.screenlyyid.com/bin-checker/)
- [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/)
