Skip to main content

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.
Some partners are the Merchant-of-Record (MoR) for the businesses they serve: they hold the acquiring contract, funds settle to them, and they redistribute to their sub-merchants off-platform. For that model, spinning up a full KYB’d payfac tree per sub-merchant is wrong — the sub-merchant is not the legal merchant, you are. 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().
This is opt-in per partner. The MoR sub-merchant system must be enabled for your partner account (ask your account manager). Until then, subMerchants.create() returns 403 mor_sub_merchant_not_enabled.
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

Only the business line + store are new on Adyen. The account holder and balance account are yours — that’s why funds settle to you. The sub-merchant’s CRM store (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

  1. A provisioned root TPA — your own tpa_xxx, fully active on Adyen (legal entity + account holder + balance account). This is the umbrella every sub-merchant nests under. Provision it the normal way once (Processing provisioning).
  2. MoR enabled for your partner account, with your root TPA set as the default parent (optional — you can also pass parentTpaId on 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

Funds settle to YOU, not the sub-merchant. Every charge on a sub-merchant lands in your (the partner’s) settlement balance account. Tagada does not pay out to sub-merchants in MoR mode — redistributing to them is your responsibility, off-platform. The split stays as configured: Tagada’s commission and your markup are kept as separate legs; the remainder settles into your balance account.
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.