Skip to main content
GET
Cada merchant tem uma carteira (wallet) por moeda. Esta rota devolve essas carteiras com três saldos: disponível (available), pendente (pending) e reservado (reserved). Ela também informa se o saque está habilitado em cada moeda e traz os mesmos saldos convertidos para dólar.

Quando usar

Antes de chamar

  • Use a chave secreta (sk_) em Basic, como no resto da API (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 nesta rota.
  • Tenha o merchantId da conta que você quer consultar: a sua própria conta ou, para a conta master do Connect, uma subconta.

Parâmetros de consulta

string
required
ID do merchant cujas carteiras você quer consultar. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
string
Filtra pela moeda da carteira (código ISO 4217). Ex.: BRL.

Respostas

A resposta 200 é um array de carteiras, sem paginação. Cada item tem os campos abaixo.
string
Moeda da carteira. Ex.: BRL.
boolean
Indica se o saque está habilitado nesta moeda. Ex.: true.
object
Saldos na moeda da carteira.
object
Os mesmos saldos convertidos para dólar (USD).
O contrato não detalha as regras que movem o valor de pending para available nem o que leva um valor a reserved. Para essas regras, consulte o guia de Saldos e meios de pagamento e o seu contato comercial.
Para o negócio: os valores estão em reais (na unidade da moeda): 1000.5 significa R$ 1.000,50. Antes de pedir um saque, confira duas coisas na carteira da moeda: se isWithdrawalEnabled é true e se balance.available cobre o valor.
Trate o erro pelo código HTTP, não pelo texto da mensagem.

Exemplos por caso de uso

Consulta só a carteira em BRL, para mostrar no painel.

Erros comuns

Como testar

O cenário PAY-01 do Roteiro de homologação pede a consulta do saldo disponível por moeda antes do saque. A consulta funciona com a chave de teste, mas o saque não: não existe saque no Modo Teste.

Veja também

Saldos e meios de pagamento

Como acompanhar saldo e sacar.

Solicitar saque

Saque do saldo da própria conta, por Pix.

Meios de pagamento

Formas de pagamento disponíveis na conta.

Criar saque da subconta

Saque de subconta pela conta master.