Adyen gateways

The Adyen gateway object and the allowed CRUD operations on the related resource endpoint

Configuring an Adyen payment gateway for a market lets you safely process payments through Adyen. The Adyen gateway is compliant with the PSD2 European regulation so you can implement a payment flow that supports SCA and 3DS2 by using Adyen's official JS SDK and libraries.

Commerce Layer currently supports the latest version (v71) of Adyen Checkout API by default and back up to v66 for backward compatibility. If you're using or have implemented an old integration that requires a version lower than v71 make sure to specify it in the api_version attribute when creating or updating the Adyen gateway resource in Commerce Layer and to use the correct version of Adyen's JS SDK and client libraries as detailed on Adyen's website.

To create an Adyen gateway choose a meaningful name that helps you identify it within your organization and gather all the credentials requested (like merchant account, API key, etc. — contact Adyen's support if you are not sure about the requested data).

To get real orders and be able to process live transactions with Adyen make sure to get your live URL prefix and correctly set the live_url_prefix attribute of the gateway.

If you're leveraging Adyen's native Drop-in for your integration and want to use the customer payment sources saved from their JS library (highly recommended) instead of the ones saved in Commerce Layer, you can set the native_customer_payment_sources attribute to true (default is false).

Adyen Uplift

Commerce Layer sends the shopper and order data required by Adyen Uplift to optimize fraud screening, authentication, and conversion. Any of these values you already pass in the payment request data are kept as is — Commerce Layer only fills in what's missing.

Adyen request	Data sent
Payment methods	shopperEmail, shopperConversionId
Payments	riskData, accountInfo, merchantOrderReference, shopperConversionId
Card storage	accountInfo

Most of these values map directly from the order or the payment request data, with no special handling. Here's how the rest are sourced:

• riskData — the device fingerprint collected by Adyen's Drop-in or Components. It's forwarded only if your checkout includes it in the payment_request_data attribute of the Adyen payment (e.g. by sending Adyen's state.data as is).

• accountInfo — the account creation date, sent for registered customers only (guests are left out).

• merchantOrderReference — the order number, so that Adyen can link all the payment attempts of the same order.

• shopperConversionId — derived from the order, so that every Adyen request for the same checkout — payment methods and payments — carries the same value.

When api_version is 69 or higher, 3DS is requested in the native format expected by recent versions of Adyen's Checkout API — authenticationData. Lower versions keep using the legacy additionalData flags. Payments that skip 3DS (e.g. with a stored card or Klarna) do so in both formats.

Adyen requires Checkout API v71 to qualify for Uplift. If your gateway is set to a lower api_version, update it and make sure your Adyen JS SDK and client libraries are aligned.

Adyen's notification system

Adyen's notifications are webhooks informing you of payment status updates and newly available reports. Notifications are the only way you'll receive automatic updates about requests that are processed asynchronously. To process payments asynchronously, set the async_api attribute to true as explained here.

If you create an Adyen gateway without a webhook_endpoint_secret, Commerce Layer configures a merchant-level Standard webhook pointing to webhook_endpoint_url through Adyen's Management API, generates its HMAC key, and stores the resulting webhook_endpoint_id and webhook_endpoint_secret. If a webhook with the same URL already exists on the merchant account, it is updated and reused instead of creating a new one. The webhook is removed from Adyen when the gateway is deleted.

Automatic configuration requires the API credential behind api_key to have the Management API — Webhooks read and write role. Without it, a gateway with async_api set to true can't be created. Any other gateway is created anyway, and you need to configure the webhook manually.

To configure the webhook manually, set it up in Adyen's customer area pointing to webhook_endpoint_url, then copy its HMAC key into webhook_endpoint_secret.

Gateways configured manually can switch to automatic configuration at any time by updating them with the _update_webhooks trigger attribute: Commerce Layer adopts the webhook already pointing to webhook_endpoint_url (or creates a new one) and generates a new secret. To renew the secret only, use the _refresh_webhook_secrets trigger attribute.

Notifications already sent by Adyen when the secret changes fail signature verification and are not retried. We recommend renewing the secret outside of your peak hours.

Tokenization webhooks

Commerce Layer also supports Adyen's tokenization webhooks on the same webhook_endpoint_url. They must be registered as an additional, separate webhook in Adyen's customer area (selecting the Tokenization webhook type), with its own HMAC key stored on token_webhook_endpoint_secret.

Event	Effect
recurring.token.created / recurring.token.alreadyExisting	Saves the card as a customer payment source, unless already saved.
recurring.token.updated	Marks the matching customer payment source as updated.
recurring.token.disabled	Deletes the matching customer payment source.

The customer is resolved from the token's shopper reference, and the card is linked to that customer's Adyen payment whose response carries the token's stored payment method ID — tokens that weren't created by a Commerce Layer payment aren't saved. A card notified by both a RECURRING_CONTRACT notification and a tokenization webhook is saved only once.

Set token_webhook_endpoint_secret before enabling the tokenization webhook in Adyen's customer area. Until it's configured, tokenization notifications fail signature verification: they're acknowledged to Adyen but not processed.

How-to

Check the related guide to learn more on how Commerce Layer handles the server-side part of the integration process with Adyen.