星途 · API 对接文档

0. 快速开始

1. 在码池后台「支付通道 → 下游应用（商户）」创建应用，拿到 API 编号（apiNo）、AppID、密钥（secret，只显示一次）；
2. 调用 POST /v1/pay/unified 下单，得到 payUrl；
3. 让用户打开 payUrl（收银台页面），填写姓名后提交（页面会调用 POST /v1/cashier/{tradeNo}/intent）；
4. 轮询 GET /v1/cashier/{tradeNo} 或 GET /v1/pay/qr/status，直到 status=SUCCESS；
5. 码池向你的 notifyUrl 发送异步回调，验签后返回纯文本 success。

1. 通用约定

1.1 请求方式与编码

⚠️ 所有 POST 接口只接受 JSON。用表单提交会返回 {"code":"5001","msg":"内部错误：Content-Type 'application/x-www-form-urlencoded' is not supported"}， 这是最常见的 415 类失败原因。

1.2 统一返回结构

{ "code": "0", "msg": "SUCCESS", "data": { } }

业务错误统一 HTTP 200，必须判断 code，不能只看 HTTP 状态码。

2. 鉴权与签名

2.1 凭证

2.2 签名算法（下单）

1. 取参与签名的字段：amount、appId、outTradeNo、payType；
2. 按 key 的 ASCII 升序排列；
3. 拼成 k1=v1&k2=v2&...（剔除空值）；
4. 末尾追加 &key=<secret>；
5. 对整串做 HMAC-SHA256，密钥为 <secret>；
6. 输出小写十六进制，放入请求字段 sign。

示例（金额 1.23 元）：

待签串：amount=123&appId=SF4F001&outTradeNo=ORD20261110001&payType=wechat&key=<secret>
sign  ：HMAC-SHA256(待签串, <secret>) 的小写十六进制

sign、sign_type 不参与签名；请求里不需要传 sign_type。

Python 示例

import hmac, hashlib

def sign(app_id, out_trade_no, pay_type, amount_fen, secret):
    raw = f"amount={amount_fen}&appId={app_id}&outTradeNo={out_trade_no}&payType={pay_type}"
    return hmac.new(secret.encode(), (raw + "&key=" + secret).encode(), hashlib.sha256).hexdigest()

PHP 示例

$raw  = "amount={$amount}&appId={$appId}&outTradeNo={$outTradeNo}&payType={$payType}";
$sign = hash_hmac('sha256', $raw . '&key=' . $secret, $secret);

2.3 回调验签

与下单同一套算法，参与字段为回调中的： appId、outTradeNo、tradeNo、amount、realAmount、tradeStatus、payTime （剔除 sign、sign_type 和空值，按 key 升序 + &key=<secret>，HMAC-SHA256 小写）。

3. 接口总览

4. 统一下单

POST /v1/pay/unified

4.1 请求参数

4.2 成功响应

{
  "code": "0",
  "msg": "SUCCESS",
  "data": {
    "tradeNo": "P20261110222708557265353",
    "status": "WAITING",
    "amount": 123,
    "payUrl": "https://www.hjdgawjkdn.top/cashier/P20261110222708557265353",
    "expireAt": "2026-11-10 22:57:08"
  }
}

4.3 幂等响应

同一 appId + outTradeNo 且金额一致重复请求时，返回原单（不会新建）：

{
  "code": "0",
  "data": {
    "tradeNo": "P20261110222708557265353",
    "status": "PAYING",
    "amount": 123,
    "payUrl": "https://www.hjdgawjkdn.top/cashier/P20261110222708557265353",
    "expireAt": "2026-11-10 22:30:09",
    "idempotent": true
  }
}

• 幂等命中时即使原单已支付/已关闭也返回原单，不会重新下单；
• 需要新订单请更换 outTradeNo；
• 并发重复请求由唯一键兜底，行为一致。

4.4 常见错误

单笔区间、每分钟限流均可在后台「系统设置 → 支付参数」调整。

5. 收银台信息（轮询）

GET /v1/cashier/{tradeNo}

无需签名，凭 tradeNo 查询，用于收银台页面与商户轮询。

5.1 响应字段

5.2 示例（已派发）

{
  "code": "0",
  "data": {
    "tradeNo": "P20261110222708557265353",
    "amountFen": 123,
    "realAmountFen": 123,
    "status": "PAYING",
    "confirmState": "WAIT_CONFIRM",
    "orderState": "PAYING",
    "queued": false,
    "dead": false,
    "qrCode": "DEMO-QR-MC0001",
    "payerName": "样例用户",
    "expireAt": "2026-11-10 22:30:09",
    "expireInSeconds": 177,
    "channelCode": "wechat"
  }
}

