金额与数据格式

本文主要说明 /openapi/v1 商品与订单接口。账户充值、支付网关和后台接口有不同的字段及状态协议，不能套用同一张状态表。

金额统一采用八位定点整数

当前商品与订单 API 的金额字段统一采用 10^-8 刻度，即：

显示金额 = 接口整数 / 100000000

这与币种可显示的小数位是两件事。currency_decimals 和 payment_currency_decimals 用于币种精度，不改变金额整数的缩放比例。

不能因为 USD 通常显示两位小数，就把 125000000 除以 100。

通用收款使用币种最小单位

/openapi/v1/merchant-payments 的 amount_minor 按币种精度换算：USD 10.50 提交 1050（精度 2），TDC 10.50 提交 1050000000（精度 8）。不要复用商品订单的统一八位缩放。其 status 为字符串，expires_at 和 occurred_at 为 RFC 3339 时间；列表返回 items，且必须按外部引用或单号过滤。详见 通用商户收款。

商品金额与支付金额

展示付款确认时优先使用支付币种及对应金额，避免给同一个数字贴错币种。不要跨币种相加，也不要用实时汇率改写已经生成的历史订单金额。

费率与金额不是同一刻度

固定手续费和金额封顶仍是八位定点金额。handling_fee_percent 等整数费率使用 ppm：10000 表示 1%，40000 表示 4%，不是金额的 10^8 刻度。汇率乘数（例如 tdc_per_unit）则是十进制字符串，不要当作 nano 整数。

渠道的比例手续费以“金额 + 固定手续费”为基数，封顶只限制比例部分。例如充值 10 USD、固定费 4 USD、比例 4%，比例部分为 0.56 USD，合计手续费 4.56 USD。前端百分比输入显示的是 4%，接口存储为 40000；应优先使用服务端报价结果。

JavaScript 精度

接口中的金额是 JSON 整数。超过 JavaScript 安全整数范围时，普通 JSON.parse 可能已经丢失精度，此后再转为 BigInt 也无法恢复。

接入时使用保留大整数的 JSON 解析方案，金额运算使用整数或十进制定点库。普通 Number 仅能用于已经确认在安全范围内的值。相关限制见 MDN 安全整数说明 。

两种状态不要混用

而 GET /openapi/v1/orders/{order_no}/payment 的 status 是支付查询结果：

支付查询返回 1 时，若要判断交付是否完成，还要读取订单详情。

账户充值的网关查询是另一种协议：status 为 1000（UnPaid）、1001（Paid）、1002（Complete）、1003（Expired），同时返回 status_label。充值历史记录又使用 pay_status，不能把它们映射成上面的 OpenAPI 0/1/2。这些账户接口需要平台登录态，不属于第三方 OAuth OpenAPI。

成功响应与错误响应

OpenAPI 成功响应直接返回资源或列表，没有统一的 data 包裹。OAuth 错误包含字符串 error 与 error_description；交易参数或业务错误可能使用数字 code、文本 error 和可选 error_description。先检查 HTTP 状态和实际响应结构，不要假设所有接口都有同一种业务错误码。

编号、分页与时间

• 商品号、订单号、客户端号均按字符串保存，不转成数字。
• 商品列表使用 list、total、page、limit；默认页码 1、每页 20，合法 limit 为 1–100，超出范围当前回退到 20。
• 支付创建响应的 expire_time 是 Unix 秒时间戳；OAuth 的 expires_in 是从签发开始计算的有效秒数，两者不能互换。
• 订单日期字段使用 YYYY-MM-DD HH:mm:ss 或 null，不携带时区；展示空值时不要自动变成 1970 年，也不要擅自附加 UTC 时区。充值历史的 expire_time 也是日期字符串，与支付创建响应中同名的 Unix 秒字段不同。