MerchantPaymentGateway Configuration — Adyen

Level 200 — Configuration Applies To: Gateway=Adyen | Integration=SPF, MS | Variants=ALL

Prerequisites: Terminal Configuration

What Is a MerchantPaymentGateway?

A merchantPaymentGateway (MPG) entry connects a specific payment method slot to the Adyen gateway. A merchant with multiple active payment methods needs one MPG entry per payment method slot.

Adyen critical difference: MPG entries do not contain gateway credentials. Adyen credentials live on the Merchant (ADYEN_API_KEY, ADYEN_HOST_MERCHANT_DNS) and on the terminalConfig (ADYEN_MERCHANT_ACCOUNT, ADYEN_POIID). MPG entries carry mapper IDs and STS channel references only.

Adyen MPG Array Overview

The number of MPG entries depends on the active SKU bitmap. Unlike MPGS, Adyen does not require separate sync/async entries for PM1 — one entry per active PM slot.

Entry PM Slot Role Purpose
1 PM0 bank_card Card-present via physical terminal
2 PM1 token Tokenised / card-on-file transactions
3 PM4 ecom Browser-based via Adyen Drop-in

A merchant using only PM0+PM1 (bitmap 110000) has 2 MPG entries. A merchant using PM0+PM1+PM4 (bitmap 111000) has 3 entries.

Common Fields (All Entries)

These two fields appear on every MPG entry regardless of PM slot.

Field MGMT Field Required Notes
GATEWAY_ID gatewayId Conditional Adyen gateway identifier. Set from platform configuration.
STS_TOKEN_CHANNEL extData1 Mandatory STS token channel reference. Links this MPG entry to the STS token space. See Tokenisation.

Entry 1 — PM0 Bank Card (Card Present)

Card-present transactions through a physical Adyen terminal.

Field MGMT Field Required Notes
MAPPER_CP extData2 Mandatory Card-present mapper ID. Maps Adyen response codes to internal transaction codes.
WAIT_FOR_WEBHOOK_CP extData3 Mandatory Whether to wait for Adyen webhook confirmation before returning response. true = synchronous webhook wait.

WAIT_FOR_WEBHOOK_CP controls the processing model. Setting this to true means the platform waits for Adyen's async webhook before confirming the transaction. Setting it false returns immediately and handles the webhook event separately. Choose based on the merchant's integration requirements.

Entry 2 — PM1 Token

Tokenised transactions (MOTO, card-on-file, recurring).

Field MGMT Field Required Notes
MAPPER_TOKEN extData2 Mandatory Token mapper ID. Maps Adyen response codes for token transactions.
STS_TOKEN_CHANNEL_4 extData3 Conditional Additional STS token channel for token processing (channel 4 slot).

Entry 3 — PM4 Ecommerce (Drop-in)

Browser-based payments via Adyen Drop-in hosted components.

Field MGMT Field Required Notes
MAPPER_ECOM extData2 Mandatory Ecommerce mapper ID. Maps Adyen response codes for ecom transactions.
HPP_POPOUT extData3 Conditional Controls Drop-in display mode. true = popout overlay, false = inline.
CLIENT_KEY extData4 Conditional Adyen client-side key for Drop-in initialisation. Supply via secrets manager.
ADYEN_SDK_VERSION extData5 Conditional Adyen Web SDK version string (e.g. 5.26.0). Must match the version bundled in the frontend.
ADYEN_COUNTRY extData6 Conditional Country code for Adyen Drop-in localisation.
WEBHOOK_HMAC extData7 Conditional HMAC key for verifying Adyen webhook payloads. Supply via secrets manager.
ALLOW_PAYMENT_METHODS extData8 Conditional ⚠️ Comma-separated list of Adyen payment method types to allow (e.g. scheme,ideal). Confirm with integration owner.
THEME_ID extData9 Conditional Adyen Drop-in theme identifier.

Why does PM4 have so many fields? Adyen's Drop-in SDK is initialised client-side and needs the CLIENT_KEY, SDK_VERSION, and optionally THEME_ID and ALLOW_PAYMENT_METHODS to render correctly. WEBHOOK_HMAC is separate — it is used server-side to verify that inbound webhook calls genuinely originate from Adyen.

Provisioning Checklist

Before submitting MPG configuration:

Open Items

# Item
OI-MAPPER Mapper ID values not documented — obtain from Adyen integration owner
OI-ALLOW_PM ALLOW_PAYMENT_METHODS allowed values not confirmed
OI-WEBHOOK WAIT_FOR_WEBHOOK_CP default value not confirmed — varies by deployment

See Also