> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Saldo agregado por moeda

> Quanto o recebedor tem — disponível, a liberar, bloqueado — e quanto disso dá para sacar.

`GET /wallets/owner/:ownerId/balance`

Faz parte do recurso [Carteiras](/pt-BR/wallets) — o modelo de saldo e liberação está lá.

Devolve um item por moeda, somando todas as carteiras do recebedor. É a leitura que responde
"quanto posso sacar agora".

<Warning>
  **Ter saldo não é poder sacar.** Os quatro números respondem coisas diferentes: o **disponível**
  já foi liberado, o **a liberar** é venda cujo prazo de liquidação ainda corre, o **bloqueado**
  está retido, e o **sacável** é o que a [solicitação de saque](/pt-BR/withdrawals/create) aceita.

  O sacável é o menor de todos, e é o único que importa antes de pedir um saque — os outros três
  explicam por que ele é o que é.
</Warning>

<Note>
  **`balances` é uma lista, com um item por moeda.** Mesmo quando a conta só opera em `BRL` ela vem
  como array — uma integração que leia `balances[0]` sem conferir a `currency` quebra no dia em que
  houver duas.
</Note>

<Note>
  **O `ownerId` é o `rec_` do recebedor**, não um id de carteira. As carteiras são internas: você
  não as endereça uma a uma.
</Note>

## Exemplo

```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/wallets/owner/rec_v57bi6ruyolouw3cpaq2ofy1k/balance \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```

```json Resposta 200 theme={null}
{
  "recipientId": "rec_v57bi6ruyolouw3cpaq2ofy1k",
  "balances": [
    {
      "currency": "BRL",
      "availableBalance": 1250000,
      "pendingBalance": 380000,
      "blockedBalance": 0,
      "withdrawableBalance": 1250000
    }
  ]
}
```

<Note>
  Todos os valores em centavos. No exemplo, R\$ 3.800,00 de vendas ainda estão no prazo de liquidação
  e não entram no que pode ser sacado hoje.
</Note>


## OpenAPI

````yaml openapi/psp.json GET /wallets/owner/{ownerId}/balance
openapi: 3.0.3
info:
  title: Z2Pay PSP API
  version: 1.0.0
  description: API pública do PSP — autenticação via API Key (Credential)
servers:
  - url: https://api.sandbox.z2pay.com/v1
    description: Sandbox
  - url: https://api.z2pay.com/v1
    description: Produção
security: []
tags:
  - name: Cards
    description: Cartões salvos de um cliente
  - name: Chargebacks
    description: Gerenciamento de chargebacks
  - name: Customers
    description: Gerenciamento de clientes (compradores)
  - name: Fees
    description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
  - name: Recipients
    description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
  - name: Refunds
    description: Gerenciamento de reembolsos e estornos
  - name: Splits
    description: Regras de divisão do valor de uma venda entre recebedores
  - name: Transactions
    description: Gerenciamento de transações e payments
  - name: Wallets
    description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
  - name: Webhooks
    description: Configuração, gerenciamento e histórico de entregas de webhooks
  - name: Withdrawals
    description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
  /wallets/owner/{ownerId}/balance:
    get:
      tags:
        - Wallets
      summary: Saldo agregado por moeda
      description: >-
        Retorna o saldo do recebedor, um item por moeda: disponível, a liberar,
        bloqueado e o quanto disso dá para sacar — todos em centavos
      operationId: WalletController_getBalance
      parameters:
        - name: ownerId
          in: path
          required: true
          description: ID do recebedor
          schema:
            type: string
      responses:
        '200':
          description: Saldos agrupados por moeda
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipientId:
                    type: string
                    description: ID do recebedor.
                  balances:
                    type: array
                    items:
                      type: object
                      properties:
                        currency:
                          type: string
                          description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
                        availableBalance:
                          type: integer
                          description: Saldo disponível em centavos
                        pendingBalance:
                          type: integer
                          description: Saldo pendente em centavos
                        blockedBalance:
                          type: integer
                          description: Saldo bloqueado em centavos
                        withdrawableBalance:
                          type: integer
                          description: >-
                            Saldo sacável em centavos (aplica limite percentual
                            da company)
                    description: Saldos do recebedor discriminados por moeda.
              example:
                recipientId: rec_t8wq4hz2mxk9rpf5snc7ydv3b
                balances:
                  - currency: BRL
                    availableBalance: 1250000
                    pendingBalance: 380000
                    blockedBalance: 0
                    withdrawableBalance: 1250000
                  - currency: USD
                    availableBalance: 45000
                    pendingBalance: 12000
                    blockedBalance: 0
                    withdrawableBalance: 45000
        '401':
          description: Chave de API ausente, malformada ou inválida
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Identificador estável do erro. É por ele que você deve
                          ramificar, não pela mensagem.
                      message:
                        type: string
                        description: >-
                          Descrição legível. Pode mudar sem aviso e não deve ser
                          usada em condicional.
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid API key
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key da Credential (gerada no Backoffice)

````