Unscheduled payments with stored card details

Last updated: March 15, 2023

With an unscheduled payment agreement, you can request to store a customer’s card details during an initial transaction and perform a payment with the stored card at a later date, without the cardholder present. 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 without the cardholder present.

MIT payment requests must include:

"payment_type": "Unscheduled"
"merchant_initiated": true

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

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 including the merchant_initiated_reason field set to resubmission, delayed_charge, no_show, or reauthorization. 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}

We've made some changes to our API

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

SCA requirements

Request example

Response example