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 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.

CRM domain

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)

Processing domain

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
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. 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

Quick 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.

API keys & authentication

The three keys — CRM Key, Processing Key, Partner Key — their scopes, rotation, and blast radius.

CRM provisioning (merchants)

Create acc_xxx merchants and mint CRM Keys for the public API. CRM-only merchants are valid.

Apply for TagadaPay Processing

Same payload for direct merchants (processing.applications.create) and CRM-only partners (partners.processing.applications.create({ accountId, … })). Payfac partners: see Processing provisioning.

Processing provisioning (TPAs)

Create tpa_xxx TPAs, handle KYB requirements and documents, mint Processing Keys.

Embed onboarding (iframe)

Mount TagadaPay’s KYB form inside your app via iframe — partner-branded, same backend as the dashboard form.

Merchant-of-Record sub-merchants (beta)

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.

Merchant automation (REST)

The raw HTTP routes behind both domains, for backends that don’t use the Node SDK.

Server-to-server payments

Card flow, instruments, 3DS, refunds, captures, MIT.

Alternative payment methods

Apple Pay, Google Pay, Klarna, iDEAL — native vs through-processor.

Full end-to-end example

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 or Plugin SDK
A custom checkout page hosted on TagadaPay	Plugin SDK
A simple “Buy Now” button on an external site	Web Integration
Server automation for a single merchant’s store	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).

Get Started

CRM provisioning

Processing provisioning

REST reference

Server-to-server payments

Money movement

Reporting & disputes

End-to-end

Partners — Overview

TagadaPay for Partners

The one thing to understand first: two domains

CRM domain

Processing domain

Entities & ids — never confuse these two

What you can do as a partner

The SDK in one diagram

Mental model in 30 seconds

Humans (Ops) vs machines (API keys)

Where to start

Quick Start

API keys & authentication

CRM provisioning (merchants)

Apply for TagadaPay Processing

Processing provisioning (TPAs)

Embed onboarding (iframe)

Merchant-of-Record sub-merchants (beta)

Merchant automation (REST)

Server-to-server payments

Alternative payment methods

Full end-to-end example

What this section is NOT

​TagadaPay for Partners

​The one thing to understand first: two domains

CRM domain

Processing domain

​Entities & ids — never confuse these two

​What you can do as a partner

​The SDK in one diagram

​Mental model in 30 seconds

​Humans (Ops) vs machines (API keys)

​Where to start

Quick Start

API keys & authentication

CRM provisioning (merchants)

Apply for TagadaPay Processing

Processing provisioning (TPAs)

Embed onboarding (iframe)

Merchant-of-Record sub-merchants (beta)

Merchant automation (REST)

Server-to-server payments

Alternative payment methods

Full end-to-end example

​What this section is NOT

TagadaPay for Partners

The one thing to understand first: two domains

Entities & ids — never confuse these two

What you can do as a partner

The SDK in one diagram

Mental model in 30 seconds

Humans (Ops) vs machines (API keys)

Where to start

What this section is NOT