Checkout icon

Migrate to Checkout API

Migrate your Classic API integration to Checkout API.

Adyen no longer develops or updates our Classic API. We recommend that you migrate your integration to use the latest version of Checkout API for the following benefits:

  • A single integration to process all payment methods, including cards, bank-based, and alternative payment methods.
  • A simpler client-side integration with Drop-in/Components that is only available with the Checkout API.
  • Improved 3D Secure 2 authentication for payments. This includes simpler integration and the auto-authorization feature which reduces integration errors and failed payments.
  • An integration that adheres to latest security standards, like JSON Web Encryption (JWE) and JSON Web Signature (JWS), and offers your shoppers a more secure checkout process.
  • A simple, developer-friendly integration experience that handles many of the complexities of processing payments with less code complexity.
  • More specific error responses that makes debugging easier.

When you migrate to Checkout API, changes affect payment authentication, authorization and modification changes. Other processes and credentials, like reporting, reconciliation, webhooks, and API authentication keys do not change.

Supported features

The following table shows the features supported in Classic API and Checkout API:

Feature Classic API Checkout API
Card payments -white_check_mark- -white_check_mark-
3D Secure 2 authentication -white_check_mark- -white_check_mark-
Drop-in/Components for web, mobile, and cross-platform -white_check_mark-
Hosted Checkout -white_check_mark-
Pay by Link -white_check_mark-
Donations with Adyen Giving -white_check_mark-
Creating orders that allow for partial payments -white_check_mark-
Usage analytics -white_check_mark-

How to migrate

Follow this guide to migrate to Checkout API v71 or later.

While you make your updates, you can continue to use your existing Classic API integration to process live payments.

After testing your Checkout API integration, you can go live and start processing live payments with it.

To migrate your integration, do the following:

  1. Update settings in Customer Area.
  2. Update your endpoints.
  3. Update your request objects.
  4. Implement cards brand check.
  5. Handle additional actions
  6. Request additional configuration (optional)
  7. Handle new errors.
  8. Test your updates.
  9. Go live.

Use our API library

When you migrate to Checkout API, we recommend that you use one of our API libraries, available in many languages, to help you make requests.

If you use an API library for your Classic API integration, migrate to the latest version to get the latest changes for Checkout API.

Update settings in Customer Area

In your Customer Area, do the following:

  • Make sure that your API credential has the Checkout webservice user role.
    1. In your Customer Area, go to Developers > API credentials.
    2. From the list of users, select the user whose credentials you want to use to make Checkout API requests.
    3. Under Permissions, in the Roles, under UNCATEGORIZED, select Checkout webservice role.
  • Turn on additional data that you want to get it in your Checkout API responses.
    1. In your Customer Area, go to Developers > Additional data.
    2. Select the fields that you want to get.

You continue to get the same reports in your Customer Area when you migrate to Checkout API.

Update your endpoints

The following tables show the base URL and endpoints that you must update from Classic API to Checkout API.

Base URL

Environment Classic Checkout
Test https://pal-test.adyen.com/pal/servlet/Payment/{VERSION} https://checkout-test.adyen.com/{VERSION}
Live https://{PREFIX}-pal-live.adyenpayments.com/pal/servlet/Payment/{VERSION} https://{PREFIX}-checkout-live.adyenpayments.com/{VERSION}

You can find your URL prefixes for the live environment in your live Customer Area:

  1. Go to Developers > API URLs.
  2. Select the endpoint that corresponds to the region that the account operates in. For example, if you are located in India, you must use a URL in the India (IN) region.

Endpoints

Change the following endpoints for each corresponding action.

Append each endpoint to the base URL.

Action Classic Checkout
Get a list of available payment methods. Not available. /paymentMethods
Make a payment. /authorise /payments
Authorize a payment after 3D Secure 2 authentication. authorise3d and /authorise3ds2 /payments/details
Refund a captured payment with its pspReference. /refund /payments/{paymentPspReference}/refunds
Cancel an authorization with its pspReference. /cancel /payments/{paymentPspReference}/cancels
Cancel an authorization without its pspReference. /technicalCancel /cancels
Capture a payment. /capture /payments/{paymentPspReference}/captures
If you do not know the status of a payment, refund or cancel the payment. /cancelOrRefund /payments/{paymentPspReference}/reversals
Update the amount of an authorized payment. /adjustAuthorisation /payments/{paymentPspReference}/amountUpdates
For redirect payment methods, send payment data after the redirect. Not available. /payments/details
Get the list of brands on a card. Not available. /cardDetails
Make a donation through Adyen Giving. Not available. /donations
Get a list of your active donation campaigns. Not available. /donationCampaigns
Create a Pay by Link payment link. Not available. /paymentLinks

