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:
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:
7071(default)
Internal versions
Adyen payment settings support the following internal versions — Commerce Layer's own payload-building variants, unrelated to the gateway version above:
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.
Capabilities
Adyen payment settings support the following Commerce Layer features:
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.
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_methodand 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 theAUTHORISATIONwebhook arrives (more details below).Advanced flow — when a
payment_methodis 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).
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.
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 asriskDatain the payment session'sclient_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 fromshopper_localein the payment session'sclient_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.
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:
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.
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.
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.
Last updated