Lunium API · Integration manual

Contents

1. Flowchart

High-resolution version: https://docs.luniumpay.com/manual-fluxograma.png (labels in Portuguese).

2. First steps

2.1 Test key (sandbox) — one call

curl -s -X POST https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' -d '{"name":"my-project"}'
→ {"api_key":"lun_test_…","sandbox":true,"como_usar":{…}}

The lun_test_… key runs on the same base URL, with the same shapes, states and error contract as production. Nothing moves. What the sandbox covers today:

2.2 Production key — only the name is required

curl -s -X POST https://api.luniumpay.com/keys \
  -H 'Content-Type: application/json' -d '{"name":"My Company"}'
→ {"api_key":"lun_…", "dashboard_url":"…", "grupos_obrigatorios":{…}, "limits":{…}}

The key is born immediately with cash-in and cash-out enabled, in the Início tier (R$ 5,000/day on cash-in + payouts; it rises to R$ 25,000 at R$ 50k settled and to R$ 100,000 at R$ 500k). The response carries the raw key once only (only the hash is stored); keep it in a vault. Limit of 5 production keys per IP per day.

2.3 Operations group on Telegram — strongly recommended

1. Create a group named Lunium <> YourProject with @LuniumNotifyBot (the agent) and @luniumB2B (the human on the other side). The API works without a group, but operating without one is operating blind: it is where you learn about a settlement that failed at 3 a.m.
2. In the bot's private chat, create or look up the key: https://t.me/LuniumNotifyBot → /chave shows the lk… code.
3. A group admin sends /vincular lk…. Without it the group receives no notification at all.
4. From then on the bot announces every PIX that comes in, every crypto that goes out, attaches the receipt PDF of every paid sale and answers questions when mentioned. Useful commands: /configurar (checklist), /carteira 0x…, /status, /extrato, /limites.

2.4 Configure the key

curl -s -X PATCH https://api.luniumpay.com/keys/me -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{
    "settlement_address": "0xYOUR_POLYGON_WALLET",
    "webhook_url": "https://api.yourdomain.com/lunium/webhook"
  }'
→ returns webhook_secret (whk_…) ONCE; rotate_webhook_secret:true generates another

• settlement_address: default wallet that receives the cash-in crypto when the charge carries no payout_address.
• webhook_url + webhook_secret: HMAC signature of the events (section 7).
• GET /keys/me returns every limit currently in force for your key (tier, per operation, payer ladder, recipient ceiling). It is the number that never goes stale: read it instead of hard-coding the tables in this manual.

2.5 Test and reference links

3. Cash-in: the customer pays a PIX → receives crypto

Flow: check the payer's limit → create the charge (QR + copy-and-paste) → the customer pays → the provider confirms → Lunium sends the crypto to payout_address → webhook cashin.settled with the transaction hash. The payer's CPF/CNPJ is required (a Central Bank requirement — the provider does not issue a QR without it) and it is what feeds the limit ladder.

3.1 Limits: instant × 24h hold — and how to use the hold

There is an anti-fraud step per payer (CPF/CNPJ), independent of the key. It has two levels and applies from the document's very first operation — no history and no 24h wait needed:

Per charge: minimum R$ 1.00 (with the default fee the effective minimum is R$ 1.02), maximum R$ 6,000.00. The ladder counts what was already paid and what is in flight (pending charges still valid); the clock only starts at the first confirmed payment — creating a QR does not mature the document.

GET /cashin/limits?payer_tax=52998224725   (real response, payer with no history)
{
  "stage": "first_transaction",
  "instant_available_cents": 20000,          ← settles instantly
  "max_amount_cents": 600000,                 ← largest amount accepted now (with hold)
  "held_qr": { "max_amount_cents": 600000, "used_cents": 0, "available_cents": 600000, "hold_hours": 24 },
  "ladder": { "first_transaction_cents": 20000, "first_24h_cents": 20000,
              "mature_day_cents": 600000, "held_max_cents": 600000, "hold_hours": 24 },
  "next_stage": { "stage": "first_24h", "limit_cents": 20000, "quando": "após o primeiro pagamento confirmado" },
  "explicacao": "Primeira operação deste CPF/CNPJ: até R$ 200.00 entra na hora; acima disso, até R$ 6000.00 o QR sai com retenção de 24h do provedor…"
}