Update your request objects

The request objects in Classic API and Checkout API are different. You must update the parameters for each object.

Data format

The required data format for Checkout API is JSON. If your Classic API integration uses XML data, you must change your request objects to JSON instead.

The following examples show the differences in the request objects between Classic API and Checkout API, in JSON format.

If you are not PCI-compliant, use one of Adyen's client-side solutions to encrypt card details.

After encrypting card details, make a payment request with the encrypted card details.

Parameters

Classic API Checkout API
amount amount
additionalData.card.encrypted.json paymentMethod
Not applicable. paymentMethod.type
Not applicable. paymentMethod.encryptedCardNumber
Not applicable. paymentMethod.encryptedExpiryMonth
Not applicable. paymentMethod.encryptedExpiryYear
Not applicable. paymentMethod.encryptedSecurityCode
Not applicable. paymentMethod.holderName
reference reference
merchantAccount merchantAccount
Not applicable. returnUrl

Classic API

To make a basic card payment with encrypted card details, include the following in the /authorise request:

Checkout API

To make a basic card payment with encrypted card details, include the following in the /payments request:

You must be PCI compliant to use unencrypted card details.

Make a request for a card payment with unencrypted card details.

Parameters

Classic API Checkout API
amount amount
Not applicable. paymentMethod.type
card.number paymentMethod.number
card.expiryMonth paymentMethod.expiryMonth
card.expiryYear paymentMethod.expiryYear
cvc paymentMethod.cvc
holderName paymentMethod.holderName
reference reference
merchantAccount merchantAccount
Not applicable. returnUrl

Classic API

To make a basic card payment, include the following in the /authorise request:

Checkout API

To make a card payment, include the following in the /payments request:

Make a request to store the shopper's card details.

Parameters

Classic API Checkout API
amount amount
additionalData.card.encrypted.json paymentMethod
Not applicable. paymentMethod.type
Not applicable. paymentMethod.encryptedCardNumber
Not applicable. paymentMethod.encryptedExpiryMonth
Not applicable. paymentMethod.encryptedExpiryYear
Not applicable. paymentMethod.encryptedSecurityCode
Not applicable. paymentMethod.holderName
reference reference
merchantAccount merchantAccount
shopperEmail shopperEmail
shopperIP shopperIP
shopperReference shopperReference
recurring Not applicable.
recurringProcessingModel recurringProcessingModel
Not applicable. storePaymentMethod
Not applicable. returnUrl

Classic API

To store the shopper's card details (in this example, for one-off payments), include the following in the /authorise request:

Checkout API

To store the shopper's card details (in this example, for one-off payments), include the following in the /payments request:

Make a request for a one-off payment with stored card details.

Parameters

Classic API Checkout API
amount amount
additionalData.card.encrypted.json paymentMethod.type
Not applicable. paymentMethod.encryptedSecurityCode
selectedRecurringDetailReference paymentMethod.storedPaymentMethodId
reference reference
merchantAccount merchantAccount
shopperEmail shopperEmail
shopperIP shopperIP
shopperInteraction shopperInteraction
recurringProcessingModel recurringProcessingModel
shopperReference shopperReference
recurring.contract Not applicable.
Not applicable. returnUrl

Classic API

To make a one-off payment with stored card details, include the following in the /authorise request:

Checkout API

To make a one-off payment with stored card details, include the following in the /payments request:

Make a request for a subscription payment with stored card details.

Parameters

Classic API Checkout API
amount amount
Not applicable. paymentMethod.type
Not applicable. paymentMethod.encryptedSecurityCode
selectedRecurringDetailReference paymentMethod.storedPaymentMethodId
reference reference
merchantAccount merchantAccount
shopperEmail shopperEmail
shopperIP shopperIP
shopperReference shopperReference
shopperInteraction shopperInteraction
recurringProcessingModel recurringProcessingModel
recurring Not applicable.
Not applicable. storePaymentMethod
Not applicable. returnUrl

Classic API

To make a subscription payment with stored card details, include the following in the /authorise request:

Checkout API

To make a subscription payment with stored card details, include the following in the /payments request:

Make a request for a payment with native 3D Secure 2 authentication. Use our native 3D Secure 2 Component to handle 3D Secure 2 authentication.

Parameters

