银联云闪付接入实操：全渠道报文、签名与对账文件

银联云闪付接入实操：全渠道报文、签名与对账文件

做国内收款时，支付宝和微信支付通常已经覆盖大部分用户，但在两类场景里银联仍然是必选项：一是企业客户与部分用户仍然偏好银行卡直接支付，二是线下收单与线上订单需要统一清结算。银联通道的产品定位见 中国银联。

需要提前说明的是：银联的接入体验与支付宝、微信差别很大。报文是表单式的 key=value 串、签名依赖商户证书、通知分前台和后台两条、对账要靠下载文件。第一次接入的团队往往要花比预期更多的时间。基础链路概念见 网站接入支付宝/微信支付教程。

一、接入前置条件

银联的商户体系与其他两家不同，通常需要经过收单机构或银联商务等渠道进件，而不是自己在开放平台注册就能开通。实际流程一般是：

1. 通过收单机构提交企业资质，完成商户进件；
2. 获得商户号（merId）与终端号（terminalId）；
3. 申请并下载商户证书（签名用 pfx 文件，含私钥与密码）；
4. 配置前后台通知地址，完成联调；
5. 在生产环境开通对应交易权限。

关键差异在于证书是文件形态并且带密码，不像支付宝那样纯字符串配置。证书文件属于高敏感资产，必须放在安全的密钥存储中，不能随代码提交。

二、报文结构与签名

银联全渠道的请求报文是 key=value&key=value 形式的表单串，不是 JSON 也不是 XML。签名流程是：

1. 把所有非空参数按字典序拼接成待签名串；
2. 用商户证书私钥做 SHA-256 + RSA 签名；
3. 对签名值做 Base64 与 URL 编码后作为 signature 字段一并提交；
4. 接收方用银联公钥验签。

四个高频错误点：

• 空值参数参与了签名：银联要求空值不参与签名，多带一个空字段就会验签失败；
• 编码不一致：报文编码与签名时的编码必须一致，中文参数尤其容易出问题；
• 证书用错环境：测试证书与生产证书不通用，混用会直接报签名错误；
• 时间戳超时：报文里的时间字段格式与服务器时间必须匹配。

三、前台通知与后台通知

这是银联设计里最需要适应的一点：两套通知并存。

前台通知（frontUrl） 是用户支付完成后浏览器跳回的地址，属于用户体验环节，不能作为支付成功的依据，因为用户可以关闭页面或网络中断导致跳转丢失。

后台通知（backUrl） 是银联服务器推送的异步结果，这才是可信来源。后台通知同样可能重复投递，必须做幂等。

正确做法是：前台跳回只用于展示"支付结果查询中"，真实状态由后台通知或主动查询确定。如果只依赖前台跳回，会稳定出现"用户付了钱但订单未发货"的工单。

四、常用交易类型

这里有一个国内通道特有的概念需要区分：撤销与退货不是一回事。撤销一般限于当日交易，撤销后原交易如同未发生；退货则是对已清算交易的反向操作，有独立的退款流水。做订单取消逻辑时必须先判断交易是否已清算，否则可能调错接口。

五、支付产品形态

银联的线上产品主要包括：

• 网关支付：PC 端跳转银联网银页面，用户输入卡号，覆盖借记卡与信用卡；
• WAP 支付：手机浏览器场景；
• 手机控件支付：原生 App 内调用；
• 银联二维码：生成二维码由用户用云闪付或银行 App 扫码。

选型逻辑与其他两家一致——按用户环境决定。需要注意的是，网关支付会离开你的站点进入银联网银页面，品牌体验上是割裂的，对转化率有影响；如果追求统一体验，二维码或控件支付更合适。

六、对账文件与差错处理

银联的对账不像支付宝、微信那样在商户后台点一下就能下载表格，通常是通过文件服务器按日期下载对账文件，由收单机构提供访问方式。文件里是当日全部交易明细，需要与本地订单做逐笔比对。

对账要做三件事：

1. 金额与笔数核对：总笔数、总金额先对平，再逐笔比对；
2. 状态比对：本地成功但银联无记录（可能丢单）、银联成功但本地无记录（可能漏单）；
3. 差错落表：每笔差异记录原因、处理人、处理结果，形成可追溯的差错台账。

标准对账方法论见 对账与账单下载操作手册，本文不重复。

七、与支付宝、微信的差异对照

理解这张表能省下大量排查时间：遇到问题时先确认自己是在哪个体系里排查，把支付宝的经验套到银联上很容易走错方向。

八、上线检查清单

商户号与终端号在配置中心统一管理；证书文件加密存储并按环境隔离；空值参数已在签名前过滤；前台通知只做展示不做入账；后台通知有幂等键并返回规范响应；查询接口已实现且纳入超时兜底；对账文件下载任务已定时化并有失败告警；差错台账有明确的处理人和 SLA。

微信侧的 APIv3 教程见 微信支付 APIv3 接入实操，支付宝侧见 支付宝开放平台接入实操，多通道统一接入的思路见 聚合支付与服务商模式。更多支付方案可参见 支付 分类。

来源：16IDC 原创，文中涉及的产品能力、费率与准入要求以 open.unionpay.com 等官网文档及合同为准。