Skip to content

Retrieve card metadata Beta

Last updated: January 18, 2023

Metadata is information about cards provided by a card network. 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
  • Is the card co-branded or not
  • If the card is payout eligible

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

There are four ways to request payment card metadata using the Card Metadata API.


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 Customer Success Manager or support@checkout.com.


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

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.

Endpoints

    post

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

    Request example

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

    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 network 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
      "issuer": "Test Bank",
      8
      "issuer_country": "MU",
      9
      "issuer_country_name": "Mauritius",
      10
      "product_id": "F",
      11
      "product_type": "Visa Classic",
      12
      "card_payouts": {
      13
      "domestic_non_money_transfer": "not_supported",
      14
      "cross_border_non_money_transfer": "standard",
      15
      "domestic_gambling": "fast_funds",
      16
      "cross_border_gambling": "unknown",
      17
      "domestic_money_transfer": "unknown",
      18
      "cross_border_money_transfer": "not_supported"
      19
      }
      20
      }

      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.

      Endpoints

        post

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

        Request example

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

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

          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.

          Endpoints

            post

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

            Request example

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

            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

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

              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, instrument, or full card details instead.

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

              Endpoints

                post

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

                Request example

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

                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

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

                  Testing

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

                  Non-money transfer

                  Test cardDomestic non-money transferCross 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

                  5596061690670931

                  standard

                  standard

                  Money transfer

                  Test cardDomestic money transferCross 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

                  5596061690670931

                  standard

                  standard

                  Gambling

                  Test cardDomestic gamblingCross 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

                  unknown

                  unknown

                  5558468902774508

                  unknown

                  unknown

                  5596061690670931

                  unknown

                  unknown