Wallets for your customers

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

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.

{
  "_id": "6981f701fac3b778cf808272",
  "currency": "986",
  "status": "PENDING",
  "role": "CHECKING"
}

Reference: POST .../accounts/{accountId}/wallets

Read a wallet and its balances

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

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

{
  "_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}

Register a PIX key

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

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
Remove a key — POST .../pix-dict/{pixDictId}/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.

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

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.

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

For card-only history, use the per-card transactions endpoint described in Manage and monitor cards.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Wallets for your customers

Create a wallet

Read a wallet and its balances

Register a PIX key

Move money between wallets (P2P)

Read transactions

Next steps

Charge with PIX

Issue virtual cards

​Create a wallet

​Read a wallet and its balances

​Register a PIX key

​Move money between wallets (P2P)

​Read transactions

​Next steps

Charge with PIX

Issue virtual cards

Create a wallet

Read a wallet and its balances

Register a PIX key

Move money between wallets (P2P)

Read transactions

Next steps