Classic API Checkout API
amount amount
reference reference
merchantAccount merchantAccount
additionalData.card.encrypted.json paymentMethod.type
Not applicable paymentMethod.encryptedCardNumber
Not applicable. paymentMethod.encryptedExpiryMonth
Not applicable. paymentMethod.encryptedExpiryYear
Not applicable. paymentMethod.encryptedSecurityCode
Not applicable. paymentMethod.holderName
threeDS2RequestData.mobilePhone threeDS2RequestData.mobilePhone
threeDS2RequestData.deviceChannel channel
threeDS2RequestData.notificationURL Not applicable.
browserInfo browserInfo
shopperIP shopperIP
shopperReference shopperReference
Not applicable. billingAddress
shopperEmail shopperEmail
Not applicable. origin
Not applicable. returnUrl

Classic API

To make a payment for native 3D Secure 2 authentication, include the following in the /authorise request:

Checkout API

To make a payment for native 3D Secure 2 authentication, include the following in the /payments request:

Make a request for a payment with 3D Secure 2 redirect authentication. Use our redirect 3D Secure 2 Component to handle redirect 3D Secure 2 authentication.

Parameters

Classic API Checkout API
amount amount
reference reference
merchantAccount merchantAccount
additionalData.card.encrypted.json paymentMethod.type
Not applicable paymentMethod.encryptedCardNumber
Not applicable. paymentMethod.encryptedExpiryMonth
Not applicable. paymentMethod.encryptedExpiryYear
Not applicable. paymentMethod.encryptedSecurityCode
Not applicable. paymentMethod.holderName
browserInfo browserInfo
shopperReference shopperReference
shopperEmail shopperEmail
shopperIP shopperIP
Not applicable. billingAddress
Not applicable. channel
Not applicable. origin
Not applicable. returnUrl

Classic API

To make a payment with 3D Secure 2 redirect authentication, include the following in the /authorise request:

Checkout API

To make a payment with 3D Secure 2 redirect authentication, include the following in the /payments request:

Make a request for refund.

Parameters

Classic API Checkout API
amount amount
merchantAccount merchantAccount
reference reference
originalReference Path parameter: paymentPspReference

Classic API

To make a refund, include the following in the /refund request:

Checkout API

To make a refund, include the following in the /payments/{paymentPspReference}/refunds request:

Make a request to cancel a payment.

Parameters

Classic API Checkout API
merchantAccount merchantAccount
reference reference
originalReference Path parameter: paymentPspReference

Classic API

To cancel a payment, include the following in the /cancel request:

Checkout API

To cancel a payment, include the following in the /payments/{paymentPspReference}/cancels request:

Make a request to capture a payment.

Parameters

Classic API Checkout API
modificationAmount amount
merchantAccount merchantAccount
reference reference
originalReference Path parameter: paymentPspReference

Classic API

To capture a payment, include the following in the /capture request:

Checkout API

To capture a payment, include the following in the /payments/{paymentPspReference}/captures request:

Make a request for reversal. Use this when you do not know if a payment was already captured.

Parameters

Classic API Checkout API
merchantAccount merchantAccount
reference reference
originalReference Path parameter: paymentPspReference

Classic API

To reverse (cancel or refund) a payment, include the following in the /cancelOrRefund request:

Checkout API

To To reverse (cancel or refund) a payment, include the following in the /payments/{paymentPspReference}/reversals request:

Make a request to adjust the amount of an authorized payment.

Parameters

Classic API Checkout API
modificationAmount amount
merchantAccount merchantAccount
reference reference
additionalData.industryUsage industryUsage
originalReference Path parameter: paymentPspReference
Not applicable. lineItems

Classic API

To adjust an authorized amount, include the following in the /adjustAuthorisation request:

Checkout API

To adjust an authorized amount, include the following in the /payments/{paymentPspReference}/amountUpdates request:

Make a request for a payment with third-party authentication. The parameters you include depend on the authentication data from the third party.

Parameters

