payout.approved quando o saque foi aprovado e enviado para pagamento, e payout.rejected quando a solicitação foi recusada, com o motivo.
Para o negócio: em um marketplace, o vendedor quer saber quando o saque sai. Com estes eventos, a sua plataforma mostra ao vendedor o status do saque e o valor líquido, sem que ninguém precise conferir o painel. Se o saque for rejeitado, o motivo chega junto, e o seu time de suporte pode orientar o vendedor.
Quando usar
Como funciona
O desenho abaixo mostra o caminho de um saque de subconta, do pedido ao webhook.1
O saque da subconta é solicitado
A conta master solicita em
POST /v1/submerchants/{merchantId}/payout-requests, ou a própria subconta solicita com a chave dela. Em qualquer caso, a solicitação nasce com status pending e o valor bruto sai do saldo disponível.2
A Finvia decide
A solicitação é aprovada ou rejeitada pela operação da Finvia. Na aprovação, o Pix do valor líquido é enviado ao provedor de pagamento. Na rejeição, o valor reservado volta ao saldo disponível.
3
A Finvia escolhe os destinos
O aviso vai para os endpoints de webhook cadastrados na subconta e para os endpoints da conta master cadastrados com a opção de incluir subcontas (
include_submerchants: true). Em cada endpoint, vale o filtro de eventos (enabled_events); lista vazia recebe todos.4
O webhook é enviado
O aviso é enviado depois que os dados foram gravados, então uma consulta feita ao receber o webhook já mostra o resultado. Uma falha de entrega não interrompe a aprovação nem a rejeição.
Eventos disponíveis
Não há evento de criação do saque. Para saber que um saque foi solicitado, use a resposta da criação ou a listagem de saques.
Regras de negócio
Status do saque
O webhook só chega com
approved ou rejected. approved significa que o Pix do valor líquido foi enviado ao provedor no momento da aprovação. Não trate esse status como confirmação de crédito na conta bancária do vendedor.
Envelope (camelCase)
O envelope do saque é mais simples que o de cobrança: oid da raiz é o id da solicitação de saque, igual a data.id, e se repete nos eventos do mesmo saque. Não há id de evento próprio, livemode, processedAt nem createdAt.
Em validação (V-16): há uma mudança em desenvolvimento no webhook de saque: id de evento próprio na raiz, campo
livemode, registro de entrega e envio também para os saques da conta master. Esta página descreve o formato atual. Escreva o parser aceitando campos adicionais sem erro.Campos do objeto data
Valores em texto decimal
Os valores chegam como texto:"100.00000000" é R$ 100,00. Converta antes de usar. Em JavaScript, data.netAmount.toFixed(2) dá erro, porque toFixed não existe em texto.
Payloads por evento
- payout.approved
- payout.rejected
Enviado depois da aprovação da solicitação e do envio do pagamento.
Configuração
- Pelo painel
- Pela API
No painel da Finvia, selecione a conta e vá em Configurações > Webhooks. Há dois caminhos:
- Na conta master, cadastre um endpoint com a opção de incluir subcontas. Ele recebe os saques de todas as subcontas.
- Com a subconta selecionada, cadastre um endpoint só para ela.
Passo a passo
Node.js
Erros comuns
Perguntas frequentes
Sou a conta master. Como acompanho os saques dos meus vendedores?
Sou a conta master. Como acompanho os saques dos meus vendedores?
Cadastre um endpoint na conta master com a opção de incluir subcontas (
include_submerchants: true). Ele recebe os eventos de saque de todas as subcontas, e data.merchantId indica de qual subconta é o saque. Para conciliar, consulte a listagem de saques.O saque da minha própria conta gera webhook?
O saque da minha própria conta gera webhook?
Não. Só os saques de subconta geram webhook. O saque da própria conta é acompanhado pela listagem, que traz os saques do mais recente para o mais antigo.
Para onde vai o dinheiro do saque?
Para onde vai o dinheiro do saque?
Para a chave Pix do tipo CNPJ igual ao CNPJ cadastrado na subconta. A moeda é
BRL.Como a taxa de saque aparece?
Como a taxa de saque aparece?
Em
payoutFee, em reais, como texto decimal. O valor que o vendedor recebe é netAmount, que é amount menos a taxa. O cálculo está em Saques do Connect.approved quer dizer que o dinheiro caiu na conta do vendedor?
approved quer dizer que o dinheiro caiu na conta do vendedor?
Significa que o saque foi aprovado e que o Pix do valor líquido foi enviado para pagamento. Se o vendedor não receber, acione o suporte da Finvia com o id do saque.
Como testar
Saques não existem no Modo Teste, então o webhook de saque só pode ser observado com um saque real de subconta, em produção, de valor baixo.
Guarde o registro do webhook
payout.approved ou payout.rejected recebido e a resposta HTTP que o seu endpoint devolveu.
Veja também
Saques do Connect
Como a subconta solicita e acompanha saques.
Listar saques
Consulta de solicitações com filtros.
Criar endpoint de webhook
Cadastro com include_submerchants e filtro de eventos.
Webhooks: visão geral
Destinos, formatos, entrega e deduplicação.

