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": 20267},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"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": true8},9"amount": 5000,10"currency": "USD",11"payment_type": "Recurring",12"merchant_initiated": true,13"previous_payment_id": "pay_paymentid"14}
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": 019},20"risk": {21"flagged": false22},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}