Skip to content

Last updated: February 15, 2023

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


Store card details during the initial transaction

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.

SCA requirements

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.

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, we automatically upgrade the payment to 3DS and retry the transaction.

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.

Request example

post

https://api.checkout.com/payments

Information

SAQ D and SAQ A are, respectively, the highest and lowest forms of PCI compliance. 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
}

Response example

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
}

Request a payment in a subsequent MIT

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.

SCA requirements

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.

Request example

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
}

Response example

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
}