Recurring payments with stored card details

Last updated: December 17, 2025

If a customer is setting up a series of repeat payments, you can store their card details during the initial cardholder-initiated transaction (CIT). For example, if they're paying for a product in installments or setting up a recurring payment for a subscription service.

You can then use the stored details to request payment for subsequent card-not-present (CNP) transactions in the payment series. These types of transactions are referred to as merchant-initiated transactions (MITs).

Note

MIT installments are not supported for American Express payments.

In regions that require Strong Customer Authentication (SCA), you must enable 3D Secure (3DS) authentication for the initial payment by setting 3ds.enabled to true in the initial payment request.

If you do not supply the required information, your payment request has a higher risk of declining with a 20154 response code. If this happens, we automatically upgrade the payment to 3DS and retry the transaction. See SCA compliance for more information.

You must also set 3ds.challenge_indicator to challenge_requested_mandate to prevent subsequent CNP transactions from being declined.

Information

If the transaction qualifies, you can also make use of 3DS exemptions.

For more information, see SCA compliance.

To store the card details during the CIT in which the customer sets up the agreement, call the Request a payment or payout endpoint with the following fields:

payment_type – Set to Installment or Recurring.
merchant_initiated – Set to false.

You do not need to set source.store_for_future_use to true. Installment and Recurring payments automatically request to store the cardholder's details.

post

https://api.checkout.com/payments


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


1{
2  "source": {
3    "type": "token",
4    "token": "tok_tokenguid"
5  },
6  "amount": 5000,
7  "currency": "USD",
8  "payment_type": "Recurring",
9  "merchant_initiated": false,
10  "3ds": {
11    "enabled": true,
12    "challenge_indicator": "challenge_requested_mandate"
13  }
14}


1{
2  "source": {
3    "type": "network_token",
4    "token": "4111111111111111",
5    "token_type": "vts",
6    "expiry_month": "10",
7    "expiry_year": "2025",
8    "eci": "06",
9    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
10  },
11  "amount": 5000,
12  "currency": "USD",
13  "payment_type": "Recurring",
14  "merchant_initiated": false,
15  "3ds": {
16    "enabled": true,
17    "challenge_indicator": "challenge_requested"
18  }
19}


1{
2  "id": "pay_4hlqceyyib5ezpxtpdpwfhwtda",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "3ds": {
6    "downgraded": false,
7    "enrolled": "Y"
8  },
9  "source": {
10    "type": "id",
11    "id": "src_nwd3m4in3hkuddfpjsaevunhdy"
12  },
13  "_links": {
14    "self": {
15      "href": "https://api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i"
16    },
17    "actions": {
18      "href": "https://api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i/actions"
19    },
20    "redirect": {
21      "href": "https://api.sandbox.checkout.com/redirect/act_y3oqhf46pyzuxjbcn2giaqnb44"
22    }
23  }
24}

The response returns a payment instrument, which contains the stored card details, in the source.id field. Use the payment instrument ID to request future payments.

Once the customer has set up a payment agreement, you can initiate subsequent CNP transactions in the payment series. For example, if the customer pays using auto-renewal at the end of a subscription period.

Call the Request a payment or payout endpoint with the following fields:
- payment_type – Set to Installment or Recurring.
- merchant_initiated – Set to true.
- previous_payment_id – Set to one of the following:
  - The payment ID of the initial CIT.
  - The payment ID of a previous MIT in the payment series.
  - The card scheme's transaction ID, if previous transactions in the payment series were processed by another payment service provider (PSP). The value you provide must meet the scheme's transaction ID requirements.

If you do not provide a previous_payment_id:

Checkout.com automatically attempts to retrieve the payment ID from the initial CIT in the payment series.
If the fallback mechanism fails to find a payment ID, we attempt to downgrade the MIT to a CIT and apply relevant exceptions.

Note

Do not use the fallback mechanism as your primary method of managing transaction IDs.

Information

The following table is not an exhaustive list of supported schemes. Other schemes that are not listed may have their own format requirements.

