Reference Data

All card schemes publish account range information which helps understand the product, issuer country code, issuer name etc. Hence, merchants can request account range data under a particular PAN thereby enabling business logic such as:

Merchants query for BIN info using the PAN to get information about card type so that they can surcharge if the card used is commercial / credit or other cases.
Merchants would like to know the brand and product information to run discounts and offers on the website. The cart amount will be dynamically updated to reflect the discounted price.
Merchants query on the card details like country code to run some risk level checks at their side without depending on the acquirer. Merchants may not want to accept cards issued in a certain country, because sending this to the acquirer may cost them additional charges (gateway fee / authorization fee, etc.).

Endpoints

GET /api/v1/pa/reference/bin/lookup

Retrieve BIN info

GET /api/v1/pa/reference/bin/lookup

Copy for LLMView as Markdown

Retrieve BIN info using the PAN passed via header param called x-pan.

Response body - 200 OK - Multiple values

card_brandstring

One of visa, mastercard, union pay, american express

card_typestring

Visa: One of credit, debit, prepaid, charge, deferred_debit, not_applicable.
Mastercard: One of debit, prepaid, credit, non_mastercard.
Union Pay: One of debit, prepaid, credit.
American Express: One of consumer, corporate, small_business, debit, prepaid, prepaid_reloadable.

commercial_cardboolean

A boolean field referring whether the card is commercial or not

issuer_country_codestring

Issuer country code

issuer_namestring

Issuer name

product_codestring

Visa: it is Product ID description. For more details please refer to base-ii-clearing-data-codes Product ID Values section.
Mastercard: it will be IP0040T1.Card_Program_ID.
Union Pay: it will be one of UNKNOWN, UNION_PAY_CLASSIC, RESERVED_2, UNION_PAY_GOLD, UNION_PAY_PLATINUM, UNION_PAY_DIAMOND, RESERVED_6.

product_descriptionstring

Description for product_code

product_subtype_codestring

Visa: it will be production sub-type id description. For more details please refer to base-ii-clearing-ep-release-4-reports, 'EP-302 — Account Range Table (ARDEF) Field Descriptions' field SU TY.
Mastercard: it will be IP0040T1.GCMS_Product_ID.
Union Pay: it will be BIN_Update_File.Card_Level.

product_subtype_descriptionstring

Description for product_subtype_code

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url)
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/pa/reference/bin/lookup

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/pa/reference/bin/lookup' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --header 'x-pan: 4111111111111111'

Response (200 OK)

1[
2  {
3    "card_brand": "visa",
4    "card_type": "credit",
5    "commercial_card": false,
6    "issuer_country_code": "US",
7    "issuer_name": "An Issuer Name",
8    "product_code": "G",
9    "product_description": "Visa Business",
10    "product_subtype_code": "MS",
11    "product_subtype_description": "Multicurrency Solution"
12  }
13]

Was this section helpful?