Agent Skills: Adyen Knowledge Patch

Adyen Knowledge Patch

Use this skill when implementing or upgrading Adyen Web, Drop-in, Components, sessions integrations, or Checkout API v72. Start with the breaking changes and upgrade hazards below, then open the topic reference that matches the payment method or integration flow being changed.

Reference index

| Reference | Topics | | --- | --- | | Web upgrades | Select rendering, localization, callbacks, TypeScript surfaces, Secured Fields, amount updates, stored methods, and regressions | | Cards and bank payments | Card data, installments, UPI, ACH, EFT PAD, bank transfers, OpenInvoice, PayByBankUS, Econtext, and meal vouchers | | Wallets and components | Apple Pay, Google Pay, Affirm, Giving, and Riverty | | Sessions and Checkout API v72 | Sessions constraints and support, request validation, precedence, redirects, status codes, Pix, line items, and partial payments |

Breaking changes and upgrade hazards

Validate Checkout API v72 requests before upgrading

V72 adds stricter validation to requests including /payments and /sessions. Audit the following fields before upgrading:

• billingAddress.postalCode
• billingAddress.stateOrProvinceCode
• captureDelayHours
• dateOfBirth
• deliveryAddress.postalCode
• deliveryAddress.stateOrProvinceCode
• entityType
• metadata
• reference
• returnUrl
• shopperEmail
• shopperIP
• shopperName.firstName
• shopperName.lastName
• socialSecurityNumber
• telephoneNumber

For card payments, v72 also rejects a card number in holderName with Invalid card holder name. This exposes integrations that map PAN input to the cardholder-name parameter.

See Sessions and Checkout API v72.

Handle v72 validation and throttling statuses

Some validation and rate-limit failures return HTTP 422 or 429 instead of 500. Treat them as validation and throttling responses, rather than server failures, in error handling and retry logic.

Supply required v72 line-item tax fields

Omitting taxAmount and amountExcludingTax from /payments lineItems produces an error. V72 no longer creates the incorrect amountExludingTax value equal to amountIncludingTax.

Remove obsolete parameters during the v72 upgrade

V72 deprecates unused parameters and removes parameters that were already deprecated. Check the v71-to-v72 API diff and regenerate schema-derived clients before carrying old request fields into the upgrade.

Use redirectResult after a sessions redirect

In Drop-in /sessions flows, the redirect back no longer supplies the erroneous payload parameter instead of redirectResult. Use the required redirectResult to complete the payment.

Remove UPI Collect assumptions

From Adyen Web v6.30.0, UPI Collect is unsupported. The default UPI flow is QR code on desktop and Intent on mobile.

Remove deprecated OpenInvoice gender input

From v6.26.0, OpenInvoice components for Oney, Riverty, and RatePay no longer contain the deprecated gender field.

Correct the PayByBankUS option name

From v6.26.0, use showOtherInsteadOfNumber. The former showOtherInsteafOfNumber spelling was corrected.

Work around the v6.24.0 Card callback regression

In v6.24.0, onAdditionalDetails does not fire when defined only on the Card component. Define it at Checkout level or update to v6.25.1, where the regression is fixed.

Validate Google Pay environment strings

From v6.32.0, an unrecognized Google Pay environment falls back to PRODUCTION, not TEST. Validate the configured value explicitly to avoid unintentionally initializing the production environment.

Do not configure component-level installments with sessions

The sessions backend ignores component-level installment configuration. From v6.41.0, the installments are not displayed and the SDK emits a console warning.

High-use Web changes

Update amounts without remounting checkout

From v6.31.0, Drop-in and Components can receive amount updates without reinitialization, preserving the mounted checkout UI across amount changes.

Account for larger onSubmit payloads

From v6.35.0, sdkData changes increase the payload size passed to onSubmit. Allow for the increase in integrations that copy, validate, log, or impose size limits on the payload.

Render richer Select options

From v6.43.0, Select options can include tags, rendered as colored labels in the open list and collapsed button. secondaryText appears below the option name in the open list but is omitted from the collapsed button.

Use localized errors consistently

From v6.39.0, errors outside Secured Fields also include a translated error message, enabling consistent localized error handling.

Use the English translation fallback

From v6.34.0, English translations are bundled as the fallback. The SDK requests translations from the CDN only when the selected locale is supported.

Consume healthcare BIN data

From v6.41.0, the value passed to onBinLookup includes healthcare; card integrations can consume it directly from the callback result.

High-use payment-method changes

Configure Google Pay issuer-country filters

From v6.32.0, Google Pay accepts allowedIssuerCountryCodes and blockedIssuerCountryCodes component properties to filter cards by issuer country.

Configure Affirm countries

From v6.40.0, Affirm components accept allowedCountries. Supported codes are CA, US, and GB:

{ allowedCountries: ["CA", "US", "GB"] }

Use Apple Pay additions

Apple Pay supports third-party browsers from v6.10.0, shippingContactEditingMode from v6.13.0, domainName from v6.23.0, and coupon codes from v6.33.0. The references preserve the scope of each option.

Use sessions support where available

From v6.32.0, sessions integrations support card components with split funding sources. From v6.36.0, /sessions flows support Giving; when the /payments response requires Giving, the SDK automatically mounts and handles a Donation component.

Respect Advanced-flow sdkData precedence

In Drop-in or Components Advanced flow, v72 /payments uses values from sdkData when the same SDK-related information appears elsewhere. For example, sdkData.checkoutAttemptId wins over another supplied checkoutAttemptId.

Task routing

When upgrading Adyen Web

1. Check the breaking changes above against the installed Web version.
2. Open Web upgrades for shared UI, callback, localization, TypeScript, and Secured Fields changes.
3. Open the payment-method reference for method-specific changes.
4. If the integration uses /sessions, also check Sessions and Checkout API v72.

When upgrading to Checkout API v72

1. Audit the request fields listed above.
2. Check removed and deprecated parameters against the v71-to-v72 API diff.
3. Regenerate schema-derived clients.
4. Update status-code, redirect, timeout, and line-item handling using the v72 reference.
5. Preserve returned order data for 3DS2 partial payments.

When changing a payment method

• Use Cards and bank payments for Card, UPI, ACH, EFT PAD, bank transfer, OpenInvoice, PayByBankUS, Econtext, and Brazilian meal vouchers.
• Use Wallets and components for Apple Pay, Google Pay, Affirm, Giving, and Riverty.
• Cross-check Sessions and Checkout API v72 whenever the payment method runs through /sessions.