Guia da Nero: o conector nero_payments¶

Para: Dev, Adm — Conferido em 2026-10-18.

Um caso real: o conector nero_payments de uma casa de apostas, único serviço dela que fala com o Dracma. A parte do Dracma foi conferida na data acima. A parte da Nero (nomes de serviços, rotas do portal e decisões do dono) é a descrição adotada pelo time dela.

O que é¶

A Nero é uma bet que usa o Dracma para depósito e saque por PIX. Este caso reúne o que é específico dela: as rotas do portal que o front consome, o mapeamento de estados para a tela do jogador, o outbox, a fila needs_decision e as decisões do dono (D1 a D24). Tudo que vale para qualquer operador está nas páginas gerais e aparece aqui só como link.

A Nero no Dracma¶

Item	Valor
Tenant	A pessoa jurídica da Nero
Operações	nero-br-hml (operação Teste, chave key_test_) e nero-br-prd (operação Real, chave key_live_)
Conector	nero_payments, único dono da credencial do Dracma
Moeda e método	BRL e pix, em depósito e saque
PSP de depósito	Escolhido pelo Dracma por operação. Com o Mercado Pago, player.name e player.email são exigidos; com a MaximaxPay, player.name
PSP de saque	MaximaxPay
Multiplicador do saque automático	X = 1 (D2): o jogador saca no automático até o que depositou e o Dracma liquidou
Jogadores antigos	Depósitos feitos antes do Dracma não contam para o X× (D3): o primeiro saque de um jogador antigo vai para revisão

A tabela completa de PSPs por operação está em PSPs. O modelo de ficha para descrever uma operação está em Ficha do operador.

Decisões do dono que moldam o conector¶

Decisão	Efeito no conector
D1	Tratamento dos saques de jogadores antigos (decisão registrada pelo dono; ver o item N33 do Go-live da Nero)
D2	X = 1
D3	Depósitos anteriores ao Dracma não contam para o X×
D4	Pagamento de terceiro ou de valor diferente: devolver
D5	Em produção sem credencial do Dracma, depósito e saque respondem 503 payment_provider_not_configured e o resto da bet funciona
D6	Depósito creditado que vira refunded ou chargeback: não debita; needs_decision
D7	Saque paid que vira returned: não recredita; needs_decision
D8	Depósito pago depois de expirar ou cancelar: não credita; needs_decision
D11	Ações e permissões do backoffice sobre needs_decision
D12	409 no envio de saque: reserva mantida, nada devolvido nem reenviado
D18	Saque recalled: como D7
D24	Nunca mostrar ao jogador o estado bancário nem a palavra "compliance"

Quando usar¶

Leia este caso depois das páginas gerais, quando quiser ver o desenho completo aplicado: portal, conector, livro e backoffice. Para outro produto, copie a estrutura e troque as decisões pelas suas.

Ordem de leitura¶

#	Página	O que você sai sabendo
1	Fluxo ponta a ponta	O caminho jogador, portal, conector, Dracma, PSP, webhook, fetch-back e carteira
2	Estados no front	Como cada estado do Dracma vira um estado do front
3	Depósito	Como implementar a rota de depósito do portal
4	Saque	Como implementar a rota de saque: reserva antes, player.ip, chave PIX
5	Webhook, eventos e reconciliação	Rota do webhook, job de GET /events, reconciliação, métricas e alertas
6	Revisão e decisões	under_review e a fila needs_decision
7	Rede e segredos	Credenciais, egress restrito e rotação
8	Primeiros passos no sandbox	O primeiro depósito e o primeiro saque, com as constantes da Nero
9	Go-live da Nero	Checklist de produção com a prova de cada item

Referência geral: Autenticação, Webhooks, Depósitos, Saques, Idempotência, Reconciliação, Sandbox e Exemplos executáveis.

Como funciona¶

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. A reserva só volta em rejected, failed ou cancelled confirmados, ou em 4xx conclusivo.
3. Idempotency-Key igual ao external_id (dep_<uuidv7> ou wdr_<uuidv7>), gravados antes da chamada. Repetição de POST de dinheiro usa sempre a mesma chave.
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, returned, recalled e pagamento depois de expirar vão para needs_decision e um humano decide (D6, D7, D8, D18).
6. A 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 usuário 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 e NEVER está na Referência rápida.

Exemplos¶

Os trechos de código e os corpos de requisição estão nas páginas de Depósito e Saque. O caminho completo em comandos está em Primeiros passos no sandbox.

Erros e casos de borda¶

Pontos a confirmar do lado da Nero¶

Ponto	Por quê	Sugestão
Formato de amount nas respostas do portal	O contrato do portal fixa o pedido (número 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 ou telefone	Mapear para random e phone (Saque)
Exibir expected_settlement_date e estados bancários (D24)	Só existem em transferência bancária	Manter processing e under_review até a Nero decidir

Veja também¶

• Casos e Ficha do operador.
• Arquitetura do conector: o desenho geral que este caso aplica.
• Estados no seu produto e Política de exceções de dinheiro.