Skip to main content
Quando uma subconta do Connect tem um saque (payout) solicitado, a solicitação fica pendente até ser aprovada ou rejeitada. Os webhooks de saque avisam o resultado: 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

Mantenha uma rotina que consulte a listagem de saques para conciliar os saques ainda marcados como pendentes no seu sistema. Filtre por merchantId para ver uma subconta só e use status=pending para achar os que aguardam decisão.

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: o id 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.
Para somar ou guardar valores financeiros, prefira um tipo decimal do seu banco ou uma biblioteca de decimais, partindo do texto recebido.

Payloads por evento

Enviado depois da aprovação da solicitação e do envio do pagamento.

Configuração

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.
O endpoint cadastrado pelo painel recebe todos os eventos (cobrança, assinatura e saque).

Passo a passo

Node.js
Para o desenvolvedor: o id da raiz é o id do saque, por isso a chave pelo corpo é id + event, conforme a receita de deduplicação. Eventos diferentes do mesmo saque não se confundem.

Erros comuns

Perguntas frequentes

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.
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 a chave Pix do tipo CNPJ igual ao CNPJ cadastrado na subconta. A moeda é BRL.
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.
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.