Migrate to Adyen Web v6

To upgrade from Web Drop-in/Components v4.x.x to v6.x.x, complete the following steps.

Required API version

Using Web Drop-in/Components v6.0.0 requires Checkout API v69 or later.

Step 1: Use the new package

npm install @adyen/adyen-web@latest --save

Step 2: Update import statements

import { AdyenCheckout, Dropin } from '@adyen/adyen-web/auto'

import { AdyenCheckout, Dropin, Card, PayPal, GooglePay, ApplePay, CashAppPay} from '@adyen/adyen-web'

const checkout = new window.AdyenCheckout({ /* Configuration */ });

const { AdyenCheckout, Dropin, Card } = window.AdyenWeb;
const checkout = await AdyenCheckout({ /* Configuration */ });

Step 3: Update 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 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. Update your code accordingly.
• The showFormInstruction property is no longer used. Update your code accordingly.
• If you integrate with the custom card component, use the onValidationError() event listener to access the field errors.

Step 4: Update 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.

const checkout = new AdyenCheckout({ /* Configuration */ });
const dropin = checkout.create('dropin').mount('#dropin')

const checkout = await AdyenCheckout({ /* Configuration */ });
 
const dropin = new Dropin(checkout, {
  paymentMethodComponents: [Card, PayPal, GooglePay] // Only needed with tree-shakable npm package
  paymentMethodsConfiguration: { /* Configuration */ }
}).mount('#dropin')

Step 5: Update 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(). You should call the actions.resolve() method regardless of the resultCode, including when the payment is unsuccessful.
• Stop the payment flow: actions.reject(). Stop the payment flow only when your server-side API request to Adyen failed, or when experiencing network connection issues.

Use the actions object to manage the payment flow, for example:

Copy code
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 and Advanced Flow.

This event is no longer triggered for failed payments. For failed payments, we now use the 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.

onOrderCreated is renamed to onOrderUpdated. Update 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:

Copy code
const checkout = await AdyenCheckout({
  // core configuration
  onPaymentMethodsRequest: async (data, { resolve, reject }) => {
 
    const paymentMethods = await getPaymentMethods({
      amount,
      shopperLocale: data.locale,
      order: data.order,
    });
 
    resolve(paymentMethods);
  },
});

onError

The onError callback now returns:

• an error object that contains details about the error
• a reference to the payment method component for which the error occurs

Step 6: Update 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.

If you previously added your own styles to Components, make sure that these styles are being applied, because this version introduces different class names and DOM structures.

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 you want to style:

   Copy code
   :root {
     --adyen-sdk-color-background-secondary: #f7f7f8;
   }

2. Import the override.css file after importing the Adyen library's main CSS file:

   Copy code
   import '@adyen/adyen-web/styles/adyen.css';
   import './override.css';

Update 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 update the placeholder text for the card number in the Card Component:

const dropin = new Dropin({
    paymentMethodsConfiguration: {
        card: {
            placeholders: { cardNumber: 'Enter your card number' }
        }
    }
});

Step 7: (Optional) update your express payment methods

Copy code
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();
  },
});

Copy code
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();
  },
});

Step 8: (Optional) update your Giving integration

From v6 onwards, your Adyen Giving integration must use the Giving Campaign Manager Component.

Step 9: (Optional) update partial payments in Advanced flow

If you use the Advanced flow and process partial payments, make the following change.

Previously, you initiated the /paymentMethods call from your onSubmit() or onAdditionalDetails() event handlers to update the payment methods for the remaining amount to be paid. From v6 onwards, we introduce a new event handler named onPaymentMethodsRequest() for this use case.

To use it, pass the order from the /payments call to the action.resolve() method in your onSubmit() or onAdditionalDetails() event handler:

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);
  },
});