Saques¶

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

Um saque é um pedido de pagamento PIX ao jogador. O motor de regras do Dracma decide na hora se ele sai no automático ou vai para revisão humana, e o resultado final chega por webhook. Esta página descreve as quatro rotas (criar, consultar, listar e cancelar), o destino PIX, as recusas na ordem em que a API as confere e os campos do objeto Saque, inclusive o objeto return de um saque devolvido pelo banco.

O que é¶

O quinto POST, POST /v1/withdrawals/{id}/recall, é uma rota reservada e está em Rotas e campos reservados.

Hoje só existe PIX em BRL.

O PSP que paga o saque é escolhido pelo Dracma para a sua operação. Isso não muda nada na API. Veja PSPs.

Quando usar¶

Regra nº 1: reserve antes de pedir. Debite (reserve) o saldo do jogador antes de chamar POST /v1/withdrawals, na mesma transação em que você grava o saque no seu lado (external_id, valor e destino). Assim:

• o jogador não consegue apostar nem sacar de novo o mesmo dinheiro enquanto o saque está em voo;
• se a chamada falhar por rede ou 5xx, o dinheiro continua reservado e você repete com a mesma Idempotency-Key, sem risco de pagar duas vezes;
• a reserva só volta ao jogador quando o Dracma disser, de forma conclusiva, que o saque não sai: um 4xx síncrono, ou o estado rejected, failed ou cancelled lido pela API.

Nunca devolva a reserva sem resposta conclusiva. Timeout, erro de rede, 5xx e 429 não são conclusivos: repita com a mesma chave ou consulte GET /v1/withdrawals?external_id=<seu id>.

1. Transação local: grave o saque e reserve o saldo.
2. POST /v1/withdrawals com Idempotency-Key igual ao external_id, player.ip do jogador e timeout de 10 s.
3. 201: guarde id, status e decision. 4xx: devolva a reserva. Rede, 5xx ou 429: repita com a mesma chave.
4. Webhook withdrawal.*: verifique, deduplique, faça o fetch-back em GET /v1/withdrawals/{id} e aplique a tabela de estados.
5. Um job com GET /v1/events?after= a cada 5 minutos e a reconciliação diária fecham as lacunas.

A tabela de efeito de cada estado na reserva está em Ciclo do saque.

Como funciona¶

Criar: POST /v1/withdrawals¶

O corpo é um objeto JSON. A validação é estrita (a mesma do depósito): campo desconhecido, chave repetida, UTF-8 inválido, tipo errado e conteúdo depois do objeto voltam 400 validation_failed com errors[].reason. Veja Depósitos para a lista.

player.email, player.birth_date e player.kyc_level são aceitos pela forma do Jogador, mas o saque não os usa. purpose, fx_quote_id e payout_currency também são aceitos pela forma e ignorados: o saque PIX não tem câmbio (veja Divergências conhecidas).

Destino PIX¶

destination.pix tem key_type e key. O key_type é um dos cinco abaixo; o Dracma normaliza a chave antes de comparar e de guardar.

• key tem de 1 a 140 caracteres. Fora disso: 400 com reason: format. key_type fora da tabela: 400 com reason: enum.
• Se você tem um cadastro com nomes antigos de tipo (evp, aleatoria, telefone), converta para random e phone antes de enviar.
• destination com mais de uma chave: reason: one_of. Chave diferente de method: reason: method_mismatch.
• A titularidade é conferida na decisão: chave cpf precisa ser o CPF do jogador; cnpj para pessoa física é bloqueio; email, phone e random são conferidas na consulta ao diretório do PIX. Com a consulta indisponível, a resposta é 201 com status: "requested"; o Dracma reconsulta por alguns minutos e depois decide (approved, rejected se o titular diverge, ou under_review).

Resposta 201 e a decisão¶

O código responde sempre 201 na criação, nunca 202: a criação não espera o PSP. O status da resposta é um destes:

• O saque nasce com version 1 já no estado decidido. Não há evento público withdrawal.requested.
• approved fora do horário do automático espera a abertura da janela. Antes do envio o Dracma reconfere listas e caixa: se uma lista pegar, o saque vai a cancelled com BLOCKLIST_HIT_AT_DISPATCH; se faltar caixa, fica em approved e o Dracma alerta.
• O resultado final (paid, failed, rejected...) chega por webhook withdrawal.*. Aja só depois do fetch-back.
• Motor de regras fora na criação não é 503: o saque é criado em under_review com RULES_UNAVAILABLE (na dúvida, revisão humana). Resposta incoerente do motor resulta em RULES_INVALID_RESPONSE.
• O significado de cada código de decision.reasons está em Decisão, limites e regras. Os limiares são da regra da operação: leia com Regras (API).

Recusas síncronas 422 (sem objeto)¶

Bloqueio duro responde 422 sem criar o saque. É uma decisão: devolva a reserva e não repita. A mesma Idempotency-Key repete o mesmo 422; uma nova tentativa exige external_id novo (e nova reserva). Bloqueio com código fora desta lista vira revisão, não 422.

Consultar: GET /v1/withdrawals/{id}¶

Escopo read. É o estado autoritativo do fetch-back. 200 devolve o Saque; 404 not_found quando o id não existe nesta operação (inclusive objeto de outra operação) ou está fora do formato wdr_ seguido de letras e números.

Listar: GET /v1/withdrawals¶

Escopo read, com o balde de listagem do rate limit (veja Limites e quotas).

Resposta: {"data": [Saque, ...], "next_cursor": "..." | null}. A ordem é por created_at e depois id, crescente. O next_cursor é opaco (hoje um texto em base64url): não monte nem interprete. Veja Paginação e filtros.

Cancelar: POST /v1/withdrawals/{id}/cancel¶

Escopo withdrawals:write. Corpo vazio. Idempotency-Key obrigatória.

• Permitido em requested, under_review e em approved enquanto o comando de envio ao PSP ainda não saiu. A resposta é 200 com o objeto em cancelled, ou o mesmo 200 se ele já estava cancelled. Devolva a reserva quando ler cancelled.
• approved com o envio já publicado, processing ou qualquer estado depois: 409 invalid_state_transition. O dinheiro pode já estar saindo; espere o desfecho (paid ou failed). Isso é mais restritivo que o contrato (D-W2 em Divergências conhecidas).
• id inexistente nesta operação: 404 not_found.

Objeto Saque¶

O Saque é o mesmo no 201, no GET e no data.object do webhook. Os campos da v1.1.0 vêm sempre null ou vazios em PIX, com uma exceção: return.

Faça o parse de datas aceitando ou não fração de segundo (leitor tolerante).

status e transições¶

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

O objeto return¶

Quando o banco devolve um saque já pago, o saque vai de paid para returned e o campo return passa a vir preenchido:

• Devolução parcial continua returned: não existe um estado "parcialmente devolvido". Confira returned_amount contra amount.
• O Dracma credita de volta ao caixa da operação só o valor devolvido e registra um item return na reconciliação (veja Reconciliação).
• reason e return_fee do schema DevolucaoBancaria não são devolvidos em saque PIX.
• Fora de returned, return é null.

O que fazer com o jogador quando vem returned é política sua. A recomendação é não mover dinheiro automaticamente: marque como exceção, alerte e decida com um humano (veja Política de exceções de dinheiro).

Exemplos¶

Pedido de criação (os valores de assinatura são ilustrativos):

POST /v1/withdrawals HTTP/1.1
Host: api.example.test
Content-Type: application/json; charset=utf-8
Idempotency-Key: wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c
Dracma-Key-Id: key_test_01J9EXEMPLO
Dracma-Timestamp: 1790000000
Dracma-Nonce: 0123456789abcdef0123456789abcdef
Dracma-Signature: v1=<assinatura>

{
  "external_id": "wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c",
  "player": {
    "external_ref": "0192a3b4-0000-7000-8000-000000000001",
    "document": { "type": "CPF", "number": "12345678909", "country": "BR" },
    "name": "Jogador Teste",
    "ip": "203.0.113.10",
    "device_id": "dev_7f3a"
  },
  "amount": { "amount": "5000", "currency": "BRL" },
  "method": "pix",
  "destination": {
    "pix": { "key_type": "cpf", "key": "12345678909" }
  },
  "review_requested": false
}

Resposta 201, decisão automática:

{
  "id": "wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c",
  "external_id": "wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c",
  "status": "approved",
  "version": 1,
  "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:01.250Z"
  },
  "psp_reference": null,
  "failure_code": null,
  "created_at": "2026-10-18T15:00:00.812Z",
  "updated_at": "2026-10-18T15:00:01.250Z",
  "paid_at": null,
  "rail": null,
  "fees": [],
  "charge_bearer": null,
  "fx": null,
  "purpose": null,
  "compliance": null,
  "expected_settlement_date": null,
  "sent_at": null,
  "tracking": null,
  "return": null,
  "recall": null
}

Resposta 201, revisão manual (primeiro saque e chave nova):

{
  "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-000000000002",
  "decision": {
    "mode": "manual",
    "reasons": ["FIRST_WITHDRAWAL", "PIX_KEY_CHANGED"],
    "ruleset_version": 7,
    "decided_by": [],
    "decided_at": null
  },
  "psp_reference": null,
  "failure_code": null,
  "created_at": "2026-10-18T15:02:00.100Z",
  "updated_at": "2026-10-18T15:02:00.100Z",
  "paid_at": null,
  "rail": null,
  "fees": [],
  "charge_bearer": null,
  "fx": null,
  "purpose": null,
  "compliance": null,
  "expected_settlement_date": null,
  "sent_at": null,
  "tracking": null,
  "return": null,
  "recall": null
}

Um saque devolvido pelo banco, com devolução parcial (R$ 30,00 de R$ 50,00):

{
  "id": "wdr_0192a3b40c6d7e8f9a0b1c2d3e4f5a6c",
  "external_id": "wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c",
  "status": "returned",
  "version": 5,
  "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:01.250Z"
  },
  "psp_reference": "E00000000202610181500abcdef0123456",
  "failure_code": null,
  "created_at": "2026-10-18T15:00:00.812Z",
  "updated_at": "2026-10-19T09:30:12.004Z",
  "paid_at": "2026-10-18T15:00:09.500Z",
  "rail": null,
  "fees": [],
  "charge_bearer": null,
  "fx": null,
  "purpose": null,
  "compliance": null,
  "expected_settlement_date": null,
  "sent_at": null,
  "tracking": null,
  "return": {
    "reason_code": "unspecified",
    "returned_amount": { "amount": "3000", "currency": "BRL" },
    "returned_at": "2026-10-19T09:30:11Z"
  },
  "recall": null
}

Recusa 422, caixa insuficiente (nenhum saque foi criado):

{
  "type": "https://docs.dracma.test/errors/insufficient_operation_balance",
  "title": "insufficient_operation_balance",
  "status": 422,
  "code": "insufficient_operation_balance",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "retryable": false
}

Para descobrir o destino de um POST cuja resposta se perdeu:

GET /v1/withdrawals?external_id=wdr_0192a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6c HTTP/1.1

Erros e casos de borda¶

Erros da criação, na ordem em que a API os confere¶

• Rede, timeout, 5xx e 429: repita com a mesma Idempotency-Key até uma resposta conclusiva e não devolva a reserva. Na dúvida, consulte GET /v1/withdrawals?external_id=.
• 409 idempotency_key_reused: mesma chave com corpo diferente. É um bug do seu lado: mantenha a reserva e investigue.
• Regras de repetição e retenção da chave: Idempotência e repetição.

Outras rotas¶

Casos de borda¶

• approved pode durar. Se o envio é recusado antes de sair (caixa insuficiente ou guarda de ambiente), o saque fica em approved e o Dracma alerta. Mantenha a reserva.
• requested não é revisão. Espere: o Dracma decide sozinho depois de alguns minutos.
• Sem player.ip o saque vai sempre para revisão. Mande o IP do jogador em todo pedido.
• Estado, motivo ou campo desconhecido nunca devem derrubar o seu parser: trate como não-terminal, mantenha a reserva e confira de novo pelo fetch-back.
• Datas de saque podem ter fração de segundo; as de depósito não.

Veja também¶

• Ciclo do saque: reserva, processing, approved parado e returned.
• Decisão, limites e regras: decision.reasons.
• Limites do jogador e saldos: quanto cabe no automático e o caixa da operação.
• Rotas e campos reservados: recall e campos da v1.1.0.
• Erros, Idempotência e repetição e Webhooks
• Sandbox