Estados no front da Nero¶

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

O front da Nero (nero_client) não conhece o Dracma. Ele vê um conjunto fechado de estados, fixado no contrato do portal, que o nero_payments calcula a partir de duas fontes: o estado local do outbox e o último estado do Dracma aplicado (lido por fetch-back).

O que é¶

Esta página é a tabela de tradução entre os estados do Dracma e os do front. A regra geral é que o estado mostrado ao jogador nunca adianta dinheiro: paid só aparece depois que o crédito (depósito) ou a finalização (saque) foi gravado no nero_ledger. A versão genérica desta tabela, para qualquer produto, está em Estados no seu produto.

Rotas do portal¶

Método e rota (portal)	Autenticação	Pedido e resposta
POST /api/payments/deposits	Jogador	{amount: number (reais, ex. 50.00), method: "pix", accept_bonus: bool, cpf?: string} devolve 201 ou 202 com {deposit_id, status, amount, currency, method, pix?: {copy_paste, qr_code_png_base64?, expires_at}, expires_at}
GET /api/payments/deposits/{deposit_id}	Jogador, só o dono (outro recebe 404)	Mesmo formato; o front faz polling até paid ou expired
POST /api/wallet/withdraw/request	Jogador	Corpo legado {amount, type: "pix", pix_key, pix_type, accept_terms, currency?} devolve 200 {status: true, withdrawal_id, state: "processing" ou "under_review", message}; os erros de negócio mantêm as mensagens atuais
GET /api/payments/withdrawals/{withdrawal_id}	Jogador, só o dono	{withdrawal_id, state, amount, currency, created_at, updated_at}
POST /api/payments/dracma/webhook	Nenhuma no portal; assinatura no conector	200, 401, 400 ou 503 (Webhook, eventos e reconciliação)

deposit_id e withdrawal_id são o external_id enviado ao Dracma (dep_<uuidv7>, wdr_<uuidv7>), opacos para o front. O id do Dracma fica só no nero_payments.

Rotas legadas removidas (respondem 404 depois do corte): /api/wallet/deposit/payment, /api/payments/{deposits,callbacks,status}/{gateway}, /api/{gateway}/qrcode-pix, /api/{gateway}/consult-status-transaction e os callbacks dos gateways antigos.

Quando usar¶

Ao implementar a tradução de estado no nero_payments e a tela de depósito e saque. Confira cada linha com o time de produto antes de fixar as mensagens.

Como funciona¶

Depósito: Dracma para o front¶

Estados do front: creating, pending, paid, expired, cancelled, failed, under_review.

Situação no nero_payments	Estado do Dracma (fetch-back)	Front vê	Dinheiro na carteira	Mensagem sugerida
Intent gravado, sem resposta conclusiva (timeout, 5xx, 429)	Nenhum	creating	Nada	"Gerando seu PIX..."
202 do Dracma	created	creating	Nada	"Gerando seu PIX..."
Nenhuma	pending	pending (com pix)	Nada	"Pague o PIX até {expires_at}"
Nenhuma	under_review	under_review	Nada	"Pagamento recebido, em análise."
Crédito gravado no ledger	paid	paid	Creditado uma vez	"Depósito confirmado."
Nenhuma	expired	expired	Nada	"O PIX expirou. Gere outro."
Nenhuma	cancelled	cancelled	Nada	"Depósito cancelado."
Nenhuma	failed	failed	Nada	"Não foi possível gerar o PIX. Tente de novo."
Nenhuma	returned	failed	Nada	"O pagamento não pôde ser aceito. Fale com o suporte."
paid já creditado, depois estorno ou chargeback	refunded ou chargeback	paid (continua)	Não mexe: needs_decision (D6)	Tratado pelo backoffice
Nenhuma	pending_compliance ou frozen	under_review	Nada	"Pagamento em análise."
Nenhuma	paid_partial	under_review	Nada: needs_decision	"Pagamento em análise."
Nenhuma	Estado desconhecido	Mantém o último estado mostrado (ou under_review se era pending)	Nada	"Pagamento em análise."
4xx na criação (sem objeto no Dracma)	Nenhum	Erro HTTP ao front (sem deposit_id utilizável)	Nada	Tabela de erros em Depósito
Produção sem Dracma configurado (D5)	Nenhum	Erro 503 payment_provider_not_configured	Nada	"Depósito indisponível no momento."

