> ## Documentation Index > Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt > Use this file to discover all available pages before exploring further. # Consultar saldo > Consulta segura do saldo saqueável, valores pendentes e reservas do próprio 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. ```bash theme={null} curl --request GET 'https://api.turbofypay.com/v1/balance' \ --header 'x-client-id: SEU_CLIENT_ID' \ --header 'x-client-secret: SEU_CLIENT_SECRET' ``` ## Valores retornados Todos os valores monetários são inteiros em centavos da moeda `currency`. `asOf` indica o instante da leitura, em ISO 8601. | Campo | Significado | | - | - | | `availableBalanceCents` | Saldo disponível para saque; igual a `withdrawableCents`. | | `withdrawableCents` | Valor saqueável após regras de liquidação, reservas e restrições. | | `pendingBalanceCents` | Valor pendente de liberação. | | `reservedBalanceCents` | Valor reservado pelo cálculo financeiro da plataforma. | | `medBlockedBalanceCents` | Bloqueio MED registrado/consolidado pelo serviço financeiro, considerando wallet e casos. Pode ser menor que a obrigação MED considerada no saldo saqueável; não representa toda retenção nem uma perda confirmada. | | `medRetainedBalanceCents` | Corresponde exatamente ao valor de retenção por MED exibido no painel no mesmo instante `asOf` da resposta, incluindo valores reservados em casos MED abertos. É `0` quando não há retenção por MED. | | `medLostBalanceCents` | Total acumulado, até `asOf`, dos débitos permanentes no saldo do merchant causados por MED. Representa perda efetivada, não valor apenas retido; é `0` quando não há débitos permanentes por MED. | | `settlementDebtCents` | Dívida de liquidação, separada do saldo saqueável. | | `withdrawalFrozen` | Indica restrição de saque. | | `operationalHoldActive` | Indica retenção operacional ativa. | | `nextReleaseAt` | Próxima liberação prevista em ISO 8601, ou `null` quando inexistente. | 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](https://app.turbofypay.com/merchant/med). Exemplo ilustrativo: ```json theme={null} { "currency": "BRL", "asOf": "2026-11-04T12:00:00.000Z", "availableBalanceCents": 10000, "withdrawableCents": 10000, "pendingBalanceCents": 2000, "reservedBalanceCents": 0, "medBlockedBalanceCents": 0, "medRetainedBalanceCents": 0, "medLostBalanceCents": 0, "settlementDebtCents": 0, "withdrawalFrozen": false, "operationalHoldActive": false, "nextReleaseAt": "2026-11-05T12:00:00.000Z" } ``` ## 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. | HTTP | Situação | | - | - | | `400` | Parâmetro ou corpo não permitido. | | `401` | Credenciais ausentes, inválidas, expiradas ou revogadas. | | `403` | Acesso recusado pela política de IP. | | `429` | Limite de consultas excedido; respeite `Retry-After` quando informado. | | `503` | Leitura financeira indisponível; não interpretar como saldo zero. | 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. ## OpenAPI ````yaml GET /v1/balance openapi: 3.0.3 info: title: Turbofy Public API version: 2.0.0 description: >- Especificacao publica da API TurbofyPay para Cobranca PIX, Saldo, Saques, Webhooks e Payouts. contact: name: Turbofy Team email: suporte@turbofy.com url: https://turbofy.com license: name: Proprietary url: https://turbofy.com/terms servers: - url: http://localhost:3030 description: Development Server - url: https://api.turbofypay.com description: Production Server security: [] tags: - name: Cobranca PIX description: Operacoes de cobranca PIX para integradores. - name: Saques description: Operacoes de saque para sellers. - name: Webhooks description: Cadastro e consulta de webhooks. - name: Payouts description: Gestao de lotes de payout. - name: Saldo description: Consulta do proprio saldo com credenciais de integracao. externalDocs: description: Documentação completa url: https://docs.turbofy.com paths: /v1/balance: get: tags: - Saldo summary: Consultar saldo do merchant description: >- Consulta somente o saldo do merchant identificado pelas credenciais ativas. Nao exige novo escopo. Valores em centavos; saldo disponivel corresponde ao saqueavel. Limite de 60 consultas/minuto por merchant por instancia, alem do limite global por IP. operationId: getMerchantBalance parameters: - $ref: '#/components/parameters/XClientId' - $ref: '#/components/parameters/XClientSecret' responses: '200': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - currency - asOf - availableBalanceCents - withdrawableCents - pendingBalanceCents - reservedBalanceCents - medBlockedBalanceCents - medRetainedBalanceCents - medLostBalanceCents - settlementDebtCents - withdrawalFrozen - operationalHoldActive - nextReleaseAt properties: currency: type: string enum: - BRL asOf: type: string format: date-time availableBalanceCents: type: integer minimum: 0 description: Saldo disponível para saque, igual a withdrawableCents. withdrawableCents: type: integer minimum: 0 pendingBalanceCents: type: integer minimum: 0 reservedBalanceCents: type: integer minimum: 0 medBlockedBalanceCents: type: integer minimum: 0 description: >- 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. medRetainedBalanceCents: type: integer minimum: 0 description: >- 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). medLostBalanceCents: type: integer minimum: 0 description: >- Perda MED acumulada registrada na carteira; não representa a retenção atual. settlementDebtCents: type: integer minimum: 0 withdrawalFrozen: type: boolean operationalHoldActive: type: boolean nextReleaseAt: type: string format: date-time nullable: true '400': description: Parâmetros ou corpo não permitidos. content: application/json: schema: type: object required: - error additionalProperties: true properties: error: anyOf: - type: object required: - code - message additionalProperties: true properties: code: type: string message: type: string - type: string statusCode: type: integer code: type: string message: type: string description: Parâmetros ou corpo não permitidos. '401': description: Credenciais ausentes ou inválidas. content: application/json: schema: type: object required: - error additionalProperties: true properties: error: anyOf: - type: object required: - code - message additionalProperties: true properties: code: type: string message: type: string - type: string statusCode: type: integer code: type: string message: type: string description: Credenciais ausentes ou inválidas. '403': description: IP não autorizado. content: application/json: schema: type: object required: - error additionalProperties: true properties: error: anyOf: - type: object required: - code - message additionalProperties: true properties: code: type: string message: type: string - type: string statusCode: type: integer code: type: string message: type: string description: IP não autorizado. '429': description: Limite de consultas excedido. content: application/json: schema: type: object required: - error additionalProperties: true properties: error: anyOf: - type: object required: - code - message additionalProperties: true properties: code: type: string message: type: string - type: string statusCode: type: integer code: type: string message: type: string description: Limite de consultas excedido. '503': description: Autenticação ou saldo indisponível. content: application/json: schema: type: object required: - error additionalProperties: true properties: error: anyOf: - type: object required: - code - message additionalProperties: true properties: code: type: string message: type: string - type: string statusCode: type: integer code: type: string message: type: string description: Autenticação ou saldo indisponível. security: - clientCredentials: [] clientSecret: [] components: parameters: XClientId: name: x-client-id in: header required: true schema: type: string description: Identificador do integrador. XClientSecret: name: x-client-secret in: header required: true schema: type: string description: Segredo de autenticacao do integrador. securitySchemes: clientCredentials: type: apiKey in: header name: x-client-id description: Client ID fornecido pela TurbofyPay. clientSecret: type: apiKey in: header name: x-client-secret description: Client Secret fornecido pela TurbofyPay. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.