Retrieve card metadata
Beta

Last updated: March 27, 2024

Metadata is information about cards provided by a card scheme. Key information includes:

where the card was issued
who the issuer is
if the card is a debit or credit card
if the card is commercial or consumer
if the card is co-branded
if the card is eligible for payouts

Metadata enables you to verify if a customer's card account is Card payouts eligible and Fast funds enabled before you initiate a Card payout request. This will help with improving the acceptance rate.

Additionally, metadata enables you to:

enhance your customer's overall experience
maximize sales
optimize approval rates
perform risk checks
display information about the cards to customers in the checkout flow

You can request payment card metadata using any of the following:

full card details (FPAN) – requires PCI compliance (SAQ D)
network token (DPAN)
token
payment instrument
BIN

We offer two different collections of information in the response. You can specify the required collection when sending the request by defining the format:

basic – information in this collection is intended to find out the card scheme, card issuer, card type, country, etc. needed for processing the payments more successfully.
card_payouts – the collection includes all the basic information and specific information related to making card payouts. The specific fields on card payouts enable you to check card eligibility for payouts, which is determined by the issuing bank for the specified Fund transfer type (FTTs) and geographic scope (domestic or cross-border).

Information

To learn more, reach out to your Account Manager or [email protected].

If you are PCI SAQ D compliant, you can request metadata using the full card details (FPAN). You can also retrieve metadata information by providing us the network token (DPAN). DPAN is a surrogate value for a PAN that has a variable length and is ISO/IEC 7812 compliant. The DPAN is issued from a designated Token BIN or Token BIN Range and is flagged accordingly in all appropriate BIN tables.

A Payment Token DPAN must pass basic validation rules of a PAN, including the Luhn check digit.

For a full list of optional and required fields and their descriptions, refer to our API reference.

post

https://api.checkout.com/metadata/card


1{
2  "source": {
3    "type": "card",
4    "number": "4539467987109256"
5  },
6  "format": "card_payouts"
7}

If the request was successful, you will receive a 200 success response. This will include the metadata for the requested card.

If your request contains field format: card_payouts, you will receive the card_payouts object in the response. Valid values for the card_payouts object field include:

not_supported – the card does not support payouts or fast funds for all transaction types.
standard – the card is eligible for standard payouts for the specified funds transfer type and geographic scope. The funds may take up to 48 hours to be made available to the recipient, though this may vary depending on the issuer's posting times.
fast_funds – the card is Fast funds payouts enabled and standard for the specified funds transfer type and geographic scope. Funds will be made available to the cardholder within 30 minutes of the issuer receiving the Card payout request.
unknown – the card or issuer details were not found, or the card scheme does not know the Card payouts eligibility and fast funds status for this card.


1{
2  "bin": "45394679",
3  "scheme": "visa",
4  "scheme_local": "cartes_bancaires",
5  "card_type": "CREDIT",
6  "card_category": "CONSUMER",
7  "currency": "MUR",
8  "issuer": "Test Bank",
9  "issuer_country": "MU",
10  "issuer_country_name": "Mauritius",
11  "product_id": "F",
12  "product_type": "Visa Classic",
13  "card_payouts": {
14    "domestic_non_money_transfer": "not_supported",
15    "cross_border_non_money_transfer": "standard",
16    "domestic_gambling": "fast_funds",
17    "cross_border_gambling": "unknown",
18    "domestic_money_transfer": "unknown",
19    "cross_border_money_transfer": "not_supported"
20  }
21}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Retrieve metadata using a Checkout.com token. A single-use token represents sensitive payment information and expires after 15 minutes.

Information

Single-use is not applied when a token is used to request information from the Card Metadata API. The 15-minute lifespan of the token will still apply regardless.

For a full list of optional and required fields and their descriptions, refer to our API reference.

post

https://api.checkout.com/metadata/card


1{
2  "source": {
3    "type": "token",
4    "token": "tok_ubfj2q76miwundwlk72vxt2i7q"
5  },
6  "format": "card_payouts"
7}

If the request was successful, you will receive a 200 success response. This will include the metadata for the requested tokenized card.

If your request contains field format: card_payouts, you will receive the card_payouts object in the response. Valid values for the card_payouts object field include:

not_supported – the card does not support payouts or fast funds for all transaction types
standard – the card is eligible for standard payouts for the specified funds transfer type and geographic scope
fast_funds – the card is enabled for Fast funds payouts and standard for the specified funds transfer type and geographic scope
unknown – the card or issuer details were not found


1{
2  "bin": "45394679",
3  "scheme": "visa",
4  "scheme_local": "cartes_bancaires",
5  "card_type": "CREDIT",
6  "card_category": "CONSUMER",
7  "currency": "MUR",
8  "issuer": "Test Bank",
9  "issuer_country": "MU",
10  "issuer_country_name": "Mauritius",
11  "product_id": "F",
12  "product_type": "Visa Classic",
13  "card_payouts": {
14    "domestic_non_money_transfer": "not_supported",
15    "cross_border_non_money_transfer": "standard",
16    "domestic_gambling": "fast_funds",
17    "cross_border_gambling": "unknown",
18    "domestic_money_transfer": "unknown",
19    "cross_border_money_transfer": "not_supported"
20  }
21}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

You can also retrieve metadata with the Checkout.com payment instrument. A payment instrument's unique ID represents a payment card stored securely in our Vault.

For a full list of optional and required fields and their descriptions, refer to our API reference.

post

https://api.checkout.com/metadata/card


1{
2  "source": {
3    "type": "id",
4    "id": "src_e7hqezhxdfeetnyfdv3ayu6yru"
5  },
6  "format": "card_payouts"
7}

