Skip to main content
GET
Get a wallet
The balances are read live, per category, in cents. Send includeBalances=false to skip that read when you only need the wallet itself: totalBalance is then 0 and balances is empty. Use default as walletId to read the organization’s main wallet. A wallet of another environment answers 404, so send x-environment: LIVE for production wallets. Organization admins can read every wallet; other users only the wallets shared with them, in any role.

Headers

x-environment
enum<string>

Environment of the wallet: LIVE (production) or TEST (sandbox). When you omit it, the request runs in TEST; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization the wallet belongs to.

Format: UUID

accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
walletId
string
required

ID of the wallet (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

Query Parameters

includeBalances
enum<string>

false returns the wallet without reading its balance, which is faster: totalBalance is 0 and balances is empty.

Available options:
true,
false

Response

Successful response

A wallet, with its balances.

_id
string
required

ID of the wallet.

Example:

"66f2a3d1b4d3e80012c9a0d2"

realmId
string<uuid>
required

ID of the realm the wallet belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string<uuid>
required

ID of the organization the wallet belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId
string
required

ID of the account the wallet belongs to.

Example:

"66f2a1c7b4d3e80012c9a0b4"

environment
enum<string>
required

Environment the wallet lives in: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

currency
string
required

Currency of the wallet, as an ISO 4217 numeric code. Always 986 (Brazilian real).

Example:

"986"

status
enum<string>
required

Status of the wallet: PENDING (being created — it can't move money yet), ACTIVE, BLOCKED (it can't move money until it is unblocked), CANCELLING or CANCELLED (closed), REPROVED (its creation was refused), FRAUD_ANALYSIS (on hold while suspected fraud is analyzed) or FRAUD_CONFIRMED (closed for fraud).

Available options:
PENDING,
ACTIVE,
CANCELLING,
CANCELLED,
BLOCKED,
REPROVED,
FRAUD_ANALYSIS,
FRAUD_CONFIRMED
Example:

"ACTIVE"

role
string
required

Role of the wallet in the account: DEFAULT for the organization's main wallet — the one that funds and receives the other wallets' transfers — and CHECKING for every other wallet. A few older wallets carry another value.

Example:

"CHECKING"

type
enum<string>
required

Kind of wallet: ORGANIZATION (the organization's main wallet), SHARED (used by a team), PERSONAL (a single user's) or VEHICLE (a vehicle's, for its fuel and other purchases).

Available options:
PERSONAL,
SHARED,
ORGANIZATION,
VEHICLE
Example:

"SHARED"

shared
object[]
required

Users who can use the wallet, and how. Organization admins can use every wallet.

isSuper
boolean
required

Whether the wallet's cards are on the premium card product.

Example:

false

createdAt
string<date-time>
required

When the wallet was created.

Example:

"2024-10-01T12:30:05.000Z"

updatedAt
string<date-time>
required

When the wallet last changed.

Example:

"2024-10-01T12:34:41.000Z"

totalBalance
number
required

Total balance of the wallet across all of its categories — BLOCKED and CASHBACK included — in cents. 0 while the wallet is being created.

Example:

1250000

balances
object[]
required

Balance per category. Empty while the wallet is being created.

external
object

The wallet's bank account. Absent on a few wallets created before it was recorded.

customFields
object

Values of the organization's wallet custom fields, keyed by each field's slug. Absent when the wallet has none.


Example: {"cost-center":"CC-1020"}

Example:
name
string | null

Name of the wallet. Absent on older wallets created without one.

Example:

"Marketing"

settings
object

Settings of the wallet. Absent on older wallets created without them.

walletProduct
string

Card product of the wallet, inherited from the account. Absent on older wallets.

Example:

"NORMAL"

createdBy
string<uuid> | null

ID of the user who created the wallet. Absent, or null, on older wallets.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

updatedBy
string<uuid> | null

ID of the user who created the wallet; editing it doesn't change this field. Absent, or null, on older wallets.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

accountType
enum<string>

Type of the wallet's bank account, on older wallets only: the same as external.accountType.

Available options:
PREPAID,
CCLG
Example:

"PREPAID"

__v
number

Internal revision counter of the wallet.

Example:

0