Skip to main content

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.

1. Create a merchant​

Dashboard​

  1. Sign in to the Payments AI dashboard.
  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 for setup.

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​

Sign in to the dashboard and create a sandbox key in Developer Tools.

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:

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

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}):

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:

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.

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

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:

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.

5. Try It on API Reference​

Open the API Reference, 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 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​