支付通道对接
聚合支付通道对接:微信、支付宝接口如何一次接入
自己直连微信和支付宝,要分别签约、分别报备、分别处理签名与回调,通常需要 2–4 周。用聚合支付接口,一次对接就能覆盖全部通道,差异被收敛在平台侧。这篇讲清楚两种路径的取舍和对接细节。
- 服务商模式
- 一次签名全通道
- 沙箱可自测
- 幂等与重试
直接给结论
如果月交易量在 500 万以下、没有专职支付团队,走服务商模式的聚合支付接口成本最低:不用自己申请微信商户号与支付宝应用,不用处理两套签名算法,退款、对账、分账由平台统一。只有当你有极强的合规要求、或交易量大到需要直连议价时,直连才划算。
一、对接前先搞清三个概念
做聚合支付通道对接时,很多困惑来自把三个层级混在一起。理清之后,后面所有流程都会顺。
商户号
收单机构给你的身份标识,对应一个经营主体。一个营业执照可以有多个商户号,按门店或业务线区分。
子商户
服务商模式下,你的商户号被挂在服务商体系下,微信、支付宝侧看到的是「子商户」。结算仍直接到你的账户。
服务商
持有服务商资质、可以代商户发起报备的机构。合付云在这个层级,本身不是收单机构。
二、微信支付与支付宝接口申请的两种路径
| 对比项 | 直连模式 | 服务商模式(聚合支付接口) |
|---|---|---|
| 签约对象 | 分别与微信支付、支付宝签约 | 与持牌收单机构签一份协议 |
| 资质要求 | 需自行申请商户号、开通产品权限 | 由服务商代为报备 |
| 接入周期 | 2–4 周,含审核 | 1–3 个工作日 |
| 签名处理 | 两套算法(微信 v3、支付宝 RSA2) | 一套平台签名,通道差异由平台适配 |
| 退款与对账 | 分别在两个后台操作 | 统一接口与统一账单 |
| 费率 | 可能更低,但需达量议价 | 标准价,量大可谈 |
| 适合对象 | 大型平台、有支付团队 | 绝大多数中小与连锁商户 |
需要说明的是,服务商模式并不等于二清。判断标准仍然是资金路径:钱是持牌机构直接结算给你,还是先到服务商账户再转给你。前者合规,后者不合规,与是否走服务商模式无关。
三、聚合支付接口的对接流程
- 获取商户参数。签约后拿到
mch_id(商户号)、app_id(应用标识)、api_key(签名密钥)。密钥只用于服务端,不要写进前端代码或提交到代码仓库。 - 跑通下单。调用统一下单接口,传入金额(单位分)、订单号、支付方式、回调地址,拿到支付参数或二维码链接。
- 处理回调。顾客支付成功后,平台会向你配置的地址推送异步通知。必须验签、必须做幂等、必须返回成功标识,否则会重复推送。
- 主动查单兜底。回调可能因网络问题丢失。关键业务要在前端轮询或定时任务里调用查单接口,以查单结果为准。
- 退款与对账。退款走退款接口,支持部分退款;对账用日终账单文件,按订单号与本地库比对。
- 压测与灰度。正式放量前做一轮压测,重点看回调处理能力与数据库唯一索引是否生效。
四、签名、回调与幂等:三个最容易出错的点
4.1 签名:参数顺序与空值处理
签名失败是联调阶段最高频的问题,九成出在三个地方:参数没有按字典序排列、值为空的参数没有剔除、签名串拼接时多了一个 &。建议直接用平台提供的签名工具类,不要手写。
# 伪代码:统一下单请求体
{
"mch_id": "8001234567",
"out_trade_no": "SHOP01-20261119-0001", # 商户侧唯一,退款与查单都靠它
"total_fee": 128640, # 单位:分
"pay_type": "WECHAT_JSAPI",
"notify_url": "https://your-domain.com/pay/notify",
"body": "门店A01-餐饮消费",
"sign": "<按字典序拼接后计算>"
}
4.2 回调:验签之后还要做什么
验签只解决「这条消息是不是平台发的」。还需要校验三件事:金额是否与本地订单一致、订单状态是否已处理过、商户号是否匹配。三项都过了再改单,否则可能被伪造请求改掉订单状态。
4.3 幂等:同一笔订单不能扣两次
网络超时后重试是常态。要保证 out_trade_no 在库里有唯一索引,重复请求直接返回上一次的结果,而不是新建一笔订单。没有唯一索引的系统,在高峰期非常容易出现重复扣款,退款处理成本极高。
聚合支付通道对接完成后,建议先用真实小额交易跑一周再放量。这段时间主要看聚合支付侧的回调是否稳定、本地订单状态是否一致。
聚合支付通道对接完成后,建议先用真实小额交易跑一周再放量。这段时间主要看聚合支付侧的回调是否稳定、本地订单状态是否一致。
五、常见报错与排查
| 错误码 / 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 签名错误 | 参数排序、空值未剔除、密钥用错环境 | 用官方工具类重算,核对沙箱与生产密钥 |
| 订单号重复 | 重试时复用了同一单号但参数不同 | 同单号只允许同参数重试,否则新建单号 |
| 回调未收到 | 地址不可公网访问、被防火墙拦截 | 用公网地址,回调接口不要做登录校验 |
| 金额不匹配 | 单位用成了元,或浮点误差 | 全链路统一用「分」为整数 |
| 通道返回系统错误 | 通道侧限流或维护 | 平台自动切备通道,无需人工干预 |
| 退款失败 | 原交易未结算、超退款期限 | 等结算后重试,或改走线下退款并登记 |
六、我们能提供什么
合付云的聚合支付接口提供完整沙箱环境与测试商户号,你可以先自己跑通再决定是否签约。技术文档包含 Java、PHP、Python、Go、Node.js 五种语言的请求示例与验签代码,回调 Demo 可直接部署。
聚合支付聚合支付对接期间有专属技术顾问在群里响应,工作时间内 30 分钟回复,上线首周提供盯盘服务。如果需要,我们也可以协助你梳理现有系统的聚合支付改造点。提交对接需求后当天会拉群。
支付通道对接常见问题
以下回答基于我们 3200 家商户的真实对接记录整理。
对接支付通道需要什么技术能力?
服务端能发 HTTP 请求、能接收回调并做验签即可,主流语言都有现成 SDK。前端只需要展示二维码或调起支付。如果没有开发人员,用现成收银工具可以跳过整个对接环节。
微信支付和支付宝必须分别申请吗?
直连模式下需要分别申请。走服务商聚合模式时,由服务商代你完成子商户报备,你只需要提供营业执照与门店信息,不用自己跑两套申请流程。
回调地址必须是 HTTPS 吗?
建议使用 HTTPS。部分通道强制要求 HTTPS,HTTP 地址可能在审核阶段被拒。回调接口不要加登录态校验,也不要做 CSRF 防护,否则平台请求会被拦截。
沙箱环境和生产环境有什么区别?
沙箱不产生真实资金,用于验证签名、参数与回调逻辑。金额、商户号、密钥都与生产不同。上线前必须在生产环境用小额真实交易跑一遍全流程。
换服务商需要改代码吗?
如果原来用的是别家的聚合接口,需要做一次接口适配,通常 3–5 个工作日。如果原来是直连微信、支付宝,改造点会多一些,主要在签名与退款逻辑。
接口有调用频率限制吗?
有。下单接口按商户号限流,具体阈值与月交易量挂钩。查单接口限制较宽松,但也不建议高频轮询,推荐用回调加定时查单的组合。