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
200:
Caso de uso: saldo num dashboard
Um ERP quer mostrar ao financeiro um cartão com o saldo do dia:Node.js
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 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.
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
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
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
Qual saldo posso sacar?
Qual saldo posso sacar?
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.Posso sacar para outra chave Pix ou por transferência bancária?
Posso sacar para outra chave Pix ou por transferência bancária?
Não. O saque publicado nesta documentação é só por Pix, para a chave CNPJ da própria conta.
Como sei o id do saque que pedi?
Como sei o id do saque que pedi?
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.Por que o saldo vem também em USD?
Por que o saldo vem também em USD?
O objeto
usdBalance traz os mesmos três valores convertidos para dólar, o que ajuda a ver o total numa base única.Posso usar a mesma chave secreta nas três rotas?
Posso usar a mesma chave secreta nas três rotas?
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.

