聚合支付平台直连通道 · 持牌机构清算 · 已服务 3200+ 商户 · 7×24 小时技术支持

合付云 聚合支付平台 · 一码收全渠道

支付百科 · 第 5 篇

聚合支付接口对接流程:从签约到上线的 7 个步骤

聚合支付接口调通只是起点。真正决定系统能不能扛住高峰的,是回调验签、幂等控制与对账闭环。支付接口对接的这七个步骤,每一步都有具体的验收标准。

  • 技术对接
  • 代码示例
  • 上线清单

更新于 2026-11-06 阅读约 12 分钟 作者:陈默 信息更新至 2026 年 11 月

一句话回答

聚合支付接口对接的核心不是「调通下单」,而是把回调验签、幂等控制、主动查单、对账闭环这四件事做对。下单成功只说明能收钱,后面三件决定你会不会赔钱。

第 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 步:处理异步回调

回调是聚合支付结果的主要来源,也是漏洞最多的地方。正确处理顺序是:

  1. 验签。用平台公钥或密钥验证签名,失败直接丢弃并记录日志。
  2. 校验商户号与金额。确认回调里的 mch_id 是自己的,金额与本地订单一致。
  3. 幂等判断。查本地订单状态,已处理过则直接返回成功,不重复发货或加余额。
  4. 更新订单。用数据库事务更新状态,写支付流水。
  5. 返回成功标识。返回约定的成功响应,否则平台会按策略重推。

回调接口不要加登录校验、不要做 CSRF 防护、不要限制来源 IP 之外的复杂规则——平台请求不带你的 Cookie。同时要保证接口幂等,因为重复推送是设计行为,不是异常。

第 5 步:主动查单兜底

回调可能因为网络抖动、服务重启、部署窗口而丢失。关键业务必须有查单逻辑:前端轮询订单状态,后端定时任务扫描「支付中」超过 2 分钟的订单,主动调查单接口确认。

查单结果与回调冲突时,以查单为准。查单是主动请求,可信度高于被动通知。

第 6 步:退款

退款支持全额与部分,部分退款可多次。要记录每一次退款的独立退款单号,避免重复退款。退款是异步的,提交成功后状态为「退款中」,最终结果仍需回调或查询确认。

注意两个限制:退款金额不能超过原交易金额减去已退金额;部分通道要求原交易已结算后才能退款,未结算时会返回失败。

第 7 步:对账闭环

聚合支付接口调通不代表账对得上。上线后要建立日终对账:下载平台账单,与本地订单表按订单号比对,输出三类差异——本地有平台无(可能掉单)、平台有本地无(可能漏记)、金额不一致(可能被篡改)。

差异处理原则
差异类型常见原因处理方式
本地有、平台无下单请求未到达平台关闭本地订单,允许用户重新下单
平台有、本地无回调丢失或本地写库失败以平台为准补单,补发权益
金额不一致单位错误或参数被改立即冻结订单,人工核查

上线前检查清单

  • 密钥未出现在前端代码与代码仓库
  • 订单号在库中有唯一索引
  • 回调接口已验签、已校验金额、已幂等
  • 有定时查单任务,覆盖支付中订单
  • 退款有独立退款单号,防重复提交
  • 日终对账脚本可运行,差异有告警
  • 压测覆盖回调处理能力,非只压下单
  • 生产环境已用真实小额交易跑通全流程

这八条聚合支付上线清单全部打勾,再放量。前六条缺失任何一条,都可能在高峰期变成资损。

需要帮助时

合付云的聚合支付接口提供沙箱环境、五种语言的示例代码与回调 Demo,可以直接部署验证。技术顾问会在对接群里响应,上线首周提供盯盘。完整的接口说明见支付通道对接页面。

陈

关于作者

陈默 合付云支付方案负责人,8 年收单与聚合支付从业经历,服务过 200+ 连锁商户的收款系统改造。

支付接口对接的 6 个高频问题

以下回答基于我们 3200 家商户的真实对接记录整理。

对接需要多长时间?

有开发能力时,接口联调通常 3–5 个工作日。主要时间花在回调与对账逻辑,下单接口本身半天就能通。

回调收不到怎么办?

先确认回调地址公网可访问、未被防火墙拦截、接口未做登录校验。仍收不到时用查单接口兜底,并以查单结果为准。

金额为什么用分不用元?

避免浮点精度误差。0.1 + 0.2 在浮点运算中不等于 0.3,金额场景会直接导致对账不平。全链路统一用整数分。

重复回调会不会重复发货?

如果没有幂等控制就会。正确做法是在更新订单前判断状态,已处理过直接返回成功,不重复执行发权益逻辑。

退款多久到账?

提交成功后通常即时到账,部分通道 1–3 个工作日。退款是异步的,要以退款查询或回调的最终状态为准。

可以用前端直接调接口吗?

不可以。签名密钥必须保存在服务端,前端只能拿到调起支付的参数。密钥出现在浏览器里等于公开。

先用 1 个门店试跑,跑通再谈扩张

提交门店信息后,顾问会在 15 分钟内联系你,给出费率方案、对接文档和上线排期。全程不收开通费,不绑设备采购。