A wallet is a prepaid credit balance associated with a customer. Wallets allow customers to pre-fund their account, receive credits (promotional or otherwise), and have charges automatically deducted from their balance before falling back to a payment method.
Each customer has a primary wallet created automatically, and can have additional wallets in different currencies.
Key operations:
- Credit - add funds to the wallet (from a payment, promotion, or manual adjustment)
- Debit - remove funds (applied automatically during invoicing, or manually)
- Hold - reserve an amount for a pending charge (released or captured later)
- Transfer - move funds between wallets (e.g., currency conversion)
- Adjust - correct the balance without a formal credit/debit (e.g., migration adjustment)
List wallets
Returns wallets for the org, newest first, cursor-paginated. All filters AND together; multi-value currency is OR within itself. Pass customer_id to scope to one customer; omit to browse org-wide.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
customer_idFilter by customer UUID
Filter by customer UUID
currencyFilter by ISO 4217 currency code (repeatable or comma-separated; OR within itself)
Filter by ISO 4217 currency code (repeatable or comma-separated; OR within itself)
is_primarytrue=only primary wallets, false=only secondary; omit for both
true=only primary wallets, false=only secondary; omit for both
auto_topup_enabledFilter by auto-topup state
Filter by auto-topup state
created_afterFilter by created_at >= timestamp (RFC3339)
Filter by created_at >= timestamp (RFC3339)
created_beforeFilter by created_at < timestamp (RFC3339)
Filter by created_at < timestamp (RFC3339)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List wallets › Responses
OK
Create a wallet
Creates a secondary wallet for the specified customer.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a wallet › Request Body
auto_topup_amount^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
auto_topup_enabledWhether the wallet auto-tops-up when its balance drops below low_balance_threshold.
credit_limit^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
currencyISO 4217 currency the wallet is denominated in.
customer_idCustomer the new wallet belongs to.
low_balance_threshold^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
max_balance^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
max_single_credit^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
Create a wallet › Responses
Created
Get a wallet by ID
Returns a single wallet including its current cash, promotional and held balances, currency, and limit settings.
path Parameters
idWallet UUID
Wallet UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a wallet by ID › Responses
OK
Adjust a wallet balance
Applies an adjustment to a wallet balance (positive or negative).
path Parameters
idWallet UUID
Wallet UUID
Headers
Idempotency-KeyIdempotency key for at-most-once processing
Idempotency key for at-most-once processing
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Adjust a wallet balance › Request Body
amount^-?\d+(\.\d+)?$Signed adjustment, MAJOR units, in the addressed wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
reasonOptional free-text explanation stored on the ledger entry.
referenceOptional external reference; a repeated (source, reference) is treated as an idempotent replay.
sourceWhat originates the adjustment: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
Adjust a wallet balance › Responses
OK
Credit a wallet
Adds funds to a wallet, creating a credit transaction.
path Parameters
idWallet UUID
Wallet UUID
Headers
Idempotency-KeyIdempotency key for at-most-once processing
Idempotency key for at-most-once processing
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Credit a wallet › Request Body
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
expires_atFor PROMOTION credits, when the granted promotional balance expires; null = never.
reasonOptional free-text explanation stored on the ledger entry.
referenceOptional external reference; a repeated (source, reference) is treated as an idempotent replay.
sourceWhat originates the credit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
Credit a wallet › Responses
OK
Debit a wallet
Withdraws funds from a wallet, creating a debit transaction.
path Parameters
idWallet UUID
Wallet UUID
Headers
Idempotency-KeyIdempotency key for at-most-once processing
Idempotency key for at-most-once processing
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Debit a wallet › Request Body
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
reasonOptional free-text explanation stored on the ledger entry.
referenceOptional external reference; a repeated (source, reference) is treated as an idempotent replay.
sourceWhat originates the debit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
Debit a wallet › Responses
OK
List wallet holds
Lists pending holds for a wallet.
path Parameters
idWallet UUID
Wallet UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List wallet holds › Responses
OK
Create a wallet hold
Places a hold on wallet funds, reserving the amount for later capture.
path Parameters
idWallet UUID
Wallet UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a wallet hold › Request Body
amount^-?\d+(\.\d+)?$MAJOR units, in the hold's currency (the currency field, else the wallet's).
currencyISO 4217 currency of the hold; when empty the addressed wallet's currency is used.
expires_atWhen the wallet auto-releases the hold if it has not been captured.
metric_keyMetric key of the usage stream this hold reserves capacity for; set by the reserve service, null via the public hold API.
Promotions that reduced this hold's amount up-front; set by the reserve service, never via the public hold API.
reasonFree-text explanation of what the hold reserves for.
reference_idIdentifier of the record this hold reserves against; paired with reference_type.
reference_typeType of the record this hold reserves against; paired with reference_id.
reverse_chargeTrue when the captured amount is subject to VAT reverse-charge.
subscription_idSubscription whose usage stream this hold reserves capacity for; set by the reserve service, null via the public hold API.
tax_rate^-?\d+(\.\d+)?$Tax rate to apply at capture, as a decimal fraction (0.19 = 19%).
tax_rule_idTax rule to apply when this hold is captured; null for an untaxed hold.
Create a wallet hold › Responses
Created
Update wallet settings
Updates wallet limit and settings fields.
path Parameters
idWallet UUID
Wallet UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update wallet settings › Request Body
auto_topup_amount^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
auto_topup_enabledWhether the wallet auto-tops-up when it drops below low_balance_threshold.
auto_topup_payment_method_idPayment method charged for auto-topups.
credit_limit^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
low_balance_threshold^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
max_balance^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
max_single_credit^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
Update wallet settings › Responses
OK
Admin-side wallet top-up
Tops up a customer's wallet via a Stripe charge. Accepts mode=hosted_checkout (returns a Stripe Checkout URL) or mode=off_session (charges a saved card synchronously). The wallet is credited asynchronously when Stripe reports the payment succeeded.
path Parameters
idWallet UUID
Wallet UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Admin-side wallet top-up › Request Body
modehosted_checkout (default) or off_session
payment_method_idRequired for mode=off_session
Admin-side wallet top-up › Responses
Created
List wallet transactions
Lists transactions for a wallet with cursor-based pagination.
path Parameters
idWallet UUID
Wallet UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List wallet transactions › Responses
OK
Transfer funds between wallets
Moves funds from the path wallet (source) into the body's target_wallet_id atomically: one database transaction locks both wallets and records a debit transaction on the source and a credit transaction on the target, linked by a shared transfer_id. amount is in the source wallet's currency and is drawn from promotional balance first; cross-currency transfers convert through the org's FX rate (the snapshot used is returned) and fail when no rate is configured. Transfers to the same wallet are rejected, and replaying an Idempotency-Key yields an already-processed conflict rather than a second transfer.
path Parameters
idSource wallet UUID
Source wallet UUID
Headers
Idempotency-KeyIdempotency key for at-most-once processing
Idempotency key for at-most-once processing
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Transfer funds between wallets › Request Body
Transfer amount as {value, currency}. currency must equal the SOURCE (path) wallet's currency; the target leg converts via the org's FX rate when currencies differ.
reasonOptional free-text explanation stored on both ledger legs of the transfer.
target_wallet_idWallet that receives the transfer; must belong to the same organization as the source wallet.
Transfer funds between wallets › Responses
OK