Lunium API · Manual de integração

Sumário

1. Fluxograma

Versão em alta resolução: https://docs.luniumpay.com/manual-fluxograma.png.

2. Primeiros passos

2.1 Chave de teste (sandbox) — uma chamada

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

A chave lun_test_… roda na mesma URL base, com as mesmas formas, estados e contrato de erro da produção. Nada se move. O que o sandbox cobre hoje:

2.2 Chave de produção — só o nome é obrigatório

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

A chave nasce na hora com cash-in e cash-out habilitados, no tier Início (R$ 5.000/dia em cash-in + payouts; sobe para R$ 25.000 com R$ 50 mil liquidados e R$ 100.000 com R$ 500 mil). A resposta traz a chave crua uma única vez (só o hash fica no banco); guarde em cofre. Limite de 5 chaves de produção por IP por dia.

2.3 Grupo de operação no Telegram — fortemente recomendado

1. Crie um grupo chamado Lunium <> SeuProjeto com @LuniumNotifyBot (o agente) e @luniumB2B (o humano do outro lado). A API funciona sem grupo, mas operar sem ele é operar às cegas: é por ali que você fica sabendo de uma liquidação que falhou às 3h da manhã.
2. No privado do bot, crie ou consulte a chave: https://t.me/LuniumNotifyBot → /chave mostra o código lk….
3. Um admin do grupo manda /vincular lk…. Sem isso o grupo não recebe aviso nenhum.
4. A partir daí o bot avisa cada PIX que entra, cada cripto que sai, anexa o PDF do comprovante de cada venda paga e responde dúvidas quando mencionado. Comandos úteis: /configurar (checklist), /carteira 0x…, /status, /extrato, /limites.

2.4 Configurar a chave

curl -s -X PATCH https://api.luniumpay.com/keys/me -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{
    "settlement_address": "0xSUA_CARTEIRA_POLYGON",
    "webhook_url": "https://api.seudominio.com/lunium/webhook"
  }'
→ devolve webhook_secret (whk_…) UMA vez; rotate_webhook_secret:true gera outro

• settlement_address: carteira padrão que recebe a cripto do cash-in quando a cobrança não traz payout_address.
• webhook_url + webhook_secret: assinatura HMAC dos eventos (seção 7).
• GET /keys/me devolve todos os limites vigentes para a sua chave (tier, por operação, escada do pagador, teto do recebedor). É o número que nunca envelhece: leia-o em vez de fixar as tabelas deste manual no código.

2.5 Links de teste e referência

3. Cash-in: cliente paga PIX → recebe cripto

Fluxo: consultar o limite do pagador → criar a cobrança (QR + copia-e-cola) → cliente paga → provedor confirma → Lunium envia a cripto ao payout_address → webhook cashin.settled com a hash da transação. O CPF/CNPJ do pagador é obrigatório (exigência do Banco Central, o provedor não gera QR sem ele) e é o que alimenta a escada de limites.

3.1 Limites: instantâneo × retenção de 24h — e como usar a retenção

Existe um degrau antifraude por pagador (CPF/CNPJ), independente da chave. Ele tem dois patamares e vale já na primeira operação do documento — não é preciso histórico nem esperar 24h:

Por cobrança: mínimo R$ 1,00 (com a taxa padrão o mínimo efetivo é R$ 1,02), máximo R$ 6.000,00. A escada conta o que já foi pago e o que está em voo (cobranças pendentes ainda válidas); o relógio só começa no primeiro pagamento confirmado — criar QR não amadurece o documento.

