Merchant Configuration — Adyen
Level 200 — Configuration Applies To: Gateway=Adyen | Integration=SPF, MS | Variants=ALL
Prerequisites: Getting Started · SKU Naming Convention
What Does This Page Cover?
Everything provisioned at the Group and Merchant MGMT endpoints for an Adyen deployment. Terminal and MPG configuration are covered in their own pages — do not configure those until the merchant record exists.
Key Differences From MPGS
Adyen's authentication model is fundamentally different from MPGS:
- API Key lives on the Merchant, not on the MPG. The
ADYEN_API_KEYfield authenticates all Adyen API calls for this merchant. - Host DNS (
ADYEN_HOST_MERCHANT_DNS) is the Adyen checkout endpoint, not a per-PM gateway URL. All payment methods share one endpoint. - Terminal merchant account and POIID are configured at
terminalConfig(not here) and are the per-terminal credentials Adyen uses to route transactions.
1. Group (Optional)
A group logically wraps merchants. If a group exists, the merchant groupId must
reference it. Groups are optional — many deployments provision merchants without one.
| Field | MGMT Field | Required | Notes |
|---|---|---|---|
GROUP_ID |
groupId |
Conditional | Required only if deploying under a group. |
GROUP_NAME |
groupName |
Conditional | Also written to aliasName and comment. |
2. Merchant Identity
| Field | MGMT Field | Required | Sample | Notes |
|---|---|---|---|---|
MERCHANT_NAME |
merchantName |
Mandatory | Alliants Test |
Display name. |
REGION_ID |
regionId |
Mandatory | — | See Region Codes. BLOCKED — regions.yaml missing (OI-004). |
COUNTRY_CODE |
countryCode |
Mandatory | AUS |
ISO alpha-3. Depends on REGION_ID. See Countries. |
CURRENCY_CODE |
currencyCode |
Conditional | AUD |
ISO 4217. See Currencies. |
ADDR |
addr |
Conditional | <secret> |
Street address. Supply via secrets manager. |
CITY |
city |
Conditional | — | |
STATE |
state |
Conditional | — |
3. Commerce Settings
| Field | MGMT Field | Required | Sample | Notes |
|---|---|---|---|---|
BUSINESS_SYSTEM |
businessSystem |
Conditional | — | See Business Systems. |
BILLING_METHOD |
billingMethod |
Conditional | — | |
SERVICE_ENTRY |
serviceEntry |
Conditional | — | ⚠️ Confirm value with integration owner. |
INDUSTRYTYPE |
extData5 |
Conditional | — | Adyen industry classification. |
SMART_AUTH |
extData6 |
Conditional | — | Enables Adyen Smart Auth. |
ENABLE_ZIP_INPUT |
extData7 |
Conditional | — | Enables ZIP code input at checkout. |
LODGING_METADATA_ONLY |
extData8 |
Conditional | — | Lodging SKUs only. |
SKU_STAMP |
extData10 |
Conditional | FNB-ALL-0001-A-110000 |
SKU identifier stamped on merchant. Set to the active SKU ID. |
4. Gateway Credentials
These are secrets. Never commit to source control. Supply via secrets manager.
| Field | MGMT Field | Required | Notes |
|---|---|---|---|
ADYEN_API_KEY |
extData1 |
Mandatory | Adyen REST API key. Authenticates all API calls for this merchant. |
ADYEN_HOST_MERCHANT_DNS |
extData3 |
Mandatory | Adyen checkout endpoint (e.g. https://checkout-test.adyen.com). |
ADYEN_TERMINAL_MERCHANT_DNS |
extData4 |
Conditional | Terminal API endpoint. Required if PM0 (card-present) is active. |
ADYEN_HOST_MERCHANT_VERSION |
extData2 |
Mandatory | API version string (e.g. v71). Must match Adyen API version in use. |
Why is the API Key on the merchant, not the MPG? Adyen uses a single API Key per merchant for all payment methods. There are no per-PM-slot host credentials. The MPG entries carry mapper IDs and STS references instead — see MPG Configuration.
5. API User
| Field | MGMT Field | Required | Notes |
|---|---|---|---|
API_USER |
(template) | Conditional | API user template. See Tokenisation if STS is in use. |
Open Items
| # | Item | Impact |
|---|---|---|
| OI-004 | data/reference/regions.yaml missing |
REGION_ID value page unavailable |
| OI-005 | data/reference/countries.yaml missing |
COUNTRY_CODE value page unavailable |
| OI-006 | data/reference/currencies.yaml missing |
CURRENCY_CODE value page unavailable |
| OI-SERVICE | SERVICE_ENTRY value not documented |
Confirm with Adyen integration owner |
See Also
- Terminal Configuration — next provisioning step
- MPG Configuration — configure after terminal
- Field Catalog — full field definitions with types and constraints
Collecting Credentials from the Adyen Portal
When your Adyen portal setup is complete, the following credentials will be issued. Use this table to map the portal label to the correct field in the Astral MGMT configuration.
These are secrets. Never store in source control or share in plain text. Supply via the secrets manager.
| Portal Label | Where to find it in the portal | Our Field Key | MGMT Object | MGMT Field |
|---|---|---|---|---|
| API Key 🔒 | Developers → API credentials → Generate API key | ADYEN_API_KEY |
Merchant | extData2 |
| Checkout API URL 🔒 | Developers → API credentials → Server settings | ADYEN_HOST_MERCHANT_DNS |
Merchant | extData4 |
| Terminal API URL 🔒 | Developers → API credentials → Server settings | ADYEN_TERMINAL_MERCHANT_DNS |
Merchant | extData5 |
| Client Key 🔒 | Developers → API credentials → Client key | CLIENT_KEY |
MPG PM4 (ecom) | extData5 |
| HMAC Key 🔒 | Developers → Webhooks → configure webhook → HMAC key | WEBHOOK_HMAC |
MPG PM4 (ecom) | extData9 |
| Merchant Account 🔒 | Merchants → select merchant → Account name | ADYEN_MERCHANT_ACCOUNT |
TerminalConfig | channelMerchantId |
| POIID 🔒 | Point of Sale → Terminals → select terminal → POIID | ADYEN_POIID |
TerminalConfig | channelTerminalId |
🔒 = secret field — supply via secrets manager, never hardcode.