Guia da Nero — nero_payments como conector do Dracma

Este guia é para o time da Nero (a bet) implementar e ajustar o nero_payments, o único serviço da bet que fala com o Dracma. Ele junta, num lugar só, o que as páginas gerais deste repositório dizem e o que é específico da Nero: as rotas do portal que o front consome (Contrato §11), o mapeamento de estados para a tela do jogador, o outbox, a fila needs_decision e as decisões do dono (DECISOES D1–D24).

Base. Contrato de integração v1 1.1.0 (normativo), openapi.yaml, DECISOES e o código real do Dracma conferido em 2026-09-27. Onde o código difere do contrato, este guia diz o que o código faz e aponta para ../divergencias.md.

Ordem de leitura

# Página O que você sai sabendo
1 fluxo.md O caminho ponta a ponta (jogador → portal → nero_payments → Dracma → PSP → webhook → fetch-back → carteira), com diagramas, e o papel do outbox dracma_intents
2 estados-no-front.md Como cada estado do Dracma vira um estado do front (Contrato §11) e o que o portal devolve ao jogador em cada caso
3 deposito.md Como implementar POST/GET /api/payments/deposits: conversão de valor, corpo do Dracma, Idempotency-Key = external_id, exigências por operação (e-mail com Mercado Pago), erros
4 saque.md Como implementar POST /api/wallet/withdraw/request: reserva antes, player.ip, mapeamento da chave PIX, erros e o que devolver
5 webhook-e-jobs.md Rota do webhook, verificação, fetch-back, job de GET /events a cada 5 min, reconciliação diária, métricas e alertas
6 revisao-e-decisoes.md under_review (quem decide, o que a bet faz) e a fila needs_decision (D6, D7, D8, D11, D12, D18)
7 rede-e-segredos.md IPs, allowlist nos dois sentidos, mTLS, egress restrito, rotação de chave/segredo/certificado
8 primeiros-passos-sandbox.md Passo a passo com comandos copiáveis: primeiro depósito e primeiro saque no sandbox
9 go-live-nero.md Checklist de produção da Nero, com a prova exigida em cada item

Referência geral (vale para qualquer operador): ../autenticacao.md, ../webhooks.md, ../depositos.md, ../saques.md, ../erros-e-idempotencia.md, ../reconciliacao.md, ../sandbox.md. Exemplos executáveis: ../exemplos/README.md.

A Nero no Dracma

Item Valor
Tenant a pessoa jurídica da Nero
Operações nero-br-hml (ambiente sandbox, chave key_test_…) e nero-br-prd (ambiente production, chave key_live_…)
Conector nero_v2/nero_payments — único dono da credencial do Dracma
Moeda e método BRL / pix (depósito e saque)
PSP de depósito escolhido pelo Dracma por operação: MaximaxPay (ADR-0003) ou Mercado Pago (ADR-0013, só depósito). Com Mercado Pago, player.name e player.email são obrigatórios; com MaximaxPay, player.name
PSP de saque MaximaxPay (o Mercado Pago não tem payout PIX)
Multiplicador do automático X = 1 (D2): o jogador saca no automático até o que depositou e o Dracma liquidou
Depósitos antigos não contam para o X× (D3): o primeiro saque de jogador antigo vai para revisão

A VPS de teste da Nero hoje aponta para o Dracma falso (nero_dracma_sandbox), que só serve de teste. Em produção real, enquanto não houver credencial do Dracma, depósito e saque respondem 503 payment_provider_not_configured e o resto da bet funciona normalmente (D5, piso 10).

As regras que não se negociam

  1. Credita só em paid lido por fetch-back (GET /v1/deposits/{id} com a credencial da Nero), nunca pelo corpo do webhook nem pelo front.
  2. Reserva antes do saque, na mesma transação que grava o dracma_intents; devolve só em rejected/failed/cancelled confirmados ou em 4xx conclusivo.
  3. Idempotency-Key = external_id (dep_<uuidv7>/wdr_<uuidv7>), gravados antes da chamada. Repetição de POST de dinheiro usa sempre a mesma chave. Nunca gere chave nova para "tentar de novo".
  4. Estado desconhecido não move dinheiro. Nem crédito, nem débito, nem devolução de reserva.
  5. Nada de automático em débito. Estorno, chargeback/MED, returned, recalled, pagamento depois de expirar: needs_decision + alerta; um humano decide (D6, D7, D8, D18).
  6. Identidade do jogador vem do portal (X-Nero-Identity), nunca do corpo. player.external_ref é o id interno imutável do jogador — nunca e-mail, telefone ou CPF.
  7. Segredo só no nero_payments: arquivo 0400 do user Linux do serviço, entregue pelo ops da Nero; nunca em front, bundle, log, repositório ou variável NEXT_PUBLIC_*.

A lista completa, no formato MUST/NEVER (ids R01…R36), está na referência rápida — e, concatenada com todo o guia, no llms-full.txt.

Pontos a confirmar do lado da Nero

Ponto Por quê Sugestão deste guia
Formato de amount nas respostas do portal o §11 fixa o pedido (number em reais), não a resposta devolver no mesmo formato do pedido, gerado do inteiro por formatação exata (sem float)
Valores legados de pix_type no corpo do saque o front antigo pode mandar evp, aleatoria, telefone mapear para random/phone (ver saque.md)
Exibir expected_settlement_date e estados bancários (D24) só com wire/SWIFT (v1.1.0) manter processing/under_review até a bet decidir