SquarePay 商户接入文档

本文档面向下游商户的技术开发人员，描述如何对接四方聚合支付平台完成收款、查询、退款及支付结果通知的全流程。所有接口均基于 HTTPS + RSA2 签名，可放心用于生产环境。

1 · 接入概述

四方模式说明

四方聚合支付是指在传统「商户—收单机构」之外，引入聚合平台作为中间层的收单模式。资金与交易链路如下：

下游商户：您的业务系统，发起收款、查询、退款请求。
本平台（四方 SquarePay）：统一签名、路由、风控、对账与分润，向下屏蔽上游差异。
上游通道（斗拱 / 汇付）：实际持牌收单方，完成清结算。

◆

下游商户只需对接本平台一套 API，即可获得微信、支付宝等多渠道收款能力；平台内部完成向上游斗拱的报文转换与验签，商户无需关心上游细节。

环境地址

● 沙箱环境 Sandbox

https://sandbox-api.squarepay.com

仅用于联调，交易不产生真实资金流。

● 生产环境 Production

https://api.squarepay.com

正式收款，需完成签约与密钥配置。

接入流程（4 步）

1. 签约开户

联系集成经理签约，获取商户号 mch_id 与费率配置。

2. 配置密钥

生成 RSA2 密钥对，上传商户公钥、下载平台公钥（用于验签回调）。

3. 沙箱联调

在沙箱环境完成下单 / 查询 / 退款 / 通知全链路验证。

4. 生产上线

切换生产地址与生产密钥，报备回调 IP，正式收款。

2 · 公共说明

项目	约定
请求方式	`POST`，Content-Type 为 `application/json`
字符编码	统一使用 UTF-8，请求与响应体均为 JSON
金额单位	一律为「分」，且为整数（如 1 元 = `100`），不接受小数
时间格式	`yyyy-MM-dd HH:mm:ss`，时区 GMT+8（东八区）
商户号 mch_id	平台为每个商户分配的唯一编号，请求必带，用于路由与验签
随机串 nonce_str	32 位以内随机字符串，防重放，参与签名
签名 sign	除 sign 外所有参数参与签名，详见「签名规则」

▲

金额字段一旦传错单位（元 / 分）将直接导致收款金额错误，请务必以「分」为单位并保证为整数。

3 · 签名规则（RSA2）

平台采用 RSA2（SHA256withRSA） 非对称签名。请求方使用商户私钥签名，平台使用商户公钥验签；回调时平台使用平台私钥签名，商户使用平台公钥验签。

签名步骤

取出请求体中所有非空参数（不含 sign）。
按参数名的 ASCII 码升序 排列。
用 key=value 形式、以 & 连接，拼成待签名串 stringA。
使用 SHA256withRSA 以商户私钥对 stringA 签名。
对签名结果做 Base64 编码，得到最终 sign，放回请求体一并发送。

待签名串示例（参数已按 ASCII 排序）：

stringA

mch_id=100000018&nonce_str=a1b2c3d4e5f6&notify_url=https://shop.com/notify&out_trade_no=T20260703001&pay_type=WX_JSAPI&subject=会员充值&total_amount=100

sign 示例（RSA2 签名 + Base64，此处截断示意）：

sign

Ql3kZ8vN...c2FtcGxlLXNpZ25hdHVyZQ==...9pXbQe4rT7

ℹ

验签同理：收到响应或回调后，取除 sign 外全部参数按同样规则拼出 stringA，用对方公钥执行 SHA256withRSA 验签，通过后方可信任报文。

4 · 统一下单接口

POST/v1/pay/unifiedorder

创建一笔支付订单并返回用于唤起支付的 prepay_data。不同 pay_type 返回的 prepay 结构不同：小程序 / 公众号返回可直接 wx.requestPayment 的参数，H5 返回可跳转的收银台 URL。

请求参数