Classic API Checkout API
amount amount
additionalData.card.encrypted.json paymentMethod
Not applicable. paymentMethod.type
selectedBrand
For co-badged cards.		 paymentMethod.brand
For co-badged cards.
Not applicable. paymentMethod.encryptedCardNumber
Not applicable. paymentMethod.encryptedExpiryMonth
Not applicable. paymentMethod.encryptedExpiryYear
Not applicable. paymentMethod.encryptedSecurityCode
Not applicable. paymentMethod.holderName
additionalData.scaExemption
For Cartes Bancaires.		 additionalData.scaExemption
For Cartes Bancaires.
additionalData.acquirerCode
For Cartes Bancaires.		 additionalData.acquirerCode
For Cartes Bancaires.
merchantAccount merchantAccount
reference reference
mpiData.cavv mpiData.cavv
mpiData.eci mpiData.eci
mpiData.dsTransID mpiData.dsTransID
mpiData.directoryResponse mpiData.directoryResponse
mpiData.authenticationResponse mpiData.authenticationResponse
mpiData.threeDSVersion mpiData.threeDSVersion
mpiData.cavvAlgorithm
For Cartes Bancaires.		 mpiData.cavvAlgorithm
For Cartes Bancaires.
mpiData.challengeCancel
For Cartes Bancaires.		 mpiData.challengeCancel
For Cartes Bancaires.
mpiData.riskScore
For Cartes Bancaires.		 mpiData.riskScore
For Cartes Bancaires.
threeDS2RequestData.threeDSRequestorChallengeInd
For Cartes Bancaires.		 threeDS2RequestData.threeDSRequestorChallengeInd
For Cartes Bancaires.
Not applicable. channel
Not applicable. shopperInteraction
Not applicable. recurringProcessingModel

Classic API

To make a payment with third-party authentication, include the following in the /authorise request:

The parameters you include depend on the authentication data from the third party.

Checkout API

To make a payment with third-part authentication, include the following in the /payments request:

The parameters you include depend on the authentication data from the third party.

Implement card brands check

To comply with co-badge card regulations, follow instructions to show co-badged cards.

Handle additional actions

The /payments response includes information about the current status of the payment. If the response includes the action object, you must handle an additional action before the payment cant be completed.

What you must do depends on the action.type:

action.type Description Next steps
voucher The shopper gets a voucher which they will use to complete the payment later. 1. Show the voucher.
2. After the shopper completes the payment, get the webhook that includes the payment result.
qrCode The shopper scans a QR code and is redirected to an app to complete the payment. 1. Show the QR code.
2. After the shopper completes the payment, get the webhook that includes the payment result.
redirect The shopper is redirected to another website or app to complete the payment. Handle the redirect.
await The shopper completes the payment asynchronously, for example by using an app. 1. Inform the shopper that you are waiting for the payment.
2. Wait to get the webhook that includes the payment result.
sdk Applies for payment methods that require an SDK, for example WeChat Pay.
The type can sometimes include the payment method name, for example: wechatpaySDK.		 1. Invoke the SDK to trigger the switch to the payment method's app.
2. After the shopper completes the payment, get the webhook that includes the payment result.
threeDS2 The payment qualifies for 3D Secure 2 and will go through 3D Secure 2 authentication. Follow our 3D Secure 2 integration guides:

Show the voucher or QR code to your shopper

For voucher and QR code actions, you must use the information in the action object to show something to the shopper.

Handle the redirect

For redirect payment methods or redirect 3D Secure 2 authentication, you get action.type: redirect. You must redirect the shopper.

  1. Get the action.url from the response.

  2. Redirect the shopper to the action.url with the HTTP method from action.method.

    The shopper is redirected to a page where they need to take additional action, depending on the payment method.

    For security reasons, when displaying the redirect in an app, we recommend that you use SFSafariViewController for iOS or Chrome Custom Tabs for Android, instead of WebView objects.

    After the shopper completes the payment, they are redirected back to your returnUrl with HTTP GET. The returnUrl is appended with a Base64-encoded redirectResult:

    GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
Host: www.your-company.com/checkout

  3. Get the redirectResult appended to the URL and pass it to your server. If the shopper completes the payment but doesn't return to your website or app, you do not get the redirectResult. Instead, you get the outcome of the payment in a webhook.

  4. From your server, make a POST /payments/details request, specifying:

    Parameter Description
    details Contains the URL-decoded redirectResult.

    The response includes the following:

    Parameter Description
    resultCode The current status of the payment.
    pspReference Our unique identifier for the payment.

Request additional configuration (optional)

Adyen supports some features that require additional configuration that you cannot do yourself. Contact our Support Team if you use a feature that required additional setup from Adyen.

Handle new errors

Make changes to your server's business logic to handle errors in Checkout API responses.

A Classic API integration can get only generic error codes.

A Checkout API integration can get all error codes.

Test your updates

Follow our guide to test your online payments integration.

Go live

You can test your Checkout API integration in the live environment by processing some live payments. While testing in the live environment, you can continue to process payments with your Classic API integration.

After you verify that Checkout API meets your requirements in the live environment, we recommend that you stop using the Classic API integration.

See also