Use a mesma base https://api.luniumpay.com com uma chave lun_test_. Toda operação financeira é fictícia. O QR de entrada contém SANDBOX:NAO_PAGAVEL:: não é um PIX bancário. Confirme o pagamento pela API de simulação. Nenhum saque é enviado à MEXC ou à blockchain.
Testar agora
Abra a integração guiada, escolha o fluxo e execute a demonstração. Pela conexão pública de IA, use lunium_start_sandbox_demo com flow igual a custody, cashin, payout ou cashout, além de um request_id aleatório e estável. Continue com lunium_get_sandbox_demo; ele pode criar o saque fictício já previsto na jornada após confirmar o crédito.
Para testar seu backend, baixe o kit:
node sandbox.mjs all
# ou Python 3.9+, sem dependências:
python3 sandbox.py all
O kit cria uma chave em memória, confirma GET /keys/me antes de operar e recusa credenciais de produção. Também aceita LUNIUM_API_KEY contendo exclusivamente uma chave de teste. Não imprime credenciais. Selecione custody, cashin, payout ou cashout no lugar de all para uma jornada específica.
Jornadas e conclusão
| Jornada | Criar | Confirmar e acompanhar | Sucesso |
|---|---|---|---|
| PIX → custódia BRL | POST /cashin/charge, destino: "saldo" |
POST /sandbox/cashin/{cashin_id}/pay, depois /cashin/{cashin_id}/status e /saldo |
status=paid, settlement_status=sent; disponível na subconta correta |
| PIX → BTC, USDC ou outra rota do catálogo de teste | POST /cashin/charge, destino: "cripto", asset, chain, payout_address |
Mesma confirmação de PIX e consulta de cash-in | paid e sent; hash começa com sandbox:, sem transação real |
| Custódia → cripto | POST /saldo/sacar-cripto, amount_cents, tax_number, asset, chain, payout_address |
/cashin/{cashin_id}/status |
paid e sent; débito inclui fee_cents |
| Custódia → PIX | POST /payouts, amount_cents, pix_key |
GET /payouts/{payout_id} |
status=sent; E2E fictício com ISPB 00000000 |
| Transferência interna | POST /saldo/transferir, from_customer_ref, to_customer_ref, amount_cents |
/saldo/extrato, /saldo/clientes, /saldo/consolidado |
Débito e crédito atômicos; total custodiado conservado |
| Cripto externa → PIX | POST /cash-outs, depois POST /cash-outs/{cashout_id}/accept |
GET /cash-outs/{cashout_id} |
state=COMPLETED; depósito também simulado |
Custódia não exige carteira fixa. O saldo é BRL. Escolha moeda, rede, endereço e memo apenas no saque. O kit percorre BTC nativo, USDC na Polygon e saque de USDC na Base; o catálogo de testes oferece outras rotas nominadas. No cash-in e saque use chain; no cash-out use network.
Receber na custódia sem carteira
Crie a chave com POST /keys/sandbox e guarde api_key em LUNIUM_API_KEY somente no backend. Confirme key.sandbox=true em GET /keys/me antes das chamadas abaixo. O documento deste exemplo é sintético e serve apenas ao sandbox.
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":100000,"payer_tax_number":"12345678901","destino":"saldo","customer_ref":"cliente-teste","external_id":"sandbox-deposito-001"}'
Guarde cashin_id. Para simular o pagamento:
curl --fail-with-body -X POST "https://api.luniumpay.com/sandbox/cashin/$CASHIN_ID/pay" \
-H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' -d '{}'
Consulte /cashin/{cashin_id}/status até paid e sent, geralmente cerca de 6 segundos. Depois consulte /saldo?customer_ref=cliente-teste. O crédito é líquido das taxas da chave; não compare o saldo com o valor bruto da cobrança. Repetir o pagamento não duplica crédito.
Cenários determinísticos de cash-in, custódia e payout
Envie sandbox_scenario ao criar a operação. Consulte GET /sandbox para a matriz de cenários por fluxo.
| Cenário | Resultado |
|---|---|
success |
Sucesso; padrão quando omitido |
delayed |
Retenção/demora de aproximadamente 30 segundos antes da continuação |
held |
Somente depósito em custódia: crédito bloqueado por 30 segundos, depois disponível |
expired |
Cash-in expira ao tentar simular pagamento |
payer_mismatch |
Cash-in devolvido por divergência de pagador, sem crédito/entrega |
refunded |
Cash-in devolvido sem crédito; payout devolvido com estorno único |
failed |
Falha de pagamento; payout devolve o débito uma vez |
settlement_failed |
Pagamento pode estar confirmado, mas a entrega falha; saque estorna débito e taxas |
settlement_uncertain |
Entrega fica incerto; payout continua processing. Não estorna antes da conciliação |
route_unavailable |
Criação recusada, sem débito |
provider_unavailable |
HTTP 503 simulado, sem operação criada; enquanto o cenário continuar, a recusa continua |
Para resolver uma incerteza somente em teste, chame POST /sandbox/operations/{operation_id}/resolve com {"outcome":"sent"} ou {"outcome":"failed"}. Repetir a mesma resolução é idempotente. A rota exige uma operação incerta da própria chave. Não existe confirmação fictícia em produção.
Teste também payload inválido, mínimo por moeda/rede, saldo insuficiente, gasto concorrente, conta bloqueada, ID de outra chave e external_id reutilizado com parâmetros diferentes. Use uma intenção e um external_id estáveis para retry; parâmetros divergentes são recusados. Cobrança e saque cripto compartilham o espaço de referências. Após timeout, recupere pelo ID ou pelas listas filtradas por external_id.
Cenários de cripto → PIX
O cash-out mantém os gatilhos nas duas casas decimais de amount (ou brl_amount na cotação reversa): .00 sucesso, .01 demora, .02 falha, .03 expiração, .04 limite, .05 lento, .06 recusa do provedor, .07 primeira tentativa de aceite retorna 503 e a segunda funciona, .08 limite de pagador. Na prévia, nenhum registro é criado. Nunca envie cripto ao endereço devolvido pelo simulador.
Webhooks reais sobre eventos fictícios
Configure uma URL HTTPS pública que você controla em PATCH /keys/me com webhook_url e guarde webhook_secret com segurança. Os eventos do sandbox usam a mesma fila de entrega e assinatura do produto; levam sandbox:true. Valide HMAC sobre o corpo bruto, timestamp, event_id e tolerância a duplicatas conforme o manual. Não confunda evento fictício entregue via HTTP real com liquidação financeira real.
Use GET /sandbox/events para inspecionar eventos gerados, mesmo sem callback configurado. GET /webhooks/deliveries mostra tentativas e POST /webhooks/deliveries/{event_id}/retry reenvia. Eventos anteriores à configuração do callback não são enviados retroativamente: crie uma nova operação ou use /webhooks/test. Cash-in publica cashin.paid, cashin.settled ou a falha correspondente. Retenção/liberação e transferência têm seus eventos específicos. Payout publica seu resultado final; cash-out publica progressão e conclusão.
Persistência, preços e fronteiras do teste
Cash-in, custódia, payout e transferências persistem isolados do livro financeiro real, inclusive após reinício. 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. POST /sandbox/reset com {"confirm":true} apaga apenas o estado fictício da sua chave; entregas de webhook já enfileiradas mantêm seu histórico.
Cotações e catálogos são snapshots sintéticos identificados na resposta. Os preços, mínimos, disponibilidade e análise de risco da produção podem mudar. O sandbox não chama MEXC, bancos ou carteiras. O custo de provedor do payout de teste é fixado em 100 centavos e informado em /saldo; não representa a tarifa real. A escada por CPF não consulta histórico de pessoas; /cashin/limits informa essa diferença. Testes de retenção têm tempo comprimido.
O simulador cobre ativos nominados de seu catálogo; não simula tokens DEX arbitrários por contrato, leitura bancária de QR dinâmico, a rede blockchain nem políticas privadas de cada provedor. Em produção, leia novamente /keys/me, /saldo, limites e catálogos com a chave real. Um piloto com PIX efetivamente pago e cripto enviada pela MEXC é uma operação real, com valor e destinatário autorizados. A conclusão do sandbox valida a integração de software, não certifica liquidez ou execução dos provedores.