3.2 Request, response and states

POST /cashin/charge     (X-API-Key: lun_…)
{
  "amount_cents": 15000,                         // R$ 150.00 — ALWAYS in cents, integer
  "payer_tax_number": "12345678901",             // CPF (11) or CNPJ (14), digits only — required
  "payer_name": "Payer name",                    // optional
  "asset": "usdt", "chain": "polygon",           // pair from GET /cashin/catalog; omitted = usdt/polygon
  "payout_address": "0x51e3d4…bc75e0",           // YOUR customer's wallet; omitted = the key's settlement_address
  "external_id": "dep-0001"                      // idempotent: repeating returns the same charge (200)
}
→ 200
{
  "cashin_id": "ci_3ca9f23b…", "status": "pending",
  "amount_cents": 15000, "asset": "usdt", "chain": "polygon", "payout_address": "0x51e3…",
  "qr_copypaste": "00020126…", "qr_image_url": "https://…png",
  "expires_at": "2026-09-02T23:25:00.000Z",     // the QR is valid for 15 minutes
  "held": false, "held_hours": 0,                // true/24 when the amount requires a hold
  "delay_until": null, "liberar_em": null, "hold_hours": 0,
  "external_id": "dep-0001", "created_at": "…"
}

GET /cashin/{cashin_id}/status
{
  "cashin_id": "ci_…", "status": "paid",                     // pending | delayed | under_review | paid | expired | refunded | failed
  "settlement_status": "sent",                              // pending | sending | sent | incerto | failed
  "amount_cents": 15000, "depix_received_cents": 14625,     // net after fee
  "usdt_amount": "28.620000", "settlement_tx_hash": "0x…", "settlement_tx_url": "https://polygonscan.com/tx/0x…",
  "e2e": "E18236120202609021420…", "payer_name": "PAYER NAME", "payer_tax_number": "123.***.***-01",
  "held": false, "held_hours": 0, "delay_until": null, "liberar_em": null,
  "destino": "cripto", "customer_ref": null,
  "paid_at": "…", "settled_at": "…", "expires_at": "…", "created_at": "…"
}

3.3 Assets, timing and fees

GET /cashin/catalog is the source of truth and changes on its own. Real shape: {updatedAt, instant[], convert[], dropped[], totals}.

Default key fee: admin_fee_bps: 250 (2.5%) + admin_fee_fixed_cents: 100 (R$ 1.00) per charge, deducted from the amount paid before conversion. POST /cashin/preview shows the maths without creating anything:

POST /cashin/preview {"amount_cents":10000,"asset":"usdt","chain":"polygon"}
→ {"amount_cents":10000,"admin_fee_bps":250,"admin_fee_fixed_cents":100,"fee_total_cents":348,"net_cents":9652,"brl_per_usdt":"5.11","usdt_amount":"18.874787"}

Different commercial terms (fee, per-payer ceilings, holding period) are configured per key by Lunium and show up in GET /keys/me.

4. Balance deposit (custody) and withdrawals

For wallet apps that need a "deposit and withdraw" tab in reais. The key needs custody enabled by Lunium (custodia_ativa: true in GET /saldo) — ask in the group. No crypto leaves: the paid PIX becomes a BRL balance in your customer's sub-account (customer_ref).

Nothing is advanced and no fee is absorbed: what the provider charges is what the balance pays. Charges carry fonte (pix | saldo) and destino (cripto | saldo) so a withdrawal is never confused with a purchase.

5. Cash-out: the customer delivers crypto → a PIX key receives reais

Three steps, in this order. The quote is already net: brl_amount is exactly what lands on the PIX key.

