BIN Lookup

The BIN Lookup endpoint returns card metadata for a given Bank Identification Number (BIN)—the first 6+ digits of a card number. You get card brand, issuing bank, card type, and whether the card is surchargeable in a given region. This endpoint is for authenticated API use only: you must send your secret (private) API key in the Authorization header.

---

Endpoint

POST /api/lookup/bin/protected

Authentication
Requires your secret API key. Do not use the public key (pub_XXXX) here.

Headers

Header	Required	Description
Content-Type	Yes	application/json
Authorization	Yes	Your secret API key (private key).

---

Request body

Send a JSON body. You must provide at least one of: bin, temp_token, or customer_id. All other fields are optional.

Field	Type	Required	Description
bin	string	One of bin / temp_token / customer_id	Card BIN: 6 or more digits (digits only). Typically the first 6 digits of the card number.
temp_token	string	One of bin / temp_token / customer_id	A temporary token from Tokenizer. The BIN is derived from the tokenized card.
customer_id	string	One of bin / temp_token / customer_id	Customer vault ID. Lookup uses the customer's default payment method, or the card specified by payment_method_id.
payment_method_id	string	No	When customer_id is set, the specific vault payment method (card) ID to use. If omitted, the customer's default payment method is used.
country	string	No	Two-letter country code. Used with state for surchargeability.
state	string	No	State/region code (e.g. US state). Used with country for surchargeability.

Validation

• At least one of bin, temp_token, or customer_id must be present.
• bin: digits only, 6 or more characters (e.g. 424242).
• temp_token: must match the gateway's token format.
• customer_id: must be a valid vault/customer ID.

---

Example request

Lookup by BIN

curl -X POST { https://sandbox.koipay.io }/api/lookup/bin/protected \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_SECRET_API_KEY" \
  -d '{
    "bin": "424242",
    "country": "US",
    "state": "IL"
  }'

Lookup by Tokenizer token

curl -X POST { https://sandbox.koipay.io }/api/lookup/bin/protected \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_SECRET_API_KEY" \
  -d '{
    "temp_token": "token_from_tokenizer_submission",
    "country": "US",
    "state": "IL"
  }'

Lookup by customer vault

curl -X POST { https://sandbox.koipay.io }/api/lookup/bin/protected \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_SECRET_API_KEY" \
  -d '{
    "customer_id": "btfgqeia1g3tt4mhd5f0",
    "payment_method_id": "btfgqeia1g3tt4mhd5eg"
  }'

---

Response

Success (200)
Returns an object with BIN metadata. If the BIN is not recognized, the API still returns 200 with an empty or minimal response.

Field	Type	Description
bin	string	BIN that was looked up.
card_brand	string	Card brand (e.g. Visa, Mastercard).
issuing_bank	string	Issuing bank or network.
card_type	string	Card type (e.g. credit, debit).
card_level_generic	string	Card product level (e.g. standard, premium).
country	string	Issuing country.
is_surchargeable	boolean	Whether the card can be surcharged in the given country/state.
payment_method_type	string	e.g. card or ach.

Example response

{
  "bin": "424242",
  "card_brand": "Visa",
  "issuing_bank": "Example Bank",
  "card_type": "credit",
  "card_level_generic": "standard",
  "country": "US",
  "is_surchargeable": true,
  "payment_method_type": "card"
}

Error responses

• 400 — Validation error (e.g. missing bin/temp_token/customer_id, invalid format).
• 401 — Unauthorized (missing or invalid API key).
• 500 — Server error (e.g. lookup or vault error).

---

How it works

1. Auth — The request is authenticated with your secret API key. The merchant is determined from that key.
2. BIN source — The BIN is taken from: the bin field, or from the card behind temp_token, or from the vault card for customer_id (and optional payment_method_id).
3. Lookup — The BIN is looked up in the gateway's BIN database (and, if enabled for your merchant, enhanced/IBX lookup).
4. Surcharge — When country and state are provided, the response includes whether the card is surchargeable in that region.
5. Response — Card metadata and is_surchargeable are returned in the response body.

---

Related

• Tokenizer — Use Tokenizer to get a temp_token you can pass to this endpoint.
• 3D Secure (3DS) with Tokenizer — Optional 3DS flow after tokenization.