接入文档

PayHub 是统一收款网关：你只对接一套 API，即可通过我们后端聚合的多个上游支付渠道收款。全程无需引入 SDK、无需自建收银台——三次 HTTP 交互完成一笔收款。

更新 2026-08-07所有接口行为均经实跑验证时间口径 北京时间

0开始之前

你需要准备两样东西：一个能对外发起 HTTPS 请求的服务端，和一个能被公网访问的回调接口。除此之外不需要任何 SDK 或依赖。

接口地址

四个接口，就这些

请求用 Content-Type: application/x-www-form-urlencoded。也接受扁平 JSON，但所有值必须是字符串（"amount":"12900" 而不是 "amount":12900）。

1完整流程

一笔收款经过的站点，按实际发生顺序：

2一 · 开户

联系运营方开通商户。你需要提供这几项：

开户完成后你会拿到三样东西：

IP 白名单怎么生效

白名单留空就是不限制任何来源。一旦填了，就只有名单内的 IP 能调用，其他一律拒绝并返回 2002。支持单个 IP 和 CIDR 网段两种写法，填单个 IP 时会自动按 /32 处理。建议生产环境配上——多一道防线，密钥万一泄露也调不动。

3二 · 签名

四个接口用同一套签名规则。回调验签也是这套规则，只是方向相反。一共五步：

▸ 一个真实的待签名串（下单请求）

amount=12900&currency=USD&merchant_no=M1003&merchant_order_no=G1-20260807-001
&notify_url=https://your-service.example.com/payhub/notify&pay_method=mock
&subject=账户充值&timestamp=1786073088

# 上面的换行只是为了排版好看
# 实际是一整行，中间没有空格、没有换行
# sign = HMAC_SHA256(这一整行, secret) 取 hex 小写

签名实现

▸ Python

import hmac, hashlib

def sign(params: dict, secret: str) -> str:
    raw = "&".join(
        f"{k}={params[k]}"
        for k in sorted(params)
        if k != "sign" and params[k] != ""
    )
    return hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest()

▸ Go

func Sign(params map[string]string, secret string) string {
    keys := make([]string, 0, len(params))
    for k, v := range params {
        if k == "sign" || v == "" { continue }
        keys = append(keys, k)
    }
    sort.Strings(keys)
    parts := make([]string, 0, len(keys))
    for _, k := range keys {
        parts = append(parts, k+"="+params[k])
    }
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(strings.Join(parts, "&")))
    return hex.EncodeToString(mac.Sum(nil))
}

▸ PHP

function payhub_sign(array $params, string $secret): string {
    unset($params['sign']);
    $params = array_filter($params, fn($v) => $v !== '' && $v !== null);
    ksort($params, SORT_STRING);          // 必须按字符串序，不是默认序
    $parts = [];
    foreach ($params as $k => $v) { $parts[] = $k . '=' . $v; }
    return hash_hmac('sha256', implode('&', $parts), $secret);
}

4三 · 下单

POST https://pay.payhub.asia/api/v1/pay/create

pay_method 取哪个值

返回什么

{
  "code": 0,
  "msg": "ok",
  "data": {
    "platform_no": "P260807000005",    // PayHub 侧单号，查单退款都用它
    "pay_url":     "https://pay.payhub.asia/pay/P260807000005",
    "expire_at":   "2026-08-07 11:54:48"   // 北京时间，下单后 30 分钟
  }
}

请把 platform_no 存进你的订单表，后续查单、退款、对账都要用它。

5四 · 跳转支付

拿到 pay_url 之后，把用户浏览器整页跳转过去就行，不要用 iframe 嵌（部分渠道禁止被嵌套）。这个地址永远是 PayHub 自己的地址，用户访问时由 PayHub 决定后续走向：

6五 · 接收回调

支付和退款的结果，由 PayHub 用 POST 推到你的 notify_url，body 是 JSON。这是整个对接里最容易出错的一步，下面每一条都请仔细看。

你会收到什么

{
  "platform_no":       "P260807000005",
  "merchant_order_no": "G1-20260807-001",
  "status":            "success",
  "amount":            "12900",
  "paid_amount":       "12900",
  "currency":          "USD",
  "pay_method":        "mock",
  "paid_at":           "2026-08-07 11:24:48",   // 北京时间，注意含空格
  "extra":             null,                    // 下单时没传就是 null
  "timestamp":         "1786073092",
  "sign":              "a3f1……"
}

验签的四条规则

amount=12900&currency=USD&merchant_order_no=G1-20260807-001&paid_amount=12900
&paid_at=2026-08-07 11:24:48&pay_method=mock&platform_no=P260807000005
&status=success&timestamp=1786073092

# 注意两处：
#   1. paid_at 里的空格是原样的，没被编码
#   2. extra 是 null，整个字段没有参与拼串

你的接口要怎么应答

没收到 success 时，按 15秒 → 1分钟 → 5分钟 → 30分钟 → 2小时 → 6小时 → 24小时 的间隔重试，一共 7 次，之后标记为已耗尽不再推送。

▸ 回调接收端完整实现（Python）

import hmac, hashlib, json