字段	类型	必填	说明
mch_id	string	必填	平台分配的商户号
out_trade_no	string	必填	商户订单号，同一商户下唯一，建议 6–32 位
total_amount	int	必填	订单金额，单位分，须为正整数
pay_type	string	必填	支付方式：`WX_JSAPI` / `WX_LITE` / `ALI_H5`
subject	string	必填	订单标题 / 商品描述，≤ 128 字节
openid	string	条件必填	用户在商户公众号 / 小程序下的 openid；`WX_JSAPI` 与 `WX_LITE` 必填
notify_url	string	必填	接收异步支付结果的回调地址，须 https
attach	string	选填	商户自定义透传数据，回调原样返回，≤ 128 字节
time_expire	string	选填	订单失效时间，格式 `yyyy-MM-dd HH:mm:ss`，默认 30 分钟
nonce_str	string	必填	随机字符串，防重放
sign	string	必填	RSA2 签名，见「签名规则」

响应参数

字段	类型	说明
code	string	业务状态码，`0000` 表示成功，其余见「状态码表」
message	string	状态描述
trade_no	string	平台交易单号（唯一），退款 / 查询可用
out_trade_no	string	原样返回商户订单号
prepay_data	object	唤起支付参数，结构随 `pay_type` 不同：微信返回 `appId/timeStamp/nonceStr/package/signType/paySign`；H5 返回 `pay_url`
sign	string	平台对响应的签名，商户应验签

报文示例

请求 JSON

Request · JSON

{
  "mch_id": "100000018",
  "out_trade_no": "T20260703001",
  "total_amount": 100,
  "pay_type": "WX_JSAPI",
  "subject": "会员充值",
  "openid": "oX7bt5A1b2C3d4E5f6G7h8I9",
  "notify_url": "https://shop.com/notify",
  "attach": "vip-2026",
  "nonce_str": "a1b2c3d4e5f6",
  "sign": "Ql3kZ8vN...9pXbQe4rT7"
}

响应 JSON

Response · JSON

{
  "code": "0000",
  "message": "success",
  "trade_no": "SQ2026070310000123456",
  "out_trade_no": "T20260703001",
  "prepay_data": {
    "appId": "wxa1b2c3d4e5f6a7b8",
    "timeStamp": "1751520000",
    "nonceStr": "c3d4e5f6g7h8",
    "package": "prepay_id=wx0310000123456",
    "signType": "RSA",
    "paySign": "kM8...tR2=="
  },
  "sign": "Z9xW...aB1cD2=="
}

5 · 订单查询接口

POST/v1/pay/query

根据商户订单号或平台单号查询订单最新状态。建议在未收到异步通知或需要对账时主动调用。

请求参数

字段	类型	必填	说明
mch_id	string	必填	商户号
out_trade_no	string	二选一	商户订单号，与 `trade_no` 二选一
trade_no	string	二选一	平台交易单号，与 `out_trade_no` 二选一
nonce_str	string	必填	随机字符串
sign	string	必填	RSA2 签名

响应参数

字段	类型	说明
code	string	业务状态码
trade_no	string	平台交易单号
out_trade_no	string	商户订单号
trade_state	string	交易状态：`SUCCESS` 支付成功 / `NOTPAY` 未支付 / `CLOSED` 已关闭 / `REFUND` 已退款
total_amount	int	订单金额（分）
success_time	string	支付完成时间，未支付时为空
sign	string	平台签名

报文示例

Request / Response · JSON

// 请求
{ "mch_id": "100000018", "out_trade_no": "T20260703001",
  "nonce_str": "9f8e7d6c", "sign": "Aa1Bb2...==" }

// 响应
{
  "code": "0000",
  "trade_no": "SQ2026070310000123456",
  "out_trade_no": "T20260703001",
  "trade_state": "SUCCESS",
  "total_amount": 100,
  "success_time": "2026-07-03 10:41:22",
  "sign": "Z9xW...aB1cD2=="
}

6 · 申请退款接口

POST/v1/pay/refund

对已支付成功的订单发起退款，支持部分退款。同一原订单可多次退款，退款总额不得超过订单金额。

请求参数

字段	类型	必填	说明
mch_id	string	必填	商户号
out_refund_no	string	必填	商户退款单号，同一商户下唯一
out_trade_no	string	必填	原商户订单号
refund_amount	int	必填	退款金额（分），≤ 可退余额
reason	string	选填	退款原因，≤ 80 字节
nonce_str	string	必填	随机字符串
sign	string	必填	RSA2 签名

