四方支付商户接口对接文档

1. 对接资料

平台运营会给商户技术或对接系统提供以下资料：

2. 编码、URL 解码与字段约束

请求和通知均使用 application/x-www-form-urlencoded; charset=UTF-8。签名与业务处理都以服务端完成一次 Form URL 解码后的字段名和值为准，不以 HTTP 原始编码串为准。

• 客户端先使用 UTF-8 表示逻辑字段值，再按 Form 规则编码。%XX 在服务端只解码一次；+ 解为一个空格，字面加号必须编码为 %2B。
• 计算签名时使用解码后的原始值。例如标题为 商品 A+B 时，参与签名的是包含空格和 + 的 UTF-8 值，不是 %E5... 或 + 的传输表达。
• 同一个字段只能提交一次。服务端只取同名字段的第一个值；重复字段会使不同语言的客户端产生不同签名结果。
• 字段名区分大小写，只有小写 sign 被排除在签名外。不要发送未在本文档声明的非空字段，它们会参与签名但不构成业务字段。
• 所有下表字段必须是有效 UTF-8，且不得含控制字符（包括 TAB、CR、LF、NUL）。标识字段 mchId、mchOrderNo、productId 不得有前导或尾随空白。
• 除签名字段外，空白不会在签名阶段自动删除；空字符串才会被排除。请不要依赖服务端对业务字段的后续 trim 行为。

3. 签名规则

所有商户请求和平台支付通知均使用同一套 MD5 签名规则。

1. 取一次 Form URL 解码后的全部参数，排除小写 sign 字段。
2. 排除值恰好为空字符串的参数，例如 param1= 不参与签名；仅含空格的值不是空字符串，仍会参与签名。
3. 按参数名 ASCII 从小到大排序。
4. 拼接为 key=value&key2=value2。
5. 末尾追加 &key=商户密钥。
6. 按 UTF-8 字节对完整字符串做 MD5，结果转为大写 32 位十六进制。

签名示例

import crypto from 'node:crypto';

function makeSign(params, secretKey) {
  const pairs = Object.keys(params)
    .filter((key) => key !== 'sign' && params[key] !== undefined && params[key] !== null && String(params[key]) !== '')
    .sort()
    .map((key) => `${key}=${String(params[key])}`);
  return crypto.createHash('md5').update(`${pairs.join('&')}&key=${secretKey}`).digest('hex').toUpperCase();
}

4. 下单接口

地址：POST {平台域名}/api/v1/pay/create_order

请求示例

curl -X POST 'https://pay.example.com/api/v1/pay/create_order' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'mchId=M10001' \
  --data-urlencode 'mchOrderNo=TEST202607090001' \
  --data-urlencode 'productId=8007' \
  --data-urlencode 'amount=10000' \
  --data-urlencode 'notifyUrl=https://merchant.example.com/pay/notify' \
  --data-urlencode 'subject=商品订单' \
  --data-urlencode 'param1=merchant-extra-1' \
  --data-urlencode 'reqTime=20260709213000' \
  --data-urlencode 'sign=按签名规则计算后的MD5大写值'

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_no": "SF20260709213000A1B2C3D4",
    "merchant_order_no": "TEST202607090001",
    "pay_url": "https://pay-provider.example/pay?token=xxx",
    "amount": 10000,
    "status": 0
  },
  "request_id": "..."
}

5. 查单接口

地址：POST {平台域名}/api/v1/pay/query_order

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_no": "SF20260709213000A1B2C3D4",
    "merchant_order_no": "TEST202607090001",
    "amount": 10000,
    "status": 1,
    "pay_url": "https://pay-provider.example/pay?token=xxx"
  },
  "request_id": "..."
}

6. 订单状态通知

订单变为交易成功（status=1）后，平台会向商户下单时传入的 notifyUrl 发送 UTF-8 POST Form 通知；如果成功订单之后被交易冲正，平台会再发送 status=3 更正通知。Content-Type 为 application/x-www-form-urlencoded。商户收到每次通知后都必须按第 3 节对解码后的字段验签、校验金额和订单归属，并按订单号幂等更新最终状态；处理成功后响应纯文本 success。

通知示例

mchId=M10001
payOrderId=SF20260709213000A1B2C3D4
mchOrderNo=TEST202607090001
amount=10000
status=1
param1=merchant-extra-1
param2=
reqTime=20260709213120
sign=平台签名

同一订单发生冲正时，平台会再次发送上述字段，其中 status=3，并使用新的 reqTime 和对应签名。商户不得因为该订单曾处理过 status=1 而忽略这次更正。

商户处理要求

• 先验签，签名失败直接拒绝处理。
• 按 mchId、payOrderId 和 mchOrderNo 查询本地订单，确认订单归属一致。
• 校验 amount 与本地订单金额完全一致。
• 状态更新必须幂等：status=1 对同一订单只能入账一次；收到 status=3 时，如已按 status=1 入账，必须只冲账或扣回一次，并把本地订单更新为冲正。
• 处理成功后响应纯文本 success，不要返回 JSON、HTML 或额外空格内容。

超时与自动重试

每次通知 HTTP 请求最长等待 10 秒。首次通知立即发起；只有收到 HTTP 2xx 且响应体去除首尾空白后不区分大小写等于 success 才视为成功。请固定返回小写纯文本 success。网络错误、超时、非 2xx 或其他响应体均会重试。

7. 状态与错误

订单状态

通用响应结构

{
  "code": 0,
  "message": "ok",
  "data": {},
  "request_id": "..."
}

8. 上线检查