Wallet Management
The Wallet Management module provides balance query, recharge, fund record query, and auto-renewal management. The wallet owner is determined by the authenticated identity and is not specified in the request body; wallet APIs require authentication, and order APIs additionally require the corresponding order, purchase, or renewal permission.
Common Conventions
- Amounts are in cents, 100 cents = 1 USD; the
amountof Create Recharge is a positive integer string and must not use decimals. Long amounts in balances and records are usually serialized as strings; do not process them as floating-point numbers. - Only USD is supported; balance queries and recharge requests without
currencydefault to USD, and available recharge channels are subject to actual server configuration. - Times are Unix millisecond timestamps.
- Pagination defaults:
pageNo1,pageSize10 (max 1000); the success response structure is{"code":0,"data":...,"msg":""}, and paginateddatais{"list":[],"total":0}. - Record and task queries use the current time when
endTimeis omitted and 30 days beforeendTimewhenbeginTimeis omitted; the time range must not be reversed and must not exceed 90 days. - Do not use the signature
X-Nonceas a business idempotency key; when a request fails or times out, query the original order and records first instead of creating duplicate orders. skuName,packageName, andregionin auto-renewal lists are returned translated according toAccept-Language.
API Rules
All API requests must include the following authentication fields in the HTTP Header. See API Rules for details.
| Header Field | Required | Description |
|---|---|---|
| X-Access-Key | Yes | API access key ID, used to identify the caller |
| X-Signature | Yes | Signature value, Base64-encoded HMAC-SHA256 result |
| X-Timestamp | Yes | Millisecond-level Unix timestamp (13 digits), used for replay attack prevention |
| X-Nonce | Yes | Random string, 10~32 lowercase letters and digits, unique per request |
API List
| API | Description |
|---|---|
| Get Wallet Balance | Query balance and cumulative amounts by currency |
| Create Recharge | Create a wallet recharge order |
| Get Recharge Status | Query the credited status of a recharge order |
| Recharge Record Page | Paginated query of recharge records |
| Transaction Record Page | Paginated query of all fund records |
| Auto-Renew Policy Page | Paginated query of auto-renewal policies |
| Set Auto-Renew Switch | Turn an auto-renewal policy on or off |
| Auto-Renew Task Page | Paginated query of auto-renewal tasks |
Wallet-Related Order APIs
Wallet recharge is recommended via the Place Order API with productCode=WALLET_RECHARGE; regular product and renewal orders support pure wallet payment (payCode=WALLET, providerCode=INTERNAL) and mixed payment (additionally pass walletPayAmount in cents).
| API | Description |
|---|---|
| Place Order | Wallet recharge order (productCode=WALLET_RECHARGE); regular product orders with pure wallet/mixed payment |
| Order Payment | Pay an existing unfinished order with the wallet (payCode=WALLET) |
| Cloud Phone Renewal Price Calculation | Calculate the price before renewal |
| Cloud Phone Renewal Order Creation | Cloud phone renewal, supports wallet and mixed payment |
| Cloud Disk Renewal Order Creation | Cloud disk renewal, supports wallet and mixed payment |
| Static IP Renewal Order Creation | Static IP renewal, supports wallet and mixed payment |
| Payment Order Page | Filter wallet recharge orders by productType=7 |
| Cancel Order | Cancel an unfinished order; wallet debits are refunded per the original records |
Amount and authentication details
Wallet amounts use integer USD cents: 150 means USD 1.50. Never send 1.5, 150.0 or decimal strings. The wallet recharge endpoint requires "150"; order recharge amount and payment/renewal walletPayAmount require JSON integers. *Yuan values are display amounts in dollars; convert catalog prices according to their own endpoint documentation. Long response amounts may be integer strings.
AK/SK authentication is enabled by default and may be overridden by deployment configuration. Access Keys have the format 8–15 digits_8–15 digits; timestamps normally allow 300 seconds of clock skew. Sign the lowercase concatenation of URI path (including /papi), timestamp, nonce and Access Key, using the UTF-8 Secret Key for HMAC-SHA256 and standard Base64. HTTP method, query and body are excluded. Generate a new nonce per request; optional Accept-Language selects translated names. Wallet access requires authentication and order operations require their respective permissions.
