--- title: "Upgrade to Adyen Web v6" description: "Make the changes required to upgrade from Web Drop-in/Components v5.x.x to v6.x.x." url: "https://docs.adyen.com/online-payments/upgrade-your-integration/upgrade-to-web-v6" source_url: "https://docs.adyen.com/online-payments/upgrade-your-integration/upgrade-to-web-v6.md" canonical: "https://docs.adyen.com/online-payments/upgrade-your-integration/upgrade-to-web-v6" last_modified: "2026-05-08T17:09:17+02:00" language: "en" --- # Upgrade to Adyen Web v6 Make the changes required to upgrade from Web Drop-in/Components v5.x.x to v6.x.x. ##### Benefits to upgrading Read our [release notes](/online-payments/release-notes?Web%20Components%2FDrop-in=\&title%5B0%5D=Web%20Components%2FDrop-in\&version%5B0%5D=6.0.0#releaseNote=2024-07-24-web-componentsdrop-in-6.0.0) to learn about the benefits of upgrading. To upgrade from [Web Drop-in/Components](https://github.com/Adyen/adyen-web) v5.x.x to v6.x.x, complete the following steps. If you are upgrading from an earlier version, you need to follow a different upgrade guide: * [From **v4.x.x** to v6.x.x](/online-payments/upgrade-your-integration/upgrade-to-web-v6/from-v4). * [From **v3.x.x** to v6.x.x](/online-payments/upgrade-your-integration/upgrade-to-web-v6/from-v3). ## Required API version Using Web Drop-in/Components v6.0.0 requires [Checkout API v69](/online-payments/release-notes/?title%5B0%5D=Checkout%2BAPI\&version%5B0%5D=69#releaseNote=2022-05-24-checkout-api-69) or later. ## Step 1: Use the new package ### Tab: npm (recommended) Install this version of the [Adyen Drop-in/Components Node.js package](https://www.npmjs.com/package/@adyen/adyen-web): ```bash npm install @adyen/adyen-web@latest --save ``` ### Tab: Embed script and stylesheet Find the [Subresource Integrity hashes](/development-resources/live-endpoints/#subresource-integrity-hashes) for the latest version in our [release notes](/online-payments/release-notes). The base URLs for the script source are different for each environment. Use the one that corresponds to your [live endpoint](/development-resources/live-endpoints#checkout-endpoints): | Environment | URL | | ------------------------------------ | ------------------------------------------------- | | Test | `https://checkoutshopper-test.cdn.adyen.com` | | Europe (EU) live | `https://checkoutshopper-live.cdn.adyen.com` | | United States (US) live | `https://checkoutshopper-live-us.cdn.adyen.com` | | Australia (AU) live | `https://checkoutshopper-live-au.cdn.adyen.com` | | Asia Pacific & Southeast (APSE) live | `https://checkoutshopper-live-apse.cdn.adyen.com` | | India (IN) live | `https://checkoutshopper-live-in.cdn.adyen.com` | ```bash ``` ## Step 2: Upgrade import statements ### Tab: Drop-in You can import Drop-in [using npm](#import-using-npm) or by [embedding the scripts](#import-using-embedded-scripts). ### Using npm Starting from Drop-in v6, we offer two ways of importing with npm: * [Upgrade Drop-in with all payment methods](#npm-auto): this method resembles what you are used to before v6. You do not need to import individual payment methods, at the cost of a slower loading time. * [Upgrade Drop-in with individual payment methods](#npm-reduced-bundle-size): this method uses tree shaking to let you import only the payment methods you use, speeding up loading time. However, adding new payment methods requires developer resources. #### Upgrade Drop-in with all payment methods This method of importing resembles what you were used to before v6. With this method, you do not need to import every individual payment method for Drop-in. This allows for a simpler integration where adding a new payment method doesn't require any development resources. However, this results in a larger bundle size and slower loading times, as all module exports are imported client-side. If a smaller bundle size and faster page load times is a priority to you, consider upgrading [Drop-in with individual payment methods](#npm-reduced-bundle-size). For example, to load the Drop-in with all available payment methods: ```js import { AdyenCheckout, Dropin } from '@adyen/adyen-web/auto' ``` To add new payment methods, you only need to [add the payment method to you account](/payment-methods/add-payment-methods/). #### Upgrade Drop-in with individual payment methods Our tree-shakable `@adyen/adyen-web` npm package lets your import only the Components you use. This reduces the bundle size and loading times. For example, to load the Drop-in with card payments, PayPal, Google Pay, Apple Pay and Cash App Pay: ```js import { AdyenCheckout, Dropin, Card, PayPal, GooglePay, ApplePay, CashAppPay} from '@adyen/adyen-web' ``` To add new payment methods, you need to: 1. [Add the payment methods to you account](/payment-methods/add-payment-methods/). 2. Import them (see code sample above). 3. Assign them to the `paymentMethodComponents` property [within the Drop-in configuration](#upgrade-creating-an-instance). For an overview of available Components, see [The library's Component exports](https://github.com/Adyen/adyen-web/blob/main/packages/lib/src/components/index.ts). To know what Component you need for your payment methods, go to the relevant [payment method's Web Drop-in/Components page](/payment-methods). ### Using embedded scripts After you [import the scripts](/online-payments/upgrade-your-integration/upgrade-to-web-v6?tab=embed_script_and_stylesheet_2#use-the-new-package), the Drop-in/Components resources are available on the `window` global variable. Before v6, you would use the `window.AdyenCheckout()` method to create an instance of `AdyenCheckout`: **Before v6** ```js const checkout = await window.AdyenCheckout({ /* config */ }); ``` From v6 onwards, the `AdyenCheckout()` function is a property of `window.AdyenWeb`, alongside `Dropin` and all the payment method-specific Components: **From v6 onwards** ```js const { AdyenCheckout, Dropin, Card } = window.AdyenWeb; const checkout = await AdyenCheckout({ /* configuration */ }); ``` ### Tab: Components You can import Components [using npm](#import-using-npm}) or by [embedding the scripts](#import-using-embedded-scripts). ### Using npm We're introducing more granular imports for the `@adyen/adyen-web` package to let you load only the Components that you need, reducing the bundle size and improving overall performance. For example, to load only the card Component: ```js import { AdyenCheckout, Card } from '@adyen/adyen-web' ``` For an overview of available Components, see [The library's Component exports](https://github.com/Adyen/adyen-web/blob/main/packages/lib/src/components/index.ts). To know what Component you need for your payment methods, go to the payment method pages. If you do not find a specific Component for a payment method, and the payment method redirects the shopper, use the `Redirect` Component. For example, for iDEAL: **Use the Redirect Component for iDEAL** ```js new Redirect(checkout, { type: 'ideal' }); ``` ### Using embedded scripts After you [import the scripts](/online-payments/build-your-integration/sessions-flow?tab=embed_script_and_stylesheet_3\&platform=Web\&version=latest#install-adyen-web), the Drop-in/Components resources are available on the `window` global variable. Before v6, you would use the `window.AdyenCheckout()` method to create an instance of `AdyenCheckout`: **Before v6** ```js const checkout = await window.AdyenCheckout({ /* config */ }); ``` From v6 onwards, the `AdyenCheckout()` function is a property of `window.AdyenWeb`, alongside all the payment method-specific Components: **From v6 onwards** ```js const { AdyenCheckout, Card, PayPal } = window.AdyenWeb; ``` ## Step 3: Upgrade your configuration Make the following changes to your configuration properties: * `countryCode` is now a mandatory configuration property. Set it during the `AdyenCheckout` initialization. * If you use the Sessions flow, you can also set `countryCode` in the [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) request. * The `setStatusAutomatically` property is no longer used. To disable the Drop-in animation, set `disableFinalAnimation` to **true**. * You can no longer set `installmentOptions` during the `AdyenCheckout` instantiation. Set it directly in the Card configuration instead. * The `showBrandsUnderCardNumber` property is no longer used. Upgrade your code accordingly. * The `showFormInstruction` property is no longer used. Upgrade your code accordingly. * If you integrate with the custom card component, use the `onValidationError()` event listener to access the field errors. ## Step 4: Upgrade creating an instance In earlier versions of Drop-in/Components, creating an instance of a Component or the Drop-in used the `AdyenCheckout.create()` method. We've updated this to use a constructor function instead. ### Tab: Drop-in Before v6, creating an instance of Drop-in was as follows: **Before v6** ```js const checkout = await AdyenCheckout({ // configuration }); const dropin = checkout.create('dropin').mount('#dropin') ``` From v6 onwards, creating an instance of Drop-in is as follows: **From v6 onwards** ```js const checkout = await AdyenCheckout({ // configuration }); const dropin = new Dropin(checkout, { paymentMethodComponents: [Card, PayPal, GooglePay] // Only needed with tree-shakable npm package paymentMethodsConfiguration: { /** Configurations **/ } }).mount('#dropin') ``` If you import through [npm auto](/online-payments/upgrade-your-integration/upgrade-to-web-v6?tab=dropin-step1_1#npm-auto) or [embedded scripts](/online-payments/upgrade-your-integration/upgrade-to-web-v6?tab=dropin-step1_1#import-using-embedded-scripts), you do not need to set `paymentMethodComponents`. The Drop-in constructor function takes two positional arguments: 1. Your instance of `AdyenCheckout`. 2. Your [Drop-in configuration](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Drop-in\&version=6.0.0#configure). ### Tab: Components Before v6, creating an instance of the Card Component is as follows: **Before v6** ```js const checkout = await AdyenCheckout({ // configuration }); const card = checkout.create('card', { hideCVC: true, enableStoreDetails: true }).mount('#card'); ``` From v6 onwards, creating an instance of the Card Component is as follows: **From v6 onwards** ```js const checkout = await AdyenCheckout({ // configuration }); const card = new Card(checkout, { hideCVC: true, enableStoreDetails: true }).mount('#card'); ``` The Component constructor function takes two positional arguments: 1. Your instance of `AdyenCheckout`. 2. Your payment method-specific configuration. ## Step 5: Upgrade your event handlers In v6, we're introducing changes to several of the library's event handlers: ### `onValid` The `onValid()` event listener is no longer used. Remove it from your configuration. ### `onSubmit` and `onAdditionalDetails` These events handlers now have access to the new `actions` parameter, which lets you: * Continue the payment flow: `actions.resolve()`. Call `actions.resolve()` and pass the `resultCode`, also when the payment is unsuccessful. * Stop the payment flow: `actions.reject()`. Stop the payment flow only in the following cases: * When your server's request to Adyen's API fails. * When you experience network connection issues. Use the `actions` object to manage the payment flow, for example: ```javascript const checkout = await AdyenCheckout({ // Insert your global configuration here onSubmit: async (state, component, actions) => { try { const { action, order, resultCode, donationToken } = await makePayment(state.data); if (!resultCode) actions.reject(); actions.resolve({ resultCode, action, order, donationToken }); } catch (error) { actions.reject(); } }, }); ``` ### `onPaymentCompleted` This event now works both in the [Sessions Flow](/online-payments/build-your-integration#sessions-flow-a-single-api-request) and [Advanced Flow](/online-payments/build-your-integration#advanced-flow-three-api-requests). This event is no longer triggered for failed payments. For failed payments, we now use the [`onPaymentFailed` ](#onpaymentfailed)event handler instead. Once this event is triggered, initiate the successful transaction flow on your web page. ### `onPaymentFailed` This is a new event, which is triggered when a payment fails. Previously, this event was part of `onPaymentCompleted`. This event is triggered when the `resultCode` of a payment is **Cancelled**, **Error**, or **Refused**. Once this event is triggered, initiate the failed transaction flow on your web page. ### `onOrderCreated` and `onPaymentMethodsRequest` These events are used for [partial payments](/online-payments/partial-payments/). `onOrderCreated` is renamed to `onOrderUpdated`. Upgrade your codebase accordingly. `onPaymentMethodsRequest` is a new event, which is triggered when a partial payment is made and the associated order isn't fully paid. Use the event handler to request payment methods for a new payment: ```js const checkout = await AdyenCheckout({ // core configuration onPaymentMethodsRequest: async (data, { resolve, reject }) => { const paymentMethods = await getPaymentMethods({ amount, shopperLocale: data.locale, order: data.order, }); resolve(paymentMethods); }, }); ``` The `onPaymentMethodsRequest` event is only evoked in the [Advanced flow](/online-payments/build-your-integration#advanced-flow-three-api-requests), as you do not need to request payment methods yourself in the Sessions flow. ## Step 6: Upgrade your styling Starting from v6.0.0, we use CSS custom properties to give you more fine-grained control over Drop-in and Components' look and feel. For an overview of all available CSS variables, see [our GitHub repository](https://github.com/Adyen/adyen-web?tab=readme-ov-file#where-do-we-define-those-css-variables-and-what-is-the-default-value). Although we recommend you use CSS custom properties to style your Drop-in and Components, you can still override the CSS class names as before. ### Overriding styles with custom properties You can customize elements that are not inside an iFrame, by overriding the styles: 1. Create a CSS file `override.css`, with the [CSS variables](https://github.com/Adyen/adyen-web?tab=readme-ov-file#where-do-we-define-those-css-variables-and-what-is-the-default-value) you want to style: ```css :root { --adyen-sdk-color-background-secondary: #f7f7f8; } ``` 2. Import the `override.css` file after importing the Adyen library's main CSS file: ```css import '@adyen/adyen-web/styles/adyen.css'; import './override.css'; ``` ### Upgrade placeholder texts Placeholders are no longer added by default. To enhance the accessibility and UX, they are replaced with permanently visible contextual elements, which are shown below input fields. However, you can still add placeholder text to input fields. Placeholder texts are no longer part of the `translations` object, but part of the payment method configuration, as the placeholder texts are specific to payment methods. For example, to upgrade the placeholder text for the card number in the Card Component: ### Tab: Drop-in **Placeholders for cards in Drop-in** ```js const dropin = new Dropin({ paymentMethodsConfiguration: { card: { placeholders: { cardNumber: 'Enter your card number' } } } }); ``` ### Tab: Card Component **Placeholders in Card Component** ```js const card = new Card(checkout, { placeholders: { cardNumber: 'Enter your card number' } }); ``` ## Step 7: (Optional) upgrade your express payment methods ** ### Apple Pay #### Express The event handlers `onShippingContactSelected()` and `onShippingMethodSelected()` now work only when the Apple Pay Component configuration `isExpress` is set to **true**. ##### `onAuthorized` This event is now triggered before the `onSubmit` event, and must be resolved or rejected to continue the payment flow. `onAuthorized` returns an object with the `authorizedEvent` (raw data from Apple Pay) along with the formatted `billingAddress` and `deliveryAddress`. Create an `onAuthorized` event handler to implement checks before continuing the payment flow: ```js const applepay = new ApplePay(checkout, { onAuthorized({ authorizedEvent, billingAddress, deliveryAddress }, actions) { if (/* Your checks based on the raw data, billing and shipping address */) actions.resolve(); else actions.reject(); }, }); ``` ** ### Google Pay * The `isAvailable()` method does not return a boolean flag anymore. It now works same as [Apple Pay's `isAvailable()`](/payment-methods/apple-pay/web-component/#step-3-mount-the-component). * The event handler `onPaymentDataChanged()` now works only when the Google Pay Component configuration `isExpress` is set to **true**. ##### `onAuthorized` This event is now triggered before the `onSubmit` event, and must be resolved or rejected to continue the payment flow. `onAuthorized` returns an object with the `authorizedEvent` (raw data from Google Pay) along with the formatted `billingAddress` and `deliveryAddress`. Create an `onAuthorized` event handler to implement checks before continuing the payment flow: ```js const googlepay = new GooglePay(checkout, { onAuthorized({ authorizedEvent, billingAddress, deliveryAddress }, actions) { if (/* Your checks based on the raw data, billing and shipping address */) actions.resolve(); else actions.reject(); }, }); ``` ** ### PayPal * The `onShopperDetails(shopperDetails, rawData, actions)` event handler is renamed to `onAuthorized({authorizedEvent, billingAddress, deliveryAddress}, actions)`. * The `onShippingChange()` event handler is no longer supported. Implement [`onShippingAddressChange()` ](/payment-methods/paypal/web-component/express-checkout/#step-4-handle-delivery-address-changes)and [`onShippingOptionsChange()` ](/payment-methods/paypal/web-component/express-checkout/#handle-delivery-method-changes-sessions)instead. ## Step 8: (Optional) upgrade your Giving integration From v6 onwards, your Adyen Giving integration must use the [Giving Campaign Manager Component](/online-payments/donations/campaign-manager-web-component/). ## Step 9: (Optional) upgrade partial payments in Advanced flow If you use the [Advanced flow](/online-payments/build-your-integration/#advanced-flow-three-api-requests) and process [partial payments](/online-payments/partial-payments/), make the following change. Previously, you initiated the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) call from your `onSubmit()` or `onAdditionalDetails()` event handlers to upgrade the payment methods for the remaining amount to be paid. From v6 onwards, we introduce a new event handler named [`onPaymentMethodsRequest()` ](#onordercreated-and-onpaymentmethodsrequest)for this use case. To use it, pass the [order](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-order) from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) call to the `action.resolve()` method in your `onSubmit()` or `onAdditionalDetails()` event handler: ```js const checkout = await AdyenCheckout({ onSubmit: async (state, component, actions) => { try { const { action, order, resultCode } = await makePayment(state.data); if (!resultCode) actions.reject(); actions.resolve({ resultCode, action, order, }); } catch (error) { console.error('An error occured in the onSubmit() event handler:', error); actions.reject(); } }, onPaymentMethodsRequest: async (data, actions) => { // Merchant custom implementation to fetch payment methods const paymentMethods = fetchPaymentMethods(data); actions.resolve(paymentMethods); }, }); ```