1. 签名算法

平台采用 RSA 非对称签名（SHA256withRSA），商户请求需签名，平台回调商户需验签，双向保证报文不可篡改。

密钥体系

签名步骤（商户请求平台）

1. 将请求体 JSON 全部字段按参数名（key）ASCII 码从小到大排序（字典序），序列化为紧凑 JSON 字符串（无多余空格、换行），得到待签名串。
2. 使用商户私钥对待签名串执行 SHA256withRSA 签名，结果做 Base64 编码，得到签名值 sign。
3. 将签名值放入请求头 x-signature，随原始请求体（内容不变）一起 POST。

sign = Base64( SHA256withRSA( sortJsonByKey(requestBody), 商户私钥 ) )

// 待签名串示例（按键名 ASCII 升序排列后的紧凑 JSON）
{"bankCode":"KTB","mchNum":"M10001","mchOrderNo":"202609010001",
 "notifyUrl":"https://shop.example.com/notify","payMoney":100.00,
 "paymentName":"Somchai","transAccNo":"8888888888888"}

验签步骤（商户接收平台回调）

1. 读取请求头 x-signature 与原始请求体（raw body）。
2. 将请求体 JSON 按 key ASCII 升序排序得到待验签串。
3. 用平台公钥执行 SHA256withRSA 验签；通过后按业务处理，并响应 ok。

注意事项

• 密钥格式：RSA 2048 位，公钥 X509 / 私钥 PKCS#8，Base64（带或不带头尾行均可，平台会自动清理空白字符）。
• 签名串必须与请求体逐字节一致：先排序再序列化，勿在排序后修改字段值。
• 接口可能增加扩展字段，商户验签时必须兼容新增字段。
• 签名失败平台会直接拒绝请求（签名验证失败），不会创建订单。

签名示例代码

Java

// 1. 排序: 请求体 JSON 按键名 ASCII 升序(TreeMap), 紧凑序列化
TreeMap<String, Object> sorted = new TreeMap<>();
sorted.putAll(JSON.parseObject(rawBody));
String signData = JSON.toJSONString(sorted);

// 2. SHA256withRSA 签名 → Base64
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);                       // PKCS#8 Base64 私钥
signature.update(signData.getBytes(StandardCharsets.UTF_8));
String sign = Base64.getEncoder().encodeToString(signature.sign());

// 3. 放入请求头
headers.set("x-signature", sign);

PHP

// 1. 排序 + 紧凑 JSON（PHP 关联数组默认按 key 排序写入）
$body = json_decode($rawBody, true);
ksort($body);
$signData = json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// 2. SHA256withRSA 签名 → Base64
openssl_sign($signData, $sign, $privateKey, OPENSSL_ALGO_SHA256);
$sign = base64_encode($sign);

Node.js

const crypto = require('crypto');

// 1. 排序 + 紧凑 JSON
const body = JSON.parse(rawBody);
const sorted = Object.keys(body).sort()
    .reduce((acc, k) => (acc[k] = body[k], acc), {});
const signData = JSON.stringify(sorted);

// 2. SHA256withRSA 签名 → Base64
const signer = crypto.createSign('RSA-SHA256');
signer.update(signData);
const sign = signer.sign(privateKey, 'base64');

2. 代收下单

商户业务系统通过本接口发起收款订单，网关按商户绑定的代收通道路由完成下单，返回支付链接与收款信息，商户展示给付款用户完成支付。

接口说明

• 商户订单号 mchOrderNo 在同一商户下必须唯一，重复将返回错误。
• 平台按商户绑定的代收通道（金额规则 + 权重）匹配通道后创建订单；无可用通道时报错 无可用代收通道。
• 订单有效期 10 分钟（endTime 为失效时间），请引导用户在有效期内完成支付。
• 自营通道返回收款银行卡信息（selfBankCard 相关字段），三方通道返回支付链接与二维码。

请求参数

{
  "mchNum": "M10001",
  "mchOrderNo": "202609010001",
  "payMoney": 100.00,
  "transAccNo": "8888888888888",
  "paymentName": "Somchai",
  "bankCode": "KTB",
  "paymentMobile": "0812345678",
  "notifyUrl": "https://shop.example.com/notify"
}

返回参数（data）

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "mchNum": "M10001",
    "paymentName": "Somchai",
    "transAccNo": "8888888888888",
    "orderCreateTime": "2026-09-01 10:00:00",
    "payMoney": 100.00,
    "paymentImageBase64": "iVBORw0KGgo...",
    "createTime": "2026-09-01 10:00:00",
    "endTime": "2026-09-01 10:10:00",
    "paymentLink": "https://pay.example.com/cashier?orderNo=P2026090110000001",
    "selfBankCard": true,
    "bankCardNo": "xxx-xxx-1234",
    "bankHolder": "Somsak",
    "bankName": "KTB"
  }
}

3. 代收异步通知

代收订单支付结果确定后（成功或失败），平台向商户下单时传入的 notifyUrl 发起 POST 回调，商户验签通过后应答 ok。

通知说明

