> 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/2026-05/payment_setting_adyens.md).

# Payment setting adyens

The payment setting adyen object and the allowed CRUD operations on the related resource endpoint

Adyen payment settings are the Adyen-specific subtype of [payment settings](/core-api-reference/2026-05/payment_settings.md). They hold the credentials and configuration required to process payments through the [Adyen](https://www.adyen.com) payment gateway.

## Credentials

Setting up an Adyen payment setting requires the following credential attributes:

<table><thead><tr><th width="310">Attribute</th><th>Description</th><th width="100" data-type="checkbox">Required</th></tr></thead><tbody><tr><td><strong><code>merchant_account</code></strong></td><td>Your Adyen merchant account identifier.</td><td>true</td></tr><tr><td><strong><code>api_key</code></strong></td><td>Adyen API key for server-side requests.</td><td>true</td></tr><tr><td><strong><code>webhook_endpoint_secret</code></strong></td><td>HMAC secret used to verify incoming Adyen <a href="#webhook-events">webhooks</a>.</td><td>true</td></tr><tr><td><strong><code>public_key</code></strong></td><td>Adyen client-side encryption public key.</td><td>false</td></tr><tr><td><strong><code>live_url_prefix</code></strong></td><td>Live environment URL prefix — needed for production traffic, though not enforced as a required field by the API.</td><td>false</td></tr><tr><td><strong><code>token_webhook_endpoint_secret</code></strong></td><td>HMAC secret used to verify incoming Adyen <a href="#tokenization-webhook-events">tokenization webhooks</a>. Only needed if you configure that webhook type.</td><td>false</td></tr></tbody></table>

## Gateway versions

Adyen payment settings support the following gateway versions, corresponding to Adyen's Checkout API version:

* `70`
* `71` (default)

## Internal versions

Adyen payment settings support the following [internal versions](/core-api-reference/2026-05/payment_settings.md#internal-versions) — Commerce Layer's own payload-building variants, unrelated to the [gateway version](#gateway-versions) above:

<table><thead><tr><th width="120">Action</th><th width="150">Version</th><th>Effect</th></tr></thead><tbody><tr><td><strong><code>payments</code></strong></td><td><code>LineItemSku</code></td><td>Adds a <code>sku</code> field (matching the SKU's <code>item_code</code>) to every line item — needed by some risk/BNPL Adyen payment methods.</td></tr><tr><td><strong><code>payments</code></strong></td><td><code>WalletCvv</code></td><td>Lets the request reference a stored payment wallet while still running through the standard ecommerce flow: forces the <code>shopperInteraction</code> value to <code>Ecommerce</code> (instead of the <code>ContAuth</code> normally used for stored-credential payments), requires native 3DS authentication, and requires the CVV to be resubmitted via <code>encryptedSecurityCode</code> in the payment method data.</td></tr></tbody></table>

{% hint style="info" %}
Any other Adyen action — i.e. `payment_methods`, `payment_details`, `modification`, `void`, `stored_payment_method`, `link` — only has the default built-in behavior. There's no alternate version to select.
{% endhint %}

## Capabilities

Adyen payment settings support the following Commerce Layer features:

<table><thead><tr><th>Feature</th><th width="100" data-type="checkbox">Supported</th></tr></thead><tbody><tr><td>Payment sessions</td><td>true</td></tr><tr><td>Payment wallets</td><td>true</td></tr><tr><td>Payment links</td><td>true</td></tr><tr><td>3DS / SCA</td><td>true</td></tr></tbody></table>

## Session creation

Adyen requires a session to be created server-side before displaying the payment form. Commerce Layer creates this session automatically when a payment session is created with an Adyen payment setting. The raw Adyen session response — including the `id` and `sessionData` fields required to initialize the Drop-in or Components SDK — is available in the `response_data` attribute of the payment session.

{% hint style="info" %}
There is one exception: a session that renews an [order subscription](/core-api-reference/2026-05/order_subscriptions.md#unattended-renewals) is charged with nobody at a browser, so no Adyen session is created for it — there is no payment form to display. Commerce Layer mints the session token itself and charges the stored instrument directly through the Payments API, as a stored-credential `ContAuth` payment.
{% endhint %}

{% hint style="warning" %}
Note that `response_data` is distinct from `payment_session.token`, which is Commerce Layer's own identifier used as the `merchantReference` for subsequent webhook events.
{% endhint %}

What happens next follows one of Adyen's two [integration flows](https://docs.adyen.com/online-payments/build-your-integration), depending on whether a payment method (or a stored payment wallet) accompanies the authorization request:

* **Sessions flow** — when no `payment_method` and no wallet are submitted, Commerce Layer never calls Adyen's Payments API. The Drop-in or Components SDK handles the whole payment on Adyen's side using the session created above, and the outcome — succeeded or failed — is only known once the `AUTHORISATION` webhook arrives (more details [below](#webhook-events)).
* **Advanced flow** — when a `payment_method` is submitted, or a stored payment wallet is used, Commerce Layer authorizes the payment synchronously against Adyen's Payments API. Once the customer completes the form, payment details must be submitted back (more details [here](/core-api-reference/2026-05/payment_authorizations.md#handling-3ds-and-customer-action)).

{% hint style="info" %}
A set of [integration](/core/api-credentials.md#integration) API credentials can supply a custom token at payment session creation time to use as the merchant reference (more details [here](/core-api-reference/2026-05/payment_sessions.md#session-token)).
{% endhint %}

## Wallet vaulting

When a payment wallet is created against an Adyen payment setting, Commerce Layer identifies the shopper to Adyen using the customer's own `shopper_reference` unless you supply a different customer token yourself — Adyen never generates or returns a separate customer identifier of its own for this purpose.

{% hint style="info" %}
You can find more information about how this compares to the other payment providers [here](/core-api-reference/2026-05/payment_wallets.md#token-references).
{% endhint %}

### Duplicate wallets

Adyen keeps one stored payment method per card and shopper, and returns the same one when that card is stored again. When a payment session with vaulting enabled stores a card the customer already holds in an active wallet, the session is linked to that wallet instead of creating a new one.

{% hint style="warning" %}
Creating a wallet directly for a card that's already stored in one of the customer's active wallets is rejected, with a `422 Unprocessable Entity` error pointing to the existing wallet.
{% endhint %}

## Webhook events

Commerce Layer listens to the following Adyen notification events — sent to the `webhook_endpoint_url` attribute exposed on this resource, which you configure in the Adyen Customer Area as a [Standard Notification webhook](https://docs.adyen.com/development-resources/webhooks/) — and maps them to payment transactions:

<table><thead><tr><th width="330">Event</th><th>Transaction</th></tr></thead><tbody><tr><td><strong><code>AUTHORISATION</code></strong></td><td>Payment authorization — <code>succeeded</code> or <code>failed</code>.</td></tr><tr><td><strong><code>CANCELLATION</code></strong> / <strong><code>CANCEL_OR_REFUND</code></strong></td><td>Payment void — <code>succeeded</code> or <code>failed</code>.</td></tr><tr><td><strong><code>CAPTURE</code></strong></td><td>Payment capture — <code>succeeded</code> or <code>failed</code>.</td></tr><tr><td><strong><code>REFUND</code></strong></td><td>Payment refund — <code>succeeded</code> or <code>failed</code>.</td></tr><tr><td><strong><code>EXPIRE</code></strong></td><td>Payment authorization transitions to <code>expired</code>.</td></tr><tr><td><strong><code>RECURRING_CONTRACT</code></strong></td><td>Payment wallet — creates or updates the customer's wallet to <code>succeeded</code>, or cancels it on failure.</td></tr></tbody></table>

Events are matched to a payment session using the `merchantReference` field, which Commerce Layer sets to the session token on all outbound requests. If a transaction for the event does not already exist, it is created automatically.

{% hint style="info" %}
`RECURRING_CONTRACT` is sent when Adyen tokenizes a card asynchronously during a payment (e.g. `storePaymentMethod` requested without an immediate synchronous token). Commerce Layer resolves the customer through the originating payment session and, on success, either updates the matching payment wallet or creates a new one with the vaulted `recurringDetailReference` as its `payment_token` — no separate `POST` request to the `/payment_wallets` endpoint is required in this case.
{% endhint %}

### Tokenization webhook events

Adyen is introducing a separate [tokenization webhooks](https://docs.adyen.com/api-explorer/Tokenization-webhooks/1/overview) family intended to eventually replace `RECURRING_CONTRACT` for token lifecycle notifications. Commerce Layer supports both side by side on the same `webhook_endpoint_url`.

{% hint style="warning" %}
This means that there's no new URL to configure. Just remember that the tokenization webhook events must be registered as an **additional**, separate webhook in the Adyen Customer Area (selecting the *Tokenization webhook* type rather than *Standard notification*), with its own HMAC key stored on `token_webhook_endpoint_secret`.
{% endhint %}

<table><thead><tr><th width="330">Event</th><th>Effect</th></tr></thead><tbody><tr><td><strong><code>recurring.token.created</code></strong></td><td>Creates a <code>succeeded</code> payment wallet for the token, or transitions an existing one to <code>succeeded</code> if already present.</td></tr><tr><td><strong><code>recurring.token.alreadyExisting</code></strong></td><td>Same as <code>recurring.token.created</code> — treated as idempotent, since both indicate the token is valid and usable.</td></tr><tr><td><strong><code>recurring.token.updated</code></strong></td><td>Refreshes the matching payment wallet's stored data, without changing its status.</td></tr><tr><td><strong><code>recurring.token.disabled</code></strong></td><td>Cancels the matching payment wallet.</td></tr></tbody></table>

{% hint style="info" %}
Unlike `RECURRING_CONTRACT`, tokenization events aren't necessarily tied to a payment session. Commerce Layer resolves the customer from the token's shopper reference whenever no matching wallet already exists for it.
{% endhint %}

{% hint style="warning" %}
Set `token_webhook_endpoint_secret` **before** enabling the tokenization webhook in the Adyen Customer Area. Until it's configured, incoming tokenization events for this payment setting fail signature verification and are rejected — `RECURRING_CONTRACT` handling is unaffected either way.
{% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_adyens.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.