# Sandbox → Live for platforms

> Run sandbox and live as two separate environments with two keys, and onboard live sub-merchants the same way you do in sandbox.

<CopyAiContextButton
  pageTitle="Sandbox → Live for platforms"
  pagePath="/platform-sandbox-to-live"
/>

Payments AI sandbox and live work like Stripe test mode and live mode: **two fully separate
environments**, **two Merchant API keys**, and **no automatic link** between a sandbox
sub-merchant and a live one. Your product stores the sandbox id and the live id for each seller.

See [Platform onboarding](/platform-onboarding) for create, join links, team assign, and scoped API
routes in each environment.

## Two environments, two keys

|                      | Sandbox                                           | Live                                           |
| -------------------- | ------------------------------------------------- | ---------------------------------------------- |
| API key prefix       | `pai_test_*`                                      | `pai_live_*`                                   |
| API base             | `https://sandbox.mor.payments.ai/api`             | `https://mor.payments.ai/api`                  |
| Your parent merchant | The top-level merchant that owns your sandbox key | The top-level merchant that owns your live key |

A `pai_test_*` key is rejected on the live API and a `pai_live_*` key is rejected on sandbox.
There is no Payments AI field or API that maps a sandbox sub-merchant id to a live sub-merchant id.

Dashboard **go-live** (turning a sandbox merchant into a live merchant inside the product) is for
merchants who onboard themselves. **Do not send platform-managed sub-merchants through dashboard
go-live** — create their live sub-merchant with your live key instead (below).

**Pending:** a planned change will block dashboard go-live for a seller who joined your sandbox
sub-merchant, with a `409` that tells them going live is managed by their parent merchant. That behavior
and its error code are not live yet, so do not build on a specific code today. See
[Platform onboarding](/platform-onboarding#errors) for the errors that are live now.

## Going live: step by step

Repeat the same onboarding flow you use in sandbox, on **live**, with your **`pai_live_*`** key.

### 1. Create the live sub-merchant

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

{
  "name": "Acme Coaching",
  "email": "founder@acmecoaching.com",
  "merchantId": "01940000-0000-7000-8000-0000000000cd"
}
```

Use the same request shape as sandbox (optional `phone`, `websiteUrl`, `allowedReturnHosts`, and
so on). The parent is always the merchant bound to your **live** key — not your sandbox parent.
Details and errors: [Create a sub-merchant](/platform-onboarding#2-create-a-sub-merchant).

You may supply a **new** `merchantId` for live (recommended) or omit it and use the id in the
response. That id is unrelated to the seller’s sandbox `merchantId`.

### 2. Store both ids on your side

Keep your own mapping, for example `platformSellerId → { sandbox: <merchantId from sandbox
create>, live: <merchantId from live create> }`. Payments AI does not expose a cross-environment
mapping for platforms.

### 3. Deliver the live join link

When `ownerAttached` is `false`, the `201` response includes `joinUrl` and `joinUrlExpiresAt` for
the **live** sub-merchant. Deliver that link through your own channel (same rules as sandbox).
The sandbox `joinUrl` from create does not claim the live merchant.

### 4. Configure live catalog, return hosts, and webhooks

Nothing from sandbox is copied to live. Use the `merchantId` returned by your live create call in
every live scoped route. On that **live** sub-merchant (and your **live** parent as needed):

- Create products and plans (`/v1/public-api/merchants/{merchantId}/products`, …).
- Set `websiteUrl` and `allowedReturnHosts` with `PATCH /v1/public-api/merchants/{merchantId}` if checkout `returnUrl` hosts differ from sandbox.
- Add webhook destinations on your **live** parent in the dashboard; enable **Receive sub-merchant events** on each endpoint that should receive sub-merchant activity. See [Webhooks](/webhooks).

Sandbox catalog, return hosts, and webhook settings stay in sandbox only.

### 5. KYC and payouts on live

Identity verification and live payouts apply only to the **live** sub-merchant you created. Sandbox
KYC or activation state does not carry over.

The seller signs into the [live dashboard](https://mor.payments.ai) and completes
`/onboarding/kyc` for that live merchant. You cannot start KYC with a Merchant API Key.

### Pre-KYC processing volume (live)

This applies to live merchants whose identity is not yet verified (`activation.identityVerification`
is not `verified`). Payments AI tracks their processing volume in **USD** over a **rolling 30-day**
window; up to **5,000 USD** is within the pre-KYC band. When volume reaches **4,000 USD (80%)**,
Payments AI emails the merchant owner. Your platform has no API field or webhook event for this limit.

## Check access with your live key

```http
GET /v1/public-api/me
Authorization: Bearer pai_live_...
```

For a Merchant API Key, the response includes `allowedMerchantIds` — your parent id and every
active sub-merchant your key can access on **this** deployment. The `merchantId` from your live
create call must appear there before you call `/v1/public-api/merchants/{merchantId}/...` on live.

If you get `403` with `merchant.access_forbidden` on a scoped route, `:merchantId` is wrong for
this key or not a sub-merchant you created on live. See [Platform onboarding](/platform-onboarding).

## KYC status on the live sub-merchant

Poll with your **live** key and the `merchantId` returned by your live create call:

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

Read `activation`:

- `activation.status` — `not_provisioned`, `pending`, `verification_pending`, or `active`
- `activation.identityVerification` — `not_started`, `pending`, `in_review`, `verified`, or
  `rejected`

Also use `ownerAttached` to see whether the seller claimed the live merchant. See [Know when the
seller claims the merchant](/platform-onboarding#know-when-the-seller-claims-the-merchant).

## Canonical hosts (production)

From production deployment config and CLI defaults. Non-prod URLs use `*.dev.managed.payments.ai` —
see [CLI](/cli).

| Surface                                | Sandbox                                                            | Live                                                |
| -------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
| API base                               | `https://sandbox.mor.payments.ai/api`                              | `https://mor.payments.ai/api`                       |
| Dashboard                              | `https://sandbox.mor.payments.ai`                                  | `https://mor.payments.ai`                           |
| Hosted checkout                        | `https://mor.payments.ai`                                          | `https://mor.payments.ai`                           |
| JS embed (`checkout.js`)               | `https://js.mor.payments.ai/v1/checkout.js`                        | `https://js.mor.payments.ai/v1/checkout.js`         |
| Owner join link (from create / remint) | `https://mor.payments.ai/join?isSandbox=true#token=…&merchantId=…` | `https://mor.payments.ai/join#token=…&merchantId=…` |

The embed script URL is the same host for both environments; set `environment: 'sandbox'` or
`'live'` in embed config.
