About stored card details

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.

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

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

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.

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

{
    "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"
    }
}

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

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.

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

{
    "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 and installments are also referred to as scheduled payments.

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

All subsequent payments must be an MIT and must include:

{
    "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"
    }
}

{
    "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"
}