所有开放接口 HTTPS。金额单位:分。先在后台创建应用并授权域名,再用 app_id / app_secret 签名调用。
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 分钟内不能重复。
{
"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。
页面回跳后必须再查一次。id_type 也可为 pay_no。
{ "id_type": "out_trade_no", "reason": "用户取消" }
{
"out_trade_no": "A10001",
"out_refund_no": "R10001",
"amount": { "refund": 50, "total": 100 },
"reason": "不想要了"
}
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。
app_id = app_demo app_secret = demo_secret_change_me 已授权域名: 127.0.0.1, localhost