Advanced flow integration guide

Components is our pre-built UI solution for accepting payments on your website. Each component renders a payment method which you can place anywhere on your website. This integration requires you to make API requests to /paymentMethods, /payments, and /payments/details endpoints.

Adding new payment methods usually doesn't require more development work. Components supports cards, wallets, and most local payment methods.

Introducing Web v6

Improvements

The Web v6 library introduces the following improvements:

• Reduced bundle size through tree shaking
• Enhanced design
• Enhanced Typescript developer experience
• Better alignment of express payment methods
• Added support for 6 localizations
• Support for Apple Pay Order tracking
• Improve AVS checks for Google Pay and Apple Pay

To update your existing integration, see Migrate to Adyen Web v6.

Requirements

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.
• Get your client key.
• Set up webhooks to know the payment outcome.

How it works

To handle native 3D Secure 2 authentication:

1. Get additional shopper details in your payment form.
2. Make a payment request, including additional shopper details.
3. Handle the 3D Secure 2 action to perform the authentication flow.
4. Submit the authentication result.
5. Show the payment result.

Install an API library

We provide server-side API libraries for several programming languages, available through common package managers, like Gradle and npm, for easier installation and version management. Our API libraries will save you development time, because they:

• Use an API version that is up to date.
• Have generated models to help you construct requests.
• Send the request to Adyen using their built-in HTTP client, so you do not have to create your own.

<dependency>
  <groupId>com.adyen</groupId>
  <artifactId>adyen-java-api-library</artifactId>
  <version>LATEST_VERSION</version>
</dependency>

// Import the required classes.
package com.adyen.service;
 
import com.adyen.Client;
import com.adyen.service.checkout.PaymentsApi;
import com.adyen.model.checkout.Amount;
import com.adyen.enums.Environment;
import com.adyen.service.exception.ApiException;
 
import java.io.IOException;
 
public class Snippet {
 
    public Snippet() throws IOException, ApiException {
        // Set up the client and service.
        Client client = new Client("ADYEN_API_KEY", Environment.TEST);
    }
}

Get available payment methods

When your shopper is ready to pay, get a list of the available payment methods based on their country, device, and the payment amount.

From your server, make a /paymentMethods request, specifying:

Parameter name	Required	Description
merchantAccount		Your merchant account name.
amount		The currency and value of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.
channel		The platform of the shopper's device; use Web. This is used to filter the list of available payment methods to your shopper.
countryCode		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
shopperLocale		By default, the shopperlocale is set to en-US. To change the language, set this to the shopper's language and country code. You also need to set the same locale within your Drop-in configuration.

You can also include other optional parameters, for example allowedPaymentMethods or blockedPaymentMethods to customize which payment methods will be shown to the shopper.

The following example shows how to get the available payment methods for a shopper in the Netherlands, for a payment of EUR 10:

curl https://checkout-test.adyen.com/checkout/v71/paymentMethods \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "channel": "Web",
  "shopperLocale": "nl-NL"
}'

The response includes the list of available paymentMethods:

{
  "paymentMethods":[
   {
     "details":[...],
     "name":"Cards",
     "type":"scheme"
     ...
   },
   {
     "details":[...],
     "name":"SEPA Direct Debit",
     "type":"sepadirectdebit"
   },
   ...
   ]
}

Pass the response to your client website. You'll use this in the next step to show which payment methods are available for the shopper.

Add Components to your payments form

Next, use the Component to render the payment method, and collect the required payment details from your shopper.

Import using the Adyen Web npm package, or embed the Adyen Web script and stylesheet into your HTML file:

npm install @adyen/adyen-web --save

import { AdyenCheckout, Card } from '@adyen/adyen-web';
import '@adyen/adyen-web/styles/adyen.css';

   You can add your own styling by overriding the rules in this CSS file.

After you have imported the Adyen Web library, do the following:

1. Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered.

   Expand view

   Copy link to code block

   Copy code

   Copy code

   <div id="component-container"></div>

   If you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you do not re-render the DOM element.

