Skip to main content
GET
Consultar saldo do merchant

Autenticação

Envie x-client-id e x-client-secret pelo seu servidor. Todas as credenciais ativas podem consultar o próprio saldo, sem um novo escopo. Revogação, expiração e restrições de IP continuam aplicáveis. Nunca exponha o segredo no navegador ou aplicativo cliente. A conta é identificada pela credencial. A requisição não aceita corpo nem parâmetros de consulta, incluindo merchantId. Essa consulta não exige assinatura HMAC nem chave de idempotência.

Valores retornados

Todos os valores monetários são inteiros em centavos da moeda currency. asOf indica o instante da leitura, em ISO 8601. Esses campos não são parcelas independentes para somar um saldo total. medBlockedBalanceCents informa o bloqueio consolidado; medRetainedBalanceCents corresponde ao valor retido por MED exibido no painel no mesmo instante asOf; e medLostBalanceCents acumula débitos permanentes já realizados. Um caso MED aberto pode reduzir o saqueável antes de o bloqueio aparecer no valor registrado/consolidado. Consulte o histórico de devoluções no painel autenticado, na área MED — Contestações Pix. Exemplo ilustrativo:

Limites e erros

A resposta usa Cache-Control: no-store. O limite é de 60 consultas por minuto por merchant por processo/instância da API, compartilhado pelas credenciais dessa conta nessa instância. O limite global por IP também se aplica; essa quota não é compartilhada entre processos ou réplicas. Esta operação consulta dados persistidos. Não movimenta dinheiro, libera reservas ou dispara reconciliação com provedores. Um saldo consultado não garante autorização de um saque posterior: as regras são verificadas novamente na operação financeira.

Authorizations

x-client-id
string
header
required

Client ID fornecido pela TurbofyPay.

x-client-secret
string
header
required

Client Secret fornecido pela TurbofyPay.

Headers

x-client-id
string
required

Identificador do integrador.

x-client-secret
string
required

Segredo de autenticacao do integrador.

Response

Default Response

currency
enum<string>
required
Available options:
BRL
asOf
string<date-time>
required
availableBalanceCents
integer
required

Saldo disponível para saque, igual a withdrawableCents.

Required range: x >= 0
withdrawableCents
integer
required
Required range: x >= 0
pendingBalanceCents
integer
required
Required range: x >= 0
reservedBalanceCents
integer
required
Required range: x >= 0
medBlockedBalanceCents
integer
required

Valor de bloqueio MED registrado ou consolidado; pode ser menor que a retenção considerada no saldo saqueável e não representa toda a obrigação MED.

Required range: x >= 0
medRetainedBalanceCents
integer
required

Retenção MED exibida: maior valor entre o bloqueio canônico e a soma dos valores efetivamente reservados dos casos MED abertos (com fallback para o valor bloqueado do caso).

Required range: x >= 0
medLostBalanceCents
integer
required

Perda MED acumulada registrada na carteira; não representa a retenção atual.

Required range: x >= 0
settlementDebtCents
integer
required
Required range: x >= 0
withdrawalFrozen
boolean
required
operationalHoldActive
boolean
required
nextReleaseAt
string<date-time> | null
required
Last modified on November 6, 2026