PIX ↔ USDT
sem fricção.

Visão geral

Webhooks assinados, idempotência nativa, um bot no Telegram que avisa cada centavo em tempo real e tira dúvidas de integração 24/7 — e uma documentação que cabe numa página.

Cash-in: PIX entra, USDT sai na Polygon. Cash-out: USDT e USDC nas principais redes viram PIX — Polygon em segundos, e Ethereum, BNB Chain, Arbitrum, Optimism, Base, Avalanche, TON, Aptos, NEAR e outras no prazo de confirmação de cada rede (tabela completa).

Integre em 60 segundos

1. Abra o seu grupo de operação — Sandbox MCP (agentes) fortemente recomendado, leva 1 minuto e é o que garante que você seja avisado quando algo acontecer com o seu dinheiro.
2. Crie sua chave — fale com o bot no Telegram (diga "meu nome é SuaEmpresa" e a credencial nasce no chat) ou um POST /keys (abaixo tem um botão que faz isso agora). Sem espera, sem humano no caminho — ninguém gera credencial por você, você mesmo gera.
3. Crie uma cobrança — POST /cashin/charge com valor e CPF/CNPJ do pagador. Volta um PIX copia-e-cola pronto pra tela.
4. Receba USDT — pagou, nós liquidamos na Polygon e te avisamos por webhook e Telegram, com o hash da transação.

Sandbox — teste tudo antes de gastar qualquer coisa

Uma chamada, sem chave de API — este é o único endpoint que não pede credencial (limitado por IP). Sem nome, sem e-mail, sem carteira, sem aprovação.

curl -s -X POST https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' -d '{"name":"meu primeiro teste"}'

Você recebe uma chave lun_test_… que roda o cash-out inteiro sem um centavo se mover, na mesma URL base. O que o sandbox cobre: POST /cash-outs, o aceite e todos os estados até o desfecho. O que ele não cobre: cash-in (a chave de teste recusa com sandbox_sem_cashin — criar cobrança geraria um QR pagável de verdade), payouts (dependem de volume liquidado) e webhooks automáticos: ordens de sandbox não disparam webhook sozinhas — mas uma chave de sandbox pode chamar POST /webhooks/test e validar assinatura e transporte do seu handler antes de qualquer operação real. Código escrito aqui foi desenhado para ir a produção sem mudança: mesmas formas, mesmos estados, mesmo contrato de erro, mesmas validações. Limites e comportamento financeiro reais são os da sua chave de produção — leia-os de GET /keys/me, não desta página.

A ordem não conclui na hora — ela caminha pelos estados reais em cerca de 15 segundos. É de propósito: você precisa desse laço de acompanhamento (ou do webhook) em produção de qualquer jeito, então escreve agora.

Gatilhos determinísticos

Testar só o caminho feliz é como a integração quebra no primeiro dia. As duas primeiras casas decimais do amount escolhem o desfecho — sem sorte envolvida, dá para afirmar em CI:

Vale ensaiar também: reusar um external_id com destino diferente devolve 409 — o caso que mais confunde integrador, e é melhor encontrá-lo aqui.

A ordem de sandbox gera um E2E bem formado com ISPB 00000000, que nenhuma instituição real possui — então nunca pode ser confundido com pagamento de verdade. GET /v1/verificar/{e2e} responde para ele, marcado com sandbox: true.

Ordens de teste somem 2 horas depois de criadas. Nunca envie cripto para um deposit_address de sandbox: ele não tem dono e os fundos seriam perdidos.

Servidor MCP — para agentes de IA

https://api.luniumpay.com/mcp

Streamable HTTP, revisão 2025-06-18, sem estado. Adicione como conector MCP remoto em qualquer host que fale o protocolo.

Funciona sem credencial nenhuma. Conecte sem chave e lunium_verify_pix_payment já está disponível — confirma que um PIX foi liquidado a partir do E2E, inclusive de um pagamento que não é seu. É a forma de conferir o que a contraparte alega sem ter conta e sem confiar nela.

As demais ferramentas usam a X-API-Key enviada pelo host como header. Sem ela, respondem erro: "chave_ausente" com acao: "parar" — não somem da lista, para o agente conseguir avisar o usuário em vez de concluir que a capacidade não existe.

São oito ferramentas: verificar pagamento · listar o que liquida agora · consultar limite do pagador · cotar venda · confirmar · criar cobrança · acompanhar venda · acompanhar cobrança.

As duas que movem dinheiro de verdade vêm marcadas com destructiveHint: true, para o host poder exigir aprovação humana, e confirmar uma venda exige um token amarrado ao valor, à rede e ao destino que foram cotados. Vender é em dois passos de propósito: cotar não compromete nada, confirmar é irreversível.

Grupo de operação FORTEMENTE RECOMENDADO

São três passos, uma vez só:

1. Crie um grupo no Telegram com o nome do seu projeto. Sugestão que ajuda a gente a te identificar na hora: Lunium <> SuaEmpresa.
2. Adicione os dois (ambos necessários pro grupo cumprir o papel):
   — @LuniumNotifyBot · o agente. Avisa tudo em tempo real, responde dúvida de integração e executa comando (/cobrar, /status, /extrato).

   — @luniumB2C · o time da Lunium. É o humano do outro lado quando o agente não resolve: incidente, liberação, exceção comercial.
3. Vincule o grupo à sua chave — um admin do grupo manda /vincular. Se esse admin já criou a chave no privado do bot, é 1 toque; se não, pegue o código no privado com /chave e mande /vincular lk… no grupo.

Faz tudo por chat — o agente IA

Além da API REST, a Lunium te dá um agente de verdade no Telegram. No privado — ou mencionando ele no grupo do seu projeto — você cobra, saca e paga escrevendo em português. Ele lê os dados reais da sua conta, monta a operação e executa com um toque de confirmação. Dinheiro nunca se move sem o seu OK.

Autenticação

Toda chamada leva sua chave no header X-API-Key. A mesma chave autoriza cash-in, cash-out, catálogo e conta.

