Manual de integração

1. Escolha o fluxo#

Custódia é um saldo em reais. O parceiro recebe o líquido do PIX e escolhe a moeda e a rede no saque. Não é necessário cadastrar uma carteira fixa. Um depósito em custódia não cria saldos simultâneos em BTC, ETH e USDT.

Atenção ao padrão de cada canal: na API, omitir destino continua significando cripto. Para receber em custódia, envie destino: "saldo". No Telegram, /cobrar valor cpf já usa custódia por padrão.

2. Chaves e configuração#

Entre no Lunium Partners, a comunidade oficial de integradores. A participação é fortemente recomendada desde o início da integração: é onde compartilhamos avisos operacionais, manutenções, mudanças de API e troca entre parceiros. Entenda como usar a comunidade junto do grupo dedicado e do monitor.

Base: https://api.luniumpay.com. Nas rotas autenticadas, envie X-API-Key e, nos corpos JSON, Content-Type: application/json. Use a chave no seu servidor; ela autoriza operações sobre a conta.

Sandbox

curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"email":"voce@empresa.com","name":"Minha integração de teste"}'

Troque voce@empresa.com pelo e-mail de quem vai testar: email é obrigatório. Cerca de um minuto depois, o suporte da LuniumPay envia para esse endereço, uma única vez, o que é a LuniumPay, a integração em 3 passos, o manual e o PDF, o fluxograma e o VendaCripto (app pronto para quem só quer comprar ou vender cripto com PIX, sem integrar). Uma mensagem por endereço, com link de descadastro. Sem email válido, a resposta é 400 com erro: "email_obrigatorio". Continua sendo uma chamada, sem aprovação e sem chave de API; name é opcional.

Guarde api_key como LUNIUM_API_KEY no ambiente do seu servidor. Chaves novas de teste têm prefixo lun_test_; as de produção, lun_live_. Chaves antigas lun_ continuam válidas.

O sandbox simula PIX de entrada, crédito em custódia BRL, entrega e saque de cripto, payout PIX, transferências internas e cash-out. O QR é não pagável: confirme em POST /sandbox/cashin/{cashin_id}/pay. Nenhum banco, corretora ou blockchain é acionado. Consulte o guia de sandbox e GET /sandbox para cenários, persistência e diferenças de produção. Custódia não exige carteira fixa.

Produção sem carteira fixa

curl --fail-with-body https://api.luniumpay.com/keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"Meu projeto","email":"operacao@example.com"}'

Troque nome e e-mail pelos seus. A resposta traz api_key, key, limits, monitor_url e as instruções de Telegram. A chave completa só é apresentada na criação. monitor_url é o painel de acompanhamento; trate também esse link como informação privada do projeto.

Chaves de produção novas são criadas com custódia e payouts habilitados. A situação da sua chave é a que vale: consulte payout.enabled em GET /keys/me e custodia_ativa em GET /saldo.

curl --fail-with-body https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_API_KEY"

curl --fail-with-body https://api.luniumpay.com/saldo \
  -H "X-API-Key: $LUNIUM_API_KEY"

Configure um receptor HTTPS de webhooks por PATCH /keys/me com webhook_url; guarde o webhook_secret devolvido. settlement_address é uma opção para entrega direta em Polygon. Não é requisito para custódia e não define os destinos dos saques futuros.

Reutilize sua chave de teste: criação de chaves tem limites por IP. Em 429, respeite o prazo indicado. Não crie uma chave por operação.

Recuperar o monitor e cuidar dos acessos

O monitor privado acompanha o projeto em modo de leitura. A chave de API autoriza operações. O link do monitor, a chave de API e o segredo do webhook são credenciais diferentes; recuperar um deles não recupera os demais.

Se perdeu o link, solicite-o para o e-mail cadastrado na chave de produção:

curl --fail-with-body https://api.luniumpay.com/keys/painel-link \
  -H 'Content-Type: application/json' \
  -d '{"email":"operacao@example.com"}'

Essa rota não exige chave. A resposta 200 {"ok":true,...} é genérica para proteger o cadastro: não confirma a existência da conta nem a entrega do e-mail. Confira entrada e spam. Em 429, aguarde; não automatize pedidos sucessivos. Se o e-mail estiver incorreto ou inacessível, procure os contatos humanos do projeto para validar a recuperação.

Com a chave disponível, GET /keys/me devolve monitor_url. Para invalidar um link exposto, use PATCH /keys/me com {"rotate_monitor_token":true} e distribua o novo link apenas à equipe autorizada. O link anterior deixa de funcionar imediatamente. Isso não troca a chave da API nem o segredo do webhook.

A chave completa só é apresentada na criação. Este procedimento não reexibe nem recupera a chave. Se ela foi perdida ou exposta, acione o suporte para tratar substituição/revogação e continuidade da conta. Não crie outra chave presumindo que saldo, cobranças ou vínculos serão transferidos automaticamente. Para trocar o segredo do webhook, siga o roteiro próprio.

Monitor atual e evolução do painel

Nesta revisão, o caminho documentado de acompanhamento é o monitor privado, o feed e as rotas públicas do contrato. Recursos adicionais de painel e múltiplos destinos de webhook só devem ser integrados quando estiverem publicados e validados em produção. Configure o receptor documentado em PATCH /keys/me; não presuma uma API pública de vários destinos nem rotas de login/2FA a partir de anúncios de desenvolvimento.

Para Fable e outras IAs: confira a versão e o inventário revisados junto do OpenAPI. Se houver divergência, registre qual fonte e operação divergem e suspenda a implementação daquela capacidade até esclarecer; não invente uma rota para completar o fluxo.

Novo painel do parceiro

O painel do parceiro fica em parceiros.luniumpay.com, com o mesmo login (e-mail e senha). Também dá para entrar com um código enviado por e-mail ou com a conta Google; quem ainda não tem acesso usa Criar conta. O painel serve para a sua equipe operar e acompanhar o projeto. A integração continua pela API, com a chave do projeto: as telas do painel usam a sessão de quem entrou e não fazem parte do contrato público da API.

• Início: resumo do negócio por período (Pix recebido, vendas de cripto, Pix enviado, saques em cripto e comissão), situação das cobranças, das vendas e dos pagamentos, e calendário.
• Comprovantes: PDF nas vendas, nos Pix enviados e nas cobranças.
• Pagar com cripto: escolha entre as stablecoins (USDT e USDC em todas as redes, mais DePix) e as 30 principais criptos, com busca e ícones. A carteira de devolução só é pedida se a venda falhar (Carteira de devolução).
• Carteira USDT/USDC: depósito com QR Code do endereço e contagem regressiva do prazo de 1 hora; Pix pago com o saldo. Detalhes em Carteira USDT/USDC.
• Comissão: saque a partir de US$ 10.
• Notificações: sino com a atividade do projeto e avisos de cada operação pelo Telegram e por e-mail.
• Equipe: papéis Dono, Financeiro, Operador, Desenvolvedor e Leitura; segundo fator em Meu acesso.
• Meu acesso: o botão Encerrar as outras sessões fecha o painel nos outros aparelhos e mantém a sessão atual. Conta sem senha (entrada por código ou Google) desliga a verificação em dois passos com o código do app autenticador ou com um código de recuperação. Na troca de senha, a senha atual tem limite de 10 tentativas erradas por hora, e um e-mail avisa sempre que a senha é trocada, criada ou redefinida.
• Webhooks: Reenviar agora repete a entrega de um evento pelo próprio painel.
• Legibilidade: mais contraste e letras maiores, “Pix” com a mesma grafia em todas as telas, títulos iguais aos do menu e mensagens de erro em português claro.

Ativação de conta nova. Ao ativar o painel com um e-mail que ainda não tem conta (pelo link que chega pelo bot ou por e-mail, ou com a chave do projeto), você recebe nesse e-mail um código de 6 dígitos para confirmar. O código vale 30 minutos e aceita até 5 tentativas; Reenviar código libera um código novo depois de 1 minuto, até 5 vezes; só o mais recente vale. E-mail que já tem conta continua confirmando com a senha da conta.

Convite para quem entra por código ou Google. A conta sem senha aceita convite assim: entre no painel com o e-mail convidado e abra o link do convite de novo; com a sessão aberta, ele é aceito num clique.

Regras de segurança do painel:

• Só o papel Dono vê o link e o código de vínculo do Telegram, desconecta conversas e gera um código novo. O código troca sozinho quando alguém perde o acesso, deixa de ser dono ou quando uma conversa é desconectada.
• Quando alguém deixa de ser dono, os outros donos recebem um e-mail para revisar, em Notificações, as conversas do Telegram conectadas: elas continuam ligadas até um dono desconectá-las.
• A conversa conectada também consulta o saldo e movimenta dinheiro pelo bot: no privado, quem conectou; no grupo, os administradores. Conecte só conversas de confiança.
• Pelo painel, só o Dono troca a carteira de liquidação (settlement_address) e as sub fees (partner_fee_bps, partner_cashout_fee_bps, partner_saque_fee_bps). O papel Desenvolvedor continua ajustando webhook, nome e monitor.
• A sessão vale 12 horas e se renova enquanto você usa o painel, até 7 dias desde a entrada. O cookie de sessão é protegido e as páginas têm política de segurança de conteúdo.

3. Cobrar PIX para a custódia#

Criar a cobrança

Consulte antes GET /cashin/limits?payer_tax=CPF_OU_CNPJ, autenticado com a chave do projeto. O documento é de quem pagará o PIX; customer_ref identifica a subconta do seu sistema. São informações diferentes.

O exemplo usa R$ 50,00. Substitua documento e referência e escolha um valor permitido para esse pagador. A chamada em produção cria uma cobrança real.

curl --fail-with-body https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_cents":5000,
    "payer_tax_number":"00000000191",
    "destino":"saldo",
    "customer_ref":"cliente-42",
    "external_id":"deposito-cliente42-001"
  }'

Não envie payout_address para esse fluxo. Sem customer_ref, o crédito pertence ao saldo da própria chave, chamado casa. Com a referência, pertence somente àquela subconta.

Guarde cashin_id e external_id. Apresente qr_copypaste, qr_image_url quando disponível, o valor e o expires_at devolvidos. QR gerado significa cobrança criada; ainda não significa dinheiro recebido.

Confirmar o crédito

Use GET /cashin/{cashin_id}/status ou os eventos de webhook. Acompanhe dois estados:

Considere o crédito/entrega concluído em cashin.settled ou ao consultar status: "paid" com settlement_status: "sent". Em custódia, confirme o montante e a disponibilidade em GET /saldo?customer_ref=cliente-42 e no extrato. Um crédito registrado pode estar bloqueado por uma retenção; não gaste total_cents como se fosse disponivel_cents.

depix_received_cents é o valor recebido do liquidante, antes da dedução das taxas de depósito da chave. O nome é legado e não implica que o crédito líquido do cliente seja esse valor. Para conciliação, use os movimentos do saldo.

Taxa de depósito e disponibilidade

GET /saldo publica deposito_fee_bps, deposito_fee_fixed_cents, carencia_horas, carencia_ate, retencao_acima_cents e proximas_liberacoes. 100 bps = 1%. Novos depósitos têm deposito_fee_bps=0 e deposito_fee_fixed_cents=100, sem comissão do parceiro.

Há três conceitos separados:

held_hours e hold_hours não são aliases. Uma cobrança pode ter held: false e ainda estar sob retenção local. Não prometa liberação imediata a partir desse booleano isolado.

Não existe carência universal de 24 horas para todos os parceiros. Chaves com liberação imediata do saldo têm regra própria, mas continuam sujeitas às retenções do pagador, da cobrança e a bloqueios. Leia a criação, o status e o saldo em conjunto; um saque recusado por carência devolve 423 e o momento de liberação.

Limites por pagador

GET /cashin/limits publica a faixa de liberação imediata, a possibilidade de QR com retenção, a utilização e a próxima liberação do documento. As condições da chave podem alterar a régua. A consulta é orientativa: a criação revalida a operação, inclusive o fluxo de custódia com liberação imediata.

allow_hold: false recusa a cobrança quando ela precisaria da retenção calculada pelo limite do pagador. Não desativa outras regras contratuais nem bloqueios posteriores. Omitir o campo permite a retenção aplicável. Mostre essas condições antes do pagamento.

O mínimo efetivo também depende das taxas e do provedor. Não use R$ 1,00 como teste universal nem confunda o mínimo global com o mínimo aceito pela rota.

4. Saldo, subcontas e extrato#

Reutilize exatamente o mesmo customer_ref no depósito, nas consultas e no saque. O limite é de 80 caracteres. Essa referência separa os saldos; a chave da API continua tendo autoridade sobre todas as suas subcontas. A autorização dos seus usuários deve existir também no seu sistema.

Transferência interna, sem gerar PIX, por POST /saldo/transferir:

{
  "amount_cents":1000,
  "from_customer_ref":"cliente-42",
  "to_customer_ref":"casa",
  "external_id":"transferencia-interna-001",
  "descricao":"Transferência autorizada pelo cliente"
}

casa representa o saldo sem subconta. Só o disponível pode ser transferido; carência da subconta de origem continua sendo aplicada. Saldo insuficiente nessa rota retorna 409 saldo_insuficiente; nas rotas de saque, normalmente 402.

5. Sacar o saldo em cripto#

1. Consulte GET /saldo no escopo correto.
2. Consulte GET /cashin/catalog: é o catálogo de entrega, usado também no saque da custódia.
3. Ofereça pares de instant e convert com entregavel: true. Para saque do saldo, exclua Liquid/DePix, que não são suportados nesse fluxo.
4. Selecione moeda, rede, carteira de destino e memo/tag quando necessário. A carteira pode mudar a cada saque.
5. Envie POST /saldo/sacar-cripto e acompanhe o cashin_id devolvido em GET /cashin/{cashin_id}/status.

Corpo ilustrativo; substitua carteira e documento antes de enviar:

{
  "amount_cents":10000,
  "asset":"usdt",
  "chain":"polygon",
  "payout_address":"0x1111111111111111111111111111111111111111",
  "tax_number":"00000000191",
  "customer_ref":"cliente-42",
  "external_id":"saque-cripto-cliente42-001"
}

amount_cents é o valor em BRL a converter, não a quantidade de cripto. O documento tax_number é do cliente que saca. Para redes com memo, envie payout_tag conforme a carteira recebedora e memoRequired do catálogo. Os aliases memo, tag e destination_tag são aceitos.

A resposta traz fonte: "saldo", destino: "cripto", fee_cents e debited_cents. O débito inclui o valor mais a taxa de saque da casa. A quantidade final de cripto também considera conversão e custos de entrega; não calcule o recebido dividindo apenas o débito por uma cotação de mercado.

GET /saldo informa saque_cripto_fee_bps. POST /cashin/preview ajuda a consultar a conversão e o mínimo da rota, mas não é uma prévia completa do débito do saque. A prévia de saque utilizada pelo Telegram é interna; não existe uma rota pública /saldo/sacar-cripto/preview.

O campo opcional max_debited_cents permite limitar o débito de BRL: se a soma superar o limite, a API recusa com 409 taxa_alterada. Ele não fixa a cotação nem garante uma quantidade mínima de tokens.

Não anuncie “todas as criptos” de forma irrestrita: as opções são os pares entregáveis do catálogo atual, sujeitos a mínimos, manutenção e validação de endereço. stale: true indica catálogo de contingência; revalide antes de confirmar.

6. Sacar o saldo por PIX#

POST /payouts reserva e debita o disponível da casa ou da subconta antes de enviar o PIX. São necessários payout.enabled, custódia ativa e saldo para valor mais taxas.

{
  "amount_cents":5000,
  "pix_key":"recebedor@example.com",
  "pix_key_type":"email",
  "tax_number":"00000000191",
  "customer_ref":"cliente-42",
  "external_id":"saque-pix-cliente42-001"
}

Troque a chave PIX e o documento pelos do recebedor. tax_number deve conter um CPF ou CNPJ válido para chaves de e-mail, telefone e aleatória. Para uma chave CPF/CNPJ válida, a API deriva o documento da própria chave; se informado, deve coincidir. beneficiary_name continua opcional e não comprova titularidade. Chaves de 11 dígitos exigem pix_key_type: "cpf" ou "phone"; telefone usa DDI, como +55.

Este fluxo usa somente saldo em reais recebido por PIX. funding_source é opcional e aceita apenas pix_brl. O máximo por PIX é 600000 centavos (R$ 6.000,00), sujeito a limite menor da conta, além das taxas.

Em 409 external_id_divergente ou external_id_nao_verificavel, consulte a ordem indicada por payout_id/recovery_endpoint. Preserve o identificador; não gere outro para contornar o conflito. Em 503 idempotencia_indisponivel, aguarde e consulte o mesmo external_id: uma ordem anterior pode existir.

A carteira USDT é separada do saldo BRL: requer habilitação do projeto, recebe depósitos externos de USDT e não usa /payouts. Quando habilitada, usa funding_source=crypto_usdt; documento do recebedor não é exigido nesse fluxo. Seus limites vêm da cotação e das condições da API, não do teto de R$ 6.000 do saldo BRL. Não está disponível em sandbox.

Preço: amount_cents + fee_cents, com fee_cents = fee_service_total_cents + fee_provider_cents. Consulte saque_fee_total_bps, saque_taxa_provedor_tipo, saque_taxa_provedor_piso_cents, saque_taxa_estimada_cents e saque_taxa_provedor_formula em GET /saldo. Leia a tarifa vigente na API; não fixe “1%” ou “R$ 2,00” no seu código. O payout registra a taxa efetiva.

Consulte GET /payouts/{payout_id}. processing ainda não é pagamento concluído; sent indica envio confirmado. failed e refunded exigem conciliação do status e do extrato. Em timeout, continue consultando a operação original: não presuma estorno nem envie novamente com outro identificador.

Após confirmação, e2e, paid_at, receiver_name, receiver_tax_number e verify_url podem trazer a prova do PIX. Campos ainda não obtidos podem ser null.

7. PIX para cripto diretamente#

Para entregar cripto após cada PIX, use destino: "cripto", o par do catálogo de entrega e payout_address. Sem endereço no corpo, o serviço pode usar a carteira Polygon configurada na chave; não use essa configuração como carteira universal para outras redes.

{
  "amount_cents":10000,
  "payer_tax_number":"00000000191",
  "destino":"cripto",
  "asset":"usdt",
  "chain":"polygon",
  "payout_address":"0x1111111111111111111111111111111111111111",
  "external_id":"compra-cripto-001",
  "allow_hold":false
}

Catálogo e cotação

GET /cashin/catalog lista o que a API consegue entregar. Use asset e network do catálogo; no corpo do cash-in e do saque, o nome do campo de rede é chain. instant pode estar vazio. A presença em convert não dispensa entregavel, mínimo ou memo. A tabela pronta de mínimos por moeda e por rede, com os números de hoje, está em Mínimos e redes.

curl --fail-with-body https://api.luniumpay.com/cashin/preview \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"amount_cents":10000,"asset":"usdt","chain":"polygon"}'

A prévia não cria uma cobrança e não trava o câmbio até o pagamento. Leia min_brl_cents, taxas e quantidade estimada da resposta. A quantidade que chega na carteira do cliente vem em asset_amount, em todas as rotas e também no sandbox, já descontada a taxa de saque da rede (withdraw_fee, em unidades do ativo). Essa taxa é fixa por envio e pesa mais em valores pequenos (BTC na rede Bitcoin, por exemplo); para exibi-la em reais, use withdraw_fee × brl_per_asset. Nas rotas convertidas, usdt_amount é o USDT usado na compra, não o que o cliente recebe; amount é o nome antigo de asset_amount. eta/etaSeconds são estimativas da rota, não prazo máximo contratual.

O valor recebido e a cotação aplicável na liquidação determinam a entrega. Exiba settlement_tx_hash e settlement_tx_url quando presentes; não construa links sempre para Polygon. Identificador interno de entrega pode não ter explorador público.

O CPF/CNPJ informado deve ser o do pagador. Divergência pode gerar devolução (PAYER_MISMATCH) ou análise quando a devolução não for concluída. Não credite com base em comprovante enviado pelo cliente ou em under_review.

8. Cripto externa para PIX#

Esse fluxo recebe cripto de uma carteira externa. Para gastar saldo custodial em PIX, use /payouts.

1. Consulte GET /catalog, o catálogo de entrada cripto; ele é diferente de /cashin/catalog.
2. Opcionalmente use POST /cash-outs/preview para uma estimativa sem ordem.
3. Crie a cotação por POST /cash-outs.
4. Mostre quantidade, rede, valor líquido em reais, destinatário e validade. Aceite por POST /cash-outs/{cashout_id}/accept.
5. Só então apresente o deposit_address, o deposit_tag quando houver e o valor exato retornado.
6. Acompanhe GET /cash-outs/{cashout_id} ou webhook até o estado final.

Exemplo de sandbox, usando LUNIUM_API_KEY de teste:

curl --fail-with-body https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "asset":"USDT",
    "network":"polygon",
    "amount":"10.00",
    "pix_key":"teste@example.com",
    "pix_key_type":"email",
    "external_id":"sandbox-cashout-001"
  }'

Envie amount (cripto) ou brl_amount (reais desejados), em string decimal com ponto. Não envie os dois. A criação pode responder 200 em produção ou 201 no sandbox; aceite respostas 2xx conforme o contrato. cashout_id é o identificador retornado, não um ID criado pelo integrador.

refund_address é opcional na criação, também na venda de DePix: a carteira de devolução só é pedida se a venda falhar (veja Carteira de devolução). Se você já tem a carteira do cliente, pode enviá-la: ela precisa ser válida para a mesma rede e estar sob controle do destinatário da devolução. A origem de um saque de exchange pode ser a carteira coletiva da exchange; não presuma que ela serve como carteira de retorno.

Estados e comprovantes

Nem toda rota passa por todas as etapas. timeline, confirmations e confirmations_required, quando presentes, ajudam a acompanhar. Não trate confirmação de depósito como PIX concluído.

Em COMPLETED, confira pix_e2e, pix_paid_at, receipt_url, receipt_pdf_url e verify_url, quando disponíveis. Use os links retornados. A consulta pública GET /v1/verificar/{e2e} verifica um PIX conhecido; não é uma prova genérica de toda operação cripto.

Em devolução, acompanhe REFUNDED e refund_tx_hash. Valor e prazo dependem do estágio atingido e do retorno do provedor. Não prometa estorno integral, automático ou em prazo fixo para qualquer falha. Depósito tardio ou divergente exige acompanhar a mesma ordem; não reutilize seu endereço para outra operação.

Carteira de devolução: só quando a venda falha

A carteira de devolução só é pedida quando a venda falha e o valor precisa voltar ao cliente. Se a ordem não tem refund_address, ela para em AWAITING_REFUND_ADDRESS (refund_address_required: true) e a Lunium envia o webhook cashout.awaiting_refund_address. Peça ao seu cliente uma carteira na rede de refund_network (na venda de DePix, um endereço Liquid lq1…) e informe:

curl --fail-with-body -X POST \
  "https://api.luniumpay.com/cash-outs/$CASHOUT_ID/refund-address" \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"refund_address":"CARTEIRA_DO_CLIENTE"}'

A devolução nunca vai para a origem do depósito: o destino é só a carteira informada. Com ela registrada, a devolução segue (REFUNDING_CRYPTO na venda de cripto, REFUNDING na de DePix) até REFUNDED, com refund_tx_hash (webhooks cashout.refunding e cashout.refunded); o caso de DePix já enviado ao provedor está logo abaixo. Quando o valor a devolver já está com a Lunium, refund_amount, refund_asset e refund_network dizem o que volta. Não refaça o pagamento antes de a devolução terminar.

Na venda de DePix (asset: "DEPIX", network: "liquid"), POST /cash-outs/{cashout_id}/refund-address responde:

DePix que já foi enviado ao provedor. Se o Pix falhou depois de o DePix ter sido enviado ao provedor do DePix, nada é devolvido antes de o retorno do provedor ser confirmado na rede: até lá a ordem fica em MANUAL_REVIEW (webhook cashout.under_review), com refund_amount vazio, mesmo que já tenha carteira de devolução. Confirmado o retorno, refund_amount passa a mostrar o valor da devolução, que é no máximo o que voltou (somado à parte que não chegou a ser enviada, até o valor da ordem), e a ordem segue para REFUNDING ou, sem carteira, para AWAITING_REFUND_ADDRESS. Se o DePix ainda estava todo com a Lunium, a devolução é do valor da ordem.

Comprovante oficial do PIX

Toda venda que chega a COMPLETED tem um comprovante oficial do PIX, emitido pela Lunium. É o documento que você entrega ao seu cliente final e guarda na sua contabilidade. Ele traz valor, data e hora (horário de Brasília), o E2E (identificador único do PIX no Banco Central), a instituição e o titular da chave que recebeu, o pagador (o liquidante PIX da Lunium, que é como o PIX aparece no extrato de quem recebeu) e o link da verificação pública.

O mesmo comprovante existe em quatro formas, e todas vêm no corpo da ordem:

Onde o comprovante chega:

• API: nos campos acima, em GET /cash-outs/{cashout_id}, assim que a ordem vira COMPLETED.
• Webhook: cashout.completed traz os campos preenchidos quando o link já existe. Se vierem null, cashout.receipt_ready chega em seguida com a ordem inteira e os links prontos. Trate os dois de forma idempotente pelo cashout_id.
• Painel do parceiro: em Vendas, abra a venda e use “Abrir comprovante”, “Baixar o PDF” e “Abrir verificação”. Só usuários com permissão para ver valores enxergam esses links.
• Telegram: no grupo de operação vinculado à chave, o aviso “✅ PIX pago” traz o E2E e o link “Ver comprovante”, e o PDF chega logo depois como arquivo (“🧾 Comprovante oficial”). Se o link nascer depois do aviso, o PDF chega sozinho.

Titular da chave. Nome e instituição de quem recebeu vêm de uma única consulta ao diretório de chaves PIX, feita pela Lunium no momento do pagamento e reservada ao comprovante: ela tem cota e não é um serviço de consulta (GET /pix/keys/lookup pode responder verification_status: "not_performed" sem afetar o comprovante). Se o titular não for localizado nessa consulta, o comprovante sai válido mesmo assim, com valor, chave, data e instituição extraídos do próprio E2E, e o nome é completado depois.

Boas práticas. Guarde pix_e2e e receipt_pdf_url junto do seu pedido. Entregue o PDF ao cliente e o verify_url a quem precise conferir. Não aceite comprovante enviado pelo cliente como prova de pagamento: a prova é a ordem em COMPLETED com pix_e2e. Saques do saldo por PIX (POST /payouts) também têm E2E, nome do recebedor e verify_url em GET /payouts/{payout_id} e no painel (Payouts → “Abrir comprovante”). No cash-in, o E2E do PIX recebido vem em GET /cashin/{cashin_id}/status (e2e e payer_name).

Consulta de titular e pagamento de QR

GET /pix/keys/lookup?key=...&type=... é auxiliar. Pode responder 200 com available: false, verified: false, verification_status: "not_performed" e nomes null. Mostre “titular não verificado”; não invente nome nem confunda consulta indisponível com pagamento indisponível. No sandbox, o titular é fictício e vem com source: "sandbox".

br_code tem disponibilidade separada. Produção pode recusar a criação com 503 br_code_indisponivel, mesmo que uma prévia ou o sandbox aceite o QR. Não ofereça pagamento de copia e cola como funcionalidade sempre ativa. Quando habilitado, substitui pix_key, amount e brl_amount, e exige valor definido e ativo compatível. Se o cliente colou ou escaneou um QR com valor — estático ou dinâmico — envie o br_code inteiro, nunca pix_key + brl_amount extraídos dele: só assim o PIX sai no valor exato e como pagamento daquela cobrança (com o txid). Pago por chave, o valor pode diferir em centavos e o recebedor não reconhece.

A reserva operacional das novas vendas de cripto para Pix é de R$ 1,00 por operação, para todos os parceiros, já incluída na cotação e informada em reserve_brl. O equivalente em USDT é calculado pela cotação do momento e congelado na ordem: pix_key_reserve_usd para chave Pix ou copia_e_cola_buffer_usd para Copia e Cola. Esses campos representam o valor convertido, não uma cobrança de US$ 1. Não some a reserva novamente ao total. Os percentuais e custos do provedor continuam na cotação. O QR é pago somente pelo valor exato. A reserva operacional não é devolvida após o pagamento; a margem temporária de saldo é separada. Ordens anteriores mantêm os valores contratados. DePix/Liquid segue sua tarifa própria em reais.

Use somente redes oferecidas no catálogo da operação. Redes com memo podem ser excluídas do cash-out mesmo quando existem no catálogo de entrega; não copie a lista de um produto para outro.

Carteira USDT/USDC: saldo em cripto e PIX pago com ele

A carteira guarda um saldo em USDT do seu projeto. Você deposita USDT ou USDC, em várias redes, e paga PIX com esse saldo, por chave PIX ou por Copia e Cola. Está liberada para todas as chaves de produção; a chave lun_test_ usa o simulador.

1. GET /carteira-usdt: saldo (available, reserved, confirming), redes aceitas agora (networks[], com moedas e prazo estimado), min_deposit e min_payment_brl.
2. POST /carteira-usdt/deposits com {"amount": "100", "network": "tron"}: devolve amount_to_send (valor exato: as casas finais identificam o seu depósito), address, network_name e expires_at. Mostre os quatro ao usuário. Se a origem desconta a taxa do envio, some a taxa: o que conta é o valor que chega. O pedido vale 1 hora (deposit_validity_hours = 1; expires_at = criação + 1 h): envie dentro do prazo.
3. O crédito é automático: acompanhe GET /carteira-usdt/deposits (waiting → confirming → available) ou o webhook wallet.deposit_credited. USDC entra 1 para 1 no saldo.
4. POST /carteira-usdt/quote com {"brl_amount": "50.00"} ou {"br_code": "000201…"}: prévia em USDT (usdt_total, usdt_reserved), sem efeito.
5. POST /carteira-usdt/payments com {"brl_amount": "50.00", "pix_key": "cliente@exemplo.com", "pix_key_type": "email", "external_id": "pedido-123"} (ou com br_code): responde 201 em reservado. Acompanhe GET /carteira-usdt/payments/{payment_id} até final: true, ou os webhooks wallet.payment_completed e wallet.payment_failed.
6. Concluído traz pix_e2e, recipient_name, recipient_document (CPF parcial) e receipt_url (comprovante oficial). GET /carteira-usdt/statement é o extrato: valor sempre positivo, type dá a direção (deposit, reserve, debit, release, reversal).

Regras: o PIX mínimo é min_payment_brl (hoje R$ 25,00). A reserva cobre até 1% de variação e a sobra volta ao saldo. falhou = não executado, a reserva voltou; falhou_apos_envio = em apuração, a reserva não volta sozinha; revisao é conferência, não falha. O mesmo external_id com os mesmos dados devolve o mesmo pagamento (200); com dados diferentes, 409 external_id_divergente. 409 saldo_insuficiente quando o disponível não cobre a reserva.

Redes aceitas (9): USDT e USDC em Polygon, BNB Smart Chain (BEP20), Ethereum (ERC20), Arbitrum One, Optimism, Avalanche C-Chain e Solana; só USDT em Tron (TRC20); só USDC em Base. O que vale para a sua chave agora é networks[] de GET /carteira-usdt. Depósito mínimo: 5 USDT ou USDC (min_deposit). Sem envio dentro do prazo, o pedido termina em expired. O MCP da Lunium tem 6 ferramentas da carteira: saldo, pedido e lista de depósitos, prévia, pagamento e consulta do pagamento.

No painel do parceiro, o pedido de depósito mostra o QR Code só do endereço e uma contagem regressiva, com segundos, até expires_at. O QR não leva o valor: digite o valor exato (amount_to_send) no app de envio. Nas redes EVM o endereço 0x é o mesmo: escolha a rede certa no app.

No sandbox (lun_test_): endereço fictício (não envie nada), depósito creditado sozinho em cerca de 15 s e PIX concluído em cerca de 15 s, com E2E de teste. Os centavos escolhem o cenário: depósito .02 expira; PIX .01 passa por revisao, .02 falha e devolve a reserva, .05 demora cerca de 2 minutos.

9. Operação pelo Telegram#

Lunium Partners — comunidade oficial de integradores

Entrar no Lunium Partners

O Lunium Partners faz parte do acompanhamento recomendado para quem constrói com a API. Inclua os responsáveis técnico e operacional do parceiro desde o início e mantenha o time acompanhando os avisos durante a operação em produção. A participação é fortemente recomendada, sem ser uma condição técnica para criar chaves ou usar a API.

Na comunidade, acompanhe avisos operacionais, manutenções e mudanças de API/contrato, além da troca entre integradores. Não espere um incidente para entrar: uma integração precisa acompanhar mudanças depois de ser publicada.

Para começar: entre no Lunium Partners, combine o grupo dedicado com os dois contatos humanos, vincule o bot e valide monitor/webhooks no ambiente correto. A comunidade não substitui o suporte específico do projeto nem a conciliação financeira da API.

Não publique chaves de API, segredos de webhook, monitor_url, documentos de pagadores ou dados de transações de clientes na comunidade. Leve casos específicos ao grupo dedicado, com IDs e dados minimizados.

Integração com Fable ou outra IA: inclua o link do Lunium Partners no plano e no checklist entregue ao responsável humano. A IA deve explicar essa recomendação e distinguir os três canais acima. Não afirme que alguém já entrou no grupo sem confirmação, não exija a adesão para executar testes de sandbox e não use mensagens do Telegram como autorização para movimentar dinheiro.

Grupo de integração com acompanhamento humano

É fortemente recomendado manter um grupo de Telegram dedicado ao projeto, com os agentes humanos @luniumb2b e @luniumb2c. A Lunium pode criar o grupo e convidar a equipe do parceiro, ou a equipe do parceiro pode criá-lo e adicionar os dois contatos. O grupo acompanha a integração, a homologação e a operação em produção. Não é requisito técnico para usar a API.

1. Crie o grupo ou solicite sua criação a um dos contatos acima. Use um nome que identifique o projeto.
2. Inclua os dois contatos humanos, o responsável técnico e o responsável operacional do parceiro. Combine os responsáveis e o canal de escalonamento.
3. Adicione também @LuniumNotifyBot e faça o vínculo abaixo. O bot envia notificações e executa comandos; os contatos humanos acompanham dúvidas e incidentes. Um não substitui o outro.
4. Fixe no grupo os links do manual, do status público e as orientações de operação. Compartilhe o monitor privado apenas com integrantes autorizados a ver os dados do projeto.
5. Na homologação, confira o projeto vinculado, o monitor, um webhook assinado e o cenário de falha/recuperação do fluxo escolhido.

Para pedir ajuda, informe ambiente (sandbox ou produção), ID da operação, external_id, horário com fuso, comportamento esperado e observado, e request_id quando disponível. Para notificações, acrescente event_id e X-Lunium-Delivery-Id. Não envie chave de API, segredo de webhook, documentos completos do pagador ou dados de outros clientes. A presença no grupo não implica atendimento 24 horas nem prazo de liquidação; combine o atendimento com a equipe.

Os canais gerais de parceiros/comunidade indicados em /keys/me complementam os avisos de manutenção e mudanças de API. Eles não substituem o grupo dedicado ao projeto.

Vínculo e comandos do bot

Adicione @LuniumNotifyBot ao grupo do projeto. Um administrador identificado deve usar /vincular e o fluxo de vínculo recebido ao criar/consultar a chave. Se o bot apresentar um botão de confirmação, clique no botão: responder “sim” em texto não equivale ao clique. Não publique a chave lun_... no grupo.

No Telegram, valores são em reais, como 50 ou 50,50; na API, amount_cents usa centavos. Para subcontas, confira o escopo exibido antes de sacar. /pagar não oferece o parâmetro cliente=ref do saque cripto; para payout de subconta, use a API com customer_ref.

O saque cripto mostra destino, estimativa e débito antes da confirmação. A confirmação vale 60 segundos e pertence ao usuário, grupo e projeto que a solicitaram. Em grupos, saques exigem administrador identificado; mensagem sem remetente identificado não autoriza retirada. A confirmação revalida as condições e pode pedir nova prévia. A cotação não fica travada.

/sacar é o fluxo de cripto externa para PIX. Para retirar o saldo em cripto, use /sacarcripto. Os comandos /qr, /qrwhitelist e /qrdelay também usam custódia quando não há carteira explícita; prazo e retenção devem ser conferidos na resposta.

10. Webhooks confiáveis#

Configure webhook_url, guarde webhook_secret e execute POST /webhooks/test para testar seu receptor. Essa chamada envia uma notificação de teste ao endereço configurado.

Envelope ilustrativo:

{
  "event":"cashin.settled",
  "event_id":"evt_exemplo",
  "created_at":"2026-09-17T20:00:00.000Z",
  "data":{
    "cashin_id":"ci_exemplo",
    "destino":"saldo",
    "status":"paid",
    "settlement_status":"sent"
  }
}

O exemplo abrevia data. Eventos de cobrança, cash-out e payout compartilham o objeto-base de status do recurso; enriquecimentos de uma consulta GET, como timeline, podem não estar no evento. Eventos saldo.* têm seus próprios dados de movimento. Não exija que todo webhook seja idêntico, campo a campo, à resposta enriquecida de um GET.

Valide o corpo bruto, sem reserializar JSON, e a idade do timestamp. Compare buffers de mesmo tamanho em tempo constante. Use o verificador Node.js completo, que também rejeita assinatura malformada sem lançar erro de tamanho de buffer.

Persista/enfileire o evento e responda 2xx rapidamente. O transporte tem timeout de 10 segundos. Faça o trabalho demorado depois. Não deduplique por tentativa: todas as tentativas do mesmo evento devem produzir uma única ação de negócio.

Sem sucesso, há até 12 tentativas com backoff. A janela é aproximadamente 7 horas, sujeita à fila; não é um SLA de entrega. Consulte GET /webhooks/deliveries e reenvie por POST /webhooks/deliveries/{event_id}/retry quando corrigir seu receptor. Entrega esgotada fica failed; o registro permite recuperação.

Novas integrações devem usar a assinatura v2. X-Webhook-Signature é legado, ausente para chaves novas e com retirada anunciada para 09/11/2026; não dependa dele.

Eventos

Tolere eventos e campos novos, registre o que não conhece e confirme o recurso por GET quando necessário. Não presuma ordem de chegada. Consulte o estado atual antes de regredir um recurso que já concluiu.

Monitor ao vivo do parceiro

O parceiro já pode acompanhar seu próprio projeto no monitor privado da Lunium. Consulte GET /keys/me no backend e abra o monitor_url da resposta, ou use /monitor no grupo vinculado. A criação de chave também devolve esse link. Ele oferece acesso de leitura ao projeto: compartilhe somente com pessoas autorizadas, nunca na documentação pública ou com o cliente final.

O painel consulta o feed a cada 3 segundos e o saldo de custódia a cada 15 segundos. Mostra cobranças, cash-outs, payouts e entregas de webhook; a seção de custódia inclui saldo disponível/bloqueado, subcontas e movimentos recentes quando habilitada. Esses intervalos são a frequência de consulta da interface, não um prazo garantido de atualização do banco, provedor ou blockchain.

Se o link privado vazar, use PATCH /keys/me com {"rotate_monitor_token":true}. Guarde o novo monitor_url: o token antigo deixa de dar acesso aos dados. O token de monitor é somente leitura, mas permite ver o projeto inteiro, não apenas um cliente. Não o use como autenticação de uma tela pública por transação.

Feed para o seu próprio painel

# Execute no backend; LUNIUM_API_KEY vem do seu gerenciador de segredos.
curl --fail-with-body 'https://api.luniumpay.com/cashin/events?limit=80' \
  -H "X-API-Key: $LUNIUM_API_KEY"

GET /cashin/events aceita X-API-Key ou X-Dashboard-Token no header. O monitor hospedado usa ?token=. A resposta contém projeto, agora e eventos. Cada item traz ts, fluxo (cash-in, cash-out, payout ou webhook), provedor, ref, valor, estado, detalhe e tx, com campos eventualmente nulos. limit tem padrão 60 e limite de 1 a 200.

É um resumo recente, não um histórico completo de transições. A lista vem ordenada por ts decrescente; uma operação pode aparecer com o estado atual, e o feed não tem cursor de replay nem o event_id do envelope de webhook. Não calcule saldo, taxas ou conciliação a partir dos textos valor/estado. Não use ts como sequência global de mudanças. Para valores, rede, hash e comprovantes, consulte o recurso original. Em particular, use settlement_tx_url retornado pelo status do cash-in para o explorador correto da rede, em vez de presumir Polygon pelo resumo do feed.

Webhook + consulta de status + atualização da sua interface

O webhook é uma chamada HTTPS POST da Lunium para o backend do parceiro. Para reproduzir a experiência ao vivo no seu aplicativo, implemente este caminho:

1. Receber: leia o corpo bruto com limite de tamanho, valide assinatura e timestamp antes de interpretar o JSON. Confira a correspondência do event_id do corpo com o header. Um segredo corresponde à configuração da chave/ambiente; não confie no payload para escolher o projeto.
2. Persistir: grave o evento em uma caixa de entrada durável, com restrição única (projeto, ambiente, event_id), antes de responder 2xx. Em uma duplicata já persistida, retorne 2xx sem repetir o efeito. Se a gravação falhar, retorne erro para permitir nova tentativa. Não descarte silenciosamente um evento autenticado desconhecido.
3. Conciliar: um worker processa a caixa de entrada e consulta o recurso canônico quando necessário. Serialize as atualizações por operação para uma resposta antiga não sobrescrever uma consulta mais recente. Guarde o histórico recebido, o estado consultado e a hora da última consulta separadamente.
4. Atualizar a tela: seu backend publica o resultado por SSE, WebSocket ou polling para sessões autenticadas do seu aplicativo. Autorize o projeto e o cliente em cada leitura/conexão. Esses canais são implementados pelo parceiro; não há endpoint público SSE/WebSocket da Lunium descrito neste contrato.
5. Recuperar: mantenha uma rotina de conciliação das operações não concluídas e daquelas com entrega incerta. Use intervalo ajustável, backoff e limites da chave; não faça uma consulta à API por navegador aberto. Na reconexão do cliente, recarregue o estado persistido e mostre quando a atualização estiver atrasada.

O monitor da Lunium é a visão operacional pronta. O painel do parceiro pode acrescentar seus próprios pedidos, clientes e histórico durável. Webhooks não substituem o extrato nem constituem um registro de cada etapa interna da corretora parceira, bancos ou outros provedores.

Persista também o external_id que você definiu ao criar a operação. O status do cash-in pode trazer timeline com etapa, em, detalhe; o do cash-out, timeline com state, at. Use apenas etapas e horários efetivamente retornados. Campos de confirmação, hash ou comprovante podem estar ausentes/nulos até existirem. Não invente percentual, horário de conclusão, transação on-chain ou motivo de falha.

O que cada evento significa na tela

settlement_status=incerto requer conciliação antes de qualquer nova entrega. Um webhook antigo pode chegar depois de uma consulta que já mostra conclusão; guarde-o no histórico sem regredir o estado atual. Até uma operação concluída pode ter atualização posterior legítima, como devolução: consulte a fonte, em vez de ignorar tudo após o primeiro sucesso.

Configurar, testar e recuperar notificações

Configure o receptor HTTPS público na chave do ambiente correto. A validação recusa destinos privados/locais. O segredo é retornado quando gerado: guarde-o no backend. Uma atualização de URL não necessariamente gera ou devolve outro segredo. Se precisar rotacionar, coordene a troca usando rotate_webhook_secret; tentativas posteriores usam o segredo vigente.

curl --fail-with-body -X PATCH 'https://api.luniumpay.com/keys/me' \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"webhook_url":"https://seu-dominio.example/webhooks/lunium"}'

# Testa apenas transporte e assinatura; não cria um pagamento.
curl --fail-with-body -X POST 'https://api.luniumpay.com/webhooks/test' \
  -H "X-API-Key: $LUNIUM_API_KEY"

curl --fail-with-body 'https://api.luniumpay.com/webhooks/deliveries?status=failed&limit=100' \
  -H "X-API-Key: $LUNIUM_API_KEY"

# Reenvie somente após corrigir o receptor, usando um event_id da sua chave.
curl --fail-with-body -X POST \
  "https://api.luniumpay.com/webhooks/deliveries/$EVENT_ID/retry" \
  -H "X-API-Key: $LUNIUM_API_KEY"

Substitua o domínio ilustrativo pelo receptor real. POST /webhooks/test tem limite de 6 chamadas/minuto por chave em produção; retorna ok, status_code, ms, event_id e delivery_id. Esse teste avulso não é persistido na fila de entregas de produção. Ele valida a comunicação, não a liquidação financeira ou todos os caminhos da sua aplicação.

GET /webhooks/deliveries aceita status (pending, sent, failed), event e limit (padrão 50, máximo 200). Cada linha traz event_id, operation_id, attempts, last_error, url, next_attempt_at, created_at e updated_at, além do evento/status. failed_count conta falhas somente nas linhas retornadas. Não há filtro por operation_id nem cursor de paginação nesse endpoint; mantenha seu histórico durável e procure a operação nas linhas recebidas.

O retry responde 200 se a tentativa foi entregue, 202 se falhou e foi recolocada na fila, 409 se já estava entregue e 404 se não existir para a chave. pending/sent/failed aqui descrevem o transporte do webhook, não o resultado do pagamento. Reenviar uma notificação não refaz o pagamento nem corrige uma liquidação pendente.

Homologação do acompanhamento ao vivo

• Configure o receptor na chave de sandbox e execute os cenários aplicáveis descritos em Sandbox. GET /sandbox/events mostra os eventos simulados; não use o feed operacional de produção como prova de cobertura da sandbox.
• Verifique assinatura inválida/expirada, duplicata, eventos fora de ordem, indisponibilidade do receptor, retorno após reconexão e isolamento entre projetos/clientes.
• Prove que cashin.paid não marca entrega cripto, que retenção não vira saldo disponível e que webhook.test não altera saldo.
• Confira uma operação pela resposta de criação, webhook e GET de status, correlacionando os IDs e sem criar nova transação em timeout.
• Valide erro de liquidação, resultado incerto, devolução e recuperação de notificação. Encaminhe os IDs ao grupo humano para casos que precisem de investigação.
• Mostre no painel: operação, pedido externo, cliente autorizado, moeda/rede, valor retornado, status financeiro, entrega do webhook, última atualização e comprovante/hash quando disponíveis. Sinalize dados desatualizados e evite uma falsa indicação de “ao vivo”.

11. Erros, idempotência e conciliação#

Use o código HTTP junto de erro, acao, detail, request_id e agent_guidance quando presentes. Alguns caminhos retornam apenas parte desses campos. Não ramifique pelo texto livre de detail.

Envie external_id de até 64 caracteres em toda operação financeira que o aceite. Use um identificador persistente por intenção de negócio e mantenha todos os parâmetros iguais nos retries. Cobranças e saques cripto compartilham o espaço de referências da chave; use prefixos distintos. Não use a validação de divergência como mecanismo para alterar uma operação existente: a comparação varia por rota.

Para recuperar após timeout, consulte /cashin/charges?external_id=..., /cash-outs?external_id=... ou /payouts?external_id=..., conforme a operação. Se precisar repetir, mantenha o mesmo corpo e identificador. Não gere um novo ID apenas porque perdeu a resposta.

Salve IDs, valores, moeda/rede, customer_ref, timestamps, eventos processados e referências do extrato. Use centavos inteiros para BRL e strings decimais para cripto. Datas vêm com fuso explícito. Arredondamento e conversão devem seguir os valores devolvidos pela API.

Roteiro operacional: o que consultar e mostrar

Em qualquer fluxo, um painel com dados antigos deve mostrar “última atualização” e o estado de conexão. Não transforme timeout, resposta vazia ou ausência de webhook em sucesso ou falha financeira. Uma operação em estado incerto exige conciliação; nunca envie manualmente outra transferência apenas para remover o alerta.

Ao acionar o grupo humano, envie ambiente, ID da operação, external_id, horário com fuso, código HTTP, erro/acao, request_id quando disponível e os últimos estados consultados. Para webhook, acrescente event_id e HTTP/horário da tentativa, com logs sanitizados. Não envie chave, segredo, monitor privado, CPF completo ou payload contendo dados de clientes na comunidade aberta. Não há prazo universal de suporte ou de liquidação garantido por este manual.

O Fable pode seguir o roteiro estruturado de incidentes. Ele orienta consultas e conciliação; não concede autorização para sacar, alterar taxas ou reenviar dinheiro.

12. Sandbox e testes de integração#

Execute node sandbox.mjs all ou python3 sandbox.py all no kit. Os exemplos confirmam a chave de teste, simulam pagamento PIX e percorrem custódia, saque USDC/Base, payout, BTC, USDC/Polygon e cash-out. Para cash-in/payout use sandbox_scenario; retenção, devolução, falha de entrega e resultado incerto estão detalhados no guia. GET /sandbox/events permite inspecionar eventos; callbacks configurados usam a fila assinada do produto. Preços e prazos são sintéticos, não condições reais da corretora parceira.

Carteira USDT/USDC: a chave de teste usa o simulador da carteira, com as mesmas rotas e formas. Depósito .02 expira; PIX .01 passa por revisão, .02 falha e devolve a reserva, .05 é lento. Detalhes na seção Carteira USDT/USDC.

No cash-out de sandbox, as duas primeiras casas decimais de amount selecionam o cenário:

Ordens de teste são temporárias e não representam depósitos reais. Sandbox não certifica prazo, preço, disponibilidade de provedor ou crédito em custódia de produção. Para cash-in e saldo, exercite as rotas de simulação e os cenários documentados. O piloto real posterior usa o mínimo aceito pela rota e pelo pagador, com valor e destinatário autorizados.

13. Onde ler a regra vigente#

GET /keys/me não contém sozinho todas as condições. Um limite diário null significa ausência daquele teto na chave; os limites por pagador, recebedor, operação, saldo e eventual mandate continuam valendo. Não programe números de catálogo, taxa, prazo ou limite a partir de um exemplo deste manual.

14. Comissão, agentes e operações adicionais#

Configurar a comissão do parceiro

A sub fee é a comissão do parceiro, adicionada à taxa da Lunium. 100 bps = 1%; 200 bps = 2%. Consulte a política e o teto permitido em GET /comissao antes de configurar. O exemplo abaixo altera o preço das novas cobranças da chave; só aplique a taxa acordada com o responsável pelo projeto.

curl --fail-with-body -X PATCH https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"partner_fee_bps":200}'

Confira o valor persistido em GET /keys/me. A taxa fica registrada em cada nova cobrança: alterar a configuração não recalcula cobranças abertas nem cria comissão retroativa. No Telegram, /comissao consulta; /comissao 2 apresenta a mudança e sua confirmação. O administrador deve conferir a identidade da chave e usar o comando de confirmação devolvido pelo bot, incluindo o ID da chave. Não confirme em nome de outro projeto.

Separar taxa, comissão, câmbio e quantidade entregue

No cash-in, a base é o valor recebido menos a taxa fixa da Lunium. Sobre essa base incidem os percentuais da Lunium e do parceiro. No depósito em saldo, desconta-se somente R$ 1,00: não há percentual, faixa ou comissão. Os parâmetros da cobrança e os valores retornados pela operação prevalecem sobre exemplos.

Exemplo didático em centavos, sem representar uma oferta vigente: recebido 10000 (R$ 100), taxa fixa 100 (R$ 1), Lunium 200 bps (2%) e parceiro 100 bps (1%).

O cálculo usa floor(base_cents * (10000 - lunium_bps - partner_bps) / 10000). A comissão é a diferença entre o líquido sem e com a sub fee, preservando o arredondamento do produto. Não aplique um segundo desconto de comissão sobre a quantidade já cotada.

POST /cashin/preview pode retornar lunium_fee_cents, partner_fee_cents, fee_total_cents, net_cents e a estimativa de cripto em asset_amount, já líquida da taxa de saque da rede (withdraw_fee). Nos retornos com essa decomposição, fee_total_cents + net_cents = amount_cents. Nos campos legados brl_per_usdt e usdt_amount, confira o ativo retornado: o nome do campo pode permanecer igual para USDC.

Câmbio não é outra comissão do parceiro. A conversão usa o ask da Binance, sem o antigo ágio. A taxa Lunium e a comissão são calculadas separadamente da cotação. A prévia de cash-in é estimativa, não trava o câmbio até o pagamento. Custos e mínimos da rota/rede também podem afetar a entrega: leia os campos aplicáveis do catálogo e da resposta. Não some withdrawFee cegamente a uma quantidade que já o considera. Confira a quantidade efetivamente liquidada no status e no comprovante da operação.

No depósito em custódia, o resultado é BRL, sem compra imediata de cripto. O saque posterior tem suas próprias taxas/conversão. A prévia de cash-in não é uma prévia completa do saque custodial. Para payout PIX, a resposta separa fee_service_total_cents (Lunium + parceiro) e fee_provider_cents; fee_cents é o total. Comissão do parceiro, saldo dos clientes e lucro da Lunium são contas distintas; uma diferença entre cotação e entrega, isoladamente, não comprova lucro.

Crédito, extrato e saque da comissão

1. Consulte GET /comissao: disponivel_cents, creditado_cents, estornado_cents, sacado_cents, min_saque_cents, pode_sacar_agora, proximo_saque_em e politica.
2. Confira GET /comissao/extrato?limit=50. Use next_before como before na próxima página. Relacione origem_id com a cobrança ou saque; leia kind, valor_cents e partner_fee_bps.
3. A apuração ocorre após status=paid e settlement_status=sent, em processo posterior à liquidação. O PIX pago sozinho não comprova comissão disponível. Novos depósitos em saldo não geram comissão. Compras e saídas usam a comissão da família correspondente; consulte os valores gravados da operação. Sandbox não acumula comissão real.
4. Movimentos credito, estorno, saque e saque_estorno explicam o saldo. Confira os sinais e não conte o mesmo lançamento duas vezes. Se uma operação elegível não aparecer após a apuração, envie seu ID ao grupo humano para conciliação; não altere a taxa esperando corrigir o passado.
5. Para sacar, consulte a política vigente, o saldo e a rota entregável. O mínimo convertido em BRL (hoje US$ 10 pela cotação do momento) e a janela entre saques vêm da API; se min_saque_cents for null, não há cotação para validar o mínimo. pode_sacar_agora não substitui as validações da rede, endereço, memo, liquidez e mínimo da rota.

POST /comissao/sacar recebe amount_cents, asset, chain, payout_address, eventual payout_tag e external_id. O saque não cobra outra sub fee nem taxa administrativa da Lunium, mas a conversão e os custos da rota continuam relevantes. A resposta contém saque e comissao; acompanhe o identificador público de saque em GET /cashin/{cashin_id}/status até confirmar a entrega. Não confunda sucesso HTTP com cripto entregue.

Use um prefixo próprio, como comissao-..., para external_id: o espaço de referências é compartilhado com cobranças. Após timeout, primeiro procure /cashin/charges?external_id=... e acompanhe o ID existente. O saque valida política e intervalo antes de procurar a referência; portanto, um retry pode responder 429 mesmo que o pedido anterior tenha sido aceito. Não gere outro ID nem repita saques concorrentes para tentar destravar.

PATCH /keys/me aceita partner_fee_bps para a sub fee. Consulte política, disponível e condições de saque em GET /comissao; movimentos em GET /comissao/extrato; saque em POST /comissao/sacar. Comissão é um saldo separado da custódia dos clientes. Não some os dois nem trate comissão como recompensa de indicação do Mesh.

Para agentes, Mesh publica descoberta, registro, validação, mandate e ativação. Use GET /mesh e suas ações retornadas. O MCP está em https://api.luniumpay.com/mcp; descubra as ferramentas via tools/list, pois a superfície de ferramentas não é idêntica a todas as rotas HTTP. Operações sem ferramenta dedicada continuam disponíveis pela API autenticada.

O inventário abaixo é gerado do OpenAPI desta revisão. Inclui também consulta de entregas de webhook, recuperação do painel, catálogo DEX, comissão e ciclo de vida Mesh. Rotas administrativas e internas não são interfaces públicas do parceiro.

15. Checklist de produção#

• Comissão configurada na chave correta; decomposição e extrato conciliados sem desconto duplicado.
• E-mail de recuperação conferido; monitor, chave da API e segredo do webhook tratados separadamente.
• Roteiro de incidentes ensaiado; recursos em desenvolvimento não assumidos como disponíveis.
• Participação no Lunium Partners fortemente recomendada para os responsáveis técnico e operacional; acompanhamento de avisos e mudanças definido.
• Grupo dedicado com @luniumb2b e @luniumb2c fortemente recomendado, criado pela Lunium ou pelo parceiro, com responsáveis definidos.
• Monitor privado conferido; painel próprio autorizado por projeto/cliente, com indicação de última atualização.
• Inbox durável, duplicatas, eventos fora de ordem, indisponibilidade, retry e reconciliação do webhook testados.
• Chave guardada no servidor; ambiente de teste separado de produção.
• /keys/me e /saldo conferidos para a chave e para o escopo de cada cliente.
• Custódia usa destino: "saldo"; carteira é escolhida somente na retirada em cripto.
• Interface lê catálogo e limites atuais, mostra retenção e exige memo quando necessário.
• IDs persistidos; retries mantêm corpo e external_id; recuperação após timeout testada.
• Webhook verifica HMAC e timestamp, deduplica por evento e responde antes do timeout.
• Conciliação distingue PIX pago, crédito registrado, disponível para saque e cripto entregue.
• Erros de saldo, carência, rota, taxa, provedor e chave são tratados sem duplicar operações.
• Telegram vinculado por admin identificado; retiradas confirmadas no contexto correto.
• Homologação inclui sucesso, retenção, expiração, falha, reenvio e consulta após perda de resposta.

Suporte: @luniumb2b · @luniumb2c · contato@luniumpay.com. Acompanhe status e o Lunium Partners. Ao pedir ajuda, envie IDs e request_id quando disponível, sem compartilhar a chave completa.

16. O que mudou nesta revisão#

• 09/10/2026 · OpenAPI 1.44.1 · revisão 2026-10-09.1: Sandbox: POST /sandbox/operations/{operation_id}/resolve responde 400 outcome_invalido quando outcome não é sent nem failed (antes, um corpo sem outcome podia responder 200 sem resolver nada); a checagem vem antes de procurar a operação, e nada muda no simulador. Saldo: em GET /saldo, proximas_liberacoes pode trazer até 200 liberações do escopo pedido (antes, no máximo 20); o formato e o escopo (casa ou customer_ref) não mudam.
• 08/10/2026 · OpenAPI 1.44.0 · revisão 2026-10-08.2: Venda de DePix: refund_address deixa de ser obrigatória na criação; a carteira de devolução só é pedida se a venda falhar (Carteira de devolução). Sem carteira, a ordem fica em AWAITING_REFUND_ADDRESS (webhook cashout.awaiting_refund_address) e você informa o endereço Liquid em POST /cash-outs/{cashout_id}/refund-address; a ordem segue para REFUNDING e REFUNDED, com webhooks. Erros: 400 refund_address_invalida (inclui endereço da própria Lunium), 409 refund_address_imutavel e 409 devolucao_indisponivel. DePix que já tinha sido enviado ao provedor só é devolvido depois de o retorno ser confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou. O detail da recusa por limite do pagador com allow_hold: false foi revisado e mostra valores em R$ no formato brasileiro (R$ 1.234,56), assim como a explicação de GET /cashin/limits; erro e code não mudam. Saque da comissão a partir de US$ 10. Painel do parceiro (2): ativação de conta nova com código de 6 dígitos por e-mail; convite aceito num clique por quem entra por código ou Google; Meu acesso com Encerrar as outras sessões, verificação em dois passos que a conta sem senha desliga com código e e-mail de aviso quando a senha muda; e-mail aos donos quando alguém deixa de ser dono; Pagar com cripto com stablecoins e as 30 principais criptos; mais legibilidade e sessão de 12 horas que se renova com o uso. Novo fluxograma da venda de cripto (venda e devolução) na seção 8.
• 08/10/2026 · OpenAPI 1.43.1: o pedido de depósito da Carteira USDT/USDC vale 1 hora (deposit_validity_hours = 1; expires_at = criação + 1 h; antes eram 3 h). Nova seção Novo painel do parceiro (2): parceiros.luniumpay.com com resumo do negócio, comprovantes em PDF, carteira com QR Code do endereço e contagem regressiva, notificações e equipe com papéis e segundo fator. Pelo painel, só o Dono vincula o Telegram e troca a carteira de liquidação e as sub fees. Fluxograma da carteira (depósito e PIX pago com o saldo) na seção Carteira USDT/USDC.
• 07/10/2026 · OpenAPI 1.43.0: Carteira USDT/USDC (/carteira-usdt): depósito de USDT ou USDC em várias redes, PIX pago com o saldo (chave ou Copia e Cola), extrato, webhooks wallet.* e simulador no sandbox.
• 07/10/2026: a prévia de cash-in (POST /cashin/preview) passa a usar em produção os mesmos nomes do sandbox: asset_amount (o que chega na carteira), withdraw_fee (taxa de saque da rede, em unidades do ativo), withdraw_min e brl_per_asset (para converter em reais). amount e network_min seguem como nomes antigos.
• 03/10/2026: seção Comprovante oficial do PIX (8): o que o comprovante contém, as quatro formas (pix_e2e, receipt_url, receipt_pdf_url, verify_url) e por onde ele chega (API, webhook, painel do parceiro e Telegram).
• Taxas e comissões conciliadas em exemplo; recuperação de acesso e cenários de incidente detalhados.
• Fontes estruturadas para IA alinhadas ao OpenAPI; capacidades futuras dependem de publicação e validação.
• Lunium Partners destacado como comunidade oficial no início, na operação pelo Telegram e no checklist.
• Recomendação do grupo humano restaurada: @luniumb2b e @luniumb2c, com criação pela Lunium ou pelo parceiro.
• Monitor privado, feed, painel ao vivo, estados por fluxo, assinatura, recuperação e homologação detalhados.
• Revisão desta atualização focada em suporte e acompanhamento; versão do OpenAPI referenciada atualizada.
• Fluxo de custódia sem carteira fixa e saques pelo Telegram documentados.
• Padrão de destino da API separado do padrão do bot.
• Taxas e limites vinculados às consultas corretas; removidas promessas fixas de preço e prazo.
• Retenção local, retenção do provedor e carência de saldo diferenciadas.
• Catálogos de entrada e entrega separados, incluindo filtro entregavel e restrição de Liquid/DePix no saque.
• Titular PIX opcional/indisponível e br_code condicionado à disponibilidade.
• Timeout de webhook corrigido para 10 segundos, assinatura robusta e recuperação de falhas.
• Estados, campos, exemplos e inventário do OpenAPI revisados junto das rotas.
• HTML, Markdown e PDF gerados do mesmo conteúdo, com validações de contrato antes de publicar.

Baixar PDF · Markdown · Exemplos estruturados · Revisão do contrato