Decisão, limites e regras¶

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

Toda criação de depósito e de saque passa pelo motor de regras da sua operação. O resultado é um de três: automático (segue), revisão (uma pessoa decide) ou bloqueio (recusa na hora, com 422). Esta página explica a ordem da decisão, o catálogo de motivos (decision.reasons) e cada família de limite. Os valores dos limites são da sua operação: leia-os em GET /v1/rules.

O que é¶

Um quarto resultado existe só no saque: aguardar. O saque é aprovado, mas está fora do horário do automático (outside_policy igual a defer). Ele fica approved e espera a abertura (veja Dia, fuso e horários).

Quando usar¶

Use esta página para:

• traduzir decision.reasons em mensagem de suporte (nunca ao jogador);
• decidir o que pedir ao Dracma quando os limites da operação ficarem apertados ou frouxos;
• montar a pré-checagem do seu conector, que só pode endurecer a decisão.

Nunca revele ao jogador o motivo de uma revisão ou bloqueio: o suporte vê, o jogador não. Mostre uma mensagem genérica.

Como funciona¶

Ordem da decisão¶

• As regras de bloqueio rodam em ordem fixa e param na primeira: o 422 traz um único code.
• As regras de revisão rodam todas: decision.reasons traz todos os motivos que se aplicam, sem repetir, na ordem do catálogo.
• Se um valor igual ou acima do limite de dupla aprovação (ou um motivo que exija duas pessoas) aparecer, entra DUAL_APPROVAL_REQUIRED e a revisão precisa de dois revisores. Caso contrário, basta um.
• O depósito segue um caminho mais curto: valor mínimo e máximo, documento, lista de bloqueio, janela de depósitos e depósitos não pagos. As revisões do depósito acontecem quando o pagamento chega (veja Ciclo do depósito).

Recusas síncronas (422)¶

Nunca revele ao jogador que ele está em uma lista. A mesma Idempotency-Key repete o mesmo 422; para tentar de novo, use external_id e chave novos (veja Idempotência).

Catálogo de decision.reasons¶

Os códigos são estáveis e só crescem. Um código desconhecido deve ser tratado como "revisão", sem efeito de dinheiro. Tipo R é revisão (under_review); B é bloqueio (rejected ou 422).

Para o depósito, os motivos de revisão são PAYER_MISMATCH, PAYER_UNKNOWN, PAYER_BLOCKED, AMOUNT_MISMATCH, PAID_AFTER_EXPIRY, RULES_UNAVAILABLE e RULES_INVALID_RESPONSE. Veja Ciclo do depósito.

Quais limites existem¶

Cada operação tem um conjunto de regras versionado, lido em GET /v1/rules (com ETag). Os limites abaixo existem por moeda.

Janelas: revisão e duras¶

Cada janela de saque (dia, 7 dias, 30 dias) tem dois níveis:

• O "dia" é o dia civil no fuso da operação. As janelas de 7 e 30 dias são móveis (168 e 720 horas). Veja Dia, fuso e horários.
• No dia, se auto_max_per_day e windows.day.review_amount estiverem ambos definidos, vale o menor; o mesmo vale para a contagem (max_withdrawals_per_day e windows.day.review_count).
• A velocidade (velocity) conta pedidos num intervalo de minutos: VELOCITY_WITHDRAWALS leva à revisão e VELOCITY_HARD_LIMIT, ao 422. Para depósito, DEPOSIT_VELOCITY_UNPAID limita depósitos criados e não pagos num intervalo. Os valores são da operação.
• Para depósitos, DEPOSIT_WINDOW_EXCEEDED aplica o limite duro das janelas deposit_windows. Elas vêm desligadas por padrão.

O X do automático¶

O automático libera um saque só se, depois dele, o total sacado não passa de X vezes o total depositado e liquidado:

(S + W) <= D * X

Exemplo com X = 1: o jogador depositou R$ 100,00. Um saque de R$ 80,00 passa. O seguinte, de R$ 30,00, soma R$ 110,00 e vai a revisão com AUTO_MULTIPLIER_EXCEEDED.

