Skip to main content
Withdrawals (saques) são transferências PIX do saldo do seu merchant para uma chave PIX de destino.

​
Como funciona

1

Você solicita o saque

POST /withdrawals com amount, pixKey, pixKeyType e, opcionalmente, clientCallbackUrl para definir o callback específico da transação.
2

Validamos o saldo

Conferimos que available >= amount + fee.
3

Reservamos o valor

Movemos amount + fee de available para pending.
4

Enfileiramos o processamento

O saque entra com status PENDING e nosso worker o envia ao PSP.
5

PIX é enviado

Status vai para PROCESSING e depois COMPLETED (ou FAILED).
6

Webhook é disparado

Você recebe WITHDRAWAL_COMPLETED ou WITHDRAWAL_FAILED no seu endpoint.

​
Ciclo de vida

​
Taxa e valor líquido

A taxa do saque é somada ao valor solicitado e debitada do saldo:
Por exemplo, para um saque de R100,00comtaxadeR 100,00 com taxa de R 0,50:
  • Você recebe na chave PIX: R$ 100,00
  • É debitado do seu saldo: R$ 100,50 (10050 centavos)

​
Tipos de chave PIX aceitos

​
Restrições

Quando o saque é bloqueado

  • Saques desabilitados para o merchant (withdrawalsEnabled = false)
  • Já existe um saque em andamento (PENDING ou PROCESSING) — só um por vez
  • Saldo insuficiente (available < amount + fee)
  • Valor acima do limite configurado para o merchant
  • Valor fora da faixa de 50 a 100.000.000 centavos (R0,50aR 0,50 a R 1.000.000,00)

​
Callback por saque

O campo opcional clientCallbackUrl aceita uma URL HTTPS pública. A API cria ou atualiza internamente o webhook no merchant autenticado com WITHDRAWAL_COMPLETED e WITHDRAWAL_FAILED. Ele substitui os endpoints gerais apenas para os eventos desse saque. Para conhecer o secret da assinatura, cadastre previamente a mesma URL em POST /webhooks e guarde o valor retornado.

​
Operações disponíveis