1) POST /cash-outs                       (quote — commits nothing)
{
  "asset": "usdt", "network": "polygon",
  "brl_amount": "250.00",                 // OR "amount": "50.77" (crypto) — exactly one of the two
  "pix_key": "customer@example.com",      // CPF · CNPJ · +55AREANUMBER · e-mail · UUID; 11 bare digits require pix_key_type
  "refund_address": "0x51e3d4…bc75e0",    // the customer's RETURN wallet, same network — always send it
  "external_id": "sale-001"
}
→ 201 (real sandbox response)
{ "cashout_id": "sbx_141ce3e9…", "state": "QUOTE_CREATED", "amount": "50.774309", "brl_amount": "250.00",
  "pix_key_type": "email", "deposit_address": null, "expires_at": "2026-09-03T02:33:31Z", … }

2) POST /cash-outs/{cashout_id}/accept    (locks the quote — point of no return)
→ { "state": "AWAITING_DEPOSIT", "deposit_address": "0x2952552e…", "deposit_tag": null, … }
   The customer sends EXACTLY "amount" to deposit_address, on the quoted network.

3) GET /cash-outs/{cashout_id}            (follow it; or wait for the webhook)
→ { "state": "COMPLETED", "pix_e2e": "E0000000020260903…", "pix_paid_at": "…",
    "receipt_url": "https://app.luniumpay.com/comprovante/…", "receipt_pdf_url": "….pdf",
    "verify_url": "https://api.luniumpay.com/v1/verificar/E…", "refund_tx_hash": null, "deposit_from": "0x…" }

• Before accepting, show who will receive: GET /pix/keys/lookup?key=… returns the holder's name, masked document and institution (DICT). 5 lookups/min per account; unknown key → 404 chave_nao_encontrada.
• Never ask the seller for a CPF. The PIX key already identifies the recipient; the field does not exist on the sale.
• expires_at: 15 min on Polygon, up to 300 min on other networks. Read the field; do not hard-code a window.
• If accept answers 503 liquidante_indisponivel (acao: esperar, retry_after_seconds: 120): the PIX settlement provider is down at that instant; wait and re-accept the same order. No address is issued in the meantime, on purpose — crypto never enters a stalled pipeline.
• Paying a QR/copy-and-paste (br_code) instead of a key: disabled in production today (503 br_code_indisponivel). The sale pays PIX keys.

5.1 Limits, networks and timing

5.2 States, refunds and receipt

QUOTE_CREATED → accept → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED  ·  detours: MANUAL_REVIEW → REFUNDING → REFUNDED · EXPIRED · FAILED. Webhooks: cashout.awaiting_deposit, deposit_detected, processing, under_review, refunding, completed, refunded, expired, failed.

