Use Cases
- Keep cross-border receipts in multi-currency accounts and convert or pay out only when you need to.
- Display usable balances to your own systems, whether for your business or your end customers.
- Reconcile available balance separately from unsettled funds, so in-flight money is never treated as withdrawable.
- Isolate funds per business line or per store using separate accounts.
- Give finance a per-currency view of where the money sits for treasury planning and reporting.
Account Model
An account is identified byaccount_no, an 8-digit string. Leading zeros are significant (for example 00000001), so never store or compare it as an integer. A system default settlement account is created automatically with is_system_default set to true; accounts a merchant opens later return false. editable reports whether the merchant may rename the account, and the current query endpoints do not offer a rename operation.
Account status has two values: active for normal and restricted for restricted. Restricted accounts can still be queried; whether fund operations are allowed is decided by the relevant business endpoint, not by refusing the query.
Accounts belong to the merchant associated with the credentials, so accounts are isolated across merchants by construction. A merchant app is inherently scoped to its own merchant; a service-provider app may pass merchant_id in a query to target an authorized merchant, and an unauthorized or inaccessible merchant returns 403 permission_denied.
Balance Semantics
Each account returns three amounts, all integers in the smallest ledger unit of the currency:
Account balances contain only available and frozen amounts; money attributed to the merchant but not yet posted is not part of an account balance, so use pending settlement balances instead of treating the account balance as the whole picture.
Precision is 2 decimals for fiat and stablecoins alike (1050 means 10.50 USD); USDT and USDC use the same (125000 means 1,250.00 USDC). Convert display values by dividing by 100, never by 1,000,000.
Pending Settlement Balances
Pending settlement balance is a single merchant-level figure aggregated by currency. It is unrelated to individual accounts and never returns anaccount_no. It represents the book net amount attributed to the merchant on pending settlement accounts and may be negative; a negative value reflects the direction of the net position, so clients should display it as-is rather than clamping it to zero or treating it as an error.
This figure is neither an available balance nor a withdrawable balance, and it must never be added to an account’s total_amount. The figure aggregates total balances of pending settlement accounts, including frozen amounts, so it must not be read as “postable settlement amount after deducting frozen funds”. Currencies with no pending records are omitted, and an all-zero result is returned as an empty array.
How Money Moves In and Out
Global Accounts is the ledger view; the actual money movements are performed by the corresponding business endpoints. The table below lists each funding path together with the query and notification surfaces a merchant can use.
Every capability in this table is available through the corresponding endpoints and events; see the Global Accounts API documentation for field-level definitions. Conversion operations (fiat to stablecoin, stablecoin to fiat, and stablecoin swaps) belong to the Stablecoin Exchange product, described in the Stablecoin Exchange product and API documentation. Contact your customer success team to confirm which endpoints and currencies are enabled for your account.
Data Consistency and Reconciliation
Theas_of returned with a balance query is the database observation time for that request. It is not a data version, and consecutive requests are not guaranteed to observe the same snapshot. Balances changing between two requests is expected; the ledger is authoritative, so never compare as_of values to decide which response is newer.
A reliable reconciliation pattern is to read account balances and their as_of first, then pull the events or funding records for the same time window, and only then confirm any differences. Event deliveries may be duplicated, so deduplicate by event ID; gaps between retries can be filled by reconciling balances and funding records. See Webhook Notifications for the delivery contract.
Recommended sequence: on each webhook, deduplicate by event ID and append to your own ledger, then confirm final state with GET /account/{account_no} or the corresponding record query. Run reconciliation on a fixed cadence (for example hourly) comparing balance snapshots against your ledger, and escalate only when the gap exceeds a threshold. Events trigger processing; balances and records remain authoritative.
Relationship to Other Products
Global Accounts answers where the money sits, while Checkout, QR Pay, and Payment Links answer how it comes in. Once a payment succeeds, the funds eventually appear as the balance of the corresponding currency account. Refunds go through the refund capability of the original payment product, and outbound payments go through Payouts or Global Accounts payouts. When wiring Global Accounts into a finance system, you therefore only need the mapping between accounts and currencies, not per-channel knowledge.Permissions and Security
API Keys and Secret Keys are created per store in the merchant dashboard and are store-level credentials. Calling a read-only endpoint still requires the full authentication and signature set, so a query is never exempt from signing. Keep the Secret Key on the server only and never expose it in frontend code, logs, or client storage. See Pre-integration Preparation for key creation, the signature algorithm, and the full header list. The merchant scope comes from the credentials: a merchant app is limited to its own merchant, while a service-provider app can only passmerchant_id within an authorized scope, and 403 permission_denied means the app cannot access the target merchant. A 401 usually means the key is missing, invalid, or revoked, and a 404 means the account number does not exist or does not belong to the target merchant.