def verify(body: dict, secret: str) -> bool:
    got = body.pop("sign", "")
    parts = []
    for k in sorted(body):
        v = body[k]
        if v is None:                       # null 字段跳过
            continue
        if not isinstance(v, str):            # 非字符串取紧凑 JSON
            v = json.dumps(v, separators=(",", ":"))
        parts.append(f"{k}={v}")           # 原样拼，不要 urlencode
    calc = hmac.new(secret.encode(), "&".join(parts).encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(calc, got)    # 常数时间比较


# ---- 你的 HTTP handler ----
def on_notify(request):
    body = json.loads(request.body)

    if not verify(dict(body), SECRET):
        return text("invalid sign", 400)      # 验签失败别应答 success

    order = db.get(body["merchant_order_no"])
    if order is None:
        return text("order not found", 404)

    if order.paid:                              # 幂等：已处理过直接认
        return text("success")

    if body["status"] == "success":
        if int(body["paid_amount"]) < order.amount:   # 金额必须核对
            log.error("金额不符，人工介入")
            return text("amount mismatch", 400)
        order.mark_paid()
        deliver(order)                           # 发货

    return text("success")                     # ← 纯文本，必须

7六 · 查单

POST https://pay.payhub.asia/api/v1/pay/query

传 platform_no 或 merchant_order_no 至少一个，加上公共签名参数即可。

返回里还带 paid_amount、paid_at、channel_pay_url（上游原始支付地址）等字段。

8七 · 退款

POST https://pay.payhub.asia/api/v1/refund/create

服务端会硬校验三条，任意一条不过就直接拒绝：

• 这笔订单属于你这个商户
• 订单状态是支付成功
• 累计退款金额不超过实付金额

退满之后订单状态转为 refunded。查询退款进度用 /api/v1/refund/query，传 refund_no。

注意不是所有渠道都支持退款，不支持时报 3002，需要走线下处理。当前 mock 和 NuwaPay 支持退款。

9怎么联调

不需要单独的测试环境。直接用正式地址，把 pay_method 传成 mock 就是联调模式：

联调阶段唯一要注意的是：你的 notify_url 必须是公网能访问到的地址。本机 localhost 收不到回调，可以先用任意一个公网可达的测试服务，或者临时用内网穿透工具。

10易错点

下面这些都是实际踩过的，看一遍能省你半天时间：

11错误码

12完整示例

下面这段可以直接跑：下单 → 查单 → 模拟支付 → 退款。把商户号和密钥换成你自己的即可。

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

BASE   = "https://pay.payhub.asia"
MNO    = "你的商户号"
SECRET = "你的密钥"

def call(path, params):
    params = {k: str(v) for k, v in params.items() if v != ""}
    params["merchant_no"] = MNO
    params["timestamp"]   = str(int(time.time()))
    raw = "&".join(f"{k}={params[k]}" for k in sorted(params) if k != "sign")
    params["sign"] = hmac.new(SECRET.encode(), raw.encode(), hashlib.sha256).hexdigest()
    req = urllib.request.Request(BASE + path,
        data=urllib.parse.urlencode(params).encode(),
        headers={"Content-Type": "application/x-www-form-urlencoded"})
    try:
        return json.loads(urllib.request.urlopen(req, timeout=15).read())
    except urllib.error.HTTPError as e:
        return json.loads(e.read())        # 错误也是 JSON，别当异常吞掉


# ① 下单
r = call("/api/v1/pay/create", {
    "merchant_order_no": f"T{int(time.time())}",
    "amount":      12900,              # $129.00
    "currency":    "USD",
    "pay_method":  "mock",             # 联调用 mock，正式换 rub_qr 等
    "subject":     "账户充值",
    "notify_url":  "https://your-service.example.com/payhub/notify",
})
assert r["code"] == 0, r
pno = r["data"]["platform_no"]
print("把用户跳转到：", r["data"]["pay_url"])

# ② 查单
print(call("/api/v1/pay/query", {"platform_no": pno})["data"]["status"])   # pending

# ③ 仅 mock 渠道：模拟用户点「支付成功」
#    真实渠道下这一步由用户在渠道页完成，你不用调
urllib.request.urlopen(urllib.request.Request(
    f"{BASE}/pay/{pno}/result",
    data=urllib.parse.urlencode({"action": "success"}).encode(),
    headers={"Content-Type": "application/x-www-form-urlencoded"}))
time.sleep(4)                              # 等回调投递

print(call("/api/v1/pay/query", {"platform_no": pno})["data"])       # success

# ④ 退款（部分退 $50.00）
print(call("/api/v1/refund/create", {
    "platform_no":   pno,
    "refund_no":     f"RF{int(time.time())}",
    "refund_amount": 5000,
    "reason":        "测试退款",
}))

13上线清单

正式放量之前，请逐条确认：

• 用 mock 渠道下单成功，拿到了 platform_no 和 pay_url
• 浏览器打开 pay_url，能正常看到收银页
• 点「支付成功」后，你的 notify_url 确实收到了回调
• 回调验签通过，并且你应答的是纯文本 success
• 重复推送同一笔回调，你的系统不会重复发货
• 主动查单能拿到 success，金额和你的订单对得上
• 退款能成功，且累计退款超过实付时会被正确拒绝
• 换成正式的 pay_method（rub_qr 等），跑通一笔小额真实订单
• 把服务器出口 IP 报给运营方加了白名单
• 密钥存进了密钥管理系统，没有硬编码在代码仓库里