Skip to main content
POST
Esta rota transfere dinheiro do saldo disponível da sua conta para a conta bancária da empresa. O saque é enviado por Pix, em reais, para a chave Pix CNPJ igual ao CNPJ cadastrado na sua conta. A solicitação nasce pending e depois é aprovada ou recusada. Vale para qualquer conta, com ou sem o Connect. Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de uma conta sem Connect não gera webhook.

Quando usar

Antes de chamar

  • Use a chave secreta (sk_) em Basic (Credenciais e ambientes).
  • A chave age com as permissões do usuário que a gerou. A chave padrão da conta pertence ao proprietário e funciona aqui. Uma chave gerada por um usuário com o perfil Desenvolvedor recebe 403 Acesso negado.
  • Não existe saque no Modo Teste. Com a chave de teste (sk_test_), a resposta é 403 WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE.
  • A conta precisa estar ativa, com saques habilitados e com taxa de saque configurada.
  • Cadastre o CNPJ da sua conta como chave Pix em uma conta bancária da empresa. É para essa chave que o Pix vai, e não é possível escolher outra.
  • Confira o saldo disponível em Listar carteiras: o campo isWithdrawalEnabled mostra se o saque está liberado na moeda.
O valor vai em reais: "amount": 100 significa R$ 100,00, e 100.50 significa R$ 100,50. Enviar 10000 pensando em R$ 100,00 pede um saque de R$ 10.000,00. O valor bruto sai do saldo disponível já na criação da solicitação.

Corpo da requisição

string
required
ID da sua própria conta. A rota não aceita o id de outra conta. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
number
required
Valor do saque em reais, maior que zero. Aceita casas decimais (ex.: 100.50 = R$ 100,50). Ex.: 100.
string
required
Moeda do saque, em código ISO 4217. Use BRL. Um código inválido devolve 400; um código válido que não é aceito para saque devolve 422.
object
required
Forma de envio do saque. Envie { "type": "pix" }, sem outros campos.

Respostas

A resposta de sucesso é 201 sem corpo: a API não devolve o id do saque. Para obter o id e acompanhar o status, chame Listar saques filtrando pelo merchantId da sua conta. A lista vem do mais recente para o mais antigo, então o saque que você acabou de pedir é o primeiro. As mensagens vêm em inglês, com uma exceção em português. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.

Mensagens do 422

Se receber 422 Payout execution failed: ..., não repita o pedido de imediato. A solicitação pode ter ficado criada como pending. Consulte Listar saques e só peça de novo se o saque não aparecer.

Regras do saque

Status do saque

approved não confirma que o dinheiro já chegou à conta de destino.
A API não consulta se o CNPJ está cadastrado como chave Pix. A solicitação é criada normalmente e o Pix é enviado na aprovação. Se a chave não existir, o Pix não é concluído, e o status do saque na API não mostra essa falha (ele pode continuar pending ou aparecer como approved). 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 valor de um saque approved não chegar, abra um chamado com o id do saque.
Para o negócio: antes do primeiro saque, a empresa precisa cadastrar o próprio CNPJ como chave Pix no banco. A taxa de saque é descontada do valor pedido. Transferência para conta bancária por outro meio e saque em outra moeda não fazem parte desta documentação.

Erros comuns

Veja também

Listar saques

Obtenha o id e acompanhe o status.

Listar carteiras

Saldo disponível antes do saque.

Saldos e meios de pagamento

Como saldo, saque e taxas se relacionam.

Criar saque da subconta

Saque de subconta pela conta master.