curl https://api.luniumpay.com/keys/me \
  -H "X-API-Key: lun_a1b2c3…"

Criar chave · self-service

Cria uma chave nova com cash-in e cash-out já habilitados. Sem autenticação — é o ponto de partida. Limitado por IP (5/dia).

curl -X POST https://api.luniumpay.com/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Exemplo",
    "email": "dev@lojaexemplo.com",
    "webhook_url": "https://lojaexemplo.com/webhooks/lunium"
  }'

const r = await fetch('https://api.luniumpay.com/keys', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Loja Exemplo',
    email: 'dev@lojaexemplo.com',
    webhook_url: 'https://lojaexemplo.com/webhooks/lunium',
  }),
});
const conta = await r.json();
// conta.api_key ← guarde AGORA (só aparece aqui)

import requests

r = requests.post("https://api.luniumpay.com/keys", json={
    "name": "Loja Exemplo",
    "email": "dev@lojaexemplo.com",
    "webhook_url": "https://lojaexemplo.com/webhooks/lunium",
})
conta = r.json()
# conta["api_key"] ← guarde AGORA (só aparece aqui)

Resposta 201:

{
  "api_key": "lun_9f2c40d1e8…",          // ← única vez que aparece
  "webhook_secret": "whk_5d1a…",          // se enviou webhook_url
  "key": {
    "key_id": 7, "prefix": "lun_9f2c40d1", "name": "Loja Exemplo",
    "cashin_enabled": true, "cashout_enabled": true,
    "fee_bps": 250, "fee_fixed_cents": 100,   // padrão da casa: 2,5% + R$ 1,00 — negociável por volume
    "rate_limit_per_minute": 60, …
  },
  "limits": { "tier": "Inicio", "daily_limit_cents": 500000, … },
  "monitor_url": "https://api.luniumpay.com/cashin/monitor?token=dsh_…",  // painel ao vivo só-leitura
  "telegram": {
    "bot": "@…",
    "link": "https://t.me/…?start=lk1a2b3c…",  // 1 toque = avisos em tempo real
    "hint": "Crie um grupo com o time e adicione o agente."
  },
  "docs": "https://docs.luniumpay.com"
}

Sua conta

Tudo sobre a sua chave: configuração, tier, limite diário (cash-in e payouts — a venda não tem), uso de hoje e vínculo do Telegram.

curl https://api.luniumpay.com/keys/me -H "X-API-Key: $LUNIUM_KEY"

{
  "key": { "key_id": 7, "prefix": "lun_9f2c40d1", "name": "Loja Exemplo",
           "cashin_enabled": true, "cashout_enabled": true,
           "webhook_configured": true, "telegram_linked": true, … },
  "limits": {
    "tier": "Crescimento",
    "daily_limit_cents": 2500000,
    "used_today_cents": 431000,
    "available_today_cents": 2069000,
    "settled_volume_cents": 9174350,
    "next_tier": { "tier": "Escala", "unlocks_at_settled_volume_cents": 50000000,
                    "daily_limit_cents": 10000000 }
  }
}

Atualiza name, settlement_address e webhook_url (enviar null limpa o campo). "rotate_webhook_secret": true gira o segredo — o novo vem na resposta, uma única vez.

curl -X PATCH https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{ "settlement_address": "0xAbC123…", "webhook_url": "https://lojaexemplo.com/wh" }'

Limites & tiers — progressivos por movimentação

A confiança é construída pelo volume. Toda chave nasce no tier Início e sobe automaticamente conforme liquida volume conosco. O pagador final é validado pelo nosso provedor PIX regulado — o seu teto é só uma régua de risco.

• O teto diário conta cash-in + payouts e renova à meia-noite (America/Sao_Paulo). O cash-out não entra nessa cota — ele tem limite por operação, não por dia.
• Fonte de verdade: os números desta página são referência; o que a API aplica vem em GET /keys/me → limits.per_operation (faixa por operação de cash-in, cash-out e payout), limits.payer_limits (escada por CPF/CNPJ) e limits.daily_limit_applies_to (o que consome a cota). Não fixe limite no seu código: leia daqui, que muda sem aviso.
• Operações em andamento contam no teto; expiradas/devolvidas liberam o espaço.
• Estourou? A API responde 403 com limits no corpo — mostre pro seu financeiro e tente no dia seguinte, ou acelere o upgrade liquidando volume.
• Seu tier atual, uso e próximo degrau: GET /keys/me ou /limites no bot.

Limite por pagador (CPF/CNPJ) NOVO

Além do teto da sua chave, existe uma segunda régua: a de cada CPF/CNPJ que paga. Ela protege você e a gente do mesmo problema — conta laranja, cartão/PIX roubado e teste de fraude entram sempre por um pagador novo, nunca por um recorrente. O CPF novo começa curto e cresce sozinho:

• O relógio começa no primeiro pagamento confirmado, não na primeira cobrança criada — gerar QR é grátis, pagar não. Assim ninguém "envelhece" um CPF só emitindo cobrança.
• O limite conta o que foi pago e o que está em voo (cobrança pendente ainda válida) — disponível = teto − pago − pendente. Vale desde a estreia: antes do 1º pagamento confirmado, o CPF/CNPJ pode ter no máximo R$ 60 em cobranças abertas ao mesmo tempo (agregado, não R$ 60 por QR) — abrir vários QRs não fura o teto. Expiradas não contam.
• Pagadores que já têm histórico com você já entram maduros — nada foi resetado.
• Vale nos dois modos de uso e é independente do seu tier: mesmo no Escala, um CPF estreando paga no máximo R$ 60 na primeira.

{
  "erro": "limite_do_pagador",        // ← ramifique por aqui (contrato de toda a API)
  "acao": "corrigir",
  "detail": "Nas primeiras 24h o CPF/CNPJ pode movimentar R$ 200,00. Já usou R$ 120,00; disponível: R$ 80,00…",
  "payer_limits": {
    "stage": "first_24h",
    "window_limit_cents": 20000,
    "used_cents": 12000,
    "available_cents": 8000,
    "matures_in_hours": 23
  },
  "code": "payer_limit"               // alias legado — sai do ar em 09/11/2026, ramifique por "erro"
}

Referência rápida

Todos os endpoints numa tabela. Base: https://api.luniumpay.com · autenticação por X-API-Key exceto onde indicado.

OpenAPI · Postman & Insomnia

Todos os endpoints num arquivo só. Importe o spec e você tem uma coleção pronta — com autenticação e exemplos — pra testar a API sem escrever nada.

https://docs.luniumpay.com/openapi.json

Cash-in — PIX entra, USDT sai

Seu cliente paga um PIX comum (QR copia-e-cola); a Lunium recebe, converte e envia USDT (Polygon) pro endereço que você indicar — o seu, fixo na chave, ou um por cobrança. Sem carteira conectada, sem fricção pro pagador.

Saldo em reais (custódia) — depositar e sacar por PIX

Chaves com custódia habilitada (custodia_ativa: true em GET /saldo) guardam reais para os clientes finais do parceiro — a aba "Depositar e Sacar" de um app de carteira. O livro-razão é append-only: saldo = soma dos movimentos.

curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"amount_cents":10000,"payer_tax_number":"12345678909","destino":"saldo","customer_ref":"user_42","chain":"polygon","asset":"usdt"}'
curl "https://api.luniumpay.com/saldo?customer_ref=user_42" -H "X-API-Key: $KEY"
curl -X POST https://api.luniumpay.com/payouts -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"amount_cents":5000,"pix_key":"12345678909","pix_key_type":"cpf","tax_number":"12345678909","customer_ref":"user_42","external_id":"saque-1"}'

Duas carências: o saldo aparece na hora, mas cada depósito só pode ser usado depois de carencia_horas (D+1); e o primeiro depósito de uma sub-conta trava qualquer saque por 24h (carencia_ate em GET /saldo; 423 carencia_primeiro_deposito nas duas rotas de saque). As cobranças trazem fonte (pix|saldo) e destino (cripto|saldo).

Nada é adiantado e nenhuma taxa é absorvida: o que o provedor cobra é o que o saldo paga. Custódia é habilitada por chave pelo suporte.

Cotação (read-only)

Quanto da stablecoin sai por um valor em BRL, sem criar nada. Já aplica a taxa da sua chave. Aceita asset: "usdt" (padrão) ou "usdc".

curl -X POST https://api.luniumpay.com/cashin/preview \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{ "amount_cents": 25000 }'

const quote = await lunium('POST', '/cashin/preview', { amount_cents: 25000 });

quote = lunium("POST", "/cashin/preview", {"amount_cents": 25000})

{ "asset": "usdt", "amount_cents": 25000,
  "admin_fee_bps": 250, "admin_fee_fixed_cents": 100,   // 2,5% + R$1 fixo
  "fee_total_cents": 723, "net_cents": 24277,        // taxa total e valor líquido
  "brl_per_usdt": "5.10", "usdt_amount": "47.558132" }

base = max(0, amount_cents − admin_fee_fixed_cents)   // a fixa sai primeiro
net_cents = floor(base × (10000 − admin_fee_bps) ÷ 10000)   // trunca, nunca arredonda
fee_total_cents = amount_cents − net_cents            // fixa + % juntas

Criar cobrança

curl -X POST https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 25000,
    "payer_tax_number": "12345678901",
    "payer_name": "Maria Souza",
    "payout_address": "0xAbC123…",
    "external_id": "pedido-8812"
  }'

const charge = await lunium('POST', '/cashin/charge', {
  amount_cents: 25000,
  payer_tax_number: '12345678901',
  payer_name: 'Maria Souza',
  payout_address: '0xAbC123…',
  external_id: 'pedido-8812',
});
mostrarQR(charge.qr_copypaste);   // já vem pronto pra tela

charge = lunium("POST", "/cashin/charge", {
    "amount_cents": 25000,
    "payer_tax_number": "12345678901",
    "payer_name": "Maria Souza",
    "payout_address": "0xAbC123…",
    "external_id": "pedido-8812",
})
mostrar_qr(charge["qr_copypaste"])

{
  "cashin_id": "ci_b3f9d2a41c6e8f5a90d7",
  "status": "pending",
  "amount_cents": 25000,
  "payout_address": "0xAbC123…", "chain": "polygon",
  "qr_copypaste": "00020126580014br.gov.bcb.pix…",   // PIX copia-e-cola
  "qr_image_url": "https://…/qr.png",
  "external_id": "pedido-8812",
  "expires_at": "2026-07-20T18:45:00.000Z"
}

Status da cobrança

Snapshot completo — inclui o hash on-chain quando o USDT sai.

curl https://api.luniumpay.com/cashin/ci_b3f9d2a41c6e8f5a90d7/status \
  -H "X-API-Key: $LUNIUM_KEY"

{
  "cashin_id": "ci_b3f9d2a41c6e8f5a90d7",
  "status": "paid",
  "settlement_status": "sent",
  "amount_cents": 25000,
  "depix_received_cents": 25000,          // o que REALMENTE entrou
  "usdt_amount": "46.040515",
  "settlement_tx_hash": "0x8ef1…",
  "settlement_tx_url": "https://polygonscan.com/tx/0x8ef1…",
  "payer_tax_number": "•••••••8901",      // sempre mascarado
  "paid_at": "2026-07-20T18:34:12.000Z",
  "settled_at": "2026-07-20T18:34:40.000Z", …
}

Listar cobranças

As cobranças da sua chave, mais recentes primeiro. Filtros: status, start/end, limit (máx. 200) e external_id (recuperação). Resposta: { "charges": [ … ] } no mesmo formato do status — perfeito pra conciliação diária.

Ciclo de vida do cash-in

Cash-out — cripto entra, PIX sai

O caminho de volta: você (ou seu cliente) envia cripto e uma chave PIX recebe reais. Fluxo em 3 passos: cotar → aceitar → depositar. Depois do depósito, é conosco: conversão e PIX saem sozinhos, com evento a cada transição.

Aceitamos USDT e USDC nas principais redes — Polygon com liquidação em segundos e Ethereum, BNB Chain, Arbitrum, Optimism, Base, Avalanche, TON, Aptos, NEAR e outras com o prazo da própria rede. Veja os dois caminhos e a tabela de prazos antes de escolher a rede.

Catálogo de ativos

Ativos, redes e limites correntes pro cash-out. É a fonte da verdade — o catálogo muda sozinho conforme redes entram e saem de manutenção, então leia dele em vez de fixar uma lista no seu código.

{
  "updatedAt": "2026-07-31T03:18:16.793Z",
  "fast": [ { "asset": "USDT", "network": "polygon" } ],   // liquidação em segundos
  "convert": [                                          // principais redes, prazo pela rede
    { "asset": "USDT", "networks": ["eth", "bsc", "arbitrum", …],
      "min": "10", "max": "200000", "precision": 8 }
  ],
  "dex": { "chains": ["polygon"], "note": "…" }
}

curl https://api.luniumpay.com/catalog -H "X-API-Key: $LUNIUM_KEY"

Dois caminhos de liquidação — escolha pelo prazo

O mesmo POST /cash-outs atende os dois; quem decide é o par asset + network que você mandar. A diferença que importa pro seu cliente é quando o PIX cai.

Redes e prazos estimados

Estimativas medidas pelas confirmações exigidas por rede. O min é por ordem (USDT 10 · USDC 20); o teto é 200.000 por ordem, respeitando o seu tier.

Tokens long-tail via DEX (Polygon). Símbolos se repetem — ao usar um token do /catalog/dex, mande também o token_address exato na cotação. O token é convertido on-chain antes do PIX, então o desfecho depende da liquidez do par.

Criar cotação

curl -X POST https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT", "network": "polygon", "amount": "50",
    "pix_key": "12345678901", "pix_key_type": "cpf",
    "external_id": "saque-2207"
  }'

const ordem = await lunium('POST', '/cash-outs', {
  asset: 'USDT', network: 'polygon', amount: '50',
  pix_key: '12345678901', pix_key_type: 'cpf',
  external_id: 'saque-2207',
});

ordem = lunium("POST", "/cash-outs", {
    "asset": "USDT", "network": "polygon", "amount": "50",
    "pix_key": "12345678901", "pix_key_type": "cpf",
    "external_id": "saque-2207",
})

{
  "cashout_id": "dede940b-6adb-4104-ac6b-979b1e84b1f5",
  "state": "QUOTE_CREATED",
  "asset": "USDT", "network": "polygon", "amount": "50",
  "brl_amount": "268.00",                // o PIX que a chave vai receber
  "pix_key": "123•••••901",               // sempre mascarada
  "expires_at": "2026-07-20T18:40:00.000Z"
}

Aceitar a cotação

Trava a cotação e devolve o endereço de depósito. Envie exatamente a quantidade cotada, na rede certa; em redes com memo/tag, inclua o deposit_tag.

{
  "cashout_id": "dede940b-6adb-4104-ac6b-979b1e84b1f5",
  "state": "AWAITING_DEPOSIT",
  "deposit_address": "0xDdE987…",          // mande a cripto pra cá
  "brl_amount": "268.00", …
}

Status & lista

Estado atual. Nosso worker também acompanha cada ordem 24/7 e dispara webhook/Telegram a cada transição — o polling é opcional, não obrigatório.

Ordens da sua chave, mais recentes primeiro. Resposta: { "cash_outs": [ … ] }.

Ciclo de vida do cash-out

Devolução — o que acontece em cada falha

Mande refund_address (a carteira do seu cliente, na rede da venda) em toda cotação. É o destino de qualquer devolução; sem ela, a cripto volta para a origem on-chain do depósito — e origem de saque de exchange é a carteira da exchange.

• Copia e cola no campo errado ou fora de USDT/USDC Polygon → recusado na cotação (pix_key_invalida / br_code_nao_suportado). Nada se move: ainda não existe endereço de depósito. Para pagar um QR use br_code.
• QR recusado pelo liquidante na hora de pagar (cobrança vencida, já paga, QR não reconhecido) → o liquidante devolve a cripto para a custódia da Lunium em segundos e ela segue para refund_address; MANUAL_REVIEW → REFUNDED com refund_tx_hash.
• Provedor recusa a chave depois do depósito (inválida/inexistente) → MANUAL_REVIEW (cashout.under_review); a cripto volta à custódia da Lunium e vai automaticamente para refund_address; termina REFUNDED (cashout.refunded) com refund_tx_hash. Devolve-se o líquido que o provedor devolveu.
• Falha antes do envio (provedor fora do ar, chave rejeitada na submissão) → retentado a cada 5 min por até 45 min; se não liquidar, o valor cheio (taxa inclusive) volta para refund_address; REFUNDED + hash.
• PIX revertido depois de pago (raro — conta destino bloqueada) → mesmo caminho: REFUNDED com refund_tx_hash.
• Depósito diferente do cotado → paga-se o valor realmente recebido. Token diferente fica em MANUAL_REVIEW.
• Depósito depois de expires_at → a ordem é revivida quando o depósito aparece (até 7 dias); senão MANUAL_REVIEW.
• Teto automático: 5.000 USDT por ordem; acima, uma pessoa da operação executa e você recebe REFUNDED + hash do mesmo jeito. A devolução sai sempre na rede e no token do depósito, do endereço de custódia da Lunium; o gas é nosso.

refund_address, refund_tx_hash e deposit_from vêm em GET /cash-outs/{id} e em todo webhook.

Depósitos incorretos e recuperação

Depois do accept, mande exatamente a quantidade cotada, no ativo e na rede cotados, em uma única transação, antes do expires_at. O motor tem uma faixa de tolerância — 90% a 105% do valor cotado — e, dentro dela, o PIX é calculado pelo que realmente chegou, não pelo que foi cotado. Fora dela, o depósito não é processado sozinho: fica retido e vira revisão manual. Nada é devolvido à origem on-chain automaticamente (mesma regra do refund).

Payouts — PIX direto em reais libera a R$ 1.000

O terceiro trilho da mesma chave: pagar qualquer chave PIX em BRL com um único POST — sem cripto na ponta, sem QR, sem aceite. Você manda o valor e a chave PIX do beneficiário; o PIX sai e você recebe o evento payout.sent (webhook + Telegram). Ideal pra plataformas que precisam pagar usuários, fornecedores ou comissões em reais.

Enviar um PIX

curl -X POST https://api.luniumpay.com/payouts \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 15000,
    "pix_key": "maria@exemplo.com", "pix_key_type": "email",
    "tax_number": "12345678901",
    "external_id": "comissao-042"
  }'

const payout = await lunium('POST', '/payouts', {
  amount_cents: 15000,
  pix_key: 'maria@exemplo.com', pix_key_type: 'email',
  tax_number: '12345678901',
  external_id: 'comissao-042',
});

payout = lunium("POST", "/payouts", {
    "amount_cents": 15000,
    "pix_key": "maria@exemplo.com", "pix_key_type": "email",
    "tax_number": "12345678901",
    "external_id": "comissao-042",
})

{
  "payout_id": "po_4c1d9e22ab37f0885a1c",
  "status": "processing",
  "amount_cents": 15000,
  "pix_key": "ma•••@exemplo.com", "pix_key_type": "email",
  "external_id": "comissao-042",
  "created_at": "2026-07-21T12:00:00.000Z"
}

Status & lista

Resposta da lista: { "payouts": [ … ] }. Os avisos chegam sozinhos por webhook e Telegram — polling é opcional.

Webhooks assinados

Configure a webhook_url (na criação da chave ou via PATCH /keys/me) e receba um POST a cada evento — cash-in e cash-out, mesma assinatura, mesmo formato:

POST {sua webhook_url}
Content-Type: application/json
X-Webhook-Signature: sha256=3f5a9c…              // v1 — HMAC do corpo bruto
X-Lunium-Signature:  t=1786153475,v1=8b21e4…     // v2 — HMAC de "t.corpo" (prefira esta)
X-Lunium-Event:      cashin.settled
X-Lunium-Event-Id:   evt_9c3f21a70b5e4d8812ff0a63
X-Lunium-Delivery-Id: dlv_4f0a72c1e8b5           // muda a cada tentativa
X-Lunium-Attempt:    1                           // >1 = voce ja pode ter recebido
X-Lunium-Timestamp:  1786153475

{
  "event": "cashin.settled",
  "event_id": "evt_9c3f21a70b5e4d8812ff0a63",   // estavel entre retentativas
  "created_at": "2026-07-20T18:34:41.000Z",
  "data": { …mesmo formato do endpoint de status… }
}

Guarde o event_id. Ele é a identidade do evento e não muda em retentativa — é o que garante que um retry nosso não vire crédito em dobro do seu lado. O X-Lunium-Delivery-Id é o contrário: identifica aquela tentativa, e é o número que você cita pra gente achar o envio exato. E trate evento desconhecido como no-op: a lista cresce sem aviso, e ignorar o que você não conhece é o comportamento correto.

Verifique a assinatura (sempre!)

Vão duas assinaturas, do mesmo segredo. A v1 (X-Webhook-Signature) assina só o corpo e continua valendo — se o seu handler já a verifica, não mude nada. A v2 (X-Lunium-Signature) assina "<timestamp>.<corpo bruto>" e existe por um motivo prático: como a v1 não tem hora dentro, ela vale para sempre — quem capturar uma entrega (um log de proxy, um endpoint que trocou de dono) pode reenviar aquele cashin.settled meses depois e você creditaria de novo. Com o timestamp dentro do HMAC você recusa o que for velho. Em integrações novas, use a v2.

Status da v1: descontinuada, com data marcada — desligamento em 9 de novembro de 2026 (segunda-feira). Até lá ela continua sendo enviada normalmente às integrações existentes e nada quebra. Chaves criadas a partir de 08/08/2026 já recebem somente a v2. Migre o handler para X-Lunium-Signature antes da data — o lembrete sai também no grupo de parceiros e na changelog.

import { createHmac, timingSafeEqual } from 'node:crypto';

// use o CORPO BRUTO (string/buffer), não o JSON re-serializado
// v2 — recusa entrega antiga, entao um replay nao te credita duas vezes
function assinaturaValida(corpoBruto, header, secret, toleranciaSeg = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header || ''));
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranciaSeg) return false;   // velho demais
  const esperada = createHmac('sha256', secret).update(`${m[1]}.${corpoBruto}`).digest('hex');
  const a = Buffer.from(esperada), b = Buffer.from(m[2]);
  return a.length === b.length && timingSafeEqual(a, b);
}

app.post('/webhooks/lunium', express.raw({ type: '*/*' }), (req, res) => {
  if (!assinaturaValida(req.body, req.headers['x-lunium-signature'], process.env.LUNIUM_WEBHOOK_SECRET))
    return res.status(401).end();
  const { event, event_id, data } = JSON.parse(req.body);
  if (jaProcessei(event_id)) return res.status(200).end();   // retry nosso nao credita 2x
  if (event === 'cashin.settled') creditar(data.external_id, data.usdt_amount);
  res.status(200).end();   // responda 2xx rápido; processe async
});

import hmac, hashlib, re, time

# v2 — recusa entrega antiga, entao um replay nao te credita duas vezes
def assinatura_valida(corpo_bruto: bytes, header: str, secret: str, tolerancia=300) -> bool:
    m = re.match(r"^t=(\d+),v1=([0-9a-f]{64})$", header or "")
    if not m or abs(time.time() - int(m.group(1))) > tolerancia:
        return False
    esperada = hmac.new(secret.encode(), f"{m.group(1)}.".encode() + corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, m.group(2))

# Flask
@app.post("/webhooks/lunium")
def lunium_webhook():
    if not assinatura_valida(request.get_data(), request.headers.get("X-Lunium-Signature"), SECRET):
        return "", 401
    evento = request.get_json()
    if ja_processei(evento["event_id"]):        # retry nosso nao credita 2x
        return "", 200
    if evento["event"] == "cashin.settled":
        creditar(evento["data"]["external_id"], evento["data"]["usdt_amount"])
    return "", 200

• Entrega: retry com backoff exponencial: 12 tentativas, esperando 2ⁿ minutos com teto de 60 — ~7 horas no total, não um dia. Qualquer 2xx encerra. Cada destino é tentado em paralelo: um endpoint seu fora do ar não atrasa os eventos de mais ninguém.
• Dedupe: cada par (operação, evento) dispara uma vez. Do seu lado, deduplique pelo event_id.
• Nada se perde em silêncio: esgotadas as tentativas, a entrega fica como failed em GET /webhooks/deliveries e você a recupera com o retry abaixo. Nossa operação também é avisada na hora — antes, um evento podia morrer sem ninguém saber.
• webhook_url precisa ser https e apontar para endereço público da internet.
• Segurança: rejeite assinatura inválida com 401; nunca processe sem verificar.

Teste o seu handler antes do primeiro real

Não descubra que o endpoint estava errado quando o primeiro PIX de verdade não chegar:

curl -X POST https://api.luniumpay.com/webhooks/test \
  -H "X-API-Key: $LUNIUM_KEY"

// resposta — o que o SEU endpoint respondeu, medido por nós
{ "ok": true, "status_code": 200, "ms": 180,
  "event_id": "evt_…", "delivery_id": "dlv_…", "url": "https://seu.app/webhooks/lunium" }

Dispara um evento webhook.test pelo mesmo transporte da produção — mesmas assinaturas, mesmos headers —, então o que passar aqui passa lá. Não move dinheiro, não entra na fila e funciona também com chave de sandbox. Máximo de 6 por minuto.

O que saiu, o que falhou, e como recuperar

GET  /webhooks/deliveries?status=failed        // tambem: ?event=&limit=
POST /webhooks/deliveries/{event_id}/retry     // reenvia agora

A lista devolve status (pending · sent · failed), attempts, last_error e um failed_count — você não precisa saber filtrar pra descobrir que perdeu evento. O retry tenta na hora e responde com o resultado; se falhar de novo, a entrega volta pra fila com 12 tentativas novas. O que já foi confirmado com 2xx é recusado com 409 ja_entregue, pra você não duplicar sem querer.

Nota de design: o retry é endereçado pelo event_id porque hoje cada evento tem exatamente um destino (uma webhook_url por chave) — evento e entrega são 1:1. O delivery_id identifica cada tentativa de envio. Se um dia houver múltiplos destinos por evento, nascerá uma rota por entrega — esta continua valendo.

Agente no Telegram — operação e suporte

Cada cliente da Lunium tem um agente de verdade no Telegram: uma IA (Claude, via API, com acesso às ferramentas da conta), não um menu de botões. Ele cria credenciais, opera por linguagem natural, notifica em tempo real e tira dúvidas de integração — sempre com a sua chave, isolado por cliente (multi-tenant).

• Credencial no chat. Diga "meu nome é SuaEmpresa" (ou /criarchave) e a chave de API nasce ali, com cash-in e cash-out liberados. Self-service, em escala — ninguém da Lunium gera credencial por você.
• Opera por linguagem natural, com confirmação. Peça "cobra R$ 250 do CPF …" ou "saca 25 USDT pra minha chave PIX": o agente lê os dados reais da sua conta, monta a operação e pede um toque de confirmação antes de qualquer movimento. Dinheiro nunca se move sem o seu OK.
• Notifica em tempo real. Cada PIX que entra, cada moeda comprada e vendida (com link do Polygonscan), cada PIX que sai, revisões e falhas — no segundo em que acontecem.
• No grupo do seu projeto (recomendado pra times). Crie um grupo (ex.: Lunium SeuProjeto), adicione o agente e um admin vincula a chave: o time inteiro passa a receber os avisos e a consultar — cada grupo escopado à sua chave, com credenciais e segredos sempre reservados ao privado.
• Monitor ao vivo. /monitor abre um painel web em tempo real do seu fluxo (cash-in, cash-out, payouts) — só-leitura e compartilhável com o time. Também no monitor_url da sua chave. Vazou o link? PATCH /keys/me com {"rotate_monitor_token": true} gira o token — a URL antiga para de mostrar dados na hora e a nova vem na resposta.
• Suporte 24/7. Texto livre — "como valido a assinatura do webhook?", "tô tomando 401" — e o agente responde na hora, com exemplos, treinado nesta documentação.

O link do seu agente vem na resposta do POST /keys (campo telegram.link) e no GET /keys/me — um toque e o chat está vinculado. Os comandos abaixo funcionam também por linguagem natural.

Quem pode o quê — permissões do agente

O agente atende no seu privado (DM) e no grupo vinculado. As regras não são as mesmas nos dois — e vale entender antes de adicionar gente ao grupo:

Papéis nomeados (Owner · Admin · Operator · Viewer) com capacidades por papel estão no nosso roteiro para times maiores. Hoje o modelo é o da tabela acima: consulta e operação para o grupo, config para admin, confirmação sempre presa a quem pediu.

Chave sem passar por um humano

Se uma ferramenta respondeu erro: "chave_ausente", um agente não precisa parar e pedir credenciais. POST /keys/sandbox devolve uma chave lun_test_ numa chamada, sem autenticação e sem formulário — pelo MCP, a mesma coisa é a ferramenta lunium_create_sandbox_key, que não exige chave nenhuma.

Ela roda o cash-out na mesma URL base da produção e nada liquida (cash-in e payouts não são simulados). Deixe claro ao usuário que é chave de teste: mover dinheiro real exige chave de produção, e isso é decisão de humano.

O que esperar, em números que medimos

São medições, não promessas — colhidas em 02/08/2026 contra o serviço no ar.

Erros

O contrato de erro é: erro (código estável, que não muda quando o texto muda), acao (o que fazer) e detail (texto para humano — nunca ramifique por ele). Erros de limite trazem também limits, já convertido na moeda da sua ordem. Conectividade sem auth: GET /ping → {"ok":true,"msg":"pong"}.

{ "erro": "limite_diario",
  "acao": "esperar",
  "detail": "Essa cobrança (R$ 900.00) estoura seu limite diário. Disponível hoje: R$ 450.00.",
  "limits": { "daily_limit_cents": 500000, "used_today_cents": 455000 } }

As quatro ações

Essa distinção existe porque duas situações opostas devolviam a mesma resposta: uma ordem maior que a cota de um dia inteiro respondia “tente amanhã” — e amanhã falhava igual, para sempre.

Todos os códigos

Os mesmos códigos saem do sandbox e da produção. Código que ramifica por erro no sandbox continua funcionando quando você troca a chave.

{ "detail": "Essa cobrança (R$ 900.00) estoura seu limite diário. Disponível hoje: R$ 450.00. …",
  "limits": { "daily_limit_cents": 500000, "used_today_cents": 455000, "available_today_cents": 45000 } }

Por código HTTP

Autenticação & disponibilidade (qualquer rota)

Chaves (/keys)

Cash-in (/cashin)

Cash-out (/cash-outs, /catalog)

Payouts (/payouts)

Rate limits

• 60 requisições/min por chave (token bucket, suave). Excedeu → 429.
• POST /keys: 5 chaves/dia por IP.
• Cotações de cash-out têm um teto global de proteção; sob pico, 503 — repita em segundos.
• Precisa de mais? Fale com a gente — limite por chave é configurável.

Você não precisa adivinhar o orçamento. Toda resposta autenticada carrega o estado atual nos headers — leia-os em vez de bater no teto para descobrir:

X-RateLimit-Limit: 60        // seu teto por minuto (= rate_limit_per_minute)
X-RateLimit-Remaining: 42    // quantas ainda cabem agora
X-RateLimit-Reset: 18        // segundos até o balde encher de novo

No 429, vai também Retry-After: <segundos> — espere isso antes de repetir, com backoff. O corpo traz erro: "rate_limit", acao: "esperar".

Regras que evitam erro caro

Cada uma destas já custou dinheiro — a alguém, aqui. Estão na doc principal para não custar ao seu.

Cobrança de valor fixo não aceita “quase”

Um QR de cobrança concilia por valor exato e pelo txid que vive dentro do BR Code. Pagar R$ 0,59 a mais é tão invisível quanto R$ 0,59 a menos: o dinheiro chega e a venda continua “não paga”. Se você repassa um copia-e-cola ao seu cliente, mande o BR Code inteiro — não apenas a chave PIX extraída dele. A chave sozinha vira uma transferência avulsa, sem txid, e nenhuma conciliação automática encontra.

expires_at manda no prazo, não o seu código

Leia sempre o expires_at da resposta. Hoje são ~15 minutos em Polygon e até 300 em outras redes, mas isso muda com a rede e com o provedor. Janela fixa no cliente é a origem clássica do “paguei e expirou”.

Datas: ISO 8601 em UTC.

Toda data da API sai em ISO 8601 em UTC, terminando em Z: 2026-08-01T22:35:49.123Z. Nunca trate como hora local — converta no seu lado. A única exceção é a cota diária da chave, que é apurada no fuso de Brasília (America/Sao_Paulo) e por isso vira à meia-noite daqui, não à meia-noite UTC. Um horário lido errado vira “pagamento fora do prazo” numa discussão com o lojista — e o comprovante é documento.

delayed não é falha

O PIX foi pago e o provedor está segurando a liberação — comum na primeira operação de um pagador novo. A resposta traz delay_until. Não cancele e não crie uma segunda cobrança: ela vira paid sozinha, e a segunda cobrança vira dinheiro em duplicidade para conciliar na mão.

Ausência não é prova de ausência

nao_encontrado na verificação de um E2E significa que a Lunium não liquidou aquele pagamento — não que o PIX não aconteceu. Outra instituição pode tê-lo liquidado. Relate essa diferença ao seu usuário em vez de alegar fraude.

external_id em toda escrita

E a chave de reconciliacao e o que torna a chamada idempotente: repetir devolve a mesma ordem em vez de criar outra. Reusar o mesmo id com parametros diferentes devolve a ordem original e responde external_id_divergente — de proposito, para voce nao achar que atualizou algo que nao mudou.

Idempotência

Envie o seu id de pedido em external_id (cash-in e cash-out). Repetiu a chamada com o mesmo external_id e os mesmos parâmetros? Volta a mesma operação (200) — sem duplicar cobrança nem ordem. Mesmo id com parâmetros diferentes → 409. É a sua proteção contra timeout + retry.

Segurança

Conciliação diária

Como bater o seu dia com o nosso, sem planilha manual:

1. Amarre tudo com external_id (o id do SEU sistema) em cobranças, cash-outs e payouts — é a chave primária da conciliação.
2. Puxe a janela do dia: GET /cashin/charges?start=2026-07-21&end=2026-07-22, GET /cash-outs?limit=200 e GET /payouts?limit=200.
3. Confira pelos campos fonte-da-verdade: no cash-in, o valor que vale é depix_received_cents (o que realmente entrou) e settlement_tx_hash (prova on-chain); no cash-out, state = COMPLETED; no payout, status = sent.
4. Webhooks são gatilho, a API é extrato: processe eventos de forma idempotente e reconcilie pela listagem — nunca dependa só do webhook pra fechar caixa.

Boas práticas (o checklist de produção)

• ✅ Chave só no servidor; front-end nunca vê X-API-Key.
• ✅ Credite pelo webhook assinado (cashin.settled / cashout.completed), com verificação de HMAC.
• ✅ Use external_id em toda operação (idempotência grátis).
• ✅ Valores: centavos (int) no cash-in, string decimal no cash-out — nunca float.
• ✅ Trate 429/5xx com retry + backoff exponencial (1s, 2s, 4s…).
• ✅ Vincule o Telegram — é o seu monitor em tempo real de graça.
• ✅ Confie no depix_received_cents, não no valor cotado.

Exemplo completo — checkout PIX → USDT

Um helper mínimo e o fluxo inteiro (criar cobrança → acompanhar → creditar via webhook):

// lunium.js — helper de 15 linhas, zero dependências (Node 18+)
const BASE = 'https://api.luniumpay.com';
export async function lunium(method, path, body) {
  const r = await fetch(BASE + path, {
    method,
    headers: {
      'X-API-Key': process.env.LUNIUM_KEY,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await r.json();
  if (!r.ok) throw new Error(data.detail || `HTTP ${r.status}`);
  return data;
}

// 1) cliente clicou em "pagar com PIX"
const charge = await lunium('POST', '/cashin/charge', {
  amount_cents: pedido.totalCents,
  payer_tax_number: cliente.cpf,
  payer_name: cliente.nome,
  external_id: pedido.id,            // idempotência
});
render(charge.qr_copypaste);          // 2) mostra o copia-e-cola

// 3) crédito REAL chega pelo webhook assinado (veja a seção Webhooks):
//    event === 'cashin.settled'  →  liberar o pedido data.external_id

import os, requests

BASE = "https://api.luniumpay.com"

def lunium(method, path, body=None):
    r = requests.request(method, BASE + path, json=body,
                         headers={"X-API-Key": os.environ["LUNIUM_KEY"]})
    data = r.json()
    if not r.ok:
        raise RuntimeError(data.get("detail", f"HTTP {r.status_code}"))
    return data

# 1) cria a cobrança
charge = lunium("POST", "/cashin/charge", {
    "amount_cents": pedido.total_cents,
    "payer_tax_number": cliente.cpf,
    "payer_name": cliente.nome,
    "external_id": pedido.id,
})
mostrar(charge["qr_copypaste"])       # 2) exibe o PIX

# 3) credite no webhook 'cashin.settled' (seção Webhooks)

Idempotência & recuperação por external_id

Um número que resolve os dois piores momentos de uma integração de pagamento: o retry que não pode cobrar/pagar duas vezes, e o 500/timeout em que você não sabe se a operação existiu.

Mande external_id em toda operação de escrita — cash-in, cash-out e payout. É a sua chave de conciliação, e o contrato é o mesmo nos três:

Recuperação: descubra a verdade após um erro

Levou 500, timeout ou perdeu a resposta? Não repita às cegas — pergunte. A mesma chave de idempotência é a chave de leitura:

GET /cashin/charges?external_id=pedido-8812
GET /cash-outs?external_id=saque-2207
GET /payouts?external_id=comissao-042

Cada um responde 200 com a lista do produto: um elemento se a operação existe (com o estado atual), lista vazia se não existe — e aí é seguro criar de novo com o mesmo external_id. O índice único garante 0 ou 1 resultado. É o antídoto para o caso do payout em que "o PIX pode ter saído mas a resposta se perdeu": você consulta e sabe.

Antes da primeira cobrança real

Sete conferências. Cada uma existe porque já custou dinheiro ou uma madrugada de alguém — não é formalidade.

1. Teste o webhook com POST /webhooks/test e confirme 2xx. É a diferença entre descobrir que o handler está errado agora ou quando o primeiro PIX não chegar.
2. Verifique a assinatura (X-Lunium-Signature) e recuse o que tiver mais de ~5 minutos. Nunca processe evento sem verificar.
3. Deduplique por event_id. Retentativa nossa é normal; crédito em dobro não.
4. Mande external_id em toda ordem. É a chave de conciliação e o que torna a chamada idempotente — repetir devolve a mesma ordem em vez de criar outra.
5. Ramifique por erro e acao, nunca pelo texto. detail é para humano e muda sem aviso.
6. Leia os limites de GET /keys/me (per_operation e payer_limits) em vez de fixar valores no seu código — eles sobem sozinhos com o seu volume.
7. Entre no grupo de parceiros. É onde mudança de contrato é anunciada antes de ir ao ar, e onde você fala com a gente quando não pode esperar.

Sandbox não cobra nada e não move dinheiro: POST /keys/sandbox devolve uma chave lun_test_… na hora, e os 7 itens acima podem ser exercitados inteiros lá.

Versionamento & changelog

Política de compatibilidade: mudanças aditivas (novos campos em respostas, novos eventos, novos códigos de erro, novos endpoints) acontecem sem aviso — escreva seu parser para ignorar campos desconhecidos e trate evento ou código desconhecido pelo que o acao mandar. Mudanças que quebram contrato (remover ou renomear campo, mudar semântica) são anunciadas com antecedência.

Onde o aviso sai, em ordem de alcance: no grupo de parceiros no Telegram, no bot da sua chave e nesta tabela. Se você cadastrou e-mail em POST /keys, também por e-mail — mas a maioria das chaves não tem e-mail, então não conte só com ele: entre no grupo.

A OpenAPI é o contrato. info.version em openapi.json sobe em MINOR a cada adição compatível e em MAJOR se algo quebrar. Um teste automático confere, a cada 6 horas, se a produção ainda cumpre o que aquele arquivo promete — quando diverge, nós somos avisados antes de você.

Suporte & contato

⬡ Lunium — o hub PIX ↔ stablecoin. Esta documentação descreve o comportamento vigente da API em produção; mudanças que quebram contrato são anunciadas com antecedência no grupo de parceiros, no bot da sua chave e na changelog.

AMBIENTE: PRODUÇÃO · MONITORAMENTO 24/7 · CONTATO@LUNIUMPAY.COM