Stored card details

If you process recurring payments or perform merchant-initiated transactions (MITs)—and store customers' card details in full on your server or use tokenized cards via Checkout.com to do so—you are required, by both Visa and Mastercard, to provide extra information about these payments.

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.

Requirements

This section outlines the requirements introduced by Visa and Mastercard.

For Visa and Mastercard

  • When initiating a payment, the merchant must indicate whether they are using previously stored card details.
  • For recurring payments, the initial cardholder-initiated transaction (CIT) should not be marked as recurring, however, all subsequent payments in the subscription plan should be.

For Visa only

In recurring and unscheduled MITs, the merchant must reference either the originating payment or the previous payment.

Satisfying these requirements

To satisfy these requirements, we've introduced the following attributes to our endpoints.

AttributesDescription
source.stored

Set to true if you're making a payment with our full card API using card details previously stored on your server.

payment_type

Set this to recurring to indicate that the authorization or payment is part of a recurring plan.

previous_payment_id

Used to reference either the previous transaction or the opening transaction of the payment plan. The previous_payment_id is the payment_id issued after the authorization of the relevant payment.

Check which attributes apply to you by reading the applicable business models below.

Cardholder-initiated transactions

In cardholder-initiated transaction (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

Visa required attributes for CITs

Payment methodFirst: Payment attributes requiredSecond: Payment attributes required
Full card APIn/a
  • source.stored: true
Source IDn/an/a

Mastercard required attributes for CITs

Payment methodFirst: Payment attributes requiredSecond: Payment attributes required
Full card APIn/a
  • source.stored: true
Source IDn/an/a

Unscheduled merchant-initiated transaction 

An unscheduled transaction, using stored card details, for a fixed or variable amount where the cardholder has previously provided consent for the merchant to initiate future transactions using the stored details. For example, topping up a digital wallet that has fallen below a certain threshold.

Required attributes for unscheduled MITs

Visa required attributes for unscheduled MITs

Payment methodFirst: Payment attributes requiredSecond: Payment attributes required
Full card APIn/a
  • source.stored: true
  • previous_payment_id: "payment_id"
Source IDn/a
  • previous_payment_id: "payment_id"

Mastercard required attributes for unscheduled MITs

Payment methodFirst: Payment attributes requiredSecond: Payment attributes required
Full card APIn/a
  • source.stored: true
  • previous_payment_id: "payment_id"
Source IDn/a
  • previous_payment_id: "payment_id"

Recurring payments

Recurring payments are scheduled payments to pay for products or services that occur on a regular basis. For example, a cardholder paying an on-demand television provider's monthly subscriptions fee.

Add a card for recurring payments

When adding a customer card for recurring payments (for example, using card verification), you do not need to mark the payment as payment_type: 'recurring' in your request.

Required attributes for recurring payments 

Visa required attributes for recurring payments

Payment methodFirst: Payment attributes requiredSecond: Payment attributes required
Full card APIn/a
  • source.stored: true
  • payment_type: "Recurring"
  • previous_payment_id: "payment_id"
Source IDn/a
  • payment_type: "Recurring"
  • previous_payment_id: "payment_id"

Mastercard required attributes for recurring payments

Payment methodFirst: Payment attributes requiredSecond: Payment attributes required
Full card APIn/a
  • source.stored: true
  • payment_type: "Recurring"
  • previous_payment_id: "payment_id"
Source IDn/a
  • payment_type: "Recurring"
  • 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_B41BEAAC175U76BD3EE1.

Example: Using the previous payment ID

Recurring payments and unscheduled MITs can begin in two ways: a card verification or a payment. In the example below, a user could reference their previous_payment_id as either row one or row four.

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.

Can we help?

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