Consequências para quem migra jogadores de outro sistema:

• Só conta depósito liquidado pelo Dracma. Depósitos antigos feitos fora do Dracma não entram em D.
• Um jogador sem depósito paid no Dracma recebe NO_SETTLED_DEPOSIT no primeiro saque: ele vai para revisão, mesmo que tenha saldo no seu sistema.
• Nenhum ajuste de D é feito pela API. Planeje que o primeiro saque de cada jogador migrado passe por revisão, ou combine uma regra com o Dracma no onboarding.

Teto agregado da operação¶

operation_auto_cap limita quanto o automático libera na operação inteira, por hora e por dia (moeda a moeda). Quando um saque faria a soma passar do teto, ele vai a revisão com OPERATION_AUTO_CAP_EXCEEDED. O efeito é coletivo: enquanto o teto estiver estourado, todos os jogadores recebem revisão nos saques seguintes, até a hora ou o dia virar. Os valores estão em GET /v1/rules.

Interruptor de emergência¶

A operação pode suspender o automático inteiro. Com ele suspenso, todo saque vai a under_review com OPERATION_AUTO_SUSPENDED. O interruptor é acionado no painel ("Suspender automático") e é uma mudança que endurece a regra, então vale na hora. Reativar é uma mudança que afrouxa a regra e segue o fluxo de aprovação. Veja Painel: regras e listas.

Pré-checagem do seu conector¶

O seu conector pode endurecer a decisão, nunca afrouxá-la. Dois campos do POST /v1/withdrawals fazem isso:

Exemplo de uso: o seu sistema marca review_requested quando o jogador tem bônus ativo, quando há suspeita de fraude ou quando a conta é muito nova. O Dracma não conhece essas regras do seu negócio.

{
  "id": "wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6d",
  "external_id": "wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6d",
  "status": "under_review",
  "version": 1,
  "amount": { "amount": "5000", "currency": "BRL" },
  "fee": null,
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "decision": {
    "mode": "manual",
    "reasons": ["FIRST_WITHDRAWAL", "PIX_KEY_CHANGED", "NEW_CONTEXT"],
    "ruleset_version": 7,
    "decided_by": [],
    "decided_at": null
  },
  "psp_reference": null,
  "failure_code": null,
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-18T15:00:00Z",
  "paid_at": null
}

Exemplos¶

GET /v1/players/{ref}/limits?currency=BRL mostra a posição de um jogador: total_deposited, total_withdrawn, auto_multiplier, auto_withdrawal_remaining e blocked. auto_withdrawal_remaining é o quanto ainda cabe no X; outras regras (primeiro saque, chave nova, janelas, IP ausente) ainda podem mandar o saque para revisão. A forma da resposta está em Referência: limites do jogador e saldos.

Erros e casos de borda¶

• Motor de regras fora do ar na criação do saque. Não é 503: o saque é criado em under_review com RULES_UNAVAILABLE. Mantenha a reserva. No depósito, o motor fora devolve 503.
• player.ip e player.device_id entram no risco. O IP é por saque (o IP do jogador no momento do pedido, nunca o do seu servidor); o PSP de saque exige o IP do titular, e sem ele o saque vai a under_review com OWNERSHIP_UNVERIFIED. No depósito o IP é opcional. O device_id entra nas listas de device e no NEW_CONTEXT. Mande os dois sempre que souber.
• Limites de taxa por jogador. Além das regras, a API limita pedidos por jogador (depósitos e saques por hora). Veja Limites e quotas.
• Mudar um limite. A API do operador não altera regra diretamente. POST /v1/rules/change-requests (escopo rules:propose) cria um pedido que responde 202 pending_approval e só vale depois de aprovado no painel. Mudanças que apertam a regra valem na hora; as que afrouxam esperam aprovação e um tempo de espera. Veja Referência: regras e Painel: regras e listas.

Veja também¶

• Ciclo do saque
• Ciclo do depósito
• Dia, fuso e horários
• Saldos e caixa livre
• Referência: regras
• Painel: revisão de depósitos e saques
• Política de exceções de dinheiro