---
name: orionpay-api-bootstrap
description: >-
  Bootstrap guide for AI coding assistants building an OrionPay integration from scratch. Use when
  you have (or are asked to obtain) an OrionPay personal API key and need to create a product, its
  product API key and its webhook by code, charge buyers with PIX, verify webhook signatures and
  deliver or revoke access. Covers POST /api/v1/personal/products (request, response, replay,
  error codes), POST /api/v1/pix/generate, HMAC verification in Node and Python, event semantics,
  limits, and what still requires the dashboard.
---

# OrionPay API bootstrap — from a personal key to the first sale

This guide is written for an AI coding assistant (and the developer supervising it) that has to wire
up OrionPay sales end to end. It covers the shortest correct path. For every other endpoint, field
and event, the full references are:

- https://pay.orion.moe/llms-full.txt — full reference inlined for LLM context (every endpoint and webhook event).
- https://pay.orion.moe/docs — public API docs (also `https://payapi.orion.moe/openapi.json`).

This file is published at https://pay.orion.moe/skill.md. In Claude Code, install it as
`~/.claude/skills/orionpay-api-bootstrap/SKILL.md`.

**Base URL:** `https://payapi.orion.moe` · **Content type:** `application/json` · **Amounts:** BRL
reais as JSON numbers (e.g. `49.9`).

---

## 1. Mental model

**Two kinds of API key.** Both look like `opay_` + 64 hex chars and go in the `X-API-Key` header
(`Authorization: Bearer opay_…` also works).

| Key | Belongs to | Used for |
|---|---|---|
| **Personal key** | the account (one per account) | `/api/v1/personal/*` — including **creating products**, balances, withdrawals |
| **Product key** | one product (one per product) | selling that product: `POST /api/v1/pix/generate`, buyer/access endpoints |

The product is always derived from the product key; there is no `productId` field when charging.
Calling an endpoint with the wrong kind of key fails with 403/400.

**Product lifecycle.** A product is `DRAFT`, `PUBLISHED` or `ARCHIVED` (archived in the dashboard). Only a `PUBLISHED` product can be charged
with `pix/generate`. Publishing is also what creates its checkout link (`/p/<slug>`), which only works
— and is only returned — when the product has a fixed price.