Card scheme	Requirements
Visa	The ID length must be 15 characters. The ID must start with number three, four, or five.
Mastercard	The ID length must be 13 characters. The first three characters must be a valid product code. The last four characters must be in `MMDD` format. For example, `0227`.
Diners Club	The ID length must be 15 characters. The ID must start with number one, seven, or eight.
Cartes Bancaires	The ID length must be 16 characters. The ID must be in hexadecimal format and start with number one.

Information

If the card scheme cannot find the original transaction ID, you may see an increase in soft declines.

Merchant-initiated transactions fall out of scope of SCA and qualify for exemption under the merchant-initiated exclusion, which means 3DS authentication is not required.

You can either set 3ds.enabled to false, or omit it from the request.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "id",
4    "id": "src_nwd3m4in3hkuddfpjsaevunhdy"
5  },
6  "amount": 5000,
7  "currency": "USD",
8  "payment_type": "Recurring",
9  "merchant_initiated": true,
10  "previous_payment_id": "pay_4hlqceyyib5ezpxtpdpwfhwtda"
11}

Note

If you process a payment with full card details or network tokens stored in a card-on-file system external to Checkout.com, you must set source.stored to true in the request.


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


1{
2  "source": {
3    "type": "network_token",
4    "token": "4111111111111111",
5    "token_type": "vts",
6    "expiry_month": "10",
7    "expiry_year": "2025",
8    "eci": "06",
9    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
10    "stored": true
11  },
12  "amount": 5000,
13  "currency": "USD",
14  "payment_type": "Recurring",
15  "merchant_initiated": true
16}

If you do not provide a previous_payment_id:

Checkout.com automatically attempts to retrieve the payment ID from the initial CIT in the payment series.
If the fallback mechanism fails to find a payment ID, we attempt to downgrade the MIT to a CIT and apply relevant 3DS exceptions.

Note

Do not use the fallback mechanism as your primary method of managing transaction IDs.

Merchant-initiated transactions (MIT) fall out of scope of SCA and qualify for exemption under the merchant-initiated exclusion, which means 3DS authentication is not required.

You can either set 3ds.enabled to false, or omit it from the request.


1{
2  "id": "pay_4prafl3phiyejkfrjtgzlh4kye",
3  "action_id": "act_ep5277oczf7u7lg6hrsscbt6xy",
4  "amount": 100,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "482LT5",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "balances": {
12    "total_authorized": 100,
13    "total_voided": 0,
14    "available_to_void": 100,
15    "total_captured": 0,
16    "available_to_capture": 100,
17    "total_refunded": 0,
18    "available_to_refund": 0
19  },
20  "risk": {
21    "flagged": false
22  },
23  "source": {
24    "id": "src_y4pwpefkykre7ijbeyxjsxdkf4",
25    "type": "card",
26    "expiry_month": 12,
27    "expiry_year": 2025,
28    "scheme": "Visa",
29    "last4": "4242",
30    "fingerprint": "005D09BED0F110E7B3B13407DF0167F6E68C2FEFAB094D49DA4B4BFAE459C569",
31    "bin": "424242",
32    "card_type": "CREDIT",
33    "card_category": "CONSUMER",
34    "issuer": "Test Bank",
35    "issuer_country": "GB",
36    "product_id": "F",
37    "product_type": "Visa Classic",
38    "payment_account_reference": ""
39  },
40  "processed_on": "2023-01-25T16:42:20.8748358Z",
41  "reference": "ORD-5023-4E89",
42  "scheme_id": "481108533665280",
43  "processing": {
44    "acquirer_transaction_id": "931228481108533665280",
45    "retrieval_reference_number": "302516931228"
46  },
47  "expires_on": "2023-02-01T16:42:20.8106477Z",
48  "_links": {
49    "self": {
50      "href": "https://api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i"
51    },
52    "actions": {
53      "href": "https://api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i/actions"
54    },
55    "redirect": {
56      "href": "https://api.sandbox.checkout.com/redirect/act_y3oqhf46pyzuxjbcn2giaqnb44"
57    }
58  }
59}

Information

You may be able to automatically retry failed payments if you configure scheduled retries, or enable automatic downtime retries.

Recurring payments with stored card details

Note

SCA requirements

Information

Store card details during the initial transaction

Request examples

Response example

Request a payment in a subsequent MIT

Note

Scheme transaction ID requirements

Information

Information

SCA requirements

Request example

Note

Note

Response example

Information