> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/adyen_gateways.md).

# 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](https://docs.adyen.com/). 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.

{% hint style="warning" %}
Commerce Layer currently supports the latest version (`v71`) of [Adyen Checkout API](https://docs.adyen.com/api-explorer/Checkout/71/overview) 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](https://docs.adyen.com/online-payments/release-notes).
{% endhint %}

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](https://docs.adyen.com/account/manage-account-structure), [API key](https://docs.adyen.com/development-resources/api-credentials), etc. — contact [Adyen's support](https://www.adyen.help/hc/en-us) if you are not sure about the requested data).

{% hint style="warning" %}
To get real orders and be able to process live transactions with Adyen make sure to get your [live URL prefix](https://docs.adyen.com/development-resources/live-endpoints#live-url-prefix) and correctly set the `live_url_prefix` attribute of the gateway.
{% endhint %}

{% hint style="info" %}
If you're leveraging Adyen's native [Drop-in](https://docs.adyen.com/online-payments/3d-secure/native-3ds2/web-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](/core-api-reference/customer_payment_sources.md), you can set the `native_customer_payment_sources` attribute to `true` (default is `false`).
{% endhint %}

## Adyen Uplift

Commerce Layer sends the shopper and order data required by [Adyen Uplift](https://docs.adyen.com/online-payments/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.

{% hint style="info" %}
When `api_version` is `69` or higher, 3DS is requested in the [native format](https://docs.adyen.com/online-payments/3d-secure/native-3ds2/) 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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## 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](/how-tos/placing-orders/payments/adyen/configuring-the-notification-webhooks.md).

If you create an Adyen gateway without a `webhook_endpoint_secret`, Commerce Layer configures a merchant-level [Standard webhook](https://docs.adyen.com/development-resources/webhooks/) pointing to `webhook_endpoint_url` through Adyen's [Management API](https://docs.adyen.com/api-explorer/Management/latest/overview), 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.

{% hint style="warning" %}
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.
{% endhint %}

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.

{% hint style="warning" %}
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.
{% endhint %}

### Tokenization webhooks

Commerce Layer also supports Adyen's [tokenization webhooks](https://docs.adyen.com/api-explorer/Tokenization-webhooks/1/overview) 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](/core-api-reference/customer_payment_sources.md), 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.

{% hint style="warning" %}
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.
{% endhint %}

<details>

<summary>How-to</summary>

Check the related [guide](/how-tos/placing-orders/payments/adyen.md) to learn more on how Commerce Layer handles the server-side part of the integration process with Adyen.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commercelayer.io/core-api-reference/adyen_gateways.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.