**Money vs. access.** A PIX payment produces several webhook events. `access.granted` means the buyer
may access the product; `payment.success` means the payment settled. They can be hours apart (see
[section 8](#8-event-semantics)).

---

## 2. Bootstrap in 5 steps

1. **Human, once:** create the personal key at https://pay.orion.moe/dashboard/api-webhooks (requires
   an activated business account). This is the **only** manual step. Store it as a secret, e.g.
   `ORION_PERSONAL_API_KEY`. Never ask the user to paste it into source code.
2. **Provision:** `POST /api/v1/personal/products` with the personal key, an `externalReference` and a
   `webhook` → you get the product, its checkout link, the **product key** and the **webhook secret**
   ([section 3](#3-provision-the-product)).
3. **Store the credentials** returned: `apiKey.key` and `webhook.secret` ([section 4](#4-store-the-credentials)).
4. **Receive webhooks:** deploy an HTTPS endpoint at the `webhook.url` you registered that verifies
   `X-Webhook-Signature` over the raw body ([section 7](#7-verify-webhook-signatures)). It must be
   reachable before the first sale.
5. **Sell:** `POST /api/v1/pix/generate` with the **product key**, show the PIX code to the buyer, and
   deliver/revoke based on events ([sections 5](#5-charge-a-buyer), [8](#8-event-semantics), [9](#9-delivering-the-product)).

---

## 3. Provision the product

`POST /api/v1/personal/products` — **personal key only**. When the call creates a new product, a
failure in a later step (publishing, key, webhook) normally removes everything it created before the
error is returned. (Exception: a call that outlives its 60-second provisioning lock is not rolled
back.) A [replay](#response--200-replay) that fails part-way keeps the steps it already completed. In
every case, retrying with the same `externalReference` finishes the rest.

### Request

```bash
curl -X POST "https://payapi.orion.moe/api/v1/personal/products" \
  -H "X-API-Key: $ORION_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Curso X",
    "productType": "CURSO_ONLINE",
    "description": "Curso completo de X",
    "price": 49.90,
    "externalReference": "sku-123",
    "webhook": {
      "url": "https://shop.example.com/orion/webhook",
      "events": ["purchase.created", "access.granted", "payment.success",
                 "payment.under_review", "payment.refund_pending",
                 "payment.refunded", "payment.refunded_med"]
    }
  }'
```

Fields (anything not listed here, at any level, is rejected with `400 INVALID_FIELD` naming the field
— do not send `metadata`, `thumbnailUrl`, `status`, `slug`, etc.):

| Field | Type | Rules |
|---|---|---|
| `title`* | string | 1–191 chars, trimmed |
| `productType`* | string | one of `CURSO_ONLINE`, `FOTOS`, `ARQUIVOS`, `AREA_MEMBROS`, `TELEGRAM_CHANNEL`, `CONSULTORIA`, `MENTORIA` |
| `description` | string | ≤ 5000 chars |
| `price` | number | JSON number, finite, ≥ 0, ≤ 2 decimals, ≤ 9999999999999.99. `0`/absent = no fixed price ([section 6](#6-products-without-a-fixed-price)). If > 0 it must reach the platform's minimum PIX charge, else `400 MIN_PIX_ORDER_AMOUNT` |
| `hideFromMarketplace` | boolean | default `true` (not listed in the public marketplace) |
| `publish` | boolean | default `true`; `false` leaves the product `DRAFT` (not sellable) |
| `externalReference` | string | 1–100 chars, `^[A-Za-z0-9._:-]+$`, case-sensitive; your id for this product — **always send it** so retries are safe. Not a secret |
| `delivery` | object | only for `AREA_MEMBROS`: `{ "accessUrl"*: "https://…" (≤ 2048), "accessInstructions": "…" (≤ 5000) }`; only for `TELEGRAM_CHANNEL`: `{ "channelLink"*: "https://…" (≤ 2048), "joinInstructions": "…" (≤ 5000) }`; any other type → 400 |
| `webhook` | object | `url`* (public HTTPS with a domain name, ≤ 2048 chars; no IP literal, no localhost/private host); `events` (non-empty array of product events or `["*"]`, default `["purchase.created","access.granted","payment.success"]`); `name` (1–255, default `"Default"`); `secret` (32–128 chars, generated if absent) |

Valid webhook events: `purchase.created`, `payment.received`, `payment.success`, `access.granted`,
`payment.under_review`, `payment.refund_pending`, `payment.refunded`, `payment.refunded_med`,
`med.created`, `*`. The default list has **no refund events** — include them (as in the example) or
use `["*"]`.

```js
// Node 18+ — provisioning with safe retry on transient errors
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function provisionProduct(input) {
  if (!input.externalReference) throw new Error("externalReference is required for safe retries");
  for (let attempt = 1; attempt <= 5; attempt++) {
    let res;
    try {
      res = await fetch("https://payapi.orion.moe/api/v1/personal/products", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.ORION_PERSONAL_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(input),
        signal: AbortSignal.timeout(30_000),
      });
    } catch (networkError) {
      // network error or timeout: outcome unknown — resend the same body (same externalReference)
      await sleep(2000 * attempt);
      continue;
    }
    const body = await res.json().catch(() => ({}));
    if (res.status === 201 || res.status === 200) return body; // body.replayed tells which
    if (res.status === 429 && !body.code) {
      // request throttle (10/hour per key): retrying within seconds only burns more of the quota
      throw Object.assign(new Error("OrionPay rate limit (10 requests/hour per key): retry in a few minutes"), { status: 429, body });
    }
    const retryable = res.status >= 500 || body.code === "PROVISIONING_IN_PROGRESS";
    if (!retryable) throw Object.assign(new Error(body.message), { status: res.status, code: body.code, body });
    await sleep(2000 * attempt);
  }
  throw new Error("OrionPay provisioning did not complete — retry later with the same externalReference");
}
```

### Response — 201 Created

```json
{
  "success": true,
  "replayed": false,
  "product": {
    "id": 123,
    "title": "Curso X",
    "description": "Curso completo de X",
    "productType": "CURSO_ONLINE",
    "price": 49.9,
    "status": "PUBLISHED",
    "hideFromMarketplace": true,
    "externalReference": "sku-123",
    "createdAt": "2026-09-15T12:00:00.000Z"
  },
  "paymentLink": {
    "slug": "3f9c…",
    "url": "https://pay.orion.moe/p/3f9c…"
  },
  "apiKey": {
    "id": 456,
    "key": "opay_<64 hex>",
    "name": "Curso X",
    "createdAt": "2026-09-15T12:00:00.000Z"
  },
  "webhook": {
    "id": 789,
    "name": "Default",
    "url": "https://shop.example.com/orion/webhook",
    "events": ["purchase.created", "access.granted", "payment.success",
               "payment.under_review", "payment.refund_pending",
               "payment.refunded", "payment.refunded_med"],
    "isActive": true,
    "secret": "<hex>"
  }
}
```

- `paymentLink` is `null` when the product has no fixed price or is not `PUBLISHED`.
- `apiKey` is always present on a `201`.
- `webhook` is `null` when no webhook was requested (and the product has none).
- `product.price` is a JSON number (`0` if you sent `0`), or `null` when `price` was omitted.

### Response — 200 replay

Sending the same `externalReference` again (same account) does **not** create a duplicate. It returns
`200` with the same shape and `"replayed": true`, containing what is stored:

```json
{
  "success": true,
  "replayed": true,
  "product": { "id": 123, "title": "Curso X", "description": "Curso completo de X", "productType": "CURSO_ONLINE", "price": 49.9, "status": "PUBLISHED", "hideFromMarketplace": true, "externalReference": "sku-123", "createdAt": "2026-09-15T12:00:00.000Z" },
  "paymentLink": { "slug": "3f9c…", "url": "https://pay.orion.moe/p/3f9c…" },
  "apiKey": { "id": 456, "key": "opay_<64 hex>", "name": "Curso X", "createdAt": "2026-09-15T12:00:00.000Z" },
  "webhook": { "id": 789, "name": "Default", "url": "https://shop.example.com/orion/webhook", "events": ["purchase.created", "access.granted", "payment.success", "payment.under_review", "payment.refund_pending", "payment.refunded", "payment.refunded_med"], "isActive": true, "secret": "<hex>" }
}
```

A replay also **completes missing steps**: creates the product key if there is none (e.g. it was
deleted), creates the webhook if you request one and the product has none, and publishes the product
if `publish` is `true` and it is still `DRAFT`. It never unpublishes and never applies other changed
fields (title, price, description…) — those are edited in the dashboard. An `ARCHIVED` product is not
republished: the replay returns it with `status: "ARCHIVED"` and `paymentLink: null`.

**`apiKey` is `null` on a replay when the product key was disabled or expired in the dashboard** —
manage it there (a product has at most one key, so the replay does not create another). Handle
`apiKey: null` instead of assuming the object is always present.

A replay fails with `409 PRODUCT_REFERENCE_EXISTS` (body includes `productId`) only if the request
conflicts with the stored product: a different `productType`, or a `webhook.url` different from the
webhook the product already has (if the product has no webhook, the requested one is created).

**MCP:** the same operation is the MCP tool `personal_create_product` on
`https://payapi.orion.moe/mcp` (authenticate with the personal key in `X-API-Key`). Its input `body` is
the JSON above and it returns the same object. A failed call surfaces only the message text. Errors
specific to this endpoint end with the code in parentheses (e.g. `(INVALID_FIELD)`); authentication
failures come back as a JSON-RPC error and unexpected errors as plain text with no code — treat them
as 401 and 5xx respectively (a 5xx is retryable with the same `externalReference`).

---

## 4. Store the credentials

- `apiKey.key` is a **product key**: whoever has it can charge buyers for this product and read its
  buyers. `webhook.secret` is the key that authenticates webhooks. Treat both like passwords: secret
  manager or environment variables, never in source control, logs, client-side code or error messages.
- The personal key is more powerful still (it can create products and, if enabled, withdraw funds).
  Keep it on the server only, and only where provisioning runs.
- If you lose the values, a replay with the same `externalReference` returns them again (except a
  product key that was disabled or expired in the dashboard: `apiKey` then comes back `null`).
- The account owner receives a **security e-mail** for every product created through the API (product,
  product key id and webhook host — never the key or the secret).

---

## 5. Charge a buyer

`POST /api/v1/pix/generate` with the **product key**. The product must be `PUBLISHED`.

Body: `name`* (string), `email`* (email), `cpf` — the payer's CPF/CNPJ, required for totals of
R$10.00 or more unless you send `euid` (the payer's DePix EUID) instead; below R$10.00 it is optional,
and if sent it is validated but not forwarded (the QR is not locked to it). Optional: `amount` (≥ 0.01;
takes priority over the product's fixed price), `phone`, `ipAddress`. (`description` is accepted but
ignored: the charge is always described as `Venda de produto: <title>`.)

```bash
curl -X POST "https://payapi.orion.moe/api/v1/pix/generate" \
  -H "X-API-Key: $ORION_PRODUCT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria@example.com",
    "cpf": "52998224725"
  }'
```

**Response 200:**
```jsonc
{ "success": true, "data": {
  "purchaseId": 1234, "productId": 123, "productTitle": "Curso X",
  "id": "01a1b2c3…",                  // deposit id (32 hex chars) — store it with purchaseId (see below)
  "pixCode": "00020126…6304ABCD",     // copia-e-cola — show it (render your own QR from it)
  "qrCode": "https://…/qr/pix/…",     // URL of a PNG of the same QR (not base64); HTTP 410 once the QR expires; may be absent
  "amount": 49.9, "expiresAt": "2026-09-15T12:15:00.000Z", "status": "created", // provider status
  "coProducers": []
}}
```

Store `data.purchaseId` and `data.id` against your order, and **match product webhooks on
`data.purchaseId`** (present in every event of [section 8](#8-event-semantics)). `data.transactionId` equals this deposit `id`
only on `purchase.created`, `payment.success` and `payment.under_review`; `payment.received`, the
refund events and `med.created` carry a numeric internal `transactionId` instead (the refund events
carry this deposit id in `data.reference`). The QR expires at `data.expiresAt` (set by the PIX provider,
usually about 15 minutes) and there is no expiration event. Called with the **personal** key → 403
`PRODUCT_KEY_REQUIRED` (don't retry: provision the product in [section 3](#3-provision-the-product)
and charge with its product key); the seller's Business subscription expired → 403 `BUSINESS_EXPIRED`
(renew in the dashboard). Missing `cpf`/`euid` when required → 400
`"Informe o CPF/CNPJ ou o EUID do depositante."`; invalid CPF/CNPJ → 400. When the PIX provider's
compliance refuses the payer, the call fails with 400 and a message starting `"Pagamento recusado:"`
(no `code`): show it to the buyer and don't retry with the same CPF/CNPJ. Status polling fallback:
`GET /api/v1/pix/status/:id` (`:id` = `purchaseId` or the deposit `id`; 60/min per id and key), which
also returns `accessToken` once access exists. The complete request/response reference, including
`/api/v1/integration/deposit/pix`, is in https://pay.orion.moe/llms-full.txt and
https://pay.orion.moe/docs.

---

## 6. Products without a fixed price

If `price` is `0` or omitted:
- every `pix/generate` call **must** send `amount` (otherwise 400 `Forneça o valor no campo "amount" ou configure um preço no produto.`);
- `paymentLink` is `null`: the hosted checkout page `/p/<slug>` needs a fixed price, so this product
  can only be sold through the API.

Use a fixed price when the merchant wants a shareable checkout link; use price 0 + `amount` for
variable amounts (donations, carts computed by your system). Either way, a charge below the platform's
minimum PIX amount is refused with `MIN_PIX_ORDER_AMOUNT`.

---

## 7. Verify webhook signatures

Each delivery is a `POST` with `Content-Type: application/json` and one header,
**`X-Webhook-Signature`** = lowercase hex HMAC-SHA256 of the **raw request body**, keyed with
`webhook.secret`, no prefix. (The header is absent only for a webhook without a secret; webhooks
created by the provisioning call always have one.) There are no other OrionPay headers.

Envelope:
```json
{
  "event": "payment.success",
  "productId": 123,
  "productTitle": "Curso X",
  "webhookName": "Default",
  "timestamp": "2026-09-15T12:03:10.000Z",
  "data": { "purchaseId": 1234, "transactionId": "a1b2c3d4-…", "accessToken": "…" }
}
```

Rules: compute the HMAC over the **exact bytes received** (never over re-serialized JSON — key order
and spacing would differ), reject a missing header or one that is not 64 hex chars **before** the
constant-time compare, and only then parse the JSON.

### Node.js (Express)

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

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

function hasValidSignature(rawBody, header, secret) {
  if (typeof header !== "string" || !/^[0-9a-f]{64}$/i.test(header)) return false;
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest(); // 32 bytes
  const received = Buffer.from(header, "hex");                                    // 32 bytes
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// express.raw on THIS route: req.body is the raw Buffer. Register it before any global
// express.json() middleware, or that parser consumes the body first.
app.post("/orion/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  if (!Buffer.isBuffer(req.body) || !hasValidSignature(req.body, req.get("X-Webhook-Signature"), WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  await saveEventOnce(payload); // durable + idempotent (see section 8), then ack
  res.sendStatus(200);
  processEventAsync(payload);   // fulfil / revoke outside the request
});
```

### Python (Flask)

```python
import hashlib
import hmac
import json
import os
import re

from flask import Flask, abort, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["ORION_WEBHOOK_SECRET"].encode()
HEX64 = re.compile(r"^[0-9a-fA-F]{64}$")

@app.post("/orion/webhook")
def orion_webhook():
    raw = request.get_data()  # raw bytes; do NOT use json.dumps(request.json)
    signature = request.headers.get("X-Webhook-Signature", "")
    if not HEX64.match(signature):
        abort(401)
    expected = hmac.new(WEBHOOK_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature.lower()):
        abort(401)
    payload = json.loads(raw)
    save_event_once(payload)  # durable + idempotent, then ack
    return "", 200
```

**Delivery:** 10 s timeout; any 2xx is success; otherwise up to **8 attempts** with exponential backoff
starting around 10 s. Respond fast (store, then process asynchronously). Deduplicate on `event` +
`data.purchaseId`: one payment produces several events, a retry repeats an event, and a manual resend
from the dashboard (`data.isResend: true`) repeats it again, possibly with a different
`transactionId` than the original. To find the order an event belongs to, use `data.purchaseId`
(see [section 5](#5-charge-a-buyer)).

---

## 8. Event semantics

| Event | Meaning | Action |
|---|---|---|
| `purchase.created` | PIX charge created, not paid | mark order "awaiting payment" |
| `payment.received` | PIX paid, settlement delayed (delay window) | informational |
| `access.granted` | buyer may access the product; `data` has `purchaseId`, `buyerEmail`, `accessToken`, `expiresAt`, `grantedAt` | grant access (see below) |
| `payment.under_review` | paid, under the provider's manual compliance review; no deadline | do **not** deliver; tell the buyer to wait and not pay again |
| `payment.success` | payment **settled**; `data` has `purchaseId`, `transactionId`, `accessToken`, `price`, `netAmount`, … | mark paid / count revenue; grant access if not yet granted |
| `payment.refund_pending` | provider announced it will refund; practically always ends refunded. `data.accessRevoked: true` when OrionPay revoked access | **revoke** now |
| `payment.refunded` | payer got the money back (terminal) | **revoke**; close the order |
| `payment.refunded_med` | reversed through a MED (Brazilian PIX fraud dispute) | **revoke**; close the order |
| `med.created` | a MED dispute was opened | flag the order; follow up in the dashboard |

Match every event to your order on **`data.purchaseId`**. Don't match on `data.transactionId`: it is
the deposit id only on `purchase.created`, `payment.success` and `payment.under_review`, and a
numeric internal id on `payment.received`, the refund events and `med.created` — an order matched by
the deposit id would never see its refund, and access would never be revoked. (A resend from the dashboard
carries the deposit id even on those events: `transactionId` is not stable, `purchaseId` is.)

**Delay windows:** some accounts have a settlement delay. Then `access.granted` (and
`payment.received`) arrive at PIX confirmation, **before** settlement, and `payment.success` arrives
hours later. A purchase in `PROCESSING` during that window is normal — don't cancel it. Granting
access on `access.granted` is fine for digital goods as long as refund events revoke it; only
`payment.success` means the money settled.

---

## 9. Delivering the product

- For sales made with `pix/generate`, **OrionPay sends the buyer nothing**. Delivery is the merchant's
  job: send your own e-mail/page, or link the buyer to `https://pay.orion.moe/acesso/<accessToken>`
  (token from `access.granted` / `payment.success`, or `GET /api/v1/pix/status/:id`).
- What that access page shows depends on `productType`:
  - `AREA_MEMBROS` — `delivery.accessUrl` (plus `accessInstructions`).
  - `TELEGRAM_CHANNEL` — `delivery.channelLink` (plus `joinInstructions`).
  - `CURSO_ONLINE`, `FOTOS`, `ARQUIVOS` — **empty until content is uploaded in the dashboard**. Tell
    the user this, or deliver from your own system.
  - `CONSULTORIA`, `MENTORIA` — delivered outside OrionPay (schedule the session yourself).
- After a refund event, stop delivering: remove the buyer from your area/channel and invalidate
  anything you issued.

---

## 10. Errors

Error bodies look like `{ "statusCode", "message", "code", … }`. **Match on `code`.** The errors
specific to this endpoint have messages in Portuguese that start with `API:` and end with the code in
parentheses, e.g. `"API: campo \"price\" inválido: use no máximo 2 casas decimais (INVALID_FIELD)"`;
if you only have the message (MCP), read the code from the trailing parentheses. Authentication
failures (on MCP, a JSON-RPC error) and unexpected errors carry no code: treat them as 401 and 5xx
respectively.

| Status | `code` | Meaning | Retry? |
|---|---|---|---|
| 401 | — | key missing, invalid, expired or revoked | no — fix the key |
| 403 | `PERSONAL_KEY_REQUIRED` | a product key was used | no — use the personal key |
| 403 | `PERSONAL_API_DISABLED` | personal API temporarily disabled platform-wide, or disabled for this account (the message says which) | platform-wide: later; account: no — contact support |
| 403 | `OFFICIAL_STORE_ACCOUNT` | the OrionPay official store account can't use this | no |
| 403 | `BUSINESS_NOT_ACTIVATED` | business account not activated | no — activate in the dashboard |
| 403 | `BUSINESS_EXPIRED` | business subscription expired | no — renew in the dashboard |
| 400 | `INVALID_FIELD` | invalid, missing or unknown field; `field` holds the dotted path (`webhook.events`) | no — fix the body |
| 400 | `MIN_PIX_ORDER_AMOUNT` | price below the minimum PIX charge | no — change the price |
| 409 | `PRODUCT_REFERENCE_EXISTS` | `externalReference` already used with another `productType` or webhook URL; `productId` in the body | no — new reference or matching values |
| 429 | `API_PRODUCT_DAILY_LIMIT` | too many products created by the account in the last 24h (dashboard included) | later |
| 429 | `PROVISIONING_IN_PROGRESS` | another provisioning call for this account is running | yes, after a few seconds, same `externalReference` |
| 429 | — | request rate limit, 10/h per key (standard throttler body, no `code`: `"ThrottlerException: Too Many Requests"`) | later (minutes, not seconds) |
| 5xx / network error | — | outcome unknown | yes, **same `externalReference`** |

---

## 11. Retries and idempotency

- Always send `externalReference`. Derive it from something stable on your side (SKU, plan id,
  `shop-42:product-7`) — never a random value per attempt, or a retry creates a second product.
- On a timeout, network error or 5xx, resend the identical request: a `200` with `"replayed": true`
  means the first attempt had worked.
- `externalReference` is unique per account and is **not** a secret; don't encode credentials or
  personal data in it.

---

## 12. Limits

| Limit | Value |
|---|---|
| `POST /api/v1/personal/products` (REST) | 10 requests/hour per API key |
| Products created per account | 20 new products per rolling 24h (default) before this endpoint (REST and MCP) refuses; products created in the dashboard count, but the dashboard is not blocked; replays don't count |
| Keys | 1 product key per product, 1 personal key per account |
| `POST /api/v1/pix/generate` | no limit of its own; the global limits below apply, per product key |
| `GET /api/v1/pix/status/:id` | 60/min per id and key |
| Global | 30/s, 300/min, 1500/15min per key |

---

## 13. Not possible through the API

Tell the user these need the dashboard (https://pay.orion.moe/dashboard):
- product images and content (lessons, files, photos);
- product types other than the seven above — raffles, physical products, funding campaigns;
- editing, unpublishing or deleting a product;
- creating, rotating or revoking the personal key; revoking product keys; managing keys or webhooks
  of existing products (other than the missing-step completion of a replay);
- personal (account-level) webhooks.

---

## 14. Key revocation

Revoking the personal key does **not** revoke product keys created with it. If the personal key
leaks, revoke it **and** every product key created with it (the security e-mails list the product key
ids), then create new ones. If a webhook secret leaks, replace it by editing the webhook in the
dashboard.

---

## Checklist for the AI

- [ ] The only thing asked of the human is the personal key (https://pay.orion.moe/dashboard/api-webhooks); it lives in a secret, server-side.
- [ ] Provisioning sends `title`, `productType` (one of the 7), `externalReference`, and a `webhook` with refund events — no extra fields.
- [ ] `title` has at most 191 chars; `price` is a JSON number with ≤ 2 decimals; if it is 0/absent, every charge sends `amount` and `paymentLink` is `null`.
- [ ] 201 and 200 (`replayed: true`) are both success; `apiKey.key` and `webhook.secret` are stored as secrets and never logged; a replay with `apiKey: null` (key disabled/expired in the dashboard) is handled.
- [ ] Retries on 5xx/network error/timeout/`PROVISIONING_IN_PROGRESS` reuse the same `externalReference`; a 429 without `code` waits minutes; other errors are fixed, not retried; errors are matched on `code`.
- [ ] Charges use the **product** key on `POST /api/v1/pix/generate`, with `cpf` or `euid` for totals ≥ R$10.00.
- [ ] The webhook handler verifies `X-Webhook-Signature` (hex HMAC-SHA256) over the raw body with a length check and constant-time compare, returns 2xx fast, and dedupes on `event` + `purchaseId`.
- [ ] Orders are matched to webhook events on `data.purchaseId` (not `transactionId`).
- [ ] Access is granted on `access.granted` or `payment.success`; revenue counts only on `payment.success`; `payment.refund_pending`, `payment.refunded` and `payment.refunded_med` revoke.
- [ ] Delivery is implemented by the merchant (or via `https://pay.orion.moe/acesso/<accessToken>`); for `CURSO_ONLINE`/`FOTOS`/`ARQUIVOS` the user was told to upload content in the dashboard.
- [ ] The user was told that revoking the personal key does not revoke product keys.
