Docs/API/BIN Lookup

BIN Lookup

Look up card metadata — brand, issuer, card type, and surchargeability — from a BIN, Tokenizer token, or vaulted customer.

POST /api/lookup/bin/protected

The BIN Lookup endpoint returns card metadata for a given Bank Identification Number — the first six or more digits of the card number. You get back the card brand, issuing bank, card type, and a boolean indicating whether the card is surchargeable in the country and state you supply. This endpoint is server-side only and requires your secret API key.

Use the secret key, not the public one

Send your secret API key in the Authorization header. The public pub_XXXX key is not accepted on this endpoint.

Headers

HeaderRequiredValue
Content-Typerequiredapplication/json
AuthorizationrequiredYour secret API key.

Request body

Send a JSON body. At least one of bin, temp_token, or customer_id must be present. Everything else is optional.

FieldTypeRequiredDescription
binstringone ofCard BIN, digits only, six or more characters (e.g. 424242). Usually the first six digits of the card number.
temp_tokenstringone ofA temporary token returned from Tokenizer. The BIN is pulled from the card behind that token.
customer_idstringone ofVaulted customer ID. The lookup uses the customer's default payment method unless you specify one explicitly.
payment_method_idstringoptionalWhen customer_id is supplied, the specific vault payment method to use. Omit to fall back to the customer's default.
countrystringoptionalTwo-letter country code. Pair with state to get a surchargeability answer.
statestringoptionalState or region code. Pair with country to get a surchargeability answer.

Validation

  • Exactly one of bin, temp_token, or customer_id is enough — you can send one and skip the others.
  • bin: digits only, at least six characters.
  • temp_token: must match the Tokenizer token format.
  • customer_id: must resolve to a valid vaulted customer.

Examples

Lookup by BIN

curl -X POST https://sandbox.fluidpay.com/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.fluidpay.com/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 vaulted customer

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

Response

A successful lookup returns 200 with BIN metadata. If the BIN is not recognized, the endpoint still returns 200 — just with a minimal or empty body.

FieldTypeDescription
binstringThe BIN that was looked up.
card_brandstringBrand (Visa, Mastercard, etc.).
issuing_bankstringIssuing bank or network name.
card_typestringcredit, debit, and so on.
card_level_genericstringCard product tier (standard, premium).
countrystringIssuing country.
is_surchargeablebooleanWhether the card can be surcharged in the country/state you supplied.
payment_method_typestringcard 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. Missing required input, bad BIN format, etc.
  • 401 — Missing or invalid API key.
  • 500 — Server or vault error during the lookup.

How it works

  1. Auth. The request is authenticated using your secret API key; the merchant is derived from the key.
  2. BIN source. The BIN comes from whichever of bin, temp_token, or customer_id you sent. For the latter two, the card record is resolved and its BIN extracted.
  3. Lookup. The BIN is checked against the gateway's BIN database — and, if your merchant has the enhanced lookup enabled, an upstream IBX lookup is attempted as well.
  4. Surcharge answer. If country and state are provided, the response tells you whether the card is surchargeable in that region.
  5. Response. Metadata plus is_surchargeable come back in the response body.

Related