On This Page

BIN Lookup Service Developer Guide

Overview of the BIN Lookup Service Developer Guide, including audience, purpose, conventions, and support information for developers integrating payment card validation services.
About This Guide
This section describes how to use this developer guide and where to find further information.
Audience and Purpose
This guide is written for application developers who want to use the
REST API
 to integrate the BIN Lookup Service into an order management system.
Implementing the
Cybersource
 payment services requires software development skills. You must write code that uses the API request and response fields to integrate the credit card services into your existing order management system.
Conventions
These statements appear in this document:
IMPORTANT
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
WARNING
A
Warning
 contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.
Related Documentation
Visit the
Cybersource
 documentation hub to find additional technical documentation.
Customer Support
For support information about any service, visit the Support Center:

Limited Availability Release

This document provides information about the limited availability release of the BIN Lookup Service REST API.

Recent Revisions to This Document

26.07.01

Added these new response fields for the BIN Lookup Service. See Response Fields for the BIN Lookup Service Using the REST API.
  • paymentAccountInformation.features.atmEnabled
  • paymentAccountInformation.features.ecomEnabled
  • paymentAccountInformation.features.fleetCard
  • paymentAccountInformation.features.posEnabled

25.11.01

Removed all references to unsupported card brands.

25.06.01

Test BINs
Added the test BIN for PayPak cards. See Test BINs for the BIN Lookup Service.

Visa Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through
Cybersource for
Visa Platform Connect
 (“VPC”) processing
. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE
Visa Platform Connect
 ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT
Visa Platform Connect
 ACQUIRER.

Introduction to the BIN Lookup Service

Overview of the BIN Lookup Service functionality, including how it provides payment card account information using bank identification numbers, payment card numbers, and various token types.
The BIN Lookup Service provides payment card account information based on a
bank identification number
 (BIN) and account range information. The BIN represents the first six or eight digits on the payment card. The first digit of the BIN is the industry identifier for the network used by the card-issuing institution. The remaining five or seven digits of the BIN identify the card-issuing institution and some of the card attributes.
You can request the BIN Lookup Service using a payment card number (PAN), BIN, network token, Token Management Service (TMS) token, or
Secure Acceptance
 transient token.
For more information about
Secure Acceptance
 transient tokens, see the
Digital Accept
 Secure Integration Developer Guide
.
BIN lookup service returns BIN attribute information for the payment credential specified in the request, such as:
  • Card type code
  • Card brand, such as American Express or Visa
  • Card currency
  • Account funding source, such as credit or debit
  • Account prefix
  • Payment credential type
  • Issuer BIN length (network dependent)
  • Issuer name
  • Issuer country
  • Issuer phone number
  • Fast funds eligibility (if enabled)

Prerequisites

Requirements and setup steps needed before using the BIN Lookup Service, including REST API knowledge and sandbox account creation.
Before you begin using the BIN Lookup Service:

Requesting the BIN Lookup Service Using the REST API

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.
IMPORTANT
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
  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.

Required Fields for the BIN Lookup Service Using the REST API

Reference guide for required payment credential fields when making BIN Lookup Service requests, including payment card numbers and various token types.
Include one of these payment credential fields in the request for the BIN Lookup Service:

Optional Fields for the BIN Lookup Service Using the REST API

Reference guide for optional fields that can be included in BIN Lookup Service requests to provide additional processing information and network specifications.
These fields are optional for a BIN Lookup Service request:

Testing the BIN Lookup Service

Guidelines for testing the BIN Lookup Service in the test environment using provided test BINs instead of real payment card numbers.
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

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
Test BINs and Card Information
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

Examples: Requests to the BIN Lookup Service Using the REST API

Comprehensive examples of BIN Lookup Service requests and responses using various payment credentials including payment card numbers, tokens, and network tokens.
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"
  }
}

Requesting the BIN Lookup Service with Fast Funds Eligibility Using the REST API

Send one of these payment credentials to the BIN Lookup Service to retrieve BIN information and fast funds eligibility.
Payment Card Numbers
  • Full payment card number
Tokens
  • TMS
     customer ID token
  • TMS
     payment instrument token
  • TMS
     instrument identifier token
  • TMS
     jti transient token
  • Flex API
     JWT transient token
Follow these steps to request the BIN Lookup Service with Fast Funds:
  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
  3. Request the service. Set
    processingInformation.payoutOptions.payoutInquiry
     to
    true
    .
  4. Include optional fields in the request as needed.
  5. 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.

Required Fields for the BIN Lookup Service with Fast Funds Eligibility Using the REST API

Include this fast funds eligibility field in the request for the BIN Lookup Service:
Set this field to
true
 to get fast funds eligibility information in the response.
Include one of these payment credential fields in the request:

Optional Fields for the BIN Lookup Service with Fast Funds Eligibility Using the REST API

Testing the BIN Lookup Service with Fast Funds Eligibility Using the REST API

Cybersource
 provides these test payment card numbers for requesting the BIN Lookup Service with fast funds eligibility in the test environment. Do not use real payment card numbers. Remove spaces when sending card numbers to