• 商户需用平台公钥对报文验签（步骤见 签名算法），验签通过后再处理业务。
• 应答标准：HTTP 状态码 2xx 且响应体为 ok（忽略大小写与首尾空白），平台视为通知成功；其余情况视为失败。
• 每次通知的请求报文、签名、HTTP 状态与商户响应都会在平台留痕，可在后台「回调记录」中查询，便于联调排查。
• 建议商户对未收到通知 / 通知失败的订单，通过 查询代收订单 主动兜底核对。

通知参数（请求体）

// 平台回调请求示例（x-signature 为平台私钥对下列排序 JSON 的签名）
{
  "platformOrderNo": "P2026090110000001",
  "mchOrderNo": "202609010001",
  "mchNum": "M10001",
  "mchName": "示例商户",
  "requestAmount": 100.00,
  "actualPayAmount": 100.00,
  "mchFeeAmount": 2.50,
  "orderStatus": "success",
  "errorMessage": ""
}

商户应答

// 验签通过并处理完成业务后, 响应(HTTP 200):
ok

// 验签失败可返回(平台视为通知失败, 便于在回调记录中定位):
verify fail

4. 查询代收订单

商户通过本接口按商户订单号查询代收订单最新状态，用于结果核对与通知失败的兜底补偿。

请求参数

{
  "mchNum": "M10001",
  "mchOrderNo": "202609010001",
  "queryType": "collect"
}

返回参数（data）

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "mchNum": "M10001",
    "mchName": "示例商户",
    "platformOrderNo": "P2026090110000001",
    "mchOrderNo": "202609010001",
    "requestAmount": 100.00,
    "actualPayAmount": 100.00,
    "mchFeeAmount": 2.50,
    "orderStatus": "success",
    "settlementStatus": "UNSETTLED"
  }
}

5. 代付下单

商户业务系统通过本接口发起付款（出款）订单，平台校验并扣减商户余额后按代付通道路由出款，结果通过异步通知告知商户。

接口说明

• 商户订单号 mchOrderNo 在同一商户下必须唯一（与代收订单号相互独立）。
• 下单即校验商户可用余额是否充足并扣减，余额不足或无可用代付通道时报错。
• 代付为异步处理：本接口成功仅代表受理成功（data 为空），最终结果以异步通知 / 主动查询为准。

请求参数

{
  "mchNum": "M10001",
  "mchOrderNo": "P202609020001",
  "payMoney": 500.00,
  "transAccNo": "9999999999999",
  "paymentName": "Somsak",
  "bankCode": "KBANK",
  "paymentMobile": "0898765432",
  "description": "商家提现",
  "notifyUrl": "https://shop.example.com/pay-notify",
  "email": "merchant@example.com"
}

返回参数

受理成功时 code=200、msg=操作成功，无 data；最终出款结果通过异步通知或查询接口获取。

{ "msg": "操作成功", "code": 200 }

6. 代付异步通知

代付订单出款结果确定后（成功或失败），平台向商户下单时传入的 notifyUrl 发起 POST 回调，商户验签通过后应答 ok。

通知说明

• 商户需用平台公钥对报文验签，通过后再处理业务。
• 应答标准：HTTP 2xx 且响应体 ok，平台视为通知成功；否则视为失败。
• 每次通知在后台「回调记录」留痕；建议以 查询代付订单 兜底核对。

通知参数（请求体）

{
  "platformOrderNo": "F2026090210000001",
  "mchOrderNo": "P202609020001",
  "mchNum": "M10001",
  "mchName": "示例商户",
  "requestAmount": 500.00,
  "mchFeeAmount": 5.00,
  "orderStatus": "success",
  "errorMessage": ""
}

商户应答

// 验签通过并处理完成业务后, 响应(HTTP 200):
ok

7. 查询代付订单

商户通过本接口按商户订单号查询代付订单最新状态。

请求参数

{
  "mchNum": "M10001",
  "mchOrderNo": "P202609020001",
  "queryType": "pay"
}

返回参数（data）

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "mchNum": "M10001",
    "mchName": "示例商户",
    "platformOrderNo": "F2026090210000001",
    "mchOrderNo": "P202609020001",
    "requestAmount": 500.00,
    "actualPayAmount": 500.00,
    "mchFeeAmount": 5.00,
    "orderStatus": "success",
    "settlementStatus": "UNSETTLED"
  }
}

8. 查询账户余额

商户通过本接口查询账户可用余额、冻结金额与待结算金额，用于出款前的余额核对。

请求参数

{
  "mchNum": "M10001",
  "currency": "THB"
}

返回参数（data）

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "mchNum": "M10001",
    "mchName": "示例商户",
    "currency": "THB",
    "balance": 12500.00,
    "freeze": 0.00,
    "waitingSettleAmount": 3000.00,
    "freezeWaitingSettleAmount": 0.00,
    "totalAmount": 15500.00
  }
}

9. 订单状态与错误码

订单状态取值说明与接口常见错误信息，便于商户系统做状态映射与异常处理。

订单状态（orderStatus）

返回码

常见错误信息（msg）