2. Create a configuration object with the following parameters:

   Parameter name	Required	Description
   paymentMethodsResponse		The full /paymentMethods response returned when you get available payment methods.
   clientKey		A public key linked to your API credential, used for client-side authentication.
   locale		The shopper's locale. This is used to set the language rendered in the UI. For a list of supported locales, see Localization.
   countryCode		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
   environment		Use test. When you are ready to accept live payments, change the value to one of our live environments.
   onSubmit(state, component, actions)		Create an event handler for this event, which is called when the shopper selects the Pay button, and the details are valid. This applies if the showPayButton configuration parameter is set to true. Makes a POST /payments request. If the /payments request from your server is successful, you must call actions.resolve(), passing resultCode, action, and order objects (if available) from the API response. You must call it even if the payment is unsuccessful. If the /payments request from your server fails, or if an unexpected error occurs, call actions.reject().
   onAdditionalDetails(state, component, actions)		Create an event handler for this event, used for native 3D Secure 2, and for native QR code payment methods. In the example below, the handler is named handleOnAdditionalDetails. Makes a POST /payments/details request.
   onPaymentCompleted(result, component)		Create an event handler, called when the payment is completed.
   onPaymentFailed(result, component)		Create an event handler, called when the payment failed. A failed payment has result code Cancelled, Error or Refused.
   onError(error)		Create an event handler, called when an error occurs in the Component.
   onChange(state, component)		Create an event handler, called when the shopper provides the required payment details.
   secondaryAmount		Shows the payment amount in an additional currency on the Pay button. You must do the currency conversion and set the amount. This object has properties: currency: The three-character ISO currency code. value: The amount of the transaction, in minor units. currencyDisplay: Sets the currency formatting. Default: symbol.
   showPayButton		Shows or hides a Pay Button for each payment method. Defaults to true. When set to false, you must override it in paymentMethodsConfiguration . The Pay button triggers the onSubmit event when payment details are valid. If you want to disable the button and then trigger the submit flow on your own, set this to false and call the .submit() method from your own button implementation. PayPal Smart Payment Buttons doesn't support the .submit() method.
   amount		The currency and value of the transaction.
   onActionHandled		Create an event handler, called when an action, for example a QR code or 3D Secure 2 authentication screen, is shown to the shopper. The following action.type values trigger this callback: threeDS qr await Returns data that contains: componentType: The type of component that shows the action to the shopper. actionDescription: A description of the action shown to the shopper.

   Configure the Component

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const configuration = {
     clientKey: "YOUR_CLIENT_KEY",
     environment: "test",
     amount: {
       value: 1000,
       currency: 'EUR'
     },
     locale: 'nl-NL'
     countryCode: 'NL'
     // The full /paymentMethods response object from your server. Contains the payment methods configured in your account.
     paymentMethodsResponse: paymentMethodsResponse,
     onSubmit: async (state, component, actions) => {
       try {
    
         // Make a POST /payments request from your server.
         const result = await makePaymentsCall(state.data, countryCode, locale, amount);
    
         // If the /payments request from your server fails, or if an unexpected error occurs.
         if (!result.resultCode) {
           actions.reject();
           return;
         }
    
         const {
           resultCode,
           action,
           order,
           donationToken
         } = result;
    
         // If the /payments request request from your server is successful, you must call this to resolve whichever of the listed objects are available.
         // You must call this, even if the result of the payment is unsuccessful.
         actions.resolve({
           resultCode,
           action,
           order,
           donationToken,
         });
       } catch (error) {
         console.error("onSubmit", error);
         actions.reject();
       }
     },
     onAdditionalDetails: async (state, component, actions) => {
       try {
    
         // Make a POST /payments/details request from your server.
         const result = await makeDetailsCall(state.data);
    
         // If the /payments/details request from your server fails, or if an unexpected error occurs.
         if (!result.resultCode) {
           actions.reject();
           return;
         }
    
         const {
           resultCode,
           action,
           order,
           donationToken
         } = result;
    
         // If the /payments/details request request form your server is successful, you must call this to resolve whichever of the listed objects are available.
         // You must call this, even if the result of the payment is unsuccessful.
         actions.resolve({
           resultCode,
           action,
           order,
           donationToken,
         });
       } catch (error) {
         console.error("onSubmit", error);
         actions.reject();
       }
     },
     onPaymentCompleted: (result, component) => {
       console.info(result, component);
     },
     onPaymentFailed: (result, component) => {
       console.info(result, component);
     },
     onError: (error, component) => {
       console.error(error.name, error.message, error.stack, component);
     }
   );

3. Use the configuration object to create an instance of AdyenCheckout.

   Create an instance of AdyenCheckout

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const checkout = await AdyenCheckout(configuration);

4. Then create and mount an instance of the payment method Component.

   Some payment method Components require additional configuration. For more information, refer to our payment method integration guides.

   For example, to mount the Card Component using its component name, card:

   Mount the Component

   Expand view

   Copy link to code block

   Copy code

   Copy code

   const card = new Card(checkout).mount('#component-container');

   You can also include optional Card Component configuration.

   When the shopper enters the payment details and selects the Pay button, the Component calls the onSubmit event. If state.isValid is true, use the data in state.data to make the payment.

5. Pass the state.data to your server.

   state from onChange event for Card Component

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       isValid: true,
       data: {
           paymentMethod: {
           type: "scheme",
           encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
           encryptedExpiryMonth: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
           encryptedExpiryYear: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
           encryptedSecurityCode: "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
     }
       }
   }

Methods

All Components support the following methods:

Make a payment

After the shopper submits their payment details or chooses to pay with a payment method that requires a redirection, you need to make a payment request to Adyen.

From your server, make a /payments request specifying:

Parameter name	Required	Description
merchantAccount		Your merchant account name.
amount		The currency of the payment and its value in minor units.
reference		Your unique reference for this payment.
paymentMethod		The state.data.paymentMethod from the onChange or onSubmit event from your client website.
returnUrl		URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:// or https://. You can also include your own additional query parameters, for example, shopper ID or order reference number. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address.
riskData		Device characteristics and other data that we use to detect fraudulent payment activity, and mitigate fraud.
applicationInfo		If you are building an Adyen solution for multiple merchants, include some basic identifying information, so that we can offer you better support. For more information, refer to Building Adyen solutions.

