# SatsRail Developers

> REST API reference and integration guides for SatsRail — non-custodial Bitcoin payment infrastructure, on-chain or Lightning.

- The API is served from `https://app.satsrail.com`. Merchant endpoints are under `/api/v1/m/` and take a secret key (`sk_live_…`, or `sk_test_…` in test mode); public endpoints are under `/api/v1/pub/` and take a publishable key.
- The hosted MCP server for AI agents is `https://app.satsrail.com/api/v1/mcp`.
- The OpenAPI spec is at https://www.satsrail.com/developers/data/satsrail-openapi.json.
- Every page is also Markdown: at the page's URL plus `index.md`, or at the page's own URL when the request says `Accept: text/markdown`.
- Every page in one file: https://www.satsrail.com/developers/llms-full.txt
- For the product itself, see https://www.satsrail.com/llms.txt.

# API Reference

> SatsRail REST API documentation. Non-custodial Bitcoin payment infrastructure, on-chain or Lightning.

Source: https://www.satsrail.com/developers/

Generated from the OpenAPI 3.0.3 spec: https://www.satsrail.com/developers/data/satsrail-openapi.json

Base URL: `https://app.satsrail.com`

## Authentication

Send the key as `Authorization: Bearer <key>`.

- `merchant_api_key` (bearer) — Merchant secret API key: `sk_live_* / sk_test_*`
- `public_embed_key` (bearer) — Publishable embed key for client-side integrations: `pk_live_*`

## Errors

Errors share one shape. This is a `401`:

```json
{
  "error": {
    "code": "missing_token",
    "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.",
    "status": 401,
    "request_id": "16801347-037f-4ccb-ae22-78100ecde612"
  }
}
```

## Endpoints

Merchant API:

- `POST /api/v1/m/access/verify` — verify
- `GET /api/v1/m/api_tokens/{id}/usage` — Get API token usage
- `GET /api/v1/m/catalog` — show
- `POST /api/v1/m/invoices/generate` — generate
- `GET /api/v1/m/invoices/{id}` — show
- `GET /api/v1/m/invoices/{id}/qr` — qr
- `GET /api/v1/m/invoices/{id}/status` — status
- `GET /api/v1/m/media_keys` — index
- `POST /api/v1/m/media_keys` — create
- `GET /api/v1/m/media_keys/{id}` — show
- `PATCH /api/v1/m/media_keys/{id}` — update
- `DELETE /api/v1/m/media_keys/{id}` — destroy
- `POST /api/v1/m/media_keys/{id}/clear_old_key` — clear_old_key
- `GET /api/v1/m/media_keys/{id}/key` — key
- `POST /api/v1/m/media_keys/{id}/products` — link_products
- `DELETE /api/v1/m/media_keys/{id}/products/{product_id}` — unlink_product
- `POST /api/v1/m/media_keys/{id}/rotate` — rotate
- `GET /api/v1/m/merchant` — show
- `GET /api/v1/m/orders` — index
- `POST /api/v1/m/orders` — create
- `GET /api/v1/m/orders/{id}` — show
- `PATCH /api/v1/m/orders/{id}` — update
- `DELETE /api/v1/m/orders/{id}` — destroy
- `POST /api/v1/m/payment_requests` — create
- `GET /api/v1/m/payment_requests/{id}` — show
- `GET /api/v1/m/payment_requests/{id}/status` — status
- `GET /api/v1/m/payments` — index
- `GET /api/v1/m/payments/{id}` — show
- `GET /api/v1/m/products` — List products
- `POST /api/v1/m/products` — Create a product
- `GET /api/v1/m/products/{id}` — Get a product
- `PATCH /api/v1/m/products/{id}` — Update a product
- `DELETE /api/v1/m/products/{id}` — Archive a product
- `POST /api/v1/m/products/{product_id}/media_keys` — link_to_product
- `DELETE /api/v1/m/products/{product_id}/media_keys/{id}` — unlink_from_product
- `POST /api/v1/m/sessions` — create
- `POST /api/v1/m/sessions/activate` — activate
- `GET /api/v1/m/wallets` — index
- `GET /api/v1/m/wallets/{id}` — show
- `GET /api/v1/m/webhooks` — index
- `POST /api/v1/m/webhooks` — create
- `GET /api/v1/m/webhooks/{id}` — show
- `PATCH /api/v1/m/webhooks/{id}` — update
- `DELETE /api/v1/m/webhooks/{id}` — destroy

Public API:

- `POST /api/v1/pub/access/verify` — verify
- `GET /api/v1/pub/categories` — index
- `GET /api/v1/pub/channels` — index
- `POST /api/v1/pub/checkout_sessions` — create
- `GET /api/v1/pub/creators` — index
- `GET /api/v1/pub/exchanges` — index
- `GET /api/v1/pub/subscription_plans` — index

## Merchant API

### POST /api/v1/m/access/verify

Access: verify

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Request body (`application/json`):

- `access_token` (string, required)
- `media_key_id` (string)

```json
{
  "access_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJvcmRlcl9pZCI6IjIxNGQ1YmU4LTA1ZDktNGJiNC04MjRmLWE0NmJhZTg0NDY0YyIsInByb2R1Y3RfaWQiOiI1ZmU3NjIzZi1mMzVkLTQ1MzktOWViZC1lNjUxMGUwZjMxMTUiLCJtZXJjaGFudF9pZCI6Ijk0Y2EzNDJhLTA2ODAtNGM0NS1iZjI5LTc1ZDU2MzRhMDBjMyIsImV4cCI6MTc5MDcwNzg3N30sImV4cCI6IjIwMjYtMDktMjlUMTg6NTE6MTcuOTc5WiIsInB1ciI6ImFjY2Vzc190b2tlbiJ9fQ--26622505cab02bb993c21b1af075be31c8ca75ff77574d77543a8bc6c0b6fb06",
  "media_key_id": "86471e94-02b3-4596-8b5a-fefddab8460a"
}
```

Responses:

- `200` releases a linked media key when media_key_id is named (without it, no key is returned)
- `402` refuses media keys to a v1 token, which names no product

Example `200` response:

```json
{
  "valid": true,
  "remaining_seconds": 86399,
  "server_time": 1790621477,
  "expires_at": 1790707876,
  "product_id": "5fe7623f-f35d-4539-9ebd-e6510e0f3115",
  "order_id": "214d5be8-05d9-4bb4-824f-a46bae84464c",
  "media_key_id": "86471e94-02b3-4596-8b5a-fefddab8460a",
  "key": "EXAMPLEonly-media-key-base64url-32-bytes",
  "key_fingerprint": "db5a28ed53da2b953bdc39f08b362317ca358042a6cc5bb4d507a59bbbc3e136"
}
```

### GET /api/v1/m/api_tokens/{id}/usage

Api token: Get API token usage

Returns usage statistics and rate limit configuration for a specific API token. Only active tokens owned by the authenticated merchant are accessible.

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_...`

Path parameters:

- `id` (string, required): API token UUID

Responses:

- `200` returns token usage data
- `404` token not found or not owned by merchant
- `401` unauthorized

Example `200` response:

```json
{
  "id": "string",
  "name": "string",
  "token_type": "string",
  "rpm_limit": "integer",
  "monthly_request_count": "integer",
  "last_request_counted_at": "string",
  "last_used_at": "string",
  "created_at": "string"
}
```

### GET /api/v1/m/catalog

Catalog: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer pk_live_YOUR_PUBLISHABLE_KEY`

Responses:

- `200` allows access with publishable key
- `401` requires authentication

Example `200` response:

```json
{
  "object": "catalog",
  "merchant_id": "2657842b-5006-4e6e-8488-3158e7c4806e",
  "catalog_version": "2026-03-14T03:11:55Z",
  "catalog_refresh_minutes": 30,
  "product_types": [
    {
      "id": "49708280-8d66-4cd6-9378-8e256e337160",
      "name": "Default",
      "position": 0,
      "products": [],
      "tax_ids": []
    }
  ],
  "taxes": [],
  "discounts": [],
  "livemode": true
}
```

### POST /api/v1/m/invoices/generate

Invoice: generate

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Request body (`application/json`):

- `order_id` (string, required)

```json
{
  "order_id": "cf1e996d-c303-46ea-b95e-6a7315689e70"
}
```

Responses:

- `201` returns the existing invoice
- `401` requires authentication
- `404` returns not found error

Example `201` response:

```json
{
  "object": "invoice",
  "livemode": true,
  "id": "3117b19c-4fff-4eaf-b0e4-b7406fce5d85",
  "payment_method": "lightning",
  "amount_sats": 10000,
  "status": "pending",
  "expires_at": "2026-03-14T04:11:55.467Z",
  "paid_at": null,
  "order_id": "cf1e996d-c303-46ea-b95e-6a7315689e70",
  "created_at": "2026-03-14T03:11:55.467Z",
  "updated_at": "2026-03-14T03:11:55.467Z",
  "payment_request": "lnbc10n1pj9q...",
  "payment_hash": "2eee05aec53912f0a2836d0ff78a2d934c43a2cdd02825d9e8c6fad2be86c81f",
  "expired": false,
  "time_until_expiry": 3599,
  "metadata": {
    "provider": "lnurl_demo",
    "mode": "mock"
  },
  "order": {
    "object": "order",
    "livemode": true,
    "id": "cf1e996d-c303-46ea-b95e-6a7315689e70",
    "order_number": "ORD-1773457915-4",
    "total_amount_cents": 10000,
    "tax_amount_cents": 0,
    "discount_amount_cents": 0,
    "total_amount_sats": 100000,
    "status": "pending",
    "merchant_id": "ef16bf22-8597-49af-b4df-a00ada990124",
    "channel_id": null,
    "wallet_id": "c85c322b-878c-4e67-a264-2abf023d335f",
    "discount_id": null,
    "created_at": "2026-03-14T03:11:55.464Z",
    "updated_at": "2026-03-14T03:11:55.464Z",
    "tender_type": "bitcoin",
    "items": [
      {
        "name": "Item 1",
        "price_cents": 10000,
        "qty": 1
      }
    ],
    "po_number": "ORD-1773457915-4",
    "btc_usd_price_at_creation": "100000.0",
    "btc_usd_rate_source": "coinbase",
    "currency": "usd",
    "btc_fiat_price_at_creation": "100000.0",
    "metadata": {}
  }
}
```

### GET /api/v1/m/invoices/{id}

Invoice: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `857d59e6-fe7d-4929-a3d5-3b5d0e92e8d7`

Responses:

- `200` includes order with correct JSON structure
- `401` requires authentication
- `404` prevents access to other merchant's invoices

Example `200` response:

```json
{
  "object": "invoice",
  "livemode": true,
  "id": "371bb5ac-a9a3-4251-83e7-5c5e1b9584ee",
  "payment_method": "lightning",
  "amount_sats": 10000,
  "status": "pending",
  "expires_at": "2026-03-14T04:11:55.505Z",
  "paid_at": null,
  "order_id": "70f52843-3b70-42d8-9953-111f0e840773",
  "created_at": "2026-03-14T03:11:55.505Z",
  "updated_at": "2026-03-14T03:11:55.505Z",
  "payment_request": "lnbc30n1pj9q...",
  "payment_hash": "b0df78ea711a2db64e6eb6c552ffe00b58800e8d8406bc791e7f0afcfcacee73",
  "expired": false,
  "time_until_expiry": 3599,
  "metadata": {},
  "order": {
    "object": "order",
    "livemode": true,
    "id": "70f52843-3b70-42d8-9953-111f0e840773",
    "order_number": "ORD-1773457915-6",
    "total_amount_cents": 10000,
    "tax_amount_cents": 0,
    "discount_amount_cents": 0,
    "total_amount_sats": 100000,
    "status": "pending",
    "merchant_id": "39b83ee2-3906-45c3-b7c9-d055bea10e44",
    "channel_id": null,
    "wallet_id": "c1832e80-72b1-4ae3-a49e-22e1bfffbaef",
    "discount_id": null,
    "created_at": "2026-03-14T03:11:55.502Z",
    "updated_at": "2026-03-14T03:11:55.502Z",
    "tender_type": "bitcoin",
    "items": [
      {
        "name": "Item 1",
        "price_cents": 10000,
        "qty": 1
      }
    ],
    "po_number": "ORD-1773457915-6",
    "btc_usd_price_at_creation": "100000.0",
    "btc_usd_rate_source": "coinbase",
    "currency": "usd",
    "btc_fiat_price_at_creation": "100000.0",
    "metadata": {}
  }
}
```

### GET /api/v1/m/invoices/{id}/qr

Invoice: qr

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `9f024127-e229-49a6-998c-057f832241a6`

Responses:

- `200` generates QR code with payment_request
- `401` requires authentication
- `404` prevents access to other merchant's invoice QR

A `200` response is `image/svg+xml`.

### GET /api/v1/m/invoices/{id}/status

Invoice: status

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `4b37eb1a-c52a-49e2-a327-c9d355c8d4c4`

Responses:

- `200` returns expired status
- `401` requires authentication
- `404` prevents checking status of other merchant's invoice

Example `200` response:

```json
{
  "status": "expired",
  "paid": false,
  "expired": true,
  "paid_at": null,
  "expires_at": "2026-03-14T02:11:55.758Z",
  "payment_method": "lightning",
  "payment": {
    "object": "payment",
    "livemode": true,
    "id": "fd1eba72-cc81-4267-8173-e129c6ced838",
    "amount_sats": 10000,
    "preimage": "preimage_0788fb6dc7e7b0554af6f0c90fc12b79_1",
    "confirmed_at": "2026-03-14T03:11:55.735Z",
    "order_id": "9f2a1e84-7748-41ac-aec9-44e74d44d928",
    "invoice_id": "7f0aecaf-d021-479f-a568-ff3a43ce40a0",
    "created_at": "2026-03-14T03:11:55.735Z",
    "updated_at": "2026-03-14T03:11:55.735Z",
    "channel_id": null,
    "payment_hash": "e838979f44ef5bc6e69005352881862ee56c0f4849a07062b91e5b46d93b47c1",
    "settled_at": "2026-03-14T03:11:55.735Z",
    "btc_usd_price_at_payment": "100000.0",
    "usd_value_at_payment": "10.0",
    "usd_variance_cents": -9000,
    "variance_percentage": "-90.0",
    "currency": "usd",
    "btc_fiat_price_at_payment": "100000.0",
    "fiat_value_at_payment": "10.0",
    "fiat_variance_cents": -9000,
    "confirmations": 0,
    "required_confirmations": 1,
    "metadata": {},
    "order": {
      "object": "order",
      "livemode": true,
      "id": "9f2a1e84-7748-41ac-aec9-44e74d44d928",
      "order_number": "ORD-1773457915-18",
      "total_amount_cents": 10000,
      "tax_amount_cents": 0,
      "discount_amount_cents": 0,
      "total_amount_sats": 100000,
      "status": "paid",
      "merchant_id": "cd2a76bd-53f5-4461-8129-660f18f955dc",
      "channel_id": null,
      "wallet_id": "2d425f9c-7817-4818-ab9a-26547c2b1405",
      "discount_id": null,
      "created_at": "2026-03-14T03:11:55.728Z",
      "updated_at": "2026-03-14T03:11:55.738Z",
      "tender_type": "bitcoin",
      "items": [
        {
          "name": "Item 1",
          "price_cents": 10000,
          "qty": 1
        }
      ],
      "po_number": "ORD-1773457915-18",
      "btc_usd_price_at_creation": "100000.0",
      "btc_usd_rate_source": "coinbase",
      "currency": "usd",
      "btc_fiat_price_at_creation": "100000.0",
      "metadata": {}
    }
  }
}
```

### GET /api/v1/m/media_keys

Media key: index

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Responses:

- `200` lists media keys
- `403` refuses keys that bridge an OAuth-connected assistant

Example `200` response:

```json
{
  "object": "list",
  "data": [
    {
      "object": "media_key",
      "livemode": true,
      "id": "9849fec0-44ae-40ac-99ba-293bb1ee7cff",
      "merchant_id": "95d63ac6-1625-4105-9dad-dafe5b12a9ce",
      "name": "Video key",
      "key_fingerprint": "2736be3e2cff047837483b34d47efe4ff8811da318b56856fab2a5be8c048beb",
      "rotation_pending": false,
      "browser_delivery": false,
      "product_ids": [
        "01109d09-a655-457a-ad78-37d62166ee9d"
      ],
      "metadata": {},
      "created_at": "2026-09-28T21:18:58.454Z",
      "updated_at": "2026-09-28T21:18:58.454Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}
```

### POST /api/v1/m/media_keys

Media key: create

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Request body (`application/json`):

- `media_key` (object)
- `media_key.name` (string)
- `media_key.browser_delivery` (boolean)
- `media_key.product_ids` (string[])

```json
{
  "media_key": {
    "name": "Video key",
    "browser_delivery": true,
    "product_ids": [
      "6f9d703d-09ac-4625-8cd3-3ec856f74fd2"
    ]
  }
}
```

Responses:

- `201` links products by id or slug in the same request
- `404` creates nothing when a product is unknown or belongs to another merchant

Example `201` response (lists cut to their first item):

```json
{
  "object": "media_key",
  "livemode": true,
  "id": "9e5e7fe3-e975-416f-b695-56c16241cbd3",
  "merchant_id": "96c3e316-923e-4e8a-a86b-b16ce0aafa55",
  "name": null,
  "key_fingerprint": "aa6453240caa89e1083273f6273e314c919e7fbbae567418e904c3739efe9793",
  "rotation_pending": false,
  "browser_delivery": false,
  "product_ids": [
    "2fa6f3b5-a44d-47f4-a41f-1eb520471f0a"
  ],
  "metadata": {},
  "created_at": "2026-09-28T21:18:52.050Z",
  "updated_at": "2026-09-28T21:18:52.050Z"
}
```

### GET /api/v1/m/media_keys/{id}

Media key: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `not-a-uuid`

Responses:

- `200` lists and shows the merchant's keys with their products
- `404` hides other merchants' keys

Example `200` response (lists cut to their first item):

```json
{
  "object": "media_key",
  "livemode": true,
  "id": "24da3441-b528-4024-a644-92bb5128e8b5",
  "merchant_id": "1266078b-ab5d-46b8-bf3c-24b15bdbbe5d",
  "name": "Video key",
  "key_fingerprint": "f1e9efc16cb7e202cfd05203c19925ddae2cad821dfb8c03bc941370b755591e",
  "rotation_pending": false,
  "browser_delivery": false,
  "product_ids": [
    "8c0b7625-0818-4920-a5df-c8895d606352"
  ],
  "metadata": {},
  "created_at": "2026-09-28T21:18:53.166Z",
  "updated_at": "2026-09-28T21:18:53.166Z"
}
```

### PATCH /api/v1/m/media_keys/{id}

Media key: update

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `6f517730-8e25-40b2-b024-723419718568`

Request body (`application/json`):

- `media_key` (object, required)
- `media_key.browser_delivery` (boolean, required)
- `media_key.key` (string)

```json
{
  "media_key": {
    "browser_delivery": true,
    "key": "attacker-key"
  }
}
```

Responses:

- `200` updates a media key
- `400` hides other merchants' keys and needs a body
- `403` requires manage access for key custody and links

Example `200` response:

```json
{
  "object": "media_key",
  "livemode": true,
  "id": "b1d7b020-17eb-48a4-8f83-1f221e2348d7",
  "merchant_id": "fb5c4efa-4d5b-488b-8f18-05e51b0029ab",
  "name": "Video key",
  "key_fingerprint": "a481a639027046fd752f8c52a1c96fce1cadde7be781ca18bc41ace53022f8e5",
  "rotation_pending": false,
  "browser_delivery": true,
  "product_ids": [],
  "metadata": {},
  "created_at": "2026-09-28T21:18:58.174Z",
  "updated_at": "2026-09-28T21:18:58.209Z"
}
```

### DELETE /api/v1/m/media_keys/{id}

Media key: destroy

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `5fe33e01-dcf1-485a-8a54-275baeb68180`

Responses:

- `204` destroys a key and its links

### POST /api/v1/m/media_keys/{id}/clear_old_key

Media key: clear_old_key

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `c0d8d917-e602-49cb-b93a-6ee7a3a601f6`

Request body (`application/json`):

```json
{}
```

Responses:

- `200` rotates, keeps the previous key until cleared, and notifies webhooks

Example `200` response:

```json
{
  "object": "media_key",
  "livemode": true,
  "id": "c0d8d917-e602-49cb-b93a-6ee7a3a601f6",
  "merchant_id": "bc850edb-56fb-48db-aece-bb73ad182886",
  "name": "Video key",
  "key_fingerprint": "4d04688ea3f056330e55f2714870a4be618fa6f55ef782d318118ee504da93b7",
  "rotation_pending": false,
  "browser_delivery": false,
  "product_ids": [],
  "metadata": {},
  "created_at": "2026-09-28T21:18:54.607Z",
  "updated_at": "2026-09-28T21:18:54.683Z"
}
```

### GET /api/v1/m/media_keys/{id}/key

Media key: key

Header parameters:

- `Authorization` (string, required), e.g. `Bearer pk_live_YOUR_PUBLISHABLE_KEY`

Path parameters:

- `id` (string, required), e.g. `1d266228-5d2b-484e-9369-db7f749cd313`

Responses:

- `200` returns key material only from the key endpoint
- `403` refuses publishable keys

Example `200` response:

```json
{
  "object": "media_key_secret",
  "id": "46db8bcc-10ac-47fa-98c4-d84e2a6a4aa1",
  "key": "EXAMPLEonly-media-key-base64url-32-bytes",
  "key_fingerprint": "db5a28ed53da2b953bdc39f08b362317ca358042a6cc5bb4d507a59bbbc3e136",
  "previous_key": null,
  "previous_key_fingerprint": null
}
```

### POST /api/v1/m/media_keys/{id}/products

Media key: link_products

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `45ad786b-530f-424a-9ccd-3f965fd9f11f`

Request body (`application/json`):

- `product_ids` (string[], required)

```json
{
  "product_ids": [
    "c21a8a3b-12b3-414f-b9ec-5672875d187c"
  ]
}
```

Responses:

- `200` links products to a media key
- `400` requires a bounded list

Example `200` response (lists cut to their first item):

```json
{
  "object": "media_key",
  "livemode": true,
  "id": "45ad786b-530f-424a-9ccd-3f965fd9f11f",
  "merchant_id": "93492e20-9ec7-4a07-a85f-f190b8a34dc6",
  "name": "Video key",
  "key_fingerprint": "bfcd0c3f43088f9ac2a69832fda5be910f5025efde7ba145dc7a78dafee4d217",
  "rotation_pending": false,
  "browser_delivery": false,
  "product_ids": [
    "c21a8a3b-12b3-414f-b9ec-5672875d187c"
  ],
  "metadata": {},
  "created_at": "2026-09-28T21:18:59.049Z",
  "updated_at": "2026-09-28T21:18:59.049Z"
}
```

### DELETE /api/v1/m/media_keys/{id}/products/{product_id}

Media key: unlink_product

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `e06f85b8-9462-429c-b046-34b1d912f932`
- `product_id` (string, required), e.g. `589a3798-7e6d-49ff-b96d-5c6e932a7fa2`

Responses:

- `200` links from the key side and unlinks one product

Example `200` response:

```json
{
  "object": "media_key",
  "livemode": true,
  "id": "e06f85b8-9462-429c-b046-34b1d912f932",
  "merchant_id": "2dc5660c-ee8d-4199-8062-0c36c2aa7253",
  "name": "Video key",
  "key_fingerprint": "554779381f4352fca9c28017544444c9938c988074365054679366126288dd96",
  "rotation_pending": false,
  "browser_delivery": false,
  "product_ids": [
    "265b3db6-8157-4e0d-b4f4-71020b616b74"
  ],
  "metadata": {},
  "created_at": "2026-09-28T21:18:55.184Z",
  "updated_at": "2026-09-28T21:18:55.184Z"
}
```

### POST /api/v1/m/media_keys/{id}/rotate

Media key: rotate

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `a28a806e-1927-43ad-a316-b3cd70e8c00f`

Request body (`application/json`):

```json
{}
```

Responses:

- `200` rotates a media key

Example `200` response:

```json
{
  "object": "media_key_secret",
  "id": "a28a806e-1927-43ad-a316-b3cd70e8c00f",
  "key": "EXAMPLEonly-media-key-base64url-32-bytes",
  "key_fingerprint": "db5a28ed53da2b953bdc39f08b362317ca358042a6cc5bb4d507a59bbbc3e136",
  "previous_key": "EXAMPLEonly-previous-key-base64url-32-bytes",
  "previous_key_fingerprint": "8bc62288bb5e4910fbbd3560fbb75dcd09bc9fb9e39bf29c2dc8ab16c1603ee8"
}
```

### GET /api/v1/m/merchant

Merchant: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Responses:

- `200` allows API access
- `401` returns 401 for GET /api/v1/merchant (token revoked on terminate)
- `403` returns 403 forbidden for GET /api/v1/merchant

Example `200` response:

```json
{
  "object": "merchant",
  "id": "030f701e-19ec-429d-93b0-ce36a444c5da",
  "name": "Merchant 64",
  "email": "merchant64@example.com",
  "phone": "(555) 555-0100",
  "business_license": "LICENSE-001",
  "status": "active",
  "time_zone": "UTC",
  "currency": "usd",
  "created_at": "2026-03-14T03:11:56.312Z",
  "updated_at": "2026-03-14T03:11:56.312Z",
  "tip_options": [],
  "logo_url": null,
  "pos_theme": "dark",
  "pos_enabled": true,
  "privapaid_enabled": false,
  "channels": [],
  "wallets": [
    {
      "object": "wallet",
      "id": "d91382af-e191-4117-9c57-7e8a657800a6",
      "name": "Wallet 65",
      "status": "active",
      "enabled": true,
      "position": 67,
      "created_at": "2026-03-14T03:11:56.316Z",
      "updated_at": "2026-03-14T03:11:56.316Z",
      "operational": true,
      "lightning": {
        "lightning_address": "testmerchant70@phoenix.acinq.co"
      }
    }
  ],
  "taxes": [],
  "livemode": true
}
```

### GET /api/v1/m/orders

