Recurring payments with stored card details

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 transactions in the payment series, without the cardholder being present. These types of transactions are referred to as merchant-initiated transactions (MITs).

The initial cardholder-initiated transaction (CIT), in which the customer is setting 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 Strong Customer Authentication (SCA) mandated regions, you must enable 3D Secure authentication for the transaction by setting 3ds.enabled to true. If the transaction qualifies, you can also make use of 3DS exemptions.

You must also set 3ds.challenge_indicator to challenge_requested_mandate to prevent subsequent card-not-present (CNP) transactions from being declined.

See our SCA compliance guide for more information.

json
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}

json
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 transactions in the payment series without the cardholder being present. For example, if the customer is paying via auto-renewal at the end of a subscription period.

MIT payment requests must include:

• "payment_type": "Installment" or "payment_type": "Recurring"
• "merchant_initiated": true

You must also include the payment ID returned in the initial payment’s response in the previous_payment_id field.

Alternatively, you can supply the ID of the previous transaction in the payment series.

If the previous transactions in the payment series were processed by an acquirer other than Checkout.com, you can instead supply the scheme transaction ID in the previous_payment_id field. This means you do not have to request payment details from the customer again.

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.

json
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}

json
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}