# Platform onboarding

> Onboard sub-merchants from your platform via the Payments AI Public API.

<CopyAiContextButton pageTitle="Platform onboarding" pagePath="/platform-onboarding" />

Use this guide when your platform (ClickFunnels, a marketplace, a page builder, etc.) creates PAI
merchants on behalf of the businesses that use your product. It covers your merchant's own API
key, `POST /v1/public-api/merchants`, key lifecycle for the sub-merchants you create, how owner
assignment works, how to tell when a seller claims a merchant, and what you can (and cannot) do
for KYC today.

The create, read, and assign operations live in the [API Reference](/api) under **Merchant** (with API key lifecycle under **API Keys**). Catalog and checkout routes stay under **Products** and **Checkout**.

There is no separate "platform" credential. **Your own Merchant API Key onboards
sub-merchants** — any merchant without a parent of its own may call this endpoint. A merchant
that already has a parent cannot itself become a parent (one level of nesting only — see
[The one-level cap](#4-the-one-level-cap)).

## Full data-plane authority

**Your Merchant API Key has the same access to every sub-merchant it creates as that
sub-merchant's own key.** It is not read-only and it is not limited to onboarding — it can
create products, run checkouts, issue refunds, and mint or revoke API keys for any of your
sub-merchants, exactly as if it were that sub-merchant's own key. Treat it accordingly:
encrypted at rest, redacted from logs, rotated on a schedule, revoked immediately if you suspect
exposure. Revoking your key cascades to every key it minted over the Public API — see
[Key lifecycle](#3-key-lifecycle-for-your-sub-merchants) below.

To also receive webhooks for activity on sub-merchants you created, configure endpoints on your **parent** merchant in **Developer Tools → Webhooks** and enable **Receive sub-merchant events** on each listener. Event types still follow each endpoint's subscription list. Details: [Webhooks](/webhooks).

## 1. Prerequisites

- Your own Merchant API Key (`pai_test_*` in sandbox, `pai_live_*` in live) — the same key you
  use for `/v1/public-api/merchants/{merchantId}/products`, checkouts, etc. There is no
  separate platform-scoped credential.
- Keep sandbox and live keys strictly separated — a `pai_test_*` key is rejected in live
  deployments and vice-versa.
- When sellers go live, see [Sandbox → Live for platforms](/platform-sandbox-to-live).

## 2. Create a sub-merchant

```http
POST /v1/public-api/merchants
Authorization: Bearer pai_live_...
Content-Type: application/json

{
  "name": "Acme Coaching",
  "email": "founder@acmecoaching.com",
  "phone": "+14155552671",
  "merchantId": "01930000-0000-7000-8000-0000000000ab",
  "websiteUrl": "https://acmecoaching.com",
  "allowedReturnHosts": ["acme.myclickfunnels.com", "go.acmecoaching.com"]
}
```

- `name` — business name; PAI appends `'s Merchant` internally.
- `email` — the future owner's email. See [Assign team members (including owners)](#5-assign-team-members-including-owners).
- `phone` — optional E.164 phone (`^\+[1-9]\d{1,14}$`). Dashboard KYC collects it later if you omit it.
- `merchantId` — optional client-supplied UUID v7. **Supply your own** so a network retry cannot double-provision — re-posting the same id with the same details returns `created: false` idempotently.
- `websiteUrl` — optional HTTPS URL (max 255 characters) for the sub-merchant's storefront or funnel. A checkout `returnUrl` on **exactly** this hostname is allowed (`https://shop.example.com` and `https://www.shop.example.com` are different hosts). `http://` is rejected. To allow more hosts, such as a funnel domain and the seller's custom domains, list them in `allowedReturnHosts`.
- `allowedReturnHosts` — optional list of up to 20 extra hostnames a checkout `returnUrl` may use. See [Allowed checkout return hosts](#allowed-checkout-return-hosts).

The new merchant is parented to **you** — the merchant bound to the API key making the call.
There is no `parentId` field in the body: parentage is always derived from the calling key,
never from anything the client sends.

### Response (`201 Created`)

```json
{
  "merchantId": "01930000-0000-7000-8000-0000000000ab",
  "created": true,
  "ownerAttached": false,
  "joinUrl": "https://app.payments.ai/join#token=<opaque>&merchantId=01930000-0000-7000-8000-0000000000ab",
  "joinUrlExpiresAt": "2026-09-25T15:04:05Z"
}
```

- `created` — `true` on first success, `false` on an idempotent replay.
- `ownerAttached` — whether create assigned an owner. See [Assign team members (including owners)](#5-assign-team-members-including-owners).
- `joinUrl` — owner-claim deep link. Present only when `ownerAttached` is `false`. Deliver it to the seller through your own channel; **PAI does not email the seller.** 7-day TTL.
- `joinUrlExpiresAt` — ISO-8601 timestamp when the link expires. Present with `joinUrl`.

### Errors

| Status             | Cause                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Missing or malformed body — the response `errors` array names the Zod issue.                                                                                                                                  |
| `400 Bad Request`  | Email cannot receive mail (`code: email_undeliverable`); provide a different address. See [Email cannot receive mail](/errors/email-undeliverable).                                                           |
| `401 Unauthorized` | Missing `Authorization`, unknown key, or key environment mismatched with the deployment.                                                                                                                      |
| `404 Not Found`    | Should not occur on this route in practice — the caller is always its own parent.                                                                                                                             |
| `409 Conflict`     | Replaying `merchantId` with different `name`, `email`, `phone`, `websiteUrl`, or `allowedReturnHosts` — **or** your merchant already has a parent of its own (see [The one-level cap](#4-the-one-level-cap)). |

### Update the website URL

After create, set or change the sub-merchant's website URL with a scoped PATCH. Use the same Merchant API Key you use for other sub-merchant routes; `:merchantId` must be your own merchant id or a sub-merchant you created.

```http
PATCH /v1/public-api/merchants/{merchantId}
Authorization: Bearer pai_live_...
Content-Type: application/json

{
  "websiteUrl": "https://acmecoaching.com"
}
```

```json
{
  "websiteUrl": "https://acmecoaching.com"
}
```

Only `https://` URLs are accepted (max 255 characters). Clearing the URL is not supported on this route — use the seller dashboard if you need to remove it. On idempotent create replay, `websiteUrl` is applied only when the stored URL is still empty; a replay with a different non-empty URL returns `409 Conflict` like a name or email mismatch.

### Allowed checkout return hosts

Platforms like funnel builders send the buyer back to the page the checkout started on, and that page can sit on the seller's funnel domain or on any of their custom domains. A checkout `returnUrl` is accepted only when it uses `https://` and its hostname **exactly** matches one of:

- the hostname of `websiteUrl`,
- the PAI checkout host,
- a hostname in the merchant's `allowedReturnHosts` list.

Any other host is rejected with `400` and `code: checkout.return_url_forbidden` (message `Checkout return URL must match the merchant website host.`), so the checkout cannot be used as an open redirect.

Set the list at create, or replace it with the same PATCH route. Your own key manages the list for a sub-merchant you created; a merchant's own key manages its own list.

```http
PATCH /v1/public-api/merchants/{merchantId}
Authorization: Bearer pai_live_...
Content-Type: application/json

{
  "allowedReturnHosts": ["acme.myclickfunnels.com", "Go.AcmeCoaching.com"]
}
```

```json
{
  "allowedReturnHosts": ["acme.myclickfunnels.com", "go.acmecoaching.com"]
}
```

You can send `websiteUrl` and `allowedReturnHosts` in one request; the response echoes the fields you sent. Read the current list from `GET /v1/public-api/merchants/{merchantId}`.

Rules for each entry:

- A bare hostname such as `shop.example.com`: no scheme, path, port, query, or `user@` part.
- No wildcards. `*.myclickfunnels.com` is rejected, and a listed host does not cover its subdomains: list `www.shop.example.com` separately from `shop.example.com`.
- No IP addresses and no `localhost`.
- No trailing dot.
- Entries are lowercased, internationalised names are stored in punycode (`bücher.de` → `xn--bcher-kva.de`), and duplicates are removed.
- At most 20 entries.

Sending the list replaces the stored list; send `[]` to clear it. Each change is recorded in the merchant's audit log with the API key that made it and the list before and after. On idempotent create replay the list is applied only when the stored list is still empty; a replay with a different list returns `409 Conflict`.

An invalid entry returns `400` naming the entry and its position:

```json
{
  "message": "Validation failed",
  "errors": [
    {
      "code": "custom",
      "path": ["allowedReturnHosts", 1],
      "message": "allowedReturnHosts entry \"https://go.acmecoaching.com/thanks\" must be a bare hostname such as shop.example.com, with no scheme, path, port or wildcard."
    }
  ]
}
```

### PATCH errors

| Status             | Cause                                                                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Missing or malformed body — the response `errors` array names the Zod issue (for example non-HTTPS URL, or an invalid `allowedReturnHosts` entry).                   |
| `401 Unauthorized` | Missing `Authorization`, unknown key, or key environment mismatched with the deployment.                                                                             |
| `403 Forbidden`    | `:merchantId` is outside your key's allowed set (another parent merchant's sub-merchant, your parent, a sibling sub-merchant, or a missing / soft-deleted merchant). |

### List your sub-merchants

A sub-merchant can be attached to your merchant without passing through `POST /v1/public-api/merchants`, so its `merchantId` is one you never received. List every active sub-merchant of your merchant, newest first, and match them to your sellers by `name` and `merchantId`:

```http
GET /v1/public-api/merchants/{merchantId}/sub-merchants?page=1&limit=20
Authorization: Bearer pai_live_...
```

```json
{
  "data": [
    {
      "merchantId": "019a1b2c-3d4e-7f00-8a1b-2c3d4e5f6a7b",
      "parentMerchantId": "019a1b2c-3d4e-7f00-8a1b-2c3d4e5f6a7a",
      "name": "Acme Coaching",
      "createdAt": "2026-10-02T09:15:00.000Z"
    }
  ],
  "meta": { "totalRecords": 1, "totalPages": 1, "currentPage": 1, "limit": 20 }
}
```

`limit` is at most 100. Each item includes `parentMerchantId` (your merchant id for that sub-merchant). The list is scoped to the environment of your API key — sandbox keys list sandbox sub-merchants, live keys list live sub-merchants. Contact email is not returned on this route. A sub-merchant's own id returns an empty list, and an id outside your key's allowed set returns `403` `merchant.access_forbidden`.

## 3. Key lifecycle for your sub-merchants

Mint, list, and revoke API keys for any sub-merchant you created using the ordinary
merchant-scoped key routes — there is no separate hierarchy-shaped path. `:merchantId` below can
be **your own** merchant id or any active sub-merchant's id; both work identically.

```http
POST /v1/public-api/merchants/{merchantId}/api-keys
Authorization: Bearer pai_live_...
Content-Type: application/json

{
  "name": "Acme Coaching storefront key",
  "environment": "live"
}
```

```json
{
  "key": "pai_live_...",
  "maskedKey": "pai_live_••••ab12",
  "id": "01930000-0000-7000-8000-0000000000cd",
  "createdAt": "2026-09-15T12:00:00.000Z"
}
```

The plaintext `key` is returned **exactly once** — store it immediately; PAI only ever persists
its hash. `GET /v1/public-api/merchants/{merchantId}/api-keys` lists a sub-merchant's keys
(masked); `DELETE /v1/public-api/merchants/{merchantId}/api-keys/{id}` revokes one.

Revoking a key you minted **cascades**: every key that key itself minted over the Public API is
revoked in the same transaction. Revoking your own top-level key therefore revokes every key you
minted for every sub-merchant — a fast, complete way to contain a leaked credential. Keys minted
some other way (e.g. from the sub-merchant's own dashboard) are unaffected.

## 4. The one-level cap

Nesting is exactly one level deep: a merchant with a parent can never itself become a parent.
Calling `POST /v1/public-api/merchants` with a sub-merchant's own key returns `409 Conflict` —
onboard sub-merchants only with a top-level merchant's key.

## 5. Assign team members (including owners)

You can put someone on a sub-merchant's dashboard team in three ways:

1. **At create** — `POST /v1/public-api/merchants` with an `email` that already matches a Payments AI user sets `ownerAttached: true` and assigns them `owner` on that new merchant.
2. **Join link** — when `ownerAttached` is `false`, deliver the `joinUrl` from the create response so the seller can sign up (or in) and claim the merchant.
3. **After create** — `POST /v1/public-api/merchants/{merchantId}/members` copies an **active** member of **your** merchant team onto a sub-merchant you manage (any role: `owner`, `admin`, `editor`, or `viewer`).

There is no invite email and no accept step on the assign route — the user must already be on your team.

```http
POST /v1/public-api/merchants/{merchantId}/members
Authorization: Bearer pai_live_...
Content-Type: application/json

{
  "email": "operator@yourplatform.com",
  "role": "owner"
}
```

`{merchantId}` must be a sub-merchant your key can access (a sub-merchant parented to the merchant that owns the key). Use your **parent** merchant's API key — a sub-merchant's own key cannot call members on the parent. The path id must **not** be the same merchant that owns the API key: the email must already be active on that parent team, so using the parent id as `{merchantId}` always returns `409` with code `team.already_member`. The email must belong to someone who is already an **active** member of the merchant that owns the API key — not merely registered in Payments AI, and not only on another merchant's team. Unknown and out-of-org emails return the **same** `404` with code `user.not_found` (see [User not found](/errors/user-not-found)).

### Create-time `ownerAttached`

| `ownerAttached` | What it means                                                                     | What you should do                                                                                                                                              |
| --------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`          | That user is now `owner` of this merchant and can sign into the dashboard.        | Continue to KYC and catalog setup.                                                                                                                              |
| `false`         | No matching user yet. The response includes `joinUrl` — deliver it to the seller. | Do not treat create as finished until [claimed](#know-when-the-seller-claims-the-merchant), **or** add the person to **your** team and call `POST .../members`. |

### Owner-claim join URL

- **You deliver it.** PAI does not email the seller — the link goes out through whichever channel your platform uses to notify sellers (email, dashboard, SMS, etc.).
- **7-day TTL.** After that the link is dead; the seller sees a "join link expired" screen.
- **Remint** the link with `POST /v1/public-api/merchants/{merchantId}/join-link` (see below). Reminting invalidates the previous token.
- **One shot.** Once a seller has claimed the merchant, both `create` (idempotent replay) and the remint endpoint return `409 merchant.owner_already_attached`.

### Remint a lost or expired join link

Use the same Merchant API Key that can access the sub-merchant (`:merchantId` in the path):

```http
POST /v1/public-api/merchants/{merchantId}/join-link
Authorization: Bearer pai_live_...
```

Body: none. Response `201`:

```json
{
  "joinUrl": "https://app.payments.ai/join#token=<opaque>&merchantId=01930000-0000-7000-8000-0000000000ab",
  "joinUrlExpiresAt": "2026-09-25T15:04:05Z"
}
```

`409` once the merchant has an owner; `403` if the merchant does not exist or your key cannot access it — the two cases return the same `403` by design, so a key cannot probe for merchant ids outside its scope.

### Know when the seller claims the merchant

**Do not remint the link to check whether the seller claimed the merchant.** On an unclaimed merchant, remint issues a new link and invalidates the one you already delivered. Use one or both of these signals instead.

**Read it.** Call `GET /v1/public-api/merchants/{merchantId}` with the same key you used for create:

```http
GET /v1/public-api/merchants/{merchantId}
Authorization: Bearer pai_live_...
```

Response `200`:

```json
{
  "merchantId": "01930000-0000-7000-8000-0000000000ab",
  "ownerAttached": true,
  "activation": {
    "status": "pending",
    "identityVerification": "not_started"
  },
  "allowedReturnHosts": ["acme.myclickfunnels.com"]
}
```

- `ownerAttached` — `true` once the merchant has an active owner, however it got one: attached at create, claimed through `joinUrl`, or assigned with `POST .../members`.
- `activation.status` — go-live progress: `not_provisioned`, `pending`, `verification_pending`, or `active`.
- `activation.identityVerification` — the owner's identity verification (KYC) state: `not_started`, `pending`, `in_review`, `verified`, or `rejected`. See [Identity verification (KYC)](#6-identity-verification-kyc).
- `allowedReturnHosts` — extra hosts a checkout `returnUrl` may use. Empty when none are set. See [Allowed checkout return hosts](#allowed-checkout-return-hosts).

`403` if the merchant does not exist or your key cannot access it, the same as remint.

**Get told.** Subscribe an endpoint on your **parent** merchant to `merchant.owner_attached` and enable **Receive sub-merchant events** on it. We send the event when the seller claims the merchant through `joinUrl`. The body carries `eventId`, `eventType`, `merchantId` (the claimed sub-merchant), `ownerUserId`, and `email`. Create-time attach and `POST .../members` do not send it — their responses already tell you. Failed deliveries are retried for a limited time (see [Retries](/webhooks#retries)), so keep reading `ownerAttached` if your endpoint may miss one. See [Webhooks](/webhooks#merchants).

### Make attachment succeed at create

1. Have the future owner **sign up in Payments AI first** (or confirm they already have an account).
2. Call `POST /v1/public-api/merchants` with **that same email**.
3. Assert `ownerAttached === true` before you continue when you rely on create-time attach.

### What does not attach someone

- Signing up **after** create does **not** claim an existing merchant by email (unless the seller uses `joinUrl`).
- Assign member **cannot** add someone who was never on **your** merchant team — invite them to your platform merchant in the dashboard first, then assign them to the sub-merchant.
- Dashboard team invite on an **ownerless** sub-merchant still requires an existing Owner or Admin on that merchant — use assign member, `joinUrl`, or Support instead.

### Dashboard merchant context

After assign, the user can sign in, but the dashboard still opens the **first** merchant they belong to (there is no merchant switcher yet). If they belong to multiple merchants, they may need to use the sub-merchant's URL context or sign out and back in depending on your flow — plan for [multiple merchants per user](/public-api) limitations until switcher support ships.

## 6. Identity verification (KYC)

Sellers must complete identity verification before live payouts. **The verification flow itself is dashboard-only today.** You cannot start it over the Merchant Public API, and its routes are not in this API Reference. You can follow its progress: read `activation.identityVerification` from `GET /v1/public-api/merchants/{merchantId}`, or call `GET /v1/public-api/merchants/{merchantId}/kyc` for a dedicated KYC snapshot (`kycStatus`, `activationStatus`, `updatedAt`). Subscribe to `merchant.kyc.updated` on a parent webhook destination with **Receive sub-merchant events** to be told when status changes without polling. See [Webhooks](/webhooks#merchants).

After `ownerAttached` is `true`, the owner:

1. Signs into the [Payments AI dashboard](https://mor.payments.ai).
2. Opens **onboarding / identity verification** (`/onboarding/kyc`) for that merchant.
3. Completes identity verification. Status questions after submit go to [Support](/getting-help).

KYC also collects phone if you omitted it on create.

### Not available yet (do not call these)

Platforms cannot yet mint a verification link to send to the seller. Do **not** call
`POST /v1/public-api/merchants/{merchantId}/kyc` — that route does not exist (404). Dashboard KYC
is `GET /v1/merchants/{merchantId}/kyc` and `POST /v1/merchants/{merchantId}/kyc/session` and
requires the owner's Cognito session, not a Merchant API Key.

## 7. Next steps

Once the owner is attached and KYC can run in the dashboard:

1. Have the owner mint a **merchant-scoped** API key (**Developer Tools → API Keys**) for catalog and checkout.
2. Use that key with the same `merchantId` on `/v1/public-api/merchants/{merchantId}/products` and the rest of the [Merchant Public API](/public-api).
3. Your own key also reaches those routes for any sub-merchant you created — see [Full data-plane authority](#full-data-plane-authority).

## FAQ

**Does PAI email the seller the join link?** No. Deliver `joinUrl` through your own channel — email, dashboard, SMS, wherever you already talk to the seller. This keeps the notification voice yours and avoids double-messaging.

**What if the seller loses the link?** Call `POST /v1/public-api/merchants/{merchantId}/join-link` to remint. The previous token stops working; the new one is valid for another 7 days.

**How do I know the seller claimed the merchant?** Read `ownerAttached` from `GET /v1/public-api/merchants/{merchantId}`, or subscribe to `merchant.owner_attached`. Do not remint the link to find out — that invalidates the link you delivered. See [Know when the seller claims the merchant](#know-when-the-seller-claims-the-merchant).

**Do I need to record consent flags?** No. Consent for ToS and privacy policy is set to `true`
on your behalf when you call this endpoint — you have accepted PAI's terms on the sub-merchant's
behalf. The audit log captures the implied source so it is auditable.

**Can I assign an owner later via API?** Yes, with limits. Deliver the `joinUrl` from create or remint it with `POST /v1/public-api/merchants/{merchantId}/join-link`, **or** use `POST /v1/public-api/merchants/{merchantId}/members` to copy someone who is already an **active** member of **your** merchant team onto a sub-merchant (role can be `owner`). You cannot attach a brand-new seller who was never on your team without `joinUrl` — invite them to your merchant first, then assign, or use the join link. See [Assign team members](#5-assign-team-members-including-owners).

**Can I start or poll KYC with my API key?** You can poll it: read `activation.identityVerification` from `GET /v1/public-api/merchants/{merchantId}`, or use `GET /v1/public-api/merchants/{merchantId}/kyc`. Subscribe to `merchant.kyc.updated` to be notified when status changes. You cannot start verification — the owner completes it in the dashboard. See [Identity verification (KYC)](#6-identity-verification-kyc).

**Can I read or update a sub-merchant's data with my own key?** Yes — see
[Full data-plane authority](#full-data-plane-authority). Your key has the same access as the
sub-merchant's own key across every Public API resource, not just onboarding.

**How do I get a key that can onboard sub-merchants?** Any merchant without a parent of its own
already can — there is no separate eligibility flag or approval step. Use your existing Merchant
API Key, or mint a fresh one from your dashboard.
