under_review e a fila needs_decision

Dois conceitos parecidos, com donos diferentes:

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 reserva) nenhum movimento

1. 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 (→ paid, aí a Nero credita pelo fetch-back) ou devolver ao pagador (→ returned, a Nero mostra failed com "devolvido");
  • default da Nero (D4): devolver pagamento de terceiro ou de valor diferente;
  • com o Mercado Pago, PAYER_UNKNOWN é esperado com frequência (o PSP não informa o documento do pagador real, ADR-0013 MP-L2). 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;
  • decisão no painel do Dracma: 1 revisor, ou 2 com DUAL_APPROVAL_REQUIRED;
  • aprovado → approved → processing → paid (finaliza); recusado → rejected (devolve);
  • a Nero pode pedir revisão (review_requested: true) mas nunca pular uma.

2. needs_decision — quando abrir

Abra um caso (e dispare alerta, log ALERTA, 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 Default em vigor Ações possíveis no backoffice (D11)
Depósito já creditado vai a refunded ou chargeback (MED) D6 não debita; needs_decision close (perda com a casa) ou débito manual auditado pela carteira
Saque pago vai a returned (banco devolveu) 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/cancelled (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 (v1.1.0) D18 não recredita como D7
Depósito paid_partial (v1.1.0) contrato §6.1 não credita (a Nero não implementa parcial) credit do valor parcial, se o dono decidir
Fetch-back incoerente (external_id desconhecido, amount/currency/player_ref diferentes do intent) contrato §4.6 não credita; alerta P1 investigar (possível ataque ou bug)
Outbox esgotou tentativas e GET ?external_id= não resolveu contrato §7 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, close (encerra sem mover). Ler exige payments.decisions.read; decidir exige payments.decisions.write + step-up + motivo. Alerta de caso parado: mais de 4 h é aviso; mais de 24 h é crítico.

3. 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 + 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.