DOCSEARCHbyAlgolia
Submit Docs

Adyen Web SDK

repository·main·Indexed 42 days ago

https://github.com/adyen/adyen-web

A library providing modular UI building blocks, including Web Drop-in and Web Components, to integrate Adyen payment methods into web applications. It supports customization via CSS variables and provides a comprehensive set of tools for localization and themeing.

Tokens
29.8K
Snippets
118
Records
154
Agent score
53%

What's inside Adyen Web

  1. Accessibility considerations for Card Component and Secure Fields

    main

    The Card component and Secure Fields have been optimized for accessibility (a11y) to comply with WCAG standards. Key improvements include:

    • Secure Fields iframes: The role="presentation" attribute has been removed from iframes used for secure field inputs (card number, expiry date, CVC). This ensures compliance with WCAG SC 4.1.2 (Name, Role, Value) and avoids WCAG Failure F92, where role="presentation" on interactive content conflicts with ARIA specifications and can cause inconsistent behavior across screen readers.
    • Decorative Images: To prevent redundant announcements by screen readers, purely decorative elements are hidden from assistive technology following WCAG SC 1.1.1 (Non-text Content):
      • CVC hint SVGs use aria-hidden.
      • Expiry date hints and placeholder brand icon images use alt="".
      • Note: Real detected brand icons will still retain their full brand name as alt text to ensure they remain informative.

  2. Overview of Adyen Web integration methods

    main

    Adyen Web provides building blocks for creating checkout experiences. You can integrate using two primary methods:

    • Web Drop-in: An all-in-one solution designed for the quickest way to accept payments on your website.
    • Web Components: A modular approach where you use one Component per payment method and combine them with your own custom payment form logic.

  3. Understand Analytics and Data Tracking in Adyen Web

    main
    Starting from version v5.16.0, both the Drop-in and Components integrations include analytics and tracking features that are enabled by default. If you need to manage or disable these features, refer to the official Adyen documentation regarding what data is collected and how to control it.

  4. Configure address prefixes for billing and shipping

    main

    To distinguish between billing and shipping information, you can prefix address tokens with billing or shipping (e.g., billing address-line1).

    When using the Address component, the prefix is automatically derived from the label prop:

    • label="billingAddress" results in the billing prefix.
    • label="deliveryAddress" results in the shipping prefix.

  5. Understand the Address Component search bar DOM order

    main

    In the Address Component, the search field is rendered in the DOM before the "+ Enter manually" button. This ensures that the primary flow (address lookup) is the first thing encountered by keyboard and screen reader users.

    Even if your visual layout places the manual entry button before the search field, the focus order follows the DOM structure to comply with WCAG SC 2.4.3 Focus Order. This prevents screen reader users from mistakenly believing manual entry is the only available option before they have had the chance to use the search functionality.

  6. Localization in Adyen Web

    main
    Adyen Web includes UI localizations for many languages. You can find the list of supported languages and their translations in the /packages/server/translations/ directory. You also have the option to customize translations by replacing default text with your own custom strings.

  8. Exit pre mode and release a stable major version

    main

    Once the major version is ready for a stable release, follow these steps to roll up all accumulated changesets into a single stable version (e.g., 7.0.0) with a combined changelog:

    1. Reset the base branch: In .changeset/config.json, set baseBranch back to main.
    2. Exit pre mode: Run yarn changeset pre exit. This records the intent to exit but does not perform versioning.
    3. Commit changes: Commit .changeset/pre.json and .changeset/config.json.
    4. Run versioning: Execute yarn run version to generate the stable version and combined changelog.
    5. Promote the branch: Instead of merging, tag the current main as the previous major version (e.g., v6), then rename your development branch (e.g., next-v7) to main.
    # 1. Update .changeset/config.json: "baseBranch": "main"

# 2. Exit pre mode
yarn changeset pre exit

# 3. Commit
git add .changeset/pre.json .changeset/config.json
git commit -m "Exit changeset pre mode"

# 4. Run version to create the stable release
yarn run version

  9. Use autocomplete tokens for WCAG 2.2 compliance

    main

    To ensure WCAG 2.2 compliance and enable proper browser autofill behavior, use specific autocomplete tokens on form input components. This helps users fill out forms more efficiently and meets accessibility standards for input purposes.

    <InputText
    name="firstName"
    value={data.firstName}
    autocomplete="given-name"
    onInput={handleChangeFor('firstName', 'input')}
    onBlur={handleChangeFor('firstName', 'blur')}
/>

  10. Customize Adyen Web styles using CSS variables

    main

    Adyen Web is themeable via CSS variables. For elements that are not contained within iframes, you can override the default look by defining new values for these variables in a CSS file.

    To ensure your overrides take effect, you must import your custom CSS file after the main Adyen library CSS.

    Important Note: Overriding variables at the :root level will apply the change to all child elements that use those specific variables. To limit the scope of a style change, target specific elements instead of using :root.

    /* 1. Create your override.css */
:root {
    --adyen-sdk-color-background-secondary: #f7f7f8;
}

/* 2. Import in your JavaScript/TypeScript entry point */
import '@adyen/adyen-web/styles/adyen.css';
import './override.css';

  11. Switch between prerelease stages (alpha, beta, rc)

    main

    To move from one prerelease stage to another (e.g., from alpha to beta), do not re-run the enter command. Instead, manually edit the tag value inside the .changeset/pre.json file and commit the change.

    • Changing tag to beta will result in versions like 7.0.0-beta.0.
    • Changing tag to rc will result in versions like 7.0.0-rc.0.

    Note that the prerelease counter continues to increment across stages (e.g., alpha.1 -> beta.0).

    // Edit .changeset/pre.json to change the stage
{
  "tag": "beta"
}

  12. Manually instantiate Donation on a review page

    main

    If your payment response indicates that a donation is requested (askDonation: true), you must manually instantiate the Donation component within the onPaymentCompleted callback on a review page.

    Because askDonation is an internal response flag not present in the standard PaymentCompletedData type, you must cast the result to PaymentResponseData to access it.

    When instantiating Donation, providing a rootNode allows the element to automatically detect service mode and fetch campaigns via the sessions endpoint. The commercialTxAmount is optional in this context as the SDK will fall back to the amount defined in the session setup.

    const checkout = await AdyenCheckout({
    session: { id },
    donation: {
        onDonationSuccess: ({ didDonate }) => { ... },
        onDonationFailure: reason => { ... }
    },
    onPaymentCompleted: result => {
        // Cast to PaymentResponseData to access askDonation
        if ((result as PaymentResponseData).askDonation === true) {
            new Donation(checkout, { rootNode: '#donation-root' });
        }
    }
});