5.3 轮询建议

收银台页面另提供 SSE：GET /v1/cashier/{tradeNo}/events（可选用）。

6. 填名出码（intent）

POST /v1/cashier/{tradeNo}/intent

把付款人姓名写入订单、进入派单队列；派单是异步的，接口立即返回 queued=true，随后轮询 §5 获取二维码。

6.1 请求

{
  "payerName": "张三",
  "payerAccount": "zhangsan",
  "methodCode": "WECHAT_QR"
}

payerName 是 UTF-8 字符串，按字符数限制 32（不是字节数）。 中文名可以直接传，不需要 URL 编码（JSON 请求体）。

6.2 响应

{
  "code": "0",
  "data": {
    "tradeNo": "P20261110222708557265353",
    "status": "WAITING",
    "queued": true,
    "orderState": "PENDING",
    "payerName": "样例用户",
    "expireInSeconds": 179,
    "qrCode": null
  }
}

• 已派发/已支付时重复调用是幂等的：直接返回当前视图（status=PAYING/SUCCESS，可能带 qrCode），不重复入队；
• 订单已关闭/不存在时返回 4001/4002。

6.3 错误

必须用 JSON。表单提交返回： {"code":"5001","msg":"内部错误：Content-Type 'application/x-www-form-urlencoded' is not supported"}

7. 派发说明（异步）

8. 查单

GET /v1/pay/qr/status?tradeNo=P2026... 或 GET /v1/pay/qr/status?outTradeNo=ORD...&appId=SF4F001

{
  "code": "0",
  "data": {
    "tradeNo": "P20261110222708557265353",
    "status": "PAYING",
    "realAmount": 123,
    "payTime": null
  }
}

错误：1002（两个单号都没传）、4001（查无订单）。

9. 订单详情

GET /v1/pay/query?tradeNo=P2026...

返回完整订单对象（节选）：

{
  "code": "0",
  "data": {
    "tradeNo": "P20261110222708557265353",
    "outTradeNo": "SMP1794320828",
    "appId": "SF4F001",
    "payType": "wechat",
    "channelCode": "wechat",
    "amountFen": 123,
    "realAmountFen": 123,
    "feeFen": 4,
    "subject": "样例",
    "status": "PAYING",
    "payerName": "样例用户",
    "notifyUrl": "http://anduzf.cc/admin-api/pay/notify/merchant",
    "expireAt": "2026-11-10 22:30:09",
    "createdAt": "2026-11-10 22:27:08"
  }
}

10. 旧版出码（兼容保留）

POST /v1/pay/qr/intent（JSON）

{ "tradeNo": "P2026...", "payerName": "张三" }

响应：

{
  "code": "0",
  "data": {
    "tradeNo": "P2026...",
    "status": "PAYING",
    "qrCode": "...",
    "realAmount": 123,
    "realAmountYuan": "1.23",
    "expireAt": "2026-11-10 22:30:09"
  }
}

新接入建议用 §6 的 /v1/cashier/{tradeNo}/intent（支持 methodCode、幂等更好）。

11. 码商确认（码商端接口）

以下接口给码商 App/工作台使用，普通商户无需调用；列出用于说明“支付确认”链路。

11.1 登录

POST /machi-api/auth/login

{ "username": "machi01", "password": "******" }

返回 data.token（Bearer Token，有效期默认 8 小时）。

11.2 确认到账

POST /machi-api/orders/{tradeNo}/confirm Header：Authorization: Bearer <码商Token>

无请求体。成功返回：

{
  "code": "0",
  "msg": "SUCCESS",
  "data": {
    "msg": "确认成功",
    "depositBalance": 490834,
    "depositFrozen": 0,
    "profitBalance": 956,
    "platform_fee_fen": 135,
    "merchant_profit_fen": 15,
    "rate_bp": 1000,
    "confirm_state": "CONFIRMED"
  }
}

注意：platform_fee_fen、merchant_profit_fen、rate_bp、confirm_state 为下划线命名（数据库字段原样返回），其余为驼峰。

确认成功后：订单 status=SUCCESS、解冻押金、写分账流水，并触发 §12 回调。

12. 异步回调（码池 → 商户）

12.0 回调地址从哪来

回调地址按以下优先级取：

1. 下单请求里的 notifyUrl（推荐，按订单指定）；
2. 下单未传时，取「下游应用」配置的默认回调地址：
   • 管理后台 → 支付通道 → 下游应用（商户）→ 新增/编辑 → 回调地址；
   • 或商户控制台 → 接入设置 → 回调地址；
3. 两者都为空：不回调。

