商户对接文档（统一收银台 API）

版本：v1.1（2026-10-04）｜ 适用对象：接入本平台的外部商户技术人员 ｜ 历史版本

1. 概述与接入流程

本平台为多国聚合支付平台，采用「一国一收银台」模型：商户只需对接一次平台统一 API，即可使用各国收银台的代收 / 代付能力。上游通道的切换、权重、启停由平台侧完成，商户无感。

接入流程（5 步）：

1. 开户：联系平台运营开通商户号（商户后台登录账号）。
2. 拿密钥：登录商户后台 → 「API 密钥管理」获取 API Key 与 API Secret（见 §2）。
3. 沙箱联调：用测试服地址按本文档完成签名、下单、查询、通知验签联调（见 §8）。
4. 配置通知地址：下单时传入 notify_url（或在商户后台配置默认通知地址，以联调时确认为准），确保能接收并正确处理异步通知（见 §6）。
5. 上线：联调通过后切换生产网关地址与生产密钥，开始真实交易。

2. 接入准备

⚠️ API Secret 明文平台不保存、不回显。遗失请重新重置，重置后旧密钥立即失效。

网关地址：

以下接口路径均为相对路径，如代收下单完整地址为 http://45.76.155.11/api/v1/pay/mch/payin/create。

支持的国家收银台（沙箱）：

下单时 currency 必须与收银台币种一致，pay_method 必须在该国支持列表内，否则返回参数/业务错误。

3. 签名规则

所有商户统一 API 请求都必须签名。鉴权方式为请求头三件套：

签名算法（7 步）：

1. 收集待签参数：URL query 参数与 JSON body 顶层字段合并为一个字典（本接口一般无 query 参数，即对 body 顶层字段签名）；
2. 排除 sign 字段（精确匹配小写 sign）；
3. 空值不参与签名：值为 null 或 ""（空字符串）时跳过；
4. 剩余参数按 key 的 ASCII 码升序排列；
5. 拼接为 k1=v1&k2=v2&...&kn=vn 形式。值先字符串化：
6. 数字 / 布尔：按服务端语言的字符串转换（Python str()，即布尔为 True/False，注意不是 true/false）；
7. 嵌套 dict / list：按 JSON 紧凑格式序列化（key 排序、分隔符为 , 和 :、不转义 Unicode），即 json.dumps(v, sort_keys=True, separators=(",", ":"), ensure_ascii=False)；
8. 尾部拼接 &key={api_secret}，api_secret 为你的接口密钥明文；
9. 对拼接串取 MD5，结果转大写，即为 X-Sign 的值。

示例（api_secret = "testsecret123"，body 为 {"country_code":"PK","pay_method":"EP","amount_minor":10000,"currency":"PKR","mch_order_no":"ORDER20260930001","notify_url":"https://merchant.example/notify"}）：

待签串：
amount_minor=10000&country_code=PK&currency=PKR&mch_order_no=ORDER20260930001&notify_url=https://merchant.example/notify&pay_method=EP&key=testsecret123
X-Sign = MD5(待签串).upper()

注意：mode、return_url、goods_desc、client_ip 若传空字符串则不参与签名；若传了非空值则参与签名，body 与签名必须一致。

验签失败一律返回 HTTP 401，code=40100（签名验证失败 / 时间戳过期 / 缺少鉴权参数 / 商户不存在或被禁用）。

4. 代收

4.1 代收下单

POST /api/v1/pay/mch/payin/create ｜ Content-Type: application/json

请求字段：

响应（code=0）：

{
  "code": 0,
  "msg": "下单成功",
  "data": {
    "platform_order_no": "PI20260930010101001",
    "mch_order_no": "ORDER20260930001",
    "pay_url": "http://45.76.155.11/api/v1/pay/cashier/PI20260930010101001",
    "qr_data": "",
    "status": "PENDING"
  }
}

4.2 代收查询

POST /api/v1/pay/mch/payin/query ｜ Content-Type: application/json

请求字段（二选一，至少传一个）：

响应（code=0，data 为订单详情）：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "platform_order_no": "PI20260930010101001",
    "mch_order_no": "ORDER20260930001",
    "order_type": "payin",
    "country_code": "PK",
    "country_name": "巴基斯坦",
    "pay_method": "EP",
    "mode": "cashier",
    "amount_minor": 10000,
    "currency": "PKR",
    "fee": 30,
    "status": "SUCCESS",
    "upstream_order_no": "UP202609300001",
    "pay_url": "http://45.76.155.11/api/v1/pay/cashier/PI20260930010101001",
    "qr_data": "",
    "notified": true,
    "paid_at": "2026-09-30T10:05:00+00:00",
    "created_at": "2026-09-30T10:01:00+00:00"
  }
}