• returned não existe na lista de estados do front: a Nero mostra failed com a mensagem de devolução.
• refunded e chargeback acontecem depois de o jogador ter visto paid. A tela não volta atrás; o caso vai para a fila needs_decision (Revisão e decisões).
• Nunca explique under_review com o motivo (PAYER_MISMATCH, AMOUNT_MISMATCH) ao jogador; o suporte vê.
• Com o Mercado Pago, under_review por PAYER_UNKNOWN fica mais comum, porque o PSP não informa o pagador (PSPs).

Saque: Dracma para o front¶

Estados do front: processing, under_review, paid, rejected, failed, cancelled.

Situação no nero_payments	Estado do Dracma (fetch-back)	Front vê	Reserva no ledger	Mensagem sugerida
Intent e reserva gravados, sem resposta conclusiva	Nenhum	processing	Mantida	"Saque em processamento."
Nenhuma	requested (consulta de titularidade pendente)	processing	Mantida	"Saque em processamento."
Nenhuma	approved ou processing	processing	Mantida	"Saque em processamento."
Nenhuma	under_review	under_review	Mantida	"Saque em análise."
Finalização gravada	paid	paid	Finalizada (saída definitiva)	"Saque enviado."
Nenhuma	rejected	rejected	Devolvida	"Saque não aprovado. O valor voltou para sua carteira."
Nenhuma	failed	failed	Devolvida	"Não foi possível enviar o PIX. O valor voltou para sua carteira."
Nenhuma	cancelled	cancelled	Devolvida	"Saque cancelado. O valor voltou para sua carteira."
paid já finalizado, o banco devolveu	returned	under_review	Não mexe: needs_decision (D7)	"Saque em análise."
Nenhuma	pending_compliance, sent, in_transit ou recall_requested	processing	Mantida	"Saque em processamento." (nunca dizer "compliance", D24)
Nenhuma	recalled	under_review	Não mexe: needs_decision (D18)	"Saque em análise."
Nenhuma	Estado desconhecido	processing	Mantida	"Saque em processamento."
4xx na criação (422, 400)	Nenhum	200 {status: false, message} (mensagem legada)	Devolvida	Saque
409 idempotency_key_reused no envio	Nenhum	processing	Mantida: needs_decision (D12)	"Saque em processamento."

Resposta do POST /api/wallet/withdraw/request: state: "under_review" quando o 201 do Dracma veio com under_review; state: "processing" em todos os outros casos aceitos, inclusive quando o Dracma não respondeu de forma conclusiva (o pedido está no outbox e a reserva está feita).

O returned do saque aparece como under_review no front e abre needs_decision: a Nero não recredita sozinha (D7). O dinheiro volta ao caixa da operação no Dracma, e o backoffice decide se recredita a carteira.

Como calcular o estado sem corrida¶

estado_front(intent):
  se intent.dracma_version é nulo:       # o Dracma ainda não respondeu de forma conclusiva
      devolve "creating" (depósito) ou "processing" (saque)
  s = intent.dracma_status                # último estado APLICADO (fetch-back, versão maior)
  devolve TABELA[s] ou PADRAO_DESCONHECIDO

• Aplique um estado novo só se a version for maior que intent.dracma_version (webhooks chegam fora de ordem).
• O efeito de dinheiro e a atualização de dracma_status vão na mesma transação do ledger. Assim o front nunca vê paid antes do crédito.
• O polling do front não chama o Dracma a cada pedido. Se o intent está parado em creating ou pending há mais de 60 segundos, o nero_payments pode fazer um fetch-back por id (no máximo a cada 10 segundos por objeto), além do webhook e do job de GET /events.

Exemplos¶

A tabela acima é o exemplo. Para o caminho completo com comandos, veja Primeiros passos no sandbox.

Erros e casos de borda¶

• Estado do Dracma que a tabela não conhece: nunca mova dinheiro. Mantenha o último estado e registre.
• Versão do evento menor ou igual à aplicada: ignore (já foi superada).
• Divergência entre o estado local e o fetch-back: vale o fetch-back; registre a diferença.

Veja também¶

• Estados no seu produto.
• Ciclo do depósito e Ciclo do saque.