版本 2.4.7.20261116085428 · 最新
在线支付 payments
发起在线充值:建一张待支付订单并向支付网关预下单,返回付款地址。
点击任一接口,右侧显示对应的调用示例。
支付与账户鉴权: 用户3 个接口
鉴权
请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。
X-API-Key
鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。
约定
分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。
时间一律 RFC 3339(UTC);金额单位为分。
写操作成功回 200/201/204;重复提交按资源唯一键回 409。
POST
/api/v2/payments/{provider}/orders发起在线支付
鉴权: 用户
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
amount_cents必填 | integer | 充值金额(分),1 ~ 1000000000000(单笔上限,与后端 account.MaxAmount 一致)。USDT 另有单笔上限:按汇率折出不超过 2^40 个 0.0001 USDT(约 1.09 亿 USDT),超出回 422(/amount_cents range,文案说明是 USDT 单笔上限)。 |
intent | PaymentIntent | 办理意图(在线付差额):到账入余额后由服务端按它办理(同键调购买/续费/更换/加购接口),不靠浏览器开着。下单时先按原请求体试算,试算不过原样回该错误;试算应付与币种记作报价快照,到账时价格变了、报价过期(付款晚于网关单 2 小时 / USDT 单过期时间)或办理失败都不办理,钱留余额,订单 data.intent.state=failed 并写明 code/reason,发站内信。办理结果见订单 data.intent。 |
在线支付对象
| 字段 | 类型 | 说明 |
|---|---|---|
address | string | 收款地址(TRC20)。 |
amount | string | 应付 USDT(4 位小数,含区分订单的尾数),须一分不差地转。 |
amount_cents必填 | integer | 充值金额(分),1 ~ 1000000000000(单笔上限,与后端 account.MaxAmount 一致)。USDT 另有单笔上限:按汇率折出不超过 2^40 个 0.0001 USDT(约 1.09 亿 USDT),超出回 422(/amount_cents range,文案说明是 USDT 单笔上限)。 |
chain_error | string | 本次没查成链的已知原因(仅 checked=false 时可能有);auth = 链上查询服务拒绝了平台的 API Key,需管理员处理。无此字段 = 查成了、被节流或瞬时失败。 |
checked | boolean | 本次确实查了链;false = 节流内(同租户 15 秒、同地址 5 秒)或查链失败,状态照旧。 |
created_at | string | 下单时间;与 expires_at 一起给出订单完整有效期,供进度条按总时长算。 |
credited_order_id | integer | 到账转人工补入后另生成的已付款充值单 ID(仅人工补入才有);有值时实际入账金额以余额明细为准,可能与下单金额不同。 |
currency | string | 账户币种。 |
expires_at | string | 有效期截止;过期后到账不自动入账,进到账表待管理员处理。 |
gateway | string | 实际下单的支付网关。 |
intent | PaymentIntent | 办理意图(在线付差额):到账入余额后由服务端按它办理(同键调购买/续费/更换/加购接口),不靠浏览器开着。下单时先按原请求体试算,试算不过原样回该错误;试算应付与币种记作报价快照,到账时价格变了、报价过期(付款晚于网关单 2 小时 / USDT 单过期时间)或办理失败都不办理,钱留余额,订单 data.intent.state=failed 并写明 code/reason,发站内信。办理结果见订单 data.intent。 |
mch_order_no | string | 充值单号。 |
order_id | integer | 充值单 ID。 |
pay_url | string | 付款地址:跳转网址,或微信 weixin:// 与支付宝当面付的二维码串;USDT 为 tron:<收款地址>。 |
rate | string | 下单锁定的汇率:1 USDT = rate 账户币种。 |
server_time | string | 服务器当前时间;前端按它与浏览器时钟的偏移算倒计时与过期态,不信浏览器时钟。 |
status | string | unpaid = 等待转账;paid = 已到账入余额;expired = 已过期。 |
txid | string | 入账的链上交易号(已付款才有)。 |
usdt | UsdtPay | USDT 订单的收款要素。 |
返回与错误
成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。
成功
{
"id": 1,
"name": "example"
}列表
{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}失败
{
"code": "validation_failed",
"detail": "请求参数不合法",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name 必填"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}