The following example shows how to make a payment request for EUR 10:

curl https://checkout-test.adyen.com/checkout/v71/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod":{
	    "type": "scheme",
	    "encryptedCardNumber": "test_4111111111111111",
	    "encryptedExpiryMonth": "test_03",
	    "encryptedExpiryYear": "test_2030",
	    "encryptedSecurityCode": "test_737"
	},
  "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..",
  "riskData": {
	   "clientData": "eyJ0cmFuc1N0YXR1cy...I6IlkifQ=="
	},
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT"
}'

Next, implement logic to handle /payments responses with and without an action object:

The following example shows a /payments response with action.type: redirect.

{
  "action": {
    "method": "GET",
    "paymentMethodType": "ideal",
    "type": "redirect",
    "url": "https://checkoutshopper-test.adyen.com/checkoutshopper/checkoutPaymentRedirect?..."
  }
}

Handle the additional action

Some payment methods require additional action from the shopper such as: to scan a QR code, to authenticate a payment with 3D Secure, or to log in to their bank's website to complete the payment. To handle these additional front-end actions:

The Component handles these additional front-end actions based on the action object and resultCode that you pass to the onSubmit actions.resolve() function.

The action.type determines your next steps:

Handle the redirect result

If you receive an action.type redirect, the Component redirects your shopper to another website to complete the payment or go through 3D Secure redirect authentication.

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

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

1. Get the redirectResult appended to your return URL and pass it to your server.

2. Send additional payment details.

Send additional payment details

If the shopper performed additional action, you need to submit additional details to either complete the payment, or to check the payment result.

Make a /payments/details request, and include:

• For action.type: redirect, pass in your request:
  • details: Object that contains the URL-decoded redirectResult.
• For action.type: qrCode, await, sdk, or threeDS2, pass in your request the state.data from the onAdditionalDetails event.

The following example shows how to submit additional payment details in case of a redirect.

curl https://checkout-test.adyen.com/checkout/v70/payments/details \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
     "details": {
       "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
   }
}'

The response includes:

• pspReference: Our unique identifier for the transaction.
• resultCode: Indicates the status of the payment.

{
  "pspReference": "NC6HT9CRT65ZGN82",
  "resultCode": "Authorised"
}

{
  "pspReference": "KHQC5N7G84BLNK43",
  "refusalReason": "Not enough balance",
  "resultCode": "Refused"
}

Get the payment outcome

After the Component finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

Inform the shopper

Use the resultCode from the onPaymentCompleted or onPaymentFailed event to show the shopper the current payment status. This synchronous response doesn't give you the final outcome of the payment. You get the final payment status in a webhook that you use to update your order management system.

Update your order management system

You get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.
For a successful payment, the event contains success: true.

{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"033899:1111:03/2030",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "operations":["CANCEL","CAPTURE","REFUND"],
        "success":"true",
        "paymentMethod":"mc",
        "additionalData":{
          "expiryDate":"03/2030",
          "authCode":"033899",
          "cardBin":"411111",
          "cardSummary":"1111"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"NC6HT9CRT65ZGN82",
        "eventDate":"2021-09-13T14:10:22+02:00"
      }
    }
  ]
}

For an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.

{
  "live": "false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "eventCode":"AUTHORISATION",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "reason":"validation 101 Invalid card number",
        "amount":{
          "currency":"EUR",
          "value":2500
        },
        "success":"false",
        "paymentMethod":"unknowncard",
        "additionalData":{
          "expiryDate":"03/2030",
          "cardBin":"411111",
          "cardSummary":"1112"
        },
        "merchantReference":"YOUR_REFERENCE",
        "pspReference":"KHQC5N7G84BLNK43",
        "eventDate":"2021-09-13T14:14:05+02:00"
      }
    }
  ]
}

Error handling

In case you encounter errors in your integration, refer to the following:

• API error codes: If you receive a non-HTTP 200 response, use the errorCode to troubleshoot and modify your request.
• Payment refusals: If you receive an HTTP 200 response with an Error or Refused resultCode, check the refusal reason and, if possible, modify your request.

Test and go live

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.

To debug or troubleshoot test payments, you can also use API logs in your test environment.

When you are ready to go live, you need to:

1. Apply for a live account. Review the process to start accepting payments on Get started with Adyen.
2. Assess your PCI DSS compliance by submitting the Self-Assessment Questionnaire-A.
3. Configure your live account. 
4. Submit a request to add payment methods in your live Customer Area .
5. Switch from test to our live endpoints.

6. Load Components from one of our live environments and set the environment to match your live endpoints:

   Endpoint region	Value
   Europe (EU) live	live
   United States (US) live	live-us
   Australia (AU) live	live-au
   Asia Pacific & Southeast (APSE) live	live-apse
   India (IN) live	live-in

See also

Next steps