# Retrieve card metadata

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

---

## Requesting card payment metadata

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

- [Full card details (FPAN)](#Using_full_card_details_(FPAN)_or_network_tokens_(DPAN)) – requires [PCI compliance (SAQ D)](https://www.checkout.com/docs/payments/ensure-regulatory-compliance/pci-compliance.md#What_is_PCI_and_why_is_it_important?)
- [Network token (DPAN)](#Using_full_card_details_(FPAN)_or_network_tokens_(DPAN))
- [Token](#Using_a_token)
- [Payment instrument](#Using_a_payment_instrument)
- [BIN](#Using_a_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, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

---

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

If you are [PCI SAQ D compliant](https://www.checkout.com/docs/payments/regulation-support/pci-compliance.md#What_is_PCI_and_why_is_it_important?), 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](https://api-reference.checkout.com/tag/Card-metadata/#operation/requestCardMetadata).

### Endpoints

**Live**

`POST` `https://{prefix}.api.checkout.com/metadata/card`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/metadata/card`

### Request example

```json
{
  "source": {
    "type": "card",
    "number": "4539467987109256"
  },
  "format": "card_payouts"
}
```

### Response example

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.

**200 Metadata request successful**

```json
{
  "bin": "45394679",
  "scheme": "visa",
  "scheme_local": "cartes_bancaires",
  "card_type": "CREDIT",
  "card_category": "CONSUMER",
  "currency": "MUR",
  "issuer": "Test Bank",
  "issuer_country": "MU",
  "issuer_country_name": "Mauritius",
  "product_id": "F",
  "product_type": "Visa Classic",
  "card_payouts": {
    "domestic_non_money_transfer": "not_supported",
    "cross_border_non_money_transfer": "standard",
    "domestic_gambling": "fast_funds",
    "cross_border_gambling": "unknown",
    "domestic_money_transfer": "unknown",
    "cross_border_money_transfer": "not_supported"
  }
}
```

**422 Invalid data sent**

```json
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": ["payment_source_required"]
}
```

---

## Using a token

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](https://api-reference.checkout.com/tag/Card-metadata/#operation/requestCardMetadata).

### Endpoints

**Live**

`POST` `https://{prefix}.api.checkout.com/metadata/card`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/metadata/card`

### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_ubfj2q76miwundwlk72vxt2i7q"
  },
  "format": "card_payouts"
}
```

### Response example

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.

**200 Metadata request successful**

```json
{
  "bin": "45394679",
  "scheme": "visa",
  "scheme_local": "cartes_bancaires",
  "card_type": "CREDIT",
  "card_category": "CONSUMER",
  "currency": "MUR",
  "issuer": "Test Bank",
  "issuer_country": "MU",
  "issuer_country_name": "Mauritius",
  "product_id": "F",
  "product_type": "Visa Classic",
  "card_payouts": {
    "domestic_non_money_transfer": "not_supported",
    "cross_border_non_money_transfer": "standard",
    "domestic_gambling": "fast_funds",
    "cross_border_gambling": "unknown",
    "domestic_money_transfer": "unknown",
    "cross_border_money_transfer": "not_supported"
  }
}
```

**422 Invalid data sent**

```json
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": ["payment_source_required"]
}
```

---

## Using a payment instrument

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](https://api-reference.checkout.com/tag/Card-metadata/#operation/requestCardMetadata).

### Endpoints

**Live**

`POST` `https://{prefix}.api.checkout.com/metadata/card`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/metadata/card`

### Request example

```json
{
  "source": {
    "type": "id",
    "id": "src_e7hqezhxdfeetnyfdv3ayu6yru"
  },
  "format": "card_payouts"
}
```

### Response example

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.

**200 Metadata request successful**

```json
{
  "bin": "45394679",
  "scheme": "visa",
  "scheme_local": "cartes_bancaires",
  "card_type": "CREDIT",
  "card_category": "CONSUMER",
  "currency": "MUR",
  "issuer": "Test Bank",
  "issuer_country": "MU",
  "issuer_country_name": "Mauritius",
  "product_id": "F",
  "product_type": "Visa Classic",
  "card_payouts": {
    "domestic_non_money_transfer": "not_supported",
    "cross_border_non_money_transfer": "standard",
    "domestic_gambling": "fast_funds",
    "cross_border_gambling": "unknown",
    "domestic_money_transfer": "unknown",
    "cross_border_money_transfer": "not_supported"
  }
}
```

**422 Invalid data sent**

```json
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": ["payment_source_required"]
}
```

---

## Using a BIN

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](#using_a_token), [instrument](#using_a_payment_instrument), or [full card details](#using_full_card_details) instead.

For a full list of optional and required fields and their descriptions, refer to our [API reference](https://api-reference.checkout.com/tag/Card-metadata/#operation/requestCardMetadata).

### Endpoints

**Live**

`POST` `https://{prefix}.api.checkout.com/metadata/card`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/metadata/card`

### Request example

```json
{
  "source": {
    "type": "bin",
    "bin": "45394679"
  },
  "format": "card_payouts"
}
```

### Response example

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.

**200 Metadata request successful**

```json
{
  "bin": "45394679",
  "scheme": "visa",
  "scheme_local": "cartes_bancaires",
  "card_type": "CREDIT",
  "card_category": "CONSUMER",
  "currency": "MUR",
  "issuer": "Test Bank",
  "issuer_country": "MU",
  "issuer_country_name": "Mauritius",
  "product_id": "F",
  "product_type": "Visa Classic",
  "card_payouts": {
    "domestic_non_money_transfer": "not_supported",
    "cross_border_non_money_transfer": "standard",
    "domestic_gambling": "fast_funds",
    "cross_border_gambling": "unknown",
    "domestic_money_transfer": "unknown",
    "cross_border_money_transfer": "not_supported"
  }
}
```

**422 Invalid data sent**

```json
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": ["payment_source_required"]
}
```

---

## Testing

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

### Non-money transfer

| 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` |

### Money transfer

| 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` |

### Gambling

| 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` |