Skip to main content
Cada mudança de estado de um saque dispara um evento na URL configurada na conta, em Dashboard → Equipe & API → Developer API. Em sandbox entra a marca de teste no nome: withdrawal.test.requested, withdrawal.test.completed, e assim por diante.
Pagar um código copia e cola chega nas mesmas URLs, mas com nome próprio: pix_payment.completed e pix_payment.failed. Esses dois trazem paymentId no lugar de withdrawalId, e o method é pix_payment. O resto dos campos é igual ao desta página. Pagamento que você faz não é saque, e misturar os dois na mesma família quebraria a sua conciliação de saques.

​
Campos

​
string
required
O evento da tabela acima, ou pix_payment.completed / pix_payment.failed quando é pagamento de código.
​
string
required
Identificador do saque. Em pix_payment.* o campo se chama paymentId, e é o mesmo payment.id que o pagamento devolveu.
​
string
required
Código legível da operação: SAQ-A1B2C3 no saque comum, TURBO-... no PIX enviado na hora e PAY-... no pagamento de código. É por ele que o suporte localiza a operação.
​
number
required
Valor em reais, decimal.
​
string
required
pix, pix_turbo, ltc, usd ou pix_payment (pagamento de código copia e cola).
​
string
required
Destino. Chave PIX, endereço LTC ou endereço USDT, conforme o método. No pagamento de código, a chave que o código apontava.
​
string
required
pendente, concluido, negado ou falhou.
​
string
Só quando não deu certo: o motivo, em texto pronto pra mostrar. Não vem em concluido.
​
string
O E2E do PIX, o mesmo número que aparece no extrato de quem recebeu. É o que resolve contestação com o outro banco. Ausente quando ainda não veio ou quando o método não é PIX.
​
string
Nome de quem recebeu, como o banco confirmou.
​
string
CPF ou CNPJ de quem recebeu, inteiro, pra você amarrar o saque a um cadastro seu. Nome sozinho não fecha conciliação, porque nome se repete. Pode vir mascarado quando é assim que a informação chega. É dado pessoal de terceiro: receba em HTTPS e guarde só o que precisar.
​
string
URL do comprovante desenhado, em imagem, o mesmo papel que o painel mostra. Serve pra repassar ao seu cliente ou anexar num chamado: dá pra embutir direto num <img>. É imutável, então pode cachear. O campo some quando não foi possível gerar, então trate a ausência como normal.
​
string
Presente em withdrawal.requested.
​
string
Presente nos eventos de desfecho.
Repare que o status aqui vem em português (pendente, concluido, negado), enquanto as cobranças usam inglês (pending, paid). São domínios diferentes da API e cada um manteve o vocabulário da sua área.
No comprovante em imagem o documento do recebedor sai mascarado, mesmo quando o recipientTaxId do JSON vem inteiro. A imagem é feita pra ser repassada adiante; o JSON vai só pra sua URL.

​
Um uso que compensa

Saque que não sai devolve o valor pro saldo, mas ninguém fica olhando o painel esperando isso. Um alerta em withdrawal.denied e withdrawal.failed costuma ser a diferença entre resolver no mesmo dia e descobrir na semana seguinte:
Este webhook não cobre todos os estados. O processing do PIX enviado na hora, que significa “o dinheiro saiu e o banco ainda não confirmou”, é visto por GET /v1/payouts. Não trate ausência de withdrawal.completed como saque não realizado.
As garantias são as mesmas dos outros: assinatura HMAC em X-Webhook-Signature, idempotência em X-Webhook-Id e reentrega com backoff.