GET /cashin/limits?payer_tax=52998224725   (resposta real, pagador sem histórico)
{
  "stage": "first_transaction",
  "instant_available_cents": 20000,          ← entra na hora
  "max_amount_cents": 600000,                 ← maior valor aceito agora (com retenção)
  "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 Requisição, resposta e estados

POST /cashin/charge     (X-API-Key: lun_…)
{
  "amount_cents": 15000,                         // R$ 150,00 — SEMPRE em centavos, inteiro
  "payer_tax_number": "12345678901",             // CPF (11) ou CNPJ (14), só dígitos — obrigatório
  "payer_name": "Nome do pagador",               // opcional
  "asset": "usdt", "chain": "polygon",           // par do GET /cashin/catalog; omitido = usdt/polygon
  "payout_address": "0x51e3d4…bc75e0",           // carteira do SEU cliente; omitido = settlement_address da chave
  "external_id": "dep-0001"                 // idempotente: repetir devolve a mesma cobrança (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",     // QR vale 15 minutos
  "held": false, "held_hours": 0,                // true/24 quando o valor exige retenção
  "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,     // líquido após taxa
  "usdt_amount": "28.620000", "settlement_tx_hash": "0x…", "settlement_tx_url": "https://polygonscan.com/tx/0x…",
  "e2e": "E18236120202609021420…", "payer_name": "NOME DO PAGADOR", "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 Ativos, prazos e taxas

GET /cashin/catalog é a fonte da verdade e muda sozinho. Formato real: {updatedAt, instant[], convert[], dropped[], totals}.

Taxa padrão da chave: admin_fee_bps: 250 (2,5%) + admin_fee_fixed_cents: 100 (R$ 1,00) por cobrança, descontados do valor pago antes da conversão. POST /cashin/preview mostra a conta sem criar nada:

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"}

Condições comerciais diferentes (taxa, tetos por pagador, carência) são configuradas por chave pela Lunium e aparecem em GET /keys/me.

4. Depósito em saldo (custódia) e saques

Para apps de carteira que precisam de uma aba "depositar e sacar" em reais. A chave precisa da custódia habilitada pela Lunium (custodia_ativa: true em GET /saldo) — pedimos no grupo. Nenhuma cripto sai: o PIX pago vira saldo em reais na sub-conta do seu cliente (customer_ref).

Nada é adiantado e nenhuma taxa é absorvida: o que o provedor cobra é o que o saldo paga. As cobranças trazem fonte (pix | saldo) e destino (cripto | saldo) para um saque nunca ser confundido com uma compra.

5. Cash-out: cliente entrega cripto → chave PIX recebe reais

Três passos, nesta ordem. A cotação já é líquida: brl_amount é exatamente o que cai na chave PIX.

1) POST /cash-outs                       (cotar — não compromete nada)
{
  "asset": "usdt", "network": "polygon",
  "brl_amount": "250.00",                 // OU "amount": "50.77" (cripto) — exatamente um dos dois
  "pix_key": "cliente@exemplo.com",       // CPF · CNPJ · +55DDDNÚMERO · e-mail · UUID; 11 dígitos puros exige pix_key_type
  "refund_address": "0x51e3d4…bc75e0",    // carteira de RETORNO do cliente, mesma rede — mande sempre
  "external_id": "venda-001"
}
→ 201 (resposta real de sandbox)
{ "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    (trava a cotação — ponto sem volta)
→ { "state": "AWAITING_DEPOSIT", "deposit_address": "0x2952552e…", "deposit_tag": null, … }
   O cliente envia EXATAMENTE "amount" para deposit_address, na rede cotada.

3) GET /cash-outs/{cashout_id}            (acompanhar; ou espere o 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…" }

• Antes de aceitar, mostre quem vai receber: GET /pix/keys/lookup?key=… devolve nome, documento mascarado e instituição do titular (DICT). 5 consultas/min por conta; chave inexistente → 404 chave_nao_encontrada.
• Nunca peça CPF de quem vende. A chave PIX já identifica o recebedor; o campo não existe na venda.
• expires_at: 15 min na Polygon, até 300 min nas outras redes. Leia o campo; não fixe prazo.
• Se o aceite responder 503 liquidante_indisponivel (acao: esperar, retry_after_seconds: 120): o liquidante de PIX está fora naquele instante; espere e re-aceite a mesma ordem. Nenhum endereço é emitido enquanto isso, de propósito — cripto nunca entra numa esteira parada.
• Pagar QR/copia-e-cola (br_code) em vez de chave: desligado em produção hoje (503 br_code_indisponivel). A venda paga chaves PIX.

5.1 Limites, redes e prazos

5.2 Estados, devoluções e comprovante

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

Comprovante — três formas do mesmo fato, na mesma resposta e no mesmo webhook (nunca monte URL na mão): pix_e2e (identificador do Banco Central), receipt_url (página), receipt_pdf_url (PDF com nome, documento e instituição do recebedor, valor, data, E2E), verify_url. E qualquer pessoa, sem chave, confirma o pagamento:

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": "…" }
  (não expõe chave PIX, nome completo nem documento)

5.3 Sandbox: gatilhos determinísticos

As duas primeiras casas decimais do amount (em cripto) escolhem o desfecho — dá para afirmar em CI:

Reusar um external_id com destino diferente devolve 409, igual à produção. Ordens de sandbox somem em 2 h. Nunca envie cripto a um deposit_address de sandbox: ele não tem dono.

6. Payouts (PIX direto, sem perna cripto)

POST /payouts envia um PIX para uma chave. Precisa de payout_enabled na chave (nasce desligado; pedimos no grupo). Com custódia, o valor sai do saldo da sub-conta (customer_ref); sem custódia, sai da tesouraria da Lunium conforme acordo comercial. Limites por operação: R$ 1,00 a R$ 6.000,00; conta na cota diária do tier.

POST /payouts { "amount_cents": 5000, "pix_key": "+5548999990000", "tax_number": "12345678901",
                "external_id": "saque-001", "customer_ref": "cliente-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

Envelope único para todos os eventos. data é exatamente o objeto que o GET de status devolve para aquele recurso.

POST {webhook_url}
X-Lunium-Event-Id: evt_9f2c…          // id do EVENTO — estável entre retentativas: deduplique por ele
X-Lunium-Delivery-Id: dlv_…           // id da TENTATIVA — cite no suporte
X-Lunium-Signature: t=1756850000,v1=<hex HMAC-SHA256(secret, "t.corpo")>
{ "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…", … } }

• Verifique a assinatura v2 e recuse o que tiver mais de ~5 minutos. O header antigo X-Webhook-Signature (só o corpo) deixa de ser enviado em 09/11/2026; chaves criadas depois de 08/08/2026 já não o recebem.
• Responda 2xx em até 15 s. Sem 2xx: 12 tentativas com backoff (~7 h). A que esgota aparece como failed em GET /webhooks/deliveries e é recuperável com POST /webhooks/deliveries/{event_id}/retry. Nada se perde em silêncio: o bot também avisa no grupo.
• Trate evento desconhecido como no-op — a lista cresce sem aviso.
• POST /webhooks/test dispara webhook.test pelo mesmo transporte e devolve o que o SEU endpoint respondeu. Rode antes da primeira cobrança real.
• Prefira webhook a polling: 1 consulta/s consome sozinha os 60 req/min da chave (429 é proteção, não falha).

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

8. Erros: o campo que diz o que fazer

Todo erro traz erro (código estável), acao, detail, request_id e agent_guidance. Ramifique pela acao, não pela mensagem:

Todo carimbo de tempo é ISO 8601 com fuso explícito (2026-08-01T22:35:49-03:00 ou …Z). Nunca suponha local ou UTC.

9. Tabela-resumo de limites e taxas (produção, 02/09/2026)

Todo número daqui pode mudar; GET /keys/me devolve os que valem para a sua chave. Condições comerciais específicas (taxa, tetos por pagador, carência) são acordadas com a Lunium e refletidas na chave.

10. Checklist de go-live

1. Chave de produção criada (POST /keys) e guardada em cofre; nunca no chat.
2. Grupo de operação com @LuniumNotifyBot + @luniumB2B, /vincular feito por um admin; /configurar mostra tudo ✅.
3. settlement_address (Polygon) e webhook_url configurados via PATCH /keys/me; POST /webhooks/test respondeu 2xx.
4. Webhook verifica X-Lunium-Signature v2, deduplica por event_id, ignora eventos desconhecidos, responde em < 15 s.
5. Cash-in: front consulta GET /cashin/limits antes de cobrar, mostra held/held_hours, trata delayed como "pago, libera em …" e credita só em cashin.settled (ou paid com settlement_status: sent). Testado com PIX real de R$ 1 a R$ 5.
6. Cash-out: fluxo cotar → mostrar titular (/pix/keys/lookup) e valor → aceitar → mostrar deposit_address e amount exatos; sempre manda refund_address e external_id; polling a cada 10–15 s ou webhook; trata 503 liquidante_indisponivel re-aceitando a mesma ordem. Gatilhos .01–.08 passaram em sandbox.
7. Erros ramificados por acao; limits lidos da resposta em vez de fixados; expires_at lido em vez de prazo fixo.
8. Entrou no canal de parceiros (https://t.me/+FerOZMRRP_g5MDk5) e acompanha docs.luniumpay.com/status.

11. Links e canais