Cybersource
.

Test Payment Card Numbers for the BIN Lookup Service with Fast Funds

Use these payment card numbers to test the BIN Lookup Service with fast funds at the test endpoint:
https://apitest.cybersource.com
/bin/v1/binlookup
Test Payment Card Numbers and Card Information
Card Number
Card Type
Card Platform and/or Product
Issuer Country
Account Funding Source
4761 0800 0000 0003
Visa
Consumer
AE
Debit
4515 8600 0004 1118
Visa
Consumer
US
Debit
4515 2200 0008 1111
Visa
Business
AL
Debit
4473 3000 0051 1117
Visa
Business
AM
Debit
4846 7000 0973 1113
Visa
Business
AO
Debit

Examples: Requests to the BIN Lookup Service with Fast Funds Eligibility Using the REST API

These examples show various BIN Lookup Service requests with fast funds eligibility options enabled and successful responses.
Request Example: BIN Lookup Service with a Payment Card and Fast Funds Eligibility 
{
    "paymentInformation": {
        "card": {
            "number": "4761080000000003"
        }
    },
    "processingInformation": {
        "payoutOptions": {
            "payoutInquiry": true
        }
    }
}
Response 201 Example: Successful BIN Lookup Service with Fast Funds Eligibility
 {
    "id": "6590834057836283403955",
    "submitTimeUtc": "2022-07-29T08:30:05Z",
    "status": "COMPLETED",
    "paymentAccountInformation": {
        "card": {
            "type": "001",
            "brandName": "VISA",
            "maxLength": "16",
            "currency": "AED",
            "credentialType": "PAN"
        },
        "features": {
            "accountFundingSource": "DEBIT",
            "cardPlatform": "CONSUMER",
            "comboCard": "0"
        }
    },
    "issuerInformation": {
        "name": "INTL HDQTRS-CENTER OWNED",
        "country": "AE"
        "accountPrefix": "4111111"
    },
    "payoutInformation": {
        "pushFunds": {
            "moneyTransferFastFundsCrossBorder": "Y",
            "moneyTransferFastFundsDomestic": "Y",
            "moneyTransferCrossBorder": "Y",
            "moneyTransferDomestic": "Y",
            "nonMoneyTransferFastFundsCrossBorder": "Y",
            "nonMoneyTransferFastFundsDomestic": "Y",
            "nonMoneyTransferCrossBorder": "Y",
            "nonMoneyTransferDomestic": "Y",
            "onlineGamblingFastFundsCrossBorder": "Y",
            "onlineGamblingFastFundsDomestic": "Y",
            "onlineGamblingCrossBorder": "Y",
            "onlineGamblingDomestic": "Y"
        }
    }
}
Response 201 Example: BIN Lookup Service with Fast Funds Eligibility (Brazil)
{
    "id": "6590834057836283403955",
    "submitTimeUtc": "2022-05-19T03:21:03Z",
    "status": "COMPLETED",
    "paymentAccountInformation": {
        "card": {
            "type": "001",
            "brandName": "VISA",
            "maxLength": "16",
            "currency": "USD"
        },
        "features": {
            "accountFundingSource": "PREPAID",
            "cardPlatform": "CONSUMER",
            "cardProduct": "Visa Electron",
            "comboCard": "0"
        }
    },
    "issuerInformation": {
        "name": "BANCO DO BRASIL S.A.",
        "country": "BR",
        "phoneNumber": "5555555555",
        "binLength": "6"
        "accountPrefix": "4111111"
    },
    "payoutInformation": {
        "pushFunds": {
            "moneyTransferFastFundsCrossBorder": "N",
            "moneyTransferFastFundsDomestic": "N",
            "moneyTransferCrossBorder": "Y",
            "moneyTransferDomestic": "Y",
            "nonMoneyTransferFastFundsCrossBorder": "N",
            "nonMoneyTransferFastFundsDomestic": "N",
            "nonMoneyTransferCrossBorder": "Y",
            "nonMoneyTransferDomestic": "Y",
            "onlineGamblingFastFundsCrossBorder": "N",
            "onlineGamblingFastFundsDomestic": "N",
            "onlineGamblingCrossBorder": "Y",
            "onlineGamblingDomestic": "Y"
        }
    }
}

Reference Information

Overview of reference materials for the BIN Lookup Service, including response codes, response fields, and payout-specific response information.
This section contains reference information that is useful when you work with the BIN Lookup Service.

BIN Lookup Service Response Codes

Reference table of HTTP response codes returned by the BIN Lookup Service, including success codes, error codes, and recommended actions for each response type.
The BIN Lookup Service returns these codes.
Response Codes
Code
Description
Action to Take
201
Successful response.
No further action required.
400
Invalid request.
Verify the request and retry.
502
Unexpected system error or system timeout.
Verify the request and retry.
201
Multiple records.
Retry with full PAN, TMS token, or network token.
201
No match.
No further action required.

Response Fields for the BIN Lookup Service with Fast Funds Eligibility Using the REST API

A response for the BIN Lookup Service with fast funds eligibility information can include these response fields: