Comece pelo fluxo certo

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#

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

Uma chamada. Sem cadastro, sem aprovação humana, sem espera: a chave de produção nasce na hora, igual à de teste. Só name é obrigatório; informe email mesmo assim, porque a chave é enviada nele. Entrar no Lunium Partners é recomendado, não é condição.

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.

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%. A taxa efetiva depende da chave; o depósito não deve ser apresentado como gratuito sem verificar esses campos.

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 saldo instantâneo 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 instantânea, 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 instantânea.

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.

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.

Em produção, informe uma refund_address válida para a mesma rede e 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.

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.

A reserva operacional das novas vendas de cripto para Pix é de US$ 1,00 por operação, já considerada na cotação. Para pix_key, ela aparece em pix_key_reserve_usd, além das taxas percentuais e dos custos do provedor; em ativos como BTC e ETH, o desconto é feito em USDT após a conversão, nunca em uma unidade do ativo. Para br_code, aparece em copia_e_cola_buffer_usd (1 USDT ou 1 USDC), sem acumular a reserva de chave Pix: o QR só é pago no valor exato, e o saldo da reserva que não for usado fica com a Lunium. A reserva não é devolvida após o pagamento. Mostre o valor antes da confirmação. 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.

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.

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.

15. Checklist de produção#

• 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 · contato@luniumpay.com. Acompanhe status e o canal de parceiros. Ao pedir ajuda, envie IDs e request_id quando disponível, sem compartilhar a chave completa.