应用级回调地址修改后，只影响之后新建的订单；已创建订单仍用下单时的地址。

12.1 请求

• 方式：POST
• Content-Type：application/x-www-form-urlencoded
• 地址：下单时传入的 notifyUrl

参数（表单）：

原始请求体示例：

appId=SF4F001&outTradeNo=P202611102226432&tradeNo=P20261110222643937265346&amount=100
&realAmount=100&tradeStatus=TRADE_SUCCESS&payTime=2026-11-10+22%3A26%3A46
&sign_type=SHA256&sign=738219f69575ab208a821d76f6ab3167a91eeb556c12f551e869ef7f45dc54da

12.2 验签（Python）

import hmac, hashlib, urllib.parse

def verify(form: dict, secret: str) -> bool:
    params = {k: v for k, v in form.items() if k not in ("sign", "sign_type") and v}
    raw = "&".join(f"{k}={params[k]}" for k in sorted(params)) + "&key=" + secret
    expect = hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest()
    return expect == form.get("sign", "").lower()

12.3 成功判定

服务端按以下条件判定回调成功：

HTTP 200 且 响应体 trim 后（忽略大小写）等于 "success"

必须返回纯文本 success，不要返回 JSON、HTML 或空响应，否则会重试。

12.4 重试机制

未传 notifyUrl 时不会收到回调，且会在通知队列留下失败任务；请务必传有效地址。

12.5 回调地址要求

• 必须是 http:// 或 https:// 公网可达地址；
• 禁止内网/环回地址（平台有 SSRF 校验，白名单可在后台配置）；
• 建议独立接口、快速返回 success，业务处理异步化。

13. 运营关单

POST /admin/orders/{tradeNo}/close Header：Authorization: Bearer <管理后台Token>

{ "operator": "admin", "reason": "用户取消" }

行为：

关单不会触发支付成功回调；商户通过轮询会看到 CLOSED。

14. 错误码总表

15. 状态枚举

16. 常见失败与排查

17. 完整示例（Python）

import hashlib, hmac, json, time, urllib.request

BASE   = "https://www.hjdgawjkdn.top"
APP_ID = "<APP_ID>"
SECRET = "<SECRET>"

def sign(out_trade_no, pay_type, amount_fen):
    raw = f"amount={amount_fen}&appId={APP_ID}&outTradeNo={out_trade_no}&payType={pay_type}"
    return hmac.new(SECRET.encode(), (raw + "&key=" + SECRET).encode(), hashlib.sha256).hexdigest()

def post(path, body):
    req = urllib.request.Request(BASE + path, data=json.dumps(body).encode(),
                                 headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=15) as r:
        return json.loads(r.read().decode())

out_trade_no = "ORD" + str(int(time.time()))
body = {
    "appId": APP_ID,
    "outTradeNo": out_trade_no,
    "payType": "wechat",
    "amount": 123,
    "subject": "测试商品",
    "notifyUrl": "https://your-domain.com/notify",
}
body["sign"] = sign(out_trade_no, "wechat", 123)
order = post("/v1/pay/unified", body)
print(order)                      # 把 payUrl 给用户打开

trade_no = order["data"]["tradeNo"]

# 用户填名后（通常由收银台页面完成，这里演示接口）
post(f"/v1/cashier/{trade_no}/intent", {"payerName": "张三"})

# 轮询到成功
for _ in range(60):
    with urllib.request.urlopen(f"{BASE}/v1/cashier/{trade_no}", timeout=10) as r:
        info = json.loads(r.read().decode())["data"]
    if info["status"] in ("SUCCESS", "CLOSED"):
        break
    time.sleep(1)
print(info["status"], info.get("qrCode"))

18. 话费充值 H5

话费订单创建结果会返回 landingUrl，用户打开后进入 /phone/{landingToken} 充值引导页。手机号中间四位脱敏显示；页面进入后自动开启核对窗口，不需要用户点击“开始充值”。

• GET /v1/phone/public/{token} 订单详情与充值步骤
• POST /v1/phone/public/{token}/start 页面自动调用，开启核对窗口
• POST /v1/phone/public/{token}/claim 用户确认已完成充值

话费优先金额规则（管理端）

入口：话费管理 → 渠道与金额。配置保存到 sys_config，下一笔派单生效，无需重启。

• GET /admin/phone/collect-config 读取开关、模式、金额区间、指定金额
• POST /admin/phone/collect-config 保存配置：enabled、mode（RANGE/LIST）、minFen、maxFen、amounts（分）、windowSeconds、claimMinSeconds

当前配置为 1–200 元优先话费；号码池不可用时回退码商码池。

19. 变更记录