Acompanhe e cancele saques
Estados do saque, consulta por identificador, listagem com filtros e cancelamento de um saque ainda em análise.
Saques não têm webhook. Para saber o desfecho, consulte o saque ou liste os saques em andamento em intervalos regulares, por exemplo a cada minuto.
Estados
status | Final? | Significado | O valor reservado |
|---|---|---|---|
processando | Não | Em análise, aprovado ou em envio. | Continua reservado. |
transferido | Sim | O Pix foi enviado. pixEndToEndId identifica a transferência. | Saiu da conta. |
rejeitado | Sim | A análise recusou o saque. O motivo está em rejectionReason. | Volta ao saldo. |
cancelado | Sim | Você cancelou o saque. | Volta ao saldo. |
expirado | Sim | O saque não pôde ser executado, por exemplo depois de repetidas falhas na transferência. | Volta ao saldo. |
falha | Sim | A transferência foi recusada de forma definitiva. Veja failureCode e failureMessage. | Volta ao saldo. |
devolvido | Sim | Reservado para Pix devolvido pelo banco de destino. Hoje não é emitido. | Volta ao saldo. |
Depois de rejeitado, cancelado ou expirado, a devolução do valor ao saldo leva alguns segundos para aparecer.
Os estados são escritos em português e em minúsculas, exatamente como na tabela. Trate um estado desconhecido como não final.
Consulte um saque
/api/v1/withdrawals/{id}curl "$DM_API_BASE/api/v1/withdrawals/01932f5e-7c3a-7b21-9f4e-2d8c6a1b0e47" \
-H "Authorization: $DM_API_KEY"{
"id": "01932f5e-7c3a-7b21-9f4e-2d8c6a1b0e47",
"status": "transferido",
"amount": 25000,
"currencyCode": "BRL",
"pixKeyType": "CNPJ",
"pixKey": "************81",
"createdAt": "2026-11-02T14:58:03.412718Z",
"pixEndToEndId": "E00000000202611021508Ab12Cd34Ef5",
"transferredAt": "2026-11-02T15:08:41.090233Z",
"rejectedAt": null,
"rejectionReason": null,
"rejectionSource": null,
"failedAt": null,
"failureCode": null,
"failureMessage": null
}| Campo | Preenchido em | Descrição |
|---|---|---|
amount | sempre | Valor em centavos. |
pixKeyType | sempre | CPF, CNPJ, EMAIL, PHONE ou EVP. Repare que difere da grafia do pedido. |
pixKey | sempre | Chave mascarada: documentos e telefone mostram só os dois últimos caracteres, e-mail aparece como f***@***e.com e chave aleatória como ***. |
pixEndToEndId, transferredAt | transferido | Identificador do Pix no Banco Central e momento do envio. |
rejectedAt | rejeitado, expirado | Momento da rejeição ou da expiração. |
rejectionReason | rejeitado | Motivo informado pela análise. |
rejectionSource | rejeitado | Quem rejeitou: operator. |
failedAt, failureCode, failureMessage | falha | Momento e detalhes da falha. failureCode e failureMessage são informativos: não monte lógica sobre os valores. |
Campos que não se aplicam ao estado vêm como null. Um saque de outra conta responde 404, igual a um inexistente.
Liste saques
/api/v1/withdrawalscurl "$DM_API_BASE/api/v1/withdrawals?status=processando&page=1&pageSize=50" \
-H "Authorization: $DM_API_KEY"| Parâmetro | Padrão | Descrição |
|---|---|---|
status | todos | Um estado da tabela acima. |
dateFrom | — | Criados a partir desta data (2026-11-01 ou data e hora). Sem fuso, vale UTC. |
dateTo | — | Criados até esta data. Uma data sem hora vai até 23:59:59 UTC do dia. Envie dateTo maior ou igual a dateFrom. |
page | 1 | Página, a partir de 1. |
pageSize | 20 | Itens por página, de 1 a 100. |
{
"items": [
{
"id": "01932f5e-7c3a-7b21-9f4e-2d8c6a1b0e47",
"status": "processando",
"amount": 25000,
"currencyCode": "BRL",
"pixKeyType": "CNPJ",
"pixKey": "************81",
"createdAt": "2026-11-02T14:58:03.412718Z",
"pixEndToEndId": null,
"transferredAt": null,
"rejectedAt": null,
"rejectionReason": null,
"rejectionSource": null,
"failedAt": null,
"failureCode": null,
"failureMessage": null
}
],
"totalCount": 1,
"page": 1,
"pageSize": 50,
"totalPages": 1
}Os saques vêm do mais recente para o mais antigo. A paginação é por número de página: se novos saques forem criados enquanto você percorre a lista, itens podem se deslocar entre páginas. Para conciliação, filtre por período fechado.
Para acompanhar saques em andamento, uma chamada de listagem com status=processando substitui várias consultas individuais e economiza o limite de requisições.
Cancele um saque
/api/v1/withdrawals/{id}/cancelUm saque pode ser cancelado enquanto ainda está em análise. A requisição não tem corpo.
curl -X POST "$DM_API_BASE/api/v1/withdrawals/01932f5e-7c3a-7b21-9f4e-2d8c6a1b0e47/cancel" \
-H "Authorization: $DM_API_KEY"{
"withdrawalId": "01932f5e-7c3a-7b21-9f4e-2d8c6a1b0e47",
"status": "cancelado",
"reversalTransactionId": null
}- O cancelamento é idempotente: cancelar de novo um saque cancelado responde
200igual. - A devolução do valor ao saldo é assíncrona e leva alguns segundos.
reversalTransactionIdvemnull. - O estado
processandonão diz se o saque ainda está em análise ou já foi aprovado. Se ele já foi aprovado, o cancelamento é recusado com409 withdrawal.cannot_cancel: trate essa resposta como "não é mais possível cancelar" e continue acompanhando o saque até o desfecho.