Recurring payments with stored card details

Last updated: January 22, 2025

If a customer is setting up a series of repeat payments, you can store their card details during the initial transaction. 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).

The initial cardholder-initiated transaction (CIT), in which the customer sets up the agreement, must include the following in the request:

"payment_type": "Installment" or "payment_type": "Recurring"
"merchant_initiated": false

As installments and recurring payments require you to store the cardholder’s details, you do not need to explicitly provide the store_for_future_use flag in the request.

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

Note

If you do not supply the required information, your request has a higher risk of being declined with a 20154 response code. If this happens, Checkout.com automatically upgrades the payment to 3DS and retry the transaction.

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

See the SCA compliance guide for more information.

post

https://api.checkout.com/payments

Information

SAQ D and SAQ A are the highest and lowest forms of PCI compliance, respectively. Learn more about PCI compliance.


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  "id": "pay_4hlqceyyib5ezpxtpdpwfhwtda",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "3ds": {
6    "downgraded": false,
7    "enrolled": "Y"
8  },
9  "_links": {
10    "self": {
11      "href": "https://api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i"
12    },
13    "actions": {
14      "href": "https://api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i/actions"
15    },
16    "redirect": {
17      "href": "https://api.sandbox.checkout.com/redirect/act_y3oqhf46pyzuxjbcn2giaqnb44"
18    }
19  }
20}

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

In your MIT payment request, set:

payment_type to Installment or Recurring
merchant_initiated to true

You must also provide one of the following values in the previous_payment_id field:

The payment ID from the initial CIT.
The payment ID from 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 adhere to 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, Checkout.com attempts to downgrade the MIT to a CIT and apply relevant exceptions.

Note

Do not use the fallback mechanism as your primary method of transaction ID management.

Scheme	Requirements
Visa	ID length must be 15 characters. ID must start with number 3, 4, or 5.
Mastercard	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	ID length must be 15 characters. ID must start with number 1, 7, or 8.
Cartes Bancaires	ID length must be 16 characters. ID must be in hexadecimal format and start with number 1.

Information

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

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

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

post

https://api.checkout.com/payments


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_paymentid"
14}


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


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

Store card details during the initial transaction

SCA requirements

Note

Request example

Information

Response example

Request a payment in a subsequent MIT

Note

Scheme transaction ID requirements

Information

SCA requirements

Request example

Response example

Information