Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Beta

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. They hold the credentials and configuration required to process payments through the Adyen payment gateway.

Credentials

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

Attribute
Description
Required

merchant_account

Your Adyen merchant account identifier.

api_key

Adyen API key for server-side requests.

webhook_endpoint_secret

HMAC secret used to verify incoming Adyen webhooks. Generated automatically when the webhook is provisioned by Commerce Layer, otherwise to be copied manually from the Adyen Customer Area.

public_key

Adyen client-side encryption public key.

live_url_prefix

Live environment URL prefix — needed for production traffic, though not enforced as a required field by the API.

webhook_endpoint_id

ID of the automatically created Adyen webhook. Read-only.

token_webhook_endpoint_secret

HMAC secret used to verify incoming Adyen tokenization webhooks. Only needed if you configure that webhook type.

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 — Commerce Layer's own payload-building variants, unrelated to the gateway version above:

Action
Version
Effect

payments

LineItemSku

Adds a sku field (matching the SKU's item_code) to every line item — needed by some risk/BNPL Adyen payment methods.

payments

WalletCvv

Lets the request reference a stored payment wallet while still running through the standard ecommerce flow: forces the shopperInteraction value to Ecommerce (instead of the ContAuth normally used for stored-credential payments), requires native 3DS authentication, and requires the CVV to be resubmitted via encryptedSecurityCode in the payment method data.

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.

Capabilities

Adyen payment settings support the following Commerce Layer features:

Feature
Supported

Payment sessions

Payment wallets

Payment links

3DS / SCA

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.

There is one exception: a session that renews an order subscription 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.

What happens next follows one of Adyen's two integration flows, 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).

  • 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).

A set of integration API credentials can supply a custom token at payment session creation time to use as the merchant reference (more details here).

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 session options are kept as is — Commerce Layer only fills in what's missing.

Adyen request
Data sent

Payment methods

amount, shopperEmail, shopperLocale, shopperConversionId

Sessions

deliveryAddress, telephoneNumber, shopperName, shopperLocale, shopperInteraction, accountInfo, merchantOrderReference, shopperConversionId

Payments

riskData, accountInfo, merchantOrderReference, shopperConversionId

Payment links

merchantOrderReference

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

  • riskData — the device fingerprint collected by Adyen's Drop-in or Components. In the advanced flow, it's forwarded only if your checkout includes it as riskData in the payment session's client_data. In the sessions flow, the Adyen SDK sends it directly.

  • 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, sessions, and payments — carries the same value.

  • shopperLocale — taken from shopper_locale in the payment session's client_data.

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.

You can find more information about how this compares to the other payment providers here.

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.

Webhook management

When an Adyen payment setting is created, 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 payment setting is deleted.

If you prefer not to grant that role, configure the Standard webhook in the Adyen Customer Area yourself, pointing it to webhook_endpoint_url, and set its HMAC key on webhook_endpoint_secret — either at creation time or with a later update. The payment setting becomes active as soon as the secret is set.

Webhook events

Commerce Layer listens to the following Adyen notification events — sent to the webhook_endpoint_url attribute exposed on this resource (more details above) — and maps them to payment transactions:

Event
Transaction

AUTHORISATION

Payment authorization — succeeded or failed.

CANCELLATION / CANCEL_OR_REFUND

Payment void — succeeded or failed.

CAPTURE

Payment capture — succeeded or failed.

REFUND

Payment refund — succeeded or failed.

EXPIRE

Payment authorization transitions to expired.

RECURRING_CONTRACT

Payment wallet — creates or updates the customer's wallet to succeeded, or cancels it on failure.

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.

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.

Tokenization webhook events

Adyen is introducing a separate tokenization webhooks family intended to eventually replace RECURRING_CONTRACT for token lifecycle notifications. Commerce Layer supports both side by side on the same webhook_endpoint_url.

Event
Effect

recurring.token.created

Creates a succeeded payment wallet for the token, or transitions an existing one to succeeded if already present.

recurring.token.alreadyExisting

Same as recurring.token.created — treated as idempotent, since both indicate the token is valid and usable.

recurring.token.updated

Refreshes the matching payment wallet's stored data, without changing its status.

recurring.token.disabled

Cancels the matching payment wallet.

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.

Last updated