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 the previous_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 have merchant_initiated set to false. All subsequent payments in the series should include payment_type: "Recurring", merchant_initiated: true and the previous_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.stored: true`
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	`payment_type: "Recurring"` `merchant_initiated: false`	`merchant_initiated: true` `source.stored: true` `payment_type: "Recurring"` `previous_payment_id: "payment_id"`
Source ID	`payment_type: "Recurring"` `merchant_initiated: false`	`merchant_initiated: true` `payment_type: "Recurring"` `previous_payment_id: "payment_id"`

Payment source	First cardholder-initiated payment attributes	Second payment attributes
Full card API	`merchant_initiated: false`	`merchant_initiated: true` `source.stored: true` `payment_type: "Recurring"` `previous_payment_id: "payment_id"`
Source ID	`merchant_initiated: false`	`merchant_initiated: true` `payment_type: "Recurring"` `previous_payment_id: "payment_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	n/a	`merchant_initiated: true` `source.stored: true` `previous_payment_id: "payment_id"`
Source ID	n/a	`merchant_initiated: true` `previous_payment_id: "payment_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

What do I do if a subscription flow involves both scheduled and unscheduled payments?

Card schemes handle scheduled (recurring) and unscheduled (not recurring) payments differently, so it's important that you include the proper identifiers in your payment requests to distinguish between these two types of merchant-initiated transactions (MITs). See above for the attributes required for scheduled and unscheduled MITs.

If I save card details after a payment, should I include the previous_payment_id in following payments made with that saved card?

If you are initiating payments with saved card details—a merchant-initiated transaction (MIT)—then, yes, you must submit the previous_payment_id with your payment requests. This links the subsequent MITs with the initial transaction made by the cardholder.

If the cardholder is making further transactions with their saved card—a cardholder-initiated transaction (CIT)—then you don't need to include the previous_payment_id. But you should include "source.stored": true in the request, to flag that the payment is being made with a saved card.

Do I need to add the merchant_initiated field for installments?

For the first customer-initiated transaction in the installment plan, you should add "merchant_initiated": false to your request. For all following installments you initiate, you must include "merchant_initiated": true. See the attributes required for scheduled merchant-initiated transactions above.

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.

Powered by Atlassian Confluence and Scroll Viewport.