> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Accounts

> Manage fiat and stablecoin accounts, available and frozen balances, and pending settlement funds.

One multi-currency account set per merchant, with fiat and stablecoins visible in the same ledger.

Global Accounts is the multi-currency account system StablePay opens for every merchant. Once enabled, a merchant already has a system default settlement account and can open more accounts for different business needs. Each account carries exactly one currency: fiat uses ISO 4217 codes (USD, SGD, EUR) and stablecoins use asset codes (USDT, USDC). An account is therefore the smallest unit of "one currency plus one balance", and any cross-currency operation happens between accounts, or between an account and the outside world.

From a merchant's point of view, Global Accounts answers three questions: which currency account the money landed in, how much is usable right now, and how much is still in flight. Account balances answer the first two, pending settlement balances answer the third, and the two measures have different scopes and must never be added together.

## 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 by `account_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:

| Field | Meaning | Directly usable | Notes |
| :- | :- | :- | :- |
| `available_amount` | Available balance: posted and not reserved | Yes | Can be used for conversion, account transfers, and withdrawals |
| `frozen_amount` | Frozen balance: reserved by in-flight operations or frozen by risk controls | No | Becomes available once the hold is released |
| `total_amount` | Total account balance | No | In the current version equals `available_amount` + `frozen_amount` |

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 an `account_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.

| Capability | What the merchant sees | Queries and notifications |
| :- | :- | :- |
| Fiat collection | Local clearing account details plus an attribution code; incoming transfers are attributed automatically | Fiat deposit records, `fiat_deposit.credited` event |
| Stablecoin collection | A deposit address generated per token and network, credited after on-chain confirmation | Stablecoin deposit records, deposit.completed event |
| Payouts | Withdraw to an external wallet using a pre-created recipient, with the amount set by the merchant | Recipients, withdrawal records and withdrawal status events |
| Account transfers | Same-currency transfers between two accounts of the same merchant | Account transfer records, `account_transfer.completed` event |
| Events | Real-time pushes for all of the above | Webhook delivery (`X-StablePay-Event-Type` / `X-StablePay-Event-ID`) |

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

The `as_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 pass `merchant_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.

## FAQ

| Question | Answer |
| :- | :- |
| What is the amount unit? | The smallest ledger unit as an integer. Fiat, USDT, and USDC all use 2 decimals, so divide by 100 for display values. |
| Why is `total_amount` not the withdrawable amount? | Total includes frozen funds; only `available_amount` can be used. |
| Where do I see in-flight funds? | Account balances exclude in-flight funds; use pending settlement balances. |
| Can pending settlement balance be negative? | Yes. It reflects the direction of the net book position and must be preserved as-is, not clamped to zero. |
| Can I add pending settlement to an account balance? | No. The two have different scopes; pending settlement is an independent merchant-level aggregate unrelated to `account_no`. |
| Can `account_no` be stored as an integer? | No. It is an 8-digit string and leading zeros are significant. |
| Does the account list support pagination or filters? | No. It returns all accounts of the current merchant in one response, with no business filters. |
| Can restricted accounts still be queried? | Yes. Balances are still returned; the relevant business endpoint decides whether operations are allowed. |
| How do I get more currencies or accounts? | Account and currency enablement is configured by the platform. Contact your customer success team. |

## Related Pages

* [Global Accounts Product Documentation](https://docs.stablepayfi.ai/en/product/Global-Accounts.md)
* [Global Accounts API Documentation](https://docs.stablepayfi.ai/en/api/global-accounts/overview)
* [Stablecoin Exchange Product Documentation](https://docs.stablepayfi.ai/en/product/Stablecoin-Exchange.md)
* [Stablecoin Exchange API Documentation](https://docs.stablepayfi.ai/en/api/stablecoin-exchange/overview)
* [Pre-integration Preparation](https://docs.stablepayfi.ai/en/api/getting-started.md)
* [Webhook Notifications](https://docs.stablepayfi.ai/en/api/webhook-notifications.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.