Skip to main content
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

currency is always 986 (Brazilian real) and name is required. The wallet is shared with the users in shared; when you omit it, you become its only OWNER. It is created with status: "PENDING" and returns its _id (the walletId). It becomes ACTIVE once provisioned, usually within seconds — only then can it hold balances and move money.
Reference: Create a wallet

​
Read a wallet and its balances

Fetch a wallet to read its balances. The balance is split into categories; totalBalance is the sum.
Amounts are in centavos. FLEX_INTERNATIONAL is the general-purpose category used in most flows. Send includeBalances=false when you only need the wallet itself, and use default as walletId to read the organization’s main wallet. Reference: Get a wallet

​
Register a PIX key

A wallet needs a PIX key (DICT) to receive charges. Create a random key (EVP) on the wallet — send no value, the bank generates the key:
The response (201) returns the key’s _id, its value and its status: "ACTIVE". Use that value as the pixDict when creating charges or Pix Automático authorizations. Manage keys with: Manage Pix keys covers every key type, confirming a key with a code, and answering the claims other institutions open for your keys.

​
Ask the organization’s main wallet for money (transfer requests)

A transfer request moves money between a wallet and the organization’s main wallet once it is confirmed — after approval, when the organization’s business policies require it. A positive amount asks the main wallet for money; a negative one sends it back.
The answer’s policy.actions.autoAction says what to do next: APPROVE — confirm it and the money moves; NONE — send it for approval, and it is confirmed once approved; DENY — the policies refuse it. Organization admins — API clients included — can confirm a request that is still REQUESTED whatever the policies decide. If the policies can’t be evaluated at that moment, policy is { "error": "POLICY_EVALUATION_UNAVAILABLE" }: the request is still saved, and confirming it or sending it for approval evaluates them again. Before you confirm it or send it for approval, you can update the request to fill in custom fields or change the day it is for; its amount and category are fixed — to change them, cancel it and create another. Business policies and approvals explains the whole flow: how a policy decides, when to confirm and when to send for approval, and what happens once the approvers decide. Reference: Create a transfer request

​
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.
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: List a wallet’s transactions
For card-only history, use the per-card transactions endpoint described in Manage and monitor cards.
Each wallet also has PIX, TED and boleto limits per period — see Get transaction limits.

​
Next steps

Charge with PIX

Use a wallet’s PIX key to collect a payment.

Issue virtual cards

Create cards inside a wallet.