> ## 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.

# Carteiras

> Como o saldo de um recebedor se divide entre disponível, a liberar e bloqueado — e quanto disso dá para sacar.

A **carteira** guarda o saldo de um recebedor (`rec_`). Cada venda liquidada credita a carteira,
cada taxa debita, e o extrato é a lista desses lançamentos. Você consulta **saldo**, **resumo** e
**extrato** sempre por recebedor.

O saldo não é um número só, e é aí que a maioria dos enganos acontece: o valor **disponível** não é
o que dá para sacar. Entre um e outro entram o que está bloqueado e um limite percentual da sua
conta — a seção abaixo abre a conta inteira.

<Info>
  Todas as requisições usam o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao).
  A base URL de sandbox é `https://api.sandbox.z2pay.com/v1`.
</Info>

<Note>
  **"Owner" aqui é qualquer recebedor.** Em [Recebedores](/pt-BR/recipients), `owner` é um *papel*
  único da sua conta (`role: "owner"`). Nas rotas de carteira o `ownerId` é o id de **qualquer**
  recebedor — todos têm carteira.
</Note>

***

## Endpoints

| Método | Rota                                    | Descrição                             |
| ------ | --------------------------------------- | ------------------------------------- |
| `GET`  | `/wallets/owner/{ownerId}/balance`      | Saldo do recebedor, um item por moeda |
| `GET`  | `/wallets/owner/{ownerId}/summary`      | Totais de entrada e saída num período |
| `GET`  | `/wallets/owner/{ownerId}/transactions` | Extrato paginado                      |

<Note>
  **Não há endpoint por carteira.** Um recebedor pode ter mais de uma carteira internamente, e a
  API sempre devolve o consolidado — por isso tudo é por `ownerId` e moeda, nunca por carteira.
</Note>

***

## O que compõe o saldo

Todos os valores são **inteiros em centavos**: `152030` é R\$ 1.520,30.

| Campo                 | O que significa           | Quando acontece                                                                     |
| --------------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| `availableBalance`    | Já liberado               | A venda passou do prazo de liberação — veja [Liquidação](/pt-BR/valores/liquidacao) |
| `pendingBalance`      | Ainda a liberar           | Parcelas de cartão e vendas dentro do prazo; o extrato diz a data em `scheduledFor` |
| `blockedBalance`      | Retido                    | Chargeback em disputa ou reembolso pendente prendem o valor até a resolução         |
| `withdrawableBalance` | O que dá para sacar agora | É o disponível menos o bloqueado, com o limite percentual da sua conta aplicado     |

<Warning>
  **`withdrawableBalance` pode ser menor que `availableBalance` mesmo sem nada bloqueado.** A conta
  pode ter um teto percentual de saque configurado, e ele incide sobre o resultado. Para saber
  quanto realmente sai, leia `withdrawableBalance` — nunca calcule a partir do disponível.
</Warning>

***

## Veja também

<CardGroup cols={2}>
  <Card title="Saques" icon="banknote" href="/pt-BR/withdrawals">
    Como transformar saldo sacável em dinheiro na conta bancária.
  </Card>

  <Card title="Liquidação" icon="calendar-clock" href="/pt-BR/valores/liquidacao">
    Quando cada venda deixa de ser "a liberar" e vira disponível.
  </Card>

  <Card title="Recebedores" icon="users" href="/pt-BR/recipients">
    Quem são os donos das carteiras e como cadastrá-los.
  </Card>

  <Card title="Splits" icon="git-branch" href="/pt-BR/splits">
    Como o valor de uma venda chega dividido em várias carteiras.
  </Card>
</CardGroup>