Solicite um saque
Peça uma transferência Pix do saldo da sua conta para a chave de destino cadastrada, com idempotência e as regras de valor e titularidade.
/api/v1/withdrawalsCria um pedido de saqueO pedido de saque reserva o valor no seu saldo e entra em análise. A resposta 201 confirma que o pedido foi aceito, não que o Pix foi enviado. O envio é acompanhado pela consulta do saque.
Requisição
curl -X POST "$DM_API_BASE/api/v1/withdrawals" \
-H "Authorization: $DM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: saque-2026-11-02-000123" \
-d '{
"accountId": "3f6b2c1e-8d4a-4b7f-9e21-5a0c7d9e1b42",
"amount": 25000,
"currencyCode": "BRL",
"pixKeyType": "CNPJ",
"pixKey": "11222333000181"
}'Cabeçalhos
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
Authorization | Sim | A chave de API, com permissão de saque. |
Idempotency-Key | Sim | De 10 a 200 caracteres, única por pedido de saque. Também pode ir no corpo, como idempotencyKey; se vierem os dois, vale o cabeçalho. |
Content-Type | Sim | application/json. |
Corpo
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
accountId | string (UUID) | Sim | A conta de onde sai o saque, entregue no credenciamento. |
amount | inteiro | Sim | Valor em centavos. 25000 é R$ 250,00. Mínimo 100 (R$ 1,00). |
currencyCode | string | Sim | Sempre "BRL", em maiúsculas. |
pixKeyType | string | Sim | Tipo da chave de destino: CPF, CNPJ, Email, Phone ou Random. |
pixKey | string | Sim | A chave Pix de destino, no formato do tipo (tabela abaixo). |
beneficiaryName | string | Não | Nome do titular da chave. Se omitido, vem do cadastro. |
beneficiaryDocument | string | Não | CPF ou CNPJ do titular. Se enviado, precisa ser o do titular cadastrado. |
Tipos de chave Pix
pixKeyType | Formato de pixKey | Exemplo |
|---|---|---|
CPF | CPF válido. Pontuação é ignorada. | 52998224725 |
CNPJ | CNPJ válido, inclusive alfanumérico. Pontuação é ignorada. | 11222333000181 |
Email | Endereço de e-mail. | financeiro@loja.example.com |
Phone | Telefone brasileiro. | +5511999999999 |
Random | Chave aleatória, no formato UUID. | 7d2f9a10-4c3b-4e8a-b1d5-0f6e2a9c8b31 |
Chave aleatória: envie Random, receba EVP
No pedido, a chave aleatória é Random. Enviar EVP retorna 400. Na consulta, o mesmo tipo volta como EVP, e e-mail e telefone voltam como EMAIL e PHONE. Se o seu sistema reaproveita o tipo lido na consulta para criar um novo saque, converta EVP para Random.
Destino do saque
Por padrão, o saque só pode ir para a chave Pix cadastrada como destino de saque da sua conta. Não basta ser uma chave do mesmo CNPJ: tipo e valor precisam ser exatamente os do cadastro. Uma chave diferente é recusada com 422 withdrawal.destination_not_owned.
Saque para chaves de terceiros depende de habilitação comercial. Fale com a equipe de integração se o seu caso precisar disso.
Resposta
{
"withdrawalId": "01932f5e-7c3a-7b21-9f4e-2d8c6a1b0e47",
"status": "processando"
}O cabeçalho Location aponta para /api/v1/withdrawals/{withdrawalId}. Grave o withdrawalId junto com a chave de idempotência no seu sistema.
Idempotência
A Idempotency-Key protege contra saques duplicados quando a rede falha. Gere uma chave por pedido de saque, grave-a antes de chamar a API e reutilize-a em todas as repetições daquele pedido.
| Situação com a mesma chave | Resposta |
|---|---|
| Mesmo valor, mesma chave Pix, mesma conta | 200 OK com o saque original. O status é o atual, por exemplo transferido. |
| Valor, chave Pix ou conta diferentes | 409 withdrawal.idempotency_conflict. |
| O pedido anterior foi recusado por saldo insuficiente | A chave é liberada: a próxima chamada com ela cria um saque novo. |
A comparação considera só valor, chave Pix e conta. Mudar pixKeyType ou os dados do beneficiário com a mesma chave devolve o saque original sem erro. Trate a chave como a identidade de um pedido; não a reutilize para outro.
Regras de valor
- Unidade: centavos, inteiro.
25000é R$ 250,00. Um valor com casas decimais (250.00) é recusado com400. - Mínimo:
100(R$ 1,00). - Saldo: o valor precisa estar disponível para saque no momento do pedido. Ele fica reservado até o desfecho do saque.
- Limites: a sua conta pode ter limite por saque e limites diários de quantidade e de valor. Os limites diários contam o dia em UTC (a virada acontece às 21h de Brasília).
- Tarifa e horário: a API não cobra tarifa por saque nem bloqueia pedidos por horário. O prazo do Pix depende da análise.
Limite de requisições
As rotas de saque aceitam até 60 requisições por minuto por conta, somando criação, consulta, listagem e cancelamento. Acima disso, a resposta é 429 sem corpo e sem Retry-After: espere alguns segundos e repita com espera crescente. Para acompanhar vários saques, prefira listar por status a consultar um por um.
Lista de IPs permitidos
Se a sua conta usa lista de IPs nas rotas de saque, chamadas de um IP fora da lista recebem 403 ip_not_allowed. Mudanças na lista levam até um minuto para valer.
Próximo passo
Acompanhe o saque até um estado final.