Quando usar
- Vendedor de marketplace que quer retirar o que vendeu: a sua plataforma oferece um botão “sacar” e cria o pedido pela API.
- Repasse periódico a lojistas de um PSP: a sua aplicação cria pedidos de saque conforme a regra combinada com cada lojista.
- Painel financeiro do vendedor: a sua plataforma lista os saques com status, taxa e valor líquido (o valor do saque menos a taxa).
POST /v1/payout-requests e está em Saldos e meios de pagamento. A master também pode sacar o próprio saldo pela rota de subconta, passando o próprio id no caminho.
Como funciona
O desenho abaixo mostra um saque de subconta do pedido ao aviso, com os dois resultados possíveis. O webhook de saque não tem assinatura: confirme o status pela listagem antes de agir, como no último passo do desenho.1
Pedido de saque
Sua aplicação chama
POST /v1/submerchants/{merchantId}/payout-requests com a chave secreta da conta master e o valor em reais.2
Validação e reserva do valor
A Finvia confere a subconta (ativa, sem bloqueio, com CNPJ e saques habilitados), o saldo disponível e o limite por saque, calcula a taxa de saque (fixa mais percentual) e cria o pedido com status
pending. O valor bruto sai do saldo disponível nesse momento. A resposta traz o id do pedido.3
Aprovação ou recusa
A operação Finvia aprova (
approved) ou recusa (rejected) o pedido. Na aprovação, o Pix do valor líquido é enviado para a chave CNPJ da subconta. Na recusa, o valor volta ao saldo disponível.4
Aviso
Os webhooks
payout.approved e payout.rejected vão para os endpoints cadastrados na subconta e para os endpoints da master cadastrados com a opção de incluir subcontas.Pré-requisitos
Para o negócio: o saque é enviado por Pix para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). Antes de liberar o saque, cada vendedor precisa cadastrar esse CNPJ como chave Pix em uma conta bancária da empresa; não é possível escolher outra chave. A taxa de saque é uma condição comercial definida com a Finvia: mostre ao vendedor quanto ele vai receber já descontada a taxa.
Regras de negócio
Cálculo da taxa
A taxa é calculada automaticamente quando o pedido é criado:
Na listagem e nos webhooks, os valores chegam como texto decimal com 8 casas, em reais:
amount "1500.00000000", payoutFee "9.50000000" e, no webhook, netAmount "1490.50000000". Converta para número antes de calcular e não divida por 100.
Status do saque
approved significa aprovado e enviado para pagamento. O dinheiro pode ainda não ter chegado à conta de destino.
O desenho abaixo mostra o ciclo de status do pedido de saque e o que acontece com o saldo em cada etapa.
Os webhooks só existem para saques de subconta. O saque da própria conta (master ou não) não gera webhook: acompanhe pela listagem.
Passo a passo
1. Crie o pedido de saque
201:
2. Acompanhe pela listagem
GET /v1/payout-requests lista os pedidos, do mais recente para o mais antigo. Para a conta master, a lista inclui os saques das subcontas; filtre por merchantId para ver uma conta só.
A API ignora parâmetros desconhecidos sem erro: filtros como
createdAt ou processedAt não existem e não filtram nada.
cURL
200
pendingCount traz o total de pedidos pending com os mesmos filtros (sem considerar o filtro status), útil para um indicador de “saques aguardando” no seu painel. A listagem não traz netAmount nem rejectionReason: o líquido é amount menos payoutFee, e o motivo da recusa chega no webhook payout.rejected. A listagem é a única forma de consultar saques: não há consulta individual para contas merchant.
3. Receba o aviso de aprovação ou recusa
Quando o pedido é aprovado ou recusado, a Finvia envia um webhook:
Não há evento de criação de saque.
payout.rejected
id da raiz é o id do saque, igual a data.id, e se repete nos eventos do mesmo saque: use id + event para descartar avisos repetidos. Os webhooks de saque usam camelCase e não têm livemode.
Em validação (V-49): o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). A API não confere se o CNPJ está cadastrado como chave Pix; se não estiver, o Pix não é concluído e o status do saque não mostra a falha (ele pode continuar
pending ou aparecer como approved). Enquanto isso, se o vendedor não receber, abra um chamado com o id do saque.Erros comuns
As mensagens vêm em inglês. Trate o erro pelo código HTTP e use a mensagem só para registro ou exibição.
Perguntas frequentes
Posso escolher outra chave Pix ou uma conta bancária?
Posso escolher outra chave Pix ou uma conta bancária?
Não. O destino é sempre a chave Pix CNPJ da subconta. Na listagem, isso aparece em
externalAccountDetails como { "type": "pix", "pix_key": "<CNPJ>" }.Qual é o valor mínimo de saque?
Qual é o valor mínimo de saque?
R$ 1,00. O campo
amount aceita casas decimais, como 100.50 para R$ 100,50.Quanto tempo leva para o dinheiro cair?
Quanto tempo leva para o dinheiro cair?
O saque de subconta passa por aprovação manual da operação Finvia. O Pix é enviado quando o pedido é aprovado. Combine com os vendedores que o dinheiro não cai no momento do pedido.
Como mostro ao vendedor quanto ele vai receber?
Como mostro ao vendedor quanto ele vai receber?
Depois de criar o pedido, consulte a listagem filtrando por
merchantId. Cada pedido traz amount e payoutFee; o líquido é a diferença. O webhook de aprovação traz também netAmount.A conta master é avisada dos saques das subcontas?
A conta master é avisada dos saques das subcontas?
Sim, se tiver um endpoint de webhook cadastrado com a opção de incluir subcontas. Sem isso, os avisos vão só para os endpoints da subconta. A master também acompanha todos os saques pela listagem
GET /v1/payout-requests, que traz merchantLegalName e merchantEmail de cada pedido.Consigo testar o saque no Modo Teste?
Consigo testar o saque no Modo Teste?
Não. Com a chave de teste, a criação responde
403 WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE, e a listagem só traz registros de teste (na prática, vazia).Como testar
No roteiro de homologação, o cenário FC-07 confere o saque da subconta com valor em reais: a requisição montada, o tratamento da resposta{ "id" } e dos erros documentados. Como não existe saque com a chave de teste, o cenário não é executado no Modo Teste.
Veja também
Webhooks de saque
Envelope, campos e implementação.
Criar saque da subconta
Referência da rota de criação.
Listar saques
Referência da listagem e dos filtros.
Saldos e meios de pagamento
Saldo por moeda e saque da própria conta.