Order: index

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_YOUR_SECRET_KEY`

Query parameters:

- `per_page` (integer), e.g. `10`
- `q[created_at_gteq]` (string), e.g. `2026-03-07T03:11:56Z`
- `q[created_at_lteq]` (string), e.g. `2026-03-14T03:11:56Z`
- `q[merchant_id_eq]` (string), e.g. `724f689e-1e73-4462-947a-d8ff6e05b89b`
- `q[payments_payment_type_eq]` (integer), e.g. `1`
- `q[status_eq]` (string), e.g. `paid`

Responses:

- `200` test token only sees test orders
- `401` rejects requests without Bearer prefix
- `403` returns 403 forbidden for GET /api/v1/orders

Example `200` response:

```json
{
  "object": "list",
  "data": [
    {
      "object": "order",
      "livemode": false,
      "id": "5ae83d27-4639-416f-b06f-8550a9c9aa90",
      "order_number": "ORD-1773457918-114",
      "total_amount_cents": 10000,
      "tax_amount_cents": 0,
      "discount_amount_cents": 0,
      "total_amount_sats": 100000,
      "status": "pending",
      "merchant_id": "8e2a625e-d5c0-4654-b655-38ce54cb1f01",
      "channel_id": null,
      "wallet_id": "8c854cc8-d7d0-49eb-9c09-593bf3452d3f",
      "discount_id": null,
      "created_at": "2026-03-14T03:11:58.346Z",
      "updated_at": "2026-03-14T03:11:58.346Z",
      "tender_type": "bitcoin",
      "items": [
        {
          "name": "Item 1",
          "price_cents": 10000,
          "qty": 1
        }
      ],
      "po_number": "ORD-1773457918-114",
      "btc_usd_price_at_creation": "100000.0",
      "btc_usd_rate_source": "coinbase",
      "currency": "usd",
      "btc_fiat_price_at_creation": "100000.0",
      "metadata": {}
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}
```

### POST /api/v1/m/orders

Order: create

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_YOUR_SECRET_KEY`

Request body (`application/json`):

- `order` (object, required)
- `order.total_amount_cents` (integer, required)
- `order.customer_email` (string, email)
- `order.items` (object[], required)
- `order.items[].name` (string, required)
- `order.items[].price_cents` (integer, required)
- `order.items[].qty` (integer, required)
- `order.tender_type` (string)
- `order.currency` (string)
- `generate_invoice` (boolean)
- `mark_as_paid` (boolean)

```json
{
  "order": {
    "total_amount_cents": 5000,
    "items": [
      {
        "name": "Widget",
        "price_cents": 5000,
        "qty": 1
      }
    ],
    "tender_type": "cash",
    "currency": "usd"
  },
  "generate_invoice": true,
  "mark_as_paid": true
}
```

Responses:

- `201` creates orders with correct livemode flag from test token
- `401` requires authentication
- `422` returns validation errors with correct structure

Example `201` response:

```json
{
  "object": "order",
  "livemode": false,
  "id": "e6e9ba68-bde9-4938-8585-6d3df8aa5c08",
  "order_number": "ORD-6AE0989B55CA9F17",
  "total_amount_cents": 5000,
  "tax_amount_cents": 0,
  "discount_amount_cents": 0,
  "total_amount_sats": 50000,
  "status": "pending",
  "merchant_id": "1ba083e9-2701-43d5-b375-cceb65ecb130",
  "channel_id": null,
  "wallet_id": "42ae58e1-896a-4476-b286-a44ad10f8986",
  "discount_id": null,
  "created_at": "2026-03-14T03:11:58.382Z",
  "updated_at": "2026-03-14T03:11:58.382Z",
  "tender_type": "bitcoin",
  "items": [
    {
      "name": "Widget",
      "price_cents": 5000,
      "qty": 1
    }
  ],
  "po_number": "ORD-6AE0989B55CA9F17",
  "btc_usd_price_at_creation": "100000.0",
  "btc_usd_rate_source": "coinbase",
  "currency": "usd",
  "btc_fiat_price_at_creation": "100000.0",
  "metadata": {},
  "invoice": {
    "object": "invoice",
    "livemode": true,
    "id": "fff4313b-f93e-4321-baa2-6fcfa17fbb18",
    "payment_method": "lightning",
    "amount_sats": 10000,
    "status": "pending",
    "expires_at": "2026-03-14T03:26:56.679Z",
    "paid_at": null,
    "order_id": "a2158e12-b22d-42b7-8217-ee90f3b4ff01",
    "created_at": "2026-03-14T03:11:56.679Z",
    "updated_at": "2026-03-14T03:11:56.679Z",
    "payment_request": "lnbc10000u1ped5914a06083b199c797e26f359383d28c9679ba5ad59f2b73cb85a69691eee4",
    "payment_hash": "f911c798e78ad250c5b093e3f0838245d6bf0a4004371cd6c44a68caf63c4c18",
    "expired": false,
    "time_until_expiry": 899,
    "metadata": {
      "mode": "mock",
      "provider": "lnurl_demo"
    }
  },
  "cash_paid_at": "2026-03-14T03:11:57.031Z"
}
```

### GET /api/v1/m/orders/{id}

Order: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `bcb3cddc-2fc3-456a-8e93-ae9dceb3d50b`

Responses:

- `200` includes livemode field in order responses
- `401` requires authentication
- `404` live token cannot access test order by ID

Example `200` response:

```json
{
  "object": "order",
  "livemode": true,
  "id": "bcb3cddc-2fc3-456a-8e93-ae9dceb3d50b",
  "order_number": "ORD-1773457918-117",
  "total_amount_cents": 10000,
  "tax_amount_cents": 0,
  "discount_amount_cents": 0,
  "total_amount_sats": 100000,
  "status": "pending",
  "merchant_id": "b9475619-be78-4b05-b040-fa85171dab1a",
  "channel_id": null,
  "wallet_id": "a405197e-6f13-42d8-bd90-901db95a8efe",
  "discount_id": null,
  "created_at": "2026-03-14T03:11:58.466Z",
  "updated_at": "2026-03-14T03:11:58.466Z",
  "tender_type": "bitcoin",
  "items": [
    {
      "name": "Item 1",
      "price_cents": 10000,
      "qty": 1
    }
  ],
  "po_number": "ORD-1773457918-117",
  "btc_usd_price_at_creation": "100000.0",
  "btc_usd_rate_source": "coinbase",
  "currency": "usd",
  "btc_fiat_price_at_creation": "100000.0",
  "metadata": {},
  "merchant": {
    "object": "merchant",
    "id": "b9475619-be78-4b05-b040-fa85171dab1a",
    "name": "Merchant 176",
    "email": "merchant176@example.com",
    "phone": "(555) 555-0100",
    "business_license": "LICENSE-001",
    "status": "active",
    "time_zone": "UTC",
    "currency": "usd",
    "created_at": "2026-03-14T03:11:58.460Z",
    "updated_at": "2026-03-14T03:11:58.460Z",
    "tip_options": [],
    "logo_url": null,
    "pos_theme": "dark",
    "pos_enabled": true,
    "privapaid_enabled": false,
    "channels": [],
    "wallets": [
      {
        "object": "wallet",
        "id": "a405197e-6f13-42d8-bd90-901db95a8efe",
        "name": "Wallet 177",
        "status": "active",
        "enabled": true,
        "position": 179,
        "created_at": "2026-03-14T03:11:58.464Z",
        "updated_at": "2026-03-14T03:11:58.464Z",
        "operational": true,
        "lightning": {
          "lightning_address": "testmerchant182@phoenix.acinq.co"
        }
      }
    ],
    "taxes": []
  },
  "cash_paid_at": "2026-03-14T03:11:57.078Z",
  "payment": {
    "object": "payment",
    "livemode": true,
    "id": "4fcd5112-5dc7-428b-a58a-b4c94c861721",
    "amount_sats": null,
    "preimage": null,
    "confirmed_at": "2026-03-14T03:11:57.078Z",
    "order_id": "62037323-3c46-46b8-a04d-5320808d2326",
    "invoice_id": null,
    "created_at": "2026-03-14T03:11:57.079Z",
    "updated_at": "2026-03-14T03:11:57.079Z",
    "channel_id": null,
    "payment_hash": null,
    "settled_at": "2026-03-14T03:11:57.078Z",
    "usd_value_at_payment": "100.0",
    "currency": "usd",
    "fiat_value_at_payment": "100.0",
    "confirmations": 0,
    "required_confirmations": 1,
    "metadata": {}
  }
}
```

### PATCH /api/v1/m/orders/{id}

Order: update

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `72aa9f7f-4751-46ad-b208-155d5e81ece3`

Request body (`application/json`):

- `order` (object, required)
- `order.total_amount_cents` (integer)
- `order.currency` (string)
- `order.customer_email` (string, email)
- `order.items` (object[])
- `order.items[].name` (string, required)
- `order.items[].price_cents` (integer, required)
- `order.items[].qty` (integer, required)
- `order.metadata` (object)
- `order.metadata.ref` (string)
- `order.metadata.note` (string)
- `order.status` (string)
- `order.wallet_id` (string)
- `order.tender_type` (string)

```json
{
  "order": {
    "total_amount_cents": 9999,
    "currency": "eur",
    "items": [
      {
        "name": "New Item",
        "price_cents": 2000,
        "qty": 1
      }
    ],
    "metadata": {
      "ref": "123",
      "note": "sneaky"
    },
    "status": "paid",
    "wallet_id": "e3099d67-a21a-47a9-ac82-dc6a0d88c168",
    "tender_type": "cash"
  }
}
```

Responses:

- `200` marks cash order as paid via status update
- `401` requires authentication
- `404` prevents updating other merchant's orders

Example `200` response:

```json
{
  "object": "order",
  "livemode": true,
  "id": "72aa9f7f-4751-46ad-b208-155d5e81ece3",
  "order_number": "ORD-1773457917-80",
  "total_amount_cents": 10000,
  "tax_amount_cents": 0,
  "discount_amount_cents": 0,
  "total_amount_sats": 100,
  "status": "paid",
  "merchant_id": "b30a692c-48f0-460f-940c-bfbca552fc17",
  "channel_id": null,
  "wallet_id": null,
  "discount_id": null,
  "created_at": "2026-03-14T03:11:57.057Z",
  "updated_at": "2026-03-14T03:11:57.064Z",
  "tender_type": "cash",
  "items": [
    {
      "name": "Item 1",
      "price_cents": 10000,
      "qty": 1
    }
  ],
  "po_number": "ORD-1773457917-80",
  "btc_usd_price_at_creation": "100000.0",
  "btc_usd_rate_source": "coinbase",
  "currency": "usd",
  "btc_fiat_price_at_creation": "100000.0",
  "metadata": {
    "ref": "123",
    "note": "sneaky"
  },
  "cash_paid_at": "2026-03-14T03:11:57.064Z",
  "merchant": {
    "object": "merchant",
    "id": "b30a692c-48f0-460f-940c-bfbca552fc17",
    "name": "Merchant 102",
    "email": "merchant102@example.com",
    "phone": "(555) 555-0100",
    "business_license": "LICENSE-001",
    "status": "active",
    "time_zone": "UTC",
    "currency": "usd",
    "created_at": "2026-03-14T03:11:57.052Z",
    "updated_at": "2026-03-14T03:11:57.052Z",
    "tip_options": [],
    "logo_url": null,
    "pos_theme": "dark",
    "pos_enabled": true,
    "privapaid_enabled": false,
    "channels": [],
    "wallets": [
      {
        "object": "wallet",
        "id": "a2507cb3-e5f7-40a4-abc7-a5efe52bb2c7",
        "name": "Wallet 104",
        "status": "active",
        "enabled": true,
        "position": 106,
        "created_at": "2026-03-14T03:11:57.056Z",
        "updated_at": "2026-03-14T03:11:57.056Z",
        "operational": true,
        "lightning": {
          "lightning_address": "testmerchant109@phoenix.acinq.co"
        }
      }
    ],
    "taxes": []
  },
  "payment": {
    "object": "payment",
    "livemode": true,
    "id": "8da30daa-e106-4496-bb1a-959d05a7c0b6",
    "amount_sats": null,
    "preimage": null,
    "confirmed_at": "2026-03-14T03:11:57.064Z",
    "order_id": "72aa9f7f-4751-46ad-b208-155d5e81ece3",
    "invoice_id": null,
    "created_at": "2026-03-14T03:11:57.065Z",
    "updated_at": "2026-03-14T03:11:57.065Z",
    "channel_id": null,
    "payment_hash": null,
    "settled_at": "2026-03-14T03:11:57.064Z",
    "usd_value_at_payment": "100.0",
    "currency": "usd",
    "fiat_value_at_payment": "100.0",
    "confirmations": 0,
    "required_confirmations": 1,
    "metadata": {}
  }
}
```

### DELETE /api/v1/m/orders/{id}

Order: destroy

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `68caf49a-1084-445f-9d68-4621a8ea8c3d`

Responses:

- `204` returns no content status
- `401` requires authentication
- `404` prevents cancelling other merchant's orders

### POST /api/v1/m/payment_requests

Payment request: create

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Request body (`application/json`):

- `payment_request` (object, required)
- `payment_request.amount_cents` (integer, required)
- `payment_request.payment_method` (string, required)
- `payment_request.description` (string, required)
- `payment_request.customer_email` (string, email)

```json
{
  "payment_request": {
    "amount_cents": 10000,
    "payment_method": "lightning",
    "description": "Test payment"
  }
}
```

Responses:

- `201` returns lightning-specific fields with correct types
- `401` requires authentication
- `422` returns error for invalid payment method

Example `201` response:

```json
{
  "object": "payment_request",
  "id": "1d36a2e1-aa00-4400-b24c-4ff451b47289",
  "payment_method": "lightning",
  "amount_sats": 10000,
  "created_at": "2026-03-14T03:11:57Z",
  "expires_at": "2026-03-14T04:11:57Z",
  "payment_request": "lnbc200n1pj9q...",
  "payment_hash": "7475af0f76afbd075f49698ea177c8b08f1cf39a15dee677064677756b3d1554"
}
```

### GET /api/v1/m/payment_requests/{id}

Payment request: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `e39ebc0b-1dbf-4386-9daa-3d6dbfb33ba9`

Responses:

- `200` returns paid status with paid_at
- `401` requires authentication
- `404` prevents access to other merchant's payment requests

Example `200` response:

```json
{
  "object": "payment_request",
  "id": "e39ebc0b-1dbf-4386-9daa-3d6dbfb33ba9",
  "payment_method": "lightning",
  "amount_sats": 10000,
  "created_at": "2026-03-14T03:11:57Z",
  "expires_at": "2026-03-14T04:11:57Z",
  "payment_request": "lnbc250n1pj9q...",
  "payment_hash": "95e9191c6bde0074eaa855d51372136cb327c1327b184aa7df85d48d9b8d64a7",
  "status": "paid",
  "paid_at": "2026-03-14T03:11:57Z",
  "amount_paid_sats": null
}
```

### GET /api/v1/m/payment_requests/{id}/status

Payment request: status

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `eeb10982-feea-478e-8bab-18a0daa27751`

Responses:

- `200` returns paid_at timestamp
- `401` requires authentication
- `404` prevents access to other merchant's payment requests

Example `200` response:

```json
{
  "id": "eeb10982-feea-478e-8bab-18a0daa27751",
  "status": "paid",
  "paid_at": "2026-03-14T03:11:57Z",
  "amount_sats": 10000,
  "amount_paid_sats": null
}
```

### GET /api/v1/m/payments

Payment: index

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Query parameters:

- `per_page` (integer), e.g. `10`
- `q[amount_sats_gteq]` (integer), e.g. `10000`
- `q[confirmed_at_gteq]` (string), e.g. `2026-03-07T03:11:57Z`
- `q[confirmed_at_lteq]` (string), e.g. `2026-03-14T03:11:57Z`
- `q[order_id_eq]` (string), e.g. `cf9959e1-fa40-46f6-9e1f-37e46eb628c7`

Responses:

- `200` only returns payments for the authenticated merchant
- `401` requires authentication

Example `200` response:

```json
{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "livemode": true,
      "id": "02b006ee-4702-48fa-98f7-77b5de05058b",
      "amount_sats": 10000,
      "preimage": "preimage_9befbda3e23e242eac5fa0db8ab881ae_44",
      "confirmed_at": "2026-03-14T03:11:57.610Z",
      "order_id": "5959dde2-8bcd-43d0-bbb4-6994e6bfea8d",
      "invoice_id": "975788bb-d881-4927-8f13-5d9cfaf5a166",
      "created_at": "2026-03-14T03:11:57.611Z",
      "updated_at": "2026-03-14T03:11:57.611Z",
      "channel_id": null,
      "payment_hash": "b33ebd4143de8da227917204b4480f38e2c66a093f7d5d07b40d1a45f69d03b6",
      "settled_at": "2026-03-14T03:11:57.610Z",
      "btc_usd_price_at_payment": "100000.0",
      "usd_value_at_payment": "10.0",
      "usd_variance_cents": -9000,
      "variance_percentage": "-90.0",
      "currency": "usd",
      "btc_fiat_price_at_payment": "100000.0",
      "fiat_value_at_payment": "10.0",
      "fiat_variance_cents": -9000,
      "confirmations": 0,
      "required_confirmations": 1,
      "metadata": {},
      "order": {
        "object": "order",
        "livemode": true,
        "id": "5959dde2-8bcd-43d0-bbb4-6994e6bfea8d",
        "order_number": "ORD-1773457917-104",
        "total_amount_cents": 10000,
        "tax_amount_cents": 0,
        "discount_amount_cents": 0,
        "total_amount_sats": 100000,
        "status": "paid",
        "merchant_id": "80161a5f-b712-4072-890b-bad1dc3f9b0a",
        "channel_id": null,
        "wallet_id": "2ce37d06-aec3-408a-8d99-619a37cef996",
        "discount_id": null,
        "created_at": "2026-03-14T03:11:57.607Z",
        "updated_at": "2026-03-14T03:11:57.607Z",
        "tender_type": "bitcoin",
        "items": [
          {
            "name": "Item 1",
            "price_cents": 10000,
            "qty": 1
          }
        ],
        "po_number": "ORD-1773457917-104",
        "btc_usd_price_at_creation": "100000.0",
        "btc_usd_rate_source": "coinbase",
        "currency": "usd",
        "btc_fiat_price_at_creation": "100000.0",
        "metadata": {}
      },
      "invoice": {
        "object": "invoice",
        "livemode": true,
        "id": "975788bb-d881-4927-8f13-5d9cfaf5a166",
        "payment_method": "lightning",
        "amount_sats": 10000,
        "status": "paid",
        "expires_at": "2026-03-14T04:11:57.609Z",
        "paid_at": null,
        "order_id": "5959dde2-8bcd-43d0-bbb4-6994e6bfea8d",
        "created_at": "2026-03-14T03:11:57.609Z",
        "updated_at": "2026-03-14T03:11:57.609Z",
        "payment_request": "lnbc380n1pj9q...",
        "payment_hash": "b33ebd4143de8da227917204b4480f38e2c66a093f7d5d07b40d1a45f69d03b6",
        "expired": false,
        "time_until_expiry": 3599,
        "metadata": {}
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}
```

### GET /api/v1/m/payments/{id}

Payment: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `c1ecee92-955b-4fa0-894b-20fa391c15aa`

Responses:

- `200` includes timestamp information with correct types
- `401` requires authentication
- `404` prevents access to other merchant's payments

Example `200` response:

```json
{
  "object": "payment",
  "livemode": true,
  "id": "c1ecee92-955b-4fa0-894b-20fa391c15aa",
  "amount_sats": 10000,
  "preimage": "preimage_89a7358f79c0c62abef0b1b18d504354_50",
  "confirmed_at": "2026-03-14T03:11:57.740Z",
  "order_id": "46c49a03-b055-4d86-b406-15a2c612051f",
  "invoice_id": "752fe94f-25e6-4b4a-9323-9801bda1c9b2",
  "created_at": "2026-03-14T03:11:57.741Z",
  "updated_at": "2026-03-14T03:11:57.741Z",
  "channel_id": null,
  "payment_hash": "5a63a65dcbb2d6d87015a34a6163e4864b39657d6843abbc878b4aec54b00ac6",
  "settled_at": "2026-03-14T03:11:57.740Z",
  "btc_usd_price_at_payment": "100000.0",
  "usd_value_at_payment": "10.0",
  "usd_variance_cents": -9000,
  "variance_percentage": "-90.0",
  "currency": "usd",
  "btc_fiat_price_at_payment": "100000.0",
  "fiat_value_at_payment": "10.0",
  "fiat_variance_cents": -9000,
  "confirmations": 0,
  "required_confirmations": 1,
  "metadata": {},
  "order": {
    "object": "order",
    "livemode": true,
    "id": "46c49a03-b055-4d86-b406-15a2c612051f",
    "order_number": "ORD-1773457917-110",
    "total_amount_cents": 10000,
    "tax_amount_cents": 0,
    "discount_amount_cents": 0,
    "total_amount_sats": 100000,
    "status": "paid",
    "merchant_id": "f441a972-a1cd-47b9-8738-8ce101ba00f2",
    "channel_id": null,
    "wallet_id": "9d9411f0-0fd4-4a9c-af6d-b07390826a11",
    "discount_id": null,
    "created_at": "2026-03-14T03:11:57.736Z",
    "updated_at": "2026-03-14T03:11:57.736Z",
    "tender_type": "bitcoin",
    "items": [
      {
        "name": "Item 1",
        "price_cents": 10000,
        "qty": 1
      }
    ],
    "po_number": "ORD-1773457917-110",
    "btc_usd_price_at_creation": "100000.0",
    "btc_usd_rate_source": "coinbase",
    "currency": "usd",
    "btc_fiat_price_at_creation": "100000.0",
    "metadata": {}
  },
  "invoice": {
    "object": "invoice",
    "livemode": true,
    "id": "752fe94f-25e6-4b4a-9323-9801bda1c9b2",
    "payment_method": "lightning",
    "amount_sats": 10000,
    "status": "paid",
    "expires_at": "2026-03-14T04:11:57.739Z",
    "paid_at": null,
    "order_id": "46c49a03-b055-4d86-b406-15a2c612051f",
    "created_at": "2026-03-14T03:11:57.739Z",
    "updated_at": "2026-03-14T03:11:57.739Z",
    "payment_request": "lnbc440n1pj9q...",
    "payment_hash": "5a63a65dcbb2d6d87015a34a6163e4864b39657d6843abbc878b4aec54b00ac6",
    "expired": false,
    "time_until_expiry": 3599,
    "metadata": {}
  }
}
```

### GET /api/v1/m/products

Product: List products

Returns a paginated list of products for the authenticated merchant. Supports filtering by name, status, sku, and date range.

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_...`

Query parameters:

- `per_page` (integer), e.g. `25`
- `page` (integer), e.g. `1`
- `q[name_cont]` (string): Filter by name (contains)
- `q[status_eq]` (string): Filter by status, e.g. `active`
- `q[sku_eq]` (string): Filter by SKU
- `q[created_at_gteq]` (string): Created after (ISO 8601)
- `q[created_at_lteq]` (string): Created before (ISO 8601)

Responses:

- `200` returns paginated list of products
- `401` unauthorized — missing or invalid API token

Example `200` response:

```json
{
  "object": "string",
  "data": [
    {
      "object": "string",
      "livemode": "boolean",
      "id": "string",
      "name": "string",
      "description": "string",
      "slug": "string",
      "sku": "string",
      "price_cents": "integer",
      "currency": "string",
      "status": "string",
      "position": "integer",
      "resource_type": "string",
      "image_url": "string",
      "access_duration_seconds": "integer",
      "product_type_id": "string",
      "merchant_id": "string",
      "api_token_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "formatted_price": "string",
      "payment_link_url": "string",
      "metadata": {}
    }
  ],
  "meta": {
    "current_page": "integer",
    "total_pages": "integer",
    "total_count": "integer",
    "per_page": "integer"
  }
}
```

### POST /api/v1/m/products

Product: Create a product

Creates a new product for the authenticated merchant. The product is automatically associated with the API token used to create it.

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_...`

Request body (`application/json`):

- `product` (object, required)
- `product.name` (string, required)
- `product.description` (string)
- `product.price_cents` (integer, required)
- `product.sku` (string)
- `product.status` (string), one of `active`, `archived`
- `product.product_type_id` (string, uuid)
- `product.resource_type` (string)
- `product.image_url` (string)
- `product.access_duration_seconds` (integer)
- `product.metadata` (object)

```json
{
  "product": {
    "name": "Premium Content",
    "description": "Access to premium content",
    "price_cents": 5000,
    "sku": "PREM-001",
    "resource_type": "digital",
    "image_url": "https://example.com/image.png"
  }
}
```

Responses:

- `201` product created successfully
- `422` validation errors
- `401` unauthorized — missing or invalid API token

Example `201` response:

```json
{
  "object": "string",
  "livemode": "boolean",
  "id": "string",
  "name": "string",
  "description": "string",
  "slug": "string",
  "sku": "string",
  "price_cents": "integer",
  "currency": "string",
  "status": "string",
  "position": "integer",
  "resource_type": "string",
  "image_url": "string",
  "access_duration_seconds": "integer",
  "product_type_id": "string",
  "merchant_id": "string",
  "api_token_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "formatted_price": "string",
  "payment_link_url": "string",
  "metadata": {}
}
```

### GET /api/v1/m/products/{id}

Product: Get a product

Returns a single product by slug.

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_...`

Path parameters:

- `id` (string, required): Product slug, e.g. `premium-content`

Responses:

- `200` returns the product
- `404` product not found
- `401` unauthorized

Example `200` response:

```json
{
  "object": "string",
  "livemode": "boolean",
  "id": "string",
  "name": "string",
  "description": "string",
  "slug": "string",
  "sku": "string",
  "price_cents": "integer",
  "currency": "string",
  "status": "string",
  "position": "integer",
  "resource_type": "string",
  "image_url": "string",
  "access_duration_seconds": "integer",
  "product_type_id": "string",
  "merchant_id": "string",
  "api_token_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "formatted_price": "string",
  "payment_link_url": "string",
  "metadata": {}
}
```

### PATCH /api/v1/m/products/{id}

Product: Update a product

Updates an existing product by slug.

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_...`

Path parameters:

- `id` (string, required): Product slug, e.g. `premium-content`

Request body (`application/json`):

- `product` (object, required)
- `product.name` (string, required)
- `product.description` (string)
- `product.price_cents` (integer, required)
- `product.sku` (string)
- `product.status` (string), one of `active`, `archived`
- `product.product_type_id` (string, uuid)
- `product.resource_type` (string)
- `product.image_url` (string)
- `product.access_duration_seconds` (integer)
- `product.metadata` (object)

```json
{
  "product": {
    "name": "Premium Content",
    "description": "Access to premium content",
    "price_cents": 5000,
    "sku": "PREM-001",
    "resource_type": "digital",
    "image_url": "https://example.com/image.png"
  }
}
```

Responses:

- `200` product updated successfully
- `404` product not found
- `422` validation errors
- `401` unauthorized

Example `200` response:

```json
{
  "object": "string",
  "livemode": "boolean",
  "id": "string",
  "name": "string",
  "description": "string",
  "slug": "string",
  "sku": "string",
  "price_cents": "integer",
  "currency": "string",
  "status": "string",
  "position": "integer",
  "resource_type": "string",
  "image_url": "string",
  "access_duration_seconds": "integer",
  "product_type_id": "string",
  "merchant_id": "string",
  "api_token_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "formatted_price": "string",
  "payment_link_url": "string",
  "metadata": {}
}
```

### DELETE /api/v1/m/products/{id}

Product: Archive a product

Soft-deletes (archives) a product by slug. The product is not permanently removed.

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_test_...`

Path parameters:

- `id` (string, required): Product slug, e.g. `premium-content`

Responses:

- `204` product archived successfully
- `404` product not found
- `401` unauthorized

### POST /api/v1/m/products/{product_id}/media_keys

Media key: link_to_product

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `product_id` (string, required), e.g. `2109dc69-ea0c-4f00-8b8d-6f4430f539fd`

Request body (`application/json`):

- `media_key_ids` (string[], required)

```json
{
  "media_key_ids": [
    "a1d3271a-e83a-4885-80b6-cfd4ac4767b0"
  ]
}
```

Responses:

- `200` links media keys to a product
- `404` links nothing when any referenced key or product is not the merchant's

Example `200` response:

```json
{
  "object": "media_key_links",
  "product_id": "2109dc69-ea0c-4f00-8b8d-6f4430f539fd",
  "media_key_ids": [
    "a1d3271a-e83a-4885-80b6-cfd4ac4767b0"
  ]
}
```

### DELETE /api/v1/m/products/{product_id}/media_keys/{id}

Media key: unlink_from_product

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `067f1da0-3050-4863-9377-2e0036c5bfc4`
- `product_id` (string, required), e.g. `prod_72b688d24adb3768fc373240`

Responses:

- `200` links one product to many keys from the product side

Example `200` response:

```json
{
  "object": "media_key_links",
  "product_id": "42d59560-0bba-49f2-96c1-1caac37a60de",
  "media_key_ids": []
}
```

### POST /api/v1/m/sessions

Session: create

Request body (`application/json`):

- `email` (string, required)
- `password` (string, required)

```json
{
  "email": "user28@example.com",
  "password": "password123456"
}
```

Responses:

- `200` resets failed attempts on successful login
- `400` returns 400 for missing credentials
- `401` increments failed attempts on wrong password
- `423` rejects valid credentials when account is locked

Example `200` response:

```json
{
  "session_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJ1c2VyX2lkIjoiYjdjNDA4NGYtOWYxYi00MjRmLWE4ODMtZjQ2NWU1ZmRhZTE0IiwiZXhwIjoxNzczNDU5NzE4fSwicHVyIjoicG9zX3Nlc3Npb24ifX0=--dfc82ff6369ff136daace5c67630f30259ad9f92",
  "merchants": [
    {
      "id": "c0326624-c893-4701-a99e-bea7fa0b67ca",
      "name": "Merchant 153",
      "logo_url": null,
      "currency": "usd",
      "role": "owner"
    }
  ]
}
```

### POST /api/v1/m/sessions/activate

Session: activate

Request body (`application/json`):

- `session_token` (string, required)
- `merchant_id` (string, required)

```json
{
  "session_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJ1c2VyX2lkIjoiOTZjZDY3MzEtZGJkZi00MWEwLWEwNGYtNWQ1MjgzZTk0ZTU5IiwiZXhwIjoxNzczNDU5NzE4fSwicHVyIjoicG9zX3Nlc3Npb24ifX0=--981626a7484c548066b74e2ecd5b83b6cd664e53",
  "merchant_id": "c378f7fe-c4ab-47b4-9660-48865734bcfb"
}
```

Responses:

- `200` still allows activation (POS available to all plans)
- `400` returns 400 for missing params
- `401` returns 401 for invalid session token
- `403` returns 403 for non-operational merchant
- `404` returns 404 for merchant with no active API key

Example `200` response:

```json
{
  "api_key": "sk_live_YOUR_SECRET_KEY",
  "merchant": {
    "id": "c378f7fe-c4ab-47b4-9660-48865734bcfb",
    "name": "Merchant 165",
    "currency": "usd"
  }
}
```

### GET /api/v1/m/wallets

Wallet: index

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Query parameters:

- `q[enabled_eq]` (string), e.g. `true`
- `q[merchant_id_eq]` (string), e.g. `d81b5fe2-2df5-4709-ab99-b8a7e0c2b322`

Responses:

- `200` includes lightning section with lightning_address
- `401` requires authentication

Example `200` response:

```json
{
  "object": "list",
  "data": [
    {
      "object": "wallet",
      "id": "0251fcd0-5751-4a9c-b3f1-101117555196",
      "name": "Wallet 189",
      "status": "active",
      "enabled": true,
      "position": 191,
      "created_at": "2026-03-14T03:11:58.590Z",
      "updated_at": "2026-03-14T03:11:58.590Z",
      "operational": true,
      "lightning": {
        "lightning_address": "shop@phoenix.acinq.co"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}
```

### GET /api/v1/m/wallets/{id}

Wallet: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `21a10ea0-c9fe-406f-a02e-713ac4ef43d8`

Responses:

- `200` does not include display_name, status_color, or next_payment_address
- `401` requires authentication
- `404` returns 404 with correct error structure for non-existent wallet

Example `200` response:

```json
{
  "object": "wallet",
  "id": "b93639c1-8515-4935-adf7-020415a44411",
  "name": "Wallet 193",
  "status": "active",
  "enabled": true,
  "position": 195,
  "created_at": "2026-03-14T03:11:58.637Z",
  "updated_at": "2026-03-14T03:11:58.637Z",
  "operational": true,
  "lightning": {
    "lightning_address": "testmerchant198@phoenix.acinq.co"
  },
  "last_checked_at": null,
  "last_transaction_at": null,
  "last_error": null,
  "consecutive_failures": 0
}
```

### GET /api/v1/m/webhooks

Webhook: index

Header parameters:

- `Authorization` (string, required), e.g. `sk_live_YOUR_SECRET_KEY`

Query parameters:

- `q[active_eq]` (string), e.g. `true`
- `q[merchant_id_eq]` (string), e.g. `40cba8fd-87fc-45db-bb45-2de7fdceab8e`

Responses:

- `200` only returns webhooks for the authenticated merchant
- `401` rejects requests without Bearer prefix

Example `200` response (lists cut to their first item):

```json
{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "livemode": true,
      "id": "f0bdc2b8-8f71-4dcd-a4ad-dc81929e651f",
      "url": "https://example.com/webhooks",
      "description": "Test Webhook",
      "events": [
        "order.created"
      ],
      "active": true,
      "success_count": 0,
      "failure_count": 0,
      "last_triggered_at": null,
      "created_at": "2026-03-14T03:11:58.971Z",
      "updated_at": "2026-03-14T03:11:58.971Z",
      "health_percentage": 100,
      "metadata": {}
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  },
  "available_events": [
    "order.created"
  ]
}
```

### POST /api/v1/m/webhooks

Webhook: create

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Request body (`application/json`):

- `webhook` (object, required)
- `webhook.url` (string, required)
- `webhook.events` (string[], required)
- `webhook.description` (string)

```json
{
  "webhook": {
    "url": "https://example.com/hook",
    "events": [
      "order.created"
    ],
    "description": "My test webhook"
  }
}
```

Responses:

- `201` creates a webhook with all available event types
- `401` requires authentication
- `422` returns validation errors for invalid url format

Example `201` response (lists cut to their first item):

```json
{
  "object": "webhook",
  "livemode": true,
  "id": "db705776-1673-4757-8732-fa46cd868d1c",
  "url": "https://example.com/hook",
  "description": null,
  "events": [
    "order.created"
  ],
  "active": true,
  "success_count": 0,
  "failure_count": 0,
  "last_triggered_at": null,
  "created_at": "2026-03-14T03:11:59.075Z",
  "updated_at": "2026-03-14T03:11:59.075Z",
  "health_percentage": 100,
  "metadata": {},
  "secret_key": "whsec_YOUR_WEBHOOK_SECRET"
}
```

### GET /api/v1/m/webhooks/{id}

Webhook: show

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `e3ae1c97-c3eb-48bc-9fcd-5d48065884db`

Responses:

- `200` does not expose secret_key on show
- `401` requires authentication
- `404` prevents access to other merchant's webhooks

Example `200` response (lists cut to their first item):

```json
{
  "object": "webhook",
  "livemode": true,
  "id": "982ebe1a-819e-4d95-981e-3c77eca16d23",
  "url": "https://example.com/webhooks",
  "description": "Test Webhook",
  "events": [
    "order.created"
  ],
  "active": true,
  "success_count": 0,
  "failure_count": 0,
  "last_triggered_at": null,
  "created_at": "2026-03-14T03:11:58.995Z",
  "updated_at": "2026-03-14T03:11:58.995Z",
  "health_percentage": 100,
  "metadata": {}
}
```

### PATCH /api/v1/m/webhooks/{id}

Webhook: update

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `07aed364-1bd1-4311-8872-a9694627b335`

Request body (`application/json`):

- `webhook` (object, required)
- `webhook.url` (string)
- `webhook.events` (string[])
- `webhook.active` (boolean)
- `webhook.description` (string)

```json
{
  "webhook": {
    "url": "https://updated.example.com/hook",
    "events": [
      "payment.confirmed"
    ],
    "active": false,
    "description": "Updated"
  }
}
```

Responses:

- `200` does not expose secret_key on update
- `401` requires authentication
- `404` prevents updating other merchant's webhooks
- `422` returns validation errors for invalid events

Example `200` response (lists cut to their first item):

```json
{
  "object": "webhook",
  "livemode": true,
  "id": "1ace2467-8c77-4f12-8139-54bc9fb206c8",
  "url": "https://example.com/webhooks",
  "description": "Updated",
  "events": [
    "order.created"
  ],
  "active": true,
  "success_count": 0,
  "failure_count": 0,
  "last_triggered_at": null,
  "created_at": "2026-03-14T03:11:59.197Z",
  "updated_at": "2026-03-14T03:11:59.202Z",
  "health_percentage": 100,
  "metadata": {}
}
```

### DELETE /api/v1/m/webhooks/{id}

Webhook: destroy

Header parameters:

- `Authorization` (string, required), e.g. `Bearer sk_live_YOUR_SECRET_KEY`

Path parameters:

- `id` (string, required), e.g. `e885ab37-4295-41e4-bebc-3287142a555f`

Responses:

- `204` returns no content status
- `401` requires authentication
- `404` prevents deleting other merchant's webhooks

## Public API

### POST /api/v1/pub/access/verify

Access: verify

Header parameters:

- `Authorization` (string, required), e.g. `Bearer pk_live_YOUR_PUBLISHABLE_KEY`

Request body (`application/json`):

- `access_token` (string)

```json
{
  "access_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJwYXltZW50X2lkIjoicGF5LXRlc3QtdXVpZCIsInJlc291cmNlX2lkIjoicHJvZF9hYmMiLCJyZXNvdXJjZV90eXBlIjoic3RyZWFtIiwiZXhwIjoxNzczNDU4NTE5fSwiZXhwIjoiMjAyNi0wMy0xNFQwMzoyMTo1OS4zMDdaIiwicHVyIjoiYWNjZXNzX3Rva2VuIn19--1c6d12e1f86a6bba3be28f425669b2a0adf2449b"
}
```

Responses:

- `200` accepts token via X-Access-Token header
- `400` returns 400 when access_token param is missing
- `401` returns 401 without a publishable key
- `402` returns 402 for a tampered token
- `403` returns 403 when merchant has privapaid disabled

Example `200` response:

```json
{
  "valid": true,
  "remaining_seconds": 600,
  "resource_id": "prod_abc",
  "resource_type": "stream"
}
```

### GET /api/v1/pub/categories

Category: index

Responses:

- `200` sets public cache headers

Example `200` response (lists cut to their first item):

```json
{
  "object": "list",
  "data": [
    "Film & Animation"
  ]
}
```

### GET /api/v1/pub/channels

Channel: index

Query parameters:

- `category` (string), e.g. `Gaming`
- `nsfw` (string), e.g. `true`
- `page` (integer), e.g. `1`
- `per_page` (integer), e.g. `2`
- `q` (string), e.g. `Gaming`

Responses:

- `200` defaults to 24 per page

Example `200` response:

```json
{
  "object": "list",
  "data": [
    {
      "slug": "chan-1",
      "name": "Channel 15",
      "bio": "A test channel for streaming.",
      "videos_count": 0,
      "nsfw": false,
      "theme": "rose",
      "category": "Entertainment",
      "profile_image_url": null,
      "social_links": {},
      "merchant_name": "Merchant 250",
      "country": "IQ",
      "country_name": "Country 224",
      "language": "en",
      "currency": "usd"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 24
  }
}
```

### POST /api/v1/pub/checkout_sessions

Checkout session: create

Header parameters:

- `Authorization` (string, required), e.g. `Bearer pk_live_YOUR_PUBLISHABLE_KEY`

Request body (`application/json`):

- `checkout_session` (object, required)
- `checkout_session.amount_cents` (integer)
- `checkout_session.currency` (string)
- `checkout_session.product_id` (string)
- `checkout_session.customer_email` (string)
- `checkout_session.customer_name` (string)
- `checkout_session.metadata` (object)
- `checkout_session.metadata.order_ref` (string, required)
- `checkout_session.metadata.source` (string, required)

```json
{
  "checkout_session": {
    "amount_cents": 5000,
    "currency": "usd",
    "product_id": "prod_32bf92c24dbad85569bd9acd",
    "customer_email": "buyer@example.com",
    "customer_name": "Alice Smith",
    "metadata": {
      "order_ref": "MY-123",
      "source": "website"
    }
  }
}
```

Responses:

- `201` accepts metadata hash
- `401` requires authentication
- `422` returns validation error for invalid email

Example `201` response:

```json
{
  "object": "checkout_session",
  "livemode": true,
  "id": "1ba2644d-ca41-479d-9689-db2e0e0b4657",
  "token": "cs_Ku60a_FLU38Nls2UOZyfvdjIs39RzcItqAiV0NK9IsQ",
  "checkout_url": "http://www.example.com/checkout/cs_Ku60a_FLU38Nls2UOZyfvdjIs39RzcItqAiV0NK9IsQ",
  "expires_at": "2026-03-14T03:26:55Z",
  "amount_cents": 5000,
  "tax_amount_cents": 0,
  "tax_details": [],
  "currency": "usd",
  "status": "pending",
  "customer_email": null,
  "customer_name": null,
  "customer_phone": null,
  "customer_address": null,
  "checkout_mode": "iframe",
  "checkout_theme": "light",
  "checkout_accent_color": "#e8b53c",
  "privapaid_enabled": false,
  "metadata": {
    "order_ref": "MY-123",
    "source": "website"
  }
}
```

### GET /api/v1/pub/creators

Creator: index

Responses:

- `200` returns the same data as the channels endpoint

Example `200` response:

```json
{
  "object": "list",
  "data": [
    {
      "slug": "compat-test",
      "name": "Channel 16",
      "bio": "A test channel for streaming.",
      "videos_count": 0,
      "nsfw": false,
      "theme": "rose",
      "category": "Entertainment",
      "profile_image_url": null,
      "social_links": {},
      "merchant_name": "Merchant 251",
      "country": "IR",
      "country_name": "Country 225",
      "language": "en",
      "currency": "usd"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 24
  }
}
```

### GET /api/v1/pub/exchanges

Exchange: index

Responses:

- `200` invalidates cache when an exchange_country is destroyed

Example `200` response (lists cut to their first item):

```json
{
  "exchanges": [
    {
      "id": "02f4199f-a5d2-4f93-ae93-581f4bafe650",
      "name": "Buda.com",
      "url": "https://buda.com",
      "promoted": true,
      "min_transaction_sats": null,
      "notes": null,
      "logo_url": null,
      "countries": [
        {
          "id": "5f355627-8c07-4c5e-a8a7-2f05fe7be640",
          "name": "Chile",
          "iso_code": "CL"
        }
      ]
    }
  ]
}
```

### GET /api/v1/pub/subscription_plans

Subscription plan: index

Responses:

- `200` includes features as a hash

Example `200` response (lists cut to their first item):

```json
{
  "plans": [
    {
      "slug": "free",
      "name": "Free",
      "description": "Get started with Bitcoin Lightning payments — no credit card required",
      "price_cents": 0,
      "price_display": "$0.00/month",
      "interval": "month",
      "max_monthly_volume_cents": 50000,
      "features": {
        "basic_reports": true,
        "accounting:reports": false,
        "email_support": true,
        "webhook_endpoints": 0,
        "team_members": 3,
        "max_monthly_transactions": 100,
        "pos_access": true,
        "privapaid_access": true,
        "max_channels": 1,
        "report_history_days": 30,
        "support_tier": "email"
      },
      "feature_labels": [
        "Basic reports"
      ],
      "rate_limits": {
        "per_api_key_per_minute": 20,
        "per_api_key_per_hour": 200,
        "delivery_per_order_per_hour": 10,
        "unauthenticated_per_minute": 20
      }
    }
  ]
}
```

---

# AI Agents

> Let AI agents accept Bitcoin payments programmatically. MCP server, zero-browser payment flow, and agent-friendly API for Claude, Cursor, and any LLM tool.

Source: https://www.satsrail.com/developers/guides/ai-agents/

The only payment processor AI agents can use natively.
No browser. No forms. Just an API call and a Lightning invoice string.

## Why Lightning Is Perfect for AI Agents

##### Credit Cards

- Require browser forms & 3D Secure
- PCI compliance burden
- Card numbers agents can't handle safely
- Chargebacks and fraud checks
- Banks can freeze accounts anytime

##### Lightning (SatsRail)

- One API call → invoice string
- No browser, no forms, no redirects
- Instant settlement
- No chargebacks — payment is final
- Non-custodial — no account freezes

## MCP Server

The SatsRail MCP server gives any AI agent with [Model Context Protocol](https://modelcontextprotocol.io/) support the ability to create orders, generate invoices, and check payment status.

##### Connect to the hosted server

SatsRail hosts the server at `https://app.satsrail.com/api/v1/mcp`. It speaks Streamable HTTP (one JSON-RPC message per POST), so there is nothing to install: point your client at the URL and authenticate with a secret key.

```
{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://app.satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_test_your_key_here" }
    }
  }
}
```

Works in Claude Code, Claude Desktop, Cursor, Windsurf and any Streamable-HTTP MCP client. Stdio-only clients can bridge to the URL with `mcp-remote`.

No key to paste? A client that supports OAuth connects with the URL alone: you sign in, pick the business and approve. Those connections manage your catalog and payment links only, and you can revoke them any time under Settings → AI Assistants.

## Available Tools

The hosted server exposes 43 tools: orders, invoices, payments, checkout, payment links, products and the catalog, webhooks, wallets and account data. These are the core payment tools; `tools/list` returns them all:

| Tool | Description |
| --- | --- |
| `create_order` | Create a payment order with optional auto-generated Lightning invoice |
| `get_order` | Get order details by ID (expandable: invoice, payment, merchant) |
| `list_orders` | List orders with optional status filter |
| `cancel_order` | Cancel a pending order |
| `get_invoice` | Get invoice details including bolt11 Lightning string |
| `check_invoice_status` | Real-time payment status check against the Lightning node |
| `generate_invoice` | Generate a new invoice for an existing order |
| `list_payments` | List confirmed payments with optional date range filter |
| `get_payment` | Get payment details |
| `create_checkout_session` | Create a hosted checkout session with redirect URL |
| `create_payment_link` | Create a reusable payment link (`/pay/…`) from a name and a price, to send a customer by chat, email or text |
| `get_merchant` | Get the current merchant's profile and settings |
| `list_wallets` | List connected wallets |

## Agent Payment Flow

A complete payment takes 3 steps — no browser involved at any point.

##### 1. Create Order

Agent calls `create_order` with amount and description. SatsRail returns an order with a bolt11 Lightning invoice string.

##### 2. Customer Pays

Agent presents the bolt11 string or a QR code to the customer. Customer pays with any Lightning wallet.

##### 3. Confirm

Agent calls `check_invoice_status` to verify payment, or listens for a webhook. Done.

##### Example Conversation

User "Charge me $25 for the monthly subscription"

Agent *→ calls create_order(amount_cents: 2500, generate_invoice: true)*

Agent "Here's your Lightning invoice. Scan this QR code or copy the payment string:"

lnbc250u1pj...kqq5yxmetu

User "Paid!"

Agent *→ calls check_invoice_status(invoice_id: "...")*

Agent "Payment confirmed! Your subscription is active. ⚡"

## Payment Links for Agents

A payment link (`https://www.satsrail.com/pay/prod_…`) opens the hosted checkout for one product at one price. It never expires and can be paid any number of times. That makes it the thing an agent hands to a person:

- **Selling.** The merchant's agent calls `create_payment_link` with a name and a price and gets back `payment_link_url` to send the customer. Every product the API returns carries its `payment_link_url` too (null while the product is inactive).
- **Buying for someone.** An agent that needs to pay a SatsRail merchant for the person it works for doesn't need a wallet, a key or a card: it sends that person the merchant's payment link, and they pay from their own wallet. The money goes straight to the merchant; the agent never holds funds.

Before forwarding a link, read it: the same URL with `.json` (or `Accept: application/json`) describes it and opens no checkout. No key is needed.

```
GET https://www.satsrail.com/pay/prod_4f1c9e2a7b3d8e6f5a1c0b9d.json

{
  "object": "payment_link",
  "url": "https://www.satsrail.com/pay/prod_4f1c9e2a7b3d8e6f5a1c0b9d",
  "name": "Sunset kayak tour",
  "amount_cents": 4500,
  "currency": "usd",
  "formatted_amount": "$45.00",
  "merchant": { "name": "Ember Tours" },
  "payable": true,
  "payment_methods": ["lightning"],
  "how_to_pay": "Open the url in a browser and pay from a bitcoin wallet. ..."
}
```

`payable` is false while the merchant has no wallet that can take the price; say so rather than send a link that shows an unavailable page. An inactive or unknown link answers `404`.

##### Example Conversation

User "Book me the sunset kayak tour on Saturday."

Agent *→ finds the tour's payment link on the operator's site, reads it with .json*

Agent "Ember Tours charges $45.00 for the Sunset kayak tour. Pay here and they'll confirm your spot: https://www.satsrail.com/pay/prod_4f1c…"

## Direct REST API

Don't need MCP? Any agent that can make HTTP requests can use SatsRail directly. The entire flow is JSON in, JSON out — no redirects, no HTML.

##### Create order + invoice in one call

```
curl -X POST https://app.satsrail.com/api/v1/m/orders \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "total_amount_cents": 2500,
      "currency": "usd"
    },
    "generate_invoice": true,
    "payment_method": "lightning"
  }'
```

##### Check payment status

```
curl https://app.satsrail.com/api/v1/m/invoices/{invoice_id}/status \
  -H "Authorization: Bearer sk_test_..."
```

[Full API Reference →](https://www.satsrail.com/developers/)

## Use Cases

##### SaaS & API Billing

Agents that sell access to services and collect payment in the conversation. Per-call, per-session, or per-task billing with no checkout page.

##### Agent-Generated Invoicing

Agents that create fresh invoices when payment is due — milestone billing, on-demand charges, or periodic collections.

##### Multi-Merchant Platforms

Build agent-powered marketplaces where AI handles the checkout flow across multiple merchants.

##### Invoicing Bots

Agents that send invoices, track payments, and follow up — from Slack, Discord, Telegram, or any chat platform.

## Configuration

| Setting | Required | Description |
| --- | --- | --- |
| URL | Yes | `https://app.satsrail.com/api/v1/mcp`, over Streamable HTTP. |
| `Authorization` header | Yes, unless you use OAuth | `Bearer sk_test_*` for testing, `Bearer sk_live_*` for production. |
| OAuth | No | Discovery starts at `https://app.satsrail.com/.well-known/oauth-protected-resource/api/v1/mcp`. An OAuth connection gets the catalog tools only. |

## Build the future of AI payments

Get your API key and let your agents start accepting Bitcoin in minutes.

[Get Your API Key →](https://satsrail.com/users/sign_up) [MCP Server](https://www.satsrail.com/mcp/)

---

# Checkout Experience

> Visual guide to the SatsRail checkout flow. See what your customers experience in both embedded and new tab modes — from customer info collection through payment confirmation.

Source: https://www.satsrail.com/developers/guides/checkout-experience/

What your customers see at each step of the payment flow.

## Two Display Modes

SatsRail checkout pages adapt their layout based on your merchant's **checkout mode** setting. Each mode is designed for its context:

###### Embedded Mode

Opens in an overlay on the merchant's page

Compact, space-efficient layout. No popup blockers. Works on desktop and mobile.

###### New Tab Mode

Opens in a full browser tab

Two-column layout with product info on the left and payment details on the right.

> Set the checkout mode in your **Merchant Settings** or override it per embed button with the `data-mode` attribute.

## Your Brand

Merchants choose three things in **Checkout Settings → Appearance**, with a live preview: a **light or dark theme**, one **accent color**, and the **logo** uploaded in General settings. The accent colors the main button and small highlights, and text on it switches between white and black so it stays readable. A color that would disappear against the chosen theme is refused when saving.

Everything else is the same for every merchant: the layout, the QR code (always black on white, so every wallet can read it), the amount and fee lines, the paid and expired colors, and "Powered by SatsRail".

Creating a checkout session returns `checkout_theme` (`light` or `dark`) and `checkout_accent_color` (a `#rrggbb` hex, SatsRail gold unless the merchant chose one), so your own page can match the checkout it opens.

## Embedded Mode

Compact checkout embedded in an overlay iframe on the merchant's page.

###### 1. Customer Info

![Embedded - Collect customer info](https://www.satsrail.com/images/docs/checkout/popup-collect-info.png)

Collects email, name, phone, or address based on merchant settings.

###### 2. Payment Method

![Embedded - Select payment method](https://www.satsrail.com/images/docs/checkout/popup-select-method.png)

Shown when the merchant offers both Lightning and on-chain (early access) and the amount reaches the on-chain minimum. Otherwise this step is skipped.

###### 3. QR Code

![Embedded - QR code payment](https://www.satsrail.com/images/docs/checkout/popup-qr-code.png)

On a computer, scan the QR code with any Lightning or Bitcoin wallet. On a phone, **Open in wallet** comes first and hands the invoice to the wallet app on that phone. Real-time status via WebSocket.

###### Confirmed

![Embedded - Payment confirmed](https://www.satsrail.com/images/docs/checkout/popup-confirmation.png)

Payment received. Customer is auto-redirected to your success URL.

## New Tab Mode

Spacious two-column layout for the full browser experience.

###### 1. Customer Info

![New Tab - Collect customer info](https://www.satsrail.com/images/docs/checkout/newtab-collect-info.png)

Amount displayed on the left, form fields on the right.

###### 2. Payment Method

![New Tab - Select payment method](https://www.satsrail.com/images/docs/checkout/newtab-select-method.png)

Price on the left, payment method options on the right. Shown when both Lightning and on-chain (early access) are offered; otherwise this step is skipped.

###### 3. QR Code

![New Tab - QR code payment](https://www.satsrail.com/images/docs/checkout/newtab-qr-code.png)

Amount and invoice details on the left, large QR code on the right.

###### Confirmed

![New Tab - Payment confirmed](https://www.satsrail.com/images/docs/checkout/newtab-confirmation.png)

Wider confirmation card with order details and email receipt notice.

## Steps Are Adaptive

Not every checkout has all four steps. The flow adapts automatically:

| Step | When It Appears | When It's Skipped |
| --- | --- | --- |
| **1. Customer Info** | Merchant has customer fields configured (email, name, phone, address) | No customer fields configured, or info pre-filled via API |
| **2. Payment Method** | The merchant offers both Lightning and on-chain (early access) and the amount reaches the on-chain minimum | Only one method can take the payment (an on-chain-only checkout goes straight to its screen), or the method is pre-selected via API |
| **3. QR Code** | Always | Never skipped |
| **4. Confirmation** | Always | Never skipped |

## Try it yourself

See the checkout in action on our demo site, or integrate it into your own.

[Live Demos →](https://www.satsrail.com/demos/) [Embed Button →](https://www.satsrail.com/developers/guides/embed/)

---

# Checkout Flow

> Understand the complete data flow from checkout session creation through payment confirmation. Table relationships, status transitions, and every database write explained.

Source: https://www.satsrail.com/developers/guides/checkout-flow/

How data moves from session creation to payment confirmation.

## Table Relationships

```
Merchant
   │ has_many
   ▼
CheckoutSession ──belongs_to──▶ Order ──has_one──▶ Invoice ──has_one──▶ Payment
   │                              │                   │                   │
   │ token                        │ order_number      │ payment_request   │ preimage
   │ amount_cents                 │ total_amount_sats │ payment_hash      │ amount_sats
   │ customer_*                   │ items (jsonb)     │                   │ btc_fiat_price
   │ payment_method               │ metadata (jsonb)  │                   │ fiat_variance
   │ success_url / cancel_url     │                   │                   │ confirmed_at
   │ expires_at (15 min)          │                   │ expires_at        │
   │                              │                   │                   │
   └─ UI session (disposable)     └─ Business record  └─ Network request  └─ Settlement proof
                                     (permanent)        (per attempt)       (immutable)
```

## Why Four Tables?

Each table captures a distinct stage with a different lifecycle:

| Table | Purpose | Lifecycle |
| --- | --- | --- |
| **CheckoutSession** | Temporary UI session. Captures customer intent and info before any money is involved. Expires in 15 minutes. | Disposable |
| **Order** | Permanent business record. The merchant's receipt — tied to items, amounts, and a wallet. Feeds reports, dashboards, and refunds. | Permanent |
| **Invoice** | Payment-network request. Holds the BOLT-11 string (Lightning) plus confirmation tracking. One Order may need a new Invoice if the first expires. | Per attempt |
| **Payment** | Proof of settlement. Records the exact BTC/fiat price at confirmation, the preimage, and calculates price variance. | Immutable |

> **Key insight:** Separating Invoice from Order allows a single Order to survive invoice expiration. If a Lightning invoice expires after 1 hour, a new Invoice can be generated for the same Order with an updated BTC price — without losing the order context.

## Entry Points

Three ways to start a checkout, one unified flow:

###### API

`POST /api/v1/checkout_sessions`

Server-side integration. Returns checkout_url to redirect customer.

###### Payment Link

`GET /pay/:slug`

Zero-code. Share a URL via email, social media, or QR code.

###### Embed Button

`data-key="pk_live_..."`

JavaScript widget. Opens checkout overlay from any webpage.

All three converge at the same CheckoutController, entering the 3-step pipeline below.

## Step-by-Step Data Flow

##### 1. Session Created

API, payment link, or embed widget creates a CheckoutSession. Customer is redirected to the checkout page.

WRITE: `checkout_sessions`

token, amount_cents, currency, merchant_id, product_id, success_url, cancel_url, metadata, expires_at

##### 2. Collect Customer Info optional

If the merchant requires customer info collection and it was not pre-filled via API, the customer fills out a form.

WRITE: `checkout_sessions`

customer_email, customer_name, customer_phone, customer_address

##### 4. Order + Invoice Created

On the first visit to the QR code page, the system creates an Order, links it to the session, converts the fiat amount to sats at the current BTC price, and generates an Invoice with a BOLT-11 payment request.

WRITE: `orders`

merchant_id, wallet_id, total_amount_cents, total_amount_sats, items, metadata, status = pending

WRITE: `checkout_sessions`

order_id = new order

WRITE: `invoices`

payment_request, payment_hash, amount_sats, expires_at

##### 5. QR Code + Monitoring

The checkout page displays a QR code. Background jobs begin polling for payment:

PaymentMonitorJob polls every 5 seconds (up to 15 minutes).

The checkout page listens on WebSocket (ActionCable) for instant updates, with HTTP polling every 5 seconds as fallback.

##### Payment Confirmed

When a background job detects settlement:

WRITE: `invoices`

status = paid, paid_at

WRITE: `orders`

status = paid

WRITE: `payments`

amount_sats, preimage, btc_fiat_price, fiat_value, fiat_variance, confirmed_at

WRITE: `checkout_sessions`

status = completed

WebSocket broadcasts to checkout page, which redirects the customer to success_url. Webhooks fire asynchronously.

##### Session Expired (no payment)

If 15 minutes pass with no payment detected:

WRITE: `invoices`

status = expired

WRITE: `checkout_sessions`

status = expired

Customer is redirected to cancel_url.

## Bitcoin Conversion Fee

A merchant can add a fee of up to 3% to bitcoin payments to cover selling the sats for local currency. The price itself (`amount_cents`, `total_amount_cents`) never changes: the fee is charged on top of it and the invoice is priced at `amount_due_cents`. The hosted checkout shows it as its own line. When the fee is not zero, these fields are added so your own UI can show it too:

```
"total_amount_cents": 10000,
"conversion_fee_percent": 1.5,
"conversion_fee_cents": 150,
"amount_due_cents": 10150,
"total_amount_sats": 101500   // priced on amount_due_cents
```

Returned on orders, invoices, payment requests, checkout sessions, the checkout status poll and the order in webhook payloads. The fields are absent when the fee is zero, and on cash orders, which never carry it. A new checkout session previews the merchant's current rate; once the order exists, its own recorded rate is what the customer is charged. `GET /api/v1/m/merchant` returns the configured `conversion_fee_percent` for clients that build their own orders.

## Status Transitions

###### CheckoutSession

```
pending ──▶ completed  (paid)
pending ──▶ expired    (15 min)
pending ──▶ cancelled
```

###### Order

```
pending ──▶ invoice_generated
        ──▶ paid
        ──▶ cancelled
paid    ──▶ refunded
```

###### Invoice

```
pending ──▶ paid      (settled)
pending ──▶ expired   (TTL)
pending ──▶ cancelled
```

###### Payment

```
No status enum.
Created once on confirmation.
Immutable after creation.

Proof: preimage (Lightning)
```

## Every Database Write, In Order

| # | Trigger | Table | Operation |
| --- | --- | --- | --- |
| 1 | API call / payment link / embed | `checkout_sessions` | INSERT token, amount, currency, merchant, product, urls, metadata, expires_at |
| 2 | Customer submits info form | `checkout_sessions` | UPDATE customer_email, customer_name, customer_phone, customer_address |
| 3 | First visit to QR page | `orders` | INSERT merchant, wallet, amounts, items, metadata |
| 5 | First visit to QR page | `checkout_sessions` | UPDATE order_id = new order |
| 6 | Invoice generation | `orders` | UPDATE total_amount_sats (fresh BTC price) |
| 7 | Invoice generation | `invoices` | INSERT payment_request, payment_hash, amount_sats, expires_at |
| 8 | Background job detects payment | `invoices` | UPDATE status = paid, paid_at |
| 9 | Background job detects payment | `orders` | UPDATE status = paid |
| 10 | Background job detects payment | `payments` | INSERT amount_sats, preimage, btc_fiat_price, fiat_value, fiat_variance, confirmed_at |
| 11 | Background job detects payment | `checkout_sessions` | UPDATE status = completed |

## Ready to integrate?

Create a checkout session with a single API call.

[Checkout API →](https://www.satsrail.com/developers/) [Embed Button →](https://www.satsrail.com/developers/guides/embed/)

---

# Embed Button

> Add a Bitcoin pay button to any website with one script tag. No backend needed. Works on WordPress, Shopify, and static sites.

Source: https://www.satsrail.com/developers/guides/embed/

One script tag. Any website. Bitcoin payments.

## How It Works

Add a single `<script>` tag to your checkout page. The `pay.js` script reads the `data-*` attributes, renders a styled "Pay with Bitcoin" button, and handles the full checkout flow — no backend needed.

1. Script tag loads and renders an orange **Pay with Bitcoin** button
2. Customer clicks the button
3. Script creates a checkout session via `POST /api/v1/checkout_sessions` using your publishable key
4. Checkout page opens (embedded overlay or redirect)
5. Customer pays via Lightning QR code
6. Customer is redirected to your success URL

Two modes: **Cart checkout** (pass amount + customer data from your own checkout) or **Product button** (create a product in your dashboard, reference it by slug — price is fetched automatically).

## Integration Flows

SatsRail supports two integration patterns depending on whether you have your own checkout process or want SatsRail to handle everything.

#### Flow 1 Custom Checkout

Your site already has a cart or checkout page where you collect customer details. Pass the order amount and any customer data to SatsRail — the hosted checkout page skips the info form and goes straight to the payment QR code.

###### Via Embed Button

```
<script src="https://satsrail.com/js/pay.js"
  data-key="pk_live_..."
  data-amount="2500"
  data-currency="usd"
  data-customer-email="buyer@example.com"
  data-customer-name="Alice Smith"
  data-success-url="https://mystore.com/thanks"
  data-mode="iframe">
</script>
```

###### Via API (server-side)

```
curl -X POST https://app.satsrail.com/api/v1/m/checkout_sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_session": {
      "amount_cents": 2500,
      "currency": "usd",
      "customer_email": "buyer@example.com",
      "customer_name": "Alice Smith",
      "metadata": { "order_id": "ORD-42", "plan": "pro" },
      "success_url": "https://mystore.com/thanks",
      "cancel_url": "https://mystore.com/cart"
    }
  }'
```

> When `customer_email` is provided, the checkout page shows the payment QR immediately — no extra form step.

---

#### Flow 2 Product Button (Stripe-style)

No checkout page on your site? Create a **Product** in your SatsRail dashboard and configure which customer fields to collect in your merchant Settings (email, name, phone, shipping address). SatsRail will show a form with the selected fields before the payment QR code.

1. Create a Product in your dashboard
2. Configure which customer fields to collect in Settings
3. Embed a product button or share the Payment Link
4. Customer fills in the requested info, selects payment method, and pays
5. Customer info is stored in the order metadata

###### Embed Button

```
<script src="https://satsrail.com/js/pay.js"
  data-product="prod_abc123def456"
  data-key="pk_live_..."
  data-mode="iframe">
</script>
```

###### Payment Link

```
https://satsrail.com/pay/prod_abc123def456
```

> Customer fields are configured in your merchant Settings. Choose from email (always required), name, phone, and shipping address. The checkout page only shows the fields you selected.

## Product Button

Instead of hardcoding amounts, create a **Product** in your SatsRail dashboard (with name and price), then reference it by slug. The button fetches the price automatically and displays it.

```
<script src="https://satsrail.com/js/pay.js"
  data-product="prod_abc123def456"
  data-key="pk_live_..."
  data-mode="iframe">
</script>
```

The button will show **"Pay $25.00 with Bitcoin"** (or whatever the product price is). Override the label with `data-label` if needed.

## Payment Links

Need something even simpler? Every product has a **shareable payment link** — a URL you can paste anywhere. No code, no API keys, no website required.

```
https://satsrail.com/pay/prod_abc123def456
```

Share via email, WhatsApp, social media, or print as a QR code. When someone opens the link, a checkout session is created automatically and they see the payment page with QR code and countdown timer.

## Data Attributes

| Attribute | Required | Description |
| --- | --- | --- |
| `data-key` | Yes | Publishable key (`pk_live_` or `pk_test_`) |
| `data-product` | No* | Product slug (e.g. `prod_abc123`). If set, amount and currency are fetched automatically from the product. |
| `data-amount` | No* | Amount in cents (e.g. 5000 = $50.00). Required if `data-product` is not set. |
| `data-currency` | No | Currency code, default `"usd"` |
| `data-success-url` | No | Redirect URL after payment |
| `data-cancel-url` | No | Redirect URL on cancel |
| `data-label` | No | Button text, default `Pay with Bitcoin ⚡` |
| `data-mode` | No | `iframe` (embedded overlay), `new_tab`, or `redirect`. If omitted, uses your merchant Settings. |
| `data-customer-email` | No | Pre-fill customer email. Skips the info collection form on the checkout page. |
| `data-customer-name` | No | Pre-fill customer name. |
| `data-customer-phone` | No | Pre-fill customer phone number. |
| `data-customer-address` | No | Pre-fill customer shipping address. |

## Full Example

##### Amount Mode

Hardcode the price directly in the script tag:

```
<!DOCTYPE html>
<html>
<body>
  <h1>Buy Coffee Beans — $25.00</h1>

  <!-- The button is rendered automatically -->
  <script src="https://satsrail.com/js/pay.js"
    data-key="pk_live_..."
    data-amount="2500"
    data-currency="usd"
    data-success-url="https://mystore.com/thanks"
    data-cancel-url="https://mystore.com/cart"
    data-mode="iframe">
  </script>
</body>
</html>
```

##### Product Mode

Reference a product — price is fetched automatically:

```
<!DOCTYPE html>
<html>
<body>
  <h1>Buy Coffee Beans</h1>

  <!-- Button shows "Pay $25.00 with Bitcoin" automatically -->
  <script src="https://satsrail.com/js/pay.js"
    data-product="prod_abc123def456"
    data-key="pk_live_..."
    data-mode="iframe">
  </script>
</body>
</html>
```

## Button Styling

The script auto-creates a `<button>` element with the `.satsrail-pay-btn` class and a built-in orange gradient style. Override it with your own CSS:

```
.satsrail-pay-btn {
  background: #333 !important;
  border-radius: 0 !important;
  font-family: monospace !important;
}
```

- Default: orange/amber gradient, rounded corners, white text, hover lift effect
- The button is a standard `<button>` element — target `.satsrail-pay-btn` to restyle

## Embedded Mode

When `data-mode="iframe"` is set (or your merchant checkout mode is set to Embedded), the checkout page opens in an overlay iframe on your page (500×700 on desktop, full-screen on mobile). The customer never leaves your site. No popup blockers.

## Error Handling

If the checkout session fails to create (network error, invalid key, etc.), the button text changes to show the error message for 3 seconds, then reverts to the original label.

## Platform Integration

##### WordPress

Paste the script tag in your theme's `header.php` or use a plugin like "Insert Headers and Footers." Then add the button HTML in any post or page using a Custom HTML block.

##### Shopify

Add the script tag to your theme's `theme.liquid` layout. Use the button HTML in product descriptions or a custom page template.

##### Static Sites

Just paste both the script tag and button HTML into your page. That's it.

## CORS

The `/api/v1/checkout_sessions` endpoint allows wildcard CORS origins, so the embed script works from any domain without additional configuration.

## Add Bitcoin payments in 60 seconds

Copy the code above, swap in your publishable key, and you're live.

[Get Your API Key →](https://satsrail.com/users/sign_up)

---

# AI Agent Payment Flow

> Complete sequence diagram for AI agent payments via the SatsRail MCP server. Agent-initiated invoicing, programmatic payment creation, and agent-to-agent Bitcoin transactions.

Source: https://www.satsrail.com/developers/guides/flows/ai-agent/

MCP server + Lightning — AI agents that create invoices and process payments programmatically.

## Flow Overview

This diagram shows how AI agents (Claude, GPT, custom agents) use the SatsRail MCP server to programmatically create orders, generate Lightning invoices, and process payments — no browser, no forms, no redirects. The MCP server wraps the SatsRail REST API and exposes it as tool calls that any MCP-compatible agent can invoke.

## MCP Tools Available

| Tool | Description | Used In |
| --- | --- | --- |
| `create_order` | Create a payment order with optional auto-generated Lightning invoice | Phase 2 |
| `get_order` | Get order details by ID (expandable: invoice, payment, merchant) | Phase 2 |
| `list_orders` | List orders with optional status filter | Phase 4 |
| `cancel_order` | Cancel a pending order | Error recovery |
| `get_invoice` | Get invoice details including bolt11 Lightning string | Phase 2 |
| `check_invoice_status` | Real-time payment status check against the Lightning node | Phase 2, 3 |
| `generate_invoice` | Generate a new invoice for an existing order (on expiry) | Error recovery |
| `list_payments` | List confirmed payments with optional date range filter | Phase 4 |
| `get_payment` | Get payment details | Phase 4 |
| `create_checkout_session` | Create a hosted checkout session with redirect URL | Phase 3 |
| `get_merchant` | Get the current merchant's profile and settings | Phase 1 |
| `list_wallets` | List connected wallets | Phase 1 |

## Step-by-Step Detail

#### Phase 1: Setup

##### 1. Configure MCP Server

Add the SatsRail MCP server to your AI agent's configuration:

```
{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://app.satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key_here" }
    }
  }
}
```

The hosted server authenticates every request with the `sk_live_` key and exposes 45 tools to the agent.

##### 2. Agent Discovers Tools

When the MCP server starts, it connects to the SatsRail API, validates the key, and advertises all available tools (create_order, check_invoice_status, etc.) to the agent. The agent can now invoke any tool as part of a conversation.

---

#### Phase 2: Agent-Initiated Payment

##### 3. Create Order + Invoice

The agent determines a payment is needed (based on conversation context or autonomous task) and calls:

```
create_order({
  amount_cents: 2500,
  currency: "usd",
  description: "Monthly subscription",
  generate_invoice: true,
  payment_method: "lightning"
})
```

SatsRail creates an Order, converts USD → sats, generates a BOLT-11 Lightning invoice from the merchant's node (non-custodial), and returns the order with the bolt11 string.

##### 4. Present Invoice to Payer

The agent now has a BOLT-11 invoice string. Three paths:

- **Path A — Human user:** Agent presents the bolt11 string (and optionally a QR code) in the conversation. User scans with their Lightning wallet.
- **Path B — Another agent:** Agent passes the bolt11 string to another AI agent that has Lightning wallet access. The second agent pays programmatically.
- **Path C — Auto-pay:** If the agent itself has wallet access (via another MCP server or API), it pays the invoice automatically.

##### 5. Verify Payment

After payment, the agent calls `check_invoice_status` to verify:

- **completed:** Agent proceeds — confirms to user, activates service, delivers product
- **pending:** Agent waits and re-polls (e.g., every 5 seconds)
- **expired:** Agent calls `generate_invoice` to create a new invoice for the same order at the current BTC rate

---

#### Phase 3: Agent-Managed Product Sales

##### 6. Checkout Session for Products

For more complex sales, the agent calls `create_checkout_session` to generate a hosted checkout URL. The agent shares this link with the customer (in chat, email, Slack, etc.). The customer completes the payment through the standard SatsRail checkout flow. The agent polls for completion using `check_invoice_status` and confirms when paid.

---

#### Phase 4: Monitoring

##### 7. Transaction Reconciliation

The agent can query transaction history for reporting:

- `list_payments` — retrieve all payments with date range filters
- `list_orders` — check order statuses
- `get_merchant` — get merchant profile and settings

All MCP-initiated transactions are also visible in the SatsRail Dashboard, where the merchant can see agent-initiated vs manual transactions side by side.

## Error Paths

| Error | Trigger | Agent Behavior | Recovery |
| --- | --- | --- | --- |
| MCP Connection Failure | MCP server process crashes or fails to start | Agent detects tool unavailability | Retry MCP connection or fall back to direct REST API calls |
| Invalid Tool Parameters | Agent passes wrong types or missing required fields | MCP server returns structured error with field details | Agent corrects parameters and retries the tool call |
| 429 Rate Limited | Too many API calls per minute | Agent receives rate limit error | Agent implements exponential backoff before retrying |
| Invoice Expired | BOLT-11 invoice TTL exceeded (typically 1 hour) | check_invoice_status returns "expired" | Agent calls `generate_invoice` for a new invoice at current rate |
| Lightning Routing Failure | No route found to recipient node | Payer's wallet returns routing error | Retry later (channel liquidity may change) |
| Invalid API Key | sk_live_ key is wrong or revoked | MCP server answers 401 Unauthorized | Developer checks the Authorization header in the MCP config |

## Example Agent Conversation

User "Charge me $25 for the monthly subscription"

Agent *→ calls create_order(amount_cents: 2500, generate_invoice: true)*

Agent "Here's your Lightning invoice. Scan this QR code or copy the payment string:"

lnbc250u1pj...kqq5yxmetu

User "Paid!"

Agent *→ calls check_invoice_status(invoice_id: "inv_...")*

Agent "Payment confirmed! 25,000 sats received. Your subscription is now active."

User "Show me all payments this month"

Agent *→ calls list_payments(from_date: "2024-01-01")*

Agent "You received 3 payments totaling 75,000 sats ($75.00) this month."

## Build the future of AI payments

Give your AI agents the power to create invoices and process Bitcoin payments.

[AI Agents Docs →](https://www.satsrail.com/developers/guides/ai-agents/) [MCP Server](https://www.satsrail.com/mcp/)

---

# API Checkout Flow

> Complete sequence diagram for the SatsRail REST API checkout integration. Server-to-server checkout creation, hosted payment page, Lightning settlement, and webhook delivery.

Source: https://www.satsrail.com/developers/guides/flows/api-checkout/

Server-to-server integration — from checkout creation to webhook delivery.

## Flow Overview

This diagram shows the full developer integration using the SatsRail REST API. The merchant's backend creates checkout sessions server-side using the secret key ( `sk_live_` ), redirects customers to the hosted checkout page, and receives payment confirmations via signed webhooks. Funds settle directly to the merchant's Lightning wallet (non-custodial).

## API Endpoints

| Method | Endpoint | Description | Auth |
| --- | --- | --- | --- |
| POST | `/api/v1/checkout_sessions` | Create a new checkout session | `sk_live_` |
| GET | `/api/v1/checkout_sessions/{id}` | Retrieve checkout status | `sk_live_` |
| GET | `/api/v1/m/products` | List all products | `sk_live_` |
| POST | `/api/v1/m/products` | Create a product | `sk_live_` |
| GET | `/api/v1/transactions` | List transactions with filters | `sk_live_` |
| GET | `/api/v1/rates` | Current BTC/USD exchange rate | `pk_live_` or `sk_live_` |

## Step-by-Step Detail

#### Phase 1: Setup & Authentication

##### 1. Obtain API Keys

Merchant registers on SatsRail and receives two API keys:

- `pk_live_...` — Publishable key (safe for client-side/frontend)
- `sk_live_...` — Secret key (server-side only, never exposed to clients)

> The secret key must never be included in frontend code, committed to version control, or exposed in client-side requests.

##### 2. Connect Wallet & Configure Webhook

Connect a Lightning wallet via the Dashboard or API. Configure a webhook endpoint URL where SatsRail will send payment event notifications.

---

#### Phase 2: Checkout Creation

##### 3. Customer Initiates Checkout

Customer adds items to cart on the merchant's frontend, clicks "Checkout with Bitcoin." The frontend sends cart data to the merchant's backend server.

##### 4. Backend Creates Checkout Session

Merchant backend sends a POST request to SatsRail:

```
POST /api/v1/checkout_sessions
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "checkout_session": {
    "amount_cents": 5000,
    "currency": "usd",
    "customer_email": "buyer@example.com",
    "success_url": "https://store.com/success",
    "cancel_url": "https://store.com/cart",
    "metadata": { "order_id": "ORD-1234" }
  }
}
```

SatsRail validates the secret key, checks rate limits, validates the payload schema, then creates a CheckoutSession with a 15-minute TTL.

##### 5. Redirect Customer

SatsRail returns:

```
{
  "checkout_url": "https://satsrail.com/checkout/cs_abc123",
  "token": "cs_abc123",
  "status": "pending",
  "expires_at": "2024-01-15T10:15:00Z"
}
```

The merchant backend returns the checkout_url to the frontend, which redirects the customer to the SatsRail hosted checkout page.

---

#### Phase 3: Payment Execution

##### 6. Checkout Page & Payment

The SatsRail checkout page shows line items, total in USD and sats, and generates a Lightning invoice from the merchant's wallet (non-custodial). Customer pays via QR scan, copy, or WebLN.

Payment routes through Lightning and settles instantly to the merchant's wallet.

---

#### Phase 4: Post-Payment & Webhooks

##### 7. Webhook Delivery

SatsRail sends a POST to the merchant's webhook endpoint:

```
POST https://merchant.com/webhooks/satsrail
X-SatsRail-Signature: sha256=abc123...

{
  "event": "checkout.completed",
  "checkout_id": "cs_abc123",
  "payment_hash": "abc123...",
  "amount_sats": 50000,
  "amount_usd": "50.00",
  "metadata": { "order_id": "ORD-1234" },
  "timestamp": "2024-01-15T10:02:30Z"
}
```

The merchant verifies the HMAC signature using their webhook secret, processes the order, and returns 200 OK. On failure, SatsRail retries: 1 min → 5 min → 30 min → 2 hr.

##### 8. Client-Side Confirmation

Customer is redirected to the merchant's `success_url` with `checkout_id` as a query param. The merchant frontend calls `GET /api/v1/checkout_sessions/{checkout_id}` to verify the status is "completed" before showing the success page. Never trust the redirect alone — always verify server-side.

## Error Paths

| HTTP Status | Error | Trigger | Recovery |
| --- | --- | --- | --- |
| 401 | Unauthorized | Invalid or missing API key | Check sk_live_ key in Authorization header |
| 422 | Validation Error | Malformed payload, missing required fields | Check field-level error messages in response body |
| 429 | Rate Limited | Too many requests per minute | Implement backoff; check Retry-After header |
| 410 | Gone | Checkout session expired (15 min TTL) | Create a new checkout session |
| 200 | Double Payment | Idempotency check detects existing payment | Returns existing payment record (no double-charge) |
| 5xx | Webhook Failure | Merchant endpoint unreachable or returns error | SatsRail retries: 1 min → 5 min → 30 min → 2 hr |

## Build your custom checkout

One API call to create a checkout. Lightning settlement. Webhook confirmation.

[Checkout API Docs →](https://www.satsrail.com/developers/) [Webhooks Docs →](https://www.satsrail.com/developers/)

---

# Embed Widget Payment Flow

> Complete sequence diagram showing how the SatsRail embed widget (pay.js) loads, renders, creates checkout sessions, and processes Lightning payments — from script tag to settlement.

Source: https://www.satsrail.com/developers/guides/flows/embed-widget/

From `<script>` tag to Lightning settlement — every step visualized.

## Flow Overview

This diagram traces the complete lifecycle when a merchant adds the SatsRail embed widget to their website. The customer never leaves the merchant's page — checkout happens in an embedded overlay or redirect, with funds settling directly to the merchant's Lightning wallet (non-custodial).

## Step-by-Step Detail

##### 1. Merchant Website Loads

The merchant's HTML page includes a script tag:

```
<script src="https://satsrail.com/js/pay.js"
  data-product="prod_abc123"
  data-key="pk_live_..."
  data-mode="iframe"></script>
```

The browser sends a GET request to the SatsRail CDN to fetch the `pay.js` bundle.

##### 2. Script Initializes

`pay.js` reads the `data-*` attributes from the script tag:

- `data-key` — validates `pk_live_` or `pk_test_` prefix format
- `data-product` — product slug to fetch price from (or `data-amount` for direct amount)
- `data-mode` — "iframe", "new_tab", or "redirect" (default: uses merchant setting)

If the API key format is invalid, the script stops and renders an error state.

##### 3. Button Rendered

The script injects a styled **"Pay with Bitcoin ⚡"** button into the DOM at the script tag's position. The button class is `.satsrail-pay-btn` and can be styled with custom CSS.

##### 4. Customer Clicks Button

`pay.js` sends a `POST` request to `/api/v1/checkout_sessions` with:

**Payload:**

`{ product_id: "prod_abc123", publishable_key: "pk_live_...", success_url, cancel_url }`

The CORS endpoint allows wildcard origins, so this works from any merchant domain.

##### 5. SatsRail Creates Checkout Session

The API server:

1. Validates the publishable key against the merchant's API tokens
2. Looks up the product — fetches name, description, price (USD)
3. Converts USD price → sats using the real-time BTC/USD exchange rate
4. Creates a CheckoutSession record with a 15-minute expiry
5. Returns checkout_url, token, and expires_at

**Rate limiting:** API requests are throttled per key. Exceeding limits returns `429 Too Many Requests`

##### 6. Checkout Opens

Based on `data-mode`:

- **iframe:** Opens an embedded overlay on the merchant's page (500×700 on desktop, full-screen on mobile). No popup blockers.
- **redirect:** Navigates the customer's browser to the SatsRail hosted checkout page.

##### 7. Invoice Generated (Non-Custodial)

SatsRail requests a Lightning invoice from the merchant's connected wallet/node:

- SatsRail sends the sats amount to the merchant's wallet connection
- The merchant's node generates a BOLT-11 invoice
- The invoice is returned to SatsRail and stored in the Invoice record

> **Non-custodial:** SatsRail never holds customer funds. The Lightning invoice is created by the merchant's own node — payment goes directly to the merchant.

##### 8. QR Code Displayed

The checkout page renders:

- Product name and description
- Price in USD and equivalent in sats
- QR code encoding the BOLT-11 invoice
- "Copy Invoice" button for desktop wallets
- 15-minute countdown timer for invoice expiry

WebLN-enabled browsers (e.g., Alby extension) are auto-detected — the wallet prompts to pay without scanning.

##### 9. Customer Pays

Three payment paths:

- **Path A — QR Scan:** Customer opens their Lightning wallet app (Phoenix, Muun, etc.), scans the QR code, confirms the amount, and sends payment.
- **Path B — Copy & Paste:** Customer copies the BOLT-11 string, pastes into a desktop wallet, and confirms.
- **Path C — WebLN:** Browser extension wallet (Alby) auto-prompts. Customer clicks "Pay" in the extension popup.

##### Lightning Settlement (Instant)

Payment routes through Lightning Network channels and arrives at the merchant's wallet instantly. SatsRail detects settlement via:

- **Primary:** PaymentMonitorJob polls the merchant's wallet every 5 seconds
- **Secondary:** Webhook from the merchant's Lightning node (if configured)

Settlement is final and irreversible — no chargebacks.

##### Confirmation & Post-Payment

Once confirmed:

1. **Transaction logged:** timestamp, amount_sats, USD value at payment time, product_id, payment_hash, preimage
2. **WebSocket broadcast:** Checkout page receives real-time "payment confirmed" event
3. **UI updates:** Modal/page shows "Payment Confirmed ✓" with transaction details
4. **Redirect:** Customer sent to success_url (or shown confirmation if no URL configured)
5. **Webhook fired:** Async POST to merchant's webhook URL with full payment payload

## Error Paths

| Error | Trigger | User Experience | Recovery |
| --- | --- | --- | --- |
| Invalid API Key | `pk_live_` format check fails or key not found in database | Script renders error state — no checkout button shown | Merchant must fix the data-key attribute |
| Product Not Found | Product slug doesn't match any active product | Button shows error message for 3 seconds, then reverts | Merchant verifies product slug in dashboard |
| Invoice Expired | 15-minute countdown reaches zero before payment | Modal shows "Expired" message | Customer clicks "Generate New Invoice" — new invoice at updated BTC rate |
| Lightning Routing Failure | No route found to merchant's node, insufficient channel capacity | Error message shown on checkout page | Customer retries (may succeed with different routing) |
| Network Timeout | API request from pay.js fails (DNS, connectivity) | Button shows "Connection error" briefly | pay.js retries with exponential backoff: 1s → 2s → 4s → 8s (max 3 retries) |
| Session Creation Failed | Server error (500) or validation error (422) | Button shows error message | Customer clicks button again to retry |

## Security Architecture

###### Publishable Key Only

The embed widget uses `pk_live_` (publishable key) — safe to expose in client-side HTML. The secret key `sk_live_` is never used in the widget.

###### Non-Custodial

SatsRail never holds merchant funds. Lightning invoices are generated by the merchant's own node. Payments flow directly from customer → merchant.

###### CORS Enabled

The `/api/v1/checkout_sessions` endpoint allows wildcard CORS origins, so the widget works from any domain without configuration.

###### HTTPS Only

All communication between pay.js and SatsRail API is over TLS. The CDN serves the script via HTTPS with SRI integrity hashes.

## Add Bitcoin payments in 60 seconds

One script tag. No backend. Non-custodial Lightning payments.

[Embed Button Docs →](https://www.satsrail.com/developers/guides/embed/) [Checkout API →](https://www.satsrail.com/developers/)

---

# Payment Link Flow

> Complete sequence diagram for the no-code Payment Link flow. Merchant creates a product, shares a link, and customers pay via Lightning — no coding required.

Source: https://www.satsrail.com/developers/guides/flows/payment-link/

No code. Create a product, share a link, get paid in Bitcoin.

## Flow Overview

The Payment Link is the simplest SatsRail integration — zero code. A merchant creates a product in the dashboard, gets a shareable URL ( `satsrail.com/pay/your-product` ), and distributes it anywhere. When a customer opens the link, a checkout session is auto-created and they pay via Lightning. Funds settle directly to the merchant's wallet.

Every active product has one. Merchants make and share them on the dashboard's Payment Links page; in the API, every product carries its link as `payment_link_url` (null while the product is inactive), and `POST /api/v1/m/products` needs only a name and a price. AI agents use the MCP tool `create_payment_link`.

## Step-by-Step Detail

#### Merchant Setup

##### 1. Log In & Create Product

The merchant logs into the SatsRail Dashboard and navigates to Products → Create Product. They fill in:

- **Product name:** displayed on the checkout page (e.g., "Monthly Subscription")
- **Description:** shown below the product name
- **Price (USD):** the fiat amount to charge (converted to sats at payment time)
- **Image:** optional product image displayed on checkout

##### 2. Connect Lightning Wallet

The merchant connects their Lightning wallet to receive payments directly. Supported connection methods:

- **LNDHub:** Compatible with BlueWallet, Zeus, and others
- **LNURL:** Universal Lightning address (e.g., user@wallet.com)
- **Connection string:** Direct LND/CLN node connection

> **Non-custodial:** SatsRail connects to the merchant's wallet but never has access to funds. Payments go directly from customer → merchant.

##### 3. Get Payment Link

SatsRail generates a unique product slug and payment link:

```
https://satsrail.com/pay/prod_abc123def456
```

The dashboard also provides:

- **QR code:** downloadable QR code encoding the payment link URL
- **Embed snippet:** `<script>` tag for embedding a pay button on any website

##### 4. Distribute the Link

The merchant shares the payment link through any channel:

- **Email / SMS:** Paste the URL directly
- **Social media:** Post on Twitter, Instagram, etc.
- **WhatsApp / Telegram:** Share in chat
- **Printed QR:** Print the QR code for in-store or event use
- **Website:** Add as a simple hyperlink

---

#### Customer Payment

##### 5. Customer Opens Link

Customer clicks the link or scans the QR code. The browser navigates to `satsrail.com/pay/prod_abc123`. SatsRail looks up the product by slug, validates it's active, and auto-creates a CheckoutSession. The customer is redirected to the checkout page.

##### 6. Customer Info

If the merchant configured customer info collection:

- Customer fills in email, name, phone, and/or shipping address (as configured)

If no customer fields are configured, this step is skipped entirely — straight to QR code.

##### 7. Invoice Generated & QR Displayed

SatsRail converts USD → sats at the real-time exchange rate, requests a Lightning invoice from the merchant's wallet, and displays:

- Product name, description, and image
- Price in USD and sats
- QR code encoding BOLT-11 invoice
- Copy button for desktop wallets
- 15-minute countdown timer

##### 8. Customer Pays via Lightning

Customer scans the QR with their wallet app, copies the invoice to a desktop wallet, or pays via WebLN browser extension. Payment routes through Lightning channels and settles instantly to the merchant's wallet.

##### Confirmation

The checkout page updates to show "Paid ✓". Based on configuration:

- Redirect to merchant's custom success URL
- Show a receipt with transaction details
- Trigger digital delivery (download link, license key, etc.)

Webhooks fire asynchronously if configured. Transaction is logged in the merchant's dashboard with amount, timestamp, exchange rate, and payment hash.

## Error Paths

| Error | Trigger | User Experience | Recovery |
| --- | --- | --- | --- |
| 404 Not Found | Product slug doesn't exist or product is deactivated | Customer sees a "Product not found" error page | Merchant reactivates product or shares correct link |
| Wallet Disconnected | Merchant's Lightning wallet connection is broken or expired | Customer sees "Merchant cannot receive payments at this time" | Merchant reconnects wallet in Dashboard settings |
| Invoice Expired | 15-minute countdown reaches zero | Checkout shows "Expired" with option to regenerate | Customer clicks "Generate New Invoice" — new rate applied |
| Routing Failure | No Lightning route to merchant's node | Error shown on checkout page | Customer retries payment |

## Start selling with a link

Create a product, share the URL, and accept Bitcoin — zero code required.

[Embed Button Docs →](https://www.satsrail.com/developers/guides/embed/) [Embed Widget Flow →](https://www.satsrail.com/developers/guides/flows/embed-widget/)

---

# Integrate Your POS

> Accept Lightning payments in your existing Android, desktop, or web POS. Request an invoice, display a QR code, and confirm payment while keeping orders in your own system.

Source: https://www.satsrail.com/developers/guides/pos/

POS INTEGRATION

Add Lightning payments to your existing Android, desktop, or web POS.
Send an amount, display an invoice, and confirm payment.

## Keep your existing checkout

Your POS owns the cart, taxes, inventory, customer details, and receipts. SatsRail requests an invoice from the merchant's wallet provider and verifies settlement. The customer pays the merchant directly.

### Your POS

Calculate the total, associate the invoice with your sale, show the QR code, and issue the receipt after confirmation.

### SatsRail

Request the Lightning invoice, monitor settlement, and return payment status. Funds go directly to the merchant's wallet.

No catalog import or basket data is required. SatsRail creates a minimal internal order with a generic “Payment” line item to support the payment record. Your POS remains the source of truth for the sale.

## Before you start

Activate your merchant account, connect a compatible Lightning Address with payment verification, and configure your merchant currency. Create a secret API key with permission to create payment requests and read invoice status.

For an Android app, keep the `sk_live_...` key on your backend. Authenticate the terminal to your backend and let the backend call SatsRail. Publishable `pk_...` keys cannot call the payment endpoints below. Do not bundle a merchant secret key into the APK.

Recommended connection

Android POS → your backend → SatsRail → merchant wallet provider

Invoice and status responses travel back to the POS through your backend. The customer pays the merchant's invoice from their own Lightning wallet.

## 1. Request a payment

Calculate the final total in your POS, including any tax or tip. Make this request from your backend:

```
curl --request POST 'https://app.satsrail.com/api/v1/m/payment_requests' \
  --header "Authorization: Bearer $SATSRAIL_SECRET_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pos-payment-7f982e41' \
  --data '{
    "payment_request": {
      "amount_cents": 2500,
      "payment_method": "lightning"
    }
  }'
```

`amount_cents` is in the merchant's configured currency: for a USD merchant, `2500` means $25.00. This endpoint does not accept a per-request currency. SatsRail calculates the invoice amount in sats.

A successful request returns HTTP `201`. Example response (the invoice string is abbreviated):

```
{
  "object": "payment_request",
  "id": "4e14d219-5321-4b64-a1d3-830d11d60945",
  "payment_method": "lightning",
  "amount_sats": 25000,
  "payment_request": "lnbc...",
  "payment_hash": "...",
  "created_at": "2026-09-22T12:00:00Z",
  "expires_at": "2026-09-22T12:15:00Z"
}
```

The returned `id` is the invoice ID. Persist its association with your local sale before showing the QR code:

```
your_sale_id → satsrail_invoice_id
```

Also save the invoice string, expiry, and the idempotency key for that payment attempt. Keep your sale reference in your own database; you do not need to send it to SatsRail.

## 2. Display the invoice

Return the payment details to Android and encode the exact `payment_request` string as a QR code. Show the amount and a countdown based on `expires_at`. The customer scans the QR with their Lightning wallet.

Use the invoice returned for this sale, rather than a static Lightning Address QR. Each invoice gives your POS a specific payment to track. Displaying or scanning the QR does not mean the sale has been paid.

## 3. Confirm payment

While the payment screen is open, have your backend check the invoice status. Start with a five-second interval, adjust to your API limits, and share one check across clients watching the same invoice.

```
curl 'https://app.satsrail.com/api/v1/m/invoices/4e14d219-5321-4b64-a1d3-830d11d60945/status' \
  --header "Authorization: Bearer $SATSRAIL_SECRET_KEY"
```

This endpoint checks settlement server-side. Relevant fields from a paid response:

```
{
  "status": "paid",
  "paid": true,
  "expired": false,
  "paid_at": "2026-09-22T12:00:18Z",
  "expires_at": "2026-09-22T12:15:00Z",
  "payment_method": "lightning"
}
```

Only when `paid` is `true`, mark your local sale paid and issue the receipt. Make that update idempotent: repeated status responses must not fulfill the sale twice. A paid response also includes payment details beyond the fields shown here.

## Handle interruptions

- **App restart or lost connection**: Load the saved invoice ID and check its status again. SatsRail monitors payment independently of the terminal. A network error means the status is unknown; it does not mean the customer failed to pay.
- **Invoice expiry**: Remove the expired QR and check status before offering a new payment attempt. Late confirmation can still arrive. Retain earlier invoice IDs and reconcile them against the sale so a late payment is not lost or fulfilled twice.
- **Retrying invoice creation**: Generate a unique `Idempotency-Key` for each payment attempt and reuse it with the same payload on retries. Successful responses are cached for 24 hours. Serialize creation per sale in your backend: this cache does not guarantee deduplication of concurrent requests, failed requests, or retries after cache loss. An ambiguous timeout needs reconciliation before creating another payment attempt.
- **API errors**: Check `error.code` and `error.message` on non-success responses. Correct authentication or permission failures (`401`/`403`), inspect validation or wallet errors (`422`), and back off on `429`, honoring `Retry-After` when supplied. Do not show a payment QR until you have a successful invoice response.

## Optional: receive payment notifications

Your backend can subscribe to `payment.received` webhooks and relay updates to Android. Verify webhook signatures and deduplicate events before updating a sale. Keep invoice-status checks for reconnects and recovery.

SatsRail also offers `OrderStatusChannel` over ActionCable. It requires SatsRail's internal order ID, which the payment-request creation response does not expose. The invoice-status endpoint above is the simplest starting point for this integration.

## Build your payment screen

Exercise pending payment, confirmed payment, expiry, repeated responses, and reconnecting to an existing invoice before using the integration at the counter.

[API reference](https://www.satsrail.com/developers/) [Account setup](https://www.satsrail.com/developers/guides/quickstart/)

---

# Quickstart Guide

> Go from zero to accepting Bitcoin payments in under 10 minutes. Step-by-step guide with code examples for Node.js, Python, and Ruby.

Source: https://www.satsrail.com/developers/guides/quickstart/

From zero to accepting Bitcoin in under 10 minutes.

### 1. Create Your Account

Sign up for a free SatsRail merchant account. No bank approval, no credit checks.

[Create Account →](https://satsrail.com/users/sign_up)

### 2. Get Your API Keys

From your merchant dashboard, go to **API Keys** to find your keys:

- **Secret key** — starts with `sk_live_` or `sk_test_` (keep this server-side, never expose to clients)
- **Publishable key** — starts with `pk_live_` or `pk_test_` (safe for client-side, can only create checkout sessions)

> **⚠️ Start with test keys.** Use `sk_test_` keys during development. They create isolated test data that never touches real payment providers.

### 3. Install an SDK

Pick your language:

```
# Node.js
npm install satsrail

# Python
pip install satsrail

# Ruby
gem install satsrail
```

Or skip the SDK and use the REST API directly with curl.

### 4. Create Your First Order

###### curl

```
curl -X POST https://app.satsrail.com/api/v1/m/orders \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 50.00,
    "description": "Order #1234"
  }'
```

###### Node.js

```
import SatsRail from 'satsrail';

const sr = new SatsRail('sk_test_...');
const order = await sr.orders.create({
  amount_usd: 50.00,
  description: 'Order #1234'
});
console.log(order.lightning_invoice);
```

###### Python

```
import satsrail

sr = satsrail.Client("sk_test_...")
order = sr.orders.create(
    amount_usd=50.00,
    description="Order #1234"
)
print(order.lightning_invoice)
```

###### Ruby

```
require "satsrail"

SatsRail.api_key = "sk_test_..."
order = SatsRail::Order.create(
  amount_usd: 50.00,
  description: "Order #1234"
)
puts order.lightning_invoice
```

### 5. Listen for Webhooks

Set up a webhook endpoint to get notified when payments complete, orders update, and more. SatsRail signs every webhook with HMAC-SHA256 so you can verify authenticity.

[Webhook Guide →](https://www.satsrail.com/developers/)

### 6. Go Live

When you're ready for production, swap your test keys for live keys:

- Replace `sk_test_` with `sk_live_`
- Replace `pk_test_` with `pk_live_`

That's it. Same code, real payments.

## Ready to build?

Create a free account and start integrating today.

[Get Your API Key →](https://satsrail.com/users/sign_up)

---

# Testing

> Learn how to use SatsRail's test mode to build and test your integration without real payments. Fully isolated test environment with simulated Lightning invoices.

Source: https://www.satsrail.com/developers/guides/testing/

Build with confidence using fully isolated test data.

## Test Mode Overview

Every SatsRail merchant gets two sets of API keys: live and test. Keys prefixed with `sk_test_` and `pk_test_` create resources in a completely isolated test environment.

> **💡 No special test card numbers needed.** Lightning invoices in test mode are fully simulated — they complete automatically so you can test your entire flow without spending real sats.

## Test vs. Live Data Isolation

SatsRail enforces strict separation between test and live data:

|   | Test Mode | Live Mode |
| --- | --- | --- |
| **Key prefix** | `sk_test_ / pk_test_` | `sk_live_ / pk_live_` |
| **Data access** | Only test resources | Only live resources |
| **Payment providers** | Simulated (no real payments) | Real Lightning / Bitcoin |
| **Webhooks** | Fired for test events only | Fired for live events only |

This is enforced at the model level via `LiveModeScoped` — test resources never interact with real payment providers, and a test key can never read or modify live data (and vice versa).

## How to Get Test Keys

1. Log in to your merchant dashboard
2. Navigate to **API Keys**
3. Toggle **Test Mode** on
4. Copy your `sk_test_` secret key and `pk_test_` publishable key

Test keys are available immediately — no approval needed.

## What You Can Test

Use test keys to exercise every part of your integration:

- **Checkout Sessions** — Create sessions, test embedded/redirect flows, verify success/cancel URLs
- **Orders** — Create, list, and retrieve orders; watch status transitions
- **Invoices** — Generate invoices and see them auto-complete in test mode
- **Payments** — Simulated payments appear with realistic data and status updates
- **Webhooks** — Receive webhook events for test resources on your test webhook endpoints

When everything works in test mode, switch to live keys — the API is identical.

## Start testing now

Follow the quickstart to get your test keys and make your first API call.

[Quickstart Guide →](https://www.satsrail.com/developers/guides/quickstart/)