Merchant-of-Record sub-merchants
Beta. The Merchant-of-Record sub-merchant system is in beta: it is rolled out to selected partners case by case, and its API surface and behavior may still change. Coordinate with your account manager before using it in production.
partners.processing.subMerchants.create() provisions a sub-merchant under your own Adyen umbrella: it reuses your legal entity, account holder and settlement balance account, and only creates a dedicated acquiring point (its own store + statement descriptor). It is returned active immediately — no requirements, no provision().
Not a MoR? If each of your merchants is the legal merchant (their own KYB, their own payouts), use Processing provisioning (TPAs) instead — payfac:
tpas.create() + requirements + provision(); CRM-only: applications.create({ accountId }) or embed. Don’t use this page.Two provisioning models, side by side
Everything downstream of provisioning is identical: mint a processing key on the sub-merchant, tokenize with
core-js, and payments.process(). The Quick Start charge flow works unchanged on a sub-merchant key.
What gets created
store_xxx, for checkout & payment routing) comes with its CRM merchant — it is auto-provisioned by partners.crm.merchants.create() in step 1 below.
On the Tagada side, subMerchants.create() also wires the charge routing for you: a router processor pointing at the sub-merchant, a default payment flow, and the link to its CRM store. The sub-merchant is chargeable as soon as the call returns — no extra setup.
Prerequisites
- A provisioned root TPA — your own
tpa_xxx, fullyactiveon Adyen (legal entity + account holder + balance account). This is the umbrella every sub-merchant nests under. Provision it the normal way once (Processing provisioning). - MoR enabled for your partner account, with your root TPA set as the default parent (optional — you can also pass
parentTpaIdon every call).
Provision a sub-merchant
Each sub-merchant needs its own CRM merchant (acc_xxx) — sub-merchants share your balance account, so the (account, balance-account) pair must stay unique. Create the merchant first, then the sub-merchant.
Idempotent. A second call with the same
externalRef returns the same sub-merchant (created=false, X-Tpa-Idempotent-Replay: 1). Safe to retry.Charge on it — same as any TPA
Card scheme activation is asynchronous on Adyen’s side. The store is
active immediately, but Visa/Mastercard/Amex enablement on a brand-new store can take a short while to propagate (typically minutes). If a first charge declines right after provisioning, retry after a few minutes before digging further.Statement descriptor
statementDescriptor is the only per-sub-merchant branding on the cardholder’s statement (Adyen shopperStatement, capped at 22 chars). Because each sub-merchant gets its own Adyen store, two sub-merchants under the same umbrella show different descriptors — even though they settle to the same balance account.
Settlement & payouts
For the same reason, sub-merchant balance/ledger views in reporting reflect the shared (partner) balance account — treat the partner account as the source of truth for money movement. To observe payouts and the balance ledger over the API (always on your root TPA), see Payouts, balances & fees.What you cannot do on a sub-merchant
These are enforced server-side: dangerous operations on a sub-merchant child (
parentTpaId set) are refused so they can never mutate or drain the shared parent tree.
Errors
Next step
Charge a sub-merchant
The card flow, instruments, 3DS, APMs and refunds are identical to any TPA — mint a processing key on the sub-merchant and go.
