Global Accounts API

Version: v1.0 (2026-09-29) · Base URL: https://api.stablepay.co · Prefix: /api/v1 · HTTPS / JSON / UTF-8

Overview and Scope

The Global Accounts API manages a merchant’s multi-currency accounts and account-level money movement: account and balance queries, stablecoin deposits and withdrawals, same-merchant account transfers, recipient management, and event delivery by webhook across these resources. Every path is prefixed with /api/v1. The merchant is determined by the credentials: merchant apps omit merchant_id, while service-provider apps use it to target a merchant.

Method	Path	Purpose
GET	`/account`	List all accounts and balances for the target merchant
GET	`/account/{account_no}`	Retrieve one account and balance
GET	`/pending_settlement_balance`	Pending settlement balances by currency
GET	`/fund/deposit_address`	Retrieve a stablecoin deposit address
GET	`/fund/deposits`	List stablecoin deposit records
GET	`/fund/deposits/{deposit_id}`	Retrieve one stablecoin deposit
POST	`/fund/deposits/{deposit_id}/confirm`	Add Travel Rule funding source details
POST	`/fund/withdrawals`	Create a withdrawal
GET	`/fund/withdrawals/{withdrawal_id}`	Retrieve a withdrawal
POST	`/fund/account_transfers`	Create an account transfer
GET	`/fund/account_transfers/{account_transfer_id}`	Retrieve an account transfer
GET	`/recipient/requirements`	Retrieve recipient field rules
POST	`/recipient`	Create a recipient
GET	`/recipient`	List recipients
GET	`/recipient/{recipient_id}`	Retrieve a recipient
PUT	`/recipient/{recipient_id}`	Update a recipient
DELETE	`/recipient/{recipient_id}`	Delete a recipient

Account query endpoints use 8-digit account numbers and return lists as object with data; other endpoints use 10-digit resource IDs. Every account-related parameter uses the 8-digit account_no.

Authentication and Signing

Every request carries an API Key plus the three signing headers, following the common StablePay authentication specification.

Header	Required	Description
Authorization	Yes	Bearer `{api_key}`
`X-StablePay-Timestamp`	Yes	Unix seconds; within 5 minutes of server time
`X-StablePay-Nonce`	Yes	Anti-replay random string, 16 to 64 characters, unique per request
`X-StablePay-Signature`	Yes	HMAC-SHA256 signature, lowercase hex

The signing payload is {timestamp}.{nonce}.{requestBody}. GET and DELETE have no body, so {requestBody} is an empty string and the payload ends with a dot; POST and PUT sign the exact raw JSON string that is sent, so never reformat or reorder fields after signing. See Pre-integration Preparation for the full algorithm and multi-language samples. Credentials belong to an app. A merchant app maps to a single merchant and omits merchant_id; a service-provider app serves multiple merchants after authorization and passes merchant_id in the query or body of account and balance queries, fund, and recipient endpoints to target a merchant. An unauthorized or inaccessible merchant returns 403 permission_denied. Keep the signing secret on the server, and always regenerate the timestamp and nonce when retrying.

Data Conventions

Item	Convention	Example
Resource IDs	`xxx_id` values are 10-digit strings: `merchant_id`, `deposit_id`, `withdrawal_id`, `account_transfer_id`, `recipient_id`, `event_id`, `request_id`	”9000000070”
Account number	`account_no`. Account query endpoints return an 8-digit string; fund endpoint examples use the 00000001 form. Always use the value actually returned and never validate against a fixed pattern	”00000001”, “00000001”
Amount	Integer in the smallest unit of the currency; fiat and USDT/USDC all use 2 decimals	1050 means 10.50 USD; 125000 means 1,250.00 USDC
Currency	Uppercase; ISO 4217 for fiat, asset code for stablecoins	USD, SGD, USDT, USDC
Network	ethereum, tron, solana, base, polygon, arbitrum, bsc	solana
Time	Unix seconds as an integer	1718726400
Ratios	Ratios are decimal strings, never floats	”0.9998”
Empty fields	Optional fields that do not apply are omitted	—

List endpoints use cursor pagination: limit defaults to 20 and caps at 100, the response returns next_cursor, and the last page omits it. The account query endpoints are the exception: the account list returns every account at once with no pagination or filters. Create endpoints support two idempotency mechanisms: the Idempotency-Key header, and the external_xxx_id body field, which together with merchant_id forms a per-merchant unique key. Reusing a key with different parameters returns 409 idempotency_conflict; reuse the same identifier when retrying after a timeout.

Events

Events record state changes across all merchant resources and are delivered to the merchant webhook endpoint. The event query endpoints are not publicly available; rely on webhook payloads together with reconciliation queries.

Event Types

