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

# Wallets for your customers

> Open a wallet per end customer, register PIX keys, read balances, and move money between wallets

A wallet is the account that holds balances, cards, and PIX keys. Many integrations open one wallet per end customer so each customer's money, cards, and charges are isolated. This guide covers creating a wallet, registering a PIX key on it, reading its balances, moving money between wallets, and reading its transactions.

## Create a wallet

```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" }'
```

The wallet is created with `status: "PENDING"` and returns its `_id` (the `walletId`). It becomes `ACTIVE` once provisioned.

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

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

## Read a wallet and its balances

Fetch a wallet to read its balances. The balance is split into **categories**; `totalBalance` is the sum.

```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 }
  ]
}
```

Amounts are in centavos. `FLEX_INTERNATIONAL` is the general-purpose category used in most flows.

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

## Register a PIX key

A wallet needs a PIX key (DICT) to receive charges. Create a random key (`EVP`) on the wallet:

```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" }'
```

The response returns the key `value` and its `status: "ACTIVE"`. Use that value as the `pixDict` when creating charges or Pix Automático authorizations.

Manage keys with:

* **List keys** — [`GET .../wallets/{walletId}/pix-dict`](/api-reference/banking/pix-keys-dict/realms-organizations-accounts-wallets-pix-dict)
* **Remove a key** — [`POST .../pix-dict/{pixDictId}/remove`](/api-reference/banking/pix-keys-dict/realms-organizations-accounts-wallets-pix-dict-remove) (returns `204`)

## Move money between wallets (P2P)

Transfer a balance from one wallet to another — for example, sweeping a customer wallet into your organization wallet. The transfer is internal and settles instantly.

```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
  }'
```

| Field                                    | Notes                                                                            |
| ---------------------------------------- | -------------------------------------------------------------------------------- |
| `sourceCategory` / `destinationCategory` | Balance category to debit and credit.                                            |
| `destination*`                           | The full address of the receiving wallet (realm, organization, account, wallet). |
| `amount`                                 | Centavos.                                                                        |

The response returns `status: "PROCESSED"` and the updated origin and destination wallets with their new balances.

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

## Read transactions

List all transactions in a wallet — cards, PIX, boleto, fees, and P2P together. Filter by type and date range; page with the `next` cursor.

```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` accepts `CARD`, `PIX`, `BOLETO`, `FEE`, or `P2P`. Each item's shape depends on its type (a `cardTransaction` or `pixTransaction` block is nested accordingly).

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

<Tip>
  For card-only history, use the per-card transactions endpoint described in [Manage and monitor cards](/guides/manage-cards#read-a-cards-transactions).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Charge with PIX" icon="qrcode" href="/guides/collect-pix">
    Use a wallet's PIX key to collect a payment.
  </Card>

  <Card title="Issue virtual cards" icon="credit-card" href="/guides/issue-virtual-cards">
    Create cards inside a wallet.
  </Card>
</CardGroup>