Receipt — three forms of the same fact, in the same response and the same webhook (never build URLs by hand): pix_e2e (Central Bank identifier), receipt_url (page), receipt_pdf_url (PDF with the recipient's name, document and institution, amount, date, E2E), verify_url. And anyone, with no key, can confirm the payment:

GET https://api.luniumpay.com/v1/verificar/{e2e}
→ { "verificado": true, "pago": true, "valor_brl": "250.00", "pago_em": "2026-09-03T02:18:47Z",
    "recebedor_iniciais": "T. S. T.", "instituicao": "…", "liquidado_por": "Lunium", "comprovante_url": "…" }
  (does not expose the PIX key, full name or document)

5.3 Sandbox: deterministic triggers

The first two decimals of amount (in crypto) choose the outcome — you can assert on it in CI:

Reusing an external_id with a different destination returns 409, same as production. Sandbox orders vanish after 2 h. Never send crypto to a sandbox deposit_address: it has no owner.

6. Payouts (direct PIX, no crypto leg)

POST /payouts sends a PIX to a key. It requires payout_enabled on the key (born disabled; ask in the group). With custody, the amount leaves the sub-account's balance (customer_ref); without custody, it leaves Lunium's treasury as agreed commercially. Limits per operation: R$ 1.00 to R$ 6,000.00; counts towards the tier's daily quota.

POST /payouts { "amount_cents": 5000, "pix_key": "+5548999990000", "tax_number": "12345678901",
                "external_id": "withdrawal-001", "customer_ref": "customer-42" }
→ { "payout_id": "po_…", "status": "processing",   // processing | sent | failed | refunded
    "amount_cents": 5000, "fee_cents": 100, "pix_key": "+5548*****0000", "sent_at": null, … }
Webhooks: payout.sent · payout.failed · payout.refunded

7. Webhooks

One envelope for every event. data is exactly the object the status GET returns for that resource.

POST {webhook_url}
X-Lunium-Event-Id: evt_9f2c…          // id of the EVENT — stable across retries: deduplicate by it
X-Lunium-Delivery-Id: dlv_…           // id of the ATTEMPT — quote it to support
X-Lunium-Signature: t=1756850000,v1=<hex HMAC-SHA256(secret, "t.body")>
{ "event": "cashin.settled", "event_id": "evt_9f2c…", "created_at": "2026-09-02T23:10:11.000Z",
  "data": { "cashin_id": "ci_…", "status": "paid", "settlement_status": "sent", "settlement_tx_hash": "0x…", … } }

• Verify the v2 signature and reject anything older than ~5 minutes. The old X-Webhook-Signature header (body only) stops being sent on 2026-11-09; keys created after 2026-08-08 no longer receive it.
• Answer 2xx within 15 s. Without a 2xx: 12 attempts with backoff (~7 h). A delivery that runs out shows as failed in GET /webhooks/deliveries and is recoverable with POST /webhooks/deliveries/{event_id}/retry. Nothing is lost silently: the bot also warns in the group.
• Treat unknown events as a no-op — the list grows without notice.
• POST /webhooks/test fires webhook.test over the same transport and returns what YOUR endpoint answered. Run it before the first real charge.
• Prefer webhooks to polling: one query per second alone consumes the key's 60 req/min (429 is protection, not failure).

// Node — verifying the v2 signature
const [t, v1] = req.get('X-Lunium-Signature').split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now()/1000 - t) < 300;

8. Errors: the field that tells you what to do

Every error carries erro (a stable code), acao, detail, request_id and agent_guidance. Branch on acao, not on the message:

Every timestamp is ISO 8601 with an explicit offset/timezone (2026-08-01T22:35:49-03:00 or …Z). Never assume local time or UTC.

9. Summary table of limits and fees (production, 2026-09-02)

Every number here can change; GET /keys/me returns the ones that apply to your key. Specific commercial terms (fee, per-payer ceilings, holding period) are agreed with Lunium and reflected on the key.

10. Go-live checklist

1. Production key created (POST /keys) and stored in a vault; never in chat.
2. Operations group with @LuniumNotifyBot + @luniumB2B, /vincular done by an admin; /configurar shows everything ✅.
3. settlement_address (Polygon) and webhook_url configured via PATCH /keys/me; POST /webhooks/test answered 2xx.
4. Webhook verifies X-Lunium-Signature v2, deduplicates by event_id, ignores unknown events, answers in < 15 s.
5. Cash-in: the front end queries GET /cashin/limits before charging, shows held/held_hours, treats delayed as "paid, releases at …" and credits only on cashin.settled (or paid with settlement_status: sent). Tested with a real PIX of R$ 1 to R$ 5.
6. Cash-out: quote → show the holder (/pix/keys/lookup) and the amount → accept → show the exact deposit_address and amount; always sends refund_address and external_id; polls every 10–15 s or uses the webhook; handles 503 liquidante_indisponivel by re-accepting the same order. Triggers .01–.08 passed in the sandbox.
7. Errors branched by acao; limits read from the response instead of hard-coded; expires_at read instead of a fixed window.
8. Joined the partner channel (https://t.me/+FerOZMRRP_g5MDk5) and follows docs.luniumpay.com/status.

11. Links and channels