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.
Set up an unscheduled payment agreement
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.
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": 20267},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}
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 an unscheduled payment
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, you should include the merchant_initiated_reason
field, set to one of the following options:
resubmission
– previous authorization attempt failed and transaction can be retrieddelayed_charge
– an additional charge after payment for the initial service has been processedno_show
– a penalty charged as agreed with the cardholderreauthorization
– split or delayed shipment, meaning the fulfillment takes place after the authorization validity time period
This improves issuer visibility over the intent of the transaction.
SCA requirements
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.
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": true8},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}
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": 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}