Para plataformas e parceiros · PIX → saldo BRL
API PIX com custódia em reais
Receba PIX no saldo de custódia da sua conta ou de uma subconta, sem cadastrar carteira cripto fixa. Depois, escolha entre saque por PIX e conversão para uma moeda e rede disponíveis no catálogo de entrega.
Receba primeiro. Escolha a saída depois.
Este fluxo é adequado quando seu produto precisa receber pagamentos, manter saldos separados e deixar o destino de saque para uma etapa posterior. A custódia é em BRL: um PIX não cria saldos simultâneos de BTC, USDT e USDC. A conversão para cripto ocorre quando o saque é solicitado.
Cobrança sem carteira
Crie o PIX com destino: "saldo". Informe valor e documento do pagador; use customer_ref para direcionar o crédito a uma subconta.
Crédito e disponibilidade
Acompanhe a liquidação e confirme no extrato o valor líquido de taxas. Use o saldo disponível; retenções e carência podem manter parte do total bloqueada.
Saque escolhido depois
Use POST /payouts para PIX ou POST /saldo/sacar-cripto para escolher moeda, rede e endereço no momento do saque.
Na API, omitir destino continua significando entrega direta de cripto. Para custódia, envie explicitamente destino: "saldo". No Telegram, /cobrar valor cpf usa custódia por padrão.
Como gerar o PIX sem informar carteira
Use uma chave lun_test_, guardada no backend, e confirme key.sandbox=true em GET /keys/me. Os exemplos abaixo usam documentos e destinos sintéticos. Não os envie com credenciais de produção.
POST /cashin/charge · corpo de exemplo para sandbox
{
"amount_cents": 100000,
"payer_tax_number": "12345678901",
"destino": "saldo",
"customer_ref": "cliente-teste",
"external_id": "sandbox-custodia-001"
}O exemplo cria uma cobrança fictícia de R$ 1.000,00. Envie para https://api.luniumpay.com/cashin/charge, com a chave de teste em X-API-Key e o corpo como JSON. Não inclua payout_address nesse fluxo. payer_tax_number é o documento do pagador; customer_ref é a referência do cliente no seu sistema.
Guarde o cashin_id retornado. Na sandbox, confirme por POST /sandbox/cashin/{cashin_id}/pay com corpo {} e consulte GET /cashin/{cashin_id}/status até status=paid e settlement_status=sent. O QR de teste contém SANDBOX:NAO_PAGAVEL: e não deve ser pago em banco.
Depois, consulte GET /saldo?customer_ref=cliente-teste. O crédito é líquido das taxas da chave. Compare o extrato com o recebido efetivo, sem presumir que o valor bruto do QR virou saldo disponível.
Casa, clientes e extrato conciliável
| Consulta | Saldo ou informação retornada |
|---|---|
GET /saldo | Saldo da casa: a conta principal da chave. Não soma clientes. |
GET /saldo?customer_ref=cliente-teste | Somente a subconta informada, com disponível, bloqueado e condições aplicáveis. |
GET /saldo/consolidado | Casa e clientes, com o total custodiado para conciliação. |
GET /saldo/clientes | Lista de subcontas; siga a paginação retornada. |
GET /saldo/extrato?customer_ref=cliente-teste | Movimentos da subconta; continue por before=proxima_pagina. |
Reutilize a mesma referência, de até 80 caracteres, no depósito, na leitura e no saque. POST /saldo/transferir move saldo disponível entre subcontas ou a casa, sem gerar PIX. A transferência interna também precisa de uma intenção autorizada e um external_id estável.
A separação por customer_ref não substitui autenticação e autorização dos usuários do seu produto. A API key autoriza operações sobre todas as subcontas daquela conta; mantenha-a somente no backend.
Saque por PIX ou na cripto escolhida
Saldo BRL → PIX
POST /payouts recebe valor em centavos, chave PIX e a subconta a debitar. Confira payout.enabled, saldo e taxas antes da criação.
Saldo BRL → cripto
POST /saldo/sacar-cripto recebe valor em reais, moeda, rede, carteira, documento do titular e memo quando necessário. O endereço pode mudar a cada saque.
POST /saldo/sacar-cripto · corpo de exemplo para sandbox
{
"amount_cents": 10000,
"asset": "usdc",
"chain": "base",
"payout_address": "0x1111111111111111111111111111111111111111",
"tax_number": "12345678901",
"customer_ref": "cliente-teste",
"external_id": "sandbox-saque-usdc-001"
}No saque cripto, amount_cents é o valor BRL a converter, não a quantidade de tokens. O débito inclui a taxa da casa; conversão e custos da rota afetam a quantidade recebida. Acompanhe o cashin_id retornado até settlement_status=sent.
Selecione apenas pares entregavel=true de GET /cashin/catalog; Liquid/DePix não são suportados no saque da custódia. Consulte os mínimos atuais e o memo. POST /cashin/preview estima a conversão, mas não é uma prévia completa do débito do saque. max_debited_cents pode limitar o débito BRL, sem fixar câmbio ou quantidade de tokens.
Taxas e retenções precisam aparecer no produto
Leia deposito_fee_bps, deposito_fee_fixed_cents, carencia_horas e as próximas liberações em GET /saldo. Consulte também os limites do pagador em GET /cashin/limits. Um crédito liquidado pode continuar parcialmente bloqueado por uma regra de retenção.
Guarde external_id e o identificador retornado antes de atualizar seu pedido. Em retry, mantenha a mesma referência e o mesmo corpo. Configure um receptor HTTPS, valide a assinatura HMAC sobre o corpo bruto e deduplique por event_id. Depois de timeout, consulte a operação original antes de decidir repetir. O manual de webhooks e conciliação detalha a implementação.
Dúvidas de integração
O parceiro recebe reais ou todas as criptos?
O parceiro recebe saldo em reais, líquido das taxas. No saque cripto escolhe um par de moeda e rede entregável naquele momento. Isso não significa suporte irrestrito a todas as criptos.
É preciso uma carteira fixa na chave?
Não. O depósito em custódia não exige endereço. Em cada saque cripto você informa a carteira correspondente à rede selecionada. No saque PIX, informa uma chave PIX.
Como evitar gastar saldo bloqueado?
Use o campo disponível da subconta correta e acompanhe liberações e extrato. total_cents pode incluir valores bloqueados e não deve ser tratado como disponível para saque.
Posso testar depósito e saque na mesma sandbox?
Sim. A jornada custody cria o PIX fictício, confirma o crédito e executa saque cripto simulado. O kit completo também testa payout e transferência interna; nenhum dinheiro real se move.