响应参数

字段	类型	说明
code	string	业务状态码
refund_no	string	平台退款单号
out_refund_no	string	商户退款单号
refund_amount	int	本次退款金额（分）
refund_state	string	`PROCESSING` 退款中 / `SUCCESS` 退款成功 / `FAIL` 退款失败
sign	string	平台签名

报文示例

Request / Response · JSON

// 请求
{
  "mch_id": "100000018",
  "out_refund_no": "R20260703001",
  "out_trade_no": "T20260703001",
  "refund_amount": 100,
  "reason": "用户取消订单",
  "nonce_str": "7a6b5c4d",
  "sign": "Bb2Cc3...=="
}

// 响应
{
  "code": "0000",
  "refund_no": "SR2026070310000987654",
  "out_refund_no": "R20260703001",
  "refund_amount": 100,
  "refund_state": "PROCESSING",
  "sign": "Y8vU...9cD1=="
}

7 · 支付结果异步通知

用户支付成功后，平台会以 POST（application/json）主动推送结果到商户下单时传入的 notify_url。商户须验签成功后处理业务，并返回纯文本字符串 SUCCESS；否则平台将按 0/15s/30s/3m/10m/30m… 策略多次重推。

通知参数

字段	类型	说明
trade_no	string	平台交易单号
out_trade_no	string	商户订单号
trade_state	string	交易状态，通常为 `SUCCESS`
total_amount	int	订单金额（分）
success_time	string	支付完成时间
attach	string	下单时透传的自定义数据（若有）
sign	string	平台签名，商户须用平台公钥验签

通知示例与应答

Notify · JSON

// 平台 POST 到 notify_url 的报文
{
  "trade_no": "SQ2026070310000123456",
  "out_trade_no": "T20260703001",
  "trade_state": "SUCCESS",
  "total_amount": 100,
  "success_time": "2026-07-03 10:41:22",
  "attach": "vip-2026",
  "sign": "Z9xW...aB1cD2=="
}

// 商户应答（HTTP 200，纯文本 body）
SUCCESS

▲

幂等处理：同一订单可能收到多次通知，商户须以 out_trade_no 或 trade_no 做去重，确保发货 / 加款等业务只执行一次；处理成功后即返回 SUCCESS，重复通知直接返回 SUCCESS 即可。

ℹ

处理逻辑中不要以通知里的金额直接入账，应回查本地订单金额比对，防止金额被篡改；验签失败时返回非 SUCCESS 即可触发平台重推。

8 · 状态码 / 错误码

接口以 code 字段返回业务处理结果，0000 为成功，其余为各类失败。建议商户对下表错误码做统一映射与告警。

code	含义	说明 / 处理建议
0000	成功	请求处理成功
2001	参数错误	缺少必填参数或格式非法，检查请求体
2002	金额非法	金额非正整数或超限，须以「分」为单位
3001	签名验证失败	签名串拼接、密钥或算法有误，核对签名规则
3002	商户不存在或已禁用	核对 `mch_id` 与账户状态
4001	订单已存在	`out_trade_no` 重复，请更换订单号
4004	订单不存在	查询 / 退款时未找到对应订单
4005	订单状态不允许	如对未支付订单退款、对已退款订单重复退款
4006	退款金额超限	退款总额超过原订单可退余额
5001	上游通道异常	斗拱 / 汇付返回异常或超时，建议稍后重试或查单
5002	系统繁忙	平台内部异常，请重试；持续失败请联系集成

9 · pay_type 枚举

下表为本平台当前已开通的支付能力，下单时 pay_type 取以下值。

pay_type	渠道	场景	openid
WX_JSAPI	微信	微信公众号内 H5 支付（JSAPI）	必填
WX_LITE	微信	微信小程序支付	必填
ALI_H5	支付宝	支付宝手机网站 H5 支付	不需要

◆

更多渠道（银联云闪付、数字人民币等）正在接入中，如有需求可联系集成经理评估开通。