Skip to content

Requirements for stored payment details

Last updated: 6th July 2022

Whether you securely store a customer’s card details in full, or in a tokenized form, card schemes like Visa and Mastercard require additional information in the payment request. A stored card details payment request sent without these details has a higher risk of being declined.


Transaction types

Payment requests made with stored details can be either cardholder-initiated transactions (CITs) or merchant-initiated transactions (MITs). In both scenarios, you must ask for cardholder consent before storing credentials. Please refer to the consent requirement section in Visa’s ‘Improving Authorization Management for Transactions with Stored Credentials’.

  • CITs: The cardholder initiates the payment and authorizes the use of their stored card details. For example, when a cardholder orders takeaway food using a card previously stored with the merchant. The cardholder is always present in CITs.
  • MITs: Merchants trigger these payments with the cardholder's consent, using stored card details. The cardholder is not present in MITs.

Payment types

In both the initial and subsequent payment requests, you must specify the type of payment. Our Unified Payments API accepts 3 payment types, and these should be included with the payment_type field.

  • Regular: This is a one-off e-commerce payment, or for one-click purchases using stored details. For example, a cardholder buying an item from a shop using their web or mobile browser.
  • MOTO: This is mail order or telephone order. For example, a cardholder makes a payment over the phone.
  • Recurring: For example, a cardholder has performed their initial transaction of a series of subsequent payments for a subscription.

Initial payment request with intent to store

When taking an initial payment for goods or services, you can store a cardholder's details for future reuse. For example, you may want to perform a card verification for subsequent payments, or offer a smoother checkout experience when your customer next visits your website.

To store a cardholder’s details, add "store_for_future_use": true in the source object of your initial payment request. If omitted, the value will be set to true by default.

For SCA-mandated countries, you must also set 3ds.enabled to true and 3ds.challenge_indicator to challenge_requested_mandate to comply with regulation. Please see our SCA compliance guide for various business scenarios.

If you do not want to store the cardholder's details, you must specify this by adding "store_for_future_use": false in the source object of your initial payment request.

If store_for_future_use is set to false, then a payment instrument will not be included in the payment response.

Request examples

These requests are made using our Unified Payments API. Use our API reference for a more detailed explanation of required and optional fields.

    You must be PCI DSS compliant to store full card details.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    {
    "source": {
    "type": "card",
    "number": 4242424242424242,
    "expiry_month": 10,
    "expiry_year": 2026,
    "store_for_future_use": true
    },
    "amount": 5000,
    "currency": "USD",
    "payment_type": "Recurring",
    "3ds": {
    "enabled": true,
    "challenge_indicator": "challenge_requested_mandate"
    }
    }

    Subsequent payment requests with stored details

    When requesting subsequent payments in a merchant-initiated transaction series, there are specific fields that you should include in your request. The required fields change depending on the type of transaction, and whether you’re using full card details or a tokenized reference. It is important to include the correct fields in your request to fulfill Strong Customer Authentication (SCA) requirements.

    If you have stored the full card details on your own server for any payment type, you must state this by including ”stored”: true in the source object. If you have used a token or a source ID to store the details, you do not need to include any additional fields.

    Reference to a previous payment

    Use the field previous_payment_id to reference the opening transaction of the payment series, or the previous transaction if you’re not able to locate the reference for the opening transaction. The previous_payment_id is the payment_id issued after the authorization of the relevant payment.

    Your previous payment ID will contain the prefix pay_, if the previous payment was processed by Checkout.com, for example, pay_fou2pabzc6we5obvmcwum5ns5e. If another acquirer processed your previous subscriptions and other recurring payments, you can use the scheme transaction ID as your previous_payment_id to process those payments with us, with no need to take the customer's details again.

    Request examples

    These requests are made using our Unified Payments API. Use our API reference for a more detailed explanation of required and optional fields.

      You must be PCI DSS compliant to store full card details.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      {
      "source": {
      "type": "card",
      "number": 4242424242424242,
      "expiry_month": 10,
      "expiry_year": 2026,
      "stored": true
      },
      "amount": 5000,
      "currency": "USD"
      "merchant_initiated": true,
      "payment_type": "Recurring",
      "previous_payment_id": "pay_previouspaymentid"
      }

      Recurring payments

      Recurring payments are also referred to as scheduled payments.

      For scheduled payments, the initial transaction must be a CIT and include:

      • ”payment_type:” “Recurring”
      • ”merchant_initiated”: false

      All subsequent payments must be an MIT and must include:

      • ”merchant_initiated”: true
      • ”payment_type”: “Recurring”
      • ”previous_payment_id”: {id}
      • "3ds.enabled": false – read more about why you need to send this on the SCA compliance guide

      Request examples

      Initial request

        You must be PCI DSS compliant to store full card details.

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        {
        "source": {
        "type": "card",
        "number": 4242424242424242,
        "expiry_month": 10,
        "expiry_year": 2026,
        "store_for_future_use": true
        },
        "amount": 5000,
        "currency": "USD",
        "merchant_initiated": false,
        "payment_type": "Recurring",
        "3ds": {
        "enabled": true,
        "challenge_indicator": "challenge_requested_mandate"
        }
        }

        Subsequent requests

          You must be PCI DSS compliant to store full card details.

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          {
          "source": {
          "type": "card",
          "number": 4242424242424242,
          "expiry_month": 10,
          "expiry_year": 2026,
          "stored": true
          },
          "amount": 5000,
          "currency": "USD",
          "payment_type": "Recurring",
          "merchant_initiated": true,
          "previous_payment_id": "pay_previouspaymentid"
          }