Ciclo do saque¶

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

Um saque é um pedido de pagamento PIX ao jogador. O Dracma decide se ele sai no automático ou vai para revisão, reserva o caixa no envio e só confirma paid quando o PIX é liquidado. Esta página mostra os estados, o que pode demorar, o que pode ficar parado e o que o seu livro deve fazer em cada caso.

O que é¶

• O saque nasce já decidido (approved ou under_review) ou em requested, quando a consulta da chave PIX ainda está pendente. A criação responde sempre 201 e não espera o PSP.
• version sobe a cada transição. Ignore estado com version menor ou igual ao já aplicado.
• rejected, failed, cancelled e returned são terminais; paid só pode ir a returned.
• Os estados pending_compliance, sent, in_transit, recall_requested e recalled fazem parte do contrato, mas não ocorrem em PIX hoje. Se aparecerem, mantenha a reserva e confira de novo.

Quando usar¶

Consulte esta página para:

• definir o prazo de suporte de um saque em processing;
• explicar ao financeiro por que um saque approved não saiu;
• decidir o que fazer com a reserva do jogador em cada estado.

A regra de ouro está na Referência: saques: reserve o valor no seu livro antes de pedir o saque e só devolva a reserva com resposta conclusiva (4xx síncrono, ou estado rejected, failed ou cancelled lido pela API). Timeout, erro de rede, 5xx e 429 não são respostas conclusivas.

Como funciona¶

Efeito no seu livro¶

Devolver e finalizar são idempotentes pelo external_id: dois eventos do mesmo desfecho movem o dinheiro uma vez.

processing pode durar¶

processing significa que o Dracma enviou o pedido ao PSP e espera o desfecho. Dentro dele cabem situações diferentes: o PSP aceitou e ainda não liquidou, o PSP não respondeu de forma conclusiva, ou o caso passou para tratamento manual do Dracma.

Quando o PSP não dá resposta conclusiva, o Dracma consulta o PSP repetidas vezes, em intervalos crescentes, por até cerca de 1 h 30. Se mesmo assim não houver resposta, o caso passa para tratamento manual pelo time do Dracma, que também é avisado por alerta. Nessa hora o saque continua processing.

Regras que valem sempre:

• Nunca há reenvio. O Dracma não manda o mesmo pedido de novo ao PSP, para não pagar duas vezes.
• Nunca há failover de PSP. Se o PSP de saque não responde, o Dracma não tenta outro.
• failed só sai com resposta definitiva do PSP de que o dinheiro não saiu. Se você vir failed, a reserva pode voltar ao jogador.
• Enquanto estiver processing, mantenha a reserva. Não devolva, não reenvie e não crie outro saque.

Defina um prazo de suporte pelo seu lado. Como o Dracma consulta o PSP por até cerca de 1 h 30 antes de passar o caso para tratamento manual, um saque em processing por mais de 2 horas merece um chamado com o id do saque e o trace_id (veja Suporte).

approved parado¶

approved não quer dizer "saiu". O saque pode ficar aprovado e parado por quatro motivos:

Dois detalhes a mais:

• Um saque sem player.ip nunca é enviado. O PSP de saque exige o IP do titular; sem o IP o saque nasce em under_review com OWNERSHIP_UNVERIFIED, e, se um revisor o aprovar, ele fica approved sem sair.
• Uma lista de bloqueio atualizada antes do envio leva o saque a cancelled com BLOCKLIST_HIT_AT_DISPATCH.

Reserva recusada no envio¶

Se o Dracma não consegue reservar o caixa na hora do envio (por exemplo, o caixa livre baixou depois da aprovação), a tentativa termina sem enviar nada e o saque fica approved com alerta interno. Esse caso não é reenviado sozinho.

Você tem dois caminhos:

1. Cancelar o saque com POST /v1/withdrawals/{id}/cancel. Como o envio não saiu, a resposta é 200 com status: "cancelled". Devolva a reserva do jogador ao ler cancelled.
2. Abrir um chamado com o id do saque para o Dracma investigar e orientar (veja Suporte).