If the request was successful, you will receive a 200 success response. This will include the metadata for the requested payment instrument.

If your request contains field format: card_payouts, you will receive the card_payouts object in the response. Valid values for the card_payouts object field include:

not_supported – the card does not support payouts or fast funds for all transaction types
standard – the card is eligible for standard payouts for the specified funds transfer type and geographic scope
fast_funds – the card is enabled for Fast funds payouts and standard for the specified funds transfer type and geographic scope
unknown – the card or issuer details were not found


1{
2  "bin": "45394679",
3  "scheme": "visa",
4  "scheme_local": "cartes_bancaires",
5  "card_type": "CREDIT",
6  "card_category": "CONSUMER",
7  "currency": "MUR",
8  "issuer": "Test Bank",
9  "issuer_country": "MU",
10  "issuer_country_name": "Mauritius",
11  "product_id": "F",
12  "product_type": "Visa Classic",
13  "card_payouts": {
14    "domestic_non_money_transfer": "not_supported",
15    "cross_border_non_money_transfer": "standard",
16    "domestic_gambling": "fast_funds",
17    "cross_border_gambling": "unknown",
18    "domestic_money_transfer": "unknown",
19    "cross_border_money_transfer": "not_supported"
20  }
21}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Use the following details to set up your request. Both 6-digit BIN and 8-digit BIN are supported to request payment card metadata from the API.

Note

While a BIN (both 6 and 8-digit) can be used to obtain general card information, the BIN is the least accurate way to retrieve metadata. We recommend requesting metadata using either using a token, instrument, or full card details instead.

For a full list of optional and required fields and their descriptions, refer to our API reference.

post

https://api.checkout.com/metadata/card


1{
2  "source": {
3    "type": "bin",
4    "bin": "45394679"
5  },
6  "format": "card_payouts"
7}

If the request was successful, you will receive a 200 success response. This will include the metadata for the requested card BIN.

If your request contains field format: card_payouts, you will receive the card_payouts object in the response. Valid values for the card_payouts object field include:

not_supported – the card does not support payouts or fast funds for all transaction types
standard – the card is eligible for standard payouts for the specified funds transfer type and geographic scope
fast_funds – the card is enabled for Fast funds payouts and standard for the specified funds transfer type and geographic scope
unknown – the card or issuer details were not found


1{
2  "bin": "45394679",
3  "scheme": "visa",
4  "scheme_local": "cartes_bancaires",
5  "card_type": "CREDIT",
6  "card_category": "CONSUMER",
7  "currency": "MUR",
8  "issuer": "Test Bank",
9  "issuer_country": "MU",
10  "issuer_country_name": "Mauritius",
11  "product_id": "F",
12  "product_type": "Visa Classic",
13  "card_payouts": {
14    "domestic_non_money_transfer": "not_supported",
15    "cross_border_non_money_transfer": "standard",
16    "domestic_gambling": "fast_funds",
17    "cross_border_gambling": "unknown",
18    "domestic_money_transfer": "unknown",
19    "cross_border_money_transfer": "not_supported"
20  }
21}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

To test the Card Metadata API, use the following test card details.

Test card	Domestic non-money transfer	Cross border non-money transfer
`4273149019799094`	`fast_funds`	`fast_funds`
`4024007181869214`	`not_supported`	`not_supported`
`4916301720257093`	`unknown`	`unknown`
`4095254802642505`	`fast_funds`	`not_supported`
`4140253846048187`	`standard`	`standard`
`4659105569051157`	`fast_funds`	`fast_funds`
`4484070000035519`	`standard`	`standard`
`4820285375797526`	`standard`	`not_supported`
`5352151570003404`	`fast_funds`	`fast_funds`
`5558468902774508`	`fast_funds`	`fast_funds`
`5356860600000133`	`standard`	`standard`

Test card	Domestic money transfer	Cross border money transfer
`4273149019799094`	`fast_funds`	`fast_funds`
`4024007181869214`	`not_supported`	`not_supported`
`4916301720257093`	`unknown`	`unknown`
`4095254802642505`	`fast_funds`	`not_supported`
`4140253846048187`	`standard`	`standard`
`4659105569051157`	`fast_funds`	`fast_funds`
`4484070000035519`	`standard`	`standard`
`4820285375797526`	`standard`	`not_supported`
`5352151570003404`	`fast_funds`	`fast_funds`
`5558468902774508`	`fast_funds`	`fast_funds`
`5356860600000133`	`standard`	`standard`

Test card	Domestic gambling	Cross border gambling
`4273149019799094`	`not_supported`	`not_supported`
`4024007181869214`	`not_supported`	`not_supported`
`4916301720257093`	`unknown`	`unknown`
`4095254802642505`	`fast_funds`	`not_supported`
`4140253846048187`	`not_supported`	`not_supported`
`4659105569051157`	`fast_funds`	`fast_funds`
`4484070000035519`	`standard`	`standard`
`4820285375797526`	`not_supported`	`not_supported`
`5352151570003404`	`not_supported`	`not_supported`
`5558468902774508`	`not_supported`	`not_supported`
`5356860600000133`	`fast_funds`	`fast_funds`

Retrieve card metadata
Beta

Requesting card payment metadata

Information

Using full card details (FPAN) or network tokens (DPAN)

Endpoints

Request example

Response example

Using a token

Information

Endpoints

Request example

Response example

Using a payment instrument

Endpoints

Request example

Response example

Using a BIN

Note

Endpoints

Request example

Response example

Testing

Non-money transfer

Money transfer

Gambling