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:
- Create a payment session from your server.
- Make a payment using the client-side SDK.
- 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/paymentSessionExecute 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 SOFORT, 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=completionDo 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/resultIf 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 Transactions > Payments.
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:
- Adding your own styling.
- Customizing the localizations used for your Checkout.
- Sorting and filtering the list of payment methods.
- Using hooks to add your own custom logic to the payment form.
- Configuring the rendering and behaviour of your payment form fields.
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) 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.