Skip to main content
POST
Esta rota cria uma solicitação de saque (payout) para uma subconta (SubMerchant) do Connect. Quem chama é a conta master, com a própria chave secreta. O valor sai do saldo disponível da subconta e é enviado por Pix, em reais, para a chave Pix CNPJ da subconta. A solicitação nasce pending e sempre passa por aprovação manual da operação Finvia.

Quando usar

Antes de chamar

  • Use a chave secreta (sk_) da conta master em Basic. A conta master precisa ter o Connect habilitado pela Finvia; sem isso, a resposta é 403 Fast Connect not enabled..
  • A chave age com as permissões do usuário que a gerou. Uma chave de usuário com perfil Desenvolvedor recebe 403 Acesso negado. Use a chave padrão da conta (do proprietário) ou uma gerada por Owner ou Manager.
  • Não existe saque no Modo Teste: com a chave de teste (sk_test_), a resposta é 403 WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE.
  • A subconta precisa estar ativa (active), com CNPJ cadastrado, saques habilitados e taxa de saque configurada.
  • O CNPJ da subconta precisa estar cadastrado como chave Pix em uma conta bancária da empresa. A API não confere isso na criação do saque.
O valor vai em reais: "amount": 100 significa R$ 100,00, e 100.50 significa R$ 100,50. O mínimo é 1 (R$ 1,00). Enviar 10000 pensando em R$ 100,00 pede um saque de R$ 10.000,00.

Parâmetros de caminho

string
required
ID da subconta que vai sacar. A conta master também pode informar o próprio id para sacar o próprio saldo. Ex.: 36OO3bcGjhPjjF3tzrqOGcmQuKo.

Corpo da requisição

number
required
Valor do saque em reais. Aceita casas decimais (ex.: 100.50 = R$ 100,50). Mínimo: 1 (R$ 1,00). Ex.: 100.
Não há outros campos. A moeda é sempre BRL e o destino é sempre Pix na chave CNPJ da subconta: não é possível informar outra conta de destino.

Respostas

string
Identificador da solicitação de saque criada. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI. Guarde este valor: ele chega no campo id dos webhooks de saque e identifica o saque na listagem.
As mensagens vêm em inglês. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.

Validação do valor (400)

Mensagens do 422

Taxa e valor líquido

A taxa de saque tem uma parte fixa e uma parte percentual sobre o valor, e é descontada do valor pedido:
Com amount 100 e taxa de R$ 1,00, chegam R$ 99,00 no Pix. Na listagem e nos webhooks de saque, os valores chegam como texto decimal com 8 casas (ex.: "99.00000000").

Status e acompanhamento

1

Solicitação criada

A resposta 201 traz o id. O valor bruto sai do saldo disponível da subconta e o saque fica pending.
2

Aprovação ou recusa

A operação Finvia aprova (approved) ou recusa (rejected). Na aprovação, o Pix do valor líquido é enviado. Na recusa, o valor volta ao saldo disponível.
3

Aviso por webhook

Os eventos payout.approved e payout.rejected vão para os endpoints de webhook cadastrados na subconta e para os endpoints da master cadastrados com a opção de incluir subcontas. Veja Webhooks de saque.
approved significa aprovado e enviado para pagamento. Ele não confirma que o dinheiro já chegou à conta de destino.
O Pix vai para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). A API não consulta se essa chave existe. Se o CNPJ não estiver cadastrado como chave Pix, o Pix não é concluído e o status do saque na API não mostra essa falha. Nesse caso, fale com o suporte da Finvia.
Em validação (V-49): o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). Enquanto isso, se o vendedor não receber um saque approved, abra um chamado com o id do saque.
Para o negócio: o vendedor precisa ter o CNPJ da empresa cadastrado como chave Pix antes do primeiro saque. A taxa de saque é descontada do valor pedido. Como todo saque de subconta passa por aprovação manual, combine com os vendedores que o dinheiro não cai na hora do pedido.

Erros comuns

Veja também

Saques no Connect

Fluxo completo de saque das subcontas.

Listar saques

Acompanhe status e valores.

Webhooks de saque

Eventos payout.approved e payout.rejected.

Homologação

Cenário FC-07: saque da subconta.