Guia para desenvolvedores · testes de integração
Sandbox de API PIX, custódia e cripto
Valide a jornada financeira do seu produto antes de usar uma chave de produção. A sandbox Lunium simula cobranças PIX, saldo BRL, entrega e saque cripto, payout e cash-out na mesma API usada pela integração.
Seis jornadas, com critério de conclusão
A credencial lun_test_ seleciona o ambiente fictício. A URL base continua https://api.luniumpay.com. Você testa requisições, respostas, estados, saldo e eventos sem pagar PIX ou enviar cripto.
| Jornada | Como criar | Quando terminou |
|---|---|---|
| PIX → custódia BRL | POST /cashin/charge, destino: "saldo" | paid e sent, com crédito na subconta correta. |
| PIX → cripto | POST /cashin/charge, destino: "cripto" | paid e sent; hash fictício sandbox:. |
| Custódia → cripto | POST /saldo/sacar-cripto | Entrega sent e débito conciliado, incluindo taxa. |
| Custódia → PIX | POST /payouts | status=sent, com E2E fictício e débito no extrato. |
| Transferência interna | POST /saldo/transferir | Débito e crédito nas referências certas; total custodiado conservado. |
| Cripto externa → PIX | POST /cash-outs e aceite | state=COMPLETED; depósito e PIX simulados. |
O QR contém SANDBOX:NAO_PAGAVEL:. Não é um PIX bancário. A confirmação usa POST /sandbox/cashin/{cashin_id}/pay. Nenhum banco, corretora ou blockchain é acionado.
Comece pelo navegador ou pelo seu backend
A integração guiada permite escolher o fluxo e executar uma demonstração informando só o seu e-mail. Para implementar no seu projeto, baixe o kit Node e Python, extraia e execute:
node sandbox.mjs all
# ou Python 3.9+, sem dependências:
python3 sandbox.py allO kit cria uma chave de teste em memória com o e-mail de quem vai testar (defina LUNIUM_SANDBOX_EMAIL; sem ele o kit para com uma mensagem clara) e verifica GET /keys/me antes de operar. Também aceita LUNIUM_API_KEY com uma credencial exclusivamente de teste e recusa chaves de produção. Use custody, cashin, payout ou cashout no lugar de all para selecionar uma jornada.
Para fazer as chamadas manualmente
curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
-H 'Content-Type: application/json' \
-d '{"email":"voce@empresa.com","name":"Minha integração"}'O email de quem vai testar é obrigatório: é para ele que mandamos o manual, o fluxograma e o passo a passo da integração. Sem ele, a resposta é 400 email_obrigatorio. Guarde o campo api_key em uma variável de ambiente do backend; não o coloque no frontend, URL ou conversa com IA. Reutilize a chave: a criação tem cota por IP. Consulte GET /sandbox para capacidades e a matriz atual de cenários.
Teste também o que impede a conclusão
| Cenário | O que seu sistema deve fazer |
|---|---|
delayed / held | Exibir espera ou retenção sem criar outra operação. Os cenários disponíveis dependem do fluxo. |
expired / payer_mismatch | Encerrar ou conciliar a cobrança sem creditar saldo indevido. |
settlement_failed | Distinguir pagamento confirmado de entrega malsucedida. Conferir o resultado e o extrato. |
settlement_uncertain | Preservar a operação original e não presumir estorno. Use a resolução fictícia apenas na sandbox. |
route_unavailable / provider_unavailable | Mostrar uma falha acionável, sem anunciar criação ou débito que não ocorreu. |
| Saldo insuficiente e repetição | Recusar gasto sem saldo; repetir a mesma referência e corpo sem duplicar cobrança ou saque. |
Para cash-in, custódia e payout, envie sandbox_scenario somente com chave de teste e consulte scenarios_by_flow em GET /sandbox. Nem todo cenário se aplica a toda jornada. Uma operação incerta pode ser resolvida por POST /sandbox/operations/{operation_id}/resolve com {"outcome":"sent"} ou {"outcome":"failed"}.
O cash-out usa gatilhos nas duas casas decimais de amount ou brl_amount: .00 sucesso, .01 demora, .02 falha, .03 expiração e outros descritos no guia técnico de cenários. Não aplique esses gatilhos como regra de produção.
Webhooks reais para eventos fictícios
Configure uma URL HTTPS pública sua e guarde webhook_secret. O evento da sandbox traz sandbox:true, mas a entrega HTTP e sua assinatura usam a fila real de webhooks. Isso permite testar validação HMAC, resposta do seu servidor, duplicatas e reenvio.
| Endpoint | Validação possível |
|---|---|
GET /sandbox/events | Eventos da simulação, mesmo sem callback configurado. |
GET /webhooks/deliveries | Tentativas de entrega, resposta do receptor e resultado. |
POST /webhooks/deliveries/{event_id}/retry | Reenvio para comprovar processamento idempotente. |
Valide o corpo bruto, timestamp e event_id conforme o contrato de assinatura. Configure o callback antes da operação: eventos antigos não são enviados retroativamente pela simples configuração da URL.
O que o teste comprova — e o que depende da produção
A sandbox comprova que seu software consegue criar, acompanhar e conciliar as jornadas simuladas. Cotações e catálogos são snapshots sintéticos. Os mínimos, disponibilidade, preços, limites e retenções de produção devem ser consultados novamente com a chave real.
Cash-in, custódia, payout e transferências persistem isolados do livro financeiro real. Cash-out também é persistido, com retenção de duas horas. Há limite de 1.000 operações por chave para as novas jornadas e 1.000 cash-outs. Use POST /sandbox/reset com {"confirm":true} para limpar o estado fictício; o histórico de webhooks já enfileirados permanece.
Não são simulados tokens DEX arbitrários por contrato, leitura bancária de QR dinâmico, confirmações reais de blockchain ou políticas privadas dos provedores. Retenções de teste têm tempo comprimido. A conclusão não certifica liquidez nem execução bancária: um piloto com PIX pago e cripto entregue é uma operação real e precisa de valor e destinatário autorizados.
Dúvidas de integração
A sandbox simula só cripto para PIX?
Não. Ela cobre as seis jornadas da tabela, incluindo PIX para custódia ou cripto, saques e transferências. O fluxo de entrada PIX exige a confirmação explícita pela API de simulação.
Como receber sem uma carteira fixa no teste?
Envie destino: "saldo" na cobrança. O saldo fica em BRL e a escolha de carteira acontece somente em um saque cripto posterior.
Posso integrar com ChatGPT ou outro agente?
Use o guia de integração com IA e o briefing da página guiada. A conexão pública via MCP oferece descoberta e demonstrações de sandbox; operar contas de produção pelo ChatGPT ainda exige autenticação dessas contas.
Onde está o contrato para gerar minha integração?
O OpenAPI, o manual e o manifesto de integração descrevem os fluxos. Peça à IA para lê-los antes de editar seu projeto e mantenha as credenciais fora do chat.