Event	Description
account.updated	Account information changed
balance.updated	Available or frozen balance changed
deposit.completed	Stablecoin deposit credited; data is the deposit record
withdrawal.processing / `payment_submitted` / completed / `bounced_back`	Withdrawal lifecycle
`account_transfer.completed`	Account transfer completed

Webhook requests carry X-StablePay-Event-Type and X-StablePay-Event-ID. Failed deliveries retry up to 10 times with exponential backoff starting at 2 minutes and capping at 1024 minutes. The same event may be delivered more than once, so deduplicate by X-StablePay-Event-ID and confirm final state with balance and record queries. See Webhook Notifications for details.

Balance Semantics and Data Consistency

Field	Meaning	Directly usable	Notes
`available_amount`	Available: posted and not reserved	Yes	Usable for conversion, transfers, and withdrawals
`frozen_amount`	Frozen: reserved by in-flight operations or risk controls	No	Becomes available when released
`total_amount`	Total account balance	No	Equals `available_amount` + `frozen_amount`

The as_of returned by balance endpoints is the database observation time of that request, not a data version, and consecutive requests are not guaranteed to share a snapshot. Balances changing between requests is expected; the ledger is authoritative. A transfer status of completed means the business operation finished, not that the balance posted immediately. Write endpoints are protected by Idempotency-Key and external_xxx_id.

Errors and Status Codes

Errors use a shared envelope: an error object (type, code, message, param), plus request_id and timestamp. Include request_id when reporting an issue. Example error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The amount must be greater than zero.",
    "param": "amount"
  },
  "request_id": "9000000099",
  "timestamp": 1718726400
}

Status	Code	Meaning
400	`invalid_parameter`	Missing or invalid parameter, such as a zero amount or an unsupported currency or network
401	`invalid_api_key`	API key missing, invalid, or revoked, or signature verification failed
403	`permission_denied`	The merchant has not authorized this app, or the app cannot access the target merchant
404	`resource_not_found`	The resource does not exist or belongs to another merchant
409	conflict	Business state conflict: `idempotency_conflict` and `insufficient_funds`
429	`rate_limit_exceeded`	Rate limit exceeded; back off and retry
500	`internal_error`	Platform internal error; contact support with `request_id`
503	—	Balance query service temporarily unavailable; retry with a new timestamp, nonce, and signature

error.type is one of api_error, invalid_request_error, authentication_error, permission_error, resource_not_found, conflict, or rate_limit_error. param is returned only when a specific parameter can be identified. Always regenerate the timestamp and nonce on retry, and never blindly retry a 401.

Handling Error Codes

Code	Retry	Recommended action
`invalid_parameter`	No	Fix the parameter named in param and resubmit; do not replay unchanged
`invalid_api_key`	No	Check the key, the trailing dot in the signing payload, and server clock skew
`permission_denied`	No	Service-provider apps should confirm `merchant_id` is within the authorized scope
`resource_not_found`	No	Verify the resource ID and merchant ownership, and that it was not deleted
`idempotency_conflict`	No	Same key with different parameters: reuse the original payload or use a new key
`insufficient_funds`	No	Check `available_amount`, then adjust the amount or top up
`rate_limit_exceeded`	Yes	Back off exponentially and reduce concurrency
`internal_error` / 503	Yes	Retry with a new timestamp, nonce, and signature; if it persists, report with `request_id`

When retrying a write request, keep the same idempotency identifier (Idempotency-Key or external_xxx_id) and regenerate the timestamp and nonce so one operation is never executed twice.

Version and Change Log

Version	Change
2026-09-29	First public version: account and balance queries, stablecoin deposits and withdrawals, account transfers, and recipients — 17 endpoints. Events are delivered by webhook; no event query endpoints are provided.

API Boundaries

Account opening, renaming, and merchant administration happen in the merchant dashboard, not through this API.
The API returns only the current merchant’s own accounts and transaction data; cross-merchant queries are not available.
Cross-merchant fund movements and platform account collection are provided by the Payouts product.
KYB and KYC submission and review status are not handled by this API.

全球账户

稳定币兑换

稳定币收单

稳定币付款

企业卡

退款

参考

Overview and Scope

Authentication and Signing

Data Conventions

Events

Event Types

Balance Semantics and Data Consistency

Errors and Status Codes

Handling Error Codes

Version and Change Log

API Boundaries

​Overview and Scope

​Authentication and Signing

​Data Conventions

​Events

​Event Types

​Balance Semantics and Data Consistency

​Errors and Status Codes

​Handling Error Codes

​Version and Change Log

​API Boundaries

​Related Documentation

Overview and Scope

Authentication and Signing

Data Conventions

Events

Event Types

Balance Semantics and Data Consistency

Errors and Status Codes

Handling Error Codes

Version and Change Log

API Boundaries

Related Documentation