Skip to main content
Com o Connect, a conta master solicita o saque (payout) do saldo disponível de cada subconta. O dinheiro vai por Pix para a chave Pix CNPJ da própria subconta, sempre em reais. A taxa de saque é calculada na criação do pedido, todo saque de subconta passa por aprovação manual da operação Finvia, e o resultado chega por webhook e pela listagem.

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).
Esta página trata do saque de subconta. O saque do saldo da própria conta (master ou não) usa 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

O valor vai em reais. Enviar 10000 pensando em R$ 100,00 cria um pedido de saque de R$ 10.000,00.

Cálculo da taxa

A taxa é calculada automaticamente quando o pedido é criado:
Exemplo com uma taxa ilustrativa de R$ 2,00 fixa mais 0,5%, em um saque de R$ 1.500,00: 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

Resposta 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
O 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.
Os avisos de saque vão para os endpoints de webhook cadastrados na subconta e também para os endpoints da master cadastrados com a opção de incluir subcontas (no painel, em Configurações > Webhooks da conta selecionada). O webhook de saque não tem cabeçalho de assinatura: confirme o status pela listagem antes de agir. Saque da própria conta (master ou não) não gera webhook.
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.
Formato completo e exemplo de implementação em Webhooks de 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

Não. O destino é sempre a chave Pix CNPJ da subconta. Na listagem, isso aparece em externalAccountDetails como { "type": "pix", "pix_key": "<CNPJ>" }.
R$ 1,00. O campo amount aceita casas decimais, como 100.50 para R$ 100,50.
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.
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.
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.
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.