> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Partners — Overview
> Provision and run merchants on behalf of your customers. Two clearly-separated domains — CRM and Processing — exposed through one Node SDK.
# TagadaPay for Partners
**Who this is for** — Companies who run their own merchant-facing product (PSPs, marketplaces, embedded-payments platforms, recurring-billing tools, virtual terminals) and want to use TagadaPay as their infrastructure for **both** the merchant control plane (orders, stores, customers, subscriptions) **and** card processing.
**Your merchants never see TagadaPay.** They see your brand, your dashboard, your support. TagadaPay sits behind your service.
**Building a single store for yourself instead?** You're in the wrong tab — head to [Developer Tools](/developer-tools/index) for merchant SDKs (Headless, Plugin, Node, Studio MCP…).
***
## The one thing to understand first: two domains
Everything in the platform — API URLs, SDK namespaces, keys, docs — is organized along **one primary axis: CRM vs Processing.**
The **merchant control plane**: stores, products, orders, customers, subscriptions, promotions.
* Base URL: `/api/public/v1`
* Key: **CRM Key** (`sk_crm_…`, legacy UUID still works)
* Scoped to a **merchant** (`acc_xxx`)
**TagadaPay Processing**: provisioning TPAs, KYB, documents, and charging cards / APMs.
* Base URL: `/api/tagadapay/v1`
* Key: **Processing Key** (`tp_sk_…`)
* Scoped to a **TPA** (`tpa_xxx`)
A merchant can use **CRM only**, **Processing only**, or **both** — they are independent. You (directly or on behalf of your merchants) pick what you need.
The **secondary axis** is *who is acting*: a **direct merchant** managing their own data, or a **partner** acting **on behalf of** its sub-merchants. In the SDK that's the difference between the top-level namespaces and `partners.*`.
***
## Entities & ids — never confuse these two
| Entity | id | Domain | What it is |
| ------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
| **Merchant** | `acc_xxx` | CRM | The organization / account. Owns stores, products, orders, CRM keys. **One per merchant.** |
| **TPA** | `tpa_xxx` | Processing | A TagadaPay processing account: KYB, settlement, charging. **A merchant can own 0..N TPAs** (e.g. one per region). |
| **Store** | `store_xxx` | CRM | Auto-created with a merchant. Store ↔ processor routing is configured via payment orchestration. |
| **Partner** | `par_xxx` | both | You. Provisions and manages the above on behalf of your merchants. |
`accountId` (**`acc_xxx`**) and `tpaId` (**`tpa_xxx`**) are **different ids**. A CRM Key knows its `acc_xxx`; a Processing Key knows its `tpa_xxx`. Mixing them up is the #1 integration mistake.
***
## What you can do as a partner
| Domain | Capability | SDK |
| ---------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| CRM | Provision a merchant (`acc_xxx`) + its store | `partners.crm.merchants.create()` |
| CRM | Mint a CRM Key scoped to one merchant | `partners.crm.merchants.keys.create(accId)` |
| Processing | Submit an entity application for a sub-merchant (CRM-only) | `partners.processing.applications.create({ accountId, … })` |
| Processing | Provision a TPA (`tpa_xxx`) — **payfac partners only** | `partners.processing.tpas.create({ legalName, accountId })` |
| Processing | Provision a **MoR sub-merchant** under your own umbrella *(beta, payfac)* | `partners.processing.subMerchants.create({ parentTpaId, accountId, statementDescriptor })` |
| Processing | Mint a Processing Key after promote (CRM-only) | `partners.processing.enroll({ accountId, mode })` |
| Processing | Mint a Processing Key scoped to one TPA | `partners.processing.tpas.keys.create(tpaId)` |
| Processing | Submit KYB requirements & documents | `partners.processing.tpas.requirements.*` / `.documents.upload(tpaId, …)` |
| Processing | Embed KYB form in your app (iframe, partner-branded) | `partners.processing.onboarding.createSession()` — see [Embed onboarding](/developer-tools/partners/embed-onboarding) |
| Processing | Charge cards / APMs server-to-server | `payments.process()` (with a Processing Key) |
| Processing | Tokenize cards / wallets client-side (PCI-safe) | `@tagadapay/core-js` |
***
## The SDK in one diagram
```
new Tagada(key)
│
├── CRM (direct merchant, top-level — /api/public/v1)
│ orders.* stores.* customers.* products.* subscriptions.* promotions.* …
│
├── processing. // direct merchant — /api/tagadapay/v1
│ applications.create / retrieve // apply → reviewed by our team (no TPA create)
│ tpas.list / retrieve // manage TPAs we assigned you
│ tpas.keys.* · tpas.requirements.* · tpas.documents.*
│
├── payments.* · paymentInstruments.* · threeds.* · paymentSetup.* // charging
│
└── partners. // acting on behalf of merchants (partner key)
crm.merchants.create / list / retrieve / retrieveByExternalRef
crm.merchants.keys.create / list / revoke // sk_crm_…
processing.applications.create / retrieve // CRM-only entity intake
processing.enroll({ accountId }) // mint tp_sk_… after promote
processing.tpas.create / list / retrieve // payfac WL only for create
processing.tpas.keys.* · requirements.* · documents.*
processing.subMerchants.create // MoR (payfac)
```
`partners.crm.*` and `partners.processing.*` mirror the platform's two domains. **CRM-only partners** submit entity applications (`applications.create`) or embed — `tpas.create` returns `403 payfac_required`. **Payfac partners** keep `tpas.create`. Direct merchants use `processing.applications.create()` with a CRM key.
***
## Mental model in 30 seconds
```
You (the partner) TagadaPay
───────────── ──────────
1. Get activated ───► partner_id (par_xxx)
Partner key (in the Hub) ───► tp_sk_live_xxx (partner-scoped; provisions both domains)
2a. Provision a merchant ───► acc_xxx + store_xxx (CRM)
crm.merchants.create() → mint sk_crm_… for CRM API access
2b. Processing intake ───► depends on your contract
CRM-only partner: applications.create({ accountId })
→ entity inbox → Tagada promotes → enroll()
Payfac partner: tpas.create({ accountId })
→ self-serve KYB → provision → keys
3. Tokenize browser-side ───► tagadaToken (PCI-safe, single-use)
4. Charge server-to-server ◄─── { paymentId, status, … }
with the Processing Key
```
The keys are the security boundary: a leaked **CRM Key** exposes one merchant's CRM data; a leaked **Processing Key** exposes one TPA's charging — never your whole partner account.
## Humans (Ops) vs machines (API keys)
Two auth models — do not mix them up:
| | **Ops / dashboard** (humans) | **Partner SDK / REST** (machines) |
| ------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Auth | Clerk session | Partner / CRM / Processing **API key** |
| Identity | `tgdRoles` + `whitelabelOwnership` | Key scope (`partner` / `acc_xxx` / `tpa_xxx`) |
| Canonical Ops job | **`payment_ops`** — scope `null` = Tagada global book; scope `"slug"` = that partner's book | — |
| Partner roster owner | `partneradmin` (scoped) | — |
| Opens Ops UI / `/api/v2/ops/*` | Yes (Clerk) | **No** |
| Provisions merchants / TPAs / charges | No (use keys) | Yes (`partners.*`, `payments.*`) |
| Job | Scope | What they can do in Ops |
| ---------------- | -------- | --------------------------------------------------------------------- |
| `payment_ops` | `null` | TagadaPay Ops — **all** partner books + platform surfaces |
| `payment_ops` | `"acme"` | Same Ops UI, **Acme book only** (payfac + active membership required) |
| `partneradmin` | `"acme"` | Own Acme roster; Ops when payfac WL is enabled |
| `accountmanager` | any | CRM / AM tooling — **not** payment Ops |
Full matrix: [IAM Overview](/api-reference/iam-overview). Deprecated / removed aliases (`tagadapaymentAdmin`, `partner_ops`, `hubadmin`, `partnerstaff`) must not be granted — use `payment_ops` + scope.
A Partner Key (`tp_sk_…`) never makes you an Ops user. Mint keys for your backend; invite humans with Clerk roles for the dashboard.
***
## Where to start
The end-to-end flow in a few steps: provision a TPA → mint a Processing Key → tokenize → charge. \~10 minutes to a successful payment.
The three keys — CRM Key, Processing Key, Partner Key — their scopes, rotation, and blast radius.
Create `acc_xxx` merchants and mint CRM Keys for the public API. CRM-only merchants are valid.
Same payload for direct merchants (`processing.applications.create`) and CRM-only partners (`partners.processing.applications.create({ accountId, … })`). Payfac partners: see [Processing provisioning](/developer-tools/partners/accounts).
Create `tpa_xxx` TPAs, handle KYB requirements and documents, mint Processing Keys.
Mount TagadaPay’s KYB form inside your app via iframe — partner-branded, same backend as the dashboard form.
**Beta.** Are YOU the merchant-of-record? Provision sub-merchants under your own payfac umbrella (shared balance account, per-sub-merchant statement descriptors, no KYB) — returned `active` immediately.
The raw HTTP routes behind both domains, for backends that don't use the Node SDK.
Card flow, instruments, 3DS, refunds, captures, MIT.
Apple Pay, Google Pay, Klarna, iDEAL — native vs through-processor.
A complete partner integration: provision → charge → refund, in one place.
***
## What this section is NOT
| If you’re building… | Use instead |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| A web checkout for **your own** store | [Headless SDK](/developer-tools/headless-sdk/introduction) or [Plugin SDK](/developer-tools/sdk/introduction) |
| A custom checkout page hosted on TagadaPay | [Plugin SDK](/developer-tools/sdk/introduction) |
| A simple "Buy Now" button on an external site | [Web Integration](/developer-tools/web-integration/trigger-checkout-from-website) |
| Server automation for a **single** merchant’s store | [Node SDK quick start](/developer-tools/node-sdk/quick-start) |
The "Partners" section assumes you’re acting on behalf of **many merchants** and need the multi-tenant primitives (merchants, TPAs, scoped keys).