# MutoPay — Full Documentation

> Crypto payment gateway. Merchants accept any token, receive their preferred stablecoin. REST API, HMAC-signed webhooks, six-chain support (Ethereum, Base, BSC, Polygon, Arbitrum, TON).

Source site: https://mutopay.com
Interactive API reference: https://mutopay.com/api/docs
OpenAPI spec: https://mutopay.com/api/openapi.json

---
# Getting Started

Source: https://mutopay.com/docs/getting-started/

Accept your first crypto payment in five minutes. Create a payment link, redirect your customer, and receive settlement in your preferred stablecoin.

MutoPay is a crypto payment gateway. Your customer pays in any supported token on any supported chain; you receive your preferred stablecoin in your wallet. This guide takes you from zero to a working payment link in five minutes.

## What you need

1. A MutoPay account — sign up at [mutopay.com/dashboard/register](https://mutopay.com/dashboard/register).
2. A settlement wallet address and preferred stablecoin/chain (set in [Settings](https://mutopay.com/dashboard/settings)).
3. A **channel API key** (prefix `ep_`). Every integration has its own channel — create one at [Settings → Channels](https://mutopay.com/dashboard/settings).

## Create a payment

```bash
curl -X POST https://mutopay.com/api/payments \
  -H "X-API-Key: ep_your_channel_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 25.00,
    "description": "Order #1042",
    "external_id": "order_1042",
    "callback_url": "https://yourstore.com/thanks"
  }'
```

Response:

```json
{
  "id": "pay_abc123",
  "status": "pending",
  "url": "https://mutopay.com/pay/pay_abc123",
  "expires_at": "2026-04-21T14:30:00Z"
}
```

Redirect your customer to the `url`. They pick a token, connect their wallet (or scan a QR code for manual transfers), and the hosted page handles the rest.

## Receive the result

Two options — use both in production:

1. **Webhook** (recommended). Configure your endpoint in the dashboard. MutoPay POSTs to it with an HMAC-SHA256 signature when the payment completes, fails, or expires. See [Verify a webhook signature](/docs/verify-webhook-signature/).
2. **Polling**. `GET https://mutopay.com/api/payments/{id}/status` returns the current `status`. Useful as a fallback or for the browser "thanks" page.

## What happens on-chain

- Customer pays in USDC on BSC → MutoPay executes a cross-chain swap → you receive USDC on Polygon (for example). Fees are deducted before settlement.
- Direct transfers (customer pays the same token/chain you want to receive) skip the swap.

## Next steps

- [Authentication](/docs/authentication/) — channel keys vs master key vs JWT.
- [Create a Payment](/docs/create-payment/) — full request/response reference with every parameter.
- [Webhooks](/docs/webhooks/) — events, payload shape, retry schedule.
- [Interactive API reference](https://mutopay.com/api/docs) — try every endpoint in your browser.

---
# Authentication

Source: https://mutopay.com/docs/authentication/

MutoPay has three authentication methods — channel API keys for creating payments, master API keys for account management, and JWTs for the browser dashboard. This page explains when to use which.

MutoPay has three authentication methods. Most integrations only need the first two.

| Credential | Prefix | Header | Use for |
|---|---|---|---|
| Channel API key | `ep_` | `X-API-Key: ep_...` | Creating payments from a specific integration (WooCommerce, mobile app, SaaS billing) |
| Master API key | `msk_` | `Authorization: Bearer msk_...` | Headless account management — list payments, manage channels, change settlement settings |
| Browser JWT | — | `Authorization: Bearer <jwt>` | The dashboard at `mutopay.com/dashboard`. Issued by Google Sign-In. You will not usually handle these directly. |

## Channel API keys

**One channel per integration.** Each channel has its own API key, webhook URL, and webhook secret. Revoke or rotate one integration without affecting the others.

Create a channel at [Settings → Channels](https://mutopay.com/dashboard/settings). The full key is shown **once**; store it in your secret manager.

Use the channel key on `POST /api/payments`:

```http
POST /api/payments HTTP/1.1
Host: mutopay.com
X-API-Key: ep_live_4b8f...
Content-Type: application/json

{"amount_usd": 25.00, "description": "Order #1042"}
```

A channel key **cannot**:
- List or read other channels' payments
- Rotate itself
- Change account settings

If you need those, use a master key.

## Master API keys

**One per merchant account.** Grants full access to `/api/merchant/*` endpoints — list all payments, manage channels, update settlement wallet/token, etc.

Generate at [Settings → Master API Key](https://mutopay.com/dashboard/settings). Shown once. Store in your secret manager. Rotate or revoke anytime.

```http
GET /api/merchant/payments HTTP/1.1
Host: mutopay.com
Authorization: Bearer msk_live_9c2e...
```

A master key **cannot rotate or revoke itself** — that requires a browser JWT session. This is intentional: if your master key leaks, you (the human) can always revoke it from the dashboard, but an attacker holding the leaked key cannot lock you out by rotating it.

## Which key should I use?

- **Building a plugin or SDK?** → channel key. One key per install.
- **Writing a server-side automation that needs to see all your payments?** → master key.
- **Creating payments from multiple distinct integrations?** → one channel per integration.

If unsure, start with a channel key. Upgrade to master only when you need account-wide access.

## Suspended accounts

If your merchant account is suspended, both channel and master keys return **HTTP 403** with `{"error": "merchant suspended"}`. Contact support to resolve.

## See also

- [Master keys vs channel keys](/docs/master-keys-vs-channel-keys/) — deeper comparison and rotation guidance.
- [Getting Started](/docs/getting-started/)

---
# Create a Payment

Source: https://mutopay.com/docs/create-payment/

Full reference for POST /api/payments — every field, every response, and copy-paste examples in cURL, Node.js, and Python.

`POST https://mutopay.com/api/payments` creates a payment link. Authenticate with a channel API key in the `X-API-Key` header.

## Request

```http
POST /api/payments HTTP/1.1
Host: mutopay.com
X-API-Key: ep_live_4b8f...
Content-Type: application/json
```

### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `amount_usd` | number | yes* | Amount in USD. Required unless `amount_original` + `currency` are supplied. |
| `amount_original` | number | no | Amount in the original currency. Used with `currency`. |
| `currency` | string | no | ISO-4217 code (`EUR`, `GBP`, `JPY`, ...). Defaults to `USD`. |
| `description` | string | no | Human-readable description shown to the customer on the payment page. |
| `external_id` | string | no | Your order/invoice ID. Returned on webhooks for reconciliation. |
| `callback_url` | string | no | Where to send the customer after payment completes. |
| `customer_email` | string | no | For receipt emails and dispute resolution. |
| `expires_at` | ISO-8601 string | no | Override the default 30-minute expiry. Max 7 days. |
| `metadata` | object | no | Arbitrary JSON metadata, echoed back on webhooks. ≤ 4 KB. |

## Response — 201 Created

```json
{
  "id": "pay_abc123",
  "status": "pending",
  "url": "https://mutopay.com/pay/pay_abc123",
  "amount_usd": 25.00,
  "currency": "USD",
  "description": "Order #1042",
  "external_id": "order_1042",
  "expires_at": "2026-04-21T14:30:00Z",
  "created_at": "2026-04-21T14:00:00Z"
}
```

Redirect your customer to `url`.

## Examples

### cURL

```bash
curl -X POST https://mutopay.com/api/payments \
  -H "X-API-Key: $MUTOPAY_CHANNEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 25.00,
    "description": "Order #1042",
    "external_id": "order_1042",
    "callback_url": "https://yourstore.com/thanks",
    "metadata": {"user_id": "u_88124", "tier": "pro"}
  }'
```

### Node.js (fetch)

```js
const res = await fetch('https://mutopay.com/api/payments', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.MUTOPAY_CHANNEL_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount_usd: 25.00,
    description: 'Order #1042',
    external_id: 'order_1042',
    callback_url: 'https://yourstore.com/thanks',
  }),
});

if (!res.ok) throw new Error(`MutoPay error: ${res.status}`);
const payment = await res.json();
// Redirect the customer:
//   res.redirect(payment.url);
```

### Python (requests)

```python
import os
import requests

res = requests.post(
    "https://mutopay.com/api/payments",
    headers={
        "X-API-Key": os.environ["MUTOPAY_CHANNEL_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "amount_usd": 25.00,
        "description": "Order #1042",
        "external_id": "order_1042",
        "callback_url": "https://yourstore.com/thanks",
    },
    timeout=10,
)
res.raise_for_status()
payment = res.json()
# Redirect the customer to payment["url"]
```

## Non-USD pricing

Pass `amount_original` + `currency` for merchants pricing in EUR/GBP/etc. The FX rate is captured at creation time and returned in webhook payloads as `fx_rate`.

```json
{
  "amount_original": 25.00,
  "currency": "EUR",
  "description": "Abonnement Pro"
}
```

MutoPay quotes the customer in USD equivalent, then settles in your preferred stablecoin.

## Errors

| Status | Body | Meaning |
|---|---|---|
| 400 | `{"error": "invalid_request", "message": "..."}` | Validation error — see `message`. |
| 401 | `{"error": "unauthorized"}` | Missing or invalid API key. |
| 403 | `{"error": "merchant suspended"}` | Your account is suspended. Contact support. |
| 429 | `{"error": "rate_limited"}` | Too many requests. Retry with exponential backoff. |

## See also

- [Webhooks](/docs/webhooks/) — what you get back after the customer pays.
- [Payment statuses](/docs/payment-statuses/) — state machine reference.

---
# Webhooks

Source: https://mutopay.com/docs/webhooks/

MutoPay sends an HMAC-SHA256 signed webhook when a payment completes, fails, expires, or needs attention. This page documents every event, the payload shape, and the delivery/retry guarantees.

MutoPay sends a webhook to your configured URL whenever a payment changes to a terminal state or requires your attention. Payloads are signed with HMAC-SHA256 — always verify the signature before trusting the data. See [Verify a webhook signature](/docs/verify-webhook-signature/).

## Configure

Set the webhook URL and retrieve the webhook secret per-channel at [Settings → Channels](https://mutopay.com/dashboard/settings). Each channel has its own URL and secret.

## Events

| Event | When it fires |
|---|---|
| `payment.completed` | Payment succeeded, funds settled in your wallet |
| `payment.failed` | Payment attempt failed (on-chain revert, provider rejection, etc.) |
| `payment.expired` | Payment was not completed before `expires_at` |
| `payment.underpaid` | Customer sent less than the required amount |
| `payment.kyc_required` | The swap provider requested customer KYC — payment is paused, not terminal |
| `payment.needs_manual_check` | Unknown provider status — MutoPay support will investigate |

`kyc_required` and `needs_manual_check` are non-terminal. When they resolve (e.g. KYC cleared → `processing` → `completed`), **no additional webhook fires for the recovery** — the eventual `payment.completed` or `payment.failed` is your signal.

## Payload

```json
{
  "event": "payment.completed",
  "payment_id": "pay_abc123",
  "status": "completed",
  "amount_usd": 54.23,
  "amount_original": 50,
  "fx_rate": 1.0846,
  "currency": "EUR",
  "src_token": "USDC",
  "src_chain_id": "56",
  "src_amount": null,
  "dest_token": "USDC",
  "dest_chain_id": "137",
  "dest_amount": "54230000",
  "dest_decimals": 6,
  "external_id": "order_1042",
  "tx_hash": "0xabc...",
  "failure_reason": null,
  "completed_at": "2026-04-21T12:00:00Z",
  "timestamp": "2026-04-21T12:00:01Z"
}
```

### Field notes

- **`dest_amount`** is raw token base units. Divide by `10^dest_decimals` for human-readable: `54230000 / 10^6 = 54.23 USDC`.
- **`external_id`** is the value you sent when creating the payment — use it for reconciliation.
- **`tx_hash`** is the on-chain destination transaction (where the stablecoin arrived in your wallet).
- **`failure_reason`** is populated for `payment.failed` and sometimes `payment.expired`.
- **`timestamp`** is when MutoPay fired the webhook. **`completed_at`** is when settlement actually happened.

## Delivery guarantees

- Delivery is **at-least-once**. You may receive the same webhook more than once — idempotency is your responsibility (use `payment_id` + `event` as the dedupe key).
- Your endpoint must respond with a **2xx status** within 30 seconds to be considered delivered.
- Non-2xx responses, timeouts, and network errors are retried up to **5 times** with exponential backoff:

  | Attempt | Delay after previous failure |
  |---|---|
  | 2 | 1 minute |
  | 3 | 5 minutes |
  | 4 | 30 minutes |
  | 5 | 2 hours |
  | (final) | 12 hours |

  After the final attempt fails, delivery is abandoned. Use the merchant dashboard or `GET /api/merchant/payments/:id` to reconcile.

## Request headers

```http
POST /your/webhook HTTP/1.1
Content-Type: application/json
X-MutoPay-Signature: sha256=<hex-digest>
User-Agent: MutoPay-Webhook/1.0
```

## Security

- **Always verify the signature** before processing the payload. See [Verify a webhook signature](/docs/verify-webhook-signature/).
- **Never log the webhook secret.** Rotate it via the channel settings if you suspect compromise.
- Your endpoint should be **HTTPS**.

## Test your endpoint

From [Settings → Channels](https://mutopay.com/dashboard/settings) click **Send test webhook**. MutoPay will POST a signed sample payload to your configured URL — same shape, same headers, same signing algorithm as production.

## See also

- [Verify a webhook signature](/docs/verify-webhook-signature/) — Node, Python, PHP examples.
- [Payment statuses](/docs/payment-statuses/) — status transition reference.

---
# Verify a Webhook Signature

Source: https://mutopay.com/docs/verify-webhook-signature/

MutoPay signs every webhook with HMAC-SHA256. This page shows how to verify the X-MutoPay-Signature header in Node.js, Python, and PHP — copy-paste, no dependencies.

Every MutoPay webhook includes an `X-MutoPay-Signature` header containing an HMAC-SHA256 digest of the raw request body. Verify it before trusting the payload.

## The algorithm

```
signature = HMAC-SHA256(webhook_secret, raw_request_body)
expected  = "sha256=" + hex(signature)

valid     = constant_time_equal(expected, header_value)
```

Three things that matter:

1. Use the **raw** request body bytes. Do **not** parse JSON first and re-serialize — whitespace and key order will change and the signature will fail.
2. Use the webhook secret **for this specific channel** (each channel has its own secret). Find it at [Settings → Channels](https://mutopay.com/dashboard/settings).
3. Use a **constant-time comparison** (`crypto.timingSafeEqual` / `hmac.compare_digest` / `hash_equals`) — not `===` or `strcmp`. Regular comparison leaks timing information and enables signature forgery.

## Node.js (Express)

```js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const WEBHOOK_SECRET = process.env.MUTOPAY_WEBHOOK_SECRET;

// IMPORTANT: use express.raw, not express.json — we need the raw bytes.
app.post(
  '/webhooks/mutopay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const header = req.header('X-MutoPay-Signature') ?? '';
    const expected =
      'sha256=' +
      crypto.createHmac('sha256', WEBHOOK_SECRET).update(req.body).digest('hex');

    const ok =
      header.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));

    if (!ok) return res.status(401).send('invalid signature');

    const event = JSON.parse(req.body.toString('utf8'));
    // handle event.event / event.payment_id / event.status ...
    res.status(200).send('ok');
  }
);
```

## Node.js (Cloudflare Workers / Hono)

```ts
async function verify(secret: string, body: string, header: string | null) {
  if (!header) return false;
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );
  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(body));
  const expected =
    'sha256=' +
    Array.from(new Uint8Array(sig))
      .map((b) => b.toString(16).padStart(2, '0'))
      .join('');
  // Constant-time compare
  if (expected.length !== header.length) return false;
  let diff = 0;
  for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ header.charCodeAt(i);
  return diff === 0;
}

app.post('/webhooks/mutopay', async (c) => {
  const body = await c.req.text();
  const ok = await verify(
    c.env.MUTOPAY_WEBHOOK_SECRET,
    body,
    c.req.header('X-MutoPay-Signature') ?? null
  );
  if (!ok) return c.text('invalid signature', 401);
  const event = JSON.parse(body);
  // handle event ...
  return c.text('ok', 200);
});
```

## Python (Flask)

```python
import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["MUTOPAY_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/mutopay")
def mutopay_webhook():
    body = request.get_data()  # raw bytes
    header = request.headers.get("X-MutoPay-Signature", "")
    expected = "sha256=" + hmac.new(WEBHOOK_SECRET, body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, header):
        abort(401)

    event = request.get_json()
    # handle event["event"] / event["payment_id"] / event["status"] ...
    return "", 200
```

## PHP

```php
<?php
$secret = getenv('MUTOPAY_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_MUTOPAY_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit('invalid signature');
}

$event = json_decode($body, true);
// handle $event['event'] / $event['payment_id'] / $event['status'] ...
http_response_code(200);
echo 'ok';
```

## Testing

From [Settings → Channels](https://mutopay.com/dashboard/settings) click **Send test webhook**. The signature is generated the same way as a real event — if your verification code accepts the test payload, it will accept production webhooks.

## See also

- [Webhooks](/docs/webhooks/) — events, payloads, retry schedule.

---
# Master Keys vs Channel Keys

Source: https://mutopay.com/docs/master-keys-vs-channel-keys/

MutoPay has two kinds of API keys — channel keys for creating payments, master keys for account-wide management. Use the weaker one per integration; reserve the master key for automation that genuinely needs account-wide access.

Use **channel keys** for every integration that only needs to create payments. Reserve the **master key** for automation that must see or manage the whole account. This is a least-privilege default — each channel key's blast radius is limited to its own integration.

## Comparison

| | Channel key | Master key |
|---|---|---|
| Prefix | `ep_` | `msk_` |
| Header | `X-API-Key: ep_...` | `Authorization: Bearer msk_...` |
| Count per account | Many (one per integration) | One |
| Create payments | ✅ | ✅ |
| List all payments | Only its own | ✅ all |
| Manage channels | ❌ | ✅ |
| Change settlement token / wallet | ❌ | ✅ |
| Rotate or revoke itself | ❌ | ❌ (dashboard JWT required) |
| Suspended merchant | 403 | 403 |

## When to use which

- **WooCommerce, Shopify, mobile apps, SaaS billing hooks** → channel key. One per plugin install or app build. Scope of damage if leaked: limited to that one integration.
- **Back-office reconciliation script, BI sync, CRM integration** → master key. Needs to list all payments across every channel.
- **Ops runbook: rotate settlement wallet for the whole account** → master key. (Or use the dashboard.)
- **Customer-facing code that makes API calls from the browser** → never use either. Keep all API keys server-side.

## Rotation

### Channel key rotation

- From [Settings → Channels](https://mutopay.com/dashboard/settings), click **Rotate API key** on the channel.
- The new key is shown **once**. Update your integration.
- The old key is invalid immediately — plan a brief deploy window.

### Master key rotation

- From [Settings → Master API Key](https://mutopay.com/dashboard/settings), click **Rotate**. Browser JWT (your Google Sign-In session) is required. A master key **cannot rotate itself** — deliberate, so a leaked master key cannot lock the legitimate owner out.
- The new key is shown once.

## What to do if a key leaks

1. **Channel key** → rotate it immediately from the channel settings. This invalidates the leaked key. Review payments created during the window to spot unauthorized use.
2. **Master key** → log into the dashboard (Google Sign-In) and rotate. Then review all recent activity: `GET https://mutopay.com/api/merchant/payments` with the new key.

## See also

- [Authentication](/docs/authentication/) — full auth reference.
- [Create a Payment](/docs/create-payment/) — uses a channel key.

---
# Payment Statuses

Source: https://mutopay.com/docs/payment-statuses/

Every MutoPay payment has one of ten statuses. This page lists them, explains when each fires, and shows the legal state transitions you should expect to see.

Every MutoPay payment has a `status` field that transitions through a small state machine. Webhooks fire on terminal states and on states that need merchant attention. This page documents every value and the transitions between them.

## Statuses

| Status | Terminal | Fires webhook | Meaning |
|---|---|---|---|
| `pending` | no | no | Payment created, customer has not started yet. |
| `awaiting_payment` | no | no | Customer picked a token, waiting for the transaction / manual transfer. |
| `confirming` | no | no | Transaction submitted, waiting for on-chain confirmation. |
| `processing` | no | no | Cross-chain swap/bridge order is executing. |
| `kyc_required` | no | ✅ `payment.kyc_required` | Swap provider asked the customer to complete KYC. Payment is paused, not failed. |
| `needs_manual_check` | no | ✅ `payment.needs_manual_check` | Unknown provider status — MutoPay support will investigate. |
| `completed` | ✅ | ✅ `payment.completed` | Funds settled in your wallet. |
| `failed` | ✅ | ✅ `payment.failed` | Payment failed. See `failure_reason`. |
| `expired` | ✅ | ✅ `payment.expired` | Customer did not complete before `expires_at`. |
| `underpaid` | ✅ | ✅ `payment.underpaid` | Customer sent less than the required amount. |

## Transitions

```
pending ─▶ awaiting_payment ─▶ confirming ─▶ completed
                │                  │              │
                │                  ├─▶ processing ┤
                │                  │              │
                │                  │              ├─▶ failed
                │                  │              ├─▶ underpaid
                │                  │              └─▶ kyc_required ─▶ processing ─▶ completed
                │                  │                                              ╲─▶ failed
                │                  └─▶ needs_manual_check ─▶ (resolved off-band)
                └─▶ expired (anytime before terminal)
```

Key rules:

- A payment can only transition to `completed`, `failed`, `expired`, or `underpaid` **once**. Those are terminal.
- `kyc_required` and `needs_manual_check` are **recoverable** — they can transition back to `processing`, then continue to `completed` or `failed`.
- **Recovery transitions fire no webhook.** When `kyc_required` clears back to `processing`, your webhook endpoint will not hear about it. Your signal is the eventual `payment.completed` or `payment.failed`.

## Handling non-terminal alert statuses

For `kyc_required`:

- Inform the customer that the swap provider requested identity verification. You may want to keep the order "pending" in your own system rather than cancelling it — it can still complete.
- The customer's next action happens off-MutoPay (in the swap provider's flow).

For `needs_manual_check`:

- Support will contact you if action is needed. Don't auto-cancel the order — payment may still complete.
- Check `failure_reason` for a hint.

## Idempotency for webhook handlers

Since a payment can fire multiple webhooks across its lifetime (`kyc_required` → eventually `completed`, for example), your handler must be idempotent. The simplest pattern:

```
dedupe_key = payment_id + ":" + event
if already_processed(dedupe_key):
    return 200  // still ACK, so MutoPay stops retrying
record(dedupe_key)
handle(event)
```

## See also

- [Webhooks](/docs/webhooks/) — event list and payload.
- [Create a Payment](/docs/create-payment/) — where payments begin.

---
# Errors & Troubleshooting

Source: https://mutopay.com/docs/errors/

MutoPay uses standard HTTP status codes with structured JSON error bodies. This page lists every error, what it means, and how to fix it.

MutoPay returns standard HTTP status codes. Every error body is JSON with at least an `error` field (machine-readable) and usually a `message` field (human-readable).

```json
{
  "error": "invalid_request",
  "message": "amount_usd must be greater than 0"
}
```

## HTTP status codes

| Status | Body `error` | Meaning & fix |
|---|---|---|
| 400 | `invalid_request` | Validation error. Check `message` — a field is missing, malformed, or out of range. |
| 401 | `unauthorized` | Missing or invalid API key. Check the header name (`X-API-Key` for channel, `Authorization: Bearer` for master) and that the key hasn't been rotated. |
| 403 | `merchant suspended` | Your account is suspended. Contact support. |
| 403 | `forbidden` | You are trying to access a resource that doesn't belong to you (e.g. `GET /api/merchant/payments/pay_abc` where `pay_abc` belongs to another merchant). |
| 404 | `not_found` | The payment/channel/resource doesn't exist, or has been deleted. |
| 409 | `conflict` | State conflict — e.g. trying to create an admin when one already exists, or submitting an order for a payment that's already completed. |
| 422 | `unprocessable` | Business-logic rejection — e.g. the selected token/chain combination is unsupported, or the amount is below the minimum for the chosen route. |
| 429 | `rate_limited` | Too many requests. Back off and retry with exponential delay. |
| 500 | `internal_error` | Our fault. Retry idempotent reads; for writes, check whether the operation succeeded before retrying. |
| 502/503/504 | — | Transient infrastructure error. Retry with backoff. |

## Common gotchas

### "invalid signature" on webhook verification

- Are you using the **raw** request body bytes, not a re-serialized JSON? Re-serializing changes whitespace and key order.
- Are you using **the webhook secret for that channel**, not the merchant's master key or a different channel's secret?
- Is your comparison **constant-time**? See [Verify a webhook signature](/docs/verify-webhook-signature/).

### "payment expired" with a fresh payment

- `expires_at` defaults to 30 minutes from creation. Long-running checkout flows should pass an explicit `expires_at` when creating the payment.
- Set it in your call: `"expires_at": "2026-04-21T16:00:00Z"`. Max is 7 days.

### "unauthorized" but the key is correct

- Channel keys go in `X-API-Key`. Master keys go in `Authorization: Bearer`. Swapping these returns 401.
- Keys are shown **once** at creation. If you lost it, rotate and update your integration.

### "merchant suspended" (403)

- Someone at MutoPay has paused your account. Email support with your merchant ID (the `id` you see in the dashboard URL or returned on any `/api/merchant/*` response).

### Webhook never arrives

1. Is the webhook URL configured on the channel that created the payment? Each channel has its own URL.
2. Is your endpoint **reachable from the public internet** and served over HTTPS?
3. Check [Settings → Channels](https://mutopay.com/dashboard/settings) → test webhook. If the test fails, the issue is on your side.
4. Returning a non-2xx? MutoPay retries 5 times over ~15 hours, then gives up. Check your server logs.

## Getting help

- For integration issues: hello@mutopay.com with your merchant ID, the payment ID, and the full request/response including headers (redact keys).
- For account suspension or billing: reply to the email we sent you, or same address.
- Status page: [status.mutopay.com](https://status.mutopay.com) (if active).

## See also

- [Authentication](/docs/authentication/) — which key to use where.
- [Verify a webhook signature](/docs/verify-webhook-signature/) — fixes most webhook auth errors.

---
# API Reference

Source: https://mutopay.com/docs/api-reference/

The full MutoPay API reference — interactive Scalar viewer plus the raw OpenAPI 3.1 spec for generating clients or piping into tooling.

MutoPay publishes an OpenAPI 3.1 specification. Use it interactively, or pipe it into your codegen tool of choice.

## Interactive reference

[**mutopay.com/api/docs**](https://mutopay.com/api/docs) — Scalar-powered browser UI. Try endpoints live with your own API key, inspect request/response schemas, and copy cURL snippets.

## Raw OpenAPI spec

[**mutopay.com/api/openapi.json**](https://mutopay.com/api/openapi.json) — OpenAPI 3.1 JSON. Point any client generator at this URL.

```bash
# Example: generate a TypeScript client
npx @hey-api/openapi-ts -i https://mutopay.com/api/openapi.json -o ./src/mutopay-client

# Example: generate a Python client
openapi-python-client generate --url https://mutopay.com/api/openapi.json
```

## Authentication in the spec

Two security schemes are declared:

| Scheme | Use |
|---|---|
| `X-API-Key` (channel keys, prefix `ep_`) | Payment creation |
| `Bearer` (master keys, prefix `msk_`) | Account management under `/api/merchant/*` |

Most codegen tools will surface these as typed parameters on the generated client. See [Authentication](/docs/authentication/) for the plain-English explanation of when to use which.

## Base URL

```
https://mutopay.com
```

There is no sandbox/test server — use small `amount_usd` values (≤ $1) on your own test channel while developing.

## Prefer plain docs?

- [Getting Started](/docs/getting-started/) — end-to-end walkthrough.
- [Create a Payment](/docs/create-payment/) — the most common endpoint, with full examples.
- [Webhooks](/docs/webhooks/) — event reference.
- [llms-full.txt](/llms-full.txt) — every doc on this site, concatenated and LLM-ready.

---