应用配置
应用(appId)是商户下的调用与配置隔离单元:unipay 接口按应用区分来源,通道路由、网关支付、收银台等配置都挂在应用维度。
菜单路径:商户工作台 → 支付配置 → 应用管理(运营端);商户端 → 商户中心 → 支付配置 → 应用管理(数据同源)。
应用管理
应用列表是卡片网格(非表格):每张卡片展示应用名称、appId、启用状态与「默认」标签,点击卡片进入该应用的应用工作台。
新增 / 编辑应用的表单只有三个字段:
| 字段 | 说明 |
|---|---|
| 应用名称 | 自定义名称 |
| 状态 | 启用 / 禁用 |
| 默认应用 | 仅编辑态可改的开关 |
appId 由系统自动生成(A 开头),创建后不可修改,表单中不出现。
默认应用规则
- 商户的第一个应用创建时自动设为默认;同商户至多一个默认应用。
- unipay 请求不传 appId 时回落默认应用;显式传 appId 则按传入值路由。
- 相关错误语义:未传且无默认应用、默认应用被停用、传入的 appId 不存在或被停用、appId 与商户号不匹配,分别返回不同错误码,便于定位。
| 场景 | 后果 |
|---|---|
| 停用默认应用 | 不指定 appId 的下单会失败(页面会二次确认提醒) |
| 删除默认应用 | 被禁止,先转移默认再删除 |
| 无默认应用 | 列表顶部黄色警告条提示设置默认 |
应用工作台
从应用卡片「进入配置」进入,分两组磁贴:
支付配置
| 卡片 | 功能 |
|---|---|
| 通道路由 | 指定本应用各支付方式走哪个通道商户(多通道分流) |
| 网关支付配置 | 码牌 / 聚合支付在各客户端环境下的路由深度 |
| 收银台配置 | 收银台页面在各环境下的支付方式展示 |
| 异步通知配置 | 业务事件回调地址、通知方式(HTTP / MQ)与订阅事件,当前版本界面建设中 |
| 易支付配置 | 兼容易支付 V1/V2 协议接入,详见易支付插件 |
应用管理:编辑基本信息、设为 / 取消默认应用、删除应用(强确认,需输入应用名)。
通道路由
决定「某笔支付走哪个通道商户」的基础配置,两种策略模式二选一生效(工具栏可「设为当前生效」):
| 模式 | 配置粒度 | 适合 |
|---|---|---|
| 按渠道默认 | 每个支付渠道(微信 / 支付宝 / 银联 …)配一个默认通道商户 | 单通道或简单主备 |
| 按支付方式 | 每个支付方式(wechat_jsapi、alipay_qr …)配「通道商户 + 支付能力」 | 不同方式走不同通道的精细分流 |
网关支付配置
码牌、聚合支付等网关链路的路由配置,维度是「客户端环境 × 支付形态」(微信 / 支付宝 / 云闪付 / 抖音环境 × H5 / 小程序),每格三种模式:
| 模式 | 语义 |
|---|---|
| 跟随通道路由 | 使用通道路由的解析结果(推荐起点) |
| 指定支付方式 | 该格固定走某个支付方式 |
| 直接指定 | 直接选「通道商户 + 支付能力」,跳过路由(排错 / 特殊场景) |
页面下方内置路由预览:展示当前路由命中情况(命中数 / 总数)与待补全缺口,可一键跳转通道路由补配。
收银台配置
配置统一收银台页面在各环境下展示的支付项:一级分 H5 / WEB / 小程序,H5 与小程序再按客户端环境(浏览器 / 微信 / 支付宝 / 云闪付 / 抖音)分桶,每个桶内维护支付项列表(名称、图标、推荐标记、排序、解析方式与支付方式)。
异步通知配置(建设中)
当前版本界面建设中,开放后将支持:通知方式二选一——HTTP 回调(填回调地址,按订阅事件推送支付成功 / 失败 / 关闭 / 超时、退款成功 / 失败 / 关闭等事件)或 MQ 推送(按应用隔离的 Topic,商户侧持久订阅、离线不丢消息)。回调链路排查当前可先用商户回调推送页。
三个配置的关系
通道路由是底层路由策略;网关支付配置决定网关链路(码牌 / 聚合)用多深的路由;收银台配置只决定收银台页面的展示项。初次配置建议:先配通道路由,网关支付保持「跟随」,收银台按需调整展示。