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

# Carteiras para seus clientes

> Abra uma carteira por cliente final, registre chaves PIX, leia saldos e movimente dinheiro entre carteiras

Uma carteira é a conta que guarda saldos, cartões e chaves PIX. Muitas integrações abrem uma carteira por cliente final para que o dinheiro, os cartões e as cobranças de cada cliente fiquem isolados. Este guia cobre como criar uma carteira, registrar uma chave PIX nela, ler seus saldos, movimentar dinheiro entre carteiras e ler suas transações.

## Criar uma carteira

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "currency": "986" }'
```

A carteira é criada com `status: "PENDING"` e retorna seu `_id` (o `walletId`). Ela passa a `ACTIVE` assim que provisionada.

```json theme={null}
{
  "_id": "6981f701fac3b778cf808272",
  "currency": "986",
  "status": "PENDING",
  "role": "CHECKING"
}
```

Referência: [`POST .../accounts/{accountId}/wallets`](/api-reference/banking/wallets/realms-organizations-accounts-wallets-1)

## Ler uma carteira e seus saldos

Busque uma carteira para ler seus saldos. O saldo é dividido em **categorias**; `totalBalance` é a soma.

```bash theme={null}
curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

```json theme={null}
{
  "_id": "65425d6b3922c7d5aee353c5",
  "status": "ACTIVE",
  "totalBalance": 1378,
  "balances": [
    { "category": "FLEX_INTERNATIONAL", "amount": 1378 },
    { "category": "FLEX_NATIONAL", "amount": 0 },
    { "category": "BLOCKED", "amount": 0 }
  ]
}
```

Os valores estão em centavos. `FLEX_INTERNATIONAL` é a categoria de uso geral utilizada na maioria dos fluxos.

Referência: [`GET .../wallets/{walletId}`](/api-reference/banking/wallets/realms-organizations-accounts-wallets-2)

## Registrar uma chave PIX

Uma carteira precisa de uma chave PIX (DICT) para receber cobranças. Crie uma chave aleatória (`EVP`) na carteira:

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-dict' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "EVP" }'
```

A resposta retorna o `value` da chave e seu `status: "ACTIVE"`. Use esse valor como o `pixDict` ao criar cobranças ou autorizações de PIX Automático.

Gerencie as chaves com:

* **Listar chaves** — [`GET .../wallets/{walletId}/pix-dict`](/api-reference/banking/pix-keys-dict/realms-organizations-accounts-wallets-pix-dict)
* **Remover uma chave** — [`POST .../pix-dict/{pixDictId}/remove`](/api-reference/banking/pix-keys-dict/realms-organizations-accounts-wallets-pix-dict-remove) (retorna `204`)

## Movimentar dinheiro entre carteiras (P2P)

Transfira um saldo de uma carteira para outra — por exemplo, varrendo a carteira de um cliente para a carteira da sua organização. A transferência é interna e liquida instantaneamente.

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transfers-p2p' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCategory": "FLEX_INTERNATIONAL",
    "destinationRealmId": "...",
    "destinationOrganizationId": "...",
    "destinationAccountId": "...",
    "destinationWalletId": "...",
    "destinationCategory": "FLEX_INTERNATIONAL",
    "amount": 316
  }'
```

| Campo                                    | Observações                                                                      |
| ---------------------------------------- | -------------------------------------------------------------------------------- |
| `sourceCategory` / `destinationCategory` | Categoria de saldo a debitar e creditar.                                         |
| `destination*`                           | O endereço completo da carteira receptora (realm, organização, conta, carteira). |
| `amount`                                 | Centavos.                                                                        |

A resposta retorna `status: "PROCESSED"` e as carteiras de origem e destino atualizadas com seus novos saldos.

Referência: [`POST .../wallets/{walletId}/transfers-p2p`](/api-reference/banking/transfers/realms-organizations-accounts-wallets-transfers-p2p)

## Ler transações

Liste todas as transações de uma carteira — cartões, PIX, boleto, tarifas e P2P juntos. Filtre por tipo e intervalo de datas; pagine com o cursor `next`.

```bash theme={null}
curl 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions?transactionType=PIX&startDate=2026-01-01&endDate=2026-01-31' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

`transactionType` aceita `CARD`, `PIX`, `BOLETO`, `FEE` ou `P2P`. O formato de cada item depende do seu tipo (um bloco `cardTransaction` ou `pixTransaction` é aninhado conforme o caso).

Referência: [`GET .../wallets/{walletId}/transactions`](/api-reference/banking/transactions/realms-organizations-accounts-wallets-transactions)

<Tip>
  Para o histórico somente de cartão, use o endpoint de transações por cartão descrito em [Gerenciar e monitorar cartões](/guides/manage-cards#read-a-cards-transactions).
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cobrar com PIX" icon="qrcode" href="/guides/collect-pix">
    Use a chave PIX de uma carteira para receber um pagamento.
  </Card>

  <Card title="Emitir cartões virtuais" icon="credit-card" href="/guides/issue-virtual-cards">
    Crie cartões dentro de uma carteira.
  </Card>
</CardGroup>