Classic-integration icon

Web SDK

Integrate our Checkout SDK into your website.

The classic Checkout SDK integrations are being phased out
This means we are:

  • No longer developing the classic Checkout SDK integration.
  • Not accepting new classic Checkout SDK integrations.

You have until March 31, 2024 to migrate.

The Checkout SDK allows you to integrate key payment methods and 3D Secure into your website. It comes with a pre-built UI that allows for some customization, and takes care of encrypting and transmitting sensitive payment data so it never touches your server.

Payments are initiated by your server, while our SDK handles the rest of the transaction. This includes presenting a list of payment methods, collecting the shopper's details, and submitting these details to Adyen.

To accept online payments with the Checkout SDK, you'll need an integration that can:

  1. Create a payment session from your server.
  2. Make a payment using the client-side SDK.
  3. Verify the payment result on your server.

Before accepting live payments, we also recommend that you test your integration.

To see an example of a Web SDK integration, check out our GitHub.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

  • Get an overview of the steps needed to accept live payments.
  • Create your test account.

After you have created your test account, get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.

Step 1: Create payment session

Tokenized payments

If you have a subscription or recurring business model, we recommend using our tokenization service. See Recurring and subscription payments for details.

A payment session is used to securely transmit payment data between the shopper and the Adyen payments platform. Create one from your server by making a POST request to the /paymentSession endpoint. Specify your merchantAccount name, the sdkVersion you're using for your integration, and a channel of Web

Also include the amount, your unique reference for this payment, and the countryCode of the shopper.

Finally, specify an origin, which is the URL origin of your payments page, and a returnUrl that will be used for any payment methods that require a redirect.

Some payment methods require shoppers to verify payments on an external website. Once completed, the shopper is redirected back to the returnUrl

curl -H "Content-Type: application/json" -H "X-API-Key: YourAPIkey" -X POST -d '{
       "merchantAccount": "YourMerchantAccount",
       "sdkVersion": "1.9.9",
       "channel": "Web",
       "amount": {
          "currency": "EUR",
          "value": 17408
       },
       "reference": "Your order number",
       "countryCode": "NL",
       "shopperLocale": "nl_NL",
       "origin": "https://www.yourshop.com",
       "returnUrl": "https://www.yourshop.com/checkout/completed"
    }' https://checkout-test.adyen.com/v68/paymentSession

Execute this code from your server, not your website. This helps to prevent tampering with the transaction data.

The response will contain a paymentSession. You'll use this to initialize the SDK in the next step.

Step 2: Make a payment

Next, add the Checkout SDK to your website. The SDK will render the payment form, securely collect the shopper's payment details, and make the payment. To do this:

1. Integrate SDK

Embed the Checkout SDK by adding the following code to the <head> of your payment page.

<script type="text/javascript" src="https://checkoutshopper-test.adyen.com/checkoutshopper/assets/js/sdk/checkoutSDK.1.9.7.min.js"></script>

When you're ready to move to production, you'll have to switch from test to our live endpoints. See Live endpoints for more information.

Then add the payment form to your page using a div.

<div id="your-payment-div"></div>

2. Initialize SDK

Use the chckt.checkout method to pass the paymentSession your server received from the /paymentSession endpoint to the Checkout SDK. Also include a config object with a context of test.

// Create a config object for SDK.
var sdkConfigObj = {
   context: 'test' // change this to 'live' when you go live.
};
 
// Initiate the Checkout form.
var checkout = chckt.checkout(paymentSession, '#your-payment-div', sdkConfigObj);

This will place HTML elements into your payments page, which you can customize using CSS.

When the shopper completes the payment form and clicks Pay, the Checkout SDK encrypts their payment details and submits them to the Adyen payments platform. Once the payment is complete, the SDK generates a payload. Pass this to your server to verify the payment result.

For some payment methods, you'll instead receive the redirectResult when you handle a redirect back to your website.

3. Handle the redirect result

Some payment methods require redirects, such as iDEAL, or cards with 3D Secure authentication. For these payment methods you'll need to expose an endpoint to handle the shopper being redirected back to your payments page.

When a redirect is required, the SDK will send the shopper to a webpage or app to verify the payment. Once they have completed verification, the shopper is redirected back to your website using the returnUrl you provided earlier. This is appended with a redirectResult. URL-decode the redirectResult string and use this to verify the payment result.

https://www.yourshop.com/checkout/result/paymentResult?redirectResult=2he28Ddhwj242he28Ddhwj...&resultCode=AUTHORISED&type=completion

Do not use the resultCode appended to the returnUrl as confirmation of the payment result. Instead, verify the payment result on your server.

4. Present payment result

When the payment is completed the following hook will be triggered. Invoke this to present the result of the payment to the shopper.

chckt.hooks.beforeComplete = function(node, paymentData) {
   // 'node' is a reference to the Checkout container HTML node.
   // 'paymentData' is the result of the payment, and contains the 'redirectResult'.

   return false; // Indicates that you want to replace the default handling.
};

Step 3: Verify payment result

Once the payment has been completed, verify its result from your server with a /payments/result request. Include the redirectResult that was generated by the SDK or if you obtained the redirectResult from the returnURL, URL-decode the payload string before including it in the request.

curl \
-H "Content-Type: application/json" \
-H "X-API-Key: Your_API_key" \
-X POST \
-d '{ "redirectResult": "2he28Ddhwj242he28Ddhwj..." }' \
https://checkout-test.adyen.com/v68/payments/result

If the payment was successful you'll receive an Authorised resultCode and a pspReference, which is our unique identifier for the transaction. If you've set up webhooks, you'll also receive a successful AUTHORISATION webhook events.

If you received a different resultCode, check our result codes documentation for what action you should take.

Next, let's look at how you can test your integration.

Testing your integration

Before going live, use our list of test cards and other payment methods to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

You can check the status of a test payment in your Customer Area, under TransactionsPayments.

When you've completed testing, there are some additional steps you'll need to complete before you can accept live payments from shoppers. Refer to Getting started with Adyen for more information.

Customizing your Checkout

Create your own unique payments experience by:

Recurring and subscription payments

We recommend using our tokenization service to handle recurring payments and subscriptions.

To tokenize the shopper's payment details collected by the SDK, send additional parameters when creating a payment session. Pass enableOneClick and enableRecurring as true. Also provide a shopperReference  (minimum length three characters and do not include personally identifiable information, for example name or email address) to uniquely identify this shopper. This will act as the container for the shopper's tokenized payment details. The shopperReference will be stored when the token is created. 

Next, find out if the shopper's payment details was successfully tokenized by verifying the payment result. If the resultCode is Authorised, a recurringDetailReference value is also returned in the response. This is the identifier for the shopper's tokenized payment details.

If the resultCode is Pending, the payment details will be tokenized when the payment reaches an Authorised status. You will be informed of the status change through a webhook via our notification service. The recurringDetailReference is included in the notification if the payment has been authorised. For other result codes, see Pending and Refusal result codes under the Subscription tab.

Lastly, save the recurringDetailReference. You will use this and your corresponding shopperReference to make future payments. For more information, see Making payments with tokens.

Next steps