订单状态说明：

5. 代付

5.1 代付下单

POST /api/v1/pay/mch/payout/create ｜ Content-Type: application/json

请求字段：

响应（code=0）：

{
  "code": 0,
  "msg": "代付下单成功",
  "data": {
    "platform_order_no": "PO20260930010101002",
    "mch_order_no": "PAYOUT20260930001",
    "status": "PROCESSING"
  }
}

平台订单号代付前缀为 PO。代付为资金出账操作，请确保商户余额充足。

5.2 代付查询

POST /api/v1/pay/mch/payout/query ｜ Content-Type: application/json

请求字段与响应格式同 §4.2（order_type 为 payout）。

5.3 余额查询

POST /api/v1/pay/mch/balance/query ｜ Content-Type: application/json

代付前检查商户余额。请求体可选 currency（如 PKR）过滤币种，不传返回全部币种。

{
  "currency": "PKR"
}

响应 data.balances 为数组，每项含 currency、balance（可用余额，最小货币单位）、frozen（冻结金额）。

6. 异步通知

订单进入终态（SUCCESS / FAILED / CANCELLED / REVERSED）且下单时传入了 notify_url，平台将向该地址发送异步通知。

• 方式：POST，Content-Type: application/json，超时 10 秒；
• 通知字段：

验签：收到通知后，用 §3 算法对除 sign 外的字段重新计算签名，与 sign 比对（转大写后比对）。验签不通过的通知不得作为入账依据。

商户收到通知后应返回什么：HTTP 状态码 < 500，且响应体包含 SUCCESS 或 success（如直接返回纯文本 SUCCESS），平台即视为送达成功。

重试机制：首次发送失败后平台自动重试，最多 8 次，退避间隔为 1 分钟 → 5 分钟 → 30 分钟 → 2 小时 → 12 小时 → 12 小时 → 12 小时；8 次仍失败标记为不再重试。请做好幂等处理（同一订单可能重复通知，以 platform_order_no + status 去重）。

建议：不要完全依赖通知，重要订单主动调用查询接口对账。

7. 错误码表

统一响应体为 {"code": ..., "msg": "...", "data": ...}。code=0 表示成功。

8. 沙箱联调说明

• 测试服地址：http://45.76.155.11（HTTP，沙箱阶段可用；生产为 HTTPS，以开户提供为准）。
• 上游通道：测试服上游为 Mock 通道（URPAY / TAZPAY / SRPAY / NOTION / YUNPAY），不产生真实资金，仅用于联调接口与流程。
• 测试订单标识：沙箱订单为测试单，不影响任何真实资金与结算。
• 联调步骤建议：
• 先调通签名：用 §9 示例代码对一个查询接口签名，确认返回非 401；
• 代收下单：用 PK + EP + 10000（PKR 100.00）下一笔，拿到 pay_url 浏览器打开，查看收银台 H5；
• 代收查询：用 mch_order_no 查到订单，核对字段；
• 通知联调：notify_url 填你方可公网访问的地址，下单后观察收到的 POST 与 sign 验签；
• 代付下单 + 查询：同上，注意代付 notify_url 可选。
• 收银台 H5：GET /api/v1/pay/cashier/{platform_order_no}（无需鉴权），即 pay_url 指向的页面，展示国家 / 金额 / 支付方式 / 二维码。

9. 示例代码

9.1 Python（签名 + 代收下单 + 通知验签，完整可跑）

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

API_BASE = "http://45.76.155.11"
API_KEY = "你的API Key"
API_SECRET = "你的API Secret"


def _stringify(v):
    if isinstance(v, bool):
        return str(v)  # True/False，与服务端一致
    if isinstance(v, (dict, list)):
        return json.dumps(v, sort_keys=True, separators=(",", ":"),
                          ensure_ascii=False)
    return str(v)


def build_sign(params: dict, api_secret: str) -> str:
    items = [(k, _stringify(v)) for k, v in params.items()
             if k != "sign" and v is not None and v != ""]
    items.sort(key=lambda kv: kv[0])  # ASCII 升序
    canonical = "&".join(f"{k}={v}" for k, v in items)
    canonical = f"{canonical}&key={api_secret}" if canonical else f"key={api_secret}"
    return hashlib.md5(canonical.encode("utf-8")).hexdigest().upper()


