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

  • 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 sourceFirst payment attributesSecond payment attributes
Full card APIn/a
  • source.stored: true
Source IDn/an/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 sourceFirst cardholder-initiated payment attributesSecond 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 sourceFirst cardholder-initiated payment attributesSecond 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 sourceFirst payment attributesSecond payment attributes
Full card APIn/a
  • merchant_initiated: true
  • source.stored: true
  • previous_payment_id: "payment_id"
Source IDn/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 verificationStandard payment series

1: Card verification

Can be used for previous payment ID.

1: Payment #1

Can be used for previous payment ID.

2: Payment #12: Payment #2
3: Payment #23: 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.