Política de exceções de dinheiro

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

Alguns desfechos mexem em dinheiro que o seu produto já entregou ao jogador: estorno, chargeback, devolução de saque, pagamento tardio. Para esses casos o conector não move dinheiro sozinho. Ele abre um caso numa fila e uma pessoa decide. Esta página dá o modelo da fila, a tabela de situações e o fluxo de decisão.

O que é

Há dois conceitos parecidos, com donos diferentes:

under_review Fila de exceções (needs_decision)
Onde vive Estado do objeto no Dracma Fila no seu produto
Quem decide Revisor no painel do Dracma Um administrador no seu backoffice
O que decide Se o dinheiro do Dracma segue adiante (aprovar, devolver, recusar) Se a carteira do jogador muda (creditar, debitar, recreditar) quando não há regra automática segura
Dinheiro enquanto espera Nenhum movimento: depósito não credita e saque mantém a reserva Nenhum movimento

O nome needs_decision é uma sugestão. O que importa é a fila existir, ter dono e gerar alerta.

Quando usar

Abra um caso nas situações da tabela abaixo. Em nenhuma delas o seu conector move dinheiro sozinho.

Como funciona

Tabela de situações

Situação Default seguro Ações humanas possíveis
Depósito já creditado vai a refunded ou chargeback Não debita. Abre caso Encerrar sem mover (a perda fica com a casa) ou débito manual e auditado na carteira
Saque pago vai a returned (banco devolveu) Não recredita. Abre caso. O dinheiro voltou ao caixa da operação no Dracma Recreditar pela carteira (auditado) ou encerrar sem mover. Avisar o jogador para cadastrar outra chave
Depósito pago depois de expired, cancelled ou failed (paid_amount num estado terminal) Não credita. Abre caso Creditar só se o Dracma estiver em paid naquele momento; senão encerrar e pedir ao suporte do Dracma o destino do valor
409 no envio de um saque (idempotency_key_reused, ou duplicate_external_id com corpo diferente) Mantém a reserva. Nada é devolvido nem reenviado Investigar. Devolver a reserva só com prova de que o dinheiro não está no PSP
Fetch-back incoerente (external_id desconhecido, ou amount, currency ou player_ref diferentes do que você gravou) Não credita. Alerta crítico Investigar: pode ser bug ou ataque
Seu envio esgotou as tentativas e a consulta por external_id não resolveu Mantém a reserva Reprocessar com a mesma Idempotency-Key. Devolver só com prova de que o saque não existe
recalled ou paid_partial (estados do contrato que o PIX não usa) Não mexe Tratar como returned se ocorrer, após confirmar com o suporte

Fluxo: quando mover dinheiro sozinho

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

Só duas famílias de efeito são automáticas:

  1. Depósito paid: credita uma vez.
  2. Saque rejected, failed ou cancelled: devolve a reserva ao jogador. E paid finaliza a reserva.

Todo o resto vai para uma pessoa. O motivo: um débito automático em jogador que já sacou deixa saldo negativo, e um recrédito automático de saque devolvido pode pagar duas vezes se o banco reenviar. Esses casos são raros e caros.

O caso na fila

Registre em cada caso, no mínimo:

Campo Para quê
Tipo da situação Escolher a ação possível
id do Dracma e external_id Achar o objeto e a história (GET /v1/events?object_id=)
Estado e version do Dracma Saber o que foi aplicado
Valor e jogador Decidir
trace_id Falar com o suporte
Quem abriu, quando, quem decidiu, motivo e desfecho Auditoria

Ações da fila

Ação Quando Regra
credit Depósito, só com o Dracma em paid agora Credita uma vez, idempotente
refund Saque, só com o dinheiro fora do PSP ou devolvido ao caixa Recredita o jogador, auditado
confirm_paid Saque cujo paid você não viu Finaliza a reserva
close Qualquer caso Encerra sem mover dinheiro

Recomendações para a fila:

  • Ler a fila exige uma permissão; decidir exige outra, mais restrita, com reautenticação (step-up) e motivo obrigatório.
  • Alerte caso parado: um aviso depois de algumas horas e um alerta crítico depois de um dia. Os prazos são seus.
  • Nunca decida sem consultar o objeto pela API no momento da decisão.

Exemplos

Um saque de R$ 50,00 pago e depois devolvido pelo banco:

  1. O Dracma envia withdrawal.returned. Você lê GET /v1/withdrawals/{id}: status: "returned", return.returned_amount igual a R$ 50,00.
  2. O seu conector não recredita. Abre o caso "saque devolvido", com o valor devolvido e o jogador.
  3. O seu produto mostra "Saque em análise".
  4. Um administrador decide: recreditar (com motivo e auditoria) ou encerrar. O caixa da operação no Dracma já recebeu o valor devolvido.
  5. Se o administrador recreditar, o jogador é avisado para cadastrar outra chave.

Erros e casos de borda

  • Evento repetido. O mesmo desfecho pode chegar mais de uma vez. Abra um caso por objeto e por tipo, não por evento.
  • Devolução parcial. Credite, se decidir recreditar, só o valor de return.returned_amount.
  • Caso parado. Alerte. Um caso esquecido deixa o jogador sem resposta e o financeiro com diferença.
  • Reserva sem desfecho. Se o seu envio perdeu a resposta, nunca devolva a reserva: consulte GET /v1/withdrawals?external_id= antes.

Veja também