支付百科 · 第 5 篇
聚合支付接口对接流程:从签约到上线的 7 个步骤
聚合支付接口调通只是起点。真正决定系统能不能扛住高峰的,是回调验签、幂等控制与对账闭环。支付接口对接的这七个步骤,每一步都有具体的验收标准。
- 技术对接
- 代码示例
- 上线清单
一句话回答
聚合支付接口对接的核心不是「调通下单」,而是把回调验签、幂等控制、主动查单、对账闭环这四件事做对。下单成功只说明能收钱,后面三件决定你会不会赔钱。
第 1 步:环境与参数准备
聚合支付签约后会拿到四组参数:商户号、应用标识、签名密钥、回调地址配置权限。前三组分别对应「你是谁」「哪个应用」「怎么证明是你」。
要建立两套环境:沙箱用于开发自测,生产用于真实交易。两套环境的密钥不同,最容易犯的错是把沙箱密钥配到生产,表现为「本地全通、上线全错」。
# 建议的参数管理方式(不要硬编码)
PAY_MCH_ID=8001234567
PAY_APP_ID=app_9f3c2b1a
PAY_API_KEY=****(仅服务端可见,不进 Git)
PAY_NOTIFY_URL=https://api.your-domain.com/pay/notify
PAY_ENV=sandbox # sandbox | production
第 2 步:统一下单
调用下单接口,核心参数只有六个:商户订单号、金额(分)、支付方式、商品描述、回调地址、签名。其余为可选。
两个硬性约定:金额全程用「分」为整数,不用浮点;商户订单号在本地库建唯一索引。这两条是后面所有幂等逻辑的基础。
POST /v1/pay/unifiedorder
{
"mch_id": "8001234567",
"out_trade_no": "SHOP01-20261119-000137",
"total_fee": 128640,
"pay_type": "WECHAT_NATIVE",
"body": "门店A01-餐饮消费",
"notify_url": "https://api.your-domain.com/pay/notify",
"sign": "***"
}
# 返回
{ "code": 0, "trade_no": "2026111922001234567890",
"code_url": "weixin://wxpay/bizpayurl?pr=xxxx" }
第 3 步:发起支付
不同场景拿到的支付参数不同:Native 扫码返回二维码链接,JSAPI 返回前端调起参数,H5 返回跳转地址,刷卡返回付款码上送。前端只负责展示或调起,不参与签名。
这里有一个常见的安全问题:把签名密钥写进前端代码。只要密钥出现在浏览器里,就等于公开。所有签名必须在服务端完成。
第 4 步:处理异步回调
回调是聚合支付结果的主要来源,也是漏洞最多的地方。正确处理顺序是:
- 验签。用平台公钥或密钥验证签名,失败直接丢弃并记录日志。
- 校验商户号与金额。确认回调里的
mch_id是自己的,金额与本地订单一致。 - 幂等判断。查本地订单状态,已处理过则直接返回成功,不重复发货或加余额。
- 更新订单。用数据库事务更新状态,写支付流水。
- 返回成功标识。返回约定的成功响应,否则平台会按策略重推。
回调接口不要加登录校验、不要做 CSRF 防护、不要限制来源 IP 之外的复杂规则——平台请求不带你的 Cookie。同时要保证接口幂等,因为重复推送是设计行为,不是异常。
第 5 步:主动查单兜底
回调可能因为网络抖动、服务重启、部署窗口而丢失。关键业务必须有查单逻辑:前端轮询订单状态,后端定时任务扫描「支付中」超过 2 分钟的订单,主动调查单接口确认。
查单结果与回调冲突时,以查单为准。查单是主动请求,可信度高于被动通知。
第 6 步:退款
退款支持全额与部分,部分退款可多次。要记录每一次退款的独立退款单号,避免重复退款。退款是异步的,提交成功后状态为「退款中」,最终结果仍需回调或查询确认。
注意两个限制:退款金额不能超过原交易金额减去已退金额;部分通道要求原交易已结算后才能退款,未结算时会返回失败。
第 7 步:对账闭环
聚合支付接口调通不代表账对得上。上线后要建立日终对账:下载平台账单,与本地订单表按订单号比对,输出三类差异——本地有平台无(可能掉单)、平台有本地无(可能漏记)、金额不一致(可能被篡改)。
| 差异类型 | 常见原因 | 处理方式 |
|---|---|---|
| 本地有、平台无 | 下单请求未到达平台 | 关闭本地订单,允许用户重新下单 |
| 平台有、本地无 | 回调丢失或本地写库失败 | 以平台为准补单,补发权益 |
| 金额不一致 | 单位错误或参数被改 | 立即冻结订单,人工核查 |
上线前检查清单
- 密钥未出现在前端代码与代码仓库
- 订单号在库中有唯一索引
- 回调接口已验签、已校验金额、已幂等
- 有定时查单任务,覆盖支付中订单
- 退款有独立退款单号,防重复提交
- 日终对账脚本可运行,差异有告警
- 压测覆盖回调处理能力,非只压下单
- 生产环境已用真实小额交易跑通全流程
这八条聚合支付上线清单全部打勾,再放量。前六条缺失任何一条,都可能在高峰期变成资损。
需要帮助时
合付云的聚合支付接口提供沙箱环境、五种语言的示例代码与回调 Demo,可以直接部署验证。技术顾问会在对接群里响应,上线首周提供盯盘。完整的接口说明见支付通道对接页面。
支付接口对接的 6 个高频问题
以下回答基于我们 3200 家商户的真实对接记录整理。
对接需要多长时间?
有开发能力时,接口联调通常 3–5 个工作日。主要时间花在回调与对账逻辑,下单接口本身半天就能通。
回调收不到怎么办?
先确认回调地址公网可访问、未被防火墙拦截、接口未做登录校验。仍收不到时用查单接口兜底,并以查单结果为准。
金额为什么用分不用元?
避免浮点精度误差。0.1 + 0.2 在浮点运算中不等于 0.3,金额场景会直接导致对账不平。全链路统一用整数分。
重复回调会不会重复发货?
如果没有幂等控制就会。正确做法是在更新订单前判断状态,已处理过直接返回成功,不重复执行发权益逻辑。
退款多久到账?
提交成功后通常即时到账,部分通道 1–3 个工作日。退款是异步的,要以退款查询或回调的最终状态为准。
可以用前端直接调接口吗?
不可以。签名密钥必须保存在服务端,前端只能拿到调起支付的参数。密钥出现在浏览器里等于公开。