业务项目对接

所有开放接口 HTTPS。金额单位:分。先在后台创建应用并授权域名,再用 app_id / app_secret 签名调用。

1. 请求签名

Header:
X-App-Id / X-Timestamp / X-Nonce / X-Sign

待签名串:
timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path_with_query + "\n" + body + "\n"

X-Sign = hex(hmac_sha256(app_secret, 待签名串))
时间窗 5 分钟;nonce 10 分钟内不能重复。

2. 创建订单 POST /v1/pay/orders

{
  "out_trade_no": "A10001",
  "description": "会员充值",
  "amount": { "total": 100, "currency": "CNY" },
  "trade_type": "NATIVE",
  "mode": "CASHIER",
  "attach": "uid=1",
  "notify_url": "https://mall.example.com/pay/notify",
  "return_url": "https://mall.example.com/pay/return"
}

成功 data 含 pay_no、cashier_url。把用户带到 cashier_url。

3. 查单 GET /v1/pay/orders/{id}?id_type=out_trade_no

页面回跳后必须再查一次。id_type 也可为 pay_no。

4. 关单 POST /v1/pay/orders/{id}/close

{ "id_type": "out_trade_no", "reason": "用户取消" }

5. 退款 POST /v1/pay/refunds

{
  "out_trade_no": "A10001",
  "out_refund_no": "R10001",
  "amount": { "refund": 50, "total": 100 },
  "reason": "不想要了"
}

6. 中台回调业务 notify_url

POST {notify_url}
Header: X-App-Id X-Timestamp X-Nonce X-Sign X-Event X-Event-Id

回调验签(注意和开放接口不同,不签 METHOD/path):
timestamp + "\n" + nonce + "\n" + rawBody + "\n"

事件:
PAYMENT.SUCCESS / PAYMENT.CLOSED / REFUND.SUCCESS

业务必须:
1. 用原始 body 字节验签
2. 核对 amount.total
3. 按 event_id 幂等
4. HTTP 200 且 {"code":"SUCCESS"}

否则中台按 15s/30s/1m... 重试至 24h。

7. 演示凭证

app_id = app_demo
app_secret = demo_secret_change_me
已授权域名: 127.0.0.1, localhost