def api_post(path: str, body: dict) -> dict:
    ts = str(int(time.time()))
    headers = {
        "Content-Type": "application/json",
        "X-Api-Key": API_KEY,
        "X-Timestamp": ts,
        "X-Sign": build_sign(body, API_SECRET),
    }
    req = urllib.request.Request(API_BASE + path,
                                 data=json.dumps(body).encode("utf-8"),
                                 headers=headers, method="POST")
    with urllib.request.urlopen(req, timeout=15) as resp:
        return json.loads(resp.read().decode("utf-8"))


# ---- 代收下单 ----
order = api_post("/api/v1/pay/mch/payin/create", {
    "country_code": "PK",
    "pay_method": "EP",
    "mode": "cashier",
    "amount_minor": 10000,
    "currency": "PKR",
    "mch_order_no": "TEST" + str(int(time.time())),
    "notify_url": "https://merchant.example/notify",
    "return_url": "https://merchant.example/return",
    "goods_desc": "测试商品",
})
print(json.dumps(order, ensure_ascii=False, indent=2))

# ---- 通知验签（在你的 notify_url 处理函数中使用） ----
def verify_notify(payload: dict) -> bool:
    sign = str(payload.get("sign", "")).upper()
    return hmac.compare_digest(build_sign(payload, API_SECRET), sign)

9.2 PHP（签名函数）

<?php
function mch_ksort_recursive($arr) {
    if (!is_array($arr)) return $arr;
    if (array_keys($arr) !== range(0, count($arr) - 1)) {
        ksort($arr, SORT_STRING);          // 关联数组按 key ASCII 排序
    }
    foreach ($arr as $k => $v) $arr[$k] = mch_ksort_recursive($v);
    return $arr;
}

function mch_stringify($v) {
    if (is_bool($v)) return $v ? 'True' : 'False';   // 对齐服务端 Python str()
    if ($v instanceof stdClass) return '{}';        // 空对象
    if (is_array($v)) {
        return json_encode(mch_ksort_recursive($v),
            JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    }
    return (string)$v;
}

function mch_sign(array $params, string $apiSecret): string {
    $items = [];
    foreach ($params as $k => $v) {
        if ($k === 'sign' || $v === null || $v === '') continue; // 排除 sign 与空值
        $items[$k] = mch_stringify($v);
    }
    ksort($items, SORT_STRING);
    $pairs = [];
    foreach ($items as $k => $v) $pairs[] = $k . '=' . $v;
    $canonical = implode('&', $pairs);
    $canonical = $canonical !== '' ? $canonical . '&key=' . $apiSecret
                                   : 'key=' . $apiSecret;
    return strtoupper(md5($canonical));
}

// 使用示例
$body = [
    'country_code' => 'PK',
    'pay_method'   => 'EP',
    'mode'         => 'cashier',
    'amount_minor' => 10000,
    'currency'     => 'PKR',
    'mch_order_no' => 'TEST' . time(),
    'notify_url'   => 'https://merchant.example/notify',
];
$headers = [
    'Content-Type: application/json',
    'X-Api-Key: 你的API Key',
    'X-Timestamp: ' . time(),
    'X-Sign: ' . mch_sign($body, '你的API Secret'),
];
// 之后用 curl POST JSON $body 到网关，略

PHP 注意：空对象请用 (object)[] / new stdClass（json_encode 输出 {}），不要用 []（会输出 [] 导致签名不一致）；extra 等可选字段不传则不参与签名。

9.3 curl（先算好签名再调，调试用）

TS=$(date +%s)
# X-Sign 需按 §3 算法预先算好，此处以 PLACEHOLDER 代替
curl -X POST http://45.76.155.11/api/v1/pay/mch/payin/create \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: 你的API Key' \
  -H "X-Timestamp: $TS" \
  -H 'X-Sign: 预先算好的大写MD5签名' \
  -d '{
    "country_code": "PK",
    "pay_method": "EP",
    "mode": "cashier",
    "amount_minor": 10000,
    "currency": "PKR",
    "mch_order_no": "TEST1699999999",
    "notify_url": "https://merchant.example/notify",
    "goods_desc": "测试商品"
  }'

文档外问题请联系平台运营 / 技术对接人。生产网关地址与密钥以开户资料为准。

版本变更记录