Saques
Referência
Um saque transfere saldo de uma conta ValidaPay para uma chave Pix externa de mesma titularidade. Este guia explica o fluxo real por trás do endpoint, a taxa e os limites aplicados, e como confirmar que o dinheiro efetivamente saiu.
"Saque subconta" e "Saque master account" são o mesmo endpoint
As duas páginas da collection documentam a mesma rota: POST /v1/wallet/withdraw. A diferença é só o campo accountId no body: presente, o saque sai da subconta indicada; ausente, sai da própria conta do token.
O que é um saque
Um saque debita o saldo disponível de uma conta ValidaPay (master ou subconta) e envia o valor via Pix para uma chave externa. Só é possível sacar para contas de mesma titularidade: o CPF/CNPJ dono da chave Pix precisa ser o mesmo documento cadastrado na conta de origem.
O body aceita três campos obrigatórios e um opcional:
| Campo | Descrição |
|---|---|
amount | Valor do saque, em reais (ex.: 50.00). Precisa ser maior que zero. |
pixKey | Chave Pix de destino. |
pixKeyType | Tipo da chave: CPF, CNPJ, EMAIL, PHONE ou EVP (chave aleatória). |
accountId | Opcional. Número da subconta de destino do débito. Omitido, o débito é feito na própria conta do token. |
Saque subconta vs. saque master account
| Saque subconta | Saque master account | |
|---|---|---|
| Endpoint | POST /v1/wallet/withdraw | POST /v1/wallet/withdraw |
| Campo accountId no body | Obrigatório: número da subconta de destino do saldo | Omitido: usa a própria conta do token de autenticação |
| Origem do saldo | Saldo disponível da subconta informada | Saldo disponível da master account |
| Verificação de titularidade da subconta | A subconta precisa pertencer à master do token (senão 401 OWNERSHIP_MISMATCH ou 404 SUB_ACCOUNT_NOT_FOUND) | Não se aplica |
Fluxo do saque
O saque não é 100% síncrono. A API tenta confirmar em segundos, mas pode responder antes da confirmação definitiva chegar:
ETAPA 01
Requisição
amount, pixKey, pixKeyType e, se for saque de subconta, accountId
ETAPA 02
Validações síncronas
duplicidade (5 min), limite diário e saldo suficiente
ETAPA 03
Envio do PIX
ValidaPay dispara a saída via Celcoin para a chave informada
ETAPA 04
Espera curta
aguarda até ~15s pela confirmação antes de responder
ETAPA 05
Resposta
CONFIRMED se confirmou a tempo; senão PROCESSING
ETAPA 06
Confirmação final
chega por integração interna com a Celcoin, então consulte o extrato depois
PROCESSING não é falha. Significa apenas que a confirmação não chegou dentro da janela curta de espera da API. O saque continua em andamento. Confirme o resultado consultando o extrato.
Exemplo de resposta com confirmação pendente (mais comum em produção):
{
"withdrawalId": "wdr_1772883158760_tdhomd8xe",
"status": "PROCESSING",
"amount": 50.00,
"feeAmount": 0.47,
"accountNumber": "258965356"
}Taxas e limites
| Item | Padrão | Observação |
|---|---|---|
| Taxa fixa por saque PIX | R$0.47 | Configurável por conta. Cobrada separadamente do valor sacado: o destinatário recebe o valor cheio de amount, e a taxa é debitada do seu saldo quando o saque é confirmado. |
| Limite diário de saque | R$3.000,00 | Configurável por conta. Considera apenas saques com status CONFIRMED no dia civil (horário de Brasília, UTC-3). Quem excede recebe DAILY_LIMIT_EXCEEDED. |
| Janela antiduplicidade | 5 minutos | Um novo saque de mesmo valor na mesma conta dentro dessa janela é bloqueado, independente do status (PROCESSING, CONFIRMED ou ERROR) do saque anterior. |
Taxa e limite diário são configuráveis por conta. Os valores acima são o padrão aplicado quando a conta não tem uma configuração própria.
Validações e erros
Todos os erros seguem o envelope padrão { error: { message, code, details, timestamp } }. Note que o código OWNERSHIP_MISMATCH aparece em duas situações diferentes, com status HTTP diferentes.
| Código | HTTP | Quando ocorre |
|---|---|---|
INVALID_AMOUNT | 400 | amount ausente ou menor/igual a zero |
MISSING_PIX_KEY | 400 | pixKey não informado |
SUB_ACCOUNT_NOT_FOUND | 404 | accountId informado não corresponde a nenhuma subconta existente |
OWNERSHIP_MISMATCH | 401 | a subconta em accountId não pertence à master account do token |
OWNERSHIP_MISMATCH | 400 | a chave Pix de destino não pertence ao titular da conta de origem (checado em produção) |
DUPLICATE_OUTBOUND_TRANSACTION | 400 | já existe saque de mesmo valor na mesma conta nos últimos 5 minutos |
DAILY_LIMIT_EXCEEDED | 400 | o valor solicitado somado aos saques CONFIRMED do dia ultrapassa o limite diário |
INSUFFICIENT_BALANCE | 400 | saldo disponível menor que o valor do saque |
Exemplo de recusa por titularidade, quando a chave Pix não pertence ao titular da conta de origem:
{
"error": {
"message": "A chave PIX nao pertence ao titular da conta",
"code": "OWNERSHIP_MISMATCH",
"details": null,
"timestamp": "2026-03-17T04:01:57.811Z"
}
}Como confirmar um saque
Diferente de pagamentos e assinaturas, não existe evento de webhook para o resultado do saque, nem uma rota pública de consulta por withdrawalId. A forma confiável de confirmar um saque que retornou PROCESSING é consultar o extrato da conta filtrando por category=WITHDRAWAL. O lançamento aparece como DEBIT assim que a confirmação chega.
Testando no sandbox
No sandbox, o saque é confirmado (CONFIRMED) imediatamente na própria resposta, sem taxa cobrada e sem checagem de titularidade da chave Pix. O único efeito real é o débito do saldo sandbox da conta de origem.