Runbook de dinheiro

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

Este runbook leva do sintoma ao diagnóstico e à ação, com a verificação que prova que o problema acabou e o ponto em que você chama o suporte. Use-o quando um saldo, um saque, um depósito ou o relatório diário não fizer o que você espera.

O que é

Cada entrada tem cinco passos: sintoma (o que você viu), diagnóstico (o que consultar), ação (o que fazer), verificação (como saber que resolveu) e escalar (quando chamar o suporte). Os termos estão em Modelo de dinheiro.

Regras que valem em toda entrada:

  1. Não devolva a reserva de um saque sem resposta conclusiva (rejected, failed, cancelled ou 422 síncrono).
  2. Não reenvie um saque com external_id novo para "tentar de novo" enquanto o anterior não terminou.
  3. Não ajuste o seu livro para bater com o relatório. Abra incidente.
  4. Sempre consulte o objeto pela API antes de agir. O webhook sozinho não autoriza dinheiro.

Quando usar

Se você viu Vá para
Saque em processing há muito tempo Saque preso em processing
Saque em approved que não sai Saque approved parado
422 insufficient_operation_balance Sem caixa livre
Digest, assinatura ou total que não bate Relatório que não bate
Item return inesperado Item return inesperado
Caixa livre negativo Caixa livre negativo
Depósito em under_review há horas Depósito em revisão
paid_amount num depósito expired Pagamento tardio
Faixa "Saques em verificação" Saques em verificação
GET /v1/balances com 503 Saldo indisponível

Como funciona

Saque preso em processing

Passo O que fazer
Sintoma status continua processing por mais tempo que o normal
Diagnóstico GET /v1/withdrawals/{id}: confira status, version, updated_at. GET /v1/events?object_id={id} mostra a história
Ação Se updated_at tem menos de cerca de 1 h 30: espere, o Dracma consulta o PSP sozinho. Mantenha a reserva. Não reenvie, não cancele (responde 409) e não devolva
Verificação O saque chega a paid ou failed. Só em failed a reserva volta ao jogador
Escalar Se passar de 2 horas em processing: chamado com id do saque, external_id e trace_id. O Dracma trata o caso manualmente; nunca reenvia nem troca de PSP

Saque approved parado

Passo O que fazer
Sintoma status: "approved" e psp_reference nulo, por mais de alguns minutos
Diagnóstico Verifique, nesta ordem: (1) fora do horário do automático? (Dia, fuso e horários); (2) caixa livre menor que o valor? (Saldos e caixa livre); (3) o painel mostra a faixa "Saques em verificação"?; (4) o saque tem player.ip?
Ação (1) e (2): espere o horário abrir ou o caixa crescer; o Dracma reconfere e envia sozinho. (3): aguarde. (4): sem IP o saque não sai; cancele e peça de novo com o IP do jogador. Em qualquer caso, você pode cancelar com POST /v1/withdrawals/{id}/cancel enquanto o envio não saiu
Verificação O saque passa a processing, ou a cancelled. Se cancelled, devolva a reserva
Escalar Se nenhuma das quatro causas explica: chamado com id e trace_id. Um envio recusado antes de sair deixa o saque approved e não é reenviado sozinho

Sem caixa livre

Passo O que fazer
Sintoma 422 insufficient_operation_balance na criação do saque
Diagnóstico GET /v1/balances: calcule available - pending_out
Ação Devolva a reserva do jogador (o 422 não cria saque). Para tentar de novo, use external_id e Idempotency-Key novos, depois que houver caixa livre
Verificação Caixa livre maior ou igual ao valor do saque
Escalar Se o caixa livre parece certo e o 422 continua: chamado com a leitura de GET /v1/balances e o trace_id

Relatório que não bate

Passo O que fazer
Sintoma O digest que você calculou é diferente do digest da última página, ou a assinatura não confere, ou um total não bate com a soma dos itens
Diagnóstico (1) Você juntou todas as páginas? (2) Ordenou por (object_id, kind)? (3) Usou settled_at e amount exatamente como vieram? (4) O total que não bate é de devoluções? Elas não têm total (Reconciliar com o seu livro)
Ação Corrija o seu cálculo se a causa for (1) a (4). Se o digest ou a assinatura continuarem errados, trate como incidente: congele a conferência do dia e não ajuste o livro
Verificação O digest recalculado é igual ao da última página, e a assinatura confere
Escalar Digest ou assinatura errados com o cálculo correto: chamado com a data, a moeda, o digest recebido e o Dracma-Signature

