# Checklist de integração Pix e cripto — LuniumPay

Revisado em 18/09/2026. Documento de trabalho para desenvolvedores e agentes de IA.
Preencha com evidências de teste. Não coloque chaves, tokens, CPFs, dados bancários
ou dados de clientes neste arquivo. Use variáveis de ambiente e identificadores de teste.

## 1. Defina o produto antes de escrever código

- Nome do projeto:
- Responsável técnico:
- Fluxo: [ ] Pix → custódia BRL [ ] Pix → cripto [ ] Cripto → Pix [ ] Payout Pix
- Quem recebe o saldo ou pagamento:
- Custódia da casa ou subconta por cliente:
- Ativo/rede pretendidos (confirmar no catálogo):
- Critério de conclusão visível para o usuário:

Receber Pix em custódia significa crédito em BRL. Não exiba esse crédito como
USDT recebido. Para entrega direta de cripto, distinga Pix pago de liquidação
concluída. Para payout, consulte o estado final antes de anunciar pagamento feito.

## 2. Use as fontes atuais

- Manual: https://docs.luniumpay.com/manual
- Contrato: https://docs.luniumpay.com/openapi.json
- Sandbox: https://docs.luniumpay.com/sandbox
- Integração com IA: https://docs.luniumpay.com/integrar-com-ia
- Demonstração: https://luniumpay.com/integrar
- Status: https://docs.luniumpay.com/status

- [ ] Confirmar endpoints, autenticação, campos e estados no contrato atual.
- [ ] Consultar limites e taxas da chave em GET /keys/me.
- [ ] Consultar catálogo correto: GET /cashin/catalog para entrega de cripto;
      GET /catalog para entrada de cripto seguida de Pix.
- [ ] Usar a prévia para validar valor mínimo da rota; não fixar valores no código.
- [ ] Tratar memo/tag quando exigido e mostrar ativo e rede ao depositante.

## 3. Critérios de aceite na sandbox

| Caso | Evidência esperada | Resultado / referência de teste |
|---|---|---|
| Fluxo principal | Operação chega ao estado final documentado | |
| Valor mínimo | Valor anunciado é aceito; abaixo dele há erro legível | |
| Saldo insuficiente | Saque/payout é recusado sem saldo negativo | |
| Idempotência | Mesmo external_id e mesmos dados não duplicam a operação | |
| Conflito de idempotência | Mesmo external_id com dados diferentes é recusado | |
| Timeout | Aplicação consulta a operação antes de tentar novamente | |
| Expiração | Operação expirada não é mostrada como paga | |
| Retenção / atraso | Interface distingue saldo total de saldo disponível | |
| Falha / estorno | Estado e movimentações permanecem conciliáveis | |
| Webhook | Assinatura e timestamp são validados conforme o manual | |
| Reentrega | Mesmo evento não duplica crédito nem entrega | |
| Conciliação | Consulta recupera o estado quando um evento não chega | |

A disponibilidade de cada cenário depende do fluxo. Use os controles documentados
na sandbox; não presuma que todos os endpoints têm os mesmos parâmetros de simulação.
A sandbox usa valores fictícios e não comprova liquidação em produção.

## 4. Preparação do piloto de produção

- [ ] Confirmar elegibilidade, credenciais e condições com a equipe LuniumPay.
- [ ] Manter segredos no backend; nenhuma chave de produção em HTML ou aplicativo cliente.
- [ ] Confirmar webhook HTTPS e tratamento de eventos duplicados.
- [ ] Consultar novamente taxas, mínimos, rotas, retenções e saldo disponível.
- [ ] Definir valor pequeno autorizado, destinatário correto e limite de exposição.
- [ ] Acompanhar a operação ponta a ponta e registrar a conciliação.
- [ ] Definir critério de pausa e responsável por investigar divergências.

## 5. Instrução para sua IA de desenvolvimento

Leia as fontes atuais antes de implementar. Trabalhe primeiro em sandbox.
Implemente apenas o fluxo escolhido neste documento. Não invente endpoints,
campos, estados nem uma confirmação de pagamento. Não use dinheiro real nem
credenciais de produção sem autorização específica. Para cada critério de aceite,
registre o teste realizado, o resultado e o que ainda falta. Diferencie simulação
bem-sucedida de liquidação real. Não publique dados pessoais ou segredos nas evidências.

## 6. Envie contexto útil para integração

Informe o fluxo, linguagem/framework, ativo/rede pretendidos, volume estimado
(se conhecido) e dúvida técnica. Em uma falha, preserve request_id e external_id,
mas nunca envie sua chave de API.

Começar: https://luniumpay.com/integrar
Contato: contato@luniumpay.com