Migrate to Checkout API v70

Find out more about the major changes in this release.

Checkout API v70 changes how you use tokenization and items for in a payment request for risk management.

This page describes how you upgrade your integration to use Checkout API v70.

Previously, you could set whether to store your shopper's payment details for recurring payments in the Customer Area, under Settings > Checkout settings > enableRecurring. As of Checkout API v70, you can no longer do this.

This means that from Checkout v70 onward, you manage all tokenization settings exclusively through the Checkout API.

Create a token

Your migration steps depend on whether you use a Sessions flow or Advanced flow.

To learn about the difference, see Additional use cases.

Sessions flow

Before v70, in /sessions requests:

You must set storePaymentMethod.
You optionally set recurringProcessingModel.

From v70 onwards, in /sessions requests:

You must set storePaymentMethodMode with one of the possible values.
You must set recurringProcessingModel. This parameter is now required.

Migrating to v70

To migrate, you need to update your front-end library to:

Web Drop-in and Components (v5.27.0 or newer)
iOS Drop-in and Components (v5.0.0 or newer)

You need to update your frontend library to display the checkbox in your checkout for your customer to give consent to store their payment details.

In the /sessions request, storePaymentMethodMode has the following options:

Value	Description
disabled	Your shopper's payment details are not stored.
askForConsent	The UI lets your shopper select whether they want their payment details to be stored.
enabled	Your shopper's payment details are stored.

To store the payment details for a payment using the /sessions endpoint:

Set storePaymentMethodMode to askForConsent or enabled.
Set a shopperReference.
Set a recurringProcessingModel. Previously, this was optional.

Advanced flow

recurringProcessingModel is now required when storing a shopper's payment details.

To store the payment details for a /payments request:

Optionally, to add a checkbox to the UI that lets your shopper select whether they want their payment details to be stored, in your Drop-in configuration or Component configuration, set enableStoreDetails to true.

Use the token

To learn about the difference between Sessions flow and Advanced flow, see Additional use cases.

Sessions flow

You do not need to make any changes to your integration.

Advanced flow

recurringProcessingModel is now required when you use a token to complete a recurring payment. Previously, this was optional.

Include line items for risk rules

In Checkout API v70, you can configure custom risk rules for items using the lineItems fields instead of additionalData.riskdata.basket.

v70 or later	v69 or earlier
`description`	`item.productTitle`
`amountIncludingTax`	`item.amountPerItem`
`itemCategory`	`item.category`
`quantity`	`item.quantity`
`id`	`item.id`
`color`	`item.color`
`brand`	`item.brand`
`manufacturer`	`item.manufacturer`
`receiverEmail`	`item.receiverEmail`
`size`	`item.size`
`sku`	`item.sku`
`upc`	`item.upc`

For example, to include two items with product title, category, and brand in your payment request:

Payment request with line items

 curl https://checkout-test.adyen.com/checkout/v70/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "paymentMethod": {
    "type": "scheme",
    "encryptedCardNumber": "test_4111111111111111",
    "encryptedExpiryMonth": "test_03",
    "encryptedExpiryYear": "test_2030",
    "encryptedSecurityCode": "test_737"
  },
  "lineItems":[
    {
      "description": "Gold shoes",
      "category": "Footwear",
      "brand": "Adyen"
    },
    {
      "description": "Gold hat",
      "category": "Accessories",
      "brand": "Adyen"
    }
  ]
}'