Recurring payments with stored card details

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

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.

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}


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.

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.

Information

If you do not pass a previous_payment_id value in your request, Checkout.com will automatically attempt to locate the ID from a previous transaction in the payment series.

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.

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}

We've made some changes to our API

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

Information

SCA requirements

Request example

Response example