Requesting the BIN Lookup Service Using the REST API {#bin-lookup-req-task} =========================================================================== `Cybersource` recommends that you send the full payment card number (PAN), a TMS token, or a network token when you request the BIN Lookup Service. This ensures that a single BIN record is identified during the request. Even though the service supports sending the six-digit or eight-digit card prefix in the request, this option can result in a `MULTIPLE` record match error if a single BIN record cannot be identified. When you receive a ` MULTIPLE ` status record match error, we recommend you provide the full payment card number, a TMS token, or a network token to receive a ` SUCCESS ` status in the response. Send one of these payment credentials to the BIN Lookup Service to get the payment card account information. **Payment Card Numbers** * Full payment card number (recommended best practice) * Eight-digit card prefix (not recommended because it might result in a `MULTIPLE` status record match error) * Six-digit card prefix (not recommended because this option can result in a `MULTIPLE` status record match error) **Tokens** * `TMS` customer ID token * `TMS` payment instrument token * `TMS` instrument identifier token * `TMS` jti transient token * `Flex API` JWT transient token * Network tokens (Visa VTS, MDES, and Discover) Follow these steps to request the BIN Lookup Service: 1. Send the request to the BIN Lookup Service endpoint: #### ADDITIONAL INFORMATION `POST https://<``url_prefix``>/bin/v1/binlookup` #### ADDITIONAL INFORMATION Use one of these URL prefixes: * Test: `apitest.cybersource.com` * Production: `api.cybersource.com` * Production in India: `api.in.cybersource.com` 2. Include one of the prerequisite fields in the request: * paymentInformation.card.number (Full payment card number is recommended.) * paymentInformation.customer.id * paymentInformation.instrumentIdentifier.id * paymentInformation.paymentInstrument.id * tokenInformation.jti * tokenInformation.transientTokenJwt {#bin-lookup-req-task_choices_az2_s4v_f5b} 3. Include optional fields in the request as needed. 4. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success. For information about response codes, see [BIN Lookup Response Codes](/docs/cybs/en-us/bin-lookup/developer/all/na/bin-lookup/bin-lookup-reference-intro/bin-lookup-resp-codes.md ""). Required Fields for the BIN Lookup Service Using the REST API {#bin-lookup-service-fields} ========================================================================================== Include one of these payment credential fields in the request for the BIN Lookup Service: [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : Set this field to the full payment card number (recommended) or network token. [paymentInformation.customer.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-customer-id.md "") : [paymentInformation.instrumentIdentifier.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-instrument-identifier-id.md "") : [paymentInformation.paymentInstrument.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-payment-instrument-id.md "") : [tokenInformation.jti](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/token-info-aa/token-info-jti.md "") : [tokenInformation.transientTokenJwt](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/token-info-aa/token-info-transient-token-jwt.md "") : Optional Fields for the BIN Lookup Service Using the REST API {#bin-lookup-opt-fields} ====================================================================================== These fields are optional for a BIN Lookup Service request: [paymentAccountInformation.network.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-account-info-aa/payment-account-info-network-id.md "") : [processingInformation.binSource](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-bin-source.md "") : Testing the BIN Lookup Service {#bin-lookup-test-proc} ====================================================== `Cybersource` provides test BINs for requesting the BIN Lookup Service in the test environment. Do not use real payment card numbers. Test BINs for the BIN Lookup Service {#bin-lookup-service-test} =============================================================== Comprehensive reference table of test BINs for validating BIN Lookup Service functionality, including various card types, platforms, countries, and funding sources. Use the BINs below to test the BIN Lookup Service at the test endpoint: `https://apitest.cybersource.com``/bin/v1/binlookup` | BIN | Card Type | Card Platform and/or Product | Issuer Country | Account Funding Source | Eight-Digit BIN Results | PAN/Network Token | |:---------|:----------|:--------------------------------------|:---------------|:-----------------------|:------------------------|:------------------| | 442780 | Visa | Classic | US | Credit | --- | PAN | | 476173 | Visa | Classic | US | Credit | --- | PAN | | 679999 | Maestro | Classic | US | Credit | --- | PAN | | 22055310 | PayPak | --- | PK | Debit | --- | PAN | | 36126700 | Diners | Consumer Prepaid Non-reloadable Cards | PL | Prepaid | --- | PAN | | 36161200 | Diners | Consumer Debit Cards | AM | Debit | --- | PAN | | 36722600 | Diners | Commercial Debit Cards | ZA | Debit | --- | PAN | | 39009100 | Diners | Consumer Prepaid Reloadable Cards | US | Prepaid | --- | PAN | | 48127900 | Visa | Visa Classic | MX | Debit | Yes | PAN | | 49134300 | Visa | Visa Classic | MX | Credit | Yes | PAN | | 49134400 | Visa | Visa Classic | MX | Debit | Yes | PAN | | 49134600 | Visa | Visa Classic | MX | Credit | Yes | PAN | | 62232000 | CUP | Consumer Prepaid Reloadable Cards | US | Prepaid | --- | PAN | | 62630000 | CUP | Consumer Debit Cards | US | Debit | --- | PAN | | 40014600 | Visa | Visa Classic | US | Debit | Yes | Token | | 61900950 | Discover | Premium Plus Cards | US | Credit | --- | Token | | 4288300 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 4288301 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42882103 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42882104 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42882105 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42882106 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42882137 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889001 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889002 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889003 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889004 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889005 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889006 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889007 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889008 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | | 42889009 | Visa | Health Card | US | Debit or Prepaid | --- | PAN | [Test BINs and Card Information] Examples: Requests to the BIN Lookup Service Using the REST API {#bin-lookup-card-example} ========================================================================================== These examples show various BIN lookup requests and successful responses. Request Example: BIN Lookup Service with a Full Payment Card Number ``` { "paymentInformation": { "card": { "number": "4111111111111111" } } } ``` Response 201 Example: Successful BIN Lookup Service with a Full Payment Card Number ``` { "id": "7187318127246929204951", "submitTimeUtc": "2024-06-18T05:30:12Z", "status": "COMPLETED", "paymentAccountInformation": { "card": { "type": "001", "brandName": "VISA", "maxLength": "16", "credentialType": "PAN" }, "features": { "accountFundingSource": "DEBIT", "cardPlatform": "CONSUMER", "cardProduct": "Visa Classic" } }, "issuerInformation": { "name": "CONOTOXIA SP. Z O.O", "country": "PL", "binLength": "6", "accountPrefix": "41111111" } } ``` Request Example: BIN Lookup Service with a Health Card Number ``` { "paymentInformation": { "card": { "number": "4288900100000" } } } ``` Response 201 Example: Successful BIN Lookup Service with a Health Card Number ``` { "id": "7187371922356613504951", "submitTimeUtc": "2024-06-18T06:59:52Z", "status": "COMPLETED", "paymentAccountInformation": { "card": { "type": "001", "brandName": "VISA", "maxLength": "16", "currency": "USD", "credentialType": "PAN" }, "features": { "accountFundingSource": "CREDIT", "cardPlatform": "COMMERCIAL", "cardProduct": "Visa Purchasing", "healthCard": true } }, "issuerInformation": { "name": "BANKUNITED, NATIONAL ASSOCIATION", "country": "US", "binLength": "6", "accountPrefix": "42889001" } } ``` Request Example: BIN Lookup Service with a Network Token ``` { "paymentInformation": { "card": { "number": "4895370016313691" } } } ``` Response 201 Example: Successful BIN Lookup Service with a Network Token ``` { "id": "6680880793396052804990", "submitTimeUtc": "2022-11-10T01:47:59Z", "status": "COMPLETED", "paymentAccountInformation": { "card": { "type": "001", "brandName": "VISA", "maxLength": "16", "credentialType": "TOKEN" }, "features": { "accountFundingSource": "DEBIT", "cardPlatform": "CONSUMER", "cardProduct": "Visa Classic" } }, "issuerInformation": { "name": "INTL HDQTRS-CENTER OWNED", "country": "US", "binLength": "6" "accountPrefix": "4111111" } } ``` Request Example: BIN Lookup Service with a Six-Digit Payment Card Prefix ``` { "paymentInformation": { "card": { "number": "5033961" } } } ``` Response 201 Example: Multiple Match BIN Lookup Service with a Six-Digit Payment Card Prefix ``` \\ This response occurs when multiple account ranges are found with the provided digits. If you receive this response, please provide extended BIN digits to narrow the result to a single range. { "id": "6445408746306656603955", "submitTimeUtc": "2022-02-11T12:54:35Z", "status": "MULTIPLE" } ``` Request Example: BIN Lookup Service with an Eight-Digit Payment Card Prefix ``` { "paymentInformation": { "card": { "number": "71111111" } } } ``` Response 201 Example: BIN Lookup Service No Match ``` \\ This response occurs when a BIN record is not found with the provided digits. { "id": "6445408746306656603955", "submitTimeUtc": "2022-02-11T12:54:35Z", "status": "NO MATCH" } ``` Request Example: BIN Lookup Service with a `TMS` Customer ID Token ``` { "paymentInformation": { "customer": { "id": "D0ED44421CDA7A58E053AF598E0AD964" } } } ``` Request Example: BIN Lookup Service with a `TMS` Payment Instrument Token ``` { "paymentInformation": { "paymentInstrument": { "id": "D0ED44421CD97A58E053AF598E0AD964" } } } ``` Request Example: BIN Lookup Service with a `TMS` Instrument Identifier Token ``` { "paymentInformation": { "instrumentIdentifier": { "id": "801E10E1B4E2C86AE05341588E0A86EC" } } } ``` Request Example: BIN Lookup Service with a `TMS` jti Transient Token ``` { "tokenInformation": { "jti": "1C26VZRFEIQMOO5H0504KH47I0AM2IZFC43V5L541HBLN9COI3L75F3194E196A1" } } ``` Request Example: BIN Lookup Service with a `Flex API` JWT Transient Token ``` { "tokenInformation": { "transientTokenJwt": "eyJraWQ...xxxxx.yyyyy.zzzzz...xZqoGA" } } ```