Unscheduled payments with stored card details

Last updated: November 20, 2024

With an unscheduled payment agreement, you can request to store a customer’s card details during an initial transaction and perform a card-not-present (CNP) transaction with the stored card at a later date. These types of transactions are referred to as merchant-initiated transactions (MITs).

For example, a customer may provide their card details when checking in to a hotel, but will only be charged after they check out, at which point they may have incurred additional charges.

To obtain consent for an unscheduled payment via a card verification transaction, set amount to 0 and payment_type to Unscheduled in the payment request.

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

Information

Alternatively, you can perform an initial transaction in which amount is set to a non-zero value and store_for_future_use is set to true. This is similar to the recurring payment flow.

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": 0,
9  "currency": "USD",
10  "payment_type": "Unscheduled",
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": 0,
7  "currency": "USD",
8  "payment_type": "Unscheduled",
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 you’ve set up an unscheduled payment agreement with your customer, you can request a payment at a later date and perform a CNP transaction.

MIT payment requests must include:

"payment_type": "Unscheduled"
"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.

If you are SAQ D PCI-compliant and have stored the full card details for any payment type, you must set source.stored to true in the request.

If you are SAQ A compliant, and you used a token or a source ID to request a payment, you do not need to include any additional fields.

If you used a token or a source ID to request a payment, you do not need to include any additional fields.

To improve your approval rates and chargeback processes, we recommend that you include the merchant_initiated_reason field and set it to one of the following:

resubmission – Use when the original purchase has occurred, but you could not get authorization at the time that goods or services were provided. For example, when goods or services were provided, but the post-event authorization request was declined for insufficient funds.
delayed_charge – Use when there is a delayed charge. For example, in travel and cruise environments, where a delayed charge is used to complete a supplemental account charge after original services were provided.
no_show – Use when the cardholder entered into an agreement to purchase but they failed to meet the terms of the agreement.
reauthorization – Use when an additional purchase was made after the original purchase, typically for delayed or split orders.

This improves issuer visibility over the intent of the transaction.

Merchant-initiated transactions fall out of scope of SCA and qualify for exemption under 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": "Unscheduled",
12  "merchant_initiated": true,
13  "previous_payment_id": "pay_paymentid",
14  "processing": {
15    "merchant_initiated_reason": "delayed_charge"
16  }
17}


1{
2  "source": {
3    "type": "id",
4    "id": "src_instrumentguid"
5  },
6  "amount": 5000,
7  "currency": "USD",
8  "payment_type": "Unscheduled",
9  "merchant_initiated": true,
10  "previous_payment_id": "pay_paymentid",
11  "processing": {
12    "merchant_initiated_reason": "delayed_charge"
13  }
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": 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.

Unscheduled payments with stored card details

Set up an unscheduled payment agreement

Information

SCA requirements

Note

Request example

Information

Response example

Request an unscheduled payment

Information

SCA requirements

Request example

Response example

Information