Item return inesperado

Passo O que fazer
Sintoma O relatório tem um item return sem caso aberto do seu lado
Diagnóstico Veja o objeto pelo object_id. Se for dep_: o depósito foi devolvido em revisão. Se for wdr_: o banco devolveu o PIX; veja return.returned_amount
Ação Depósito: nada no livro (nunca foi creditado); registre. Saque: abra caso em needs_decision (Política de exceções); o caixa da operação já recebeu o valor devolvido
Verificação O caso está aberto e o item return conferido
Escalar Devolução em valor diferente do esperado: chamado com o id do saque

Caixa livre negativo

Passo O que fazer
Sintoma available - pending_out abaixo de zero
Diagnóstico Houve estorno ou chargeback de depósito (hoje só no sandbox)? Confira os itens refund e chargeback do dia
Ação Novos saques recebem 422 até o caixa se recuperar. Segure os saques no seu lado e avise o financeiro. Depósitos pagos novos recompõem o caixa
Verificação available - pending_out volta a ser positivo
Escalar Caixa negativo em produção: chamado imediato com a leitura de GET /v1/balances

Depósito em revisão

Passo O que fazer
Sintoma status: "under_review" por horas
Diagnóstico Leia review_reasons. Com Mercado Pago, PAYER_UNKNOWN é esperado e demora mais
Ação Quem decide é o revisor no painel (Painel: revisão). Não credite o jogador. Diga ao jogador apenas "pagamento em análise"
Verificação O depósito vai a paid (credite uma vez) ou returned (nada a creditar)
Escalar Se a revisão não andar no prazo da sua operação: chamado com o id do depósito

Pagamento tardio

Passo O que fazer
Sintoma Depósito expired, cancelled ou failed com paid_amount e paid_at preenchidos
Diagnóstico O jogador pagou depois de o depósito terminar. O Dracma gravou o pagamento sem mudar o estado
Ação Não credite. Abra caso em needs_decision (Política de exceções) e chame o suporte para decidir o destino do valor
Verificação O caso tem desfecho registrado
Escalar Sempre: informe o suporte, com o id do depósito, para decidir o destino do valor recebido

Saques em verificação

Passo O que fazer
Sintoma A faixa "Saques em verificação" no painel; saques novos ficam em approved
Diagnóstico A faixa é neutra de propósito e não traz motivo. Os depósitos seguem normalmente
Ação Aguarde. Mantenha as reservas. Avise o suporte do jogador de que os saques podem demorar mais que o normal
Verificação A faixa some e os saques passam a processing
Escalar Se a faixa durar mais do que o seu prazo interno: chamado pelo canal combinado no onboarding. O Dracma não publica prazo

Saldo indisponível

Passo O que fazer
Sintoma GET /v1/balances responde 503
Diagnóstico O livro do Dracma está fora do ar. Novos saques entram em under_review com BALANCE_UNAVAILABLE
Ação Repita depois do Retry-After. Não decida saque com o último valor lido
Verificação 200 com as_of recente
Escalar 503 por mais tempo que a sua tolerância: chamado

Exemplos

O que enviar ao suporte, em qualquer entrada:

Operação: <slug da operação>
Objeto: wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c (external_id wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c)
Estado lido: processing (version 3, updated_at 2026-10-18T15:00:03Z)
trace_id: 4bf92f3577b34da6a3ce929d0e0e4736
O que você já fez: consultou GET /v1/events?object_id=..., manteve a reserva

Erros e casos de borda

  • Pressa não autoriza mexer em dinheiro. Nenhuma entrada deste runbook pede reenviar, trocar de PSP ou recreditar sem desfecho conclusivo.
  • Erro de rede não é resposta. Timeout, 5xx e 429 pedem a mesma Idempotency-Key ou uma consulta por external_id, nunca um pedido novo.
  • Vários sintomas ao mesmo tempo. Resolva primeiro o caixa livre (afeta todos os saques) e depois os objetos.

Veja também