Monitore o caixa livre (veja Saldos e caixa livre) e alerte antes de ele acabar. Assim este caso quase não acontece.

Cancelamento¶

POST /v1/withdrawals/{id}/cancel é permitido em requested, under_review e approved, enquanto o comando de envio ao PSP não saiu. A resposta é 200 com o objeto em cancelled (ou o mesmo 200 se já estava cancelado). Depois que o envio saiu, ou em processing e depois, a resposta é 409 invalid_state_transition: o dinheiro pode estar saindo. Espere o desfecho (paid ou failed). Um saque que espera a verificação da operação já teve o envio pedido e também responde 409.

Consulta da chave PIX¶

Quando a consulta da titularidade da chave PIX está indisponível, o saque é criado em requested. O Dracma reconsulta com intervalos crescentes por até cerca de 5 minutos e então decide: approved, rejected se o titular diverge, ou under_review com DICT_UNAVAILABLE.

failure_code¶

failure_code é uma lista aberta; o status é que manda. Os valores que o Dracma produz:

Em todos os casos o dinheiro não saiu. Os códigos environment_guard e reservation_refused não geram failed: o saque fica approved (veja acima).

Banco devolveu o PIX¶

O Dracma sabe tratar a devolução de um PIX de saque já pago. O mecanismo:

1. O PSP avisa que o banco devolveu o PIX.
2. O aviso só dispara a conferência: o Dracma consulta o PSP e só age se a consulta confirmar a devolução.
3. O saque vai de paid para returned e sai withdrawal.returned.
4. O objeto return passa a vir preenchido. A devolução pode ser parcial: o saque continua returned, e o caixa recebe só o valor devolvido.
5. O caixa da operação sobe o valor devolvido (available), e o relatório diário ganha um item return no dia da devolução.

Campos de return:

O Dracma é idempotente nesse ponto: uma segunda devolução do mesmo saque não credita o caixa de novo. Devolução com valor zero, maior que o pago ou em outra moeda é rejeitada e gera alerta, sem lançar nada.

{
  "id": "wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c",
  "external_id": "wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c",
  "status": "returned",
  "version": 6,
  "amount": { "amount": "5000", "currency": "BRL" },
  "fee": null,
  "method": "pix",
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "decision": {
    "mode": "automatic",
    "reasons": [],
    "ruleset_version": 7,
    "decided_by": [],
    "decided_at": "2026-10-18T15:00:01Z"
  },
  "psp_reference": "E00000000202610181500AbCdEfGhIjKl",
  "failure_code": null,
  "created_at": "2026-10-18T15:00:00Z",
  "updated_at": "2026-10-19T10:00:00Z",
  "paid_at": "2026-10-18T15:00:09Z",
  "return": {
    "reason_code": "unspecified",
    "returned_amount": { "amount": "5000", "currency": "BRL" },
    "returned_at": "2026-10-19T10:00:00Z"
  }
}

Exemplos¶

Linha do tempo de um saque automático pago:

Erros e casos de borda¶

• Operação Real sem PSP de saque. O Mercado Pago só faz depósito. Se a operação Real não tiver um PSP de saque configurado, o Dracma não encontra por onde pagar: o envio é recusado antes de sair, o saque fica approved e o Dracma alerta. Confirme no onboarding que a sua operação tem PSP de saque (veja PSPs).
• Sem failover. Uma operação tem um PSP de saque por vez. Se ele ficar indisponível, os saques esperam; o Dracma não troca de PSP no meio do caminho.
• returned e o seu livro. Veja Política de exceções de dinheiro: a recomendação é abrir um caso, não recreditar sozinho.

Veja também¶

• Referência: saques
• Modelo de dinheiro
• Decisão, limites e regras
• Devoluções, estornos e disputas
• Estados no seu produto
• Runbook de dinheiro