# Quickstart

> Make your first sandbox API call in under 15 minutes.

<CopyAiContextButton pageTitle="Quickstart" pagePath="/quickstart" />

This walkthrough takes you from a new merchant to a sandbox checkout page:

1. Create a merchant
2. Get a sandbox Merchant API Key
3. Create a product and plan
4. Open the checkout page

A Merchant API Key is scoped to its own merchant and to the sub-merchants that merchant onboards. **Platforms:** use your own Merchant API Key to `POST /v1/public-api/merchants` — see the [Platform onboarding guide](/platform-onboarding).

## 1. Create a merchant

### Dashboard

1. Sign in to the [Payments AI dashboard](https://mor.payments.ai).
2. Complete **business setup** (business name, contact email, phone with country code, like `+14155552671`).
3. Copy your `merchantId` from the dashboard (you will use it in every Public API path).

### MCP (programmatic)

If you are using Cursor, Claude, or another MCP client, call `create_merchant_account` with `name` and `email`, plus an optional E.164 `phone`. See [MCP server](/mcp) for setup.

```text
Create a sandbox merchant named "Quickstart Demo" with my email <your email>.
```

Use your own real, deliverable email address — `create_merchant_account` rejects example, disposable, and other reserved or undeliverable addresses. Phone is optional. If you add one, use your own mobile number, starting with `+` and your country code, with no spaces or dashes (for example, `+14155552671` is a US number, but not yours): after go-live the identity-verification link is sent to it by SMS. Without a phone, the link goes by email.

The tool returns `{ "merchantId": "<uuid>", "existing": false }` for a new merchant. `existing: true` means this account already owns a merchant and the tool returned that one instead of creating a second. Either way, use that `merchantId` in the rest of this guide.

## 2. Get a sandbox Merchant API Key

<SandboxKeyCallout>
  Sign in to the dashboard (https://mor.payments.ai) and create a sandbox key in Developer Tools
  (https://mor.payments.ai/developer-tools).
</SandboxKeyCallout>

Create a **sandbox** key (`pai_test_*`) under **API Keys**. Never paste live `pai_live_*` keys into docs Try It.

Send the key as a Bearer token on every Public API request:

```bash
Authorization: Bearer pai_test_<your_sandbox_key>
```

## 3. Create a product and plan

`POST /v1/public-api/merchants/{merchantId}/products` creates the product and nested plans in one call. The response is `{ "id": "<productId>" }`.

```bash
curl 'https://sandbox.mor.payments.ai/api/v1/public-api/merchants/{merchantId}/products' \
  -X POST \
  -H "Authorization: Bearer pai_test_<your_sandbox_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Starter Plan",
    "status": "draft",
    "plans": [
      {
        "name": "Monthly",
        "amount": 19.99,
        "currency": "usd",
        "type": "recurring",
        "billingPeriod": "month",
        "periodLength": 1
      }
    ]
  }'
```

Fetch plan ids from the product (copy `plans[0].id` as `{planId}`):

```bash
curl 'https://sandbox.mor.payments.ai/api/v1/public-api/merchants/{merchantId}/products/{productId}' \
  -H "Authorization: Bearer pai_test_<your_sandbox_key>"
```

To add another plan later:

```bash
curl 'https://sandbox.mor.payments.ai/api/v1/public-api/merchants/{merchantId}/products/{productId}/plans' \
  -X POST \
  -H "Authorization: Bearer pai_test_<your_sandbox_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Annual",
    "amount": 199.00,
    "currency": "usd",
    "type": "recurring",
    "billingPeriod": "year",
    "periodLength": 1
  }'
```

`draft` is enough for sandbox checkout testing. Set `"status": "active"` when the product should appear in the live catalog.

## 4. Open the checkout page

Resolve hosted checkout for the plan. The JSON includes `checkoutUrl` — open that URL in a browser.

```bash
curl 'https://sandbox.mor.payments.ai/api/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}' \
  -H "Authorization: Bearer pai_test_<your_sandbox_key>"
```

Sandbox checkout URLs include `?isSandbox=true` so the checkout SPA pins the sandbox API.

### Test card (Sandbox)

Pay a sandbox checkout with test card `4242 4242 4242 4242`, any future expiry, and any CVC. To test a
refused payment, use `4000 0000 0000 0002`. Test cards never work on Live: live checkout links take
real cards only.

### Embed session (optional)

If you are embedding checkout instead of opening the hosted page, the script mounts payment
fields only — product name and price are not rendered. See [Embedded checkout](/embedded-checkout)
to fetch plan metadata and display the offer on your page.

The hosted iframe path still creates a session; use `purchaseUrl` (when present) or `sessionId`:

```bash
curl 'https://sandbox.mor.payments.ai/api/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/session' \
  -X POST \
  -H "Authorization: Bearer pai_test_<your_sandbox_key>" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl":"https://example.com/thanks"}'
```

After the buyer pays on `purchaseUrl`, they are redirected to the `returnUrl` you sent, with
`status` and `receipt_id` added to its query string. Pass `receipt_id` as the `receiptId` of
`GET /checkout/plans/{planId}/receipts/{receiptId}` to read the receipt totals.

For composable payment fields (not the iframe embed), confirm the buyer's
`confirmationToken` on your server or via the public buyer route:

```bash
curl 'https://sandbox.mor.payments.ai/api/v1/checkout/plans/{planId}/confirm' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "confirmationToken": "ctok_…",
    "returnUrl": "https://example.com/thanks"
  }'
```

The same operation is available on the Merchant Public API at
`POST /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/confirm` when using API-key
auth. See [Embedded checkout](/embedded-checkout).

## 5. Try It on API Reference

Open the [API Reference](/api), paste your `pai_test_*` key and sandbox `merchantId` in the right-rail **Try It** panel, and send `GET /v1/public-api/merchants/{merchantId}/products`.

## 6. Building with an AI coding agent?

We don't publish client SDKs yet. Instead, install the [Payments AI skill](https://github.com/paymentsai/Payments-AI-skills) in Claude Code, Cursor, or another agent-based tool — it teaches the agent our API shapes and conventions directly, so it can write correct integration code against the raw HTTP API for you.

## Next steps

- [Merchant Public API](/public-api)
- [Platform onboarding](/platform-onboarding)
- [MCP server](/mcp)
- [Webhooks](/webhooks)
- [Error catalog](/errors)
