Digital integration wiki

Sessions Flow

Create a POST /sessions request on the server and pass only the returnedid and sessionData to Adyen Web. The final outcome is asynchronous and must be reconciled from the AUTHORISATION webhook.

Move the shopper to the confirmation page on onPaymentCompleted and let the webhook be the only source of truth for the order. This playground never calls GET /sessions/{id}: Adyen documents that the status it returns is not updated, so it must not be polled for the payment's outcome.

Since v6.41.0, card installments for Sessions belong in the request-levelinstallmentOptions. Checkout API v72 accepts an expiry up to 24 hours; the default session expiry is one hour.

Advanced Flow

The browser calls your backend for /paymentMethods, /paymentsand /payments/details. The component callback resolves with the backend response so Adyen Web can handle redirects, 3DS2 or QR/voucher actions.

Drop-in is the all-in-one surface; Components let you mount one payment method. Both have the same rule: API keys and merchant credentials stay server-side.

Frontend callbacks

Core callbacks include onSubmit, onAdditionalDetails,onPaymentCompleted, onPaymentFailed, onError,onChange and payment-method-specific events. This playground records chronological, sanitized snapshots. Encrypted fields, sessionData and card data are redacted.

Adyen Web 6.41.0 added healthcare data to onBinLookup, validated an invalidthreeDSNotificationURL in challenge tokens, tightened the TypeScript callback types, and fixed aria-checked whenopenFirstPaymentMethod=false. Up to 6.46.0 it then let the 3DS2 iframe run WebAuthn and SPC challenges, added a Sessions onReview callback, kept a Drop-in method's state when another is selected, and allowed a disclaimer above the Pay button. 6.47.0 shows a failed gift card balance check to the shopper instead of failing silently, and warns when several checkouts are created on one page.

Webhooks, HMAC & idempotency

Verify HMAC before business processing, store the event durably, acknowledge it, then apply idempotent state transitions. Standard webhooks sign a canonical colon-separated field list; newer webhook families can sign the unchanged raw body in headers.

Deduplication uses stable event identity, not arrival time. API mutations carry a UUID idempotency key capped at 64 characters. Late and out-of-order events update the same correlated aggregate.

Capture, cancellation & refund

Two different things decide what can be done with a payment, and integrations go wrong when they are confused: what Adyen supports for the payment method, and how the merchant account is set up to capture it.

From Adyen's feature table on docs.adyen.com/payment-methods, checked 2026-10-10. Re-checked every three months (packages/platform/lifecycle.ts).

• Multiple partial captures also need Adyen Support to enable them on the merchant account. Without that, a partial capture is the only one: Adyen cancels what is left.
• Refunds apply to what is captured, and their total never exceeds it. Cancel releases an authorisation nothing was captured from.
• Every modification is asynchronous. /captures, /cancels and /refunds answer received; the CAPTURE, CANCELLATION and REFUND webhooks are the outcome, and CAPTURE_FAILED, REFUND_FAILED or REFUNDED_REVERSED can overturn a success days later. The Back Office keeps a button disabled while its webhook is awaited.
• Idempotency. Each request carries an Idempotency-Key (a UUID v4, at most 64 characters) minted for that intent and reused on a retry. Adyen keeps keys 7 to 14 days and answers a repeat with the first response; a repeat still in flight gets HTTP 409 or 422 with error code 704.

Partial payments and multiple attempts

Checkout /orders combines tenders such as a gift card followed by card. A remaining amount of zero is not sufficient to close: wait for all payments to reach final status and for ORDER_CLOSED success=true. Expired or manually cancelled orders close with success=false.

Sessions. Adyen Web checks the gift card balance, creates the order and pays into it on its own. The merchant implements onOrderUpdated in the AdyenCheckout configuration: show what is paid and what is left and, with Components, mount the next component (a card). The checkout already carries the order, so that component charges only the rest; onPaymentCompleted fires once nothing is left. Drop-in does all of this itself.

Advanced. The merchant's server does that work: onBalanceCheck calls /paymentMethods/balance, onOrderRequest calls /orders, and each /payments carries the order and its share of it: the gift card pays what its balance covers, the next method the rest. Without onBalanceCheck, Adyen Web submits the gift card for the whole amount and Adyen refuses it ("Not enough balance"). onPaymentMethodsRequest lists the methods for what is left, onOrderCancel calls /orders/cancel when the shopper removes a paid gift card in Drop-in.

Pay by Link

Links default to 24 hours and can be configured up to 70 days. Adyen expires a link after five unsuccessful attempts. Therefore REFUSED is attempt-level; the order can remain open until the effective link status becomes completed or expired.

MIT & tokenization

Create tokens only after shopper consent. Subsequent merchant-initiated requests usestoredPaymentMethodId, a non-PII shopperReference,shopperInteraction=ContAuth, and eitherSubscription or UnscheduledCardOnFile.

API Only & PCI

A custom form does not remove PCI obligations. Adyen Custom Card/Secured Fields keeps sensitive entry inside secure iframes and sends encrypted values. This server rejects raw PAN, CVC and security-code keys and never persists card payloads.

Troubleshooting

• 403 or component load errors: add the exact local/deployed origin to the TEST client key.
• Empty Drop-in: verify merchant payment methods, country, currency and client key.
• Webhook rejected: configure the endpoint-specific TEST HMAC key and do not reuse LIVE keys.
• Action disabled: inspect method capability, capture state and latest webhook in the timeline.
• 3DS redirect loops: verify returnUrl origin and preserve correlation without PII.