Skip to content

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 amount of 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 currency default to USD, and available recharge channels are subject to actual server configuration.
  • Times are Unix millisecond timestamps.
  • Pagination defaults: pageNo 1, pageSize 10 (max 1000); the success response structure is {"code":0,"data":...,"msg":""}, and paginated data is {"list":[],"total":0}.
  • Record and task queries use the current time when endTime is omitted and 30 days before endTime when beginTime is omitted; the time range must not be reversed and must not exceed 90 days.
  • Do not use the signature X-Nonce as 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, and region in auto-renewal lists are returned translated according to Accept-Language.

API Rules ​

All API requests must include the following authentication fields in the HTTP Header. See API Rules for details.

Header FieldRequiredDescription
X-Access-KeyYesAPI access key ID, used to identify the caller
X-SignatureYesSignature value, Base64-encoded HMAC-SHA256 result
X-TimestampYesMillisecond-level Unix timestamp (13 digits), used for replay attack prevention
X-NonceYesRandom string, 10~32 lowercase letters and digits, unique per request

API List ​

APIDescription
Get Wallet BalanceQuery balance and cumulative amounts by currency
Create RechargeCreate a wallet recharge order
Get Recharge StatusQuery the credited status of a recharge order
Recharge Record PagePaginated query of recharge records
Transaction Record PagePaginated query of all fund records
Auto-Renew Policy PagePaginated query of auto-renewal policies
Set Auto-Renew SwitchTurn an auto-renewal policy on or off
Auto-Renew Task PagePaginated query of auto-renewal tasks

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).

APIDescription
Place OrderWallet recharge order (productCode=WALLET_RECHARGE); regular product orders with pure wallet/mixed payment
Order PaymentPay an existing unfinished order with the wallet (payCode=WALLET)
Cloud Phone Renewal Price CalculationCalculate the price before renewal
Cloud Phone Renewal Order CreationCloud phone renewal, supports wallet and mixed payment
Cloud Disk Renewal Order CreationCloud disk renewal, supports wallet and mixed payment
Static IP Renewal Order CreationStatic IP renewal, supports wallet and mixed payment
Payment Order PageFilter wallet recharge orders by productType=7
Cancel OrderCancel 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.

Copyright © 2026 HongKong Quantity Best Technology Limited

QTPhone Help Center