业务系统对接
从部署到第一笔支付第七、八步已经跑通了系统内置的支付调试；本文讲的是下一步，让你的业务系统真正调用 unipay 开放接口：凭证从哪来、怎么保管，回调怎么联调，SDK 怎么选，错了去哪查。
本文讲操作与决策；请求参数、签名算法、报文格式等协议细节见接口文档。
凭证清单
业务系统接入需要以下四样东西，全部来自对接配置页面（商户端：商户中心 → 业务配置 → 对接配置；运营端可代管：商户工作台 → 业务配置 → 对接配置）：
| 凭证 | 获取操作 | 用途 |
|---|---|---|
商户号 mchNo | 商户列表 / 商户资料中查看 | 请求身份标识 |
应用号 appId | 应用管理卡片上查看（A 开头） | 调用隔离单元；不传则回落默认应用 |
| 商户私钥 | 对接配置 → 商户公钥区「生成密钥对」，私钥在弹窗中只展示一次 | 业务系统给请求签名 |
| 平台公钥 | 对接配置 → 平台公钥区「复制」 | 业务系统验证平台响应与回调的签名 |
可选：通信密钥（AES），用于接口敏感数据加解密，联调阶段可以先不配。
私钥丢失怎么办
商户私钥不展示第二次、平台侧不留存。丢失后只能在对接配置页重新「生成密钥对」并「保存」（旧公钥被覆盖，用旧私钥签名的请求会验签失败）。生成后立即妥善保存。
密钥保管规范
- 私钥禁止提交进代码仓库、禁止写死在代码里；通过环境变量或配置中心注入，生产环境建议独立于应用配置管理。
- 业务系统与平台各自只保管自己的私钥和对方的公钥，不交换私钥。
- 密钥按环境隔离：沙箱与生产使用不同的密钥对，避免测试系统用生产私钥签名。
回调通知联调
支付 / 退款结果通过异步回调推送给业务系统（notifyUrl 在下单时按请求传入）：
- 准备接收端：
notifyUrl必须是公网可达的 HTTP(S) 地址，与「后端 API 地址」的公网要求同理；本地联调可参照本地联调做内网穿透； - 验证回调链路：在支付调试页的「异步通知地址」填入你的接收地址并发起支付，确认服务端收到报文；
- 先验签再处理：回调报文带平台签名，必须先用平台公钥验签再处理业务，防止伪造通知；应答格式与重推规则见异步回调；
- 幂等处理：同一笔订单可能收到多次通知（重试机制存在），以订单号幂等去重；
- 查推送记录：平台侧在「回调通知 → 商户回调推送」可查看每次通知的发送记录与响应，失败任务可手动重推，这里是联调排错最先要看的地方。
本地能下单但收不到回调时，先看商户回调推送页：有记录且失败 → 检查你的接收端；无记录 → 检查下单参数里的 notifyUrl 是否正确。
SDK 选型
系统提供五语言官方 SDK，封装了请求签名、响应验签与回调验签，强烈建议直接使用，不要手写签名：
| 语言 | 适用场景 |
|---|---|
| Java | JVM 系业务系统（Spring Boot 等） |
| Go | Go 服务 / 云原生部署 |
| Node.js | Node 服务端 / 中间层 |
| PHP | 传统 PHP 业务系统 |
| Python | Python 服务 / 脚本工具 |
SDK 的引入方式、初始化配置与各接口调用示例见SDK 使用指南。手写对接（其他语言）时按签名机制实现，并用「签名调试」页（见下文）比对待签名串。
联调流程建议
- 沙箱环境不产生真实资金，接口行为与生产一致，尽量在沙箱把主流程与异常流（支付超时、退款）都过一遍；
- 沙箱仅「支付宝（直连）」支持；微信等其他通道无沙箱环境，用生产通道商户以小额真实支付验证；
- 切生产时需要替换三处：基础地址（后端 API 地址）、商户密钥对（建议生产重新生成）、通道商户（生产环境的通道商户与密钥）；
- 生产首笔用小额真实支付验证完整链路（含真实回调），确认后再放开业务。
排错工具
| 工具 | 位置 | 用途 |
|---|---|---|
| 支付调试(普通/网关) | 开发调试 | 不写代码复现下单、组参与签名全链路 |
| 签名调试 | 开发调试 | 输入参数与私钥复现待签名串与签名值；「签名验证」页签反向验证，排查验签失败首选 |
| 签名自检探针 | POST /unipay/ping | 发一笔最小的带签名请求：通 = 商户号/应用/私钥/签名串构造全对（见探活与自检） |
| 支付接口日志 | 系统管理 → 日志管理 → 支付接口日志 | 平台侧收到的完整请求 / 响应报文 |
| 商户回调推送 | 回调通知 | 平台→业务系统通知的发送记录与重推 |
| 通道回调记录 | 回调通知 | 通道→平台通知的接收记录 |
常见联调错误对照
| 现象 | 原因与处理 |
|---|---|
| 验签失败 / 签名不正确 | 私钥与平台上保存的商户公钥不配对（重新生成过密钥对？）；时间字段未按东八区 yyyy-MM-dd HH:mm:ss 传输；参数排序非字典序。用签名调试页比对待签名串 |
| 请求被拒绝：缺必填字段 | 检查 mchNo、reqId、reqTime、sign 与业务必填项；appId 不传时确认商户已配置默认应用 |
| 提示商户或应用不可用 | 商户被禁用、应用被停用或 appId 与商户号不匹配（对照应用配置的错误语义） |
| 下单成功但收不到回调 | 见「回调通知联调」第 5 步；本地环境可用订单「同步」主动拉取状态 |
| 回调收到了但业务没生效 | 未做幂等去重导致重复处理被业务侧拒绝，或验签失败被业务代码吞掉，先查接收端日志 |
| SDK 报解析错误 | 基础地址配错（带上了 /unipay 前缀或指向了前端地址）；对照 SDK 文档的环境配置 |
相关链接
- 接口文档：协议与字段参考
- SDK 使用指南：五语言 SDK
- 从部署到第一笔支付：前置的主线流程
- 完整上线指南 - 商户开通与对接就绪：生产环境密钥发放与就绪检查