> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/api-reference/open-api-references/ecommerce/bin-lookup.md).
# BIN Lookup
The BIN (Bank Identification Number) lookup endpoint returns card details — brand, issuer, card type, and funding source — for a given card number prefix or encrypted card. Use this to display card brand icons at checkout or to apply Merchant Choice Routing (MCR) logic for dual-branded cards.
## Card Details / BIN Lookup
## Bin lookup of Card Number
> The Card Details API endpoints will bin lookup and provides card details.
```json
{"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"cardDetailsPrefixRequest":{"title":"Prefix","type":"object","properties":{"prefix":{"type":"string","minLength":4,"maxLength":8,"description":"The prefix of the card to search for."},"entity_id":{"type":"string","description":"Optional. The identifier of merchant entity for this request.","format":"uuid"},"query_context":{"$ref":"#/components/schemas/BinQueryContext"}},"required":["prefix"]},"BinQueryContext":{"type":"object","properties":{"supported_card_brands":{"type":"array","description":"A list of card brands supported by the merchant for this context. This list will be used to filter results to supported card brands only.\n","items":{"title":"The Card Brand","description":"The brand of this card, e.g. VISA, MASTERCARD, AMEX, CB, GIFT_CARD, etc.","type":"string"}},"amount_details":{"type":"object","description":"Optional amount and currency of the transaction corresponding to this bin lookup.\n\nThese values will be used for the automatic selection of card brand for dual branded cards if MCR (Merchant Choice Routing)\nis enabled for the merchant and supported for the country.\n","required":["amount","currency_code"],"properties":{"amount":{"description":"Amount without a decimal place e.g. $1.5 = 150.\n\nThe required number of decimal places for a currency code is according to ISO 4217.\n","type":"integer"},"currency_code":{"type":"string","title":"Currency Code","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD.\n\nValues correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LVL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","USS","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XTS","XXX","YER","ZAR","ZMK","ZMW","BTC"]}}}}},"cardDetailsEncryptedCardRequest":{"title":"Encrypted Card","type":"object","properties":{"encrypted_card":{"type":"string","title":"Client encrypted cardholder data","description":"The cardholder data encrypted using the Verifone provided public key. This can be obtained using either Verifone.JS solution or Verifone Checkout in capture mode.\n\n The data to encrypt is a JSON with possible tags being cardNumber, sequenceNumber, cardholderName, startMonth, startYear, expiryMonth, expiryYear, cvv. This should be a single JSON line and should not contain any spaces. Read Secure card capture key for details.\n\n Additionally, a tag called captureTime must be presenting indicating the time the card was captured in UTC in format RFC 3339, section 5.6. eg. 2019-08-24T14:15:22Z. Encrypted card is valid for only 15 minutes."},"public_key_alias":{"type":"string","title":"Public Key Alias","description":"The alias for the public key used to encrypt this card."},"entity_id":{"type":"string","description":"The identifier of merchant entity under whose cardTableGroupId you want to look for bin info.","format":"uuid"},"query_context":{"$ref":"#/components/schemas/BinQueryContext"}},"required":["encrypted_card","public_key_alias"]},"CardDetailsResponse":{"type":"object","properties":{"bin_details":{"description":"The details of the bin range or card. May contain more than one record if a co-branded card.","type":"array","items":{"title":"BIN Information","description":"BIN entries refer to the Bank Identification Number entries in a financial system, typically representing the first six digits of a credit or debit card. These entries are essential for identifying the issuing bank or financial institution associated with a specific card.","type":"object","additionalProperties":false,"properties":{"bin":{"description":"A BIN (Bank Identification Number) prefix refers to the initial set of digits in a credit or debit card number that uniquely identifies the issuing bank or financial institution.","type":"string","minLength":4,"maxLength":8},"card_brand":{"title":"The Card Brand","description":"The brand of this card, e.g. VISA, MASTERCARD, AMEX, CB, GIFT_CARD, etc.","type":"string"},"type":{"description":"The Account type or PAYMENT_TYPE in UGP. This source of the payment for the goods or service. This has a mapping to the processing code in DE03 (Processing Code) in ISO8583. This should map to the AccountType in Nexo/ISO20022. MSISDN - Mobile Station Integrated Services Digital Network. eg. CREDIT, DEBIT, STORED_VALUE, PRIVATE_LABEL, DEFAULT, etc.","type":"string"},"funding_source":{"description":"The type of funding this card has. Is this linked to a savings account/pre paid account or is this linked to a credit facility. eg. CREDIT, DEBIT, PREPAID, UNKNOWN","type":"string"},"issuer_country":{"$ref":"#/components/schemas/issuerCountryEnum"},"issuer_name":{"description":"The issuer of this card. eg. HSBC, BARCLAYS.","type":"string"},"added_leading_zeroes":{"description":"The number of leading zeroes that were added to get the match. This used at least for Isracard to deal with cards that have only 7 digits because the first three are zeroes.","type":"integer","minimum":0,"maximum":3},"checksum_algorithm":{"description":"The checksum algorithm to apply to the PAN including the addedLeadingZeroes. LUHN is the default.","type":"string","enum":["LUHN","ISRACARD","NONE"],"default":"LUHN"},"card_product":{"type":"string","description":"The type or category of credit or debit card."}}}}}},"issuerCountryEnum":{"type":"string","description":"The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code.Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
.","enum":["ZZZ","ABW","AFG","AGO","AIA","ALA","ALB","AND","ARE","ARG","ARM","ASM","ATA","ATF","ATG","AUS","AUT","AZE","BDI","BEL","BEN","BES","BFA","BGD","BGR","BHR","BHS","BIH","BLM","BLR","BLZ","BMU","BOL","BRA","BRB","BSB","BRN","BTN","BVT","BWA","CAF","CAN","CCK","CHE","CHL","CHN","CIV","CMR","COD","COG","COK","COL","COM","CPV","CRI","CUB","CUW","CXR","CYM","CYP","CZE","DEU","DJI","DMA","DNK","DOM","DZA","ECU","EGY","ERI","ESH","ESP","EST","ETH","FIN","FJI","FLK","FRA","FRO","FSM","GAB","GBR","GEO","GGY","GHA","GIB","GIN","GLP","GMB","GNB","GNQ","GRC","GRD","GRL","GTM","GUF","GUM","GUY","HKG","HMD","HND","HRV","HTI","HUN","IDN","IMN","IND","IOT","IRL","IRN","IRQ","ISL","ISR","ITA","JAM","JEY","JOR","JPN","KAZ","KEN","KGZ","KHM","KIR","KNA","KOR","KWT","LAO","LBN","LBR","LBY","LCA","LIE","LKA","LSO","LTU","LUX","LVA","MAC","MAF","MAR","MCO","MDA","MDG","MDV","MEX","MHL","MKD","MLI","MLT","MMR","MNE","MNG","MNP","MOZ","MRT","MSR","MTQ","MUS","MWI","MYS","MYT","NAM","NCL","NER","NFK","NGA","NIC","NIU","NLD","NOR","NPL","NRU","NZL","OMN","PAK","PAN","PCN","PER","PHL","PLW","PNG","POL","PRI","PRK","PRT","PRY","PSE","PYF","QAT","REU","ROU","RUS","RWA","SAU","SDN","SEN","SGC","SGP","SHN","SJM","SLB","SLE","SLV","SMR","SOM","SPM","SRB","SSD","STP","SUR","SVK","SVN","SWE","SWZ","SXM","SYC","SYR","TCA","TCD","TGO","THA","TJK","TKL","TKM","TLS","TON","TTO","TUN","TUR","TUV","TWN","TZA","UGA","UKR","UMI","URY","USA","UZB","VAT","VCT","VEN","VGB","VIR","VNM","VUT","WLF","WSM","YEM","ZAF","ZMB","ZWE"]},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/card/card-details":{"post":{"operationId":"Binlookup","summary":"Bin lookup of Card Number","description":"The Card Details API endpoints will bin lookup and provides card details.","parameters":[{"name":"x-vfi-api-idempotencykey","required":false,"in":"header","description":"Example: 63bbc548-d2de-4546-b106-880a5018461c \n\n A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The Card Details API endpoints will bin lookup and provides card details.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/cardDetailsPrefixRequest"},{"$ref":"#/components/schemas/cardDetailsEncryptedCardRequest"}]}}}},"responses":{"201":{"description":"The details of the bin range or card. May contain more than one record if a co-branded card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardDetailsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}},"tags":["Bin"]}}}}
```
## Request Variants
{% tabs %}
{% tab title="By Prefix" %}
Submit `prefix` (4–8 digits). Optionally include `entity_id` and `query_context` for MCR support.
```json
{
"prefix": "492912",
"entity_id": "30b8bec8-5042-4e67-939c-5453fbe41711"
}
```
{% endtab %}
{% tab title="By Encrypted Card" %}
Submit `encrypted_card` and `public_key_alias` (obtained from [Secure Card Capture](/api-reference/open-api-references/ecommerce/secure-card-capture.md)).
```json
{
"encrypted_card": "U3dhZ2dlciByb2Nrcw==",
"public_key_alias": "KEY00101"
}
```
{% endtab %}
{% endtabs %}
## Key Response Fields
```
CardDetailsResponse
└── bin_details[]
├── bin ← matched BIN prefix (4–8 digits)
├── card_brand ← e.g. VISA, MASTERCARD, AMEX
├── type ← account type (CREDIT, DEBIT, STORED_VALUE, etc.)
├── funding_source ← CREDIT, DEBIT, PREPAID, UNKNOWN
├── issuer_name ← e.g. HSBC, BARCLAYS
├── issuer_country ← ISO 3166-1 alpha-3
└── card_product ← e.g. VISA CLASSIC
```
For co-branded cards, `bin_details` may contain more than one entry — one per brand. Use `query_context.supported_card_brands` to filter results to brands your merchant accepts.
{% hint style="info" %}
Supplying `query_context.amount_details` (amount + currency) enables automatic MCR brand selection if your entity is configured for Merchant Choice Routing.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.verifone.com/api-reference/open-api-references/ecommerce/bin-lookup.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.