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:
- Update settings in Customer Area.
- Update your endpoints.
- Update your request objects.
- Implement cards brand check.
- Handle additional actions
- Request additional configuration (optional)
- Handle new errors.
- Test your updates.
- 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.
- In your Customer Area, go to Developers > API credentials.
- From the list of users, select the user whose credentials you want to use to make Checkout API requests.
- 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.
- In your Customer Area, go to Developers > Additional data.
- 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:
- Go to Developers > API URLs.
- 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.
Make a payment with encrypted card details
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:
Make a payment with unencrypted card details
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 |
Store the shopper's card details
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:
One-off payment with stored card details
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:
Subscription payment with stored card details
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:
Card payment with native 3D Secure 2 authentication
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:
Card payment with redirect 3D Secure 2 authentication
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:
Refund
Make a request for refund.
Parameters
Classic API | Checkout API |
---|---|
amount |
amount |
merchantAccount |
merchantAccount |
reference |
reference |
originalReference |
Path parameter: paymentPspReference |
Checkout API
To make a refund, include the following in the /payments/{paymentPspReference}/refunds request:
Cancel
Make a request to cancel a payment.
Parameters
Classic API | Checkout API |
---|---|
merchantAccount |
merchantAccount |
reference |
reference |
originalReference |
Path parameter: paymentPspReference |
Checkout API
To cancel a payment, include the following in the /payments/{paymentPspReference}/cancels request:
Capture
Make a request to capture a payment.
Parameters
Classic API | Checkout API |
---|---|
modificationAmount |
amount |
merchantAccount |
merchantAccount |
reference |
reference |
originalReference |
Path parameter: paymentPspReference |
Checkout API
To capture a payment, include the following in the /payments/{paymentPspReference}/captures request:
Reversal
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:
Adjust the amount of an authorized payment
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:
Third-party 3D Secure 2 authentication
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.
-
Get the
action.url
from the response. -
Redirect the shopper to the
action.url
with the HTTP method fromaction.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. ThereturnUrl
is appended with a Base64-encodedredirectResult
:GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1 Host: www.your-company.com/checkout
-
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 theredirectResult
. Instead, you get the outcome of the payment in a webhook. -
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.