Stored card details
If you store customers' card details (whether in full on your server, or in a tokenized form) to allow cardholder-initiated transactions (CITs) and merchant-initiated transactions (MITs), you need to provide extra information about these payments to satisfy card scheme requirements.
We've introduced a new merchant_initiated
field to our API, which you must set to true
in all merchant-initiated transactions.
Easily transfer recurring payments to Checkout.com
If you're considering us as your payment service provider but your subscriptions and other recurring payments are currently processed by another acquirer—no problem! You can use the scheme transaction ID from a payment processed by your current acquirer as your previous_payment_id
to start processing those payments with us, with no need to take the customer's details again.
Additional attributes for your saved card payment requests
Below is a summary of the attributes you need to add to payment requests that use stored card details. These additional details help fulfill Strong Customer Authentication (SCA) requirements, and give the issuing bank what they need to approve such payments.
See the sections on cardholder-initiated transactions and merchant-initiated transactions further down for more detail.
Cardholder-initiated and merchant-initiated transactions
- If you use our full card API, storing customers' full card details on your server, you need to flag that you are using previously stored card details by including
source.stored: true
in the request.
Merchant-initiated transactions only
For both scheduled and unscheduled MITs, you must include the
merchant_initiated: true
flag to mark the payment as merchant-initiated, and reference either the original cardholder-initiated payment or the previous payment in the series of transactions using theprevious_payment_id
attribute.
The initial cardholder-initiated transaction of a scheduled recurring series should not be marked as
"Recurring"
(unless it is a Visa card, in which case it must be marked as"Recurring"
) and it should havemerchant_initiated
set tofalse
. All subsequent payments in the series should includepayment_type: "Recurring"
,merchant_initiated: true
and theprevious_payment_id
.
Cardholder-initiated transactions
In cardholder-initiated transactions (CITs), the cardholder initiates the payment and authorizes the use of their stored card details. For example, a cardholder ordering takeaway food and using a card previously stored with the merchant.
Required attributes for CITs
Payment source | First payment attributes | Second payment attributes |
---|---|---|
Full card API | n/a |
|
Source ID | n/a | n/a |
Merchant-initiated transactions
Merchant-initiated transactions (MITs) are payments you trigger, where the cardholder has previously consented to you carrying out such payments. These may be scheduled (such as recurring payments and installments) or unscheduled (like account top-ups triggered by balance thresholds and no-show charges).
Scheduled
These are regular payments using stored card details, like installments or a monthly subscription fee.
Required attributes for scheduled MITs
Add a card for scheduled MITs
If you're adding a customer card for later scheduled billing without taking a payment, you need to include payment_type: "Recurring"
in your request.
Payment source | First cardholder-initiated payment attributes | Second payment attributes |
---|---|---|
Full card API |
|
|
Source ID |
|
|
Payment source | First cardholder-initiated payment attributes | Second payment attributes |
---|---|---|
Full card API |
|
|
Source ID |
|
|
Unscheduled
These are payments using stored card details that do not occur on a regular schedule, like top-ups for a digital wallet triggered by the balance falling below a certain threshold.
Required attributes for unscheduled MITs
Payment source | First payment attributes | Second payment attributes |
---|---|---|
Full card API |
|
|
Source ID |
|
|
Previous payment ID explained
Use the attribute previous_payment_id
to reference either the previous transaction or the opening transaction of the payment series. The previous_payment_id
is the payment_id
issued after the authorization of the relevant payment.
Your previous payment ID will contain the prefix pay_
, for example, pay_fou2pabzc6we5obvmcwum5ns5e
.
Using the previous payment ID
Scheduled and unscheduled MITs can begin in two ways: a card verification or a payment. In the example below, you could reference the previous_payment_id
as either row one or row four.
Series with card verification | Standard payment series |
---|---|
1: Card verification Can be used for previous payment ID. | 1: Payment #1 Can be used for previous payment ID. |
2: Payment #1 | 2: Payment #2 |
3: Payment #2 | 3: Payment #3 |
4: Payment#3 Can be used for previous payment ID. | 4: Payment #4 Can be used for previous payment ID. |
FAQs
Can we help?
Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.