under_review e a fila needs_decision

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

Dois conceitos parecidos, com donos diferentes. Esta página mostra como a Nero os separa e quais decisões do dono definem cada caso.

O que é

under_review needs_decision
Onde vive Estado do objeto no Dracma Fila na Nero (nero_payments, tela do backoffice)
Quem decide Revisores da Nero no painel do Dracma Admin da Nero no backoffice da Nero (D11)
O que decide Se o dinheiro do Dracma vai adiante (aprovar, devolver ao pagador, recusar saque) Se a carteira do jogador muda (creditar, debitar, recreditar) quando não há regra automática segura
Dinheiro na carteira enquanto espera Nenhum movimento (depósito não credita; saque mantém a reserva) Nenhum movimento

A versão genérica da fila de exceções, para qualquer produto, está em Política de exceções de dinheiro.

Quando usar

Ao desenhar a tela de backoffice, as permissões e os alertas de caso parado, e ao treinar o time de suporte.

Como funciona

under_review: o que a Nero faz

Depósito em under_review (review_reasons: PAYER_MISMATCH, PAYER_UNKNOWN, AMOUNT_MISMATCH, PAID_AFTER_EXPIRY, PAYER_BLOCKED, RULES_UNAVAILABLE):

  • A Nero não credita; o front mostra under_review ("pagamento em análise").
  • A decisão é no painel do Dracma: aprovar (o depósito vai a paid e a Nero credita pelo fetch-back) ou devolver (vai a returned, e a Nero mostra failed com "devolvido").
  • Padrão da Nero (D4): devolver pagamento de terceiro ou de valor diferente.
  • Com o Mercado Pago, PAYER_UNKNOWN é frequente porque o PSP não informa o documento do pagador real. Planeje gente para revisar, ou aceite que esses depósitos demorem.

Saque em under_review (decision.reasons):

  • A reserva continua; o front mostra under_review.
  • A decisão é no painel do Dracma: uma pessoa, ou duas quando o motivo é DUAL_APPROVAL_REQUIRED.
  • Aprovado: approved, processing, paid (finaliza). Recusado: rejected (devolve).
  • A Nero pode pedir revisão (review_requested: true), mas nunca pular uma.

needs_decision: quando abrir

Abra um caso, dispare alerta, registre ALERTA no log e incremente a métrica nero_payments_dracma_needs_decision_total nestas situações. Em nenhuma delas o nero_payments move dinheiro sozinho.

Situação Decisão do dono Padrão em vigor Ações possíveis no backoffice (D11)
Depósito já creditado vai a refunded ou chargeback D6 Não debita; needs_decision close (perda com a casa) ou débito manual auditado pela carteira
Saque pago vai a returned D7 Não recredita; needs_decision. O dinheiro voltou ao caixa da operação no Dracma Recreditar pela carteira (auditado) ou close; avisar o jogador para cadastrar outra chave
Depósito pago depois de expired ou cancelled (o fetch-back mostra paid_amount num estado terminal) D8 Não credita; needs_decision credit só se o Dracma estiver em paid agora; senão close e pedir devolução no painel do Dracma
409 no envio de um saque (idempotency_key_reused, ou duplicate_external_id com corpo diferente) D12 Reserva mantida; nada devolvido nem reenviado Investigar; refund só com o dinheiro comprovadamente fora do PSP
Saque recalled D18 Não recredita Como D7
Depósito paid_partial Contrato Não credita (a Nero não implementa parcial) credit do valor parcial, se o dono decidir
Fetch-back incoerente (external_id desconhecido, valor, moeda ou jogador diferentes do intent) Contrato Não credita; alerta P1 Investigar (possível ataque ou bug)
Outbox esgotou as tentativas e a consulta por external_id não resolveu Contrato Reserva mantida Reprocessar com a mesma chave; refund só com prova de que o saque não existe

Ações do backoffice (D11): credit (depósito, só com o Dracma em paid agora), refund (saque, só com o dinheiro fora do PSP ou devolvido ao caixa), confirm_paid e close (encerra sem mover). Ler exige a permissão payments.decisions.read; decidir exige payments.decisions.write, step-up e motivo. Caso parado há mais de 4 horas é aviso; há mais de 24 horas é crítico.

Os débitos que a Nero não automatiza

flowchart TD A["Evento lido por fetch-back"] --> B{"Estado conhecido com regra escrita?"} B -->|"não"| Z["200, sem efeito, confere depois"] B -->|"sim"| C{"Move dinheiro a favor do jogador sem risco? paid (depósito), rejected, failed, cancelled (saque)"} C -->|"sim"| D["Aplica, idempotente por external_id"] C -->|"não: refunded, chargeback, returned, recalled, paid_partial, pago após expirar"| E["needs_decision e alerta"]

Por quê: um débito automático em jogador que já sacou deixa saldo negativo; um recrédito automático de saque devolvido pode pagar duas vezes se o banco reenviar. Esses casos são raros e caros: vão para uma pessoa.

Exemplos

Para provocar refunded, chargeback e returned no sandbox e ver o caso entrar na fila, use as Receitas 8 e 12.

Erros e casos de borda

  • Caso aberto duas vezes para o mesmo external_id: a fila deve ser idempotente por objeto e por situação.
  • Decisão tomada no backoffice sem o motivo: recuse. O motivo é parte da trilha de auditoria.
  • Papel sem a permissão de decidir: a tela mostra o caso, mas não oferece as ações.

Veja também