Migrate 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
3D Secure 2 authentication
Drop-in/Components for web, mobile, and cross-platform
Hosted Checkout
Pay by Link
Donations with Adyen Giving
Creating orders that allow for partial payments
Usage analytics

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/checkout/{VERSION}
Live	https://{PREFIX}-pal-live.adyenpayments.com/pal/servlet/Payment/{VERSION}	https://{PREFIX}-checkout-live.adyenpayments.com/checkout/{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 don't 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.

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: Web 3D Secure 2 Component iOS 3D Secure 2 Component Android 3D Secure 2 Component

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.

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