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

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. 签名规则

新开户统一强制使用 signVersion=v2。存量商户在迁移期间可由管理员保留 V1 最低策略，升级完成后应提升为 V2；平台会记住首次下单使用的签名版本，并用相同版本签署该订单后续通知。查单请求也必须满足该商户当前最低签名策略。

V2：HMAC-SHA256（推荐）

1. 参数中明确加入 signVersion=v2，取完成一次 Form URL 解码后的全部参数，只排除小写 sign；V2 会保留空字符串字段。
2. 按参数名 ASCII 从小到大排序，以 UTF-8 字节处理字段名和值。
3. 签名原文先写入固定字节 SFPAY-MERCHANT-SIGN-V2\0；随后对每个字段依次写入：4 字节无符号大端字段名字节长度、字段名字节、4 字节无符号大端值字节长度、值字节。
4. 使用商户密钥作为 HMAC key，对完整原文计算 HMAC-SHA256，结果转为大写 64 位十六进制。

V2 Node.js 签名示例

import crypto from 'node:crypto';

function makeSign(params, secretKey) {
  const chunks = [Buffer.from('SFPAY-MERCHANT-SIGN-V2\0', 'utf8')];
  for (const key of Object.keys(params).filter((k) => k !== 'sign').sort()) {
    const keyBytes = Buffer.from(key, 'utf8');
    const valueBytes = Buffer.from(String(params[key] ?? ''), 'utf8');
    const keyLength = Buffer.alloc(4); keyLength.writeUInt32BE(keyBytes.length);
    const valueLength = Buffer.alloc(4); valueLength.writeUInt32BE(valueBytes.length);
    chunks.push(keyLength, keyBytes, valueLength, valueBytes);
  }
  return crypto.createHmac('sha256', Buffer.from(secretKey, 'utf8'))
    .update(Buffer.concat(chunks)).digest('hex').toUpperCase();
}

V1：旧 MD5 兼容期

只有后台仍明确保留 V1 最低策略的存量商户，省略 signVersion（或传 v1）时，才按“排除空值与 sign、ASCII 排序、拼接 key=value&...、末尾追加 &key=密钥、计算大写 MD5”验证。为消除旧格式字段边界碰撞，V1 的非空字段名和值不得含 & 或 =，字段名 key 也不允许使用。带查询参数的 notifyUrl 必须升级 V2。新开户和已提升到 V2 策略的商户会直接拒绝 V1。

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; charset=UTF-8' \
  --data-urlencode 'mchId=M10001' \
  --data-urlencode 'mchOrderNo=TEST202607090001' \
  --data-urlencode 'productId=0001' \
  --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 'signVersion=v2' \
  --data-urlencode 'sign=按V2规则计算后的HMAC-SHA256大写值'

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_no": "SF20260709213000A1B2C3D4",
    "merchant_order_no": "TEST202607090001",
    "pay_url": "https://pay.example.com/api/v1/pay/open/随机付款令牌",
    "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.example.com/api/v1/pay/open/随机付款令牌"
  },
  "request_id": "..."
}

6. 订单状态通知

订单进入终态后，平台会从已公布的公网 IPv4 出口向商户下单时传入的 notifyUrl 发送 UTF-8 POST Form 通知：交易成功为 status=1，交易失败为 status=2；如果订单之后出现可信的上游成功结果或成功订单被交易冲正，平台会再次发送对应的状态更正通知。进行中状态不会发送终态通知。Content-Type 为 application/x-www-form-urlencoded; charset=UTF-8。商户收到每次通知后都必须按第 3 节对解码后的字段验签、校验金额和订单归属，并按订单号幂等更新状态；处理成功后响应纯文本 success。

通知示例

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

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

商户处理要求

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

交易状态与通知状态

交易状态表示订单本身的处理结果；通知状态只表示平台向商户 notifyUrl 投递该结果后，是否已收到符合协议的确认响应。二者相互独立，通知失败不会把交易成功改成交易失败。

超时与自动重试

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

7. 状态与错误

订单状态

通用响应结构

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

8. 上线检查