> For the complete documentation index, see [llms.txt](https://docs-v2.mugglepay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v2.mugglepay.com/integration/api-doc/merchant-api/api-doc-postman.md).

# API Doc (POSTMAN)

> **Note:** MugglePay uses the same wire-protocol headers as the underlying Rozo payment protocol — `X-Rozo-Signature` and `X-Rozo-Timestamp` are protocol identifiers and are sent verbatim.

#### Overview

**Latest version for merchants — Summary**

* **OpenAPI spec (v2.0.0):** available on request — email <support@mugglepay.com> and we will send you the YAML file.
* **Version:** `2.0.0` (previously `1.0.0`)
* **Revision date:** `2026-05-11` (recorded in `x-revision-date`)
* **This page:** /integration/api-doc/api-doc-postman

#### Get Your API Key

Before calling any endpoint, you need an API key from the MugglePay merchant portal.

1. Sign in at [**business.mugglepay.com**](https://business.mugglepay.com).
2. Create or open your merchant app — your `appId` will look like `merchant_<slug>` or `wallet_<slug>`.
3. Generate an API key — format: `rz_live_xxxxx`. The key is bound to that `appId`.
4. Configure your **webhook URL** in the portal (used for `payment_payin_completed` and `payment_payout_completed` events).
5. Pass the key on every `POST` request as the `X-API-Key` header:

```
X-API-Key: rz_live_xxxxx
```

> When `X-API-Key` is present, the key's `app_id` is authoritative — a stale `appId` in the request body is silently overridden. This is cross-tenant defense, so you cannot accidentally write into another merchant's namespace.

**Auth errors**

* `400 missing_api_key` — `appId` requires a key but none was provided.
* `400 invalid_api_key` — key is unknown, revoked, expired, or inactive.

#### Complete Endpoint List

This is everything a merchant needs to look at.

**1. Payment API (4 endpoints)**

All paths are based on the base URL:

```
https://apiv2.mugglepay.com/functions/v1/payment-api
```

All `POST` requests require the header:

```
X-API-Key: rz_live_xxxxx
```

| # | Method | Path                                | Purpose                                                                            |
| - | ------ | ----------------------------------- | ---------------------------------------------------------------------------------- |
| 1 | POST   | `/`                                 | Create an order — returns `id` and `source.receiverAddress` (the deposit address). |
| 2 | GET    | `/payments/{paymentId}`             | Look up an order by MugglePay payment id.                                          |
| 3 | GET    | `/payments/order/{appId}/{orderId}` | Look up an order by your own `orderId` (idempotent lookup).                        |
| 4 | POST   | `/payments/{paymentId}/payin`       | (Optional) Accelerate confirmation — tell MugglePay the buyer's on-chain `txHash`. |

**2. Webhooks (2 outbound events)**

MugglePay will `POST` to the URL you configure at [business.mugglepay.com](https://business.mugglepay.com), signed with HMAC-SHA256.

| Event                      | Triggered when                                              |
| -------------------------- | ----------------------------------------------------------- |
| `payment_payin_completed`  | The buyer's payment is confirmed on-chain.                  |
| `payment_payout_completed` | The merchant wallet has received the funds (final success). |

**Signature headers**

* `X-Rozo-Timestamp`
* `X-Rozo-Signature`

**Signature contents**

```
sha256(timestamp + "." + raw_body, webhook_secret)
```

#### Import into Postman

To explore the API interactively, import the OpenAPI spec into Postman (or Insomnia / any OpenAPI-compatible client):

1. Request the OpenAPI spec file (v2.0.0 YAML) from <support@mugglepay.com>.
2. In Postman: **File → Import**, then select the YAML file. Postman generates a ready-to-use collection with all 4 payment endpoints and webhook schemas.
3. Set your `X-API-Key` (format `rz_live_xxxxx`) as a collection-level header and you can start firing requests against `https://apiv2.mugglepay.com/functions/v1/payment-api`.