Skip to main content
Três tarefas do dia a dia financeiro ficam nesta página. GET /v1/wallets mostra o saldo da conta por moeda: quanto está disponível, quanto ainda vai ser liberado e quanto está reservado. POST /v1/payout-requests saca o saldo disponível por Pix para a chave CNPJ da empresa. GET /v1/payment-methods lista as formas de pagamento habilitadas para a conta, para montar o checkout com o que está de fato disponível.
Para o negócio: com o saldo e o saque pela API, o financeiro acompanha o caixa e pede saques do próprio sistema de gestão, sem entrar no painel. A Finvia oferece cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix; a lista de meios de pagamento mostra o que está habilitado na sua conta.

Quando usar

O saque do saldo de uma subconta do Connect é outro fluxo: veja Saques da subconta.

Como funciona

1

Consulte o saldo

GET /v1/wallets?merchantId=... devolve uma lista com uma carteira por moeda, com available (disponível), pending (a liberar) e reserved (reservado), e isWithdrawalEnabled.
2

Peça o saque

POST /v1/payout-requests com o valor em reais e externalAccountDetails { "type": "pix" }. A resposta 201 não tem corpo.
3

Acompanhe pela listagem

GET /v1/payout-requests com o merchantId da sua conta traz o saque mais recente primeiro, com status pending, approved ou rejected. O saque da conta master ou de conta sem Connect não gera webhook (só os saques de subconta geram, qualquer que seja a rota usada para criar).
4

Consulte os meios de pagamento

GET /v1/payment-methods devolve as formas de pagamento habilitadas, com países e moedas aceitos.

Regras de negócio

Saldo: GET /v1/wallets

Campos da resposta

Use available como o valor que pode ser sacado. Um saque pedido sai do saldo disponível já na criação, mesmo antes da aprovação; se for recusado, o valor volta.

Exemplo

Resposta 200:

Caso de uso: saldo num dashboard

Um ERP quer mostrar ao financeiro um cartão com o saldo do dia:
Node.js
Para o desenvolvedor: a resposta é um array. Se a conta não tem carteira na moeda filtrada, o array pode vir vazio. Trate esse caso antes de ler balance.

Saque da própria conta: POST /v1/payout-requests

O saque transfere o saldo disponível da sua conta para a conta bancária da empresa, por Pix, na chave Pix CNPJ igual ao CNPJ do cadastro. Vale para qualquer conta, com ou sem Connect.
O saque é enviado por Pix para a chave CNPJ da sua conta (o mesmo CNPJ do cadastro). Antes de solicitar saques, cadastre esse CNPJ como chave Pix em uma conta bancária da empresa. Não é possível escolher outra chave. Se a chave não existir, o Pix não é concluído; nesse caso, fale com o suporte.
O desenho abaixo mostra o caminho de um saque da própria conta, do saldo consultado ao Pix na chave CNPJ.

Regras

Exemplo

Acompanhe o status

GET /v1/payout-requests com o merchantId da sua conta mostra cada saque com status: Na listagem, amount e payoutFee chegam como texto decimal com 8 casas (ex.: "500.00000000"). Converta antes de calcular. Veja todos os filtros em Listar saques.
Se a criação responder 422 Payout execution failed: ... (acontece só com aprovação automática), não repita o pedido de imediato. A solicitação pode ter ficado criada como pending. Consulte a listagem antes de tentar de novo.
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, e o status do saque não mostra essa falha. Enquanto isso, se o valor de um saque não chegar, abra um chamado com o id do saque.

Meios de pagamento: GET /v1/payment-methods

Regras

Campos da resposta

Exemplo

Resposta 200 (exemplo ilustrativo; os valores dependem da sua conta):

Caso de uso: checkout dinâmico

Neste exemplo, o checkout consulta a lista na abertura da página e mostra só o que a conta aceita para a moeda e o país do pedido:
Node.js
Para o desenvolvedor: você pode guardar a lista em cache por alguns minutos para não consultar a API a cada visita ao checkout. Defina o tempo de cache conforme a sua operação: a documentação não informa com que frequência a lista muda.
A documentação não fixa o valor de name para Pix e cartão de crédito nessa lista. Ao mapear name para o paymentMethod.type de POST /v1/charges, confira os valores que a sua conta devolve.

Erros comuns

Mais mensagens de erro do saque em Solicitar saque.

Perguntas frequentes

O valor de balance.available, desde que isWithdrawalEnabled seja true para a moeda e o valor respeite o limite por saque da conta. pending e reserved não estão disponíveis para saque.
Não. O saque publicado nesta documentação é só por Pix, para a chave CNPJ da própria conta.
A criação responde 201 sem corpo. Liste GET /v1/payout-requests com o merchantId da sua conta: a lista vem do mais recente para o mais antigo.
O objeto usdBalance traz os mesmos três valores convertidos para dólar, o que ajuda a ver o total numa base única.
Sim. As três usam Basic com a chave secreta. Só confirme que a chave não foi gerada por um usuário com perfil Desenvolvedor, que não acessa saldo nem saques.

Como testar

Como não existe saque no Modo Teste, os cenários de saque são conferidos no código e na montagem da requisição. Detalhes no roteiro de homologação. A consulta de meios de pagamento também é a forma mais simples de validar a chave, como mostrado em Credenciais e ambientes.

Veja também

Listar carteiras

Contrato completo de GET /v1/wallets.

Solicitar saque

Contrato completo de POST /v1/payout-requests.

Listar saques

Filtros e status dos saques.

Listar meios de pagamento

Contrato completo de GET /v1/payment-methods.