钱包管理
钱包管理模块提供余额查询、充值、资金流水查询与自动续费管理能力。钱包归属由认证身份确定,不通过请求体指定用户、团队或独立站;钱包接口要求已认证,订单类接口还要求对应的订单、购买或续费权限。
通用约定
- 金额单位统一为美分,100 美分 = 1 美元;创建充值的
amount为正整数字符串,不能使用小数。余额与流水中的 Long 金额通常序列化为字符串,请勿通过浮点数处理。 - 仅支持 USD 币种;未传
currency的余额查询与充值请求默认 USD,充值渠道受服务端实际配置限制。 - 时间为 Unix 毫秒时间戳。
- 分页
pageNo默认 1,pageSize默认 10、最大 1000;成功响应结构为{"code":0,"data":...,"msg":""},分页data为{"list":[],"total":0}。 - 流水与任务查询在未传
endTime时使用当前时间,未传beginTime时使用endTime前 30 天;时间范围不能倒置且不能超过 90 天。 - 不能以签名中的
X-Nonce作为业务幂等号;请求失败或超时时先查询原订单和流水,不要重复创建订单替代查询。 - 自动续费列表的
skuName、packageName、region按Accept-Language返回翻译。
接口规则
所有 API 请求必须在 HTTP Header 中包含以下鉴权字段,详见 接口规则。
| Header 字段 | 必填 | 说明 |
|---|---|---|
| X-Access-Key | 是 | API 访问密钥 ID,用于标识调用方 |
| X-Signature | 是 | 签名值,Base64 编码的 HMAC-SHA256 结果 |
| X-Timestamp | 是 | 毫秒级 Unix 时间戳(13 位),用于防止重放攻击 |
| X-Nonce | 是 | 随机字符串,10~32 位小写字母和数字,每次请求唯一 |
接口列表
| 接口 | 说明 |
|---|---|
| 查询钱包余额 | 查询指定币种的余额与累计收支 |
| 创建充值 | 创建钱包充值订单 |
| 查询充值状态 | 查询充值订单到账状态 |
| 充值流水分页 | 分页查询充值流水 |
| 资金流水分页 | 分页查询全部资金流水 |
| 自动续费策略分页 | 分页查询自动续费策略 |
| 设置自动续费开关 | 开启或关闭自动续费策略 |
| 自动续费任务分页 | 分页查询自动续费任务 |
钱包支付相关订单接口
钱包充值推荐通过商品下单接口以 productCode=WALLET_RECHARGE 创建;普通商品与续费订单支持纯钱包支付(payCode=WALLET、providerCode=INTERNAL)与混合支付(额外传 walletPayAmount,单位美分)。
| 接口 | 说明 |
|---|---|
| 商品下单 | 钱包充值订单(productCode=WALLET_RECHARGE);普通商品纯钱包/混合支付下单 |
| 订单支付 | 使用钱包支付已有未完成订单(payCode=WALLET) |
| 云机续费价格计算 | 续费前计算价格 |
| 云机续费订单创建 | 云机续费,支持钱包支付与混合支付 |
| 云盘续费订单创建 | 云盘续费,支持钱包支付与混合支付 |
| 静态IP续费订单创建 | 静态 IP 续费,支持钱包支付与混合支付 |
| 支付订单分页 | 按 productType=7 筛选钱包充值订单 |
| 取消订单 | 取消未完成订单,有钱包扣款时按原扣款流水返还 |
金额与认证补充
钱包金额均为整数美分:150 表示 1.50 美元,不可传 1.5、150.0 或带小数点的字符串。钱包专用充值传 "150";订单充值 amount、支付和续费 walletPayAmount 传 JSON 整数。*Yuan 为美元展示值,商品目录价格须按对应接口说明换算,不能直接作为美分请求金额。Long 响应金额可能是整数字符串。
AK/SK 认证默认开启,部署配置可能覆盖。Access Key 格式为 8–15位数字_8–15位数字;时间戳默认允许与服务端相差 300 秒。签名将包含 /papi 的 URI 路径、时间戳、nonce、Access Key 直接拼接并整体转小写,以 Secret Key 的 UTF-8 字节执行 HMAC-SHA256,再做标准 Base64;不包含 HTTP 方法、query 或 body。每次请求重新生成 nonce,可选 Accept-Language 指定翻译语言。钱包要求已认证,订单操作还要求对应业务权限。
