:8161/ | grep -i '^date' # broker 侧时间(秒级精度)
date # 本机时间
```
## 修复
两台机器均开启 NTP 对时。
Linux 服务器(broker 所在主机):
```bash
timedatectl # 查看 "System clock synchronized" 与 "NTP service" 状态
sudo timedatectl set-ntp true # 未开启时先开启 timesyncd
# 系统未装 timesyncd 时,安装 chrony 接管(RHEL 系用 dnf,服务名为 chronyd):
sudo apt install chrony && sudo systemctl enable --now chrony
chronyc tracking # 验证:Leap status 为 Normal 即已同步
```
Windows 开发机(本地跑后端连远程 broker 的场景):
```powershell
w32tm /query /status # 查看时间服务状态与上次成功同步时间
# 以下两条需管理员终端执行:
w32tm /resync # 立即校时(机器休眠唤醒后时钟漂移,可手动执行)
w32tm /config /syncfromflags:manual /manualpeerlist:"ntp.aliyun.com time.windows.com" /update
# time.windows.com 通路不稳时切换国内 NTP 源
```
一键部署(运维面板)部署中,应用与 Artemis 为**同一宿主机**上的容器,共享内核时钟,天然不存在此问题。该问题常见于「本地跑后端 + 远程 broker」的开发拓扑,以及自行跨机部署 broker 的场景 —— 跨机部署时 NTP 对齐是延时消息精度的硬前提。
## 相关链接
- [返回 FAQ](https://doc.plus.daxpay.cn/getting-started/faq/.md)
- [配置说明 - Artemis 消息队列](https://doc.plus.daxpay.cn/deployment/configuration.md#artemis-消息队列)
---
# 常见问题
**源**: https://doc.plus.daxpay.cn/getting-started/faq.md
# 常见问题
汇总 DaxPay Plus 使用、部署、通道对接与二次开发中高频出现的疑问,按主题分组。多数条目附带指向专题排查页或相关章节的链接,深入细节请跳转阅读。
## 基础概念
### DaxPay Plus 是什么
DaxPay Plus 是 DaxPay 开源版的**商业增强版**,将支付宝、微信、银联等多种支付通道封装为**统一的 HTTP 接口**,提供支付、退款、分账、查询、回调等支付核心能力;并在开源核心之上补齐**代理商体系、商户进件、全量风控、商户限额**四块商用能力。详见[项目介绍](https://doc.plus.daxpay.cn/getting-started/introduction.md)。
### 和开源版是什么关系
fork 自 DaxPay 开源版,技术栈同源。开源版提供完整支付核心与运营/商户两端;Plus 在此基础上增加代理商端、进件审核、四层风控、限额与费率体系等商用增强,并配套全端管理界面。差异对比见[项目介绍 - 与开源版的关系](https://doc.plus.daxpay.cn/getting-started/introduction.md#与开源版的关系)。
### 支持哪些数据库
仅支持 **PostgreSQL 14+**,不支持 MySQL / Oracle 等。时间字段统一 `timestamp(6)`(无时区),实体使用 `LocalDateTime`,**全系统按东八区口径**处理时间。
## 部署运行
### 后端编译必须用 mvnd 吗
项目约定使用 mvnd(Maven Daemon)加速编译。普通 `mvn` 也能编译,但 mvnd 自带守护进程,增量编译速度显著更快,推荐使用。详见[项目构建](https://doc.plus.daxpay.cn/deployment/build.md)。
### PowerShell 下 mvnd 编译参数报错
PowerShell 下含 `=` 的 `-D` 参数会被空格拆分,必须加引号:
```powershell
# 错误 — 会被拆分
mvnd compile -Dmaven.test.skip=true
# 正确 — 加引号
mvnd compile "-Dmaven.test.skip=true"
```
### Apache Artemis 能否替换为其他消息队列
当前版本**强依赖 Artemis**(用于支付延时通知等 JMS 场景),不支持直接替换为 RabbitMQ / Kafka。如需替换需自行改造消息中间件适配层。
### 延时消息提前或延后投递怎么办
**现象**:延时消息设置 10 秒,约 6 秒就被消费;或设置 5 秒,过了 8 秒才收到。
**原因**:应用与 Artemis broker 跨机器部署且两机时钟不一致,延时消息按绝对时间戳投递,实际延时被平移两机时钟差。
**修复**:两台机器均开启 NTP 对时,详见[延时消息时钟偏差](https://doc.plus.daxpay.cn/getting-started/delay-message-clock-skew.md)。
### 套了 CDN 后登录报「请求验证已失效」或「请求时间戳已过期」怎么办
**现象**:本地直连后端一切正常,套上 CDN(腾讯 EdgeOne、CloudFlare 等)后登录必报「请求验证已失效,请重试」或「请求时间戳已过期,请重试」。
**原因**:登录防重放机制要求每次登录先取一个**一次性 nonce**,CDN 把这类接口的响应缓存后,所有用户拿到同一份旧 nonce;图形验证码接口被缓存同理(所有人看到同一张图)。
**修复**:在 CDN 给所有 API 路径(`/api/*` 及网关域名的 `/unipay/*`、`/client/*`、`/epay/*`)配置**不缓存**规则,详见[CDN 部署注意事项](https://doc.plus.daxpay.cn/getting-started/cdn.md)。
### 套了 CDN 后站内通知一直断开重连怎么办
**现象**:浏览器控制台反复报 `ERR_HTTP2_PROTOCOL_ERROR 200 (OK)` 之类的连接中断错误,通知消息要刷新页面才能看到,该请求按固定间隔断开重连。
**原因**:站内通知走 SSE 长连接,靠服务端周期性心跳维持;链路中间任何一层(CDN 回源超时、代理超时)等不到数据时,会在浏览器已收到 200 之后把连接掐断,前端随即自动重连。
**修复**:在 CDN 给 `/api/notify/*` 配置**回源超时 ≥ 60 秒**(须大于 10 秒的心跳间隔);EdgeOne 注意规则要配到站点实际所在的「中国大陆 / 全球」环境才生效。详见[站内通知(SSE)断开重连排查](https://doc.plus.daxpay.cn/getting-started/sse-disconnect.md)。
### 上传文件报跨域(CORS)错误怎么办
**现象**:「测试连接」通过,但上传文件时报跨域错误(`No 'Access-Control-Allow-Origin' header ...`)或直接失败。
**原因**:预签名直传是浏览器直连对象存储的跨域请求,桶上未放行跨域规则;后端「测试连接」不经过浏览器,测不出这个问题。
**修复**:在桶上配置跨域规则——来源填三端 Web 与 H5 收银台的地址(联调可用 `*`)、方法必须含 `PUT`、暴露响应头加 `ETag`;Cloudflare R2 的 `*` 只能写在 `AllowedOrigins`。详见[存储跨域(CORS)配置与上传排查](https://doc.plus.daxpay.cn/getting-started/oss-cors.md)。
### 容器化部署最低配置
纯后端全家桶(含 PostgreSQL / Redis / Artemis / 主应用 / 两个通道子应用)容器化跑通联调,**2 核 4G** 可用;生产建议 **4 核 8G** 起步,并按交易量增长评估资源。使用运维面板一键部署的,生产服务器建议 **8 GB 内存**起步,详见[面板安装 - 安装前提](https://doc.plus.daxpay.cn/tools/panel/install.md#安装前提)。
## 一键部署与运维面板
使用[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md)或[运维面板](https://doc.plus.daxpay.cn/tools/panel/overview.md)时的高频问题,完整的分阶段排查步骤见运维面板[故障排查](https://doc.plus.daxpay.cn/tools/panel/configuration.md#故障排查)。
### 在线安装下载失败或校验不通过
常见原因是下载源异常或网络受限。重新执行安装命令再试;仍失败改用[离线安装](https://doc.plus.daxpay.cn/tools/panel/install.md#离线安装)。注意 SHA256 校验失败时安装会直接终止,不会跳过校验强行安装。
### 离线安装没反应、提示在线下载
`install.sh` 与 `.xz` 安装包必须在**同一个目录**(脚本只探测自身所在目录,不探测当前工作目录),且两个文件须来自同一版本,用 `bash install.sh` 执行。
### 安装完成访问 IP:端口返回 404
面板默认开启**安全入口**:访问地址是 `IP:端口/随机入口路径` 的完整形式,直接访问 IP 和端口返回 404 属正常防护。忘记入口时执行 `daxpay-plus entrance show` 查看完整地址,详见[面板安装](https://doc.plus.daxpay.cn/tools/panel/install.md)。
### 忘记面板初始密码或登录被锁定
`daxpay-plus info` 查看首次启动生成的初始管理员凭据;改过又忘了用 `daxpay-plus reset-password` 重置(会吊销全部已登录会话);连续输错被锁定用 `daxpay-plus unlock` 解锁。详见[命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)与[面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md)。
### 端口冲突(18060 / 80 / 443)
面板默认占用 18060,统一网关监听 80/443(HTTPS 由外层 CDN / 网关终结)。停掉占用进程,或用 `--port` 换面板端口;总览页也会列出端口冲突提示。
### 业务后端容器 unhealthy 反复重启
常见根因是数据库密码为空,或业务侧与中间件侧密码不一致,导致认证失败。在基础环境服务卡片「查看密码」确认密码非空,用「配置」抽屉的「修改密码」对齐后重启业务容器。
### 页面出现 drift(漂移)横幅
提示「重新部署 <某服务>」= 该服务的端口/内存/暴露模式改了未生效,点击只重建这一个容器;提示整栈「重新部署」= 版本/JVM/内存档位等栈级变更未生效,需重建所有已启用容器;提示「应用网关配置」= 网关配置改动未应用,点击应用即可,无需重建容器。
### 明明部署了,面板却显示「未部署」
「已部署」判定基于运行时容器探测 + 部署快照。手动用 `docker compose` 拉起的容器,面板会自动补齐快照自愈;仍未识别就到对应页面点一次「部署」让面板接管。
## 支付通道对接
### 已支持哪些支付通道
共 **16** 个通道,分两组承载:
- **直连通道**(子应用1,`daxpay-plus-channel-one`)— 支付宝、微信、抖音、银联(云闪付)、银联商务
- **聚合通道**(子应用2,`daxpay-plus-channel-two`)— 拉卡拉、乐刷、富友、海科融通、盛付通、随行付、易宝、河马付、Adapay(汇付)、斗拱(汇付)与易支付协议通道
通道明细与配置结构见[支付通道总览](https://doc.plus.daxpay.cn/extension/channels/.md)。
### channel-one / channel-two 有什么区别
两个通道子应用架构完全相同(无状态、不连中间件、报文 AES-GCM 加密传输),区别只在**承载的通道集合与端口**:子应用1(端口 10100)承载官方 SDK 直连通道,子应用2(端口 10200)承载聚合通道 SDK。主应用通过 `daxpay.channel.one/two.base-url` 路由,子应用编号固定不可改名。
### 通道子应用必须独立部署吗
是的。通道子应用独立部署是 DaxPay 的核心设计——将第三方 SDK 隔离到子应用,避免 SDK 依赖污染主应用,支持独立升级与维护;主应用经声明式 HTTP 客户端调用,链路全程加密。一键部署已将两个子应用纳入统一编排,自建部署时需单独拉起。架构说明见[架构总览](https://doc.plus.daxpay.cn/getting-started/architecture-overview.md)。
### 支付报「通道服务不可用」或回调不推进怎么办
**现象**:发起支付/退款报「通道服务不可用,连接未建立」「通道子应用返回明文错误响应」等错误,或通道回调已收到但订单一直不推进。
**原因**:主应用与通道子应用(10100/10200)之间的 HTTP + AES-GCM 链路不通——子应用未启动、端口不可达,或两侧传输密钥(`transport-encrypt.key` / `CHANNEL_TRANSPORT_KEY`)不一致。
**排查**:按「进程在不在 → 端口通不通 → 两侧密钥/路由配置是否一致」的顺序排查,详见[通道子应用通信失败排查](https://doc.plus.daxpay.cn/getting-started/channel-subapp.md)。
### 微信服务商支付报「受理机构必须传入sub_mch_id」怎么办 {#wechat-isv-sub-mch-id}
**现象**:服务商模式发起支付时报「受理机构必须传入sub_mch_id」,但请求参数里的 `sub_mchid` 明明有值。
**原因**:这条报错文案有误导性——它真正的含义是微信对「服务商 ↔ 特约商户」绑定关系的校验失败,不是字段缺失。最常见的触发是服务商自己的商户号被填进了特约商户号位置。
**修复**:普通商户改配微信直连;服务商的特约商户号必须填进件绑定的真实二级商户号。详见[微信服务商支付报错](https://doc.plus.daxpay.cn/getting-started/wechat-isv-sub-mch-id.md)。
### 进件申请单创建后还能换服务商吗
不能。申请单**创建即锁定归属服务商**,后续流程都在该服务商名下推进;对外锚点始终是商户号与通道商户号,不暴露服务商细节。确实需要换服务商的,将原申请单**作废后重新发起**。详见[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)与[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)。
### 如何新增一个支付通道
1. 在对应通道子应用仓(直连走 `daxpay-plus-channel-one`,聚合走 `daxpay-plus-channel-two`)的 `daxpay-channel-impl` 下实现 SDK 调用与签名/验签
2. 在主应用 `daxpay-channel` 模块注册通道策略与配置数据 CRUD
3. 在 `ChannelEnum` 补充通道枚举
新增通道只需实现 SDK 调用并注册策略,不影响主链路。
## 功能边界
### 是否支持分账
支持支付宝、微信、抖音等通道的分账。使用流程:统一下单时声明 `allocation=true` 创建分账订单 → 通过开放接口[发起分账](https://doc.plus.daxpay.cn/api/payment/alloc.md)、[查询](https://doc.plus.daxpay.cn/api/query/alloc-order.md)或[同步](https://doc.plus.daxpay.cn/api/payment/alloc-sync.md);分账接收方需提前完成绑定,操作说明见[支付分账](https://doc.plus.daxpay.cn/common/alloc.md)。
### 是否支持国际支付(PayPal / Stripe)
当前版本未接入国际通道(Stripe、PayPal 等),境外卡支付暂不可用,属后续规划方向。
### 沙箱环境怎么用
DaxPay 采用**部署级沙箱隔离**:
- 测试 / 开发环境配置 `sandbox-enabled=true`,允许沙箱联调
- **生产环境必须配置** `sandbox-enabled=false`,启动时会强制将所有 `activeEnv=sandbox` 的产品重置为 `prod`,保证生产数据纯净
沙箱联调请走独立的测试环境部署,生产数据库严禁从测试环境导入数据。详见[配置说明 - 部署模式与生产校验](https://doc.plus.daxpay.cn/deployment/configuration.md#部署模式与生产校验)。
### 是否支持多商户 / 多商户隔离
支持,而且是三级运营结构:运营端 + 代理商端 + 商户端,商户数据按商户编号**行级隔离**,代理商只见名下商户(见[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md));单商户可配置多个支付应用,独立凭证与回调地址。
### 是否支持预授权 / 支付分
支持(plus 独有实装):支付宝预授权(授权/请款/转支付/退款)与微信支付分(独立域、需确认模式)分开建模,入口在运营端「交易管理」下。能力边界详见[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)。
## 配套工具
### 模拟联调通道是什么, 怎么接入
独立部署的模拟通道子应用,扮演三方支付平台,用于真实通道未下号时的全链路联调、POC 演示与异常演练。接入分五步:建模拟通道商户 → 纳入通道路由 → 配回调地址 → 对齐传输密钥 → 重启验证。完整步骤与失败对照见[模拟联调通道 - 接入配置](https://doc.plus.daxpay.cn/tools/mock/setup.md),工具定位与安全边界见[工具概览](https://doc.plus.daxpay.cn/tools/mock/.md)。
### 压测验收工具、收款播报 APP 的文档在哪
统一收在[配套工具总览](https://doc.plus.daxpay.cn/tools/.md)。其中运维面板与模拟联调通道文档已可用;压测验收工具与收款播报 APP 的正文在编写中,当前请先看交付包内 README 与管理台内文档,补齐后总览页会更新入口。
## 二次开发
### 能否修改源码用于自己的项目
商业版按授权协议交付源码。你可以在授权范围内修改源码、用于自有业务;具体权利与义务以你所签署的授权协议为准。业务系统通过 HTTP 接口对接时,自身代码不涉及平台源码分发问题。
### 前端如何对接后端接口
前端通过 RESTful HTTP 接口对接主应用(dev 端口 19999),接口请求 / 响应支持 **RSA 签名**防篡改,认证基于 **Sa-Token**(token name: `Accesstoken`)。详细接入方式见[接口总览](https://doc.plus.daxpay.cn/api/overview.md)与[签名机制](https://doc.plus.daxpay.cn/api/signature.md)。
### 数据库表结构在哪?如何初始化
SQL 脚本位于主应用仓库 `_config/sql/` 目录,全新安装顺序为 `table.sql`(建表)→ `data.sql`(初始数据)→ `iam_perm_menu.sql`(菜单种子,第三步为菜单权威)。仓内另提供升级脚本 `update-tables.sql` → `update-datas.sql`(不能跨版本)。详见[项目构建 - 数据库准备](https://doc.plus.daxpay.cn/deployment/build.md#数据库准备)。
### 为什么缓存会出现「只读 L1、不读写 Redis」的情况
**这不是普通缓存的常规形态,而是敏感缓存的安全降级保护**:缓存名命中敏感名单(`secure:` 前缀等)、且平台数据加密未启用时,敏感数据被禁止明文写入 Redis,仅写 L1 本机内存、读侧直接穿透。启用数据加密后自动恢复 L1+L2 双层。完整行为矩阵见[缓存只读 L1 降级说明](https://doc.plus.daxpay.cn/getting-started/cache-l1-readonly.md)。
## 相关链接
- [项目介绍](https://doc.plus.daxpay.cn/getting-started/introduction.md)
- [功能特性](https://doc.plus.daxpay.cn/getting-started/features.md)
- [架构总览](https://doc.plus.daxpay.cn/getting-started/architecture-overview.md)
- [快速开始](https://doc.plus.daxpay.cn/deployment/run.md)
- [接口总览](https://doc.plus.daxpay.cn/api/overview.md)
---
# 存储跨域(CORS)配置与上传排查
**源**: https://doc.plus.daxpay.cn/getting-started/faq/oss-cors.md
# 存储跨域(CORS)配置与上传排查
平台的文件上传走「预签名直传」:浏览器向后端申请一个预签名地址,然后**由浏览器直接把文件传到对象存储**,
文件不经过后端。这一步是「页面 → 对象存储」的跨域请求,桶上没有放行跨域规则时,浏览器会在发出真实请求**之前**就拦下它。
这个问题的麻烦之处在于:**「测试连接」是通过的**。测试连接是后端服务器发起的探测,不经过浏览器,
天然测不出跨域问题。密钥、权限、桶是否存在它都能测,唯独测不出 CORS。
> **真实案例**:2026-10 有部署使用 Cloudflare R2,把「允许请求头 / 暴露响应头」也写成 `*`,控制台保存时只报「此策略无效」。
> 根因是 R2 的策略校验只允许 `*` 出现在 `AllowedOrigins`,两个头字段必须逐个列名。
## 现象
- 浏览器控制台报 `No 'Access-Control-Allow-Origin' header is present on the requested resource`
(或带 `CORS policy` 字样的报错);
- 上传转圈后失败,但**后端日志里找不到对应请求**(预检阶段就被浏览器拦下),「测试连接」却通过、密钥权限都正常;
- 小程序 / APP 端能传,Web 端不能传(只有浏览器环境受同源策略约束)。
## 先分清是不是 CORS
「上传失败」至少有三种成因,混在一起会把排查带偏:
| 现象 | 真实原因 | 判别方法 |
|-----|---------|---------|
| 控制台报 CORS 字样,后端无请求日志 | 桶的跨域规则未放行 | 见下方「验证」一节 |
| 请求一直 pending / 连接超时 / 网络错误 | 预签名地址不可达(服务端点填了内网地址、防火墙拦截) | 用 curl 直接传预签名地址(**服务端请求不受 CORS 限制**),能通则与 CORS 无关 |
| 上传返回 403 `AccessDenied` | 密钥缺权限 / 桶策略拒绝 / 预签名已过期 | 看后端日志或 curl 的真实状态码 |
一句话判别法:**curl 能传成功、浏览器报 CORS = 跨域配置问题;curl 也失败 = 与 CORS 无关**,去查端点与权限。
## 修复
跨域规则就四个要素:来源(三端 Web 与 H5 收银台的地址,联调阶段可用 `*`)、方法(必须含 `PUT`)、允许请求头(`*`;Cloudflare R2 需逐个列名)、暴露响应头(建议加 `ETag`)。各厂商控制台入口与 R2 可粘贴策略见下方。
### 通用四要素
各厂商控制台的位置与命名不同,但语义一一对应:
| 配置项 | 建议值 | 说明 |
|-------|---|-----|
| 来源 Origin / AllowedOrigins | 三端 Web 与 H5 收银台的访问地址;联调阶段可先用 `*` | 只填 `scheme://host[:port]`,不带路径、不带尾斜杠,端口不能用通配符 |
| 方法 Methods / AllowedMethods | `PUT, GET, HEAD, POST` | 上传走 `PUT`,读取与回显走 `GET`/`HEAD`;只勾 `GET` 会让上传的预检请求失败 |
| 允许请求头 AllowedHeaders | `*`(Cloudflare R2 需逐个列名) | 至少覆盖浏览器实际发送的请求头,取值方法见下 |
| 暴露响应头 ExposeHeaders | `ETag` | 前端要做 ETag/MD5 校验必须显式列出,否则 JS 读不到该响应头 |
关于来源填 `*`(允许所有来源):预签名 URL 的签名在 query 参数里、不携带 Cookie,所以通配符可用;
若哪天改成携带 Cookie 的跨域调用,浏览器不允许「通配符 + 凭证」并存,必须改成具体域名。
不知道要放行哪些请求头时不要去猜:开发者工具 → Network → 上传时那条 `OPTIONS` 预检请求 → `Access-Control-Request-Headers` 头列出的名字,就是清单。
### 各厂商入口
| 厂商 | 位置 | 备注 |
|-----|---|-----|
| MinIO | 无桶级界面,由服务端变量 `MINIO_API_CORS_ALLOW_ORIGIN` 控制 | 自建场景通常无需配置 |
| 阿里云 OSS | 桶 → 数据安全 → 跨域设置 | `*` 可用于来源与两个头字段;除来源和方法外,别忘了单独加暴露响应头 `ETag` |
| 腾讯云 COS | 桶 → 安全管理 → 跨域访问 CORS 设置 | 同上;控制台的「暴露 Headers」即 `ETag` 的位置 |
| Cloudflare R2 | 桶 → Settings → CORS Policy(JSON 编辑) | `*` **只能写在 `AllowedOrigins`**,两个头字段必须逐个列名 |
### R2 可粘贴策略
R2 的 CORS Policy 用 JSON 编辑,下面的策略可直接粘贴使用:
```json
[
{
"AllowedOrigins": ["*"],
"AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
"AllowedHeaders": [
"Content-Type",
"Content-Length",
"Content-MD5",
"Authorization",
"x-amz-acl",
"x-amz-date"
],
"ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Last-Modified"],
"MaxAgeSeconds": 3600
}
]
```
注意 R2 **只有 `AllowedOrigins` 支持 `*`**,`AllowedHeaders` / `ExposeHeaders` 必须逐个列名;
需要放行更多请求头(如 `Content-Disposition`、自定义元数据 `x-amz-meta-*`)时逐个追加到 `AllowedHeaders`。
控制台保存不了时,可改用官方 CLI `npx wrangler r2 bucket cors set <桶名> --file cors.json` 设置,报错会精确到字段。
## 验证
分两层验证:先确认「服务端链路的预签名地址可用」,再确认「浏览器侧跨域放行」。
```bash
# 1. 服务端直接 PUT 预签名地址(不走浏览器, 不受 CORS 限制)
curl -X PUT --upload-file ./test.png "https://<预签名地址>"
# 2. 带 Origin 头观察预检响应(部分厂商对 OPTIONS 直接返回跨域响应头)
curl -sD - -o /dev/null -X OPTIONS \
-H "Origin: https://admin.pay.example.com" \
-H "Access-Control-Request-Method: PUT" \
"https://<预签名地址>" | grep -i "access-control"
```
- 第 1 步成功、第 2 步响应里没有 `Access-Control-Allow-Origin`:跨域规则未生效(或未配),回到「修复」;
- 两步都失败:不是跨域问题,查服务端点是否浏览器可达、密钥权限与预签名是否过期。
改完规则仍不生效时,通常是三层延迟之一:**桶规则传播**(官方称极端情况要几十秒)、
**浏览器预检缓存**(按 `MaxAgeSeconds` 缓存,用无痕窗口复测)、**CDN / 自定义域缓存**(需刷新)。
## 相关链接
- [返回 FAQ](https://doc.plus.daxpay.cn/getting-started/faq/.md)
- [CDN 部署注意事项](https://doc.plus.daxpay.cn/getting-started/faq/cdn.md)
- [存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md)
---
# 站内通知(SSE)断开重连排查
**源**: https://doc.plus.daxpay.cn/getting-started/faq/sse-disconnect.md
# 站内通知(SSE)断开重连排查
## 现象
浏览器控制台反复报 `ERR_HTTP2_PROTOCOL_ERROR 200 (OK)` 之类的连接中断错误;通知消息要刷新页面才能看到;该请求按固定间隔断开重连。
## 原因
站内通知走 SSE 长连接(`/api/notify/user/sse/connect`):握手成功、响应头立即返回,之后靠服务端周期性心跳维持。链路中间任何一层「等待数据超时」小于心跳间隔(当前版本心跳为 10 秒),都会在浏览器已收到 200 之后把连接掐断,前端自动重连,表现为「周期性断连」。
注意 200 表示握手成功:这不是缓存问题,也不是鉴权或后端报错,而是流建立后被中间层终止。
> **真实案例**:2026-09 演示站前置腾讯云 EdgeOne 后,站内通知连接固定 20~40 秒断开一次,
> 浏览器报 `ERR_HTTP2_PROTOCOL_ERROR 200 (OK)`;本地不经过 CDN 的同款部署长时间稳定,
> 定位为 CDN 边缘的回源等待超时。
## 处置(以 EdgeOne 为例)
1. **回源超时要大于心跳间隔**:在规则引擎针对 `/api/notify/*` 设置回源超时(源站/首字节超时),建议 **60 秒**,远大于 10 秒的心跳间隔,留足余量
2. **不缓存**:`/api/notify/*` 需配置不缓存;已按 [CDN 部署注意事项](https://doc.plus.daxpay.cn/getting-started/faq/cdn.md) 配置 API 全路径不缓存规则的话这条已覆盖。注意「不缓存」解决的是缓存问题,回源超时是**独立配置项**,两者都要
3. **环境配对**:EdgeOne 规则按「中国大陆 / 全球」两套环境分别生效,站点解析到境内节点就必须配到「中国大陆」环境,配错不生效
4. **HTTP/2 可作辅助判别**:临时关闭 HTTP/2 走 HTTP/1.1,若断流消失,说明是 CDN 对 h2 长连接的处理问题
## 自查
浏览器开发者工具 Network 面板观察该 SSE 请求的断开时刻,每次都断在相近的固定秒数,说明是链路中某一层的超时在掐流;再对照直连源站(不经过 CDN)的环境,若直连稳定、过 CDN 复现,即可锁定 CDN 层。
## 相关链接
- [返回 FAQ](https://doc.plus.daxpay.cn/getting-started/faq/.md)
- [CDN 部署注意事项](https://doc.plus.daxpay.cn/getting-started/faq/cdn.md)
---
# 微信服务商支付报「受理机构必须传入sub_mch_id」
**源**: https://doc.plus.daxpay.cn/getting-started/faq/wechat-isv-sub-mch-id.md
# 微信服务商支付报「受理机构必须传入sub_mch_id」
## 现象
服务商模式发起支付时报「受理机构必须传入sub_mch_id」,但请求参数里的 `sub_mchid` 明明有值。
## 原因
这条报错文案有误导性 —— 它真正的含义是微信对「服务商 ↔ 特约商户」绑定关系的校验失败,不是字段缺失。
最常见的触发是配置错误:服务商自己的商户号被填进了特约商户号位置,`sp_mchid` 与 `sub_mchid` 是同一个号 —— 微信不允许服务商「特约」自己。
## 判别
在通道子应用(`daxpay-plus-channel-one`)日志里核对请求体,出现 `sp_mchid == sub_mchid`(且 `sp_appid == sub_appid`),即可确认是配置问题而非代码问题。
也可以先看商户的资质:微信商户平台里有「服务商平台」入口的才是服务商,没有入口的属于普通商户。
## 修复
按商户的实际资质分两种情况:
- **普通商户**:不该使用微信服务商产品,改配微信直连即可
- **服务商**:特约商户号必须填服务商进件绑定的**真实二级商户号**,不能填服务商自己的号
特约商户的开通也可以经进件流程统一办理,见[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)。
## 相关链接
- [返回 FAQ](https://doc.plus.daxpay.cn/getting-started/faq/.md)
- [微信支付通道说明](https://doc.plus.daxpay.cn/extension/channels/wechat.md)
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)
---
# 特色功能
**源**: https://doc.plus.daxpay.cn/getting-started/features.md
# 特色功能
以下为 DaxPay Plus 已实现的核心功能亮点,涵盖商业增强域(代理商体系、商户进件、风控、限额)、支付核心能力、通道架构、多端管理、安全机制与运维可观测性。
## 商业增强能力(plus 独有)
这四块能力是 DaxPay Plus 相对开源版的主要增量,也是"可运营收单业务"的支柱。
### 代理商体系
将运营结构从"运营端 + 商户端"两级扩展为**运营端 / 代理商 / 商户三级**:
- **代理商管理** — 运营端可管理代理商档案,代理商通过独立入口(Web 端 + APP)登录自助运营
- **商户归属** — 商户挂靠在代理商名下,代理商可查看名下商户的支付与退款订单
- **授权代管(ISV)** — 支持代理商代管名下商户的通道配置,以服务商身份完成通道侧报备
- **数据边界** — 代理商仅可见名下商户数据,不越权访问平台其他商户
开源版没有代理商端 Web 与代理商 APP,对应的 `/agent/**`、`/app-agent/**` 接口与 `agent:portal:*` 权限码体系也仅在 plus 提供。
### 商户进件
打通"商户入驻 → 通道开通"的链路:
- **进件申请** — 商户资料在线填报,提交至平台审核
- **多服务商模型** — 同一通道可配置多个服务商,进件创建时锁定归属服务商,支付链路按服务商隔离凭证
- **资料主档与 OCR** — 商户进件资料一次维护为主档,跨申请单自动复用;营业执照 / 银行卡等证照支持 OCR 识别录入
- **审核工作流** — 运营端对进件资料进行审核,支持通过 / 驳回
- **费率申报** — 费率随进件一并申报,审核通过后生效
- **自动开通** — 进件通过后自动开通对应通道的收单能力,无需人工二次配置
### 费率体系
围绕"谁在收单、钱怎么分"的费率记账与配置体系:
- **费率链四级** — 平台 / 服务商 / 一级代理商 / 商户四级费率链,逐层增量分配,未配置自动回落
- **规则化计费** — 费率规则引擎支持固定金额、比例、阶梯等规则组合,简单 / 高级双视图编辑
- **实时链校验** — 配置界面实时比对费率链各层级,倒挂与断层即时提示
- **费用明细** — 每笔交易按费率快照落费用明细,对账有据可查
### 支付风控(全量四层)
开源版自 2026-09 起收敛为 IP 级防线,DaxPay Plus 保留并维护**全量四层事前防线**:
| 层级 | 说明 |
| ---- | ---- |
| IP 黑名单 | 按 IP 直接拦截,支持批量导入 |
| 用户标识 | 按用户标识(openid 等)拦截指定主体 |
| 省市地区 | 按地区名单放行 / 拦截 |
| 门店围栏 | 按门店地理围栏限定可交易范围 |
在此之上还有:
- **事后补录** — 交易发生后补充录入风险名单,追责与追溯
- **命中转黑名单** — 风险规则命中后可自动转黑名单,形成闭环
- **账号日限 / IP 频率限制** — 账号维度的日累计限额与 IP 维度的请求频率兜底
### 商户限额
**平台模板 / 商户 / 应用三级**限额配置,支持日限、单笔限额等维度,交易链路实时校验,超限自动拦截。
## 支付核心能力
DaxPay Plus 覆盖支付交易的完整生命周期:
- **支付** — 统一下单,支持主流支付渠道与多种支付方式
- **退款** — 全额 / 部分退款,支持退款同步与差错处理
- **分账** — 分账订单,开放 API 发起分账 / 查询 / 同步,分账接收方绑定管理
- **预授权与支付分** — 支付宝预授权(授权 / 请款 / 解除)与微信支付分(需确认模式双轨策略)
- **收款单** — 商户开单远程催款,一单一付,支持自定义表单字段
- **对账与投诉** — 通道对账单下载、差错单处理、支付投诉工单接入
- **查询** — 订单状态、交易明细、通道流水查询
- **回调** — 支付结果异步通知到业务系统,无需轮询等待
- **同步** — 主动向通道查询订单状态,补偿回调丢失
- **关闭** — 订单超时关闭、网关超时兜底
- **商户通知** — 商户回调消息分发、重试策略、通知任务调度
- **易支付协议兼容** — 内置 EasyPay 通用商户接入模块,兼容主流易支付协议,V1 (MD5) 存量兼容 / V2 (RSA) 推荐,小微商户与个人开发者可快速接入
## 通道架构:编排与对接分离
DaxPay Plus 的通道体系采用**主应用编排 + 子应用对接**的分层架构:
| 层级 | 职责 | 实现 |
| ---- | ---- | ---- |
| **编排层** (主应用 `daxpay-channel`) | 通道声明、通道路由、支付策略编排、配置数据 CRUD、回调组装 | 不含第三方 SDK |
| **对接层** (子应用 `channel-one` / `channel-two`) | 第三方 SDK 直接调用、签名/验签、通道专属协议适配 | 独立部署、无状态 |
主应用与子应用之间通过内部 HTTP 接口通信,链路全程 **AES-GCM 传输加密**,返回格式统一。这样设计的收益:
- **SDK 依赖隔离** — 第三方 SDK 不污染主应用,避免版本冲突
- **独立升级** — 子应用可按通道单独发版,不影响主链路
- **弹性伸缩** — 高频通道(支付宝、微信)可多实例独立扩缩容
- **无状态部署** — 子应用不连库、不连缓存、不连消息队列,通道凭证由主应用每次请求携带
### 通道总数与分布
DaxPay Plus 已接入 **16 个支付通道**:
- **直连通道** (`daxpay-plus-channel-one`,端口 10100) — 支付宝、微信(直连 + ISV)、抖音、银联(云闪付)、银联商务(UMS)
- **聚合通道** (`daxpay-plus-channel-two`,端口 10200) — 拉卡拉、乐刷、盛付通、海科融通、河马付、随行付、富友、易宝、汇付天下(Adapay)、斗拱、易支付(协议通道化)
Stripe 国际通道暂未接入 DaxPay Plus,境外卡支付能力暂不可用。
## 支付方式
覆盖主流支付场景:
- **聚合支付** — 一码多付,自动路由到用户钱包
- **扫码支付** — 主扫、被扫
- **JSAPI 支付** — 微信 / 支付宝 / 抖音公众号、小程序内调起
- **H5 支付** — 手机浏览器调起钱包
- **APP 支付** — 原生 SDK 拉起
- **小程序支付** — 微信 / 支付宝 / 抖音
- **付款码支付** — 商户扫用户动态码
- **抖音支付** — 扫码 / JSAPI / H5 / APP
## 多商户与多端管理
- **三级入口架构** — 运营端(平台运营方)、代理商端(渠道拓展方)、商户端(商户自助),菜单与数据按 `client_code` 完全隔离
- **多应用管理** — 单商户可配置多个支付应用,独立凭证与回调地址
- **行级数据隔离** — 每个商户的数据通过商户编号自动隔离,彼此互不可见
- **移动端配套** — 运营端 / 商户端 / 代理商端三套 APP,与 Web 端同一套接口与权限码
## 通道路由
- **动态路由** — 按支付产品、支付方式、支付应用等条件动态匹配最终通道
- **产品策略** — 按支付方式(扫码 / JSAPI 等)自动匹配对应的支付流程
- **环境一致性校验** — 路由层兜底校验商户环境与产品当前环境(沙箱/生产)一致
## 安全机制
DaxPay Plus 在接口、传输、存储、认证多个层面构建安全防护:
- **签名防篡改** — 接口请求与响应支持 RSA 签名
- **字段级加密** — 敏感字段 AES-256-GCM 加密存储
- **传输加密** — 主应用与通道子应用之间全程 AES-GCM 加密
- **权限认证** — 基于 Sa-Token 与 RBAC 的角色权限控制,菜单与数据按角色隔离
- **两步验证** — TOTP 一次性密码 + 备份码,支持 Google Authenticator
- **社交登录** — 微信 / 支付宝 / 抖音开放平台扫码登录
- **沙箱 / 生产隔离** — 通过部署开关彻底区分环境;生产部署启动时会自动把残留的沙箱配置重置为生产,杜绝测试数据混入
## 全端覆盖
| 终端 | 应用 | 技术栈 |
| ---- | ---- | ------ |
| 运营 Web | `daxpay-admin` | Vue 3.5 · Vite 8 · antdv-next · Vben Admin 5 |
| 代理商 Web(plus 独有) | `daxpay-agent` | 同上,同源编译 |
| 商户 Web | `daxpay-merchant` | 同上,同源编译 |
| H5 收银台 | `daxpay-plus-h5` | Vue 3.5 · Vite 8 · Vant 4 · Pinia 3(PC + Mobile 双端) |
| 运营端 APP | `daxpay-plus-app-admin` | uni-app · wot-ui v2(H5 / 微信 / 支付宝 / 抖音 / App) |
| 商户端 APP | `daxpay-plus-app-merchant` | 同上 |
| 代理商端 APP(plus 独有) | `daxpay-plus-app-agent` | 同上 |
| 聚合收银台小程序 | `daxpay-plus-mini-cashier` | uni-app · wot-ui v2(微信 / 支付宝 / 抖音) |
## 可观测性与运维
- **链路追踪** — 集成 OpenTelemetry,一次请求的全部日志携带同一追踪 ID,跨服务排查一键串联
- **审计日志** — 关键操作全量留痕,记录操作人、时间、IP 及其归属地
- **站内通知** — 公告、个人消息、SSE 实时推送
- **优雅停机** — 发布或重启时先处理完存量请求再下线,不打断进行中的交易
- **生产部署护栏** — `PROD` 模式下对沙箱开关、超管入口、Swagger、CORS、actuator 暴露面、认证放行范围等 9 项做启动期 fail-fast 校验
- **运维面板** — 配套单机运维面板,覆盖安装 / 升级 / 网关 / 证书 / 移动端构建等日常运维,支持 Web 与终端双形态
---
# 业务术语
**源**: https://doc.plus.daxpay.cn/getting-started/glossary.md
# 业务术语
> **上半部分为 DaxPay Plus 对外统一词汇表**(菜单、运营配置、对接文档以本表为准)。
> 下半部分为行业通用术语,供参考;若与上半部分冲突,**以本词汇表为准**。
---
## DaxPay Plus 对外统一词汇表
### 如何区分「渠道」和「通道」
| 字 | 站在哪一端 | 一句话 |
| -- | ---------- | ------ |
| **渠道** | 付款用户(C 端) | 钱从哪个付款账户出(微信、支付宝…) |
| **通道** | 平台对接(B 端) | 跟哪家支付机构/通道方对接(微信、拉卡拉、银联商务…) |
二者不要混用:配置里「选微信」常常同时涉及「用户用微信付」和「走微信或某间连通道进件」,必须结合下表看清层级。
### 核心对象
| 术语 | 代码/字段 | 说明 |
| ---- | --------- | ---- |
| **商户** | Merchant / `mchNo` | 接入 DaxPay Plus 的收款主体(租户)。 |
| **应用** / **商户应用** | MchApp / `appId` | 商户下的业务应用;通道路由、聚合、收银台等配置挂在应用上。口语可简称「应用」,首次说明时建议用「商户应用」。 |
| **支付渠道** | PayProvider / `provider` | C 端付款品牌:微信、支付宝、银联、抖音等。管「钱从哪个付款账户出」。 |
| **支付方式** | PayMethod / `method` | 用户怎么付:扫码、JSAPI、小程序、H5、付款码等。每个方式归属一个支付渠道。管「用户怎么操作」。 |
| **支付通道** | Channel / `channel` | B 端对接的支付机构/通道方:微信支付、支付宝、拉卡拉、银联商务等。管「跟谁家对接」。 |
| **支付产品** | Product / `product` | 某通道下的对接形态,如微信直连、微信服务商、银联商务 C 扫 B 等。一个通道可挂多个产品。管「用哪家的哪个型号」。 |
| **支付能力** | Capability / `capability` | 某支付产品实际支持的发起形态;常与支付方式对应,但以产品策略声明为准。管「这个型号能做哪些事」。配置页若可自动推断,可对用户弱化展示。 |
| **通道商户** | ChannelMerchant / `channelMchNo` | 商户在某一支付产品下的进件/开户实体;**唯一绑定一个支付产品**,是收款路径的锚点。 |
| **通道应用配置** | 通道侧 App(如微信/支付宝 AppId) | 通道侧应用号、密钥、授权等;**不是**商户应用 `appId`。菜单中「微信应用」「支付宝应用」等均属此类。 |
### 商业版增强域对象
| 术语 | 代码/字段 | 说明 |
| ---- | --------- | ---- |
| **代理商** | Agent | 平台与商户之间的展业主体;名下商户可由其代建、代管部分配置。商户归属分直营(平台)与挂靠(代理商)两种模式。 |
| **服务商** | ISV / 服务商工作台 | 以微信/支付宝 ISV 等形态对接通道的机构主体;同一通道可配置多个服务商,商户进件归属与费率定价均按服务商维度展开。 |
| **进件** | — | 商户在通道侧开户报备、取得收款资格的过程:提交资料 → 通道审核 → 通过后自动生成通道商户绑定。 |
| **进件申请单** | 进件工作台 | 一次进件申请的载体,创建时锁定商户、服务商与通道,走「待提交/审核中/渠道处理/成功/失败/作废」状态机;更换服务商需作废重开。 |
| **资料主档** | `pay_mch_onb_*_profile` | 商户进件资料的复用底稿(主体/法人/执照/门店四类),商户维度唯一;创建申请单时勾选复用,系统自动复制为该单快照。 |
| **收款单** | `billNo` | 商户开单远程催款的凭证,一单一付;付款人打开 H5 支付页(地址 `/b/:billNo`)按定义填单付款,支付成功即终态。 |
| **风控四层防线** | — | 事前四层拦截:IP 黑名单、用户标识、省市地区、门店围栏;叠加风险命中事后补录与命中自动转黑名单。 |
| **商户限额** | — | 平台模板/商户/应用三级限额配置,类型含单笔/日累计/日笔数;退款单列日累计兜底,防批量退款搬钱。 |
| **费率链** | — | 平台费率 → 服务商费率 → 一级代理商费率 → 商户费率的四级链路;每笔交易按下单时的费率快照计入费用明细。 |
| **通道子应用** | channel-one / channel-two | 独立部署的通道 SDK 适配服务(端口 10100/10200),与主应用无代码依赖,经 HTTP + AES-GCM 加密通信;无状态,不连数据库。 |
### 编码约定(code,与枚举一致)
| 层 | 规则 | 示例 |
| -- | ---- | ---- |
| Provider / ClientEnv | C 端品牌;env 与 provider 同码 | `wechat` / `alipay` / `douyin` / `union_pay` |
| Channel | B 端机构;直连品牌一般无 `_pay`;间连可 `xxx_pay` | `wechat` / `alipay` / `douyin` / `huifu` / `lakala_pay` |
| Product | 通道下型号;可与 channel 不同 | 微信直连 `wechat_pay`、抖音直连 `douyin_pay`、汇付系 `ada_pay`/`dougong_pay` |
| Method / Capability | **同码**;`{品牌}_{形态}`(如 `wechat_qr`、`union_qr`) | 勿用 `union_pay_qr`;勿把 product 的 `wechat_pay` 当 env |
**勿混用**:`wechat_pay` 仅支付产品;`wechat` 为渠道/通道/微信宿主环境。
### 通道路由
| 术语 | 代码/字段 | 说明 |
| ---- | --------- | ---- |
| **通道路由** | PayRoute | 在**商户应用**上配置:各支付渠道/支付方式收款时使用哪个**通道商户**(进而落到支付产品与能力)。当前实现为**确定性绑定**,不是按成本/成功率做多候选智能分流。业务说明可写作「收款通道配置」。 |
| **按渠道默认** | `mode = basic` | 为每个支付渠道指定一个默认通道商户;支付能力由产品策略按支付方式自动取默认。代码历史名「基础模式」。 |
| **按支付方式** | `mode = scene` | 为每个支付方式单独指定通道商户与支付能力。代码历史名「场景模式」,**不是**扫码环境/收银台业务场景。 |
| **直接指定** | 请求已传 `channelMchNo` + `capability` | 跳过应用通道路由策略,直接按传入的通道商户与支付能力发起。完整说法可写「直接指定通道商户」。 |
| **跟随通道路由** | 聚合/收银 AUTO 等 | 不单独绑通道商户,按应用通道路由解析。 |
配置与下单关系:
**配置侧**(商户应用):
```mermaid
flowchart TD
M[商户] --> APP[应用 appId]
APP --> ROUTE[通道路由]
ROUTE -->|渠道 / 方式| CM[通道商户]
CM --> PROD[产品]
PROD --> CAP[能力]
APP -.-> AGG[聚合 / 码牌 / 收银台]
APP -.-> NOTIFY[异步通知]
```
**下单侧**(交易链路):
```mermaid
flowchart TD
ORDER[下单 method 或直接指定 channelMchNo] --> PARSE[解析 product + channelMchNo + capability]
PARSE --> IMPL[走对应通道实现]
```
### 网关与展示
| 术语 | 说明 |
| ---- | ---- |
| **聚合支付** / **聚合收款配置** | 一码多付等:同一入口按环境推导或配置支付方式,再解析通道商户。 |
| **码牌** | 线下收款码牌,两类模型(programType:h5 / mini 两种跳转形态)+ 牌别归属(ownerType);商户级码牌锁定商户号中缀、不可调拨。设备资产在「码牌管理」。 |
| **收银台** | 面向用户的收银展示页及支付项配置。 |
| **打开环境** | 用户从微信/支付宝/浏览器等打开时的环境(勿与通道路由历史名「场景模式」混淆)。 |
### 配置与凭证
| 术语 | 代码/字段 | 说明 |
| ---- | --------- | ---- |
| **对接配置** | Credential | 商户调用开放 API 的密钥、验签与通信加密配置。 |
| **异步通知配置** | Notify(商户回调) | 业务事件回调 URL 与订阅;区别于系统「通知公告」。 |
| **门店** | Store | 商户线下门店。 |
### 与业内「渠道路由」的差异
行业资料中的「渠道路由」常指:在多条可用通道中按成功率、成本、金额等因子**择优**。
DaxPay Plus 当前「通道路由」是应用级 **1:1 路径绑定**(可选按渠道默认或按支付方式),**不含**权重分流与失败自动换通道。阅读外部资料时请勿直接等同。
---
## 交易类
| 术语 | 说明 |
| ---- | ---- |
| 支付 (Payment) | 用户通过在线支付系统将资金转移给收款方 |
| 退款 (Refund) | 支付系统将钱退还给用户,有全额退款和部分退款 |
| 撤销 (Cancel/Void) | 当天取消一笔交易(日切前),通常退手续费 |
| 冲正 | 与撤销类似,来源于 POS 机时代,用于取消超时交易 |
| 担保交易 | 用户先付款到平台,确认收货后再打款给商家 |
| 即时到账 | 付款资金直接转移到收款方,无需二次确认 |
| 预授权 (Preauth) | 先冻结用户资金、完成服务后再请款扣款的支付形态 |
## 资金类
| 术语 | 说明 |
| ---- | ---- |
| T日 | 交易实际发生的日期 |
| T+N | 从交易日之后第 N 个工作日 |
| 会计日 | 标识一笔交易在会计层面的日期——可能与自然日不同 |
| 日切 | 会计日切换到下一天,之后需要批处理(清算/试算平衡等) |
| 结算 | 收单机构把交易资金结转给商户(结算到余额或银行卡) |
| 清算 | 机构之间交易资金的转移(通常由专门清算机构负责) |
| 轧差 | 把当天应收和应付金额相互抵消,仅转移净额(读 gá) |
| 计收费 | 支付平台针对手续费的记录和汇总 |
| 手续费 | 支付系统对交易处理或服务收取的费用 |
| 资损 | 因错误导致的资金损失 |
## 支付形态(行业通用)
| 术语 | 说明 |
| ---- | ---- |
| 快捷支付 | 提前绑定银行卡信息,快速完成后续支付 |
| 代扣 | 个人授权商户直接扣款(如水电煤代扣) |
| 卡支付 | 使用信用卡或借记卡支付 |
| 网银支付 | 跳转到银行支付页面输入账户信息完成支付 |
| 二维码支付 | 通过二维码发起支付交易 |
| 正扫 | 商户生成二维码,用户扫码支付 |
| 反扫 | 用户生成二维码,商户扫用户码收款 |
| 聚合扫码 | 一个二维码同时支持支付宝、微信等多种支付方式 |
## 商户与账户
| 术语 | 说明 |
| ---- | ---- |
| 商户入驻 | 商户进入支付系统需提交资料并签署协议的过程 |
| 进件 | 商户在通道/收单机构侧提交资料开户,取得收款资格(见上文增强域词条) |
| 会员 | 加入支付金融机构的个人 |
| 限额 | 账户在特定时间内允许交易的最大金额(单笔/日/月) |
| 冻结 / 解冻 | 因风险问题暂停/恢复账户交易或余额 |
| KYC (实名认证) | Know Your Customer,证实客户身份 |
| 签约 / 绑卡 | 会员绑定银行卡或第三方支付账户,后续可快捷支付 |
| 解绑 | 取消已绑定的银行卡或支付账户 |
## 资金账务
| 术语 | 说明 |
| ---- | ---- |
| 记账 | 交易记录到会计科目中 |
| 复式记账 | 每笔交易至少两个账目变动,借方和贷方金额相等 |
| 账户 | 记录特定类型财务交易的户头 |
| 科目 | 会计账簿中分类记录财务交易的项目(可多级) |
| 分录 | 记录交易在会计账簿中的具体方法——明确借方和贷方 |
| 内部户 | 不直接面向客户,用于内部会计和资金管理 |
| 中间户 | 一种特殊内部户,用于临时记账(如渠道扣款成功时) |
| 头寸 | 通俗地说就是余额情况 |
## 风控与合规
| 术语 | 说明 |
| ---- | ---- |
| 风控 | 交易的风险控制(欺诈检测/信用评估/合规检查等) |
| 黑名单 | 命中风控规则后列入的拒绝名单(IP/用户标识等维度) |
| 反洗钱 (AML) | 预防、识别和打击将非法所得洗白的行为 |
| 反欺诈 | 预防、检测和遏制欺诈行为(信用卡盗用/账户盗用等) |
| 监管与合规 | 遵守所在国家相关法律、规章和行业标准,定期报告 |
## 交互与系统
| 术语 | 说明 |
| ---- | ---- |
| 信息流 | 交易过程中产生的非资金相关数据 |
| 资金流 | 资金的流转,分虚拟资金流(内部账户间)和实际资金流(银行账户间) |
| API 接口 | 系统间实时交互数据的一组协议(HTTP 请求/响应) |
| 文件接口 | 通过文件交换数据(清算文件/结算文件等),实时性较低 |
## 子系统分类(行业参考)
| 术语 | 说明 |
| ---- | ---- |
| 开放网关 | 对接商户的入口接口(下单/支付等),安全性要求最高 |
| 收单结算 | 负责收取商户订单并发起结算 |
| 收银核心 | 渲染可用支付方式供前端展示 |
| 支付引擎 | 负责真正的资金扣划 |
| 渠道网关 | 行业说法;在 DaxPay Plus 中请对照「支付通道 / 通道路由」,通道 SDK 调用实现在通道子应用 |
| 会员平台 | 管理会员的注册/登录/密码/实名认证 |
| 商户平台 | 管理商户的入驻/登录/交易管理 |
| 风控平台 | 针对账户和交易提供实时/离线风控 |
| 运营平台 | 订单管理/通道管理/产品管理等综合运营工具 |
## 相关链接
- [业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)
- [支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)
- [风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)
- [交易状态字典](https://doc.plus.daxpay.cn/getting-started/codes/trade-status.md)
---
# 项目介绍
**源**: https://doc.plus.daxpay.cn/getting-started/introduction.md
# DaxPay Plus 商业增强版
`DaxPay Plus` 是 DaxPay 开源版的**商业增强版**,面向支付服务商、多商户平台与 SaaS 运营方,在开源版完整支付核心的基座上补齐了**代理商体系、商户进件、全量风控与商户限额**四块商用能力,并配套全端管理界面。
它解决的不只是"能不能收单",而是"如何把收单做成一项可运营的业务":商户由谁发展、资料怎么审、风险怎么挡、额度怎么控、多端人员怎么管。
## 它解决什么问题
业务系统对接多种支付方式(支付宝、微信、银联等)通常面临:
- 各通道接口规范、签名算法、回调机制各不相同,对接成本高
- 多通道的运维、升级、故障切换难以统一管理
- 通道 SDK 依赖冲突、版本锁定,与主业务耦合严重
- 多渠道资金对账、风控、终端设备管理分散
- 商户由谁发展、资料是否合规、风险敞口多大,缺少可运营的管理抓手
DaxPay Plus 将各通道封装为**统一的 HTTP 接口**,业务系统只需对接一套标准协议即可接入多种支付方式;把第三方 SDK 隔离到**独立部署的通道子应用**中,显著降低对接、运维与升级的复杂度;同时在开源版基础上补齐运营链条——**代理商发展商户、进件审核开通通道、风控与限额在交易链路实时拦截**,形成完整的商业化收单运营体系。
## 核心特性
- **支付核心能力** — 覆盖支付、退款、分账、查询、回调、同步、关闭、商户通知等完整交易闭环
- **代理商体系**(plus 增强) — 运营端 / 代理商 / 商户三级运营结构,代理商可发展与管理名下商户、查看名下商户的支付与退款订单,支持授权代管(ISV)模式;配套**代理商 Web 端与代理商 APP** 两套入口(开源版没有)
- **商户进件**(plus 增强) — 通道进件申请与审核工作流,商户资料在线填报、费率随进件申报,进件通过后自动开通通道收单能力
- **全量风控**(plus 增强) — IP 黑名单 + 用户标识 + 省市地区 + 门店围栏**四层事前防线**,另有事后补录、命中自动转黑名单、账号日限与 IP 频率限制;开源版 2026-09 起已精简为 IP 级防线
- **商户限额**(plus 增强) — 平台模板 / 商户 / 应用**三级限额**配置,支持日限、单笔限额等维度,交易链路实时校验、超限自动拦截
- **多商户 SaaS 隔离** — 菜单与数据按 `client_code` 端级隔离,商户数据按商户编号行级隔离,代理商只见名下商户
- **统一 HTTP 接口** — 各通道封装为 RESTful 标准协议,业务系统一次对接、多通道通用
- **通道编排与对接分离** — 主应用负责通道路由、策略编排与配置管理;第三方 SDK 对接下沉到独立子应用,支持**独立部署、独立升级、弹性伸缩**
- **安全签名** — 接口请求与响应支持 RSA 签名防篡改,字段级 AES-GCM 加密,主应用与通道子应用之间传输层全程加密
- **全端覆盖** — 运营 / 代理商 / 商户三套 Web 管理端、运营 / 商户 / 代理商三端 APP、聚合收银台小程序(微信 / 支付宝 / 抖音)、PC + 移动双形态 H5 收银台
- **生产部署护栏** — 部署模式 `PROD` / `DEV` 强制区分,生产启动前对 9 项高危配置做 fail-fast 校验,不通过直接拒绝启动
- **沙箱 / 生产隔离** — 部署级环境隔离,生产数据天然纯净,启动期强制对齐
DaxPay Plus 采用**单语中文**设计,不再提供多语言国际化机制,时间全系统统一按东八区(Asia/Shanghai)处理。这是与开源版差异明显的一处产品取向。
## 与开源版的关系
DaxPay Plus **fork 自 DaxPay 开源版**,技术栈同源,并在此基础上做商业化增强:
| 维度 | 开源版 | DaxPay Plus |
| ---- | ------ | ----------- |
| 运营结构 | 运营端 + 商户端两级 | 运营端 + **代理商端** + 商户端**三级** |
| 商户进件 | — | 进件申请与审核工作流,费率随进件申报 |
| 风控 | IP 级基础防线 | **全量四层**防线 + 事后补录 + 命中转黑名单 + 频率限制 |
| 商户限额 | — | 平台模板 / 商户 / 应用三级限额 |
| 管理端 | 运营 / 商户 Web | 运营 / **代理商** / 商户 Web + **代理商 APP** |
| 多语言 | 10 语种国际化 | 单语中文 |
| 通道子应用 | Java + Go 双实现 | 单 Java 实现(14 通道) |
后续同步开源版更新时,风控域与基础设施(端口、消息地址等)已相对开源版分叉的文件不会被直接覆盖,以保证 plus 增强能力不被回退。
## 项目组成
DaxPay Plus 由多个独立 git 仓库的子项目协同构成(详见[应用介绍](https://doc.plus.daxpay.cn/architecture/apps.md)):
- **主后端应用** `daxpay-plus-server` — 支付核心、通道路由编排、风控与限额、代理商与商户管理、IAM 权限
- **Web 管理端** `daxpay-plus-ui` — 运营端 / 代理商端 / 商户端三套独立应用,同源 monorepo 编译
- **通道适配子应用** — `daxpay-plus-channel-one`(直连 5 通道)、`daxpay-plus-channel-two`(聚合 9 通道),独立部署的无状态微服务
- **移动与收银端** — 运营 / 商户 / 代理商三端 APP、聚合收银台小程序、H5 收银台
- **安装运维面板** `daxpay-plus-install` — 配套的一键安装与运维面板(源码拉取、镜像构建、部署编排、升级管理),可选组件
## 适用场景
- **支付服务商 / 收单外包** — 统一收银、多通道兜底、多商户进件与数据隔离,代理商体系支撑渠道拓展
- **多商户平台 / SaaS** — 为每个入驻商户分配独立支付配置与账单,平台侧统一风控与限额
- **有渠道分层的运营方** — 需要"平台 → 代理商 → 商户"三级归属与分权管理,代理商自助查看名下商户交易
- **独立软件供应商 (ISV)** — 通过统一 HTTP 接口集成支付能力,以授权代管模式服务自有客户
## 相关文档
- [特色功能](https://doc.plus.daxpay.cn/getting-started/features.md) — 各能力域的功能清单与细节
- [架构总览](https://doc.plus.daxpay.cn/getting-started/architecture-overview.md) — 子系统划分、端口与数据流
- [应用介绍](https://doc.plus.daxpay.cn/architecture/apps.md) — 各端工程的职责与技术栈
- [运维面板](https://doc.plus.daxpay.cn/tools/panel/overview.md) — 可视化部署与运维(一键部署见[此处](https://doc.plus.daxpay.cn/deployment/installer.md))
- [官方网站](https://www.daxpay.cn) — 产品介绍与商业授权咨询
---
# 网关授权认证
**源**: https://doc.plus.daxpay.cn/api/assist/auth.md
# 网关授权认证
## 接口说明
网关支付（收银台 / 聚合扫码）场景下，前端用第三方 OAuth 授权码换取 openId / userId 的认证接口。无商户签名（`@PaymentVerify`），属于网关 H5 / 小程序侧客户端接口，响应为平台级 `Result`。
提供两个端点：
| 接口 | 地址 | 返回 | 用途 |
| --- | --- | --- | --- |
| OAuth 认证回调 | `POST /unipay/gateway/auth/callback` | `Result` | H5 授权重定向落地页用 OAuth code 换取用户标识 |
| 收银台小程序认证 | `POST /unipay/gateway/cashier/auth` | `Result` | 微信/支付宝/抖音小程序前端换取 openId/userId |
这两个接口返回的是平台级 `Result`（字段 `message`），**不是** `DaxResult`（无 `sign`/`resTime`/`reqId`）。详见 [错误码 - 响应结构](https://doc.plus.daxpay.cn/api/error-codes.md#错误码体系)。
## 接口一：OAuth 认证回调
### 请求地址
`POST /unipay/gateway/auth/callback`
- 认证：无（网关客户端接口）
- 响应：`Result`
### 请求参数 `AuthCodeParam`
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| authCode | string | 是 | — | 三方通道 OAuth 授权码（换 openId/userId），亦可直接写入已拿到的 openId |
| authType | string | 否 | 32 | 认证类型（多类型通道必填：`wechat`/`alipay`/`union_pay`/`douyin`） |
| authToken | string | 否 | 64 | 认证会话码（H5 授权重定向场景下由 [生成授权链接](https://doc.plus.daxpay.cn/api/assist/generate-auth-url.md) 下发，凭此恢复上下文） |
| accessToken | string | 否 | — | AccessToken（通道直接返回时填入） |
| unionIdentifier | string | 否 | — | 云闪付 App 标识（从 UA 的 `UnionPay/<版本> <标识>` 截取） |
| queryCode | string | 否 | — | 查询 Code（用于关联生成授权链接时返回的标识） |
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"authCode": "061XYYxxx0xxx",
"authType": "wechat",
"authToken": "AT20241201020"
}
```
### 响应参数 `AuthResult`
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| openId | string | OpenId（微信场景） |
| userId | string | 用户 ID（支付宝存量商户部分返回） |
| accessToken | string | AccessToken（微信会返回，用于获取用户信息） |
| status | string | 状态（`ChannelAuthStatusEnum`：`waiting`/`success`/`not_exist`） |
| returnPath | string | 来源回跳路径（会话恢复时回填），前端授权完成后据此跳回业务页面 |
### 响应示例
```json
{
"code": 0,
"message": "success",
"data": {
"openId": "oXxX_xxxxxxxxxxxxx",
"status": "success",
"returnPath": "/pay/result"
}
}
```
## 接口二：收银台小程序认证
### 请求地址
`POST /unipay/gateway/cashier/auth`
- 认证：无（网关客户端接口）
- 响应：`Result`
### 请求参数 `CashierAuthParam`
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| channel | string | 是 | 32 | 支付通道：`wechat` / `alipay` / `douyin` |
| authCode | string | 否* | 128 | 授权码（微信 `uni.login` / 支付宝 `my.getAuthCode` / 抖音 `tt.login` 的 code） |
| anonymousCode | string | 否* | 128 | 抖音匿名登录凭证（`tt.login` 的 `anonymous_code`），仅抖音使用 |
> *抖音场景 `authCode` 与 `anonymousCode` 至少传一个（非匿名可同时传）；微信/支付宝仅使用 `authCode`。
### 响应示例
```json
{
"code": 0,
"message": "success",
"data": {
"openId": "oXxX_xxxxxxxxxxxxx",
"status": "success"
}
}
```
## 使用建议
- 授权链接的生成在 [获取授权链接](https://doc.plus.daxpay.cn/api/assist/generate-auth-url.md)（`POST /unipay/gateway/auth/generate-url`），授权完成后前端落地页回调本页接口一换取用户标识。
- 通用取 openId 重定向接口（商户签名、非支付场景）见 [获取用户标识](https://doc.plus.daxpay.cn/api/open/get-openid.md)。
---
# 生成授权链接
**源**: https://doc.plus.daxpay.cn/api/assist/generate-auth-url.md
# 生成授权链接
## 接口说明
网关支付（收银台 / 聚合扫码）场景下，用于**获取用户 openId / userId 的 OAuth 授权链接**。凭网关订单装载商户上下文后生成链接，微信/抖音按支付路由读通道商户应用，支付宝走平台级配置。
业务流程：
1. 前端在网关落地页（收银台/聚合页）调用本接口，获得 `authUrl`（带会话码 `authToken`）。
2. 前端引导用户浏览器跳转到 `authUrl`，由通道完成 OAuth 授权。
3. 授权完成后通道回调平台，平台通过 [授权码认证](https://doc.plus.daxpay.cn/api/assist/auth.md)（`POST /unipay/gateway/auth/callback`）用 code 换 openId/userId 并返回给前端。
本接口用于在支付前获取通道用户标识（openId/userId），不涉及商户系统的登录态。
## 请求地址
`POST /unipay/gateway/auth/generate-url`
- 认证：无（网关客户端接口）
- 响应：`Result`
## 请求参数 `GatewayAuthUrlParam`
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| orderNo | string | 是 | 64 | 平台网关单号 |
| authType | string | 是 | 32 | 认证类型：`wechat` / `alipay` / `douyin` |
| returnPath | string | 是 | 200 | 授权完成后前端回跳路径（须为站内相对路径，如 `/cashier/{orderNo}/wechat`） |
| clientEnv | string | 否 | 32 | 客户端环境（聚合/收银台 H5 解析支付方式用，支付宝可空）：`wechat`/`alipay`/`douyin`/`union_pay` |
| runtime | string | 否 | 16 | 运行形态（聚合解析用，空默认 `h5`）：`h5` / `mini` |
| itemId | long | 否 | — | 收银台支付项 ID（收银台场景必填） |
| cashierType | string | 否 | 16 | 收银台类型（收银台场景必填）：`h5` / `web` / `mini` |
### 请求示例
```json
{
"orderNo": "G2024120112345700001",
"authType": "wechat",
"returnPath": "/cashier/G2024120112345700001/wechat",
"clientEnv": "wechat",
"runtime": "h5",
"itemId": 1853123456789012345,
"cashierType": "h5"
}
```
## 响应参数
`Result`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| authUrl | string | 授权访问链接（前端跳转到此地址完成授权） |
| queryCode | string | 查询标识码（用于后续认证时关联会话） |
| authToken | string | 认证会话码（授权回调后凭此恢复认证上下文） |
### 响应示例
```json
{
"code": 0,
"message": "success",
"data": {
"authUrl": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=...&state=...",
"queryCode": "QC20241201020",
"authToken": "AT20241201020"
}
}
```
## 使用建议
- 本接口依赖已存在的网关订单（先 [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md) 获取 `orderNo`），返回的 `authToken` 在授权回调时需原样传回 [授权码认证](https://doc.plus.daxpay.cn/api/assist/auth.md) 恢复上下文。
- 通用取 openId 重定向接口（商户签名、非支付场景）见 [获取用户标识](https://doc.plus.daxpay.cn/api/open/get-openid.md)。
---
# 易支付对接
**源**: https://doc.plus.daxpay.cn/api/epay.md
# 易支付对接
## 概述
易支付（EasyPay）是 DaxPay 内置的通用商户支付接入模块，兼容主流易支付协议，适用于小微商户和个人开发者快速接入。
DaxPay 同时提供两套 API：
| 版本 | 路径前缀 | 签名方式 | 接口能力 |
| --- | --- | --- | --- |
| **V1**（兼容旧版） | `/epay/api/v1/*` | 固定 **MD5** | 仅下单（submit/mapi）+ 查单（api），**不支持退款/关单** |
| **V2**（推荐） | `/epay/api/v2/api/pay/*` | 固定 **RSA**（`SHA256withRSA`） | 下单、查单、退款、退款查询、关单 |
- V2 接口的 `sign_type` 固定为 `RSA`，不接受 `MD5`
- V1 接口的 `sign_type` 固定为 `MD5`，不接受 `RSA`
- 不存在「V2 任选 MD5/RSA」的说法
易支付协议的金额字段是 **`money`（String 类型，单位元）**，**不是** 标准 API 的 `amount`（Long，单位分）。例如 `1.00` 表示 1 元。
## 接口列表（V2）
| 接口名称 | 接口地址 | 方法 | 描述 |
| --- | --- | --- | --- |
| 易支付下单 | `/epay/api/v2/api/pay/create` | GET/POST | 创建易支付订单 |
| 易支付查询 | `/epay/api/v2/api/pay/query` | GET/POST | 查询易支付订单状态 |
| 易支付退款 | `/epay/api/v2/api/pay/refund` | GET/POST | 发起退款 |
| 易支付退款查询 | `/epay/api/v2/api/pay/refund_query` | GET/POST | 查询退款状态 |
| 易支付关闭 | `/epay/api/v2/api/pay/close` | GET/POST | 关闭订单 |
退款查询同时接受 `/api/pay/refund_query`（下划线）和 `/api/pay/refundquery`（无下划线）两个路径，兼容不同易支付实现。
## V2 下单
### 请求地址
`GET/POST /epay/api/v2/api/pay/create`
### 请求参数
字段名遵循易支付协议的 **snake_case** 风格：
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| pid | string | 是 | 易支付商户号（对应 `mchNo`） |
| type | string | 是 | 接口类型：`web`（跳转）/ `jump`（直接跳转通道）/ `jsapi` |
| method | string | 否 | 支付方式：`alipay` / `wxpay` 等 |
| out_trade_no | string | 是 | 商户订单号（对应 `bizOrderNo`） |
| name | string | 是 | 商品名称（对应 `title`） |
| money | string | 是 | 金额，**单位元**（如 `"1.00"`） |
| timestamp | string | 是 | 当前时间戳（秒） |
| notify_url | string | 否 | 异步通知地址 |
| return_url | string | 否 | 同步跳转地址 |
| sign | string | 是 | RSA 签名值（Base64） |
| sign_type | string | 是 | 签名类型，固定 `RSA` |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderId": 1853123456789012345,
"orderNo": "P2024120112345700001",
"payBody": "weixin://wxpay/bizpayurl?pr=xxxxx",
"payBodyType": "qr_code"
}
}
```
## V2 查询
### 请求地址
`GET/POST /epay/api/v2/api/pay/query`
### 请求参数
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| pid | string | 是 | 易支付商户号 |
| out_trade_no | string | 是 | 商户订单号 |
| sign | string | 是 | RSA 签名值 |
| sign_type | string | 是 | 固定 `RSA` |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderNo": "P2024120112345700001",
"status": "success",
"realAmount": 100,
"payTime": "2024-12-01 12:00:00"
}
}
```
## V2 退款
### 请求地址
`GET/POST /epay/api/v2/api/pay/refund`
### 请求参数
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| pid | string | 是 | 易支付商户号 |
| out_trade_no | string | 是 | 原商户订单号 |
| money | string | 是 | 退款金额，**单位元** |
| out_refund_no | string | 否 | 商户退款号（不传由系统生成） |
| sign | string | 是 | RSA 签名值 |
| sign_type | string | 是 | 固定 `RSA` |
## V2 签名规则（RSA）
1. 获取所有非空参数，**排除 `sign` 与 `sign_type`** 两个字段。
2. 按 key 的 ASCII 字典序升序排列。
3. 拼接为 `key1=value1&key2=value2` 格式（无分隔符、无 `&key=` 后缀）。
4. 使用**商户私钥**以 `SHA256withRSA` 签名，Base64 编码后填入 `sign`。
- 标准 API（`/unipay/*`）：参数名为 camelCase（`bizOrderNo`），签名字段含 `reqTime`/`nonceStr` 等
- 易支付 V2：参数名为 snake_case（`out_trade_no`），签名字段含 `timestamp`，且**排除** `sign_type`
验签使用平台公钥，规则与 [签名机制](https://doc.plus.daxpay.cn/api/signature.md) 一致。
## V1 接口（兼容旧版）
V1 接口兼容传统易支付协议路径，**仅支持 MD5 签名**：
| 接口名称 | 接口地址 | 方法 |
| --- | --- | --- |
| 提交（跳转） | `/epay/api/v1/submit.php` | GET/POST |
| 创建（API） | `/epay/api/v1/mapi.php` | GET/POST |
| 查询 | `/epay/api/v1/api.php` | GET/POST |
### V1 限制
- **仅下单与查单**：V1 不提供退款、退款查询、关单接口。如需退款请使用 V2 或商户端管理 API。
- **签名固定 MD5**：`sign_type=MD5`，使用商户 MD5 密钥拼接末尾后取 MD5（小写十六进制）。
- **查单弱鉴权**：V1 查单使用 `key=md5Key` 直接比对（query 参数），与 V2 的 RSA 验签完全不同，仅适用于低风险场景。
### V1 MD5 签名规则
1. 获取所有非空参数，排除 `sign` 与 `sign_type`。
2. 按 key 的 ASCII 字典序排列，拼接为 `key1=value1&key2=value2`。
3. 在末尾拼接商户密钥：`...&key={md5Key}`（或视具体实现直接拼接）。
4. 对整个字符串取 MD5，输出**小写**十六进制。
## 异步回调
易支付订单的回调走 `protocol=easy_pay`（**GET + URL query 参数**），与标准支付的 `system` 协议（POST JSON）不同。详见 [异步回调 - 两套通知协议](https://doc.plus.daxpay.cn/api/notice/callback.md#两套通知协议)。
---
# 错误码
**源**: https://doc.plus.daxpay.cn/api/error-codes.md
# 错误码
## 错误码体系
DaxPay 有两层 API，响应结构略有不同：
**支付 API**（`/unipay/*`）— `DaxResult`：
```json
{
"code": 0,
"msg": "success",
"data": { }
}
```
**管理 API**（`/mch/*`）— `Result`：
```json
{
"code": 0,
"message": "success",
"data": { }
}
```
| 字段 | 类型 | 支付 API | 管理 API | 说明 |
| ---- | ---- | -------- | -------- | ---- |
| `code` | `int` | ✓ | ✓ | 业务状态码。`0` 表示成功,非 `0` 表示失败 |
| `msg` | `string` | ✓ | — | 提示信息（`DaxResult` 字段名） |
| `message` | `string` | — | ✓ | 可读的中文错误文案（`Result` 字段名） |
| `data` | `object\|null` | ✓ | ✓ | 业务数据,失败时通常为 `null` |
| `sign` | `string` | ✓ | — | RSA 响应签名（仅支付 API） |
| `resTime` | `string` | ✓ | — | 响应时间（北京时间，仅支付 API） |
| `reqId` | `string` | ✓ | — | 请求 ID 回显（仅支付 API） |
- 成功: `{"code": 0, "msg": "success", ...}`
- 失败: `{"code": 10506, "msg": "通道路由未找到匹配通道", "data": null}`
错误文案为**中文**,由后端直接返回(单语中文设计,不提供多语言机制)。`code` 是数字分类码,与文案独立 —— 同一文案可能用不同 `code` 抛出,定位问题时以 `code` 为准。
## HTTP 状态码对照
| HTTP 状态码 | 说明 |
| ----------- | ---- |
| 200 | 请求成功,具体业务结果见响应体 `code` |
| 400 | 请求参数格式错误 |
| 401 | 未授权(`Accesstoken` 缺失或无效) |
| 403 | 禁止访问(权限不足) |
| 404 | 接口不存在 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |
## 错误码字典
错误码由后端常量类定义,按业务域分段。以下取自真实源码:
### 基础码 CommonCode
| 状态码 | 常量 | 含义 |
| ------ | ---- | ---- |
| `0` | `SUCCESS_CODE` | 成功 |
| `1` | `FAIL_CODE` | 失败(未细分类的通用失败兜底码) |
### 通用错误码 CommonErrorCode(10000-19999)
| 状态码 | 常量 | 含义 |
| ------ | ---- | ---- |
| `10401` | `AUTHENTICATION_FAIL` | 认证失败(Token 过期 / 无效) |
| `10404` | `SOURCES_NOT_EXIST` | 资源不存在 |
| `10405` | `DATA_NOT_EXIST` | 数据不存在 |
| `10408` | `NONCE_MISSING` | Nonce 缺失 |
| `10409` | `NONCE_INVALID` | Nonce 无效或已过期 |
| `10410` | `TIMESTAMP_EXPIRED` | 请求时间戳超出允许范围 |
| `10415` | `UN_SUPPORTED_OPERATE` | 不支持的操作 |
| `10500` | `SYSTEM_ERROR` | 系统错误 |
| `10505` | `PARSE_PARAMETERS_ERROR` | 参数解析失败 |
| `10506` | `VALIDATE_PARAMETERS_ERROR` | 参数校验失败 |
| `10507` | `REPETITIVE_OPERATION_ERROR` | 重复操作 |
| `10512` | `DANGER_SQL` | 危险 SQL 异常 |
### 支付错误码 PayErrorCode(20000-29999)
| 状态码 | 常量 | 含义 |
| ------ | ---- | ---- |
| `20000` | `UNCLASSIFIED_ERROR` | 未归类的支付错误 |
| `20011` | `CHANNEL_NOT_EXIST` | 支付通道不存在 |
| `20012` | `METHOD_NOT_EXIST` | 支付方式不存在 |
| `20013` | `STATUS_NOT_EXIST` | 支付状态不存在 |
| `20021` | `CHANNEL_NOT_ENABLE` | 支付通道未启用 |
| `20022` | `METHOD_NOT_ENABLE` | 支付方式未启用 |
| `20023` | `CONFIG_NOT_ENABLE` | 配置未启用 |
| `20024` | `CONFIG_ERROR` | 配置错误 |
| `20025` | `CONFIG_NOT_EXIST` | 配置不存在 |
| `20030` | `UNSUPPORTED_ABILITY` | 不支持该支付能力 |
| `20041` | `TRADE_NOT_EXIST` | 交易不存在 |
| `20042` | `TRADE_CLOSED` | 交易已关闭 |
| `20043` | `TRADE_PROCESSING` | 交易处理中,请勿重复操作 |
| `20044` | `TRADE_STATUS_ERROR` | 交易状态错误 |
| `20045` | `TRADE_FAIL` | 交易失败 |
| `20052` | `VERIFY_SIGN_FAILED` | 验签失败 |
| `20060` | `AMOUNT_EXCEED_LIMIT` | 金额超过限额 |
| `20080` | `OPERATION_FAIL` | 操作失败 |
| `20081` | `OPERATION_PROCESSING` | 操作处理中,请勿重复操作 |
| `20082` | `OPERATION_UNSUPPORTED` | 不支持的操作 |
| `20091` | `DATA_ERROR` | 数据错误 |
### 系统未知错误（越界码）
`SYSTEM_UNKNOWN_ERROR` 虽定义在 `PayErrorCode` 类中,但其 code 值 `30000` 已超出该类的 20000-29999 段,作为「未知异常」单独存在。对接时遇到此码表示发生了未预期的系统级异常,需联系平台排查。
| 状态码 | 常量 | 含义 |
| ------ | ---- | ---- |
| `30000` | `SYSTEM_UNKNOWN_ERROR` | 未知异常,系统无法处理 |
### 用户中心错误码 IamErrorCode(21000-21999)
主要出现在管理端 / 商户端的登录、用户、角色、权限场景。
| 状态码 | 常量 | 含义 |
| ------ | ---- | ---- |
| `21014` | `USER_EMAIL_ALREADY_EXISTED` | 用户 Email 已存在 |
| `21015` | `USER_PHONE_ALREADY_EXISTED` | 用户手机号已存在 |
| `21020` | `USER_INFO_NOT_EXISTS` | 用户信息不存在 |
| `21022` | `DUPLICATE_PHONE_NUMBER` | 手机号重复(批量导入) |
| `21023` | `DUPLICATE_EMAIL_ADDRESS` | 邮箱重复(批量导入) |
| `21024` | `NONE_PHONE_AND_EMAIL` | 邮箱和手机号均为空 |
| `21025` | `ROLE_ALREADY_EXISTED` | 角色已存在 |
| `21026` | `ROLE_NOT_EXISTED` | 角色不存在 |
| `21027` | `ROLE_ALREADY_USED` | 角色已被使用 |
| `21028` | `ROLE_HAS_CHILD` / `PERMISSION_DB_ERROR` | 含有下级角色 / 权限操作错误 |
| `21029` | `PERMISSION_NOT_EXIST` | 没有访问权限 |
| `22016` | `USER_PASSWORD_INVALID` | 密码不正确 |
## 业务异常机制
后端业务异常通过 `BizInfoException` 抛出,构造时同时传入**数字 code**(决定响应 `code` 字段)与**中文文案**(决定 `message` 内容):
```java
// 指定 code + 中文文案
throw new BizInfoException(PayErrorCode.TRADE_STATUS_ERROR, "交易状态错误");
// 仅文案,code 取默认 FAIL_CODE = 1
throw new BizInfoException("支付路由未匹配到可用通道");
```
- **code** 来自上述常量类,决定错误分类
- **文案**为中文,随异常直接返回;带参文案使用 `{0}` 占位符,由统一异常处理器按 `MessageFormat` 风格渲染(如 `"微信分账接收方绑定失败: {0}"`)
二者独立:同一文案可能被不同 `code` 抛出(如"支付路由未匹配到可用通道"既可能以 `VALIDATE_PARAMETERS_ERROR=10506` 抛出,也可能以 `FAIL_CODE=1` 抛出)。对接排错时以响应体的 `code` 定位错误分类,以 `message` 理解具体原因。
### 常见对接错误提示(节选)
| 文案示例 | 含义 |
| ------- | ---- |
| 支付路由未匹配到可用通道 | 通道路由无匹配,检查支付产品 / 应用 / 通道配置 |
| 支付宝分账接收方绑定失败: {0} | 通道侧返回错误,`{0}` 为通道原始报错 |
| 微信分账接收方解绑失败: {0} | 同上,解绑操作被通道拒绝 |
| 交易已关闭 | 订单关闭后不可再发起支付 / 退款 |
| 金额超过限额 | 触发商户限额或通道限额校验 |
> 上表为对接高频提示节选;完整文案以接口实际返回为准,不在此穷举。
## 字段校验错误
参数校验失败时直接返回中文校验文案(如「商户号不可为空」「商户号不可超过32位」),响应 `code` 为 `CommonErrorCode.VALIDATE_PARAMETERS_ERROR`(`10506`)。
---
# 接入指南
**源**: https://doc.plus.daxpay.cn/api/getting-started.md
# 接入指南
## 接入步骤
### 1. 注册商户
联系 DaxPay 运营方注册商户，获取以下核心凭证：
| 参数 | 描述 |
| --- | --- |
| mchNo | 商户号，唯一标识接入商户 |
| appId | 应用 ID，商户下创建的应用标识 |
### 2. 生成 RSA 密钥对
DaxPay 支付 API 使用 **RSA 非对称加密**进行签名验签。商户需自行生成 RSA 密钥对（推荐 2048 位）：
- **商户私钥**：保管在商户服务器，用于对请求签名
- **商户公钥**：注册到 DaxPay 平台，供平台验证请求签名
- **平台公钥**：从 DaxPay 平台获取，用于商户验证响应/回调签名
私钥是敏感信息，禁止提交到代码仓库，建议通过环境变量或安全配置中心管理。
### 3. 环境信息
| 环境 | 基础地址 |
| --- | --- |
| 测试环境 | 部署方自行搭建（如 `http://<测试服务器IP>:19999`，不影响生产数据） |
| 生产环境 | `https://your-domain.com`（部署方自有域名） |
DaxPay Plus 为商业交付部署，测试与生产环境地址以实际部署为准，本地开发时后端默认端口为 `19999`。建议先在测试环境完成联调，验证通过后再切换到生产环境。
### 4. 首次调用
以下示例展示一个完整的支付请求流程：
#### 1) 构造请求参数
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201001",
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
"reqTime": "2024-12-01 12:00:00",
"bizOrderNo": "ORDER20241201001",
"title": "测试商品",
"amount": 100,
"method": "wechat_qr",
"notifyUrl": "https://your-domain.com/notify",
"returnUrl": "https://your-domain.com/return"
}
```
#### 2) 生成签名
将请求参数（不含 `sign` 字段）按 key 升序排列，拼接为 `key=value&key=value` 格式，使用商户私钥以 `SHA256withRSA` 签名，Base64 编码后填入 `sign` 字段。
签名细节参见 [签名机制](https://doc.plus.daxpay.cn/api/signature.md)。
#### 3) 发送请求
```http
POST /unipay/pay HTTP/1.1
Host: your-domain.com
Content-Type: application/json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201001",
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
"reqTime": "2024-12-01 12:00:00",
"sign": "Base64签名值",
"bizOrderNo": "ORDER20241201001",
"title": "测试商品",
"amount": 100,
"method": "wechat_qr",
"notifyUrl": "https://your-domain.com/notify"
}
```
#### 4) 处理响应
```json
{
"code": 0,
"msg": "success",
"data": {
"orderId": 1853123456789012345,
"bizOrderNo": "ORDER20241201001",
"orderNo": "P2024120112345700001",
"tradeNo": "T2024120112345700001",
"status": "progress",
"payBody": "weixin://wxpay/bizpayurl?pr=xxxxx",
"payBodyType": "code_url"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:00:00",
"reqId": "REQ20241201001"
}
```
- `data.payBody`：支付参数体，根据支付方式不同返回不同内容（二维码链接、调起参数等）
- `data.payBodyType`：支付参数体类型（如 `code_url`、`pay_info`、`redirect_url`）
- `sign`：平台对整个响应的 RSA 签名，可使用平台公钥验签
## 安全配置
接入时必须遵循以下安全规范：
- **HTTPS**：生产环境强制使用 HTTPS，禁止明文传输
- **密钥保管**：商户私钥为敏感信息，禁止提交到代码仓库
- **签名验签**：请求需签名，响应/回调需验签，防止数据篡改
- **回调验签**：接收异步通知时必须先验签再处理业务，防止伪造通知
- **防重放**：每次请求使用不同的 `reqId` 和 `nonceStr`，平台会校验唯一性
## 常见问题
### Q: 签名验证失败？
检查签名参数排序是否正确（ASCII 字典序），签名字符串格式是否为 `key=value&key=value`，使用的密钥是否匹配（请求用商户私钥签名，验签用平台公钥）。
### Q: 请求被拒绝？
确认请求体中包含所有必填字段：`mchNo`、`appId`、`reqId`、`reqTime`、`sign`，以及业务参数。
### Q: 测试环境与生产环境差异？
沙箱环境不产生真实资金流动，用于接口联调和流程验证。生产环境配置与沙箱一致，仅基础地址和凭证不同。
---
# 异步回调
**源**: https://doc.plus.daxpay.cn/api/notice/callback.md
# 异步回调
## 概述
当订单状态发生变更时（如支付成功、支付失败、关闭、退款成功），DaxPay 系统会主动向商户发送异步通知。通知的「怎么投递」与「报文长什么样」是两个正交维度：**传输通道**（HTTP 回调 / MQ 推送）× **报文格式**（系统协议 / 易支付协议）。
## 传输通道与报文格式
**传输通道（transport）** —— 决定通知如何投递：
| transport | 投递方式 | ACK 语义 | 重试 |
| --- | --- | --- | --- |
| `http` | HTTP 请求（POST JSON 或 GET query，由报文格式决定） | HTTP 2xx 且响应体 trim 后为 `SUCCESS` | 16 次递增重试 |
| `mq` | 发布到 Artemis Topic `daxpay.notice.` | publish 成功即视为投递成功 | 3 次短间隔重试 |
**报文格式（format）** —— 决定报文如何组装与签名：
| format | 适用场景 | 请求方式 | 报文格式 | 验签方式 |
| --- | --- | --- | --- | --- |
| `system` | 标准支付 API（`/unipay/*`）发起的订单 | **POST** | JSON body | RSA（`SHA256withRSA`） |
| `easy_pay` | 易支付插件（`/epay/*`）发起的订单 | **GET** | URL query 参数 | MD5 / RSA（取决于 V1/V2） |
易支付兼容格式（`format=easy_pay`）的回调走 **GET + URL query 参数**，**不是 POST JSON**。对接易支付时需用 `request.getParameter()` 接收，而非 `request.getReader()`。
## 通知流程（system 协议）
1. 商户在发起支付请求时传入 `notifyUrl` 参数。
2. 系统处理完业务后，向 `notifyUrl` 发送 **POST** 请求（JSON 格式）。
3. 商户系统接收通知，**先验签，再处理业务逻辑**。
4. 商户系统处理后，返回 `SUCCESS` 字符串（大小写不敏感，前后空格会被 trim）。
5. 如果商户系统返回非 `SUCCESS` 或 HTTP 状态非 2xx 或超时未响应，系统按策略重试。
## 应用级订阅（并行通知）
除订单级 `notifyUrl`（每笔订单传入）外，商户还可在「异步通知配置」中为应用配置统一通知（HTTP 回调地址或 MQ 推送）+ 订阅事件。同一业务事件会**并行**生成订单级与应用级两条独立通知任务：
- **订单级（source=order）**：走支付请求传入的 `notifyUrl`，恒 `http + system`
- **应用级（source=app）**：走应用配置，按 `notifyWay`（http/mq）决定传输通道
若商户既在订单传了 `notifyUrl`，又配置了应用级订阅，同一事件会**分别**发到订单级 URL 和应用级地址（两份独立通知，各自重试）。这是预期行为（双轨并行），便于商户同时推送到对账系统与业务系统。仅订单级 URL 为空 / 应用级未配置时才单发一路。
应用级配置见管理端「应用管理 → 异步通知配置」。
## 重试策略
固定 16 次重试，间隔递增（实现于 `NoticeRetryPolicy`，通过 Artemis 延时队列调度）：
| 重试次数 | 间隔 | 累计耗时 |
| --- | --- | --- |
| 1 | 15s | 15s |
| 2 | 15s | 30s |
| 3 | 30s | 1min |
| 4 | 3min | 4min |
| 5 | 10min | 14min |
| 6 | 20min | 34min |
| 7~9 | 30min × 3 | ~2h4min |
| 10 | 60min | ~3h4min |
| 11~13 | 3h × 3 | ~12h4min |
| 14~16 | 6h × 3 | ~30h4min |
- **最大重试次数**：16 次（超过后停止，标记为发送失败）
- **仅自动发送路径会重试**：商户在管理端「手动重发通知」失败后**不会**自动重试，需再次手动触发
- **ACK 判定**：HTTP 状态 2xx **且** 响应体 trim 后忽略大小写等于 `SUCCESS`，两者缺一即视为失败并重试
### MQ 推送方式的重试
`transport=mq` 时仅当 publish 到 Topic 失败（broker 故障/网络异常）才重试 **3 次**，间隔 10s / 30s / 60s；消费侧消费失败由商户/MQ 自身机制负责（建议使用 JMS 持久订阅，离线不丢消息）。
## MQ 推送方式
当应用「异步通知配置」选择 `notifyWay=mq` 时，平台将通知消息（`system` 格式的 DaxNoticeResult JSON，含 RSA 签名）发布到按应用隔离的 Topic，商户自行订阅消费。
- **Topic 命名**：`daxpay.notice.`，每个应用独立隔离
- **消息体**：与 HTTP 回调**完全相同**的 DaxNoticeResult JSON，验签逻辑一致
- **ACK 语义**：publish 成功即视为投递完成（对齐 Stripe EventBridge 模型，推到事件总线即完成）
- **broker 要求**：Artemis address 需配为 **multicast** 路由类型，商户侧用持久订阅（Durable Subscriber）
Java JMS 消费示例：
```java
@JmsListener(
destination = "daxpay.notice.APP001", // 对应 appId
containerFactory = "topicListenerFactory", // pubSubDomain=true 的 Topic 监听工厂
subscription = "daxpay-notify-app001" // 持久订阅名(同一 appId 多实例去重)
)
public void onNotice(String body) {
// body 为 DaxNoticeResult JSON, 验签逻辑与 HTTP 回调完全一致
// 参见下方「签名验证」
}
```
## 回调消息格式
请求方式：`POST`
Content-Type：`application/json`
### 报文结构（DaxNoticeResult）
回调报文继承 `DaxResult`，增加事件与商户字段：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| event | string | 通知事件码（见下方事件类型） |
| protocol | string | 通知协议（`system` / `easy_pay`） |
| mchNo | string | 商户号 |
| appId | string | 应用 ID |
| code | int | 状态码（0 = 成功） |
| msg | string | 提示信息 |
| data | object | 业务数据（订单/退款单快照） |
| sign | string | 平台 RSA 签名（Base64） |
| resTime | string | 通知时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| reqId | string | 请求 ID |
### 事件类型（NoticeEventEnum）
| event | 说明 |
| --- | --- |
| pay.success | 支付成功 |
| pay.fail | 支付失败 |
| pay.close | 支付关闭（主动关单） |
| pay.timeout | 支付超时关闭（业务单超时未付自动关闭） |
| pay.cancel | 支付撤销（资金态 CANCEL） |
| refund.success | 退款成功 |
| refund.fail | 退款失败 |
| refund.close | 退款关闭 |
| alloc.success | 分账成功 |
| alloc.fail | 分账失败 |
| risk.hit | 风控命中（黑名单/海外 IP 等规则触发） |
> 分账通知取对应业务单携带的通知地址（分账请求时传入的 `notifyUrl`），并同样支持应用级订阅；风控事件（`risk.hit`）通过应用级订阅接收。分账通知快照含明细列表。
### 回调示例：支付成功
```json
{
"event": "pay.success",
"protocol": "system",
"mchNo": "M200000001",
"appId": "APP001",
"code": 0,
"msg": "success",
"data": {
"orderNo": "P2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"tradeNo": "T2024120112345700001",
"amount": 100,
"realAmount": 100,
"status": "success",
"method": "wechat_qr",
"payTime": "2024-12-01 12:00:00",
"attach": "{\"orderId\": 123}"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:00:00",
"reqId": "NTF20241201001"
}
```
### 回调示例：退款成功
```json
{
"event": "refund.success",
"protocol": "system",
"mchNo": "M200000001",
"appId": "APP001",
"code": 0,
"msg": "success",
"data": {
"refundNo": "R2024120112345700001",
"bizRefundNo": "REFUND20241201001",
"bizOrderNo": "ORDER20241201001",
"amount": 100,
"status": "success",
"finishTime": "2024-12-01 14:00:00"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 14:00:00",
"reqId": "NTF20241201002"
}
```
## 签名验证
商户接收回调后，**必须**验证 `sign` 字段，确保消息由 DaxPay 平台发出且未被篡改。
### 验签步骤
1. 获取回调 JSON 中的所有字段。
2. 移除 `sign` 字段。
3. 排除值为空的字段。
4. 将剩余字段按 key 的 ASCII 码升序排列。
5. 拼接为 `key1=value1&key2=value2` 格式。
6. 使用**平台公钥**以 `SHA256withRSA` 验签。
务必先验签通过后再处理业务逻辑，避免伪造通知导致数据不一致。
验签代码示例参见 [签名机制](https://doc.plus.daxpay.cn/api/signature.md#java-验签响应回调)。
## 商户响应
验签通过且业务处理成功后，商户系统应返回：
- HTTP 状态码：2xx（200-299）
- 响应体：`SUCCESS`（大小写不敏感，前后空格会被自动 trim）
```text
SUCCESS
```
返回非 `SUCCESS` 或 HTTP 非 2xx 或超时（15 秒），系统将按上述 [重试策略](#重试策略) 重新发送通知。
---
# 同步跳转
**源**: https://doc.plus.daxpay.cn/api/notice/sync-callback.md
# 同步跳转
## 概述
同步跳转（Sync Callback）是支付完成后，平台将**用户浏览器**（而非商户服务器）跳转回商户 `returnUrl` 的通知方式。跳转 URL 在商户 `returnUrl` 基础上追加订单关键参数，并用**平台私钥签名**，商户可用**平台公钥验签**确认跳转来源可信。
与 [异步回调](https://doc.plus.daxpay.cn/api/notice/callback.md) 的本质区别：
| 维度 | 同步跳转 | 异步回调 |
| --- | --- | --- |
| 接收方 | 商户**页面**（浏览器） | 商户**服务器** |
| 传递方式 | 浏览器 302 跳转，参数拼在 URL query | 服务端 HTTP POST（JSON）或 MQ 推送 |
| 触发时机 | 用户支付完成后浏览器回跳 | 订单状态变更后立即投递 |
| 可靠性 | 一次，无重试（用户可关闭浏览器） | 16 次递增重试 |
| 验签 | 平台公钥验签 query 参数 | 平台公钥验签报文 |
| 用途 | 展示"支付成功"结果页 / 引导用户回商户 | 处理订单状态变更业务 |
同步跳转依赖浏览器行为：用户可能关闭页面、网络中断、浏览器崩溃，导致跳转丢失或重复。**订单最终状态必须以异步回调或主动查询接口为准**，商户不应仅凭同步跳转参数落库对账。
## 完整流程
```mermaid
sequenceDiagram
participant M as 商户系统
participant P as DaxPay 平台
participant C as 支付通道
participant U as 用户浏览器
M->>P: 下单(携带 returnUrl)
P-->>M: 返回 tradeNo
P->>C: 发起支付(支付宝 PC/WAP 设同步回跳地址为平台结果页)
C->>U: 拉起收银台/跳转支付
U->>C: 完成支付
C->>U: 浏览器回跳平台结果页 /pay-result/{tradeNo}
U->>P: 结果页查单(无签名接口)
P-->>U: 订单状态 + 带签名跳转地址(仅 paid + 有 returnUrl)
U->>M: 倒计时后跳转商户 returnUrl(带签名参数)
P-->>M: 异步回调(服务端, 权威状态)
```
1. 商户下单时传入 `returnUrl`（[统一支付](https://doc.plus.daxpay.cn/api/payment/create.md) / [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md)）。
2. 平台发起支付；**仅支付宝 PC/WAP 网页支付**会把通道同步回跳地址设置为平台 H5 结果页 `{paymentGatewayBaseUrl}/pay-result/{tradeNo}`。
3. 支付完成后，通道把用户浏览器带回平台结果页。
4. 结果页凭 `tradeNo` 调用平台无签名查询接口，获取订单权威状态。
5. 状态为 `paid` 且订单存在商户 `returnUrl` 时，平台生成**带签名**的跳转地址（订单参数追加到 returnUrl）。
6. 结果页倒计时（3 秒）后自动跳转商户页面；无 `returnUrl` 或非 `paid` 则展示平台结果结束页。
7. 商户页面收到跳转后**先验签，再展示结果**；最终订单状态以异步回调为准。
## 跳转参数
平台生成的跳转地址 = 商户 `returnUrl` + query 参数。若 `returnUrl` 自身已携带参数，平台以 `&` 衔接；参数值做 URL 编码。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| code | int | 状态码（`0` = 成功） |
| msg | string | 状态描述 |
| tradeNo | string | 资金交易号（平台生成，反查权威） |
| orderNo | string | 平台业务单号（空值时不携带） |
| bizOrderNo | string | 商户业务单号（空值时不携带） |
| status | string | 订单状态（同步跳转恒为 `paid`） |
| amount | long | 订单金额（分，空值时不携带） |
| sign | string | 平台 RSA 签名（Base64，URL 编码） |
跳转地址示例：
```
https://merchant.example.com/return?code=0&msg=success&tradeNo=T2024120112345700001&orderNo=P2024120112345700001&bizOrderNo=ORDER20241201001&status=paid&amount=100&sign=Base64%E7%AD%BE%E5%90%8D%E5%80%BC
```
## 验签方式
商户接收同步跳转后，**必须**验证 `sign` 字段，确认跳转由 DaxPay 平台发出且参数未被篡改。验签规则与异步回调一致：
1. 取 URL 中全部 query 参数。
2. 移除 `sign` 参数。
3. 排除值为空的参数。
4. 按 key 的 ASCII 码升序排列。
5. 拼接为 `key1=value1&key2=value2` 格式（注意 query 中的值是 URL 解码后的原文）。
6. 使用**平台公钥**以 `SHA256withRSA` 验签。
验签代码示例参见 [签名机制](https://doc.plus.daxpay.cn/api/signature.md#java-验签响应回调)。
## 注意事项
同步跳转仅用于"支付完成后把用户带回商户页面并展示结果"，**不作为订单状态落库依据**。用户可能关闭浏览器导致跳转丢失、也可能反复回访触发重复跳转。请始终以异步回调或查询接口为准。
1. **通道覆盖有限**：真正走"通道回跳 → 平台结果页 → 带签名跳商户"闭环的**仅支付宝 PC/WAP 网页支付**。微信/银联/抖音等 JSAPI 场景由前端 H5 查单判定支付成功后跳转；未接入同步回跳的通道，`returnUrl` 不生效（商户仍可自行轮询）。
2. **仅 `paid` 回跳**：`failed` / `closed` / `expired` 状态不会跳转商户，用户在平台结果页看到对应状态与"关闭页面"按钮。
3. **状态未就绪不跳转**：支付成功后通道回调可能有短暂延迟。平台倒计时（3 秒）缓冲后查单；若订单仍未进入 `paid`，平台**不生成跳转地址、不跳转**——宁可停留在结果页，也**不会裸跳无签名的 returnUrl**（无签名地址商户无法验签，且会掩盖真实问题）。
4. **重入已支付订单不自动跳**：已支付订单被再次扫码或回访时，只展示成功结果卡，**不自动跳转**；用户可点击"返回商户"按钮手动跳转。
5. **PC 聚合引导页不回跳**：PC 端展示二维码的聚合引导页在支付完成后**不回跳**商户 `returnUrl`（支付发生在手机端，手机端才是回跳设备），避免手机与 PC 双端重复回跳商户造成重复处理。
6. **会话级幂等**：同一浏览器会话内仅自动跳转一次（前端 sessionStorage 标记）。换设备、清缓存、无痕模式下可能再次触发跳转——**无服务端幂等**，商户侧需自行容忍重复跳转。
7. **tradeNo 获取**：跳转参数中的 `tradeNo` 与支付发起响应 `NormalPayResult.tradeNo` 对应。商户如需提前保存，应使用**支付发起响应**中的值；预下单/查单早期阶段 `tradeNo` 可能为空（资金交易在发起支付时才创建）。
8. **不含 attach**：同步跳转是精简参数集，**不携带商户扩展参数 `attach`**。需要完整订单快照（含 attach、通道、支付时间等）请以异步回调为准。
9. **returnUrl 拼接兼容**：`returnUrl` 自身若已有 query 参数，平台以 `&` 衔接；空字段参数不会出现（如 `orderNo`/`bizOrderNo`/`amount` 可能缺失）。商户页面需容忍未知/缺失参数。
10. **平台配置**：平台需配置 `paymentGatewayBaseUrl`（平台配置-基础配置），否则无法生成支付宝同步回跳地址。
11. **必做验签**：跳转 URL 可被任何人构造（returnUrl 本身公开），**必须验签**后再处理，防止伪造跳转诱导用户。
## 商户接入步骤
1. 下单时传入 `returnUrl`（[统一支付](https://doc.plus.daxpay.cn/api/payment/create.md) 或 [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md) 的 `returnUrl` 参数，最长 200 字符）。
2. 保存支付发起响应的 `tradeNo`（用于对账与主动查询）。
3. 用户支付完成后，浏览器被带回商户 `returnUrl`，解析 query 参数。
4. **先用平台公钥验签**，验签通过后再展示订单结果。
5. 订单最终状态以**异步回调**或主动查询为准，同步跳转仅作页面引导。
---
# 获取用户标识（通用认证）
**源**: https://doc.plus.daxpay.cn/api/open/get-openid.md
# 获取用户标识（通用认证）
## 接口说明
对外提供获取用户标识（openId / userId）的**重定向式**接口。对接方构建签名 URL 引导用户浏览器访问，系统完成第三方 OAuth 后，**重定向回对接方回调地址**并携带用户标识和签名。
适用场景：对接方需要通过 DaxPay 获取微信 openId / 支付宝 userId / 抖音 openId，用于自有业务（非支付场景）。
[获取授权链接](https://doc.plus.daxpay.cn/api/assist/generate-auth-url.md) 是 POST JSON 接口，返回 authUrl 由前端自行跳转，用于支付前取 openId。
本接口是 GET 重定向接口，系统自动完成 OAuth 全流程并重定向回对接方，用于非支付场景获取用户标识。
## 请求地址
`GET /unipay/open/auth/get-openid`
- 认证：RSA 签名（所有参数参与签名）
- 响应：302 重定向（非 JSON）
## 请求参数
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| mchNo | string | 是 | 32 | 商户号 |
| appId | string | 否 | 32 | 应用号 |
| authType | string | 是 | 32 | 认证类型（`wechat` / `alipay` / `douyin`） |
| redirectUrl | string | 是 | 500 | 回调地址（获取到用户标识后重定向的目标地址，RESTful 风格，不要拼接 query 参数） |
| channelMchNo | string | 否 | 32 | 通道商户号（微信/抖音场景用于定位通道应用） |
| reqId | string | 是 | 64 | 请求 ID（商户侧生成，参与签名） |
| reqTime | string | 是 | - | 请求时间（北京时间，格式 `yyyy-MM-dd HH:mm:ss`，参与签名） |
| nonceStr | string | 否 | 32 | 随机数（参与签名） |
| sign | string | 是 | 1024 | 商户签名（使用商户私钥签名，所有非空参数按 ASCII 字典序排列） |
### 请求示例
```
GET /unipay/open/auth/get-openid?mchNo=M200000001&appId=APP001&authType=wechat&redirectUrl=https%3A%2F%2Fwww.merchant.com%2Fcallback&reqId=REQ20241201020&reqTime=2024-12-01+12%3A00%3A00&nonceStr=abc123&sign=Base64签名值
```
## 响应方式
### 第一步：302 重定向到第三方 OAuth
验签通过后，系统返回 302 重定向到第三方（微信/支付宝/抖音）的 OAuth 授权页面。
### 第二步：OAuth 回调
用户授权后，第三方回调到 `/unipay/open/auth/callback?code=xxx&state=authToken`，系统用 code 换取用户标识。
### 第三步：302 重定向到对接方回调地址
系统将用户标识和签名拼接为 query 参数，302 重定向到对接方的 `redirectUrl`：
```
https://www.merchant.com/callback?return_code=10000&return_msg=成功&openid=oUpF8uMuAJO_M2pxb1Q9zNjWeS6o&sign=Base64签名值
```
## 回调参数
重定向到对接方 `redirectUrl` 时携带的参数：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| return_code | string | 状态码：`10000`=成功，`10001`=失败 |
| return_msg | string | 状态描述 |
| openid | string | 用户标识（微信/抖音场景返回） |
| userid | string | 用户标识（支付宝场景返回） |
| sign | string | 平台签名（对接方使用平台公钥验签） |
### 成功回调示例
```
https://www.merchant.com/callback?return_code=10000&return_msg=成功&openid=oUpF8uMuAJO_M2pxb1Q9zNjWeS6o&sign=953A3CE8C278BB7A8BA277419724C3FD
```
### 失败回调示例
```
https://www.merchant.com/callback?return_code=10001&return_msg=获取openId失败&sign=...
```
## 三通道说明
| authType | 认证方式 | 配置来源 | 返回标识 |
| --- | --- | --- | --- |
| wechat | 公众号 OAuth（snsapi_base 静默授权） | 商户通道绑定的微信应用（WxAppFacade 解析） | openid |
| alipay | auth_base 静默授权 | 平台级支付宝配置（PlatformAlipayAuthConfig） | userid |
| douyin | H5 silent_auth 静默授权 | 商户通道绑定的抖音应用（DouyinDirectApp） | openid |
抖音 silent_auth 仅在抖音 App 内 WebView 中可用。对接方需确保用户在抖音 App 内打开授权链接。
## 验签说明
回调参数的签名规则与支付接口一致：
1. 参数名按 ASCII 字典序排序
2. 空值参数不参与签名
3. 使用平台公钥验签
详见 [签名说明](https://doc.plus.daxpay.cn/api/signature.md)。
---
# 接口概览
**源**: https://doc.plus.daxpay.cn/api/overview.md
# 接口概览
## 接口风格
- **RESTful** 风格，接口命名 **kebab-case**（如 `pay-order` 而非 `payOrder`）
- 基于 HTTP 协议，请求与响应均为 `JSON` 格式
## 两层 API 架构
DaxPay 对外提供两层 API，认证方式与响应格式不同：
| 层级 | 路径前缀 | 认证方式 | 响应类 | 用途 |
| --- | --- | --- | --- | --- |
| **支付 API** | `/unipay/*` | RSA 签名验签 | `DaxResult` | 服务器对服务器调用（下单、查询、关闭等） |
| **管理 API** | `/mch/*` | Sa-Token 会话 | `Result` | 商户端 Web 面板操作（退款、列表、同步等） |
支付 API 面向商户后端系统，通过 RSA 签名认证，无需登录态；管理 API 面向商户 Web 面板，通过 `Accesstoken` 请求头（Sa-Token）认证。
## 支付 API 的三类接口
`/unipay/*` 下按业务场景细分为三类：
| 类别 | 路径前缀 | 场景 | 文档 |
| --- | --- | --- | --- |
| **直连支付** | `/unipay/pay`、`/unipay/close`、`/unipay/refund`、`/unipay/query/*`、`/unipay/sync/*` | 商户后端已确定通道与支付方式 | [统一支付](https://doc.plus.daxpay.cn/api/payment/create.md) |
| **网关支付** | `/unipay/gateway/*` | 由平台收银台/聚合页选择支付方式 | [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md) |
| **分账** | `/unipay/alloc`、`/unipay/query/alloc-order`、`/unipay/sync/order/alloc` | 对分账订单发起分账、查询与同步 | [发起分账](https://doc.plus.daxpay.cn/api/payment/alloc.md) |
| **退款查询** | `/unipay/query/refund-order` | 按退款单号精确查询单笔退款 | [查询退款单](https://doc.plus.daxpay.cn/api/query/refund-order.md) |
| **网关认证** | `/unipay/gateway/auth/*`、`/unipay/gateway/cashier/auth` | 网关落地页获取用户 openId/userId（OAuth 授权，无商户签名） | [获取授权链接](https://doc.plus.daxpay.cn/api/assist/generate-auth-url.md) |
## 基础地址
```
http://{系统域名}:{端口}
```
示例：`https://your-domain.com`（生产环境），本地开发默认端口 `19999`。
## 对接流程
1. **注册商户**：在管理平台注册商户，获取商户号（mchNo）和应用 ID（appId）。
2. **配置密钥**：生成 RSA 密钥对，将**商户公钥**注册到平台；平台分配**平台公钥**用于验签响应。
3. **接口调用**：按本文档定义的规范构造请求（含签名），发起支付、查询、关闭等请求。
4. **接收回调**：配置异步通知地址（`notifyUrl`），接收支付/退款结果通知。
## 通用请求头
| 参数名 | 必填 | 描述 |
| --- | --- | --- |
| Content-Type | 是 | `application/json`，所有请求均为 JSON 格式 |
| Accesstoken | 管理API必填 | Sa-Token 会话令牌（仅 `/mch/*` 管理接口需要；支付 API `/unipay/*` 不需要） |
## 签名机制
支付 API（`/unipay/*`）使用 RSA 签名认证，**签名字段在请求体内**（非请求头）：
| 字段 | 位置 | 描述 |
| --- | --- | --- |
| sign | 请求体 | RSA 签名值（Base64 编码） |
| reqTime | 请求体 | 请求时间（`yyyy-MM-dd HH:mm:ss`，GMT+8） |
| reqId | 请求体 | 请求唯一标识，防重放 |
| nonceStr | 请求体 | 随机字符串，防重放 |
签名生成细节参见 [签名机制](https://doc.plus.daxpay.cn/api/signature.md)。
## 通用响应体（支付 API）
`DaxResult` 结构：
```json
{
"code": 0,
"msg": "success",
"data": {},
"sign": "Base64签名值",
"resTime": "2024-12-01 20:00:00",
"reqId": "REQ20241201001"
}
```
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息 |
| data | object | 业务数据 |
| sign | string | 平台对响应的 RSA 签名，商户可验签 |
| resTime | string | 响应时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| reqId | string | 请求 ID（回显入参 reqId） |
支付 API 响应字段为 `msg`（非 `message`）。管理 API（`Result`）使用 `message`。
## 通用约定
### 请求方式
支付 API 接口使用 `POST` 方式请求，请求体为 JSON 格式。管理 API 查询接口使用 `GET`，操作接口使用 `POST`。
### 日期格式
支付 API（`/unipay/**`）的**全部**时间字段（请求、响应、异步通知）统一使用**北京时间**格式 `yyyy-MM-dd HH:mm:ss`，**不带时区后缀**：
```json
{ "reqTime": "2024-12-01 12:00:00" }
```
- 平台签名时使用的**时间字面量与报文完全一致**，商户务必用同一字面量参与签名（见[签名机制](https://doc.plus.daxpay.cn/api/signature.md)）；
- 请求时间字段请勿使用 ISO 8601（如 `2024-12-01T04:00:00Z`）或带亚秒精度的写法，与平台规范字面量不一致会导致验签失败（错误码 `20052`）；
- 管理 API（`Result` 包裹的内部接口）的时间字段仍为 ISO 8601 UTC，与本开放接口无关。
### 金额单位
所有金额字段类型为 `Long`，单位为**分**，避免浮点数精度丢失。
例如：`1元` → `100`
### 状态值
状态字段类型为 `String`（非数字），使用语义化的英文小写编码：
- 支付状态（`PayStatusEnum`）：`wait` / `progress` / `success` / `close` / `cancel` / `fail` / `timeout`
- 退款状态（`RefundOrderStatusEnum`）：`progress` / `success` / `fail` / `close`
- 退款标记（`PayRefundStatusEnum`）：`no_refund` / `refunding` / `partial_refund` / `refunded`
## 术语表
| 术语 | 描述 |
| --- | --- |
| mchNo | 商户号（Merchant Number），唯一标识接入商户 |
| appId | 应用 ID，商户下创建的应用标识 |
| RSA 密钥对 | 商户生成 RSA 密钥对，公钥注册到平台，私钥用于签名请求 |
| method | 支付方式，如 `wechat_qr`、`alipay_pc`（见 [PayMethodEnum](https://doc.plus.daxpay.cn/api/payment/create.md#支付方式-method)） |
| product | 支付产品，如 `alipay_pc`、`wechat_native`（见 [通道清单](https://doc.plus.daxpay.cn/getting-started/features.md#通道总数与分布)） |
| orderNo | 系统订单号 |
| bizOrderNo | 商户业务订单号 |
| tradeNo | 交易号（一笔订单可多次尝试，每次生成新交易号） |
---
# 同步分账订单
**源**: https://doc.plus.daxpay.cn/api/payment/alloc-sync.md
# 同步分账订单
## 接口说明
当分账订单状态为 `processing`（分账中）时，商户可主动调用本接口向支付通道发起状态同步，获取最新的分账结果。适用于通道异步推进缓慢、回调延迟或商户需要主动确认状态的场景。
## 请求地址
`POST /unipay/sync/order/alloc`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| allocNo | string | 否* | 100 | 平台分账单号 |
| bizAllocNo | string | 否* | 100 | 商户分账单号 |
> *两个单号至少传一个，优先级：allocNo > bizAllocNo
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201031",
"reqTime": "2024-12-01 12:31:00",
"sign": "Base64签名值",
"allocNo": "A2024120112345700001"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| orderStatus | string | 同步后的分账状态（[AllocOrderStatusEnum](https://doc.plus.daxpay.cn/api/payment/alloc.md#分账状态-allocorderstatusenum)） |
| adjust | boolean | 是否触发了状态调整（同步前后状态是否变化） |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderStatus": "success",
"adjust": true
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:31:00",
"reqId": "REQ20241201031"
}
```
## 使用建议
- 同步是**幂等**操作，可重复调用，不会重复分账或重复通知。
- 同步触发状态变更后，平台会按 [异步回调](https://doc.plus.daxpay.cn/api/notice/callback.md) 流程重新发送通知（事件 `alloc.success` / `alloc.fail`）。
- 分账终态（`success` / `partial` / `fail`）确定后同步将不再调整状态，可结合 `adjust` 判断。
- 分账单详情（含各接收方明细结果）可调用 [分账订单查询](https://doc.plus.daxpay.cn/api/query/alloc-order.md) 获取。
---
# 发起分账
**源**: https://doc.plus.daxpay.cn/api/payment/alloc.md
# 发起分账
## 接口说明
商户系统通过该接口对**分账订单**发起分账。原支付订单须在统一下单（或网关预下单）时声明 `allocation=true`，资金才会被冻结并可发起分账；否则通道将拒绝分账。
接收方列表在请求中直接传入完整明细（极简模式），**分账接收方须提前在通道侧完成绑定**（平台管理端「通道商户详情」提供绑定入口），发起时只做金额拆分。
## 请求地址
`POST /unipay/alloc`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| bizAllocNo | string | 是 | 100 | 商户分账单号（幂等键，同一应用下唯一） |
| tradeNo | string | 否* | 100 | 原支付资金交易号 |
| bizOrderNo | string | 否* | 100 | 原支付商户业务订单号 |
| title | string | 否 | 100 | 分账标题 |
| description | string | 否 | 500 | 分账描述 |
| receivers | object[] | 是 | — | 接收方列表（至少一个） |
| attach | string | 否 | 500 | 商户扩展参数，回调时原样返回 |
| notifyUrl | string | 否 | 200 | 异步通知地址 |
> *`tradeNo` 与 `bizOrderNo` 至少传一个，优先级：tradeNo > bizOrderNo
### receivers 接收方元素
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| receiverType | string | 是 | 32 | 接收方类型（见下方码表） |
| receiverAccount | string | 是 | 128 | 接收方账号 |
| receiverName | string | 否 | 64 | 接收方姓名（部分通道/类型必填，如微信商户号类型须填商户全称） |
| amount | number | 是 | — | 分账金额（元，两位小数，最小 0.01，最大 99999999.99） |
### receiverType 码表
对应后端枚举 `AllocReceiverTypeEnum`（对外统一使用大写类型码）：
| 类型 | 说明 |
| --- | --- |
| MERCHANT_ID | 商户号（微信/抖音） |
| PERSONAL_OPENID | 个人 openid（微信/抖音） |
| PERSONAL_SUB_OPENID | 子商户应用个人 openid（仅微信服务商接收方绑定使用） |
| USER_ID | 支付宝用户 ID（2088 开头） |
| LOGIN_NAME | 支付宝登录账号（手机号/邮箱） |
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201030",
"reqTime": "2024-12-01 12:30:00",
"sign": "Base64签名值",
"bizAllocNo": "ALOC20241201001",
"tradeNo": "T2024120112345700001",
"title": "订单分账",
"receivers": [
{
"receiverType": "USER_ID",
"receiverAccount": "2088xxxxxxxxxxxx",
"receiverName": "张三",
"amount": 30.00
},
{
"receiverType": "USER_ID",
"receiverAccount": "2088yyyyyyyyyyyy",
"amount": 70.00
}
],
"notifyUrl": "https://your-domain.com/notify"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| allocNo | string | 平台分账单号 |
| bizAllocNo | string | 商户分账单号 |
| status | string | 分账状态（[AllocOrderStatusEnum](#分账状态-allocorderstatusenum)） |
| errorMsg | string | 错误信息（失败时返回） |
### 分账状态 AllocOrderStatusEnum
| status | 说明 |
| --- | --- |
| processing | 分账中（已受理，等待通道异步推进） |
| success | 分账成功（全部接收方成功） |
| partial | 部分成功（部分接收方成功，部分失败，单次分账终态） |
| fail | 分账失败（全部接收方失败） |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"allocNo": "A2024120112345700001",
"bizAllocNo": "ALOC20241201001",
"status": "processing"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:30:00",
"reqId": "REQ20241201030"
}
```
## 使用建议
- **下单即声明分账**：原支付订单须在 [统一支付](https://doc.plus.daxpay.cn/api/payment/create.md)（或 [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md)）时传 `allocation=true`，资金冻结后才可发起分账；未声明分账的订单通道会拒绝分账。
- **接收方提前绑定**：接收方绑定由调用方提前在通道侧完成（管理端「通道商户详情」提供绑定入口），绑定关系按通道商户区分，同通道商户同类型同账号不可重复绑定；发起分账时接收方须已绑定。
- **金额约束**：单接收方分账金额为 0.01 ~ 99999999.99 元（最多两位小数）；各接收方金额合计不得超过原订单金额，且须小于原订单剩余可分金额。
- **单次分账即完结**：一次发起即完结，无追加分账；`partial`（部分成功）为终态，失败接收方需重新发起分账。
- **异步通知**：分账终态确定后平台按 `notifyUrl` 通知（事件 `alloc.success` / `alloc.fail`）；也可调用 [分账同步](https://doc.plus.daxpay.cn/api/payment/alloc-sync.md) 主动拉取通道状态。
---
# 关闭撤销订单
**源**: https://doc.plus.daxpay.cn/api/payment/close.md
# 关闭撤销订单
## 接口说明
关闭指定订单。只有未支付（`wait` / `progress`）的订单可以被关闭。
部分通道支持**撤销**方式（如微信、银联的当天撤销），通过 `useCancel=true` 触发；不支持的通道会忽略该参数并统一走关单逻辑。
- **关闭（close）**：订单未支付时主动终止，资金未发生，幂等。
- **撤销（cancel）**：针对当日已扣款但未最终确认的交易，触发通道撤销（如银联当日撤销），资金会退回买家。
## 请求地址
`POST /unipay/close`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| orderNo | string | 否* | 100 | 平台业务单号 |
| bizOrderNo | string | 否* | 100 | 商户订单号 |
| useCancel | boolean | 否 | — | 是否使用撤销方式关闭（部分通道支持，默认 `false`） |
> *`orderNo`、`bizOrderNo` 至少传一个，优先级：orderNo > bizOrderNo
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201002",
"reqTime": "2024-12-01 12:05:00",
"sign": "Base64签名值",
"orderNo": "P2024120112345700001",
"useCancel": false
}
```
## 响应参数
`DaxResult`，`data` 为 `null`。
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": null,
"sign": "Base64签名值",
"resTime": "2024-12-01 12:05:00",
"reqId": "REQ20241201002"
}
```
## 支持撤销的通道
| 通道 | 关闭 | 撤销 |
| --- | --- | --- |
| 支付宝 | ✓ | ✓ |
| 微信支付 | ✓ | ✗（V3 仅关单） |
| 银联商务 | ✓ | ✓ |
| 拉卡拉 | ✓ | 视签约 |
| 富友 | ✓ | ✗ |
| 杉德 | ✓ | ✗ |
当通道不支持撤销时，`useCancel=true` 会被静默忽略，请求仍以关单方式处理，不会返回错误。生产对接时请按上表确认通道是否支持撤销。
---
# 统一支付
**源**: https://doc.plus.daxpay.cn/api/payment/create.md
# 统一支付
## 接口说明
商户系统通过该接口发起支付请求，系统根据支付产品和方式返回对应的支付参数体（`payBody`），商户前端据此调起支付或展示二维码。
适用于商户后端已确定通道与支付方式的「直连支付」场景；若需由平台收银台/聚合页选择支付方式，请使用 [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md)。
## 请求地址
`POST /unipay/pay`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
### 基础参数（所有 `/unipay/*` 接口通用）
继承自 `PaymentCommonParam` / `MerchantPaymentCommonParam`：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| mchNo | string | 是 | 32 | 商户号 |
| appId | string | 否 | 32 | 应用 ID |
| channelMchNo | string | 否 | 32 | 通道商户号（调试或直接指定通道时传入，正常路由场景留空） |
| reqId | string | 是 | 64 | 请求唯一标识 |
| nonceStr | string | 否 | 32 | 随机字符串 |
| sign | string | 是 | 1024 | RSA 签名（Base64） |
| reqTime | string | 是 | — | 请求时间（`yyyy-MM-dd HH:mm:ss`，GMT+8） |
| clientIp | string | 否 | 64 | 客户端 IP |
### 业务参数
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| bizOrderNo | string | 是 | 100 | 商户订单号，商户系统唯一 |
| title | string | 是 | 100 | 订单标题 |
| description | string | 否 | 50 | 订单描述 |
| amount | long | 是 | — | 订单金额，单位分（最小 1，最大 9999999999） |
| currency | string | 否 | 8 | 币种（ISO 4217 三位字母代码，如 `cny`/`usd`/`jpy`/`eur`/`hkd`/`gbp`，缺省 `cny`；国际通道按商户配置或订单参数透传） |
| product | string | 否 | 32 | 支付产品编码（为空时由路由引擎自动选择） |
| method | string | 否 | 32 | 支付方式，如 `wechat_qr`、`alipay_pc`（见下方码表） |
| capability | string | 否 | 32 | 支付能力编码（直接指定通道时作为输入参与校验） |
| openId | string | 否 | 128 | 用户标识（微信 jsapi/mini 场景必填） |
| channelAppId | string | 否 | 128 | 通道应用 ID（非空则强制使用，须预先配置） |
| authCode | string | 否 | 128 | 授权码（付款码/被扫支付必填） |
| limitPay | string[] | 否 | 10 | 限制支付的支付方式列表（如 `no_credit` 禁用信用卡） |
| extraParam | string | 否 | 2048 | 通道扩展参数（JSON） |
| goodsDetail | object[] | 否 | 50 | 订单商品明细列表（用于单品营销、电子发票等） |
| notifyUrl | string | 否 | 200 | 异步通知地址 |
| returnUrl | string | 否 | 200 | 同步跳转地址 |
| attach | string | 否 | 500 | 附加数据，回调时原样返回 |
| expiredTime | string | 否 | — | 订单过期时间（`yyyy-MM-dd HH:mm:ss`，GMT+8，空则默认 30 分钟） |
| terminal | object | 否 | — | 终端信息（线下 POS/收银台场景） |
| allocation | boolean | 否 | — | 是否分账订单（传 `true` 后该笔订单资金将被冻结，仅可通过 [发起分账](https://doc.plus.daxpay.cn/api/payment/alloc.md) 拆分；默认 `false`） |
跟随通道路由时一般必填；被扫场景可仅传 `authCode`（平台按前缀识别回填）；已直接指定 `channelMchNo` + `capability` 时可空（按能力反推）。
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201001",
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
"reqTime": "2024-12-01 12:00:00",
"sign": "Base64签名值",
"bizOrderNo": "ORDER20241201001",
"title": "测试商品",
"amount": 100,
"method": "wechat_qr",
"notifyUrl": "https://your-domain.com/notify",
"returnUrl": "https://your-domain.com/return"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| orderId | long | 订单 ID |
| bizOrderNo | string | 商户订单号 |
| orderNo | string | 平台业务单号 |
| tradeNo | string | 资金交易号 |
| status | string | 支付状态（[PayStatusEnum](#支付状态-paystatusenum)） |
| payBody | string | 支付参数体（二维码内容、调起参数或跳转地址） |
| payBodyType | string | 支付参数体类型（[PayBodyTypeEnum](#paybodytype-取值)） |
### payBodyType 取值
对应后端枚举 `PayBodyTypeEnum`：
| 类型 | 说明 | payBody 示例 |
| --- | --- | --- |
| `link` | 支付链接（跳转） | `https://open.weixin.qq.com/...` |
| `jsapi` | JSAPI 调起参数对象 | JSON 字符串，前端直接用于调起 SDK |
| `from` | 表单数据（自动提交表单 HTML） | `` |
| `identifier` | 标识码（如付款码场景的标识） | 通道返回的纯标识字符串 |
| `qr_code` | 二维码内容（前端渲染成二维码图片） | `weixin://wxpay/bizpayurl?pr=xxxxx` |
| `json` | JSON 对象（通道自定义结构） | 通道约定的 JSON 字符串 |
旧版文档曾使用 `code_url` / `pay_info` / `redirect_url`，**这些不是真实枚举值**。请以上表为准。
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderId": 1853123456789012345,
"bizOrderNo": "ORDER20241201001",
"orderNo": "P2024120112345700001",
"tradeNo": "T2024120112345700001",
"status": "progress",
"payBody": "weixin://wxpay/bizpayurl?pr=xxxxx",
"payBodyType": "qr_code"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:00:00",
"reqId": "REQ20241201001"
}
```
## 支付方式（method）
`method` 字段对应 `PayMethodEnum`，按渠道分组：
### 微信支付
| method | 说明 |
| --- | --- |
| wechat_qr | 微信扫码支付（Native） |
| wechat_jsapi | 微信 JSAPI 支付（公众号） |
| wechat_mini | 微信小程序支付 |
| wechat_h5 | 微信 H5 支付 |
| wechat_app | 微信 APP 支付 |
| wechat_barcode | 微信付款码支付（被扫） |
| wechat_cashier | 微信收银台支付 |
### 支付宝
| method | 说明 |
| --- | --- |
| alipay_qr | 支付宝扫码支付 |
| alipay_jsapi | 支付宝生活号支付（含小程序） |
| alipay_pc | 支付宝 PC 网站支付 |
| alipay_h5 | 支付宝 H5 支付 |
| alipay_app | 支付宝 APP 支付 |
| alipay_barcode | 支付宝付款码支付（被扫） |
### 银联
| method | 说明 |
| --- | --- |
| union_qr | 银联扫码支付 |
| union_jsapi | 银联 JSAPI 支付 |
| union_h5 | 银联 H5 支付 |
| union_barcode | 银联付款码支付（被扫） |
### 抖音支付
| method | 说明 |
| --- | --- |
| douyin_qr | 抖音扫码支付 |
| douyin_jsapi | 抖音 JSAPI 支付 |
| douyin_h5 | 抖音 H5 支付 |
| douyin_app | 抖音 APP 支付 |
### 聚合支付
| method | 说明 |
| --- | --- |
| aggregate_pay_qrcode | 聚合扫码支付（通道原生一码多付） |
### 境外卡（预留）
| method | 说明 |
| --- | --- |
| visa_card_gateway | Visa 网关支付 |
| visa_card_present | Visa 刷卡支付 |
| mastercard_card_gateway | Mastercard 网关支付 |
| mastercard_card_present | Mastercard 刷卡支付 |
## 支付状态（PayStatusEnum）
| status | 说明 |
| --- | --- |
| wait | 等待中（未指定通道和支付方式） |
| progress | 处理中（已发起通道调用） |
| success | 支付成功 |
| close | 已关闭 |
| cancel | 已撤销 |
| fail | 支付失败 |
| timeout | 已超时 |
---
# 网关预下单
**源**: https://doc.plus.daxpay.cn/api/payment/pre-pay.md
# 网关预下单
## 接口说明
用于「网关支付」场景：商户后端不预先指定支付方式，而是先通过本接口创建网关订单并获得 **H5 落地页 URL** 与 **小程序映射 URL**，按用户设备引导用户进入平台收银台或聚合扫码页，由用户在前端选择支付方式后再发起真实支付。
适用于：
- **统一收银台（cashier）**：平台提供的多支付方式选择页面
- **聚合扫码（aggregate）**：一码多付，自动识别用户钱包
## 请求地址
`POST /unipay/gateway/pre-pay`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| bizOrderNo | string | 是 | 100 | 商户订单号 |
| title | string | 是 | 100 | 订单标题 |
| description | string | 否 | 50 | 订单描述 |
| amount | long | 是 | — | 订单金额（分，最小 1，最大 9999999999） |
| currency | string | 否 | 8 | 币种（ISO 4217 三位字母代码，如 `cny`/`usd`/`jpy`/`eur`/`hkd`/`gbp`，缺省 `cny`；国际通道按商户配置或订单参数透传） |
| gatewayPayType | string | 是 | 32 | 网关类型：`cashier`（统一收银台）/ `aggregate`（聚合扫码） |
| notifyUrl | string | 否 | 256 | 异步通知地址 |
| returnUrl | string | 否 | 256 | 同步跳转地址 |
| attach | string | 否 | 512 | 商户附加参数，回调原样返回 |
| extraParam | string | 否 | 2048 | 通道扩展参数（JSON） |
| expiredTime | string | 否 | — | 过期时间（`yyyy-MM-dd HH:mm:ss`，GMT+8） |
| storeNo | string | 否 | 64 | 门店号 |
| goodsDetail | object[] | 否 | — | 商品明细列表 |
| allocation | boolean | 否 | — | 是否分账订单（传 `true` 后资金冻结，仅可通过 [发起分账](https://doc.plus.daxpay.cn/api/payment/alloc.md) 拆分；默认 `false`） |
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201010",
"reqTime": "2024-12-01 12:00:00",
"sign": "Base64签名值",
"bizOrderNo": "ORDER20241201001",
"title": "测试商品",
"amount": 100,
"gatewayPayType": "cashier",
"notifyUrl": "https://your-domain.com/notify",
"returnUrl": "https://your-domain.com/return"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| orderNo | string | 平台网关单号（后续查询/同步用此号） |
| bizOrderNo | string | 商户业务单号 |
| status | string | 业务状态（`GatewayOrderStatusEnum`，初始为 `wait_pay`） |
| h5Url | string | H5 落地页 URL（cashier 为 `/cashier/{orderNo}`，aggregate 为 `/aggregate/{orderNo}`） |
| miniUrl | string | 小程序映射 URL（cashier 为 `/cm/{orderNo}`，aggregate 为 `/am/{orderNo}`；通过微信等平台普通链接二维码规则拉起小程序） |
| expiredTime | string | 过期时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderNo": "G2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"status": "wait_pay",
"h5Url": "https://your-domain.com/cashier/G2024120112345700001",
"miniUrl": "https://your-domain.com/cm/G2024120112345700001",
"expiredTime": "2024-12-01 12:30:00"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:00:00",
"reqId": "REQ20241201010"
}
```
## 后续流程
1. 商户后端拿到 `h5Url` 与 `miniUrl` 后按设备返回给前端：浏览器使用 `h5Url`，小程序普通链接二维码使用 `miniUrl`。
2. `cashier` 使用 `/cm/{orderNo}` 映射到统一收银台小程序；`aggregate` 使用 `/am/{orderNo}` 映射到聚合支付小程序。
3. 用户在网关页完成支付后，平台通过 `notifyUrl` 异步通知商户（事件 `pay.success`）。
4. 商户也可通过 [网关订单查询](https://doc.plus.daxpay.cn/api/query/gateway-order.md) 主动查询订单状态。
## 微信普通链接二维码配置
在微信公众平台/小程序后台配置普通链接二维码规则：
- `/cm/*` → `pages-weixin/gateway-cashier/index`（统一收银台小程序）
- `/am/*` → `pages-weixin/aggregate-pay/index`（聚合支付小程序）
小程序从普通链接二维码进入时，微信会把完整 URL 放在 `options.q` 中；页面分别从 `/cm/{orderNo}` 或 `/am/{orderNo}` 提取平台网关单号。
---
# 退款同步
**源**: https://doc.plus.daxpay.cn/api/payment/refund-sync.md
# 退款同步
## 接口说明
主动向支付通道同步退款状态。当退款状态为 `progress` 时调用，获取最新退款结果。适用于通道回调延迟或需要主动确认的场景。
## 请求地址
`POST /mch/order/refund/sync?id={退款单ID}`
- 认证：Sa-Token（请求头 `Accesstoken`）
- 响应：`Result`
`id` 是查询参数（`@RequestParam`），**不是** 请求体。请求体为空即可。
## 请求参数
| 参数 | 位置 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| id | query | long | 是 | 退款单 ID（数字） |
### 请求示例
```http
POST /mch/order/refund/sync?id=1853123456789012345 HTTP/1.1
Host: your-domain.com
Accesstoken: xxxx-xxxx-xxxx
Content-Type: application/json
```
## 响应参数
`Result`，`data` 字段结构同 [申请退款 - 响应参数](https://doc.plus.daxpay.cn/api/payment/refund.md#响应参数)，主要返回：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| id | long | 退款单 ID |
| refundNo | string | 系统退款号 |
| status | string | 同步后的退款状态（[RefundOrderStatusEnum](https://doc.plus.daxpay.cn/api/payment/refund.md#退款状态-refundorderstatusenum)） |
| finishTime | string | 退款完成时间（UTC） |
| errorMsg | string | 错误信息（失败时） |
### 响应示例
```json
{
"code": 0,
"message": "success",
"data": {
"id": "1853123456789012345",
"refundNo": "R2024120112345700001",
"status": "success",
"finishTime": "2024-12-01T06:00:00Z"
}
}
```
---
# 申请退款
**源**: https://doc.plus.daxpay.cn/api/payment/refund.md
# 申请退款
## 接口说明
对已支付成功的订单发起退款。
**注意**：
- 支持部分退款和全额退款
- 退款金额不能超过订单可退款余额（查询订单返回的 `refundableBalance`）
- 同一笔订单的多次退款请求，`bizRefundNo` 必须唯一（不传则由系统生成）
## 接口列表
退款接口属于**管理 API**（`/mch/*`），通过 Sa-Token 会话认证，响应使用 `Result` 包装（字段名为 `message`，非 `msg`）。
支付 API（`/unipay/*`）使用 RSA 签名认证、`DaxResult` 响应；退款接口使用 `Accesstoken` 请求头认证、`Result` 响应。
## 请求地址
`POST /mch/order/refund/refund`
- 认证：Sa-Token（请求头 `Accesstoken`）
- 响应：`Result`
## 请求头
| 参数名 | 必填 | 描述 |
| --- | --- | --- |
| Accesstoken | 是 | Sa-Token 会话令牌 |
| Content-Type | 是 | `application/json` |
## 请求参数
`RefundParam`：
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| tradeNo | string | 否* | 原支付资金交易号（平台 tradeNo） |
| bizOrderNo | string | 否* | 商户业务订单号 |
| amount | long | 是 | 退款金额，单位分（`@Positive`，必须大于 0） |
| bizRefundNo | string | 否 | 商户退款号（不传由系统生成） |
| reason | string | 否 | 退款原因 |
> *`tradeNo`、`bizOrderNo` 至少传一个，优先使用 `tradeNo`。`tradeNo` 解析时若按资金号查不到，会再尝试网关容器 `orderNo` 反查。
### 请求示例
```json
{
"bizOrderNo": "ORDER20241201001",
"amount": 100,
"bizRefundNo": "REFUND20241201001",
"reason": "用户申请退款"
}
```
## 响应参数
`Result`，`data` 字段结构（主要字段，完整 27 字段见源码 `RefundOrderResult`）：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| id | long | 退款单 ID |
| mchNo | string | 商户号 |
| mchName | string | 商户名称（翻译） |
| appId | string | 应用号 |
| refundNo | string | 系统退款号 |
| bizRefundNo | string | 商户退款号 |
| relationOrderNo | string | 实际上送通道的关联号 |
| title | string | 标题 |
| tradeNo | string | 原支付资金交易号 |
| tradeType | string | 原支付交易形态 |
| bizOrderNo | string | 原商户订单号 |
| outOrderNo | string | 通道支付订单号 |
| outRefundNo | string | 通道退款流水号 |
| amount | long | 退款金额（分） |
| orderAmount | long | 原订单总金额（分） |
| currency | string | 币种 |
| reason | string | 退款原因 |
| status | string | 退款状态（[RefundOrderStatusEnum](#退款状态-refundorderstatusenum)） |
| finishTime | string | 退款完成时间（UTC） |
| channel | string | 支付通道 |
| product | string | 支付产品 |
| channelMchNo | string | 通道商户号 |
| channelAppId | string | 通道应用 AppId |
| notifyUrl | string | 异步通知地址 |
| attach | string | 商户附加参数 |
| clientIp | string | 客户端 IP |
| storeNo | string | 门店号 |
| errorMsg | string | 错误信息（失败时） |
### 退款状态（RefundOrderStatusEnum）
| status | 说明 |
| --- | --- |
| progress | 退款中（已创建并调用通道，等待结果） |
| success | 退款成功 |
| fail | 退款失败 |
| close | 退款关闭（超时未确认等） |
### 响应示例
```json
{
"code": 0,
"message": "success",
"data": {
"id": "1853123456789012345",
"refundNo": "R2024120112345700001",
"bizRefundNo": "REFUND20241201001",
"bizOrderNo": "ORDER20241201001",
"tradeNo": "T2024120112345700001",
"amount": 100,
"orderAmount": 100,
"status": "progress",
"reason": "用户申请退款"
}
}
```
## 退款回调
退款成功后，平台会向**原支付订单的 `notifyUrl`** 发送 `event=refund.success` 的异步通知，报文结构见 [异步回调](https://doc.plus.daxpay.cn/api/notice/callback.md)。
---
# 同步支付订单
**源**: https://doc.plus.daxpay.cn/api/payment/sync.md
# 同步支付订单
## 接口说明
当订单状态为 `progress`（处理中）时，商户可主动调用本接口向支付通道发起状态同步，获取最新的支付结果。适用于回调延迟或商户需要主动确认状态的场景。
## 请求地址
`POST /unipay/sync/order/pay`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| orderNo | string | 否* | 100 | 平台业务单号 |
| bizOrderNo | string | 否* | 100 | 商户订单号 |
| outOrderNo | string | 否* | 150 | 通道订单号 |
> *三个订单号至少传一个，优先级：orderNo > bizOrderNo > outOrderNo
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201004",
"reqTime": "2024-12-01 12:15:00",
"sign": "Base64签名值",
"orderNo": "P2024120112345700001"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| orderStatus | string | 同步后的订单状态（[PayStatusEnum](https://doc.plus.daxpay.cn/api/payment/create.md#支付状态-paystatusenum)） |
| adjust | boolean | 是否触发了状态调整（同步前后状态是否变化） |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderStatus": "success",
"adjust": true
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:15:00",
"reqId": "REQ20241201004"
}
```
## 使用建议
- 同步是**幂等**操作，可重复调用，不会重复扣款或重复通知。
- 同步触发状态变更后，平台会按 [异步回调](https://doc.plus.daxpay.cn/api/notice/callback.md) 流程重新发送通知。
- 若通道返回「订单不存在」，平台会按规则将本地订单置为 `fail` 或 `timeout`，需结合 `adjust` 判断。
---
# 查询分账订单
**源**: https://doc.plus.daxpay.cn/api/query/alloc-order.md
# 查询分账订单
## 接口说明
通过分账单号查询分账订单详情，包含分账状态、金额、各接收方明细结果等信息。仅查询本地数据，不调用通道；需要实时通道状态请走 [分账同步](https://doc.plus.daxpay.cn/api/payment/alloc-sync.md)。
## 请求地址
`POST /unipay/query/alloc-order`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| allocNo | string | 否* | 100 | 平台分账单号 |
| bizAllocNo | string | 否* | 100 | 商户分账单号 |
> *两个单号至少传一个，优先级：allocNo > bizAllocNo
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201032",
"reqTime": "2024-12-01 12:32:00",
"sign": "Base64签名值",
"allocNo": "A2024120112345700001"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| allocNo | string | 平台分账单号 |
| bizAllocNo | string | 商户分账单号 |
| tradeNo | string | 原支付资金交易号 |
| bizOrderNo | string | 原支付商户业务订单号 |
| outAllocNo | string | 通道分账单号 |
| amount | long | 分账总金额（分） |
| status | string | 分账状态（[AllocOrderStatusEnum](https://doc.plus.daxpay.cn/api/payment/alloc.md#分账状态-allocorderstatusenum)） |
| finishTime | string | 分账完成时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| channel | string | 支付通道 |
| attach | string | 商户扩展参数 |
| errorMsg | string | 错误信息 |
| details | object[] | 分账明细列表（各接收方结果） |
### details 明细元素
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| receiverType | string | 接收方类型（[AllocReceiverTypeEnum](https://doc.plus.daxpay.cn/api/payment/alloc.md#receivertype-码表)） |
| receiverAccount | string | 接收方账号 |
| receiverName | string | 接收方姓名 |
| amount | long | 分账金额（分） |
| result | string | 明细结果（`pending` 待分账 / `success` 成功 / `fail` 失败） |
| errorMsg | string | 错误信息 |
| finishTime | string | 明细完成时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"allocNo": "A2024120112345700001",
"bizAllocNo": "ALOC20241201001",
"tradeNo": "T2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"outAllocNo": "202412012200000000000001",
"amount": 10000,
"status": "success",
"finishTime": "2024-12-01 12:40:00",
"channel": "alipay",
"attach": "{\"orderId\": 123}",
"details": [
{
"receiverType": "USER_ID",
"receiverAccount": "2088xxxxxxxxxxxx",
"receiverName": "张三",
"amount": 3000,
"result": "success",
"finishTime": "2024-12-01 12:40:00"
},
{
"receiverType": "USER_ID",
"receiverAccount": "2088yyyyyyyyyyyy",
"amount": 7000,
"result": "success",
"finishTime": "2024-12-01 12:40:00"
}
]
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:32:00",
"reqId": "REQ20241201032"
}
```
## 使用建议
- 查询为**幂等**操作，仅返回本地已落库的数据；分账状态可能滞后于通道，实时状态请优先使用 [分账同步](https://doc.plus.daxpay.cn/api/payment/alloc-sync.md)。
- 通过 `details` 可核对各接收方是否到账，`result` 为 `fail` 的明细可查看 `errorMsg` 定位原因。
- 金额字段单位为**分**（`details[].amount` 同），与发起分账时传入的元单位不同，注意换算。
---
# 网关订单查询
**源**: https://doc.plus.daxpay.cn/api/query/gateway-order.md
# 网关订单查询
## 接口说明
查询通过 [网关预下单](https://doc.plus.daxpay.cn/api/payment/pre-pay.md) 创建的网关订单详情。
## 请求地址
`POST /unipay/gateway/query`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数继承自 `PaymentCommonParam`（无需 `mchNo` 签名外的字段，但 `mchNo` 必填）：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| mchNo | string | 是 | 32 | 商户号 |
| appId | string | 否 | 32 | 应用号 |
| reqId / nonceStr / sign / reqTime | — | — | — | 见 [签名机制](https://doc.plus.daxpay.cn/api/signature.md) |
| orderNo | string | 否* | 64 | 平台网关单号 |
| bizOrderNo | string | 否* | 100 | 商户业务单号 |
> *`orderNo`、`bizOrderNo` 至少传一个，优先级：orderNo > bizOrderNo
### 请求示例
```json
{
"mchNo": "M200000001",
"reqId": "REQ20241201011",
"reqTime": "2024-12-01 12:20:00",
"sign": "Base64签名值",
"orderNo": "G2024120112345700001"
}
```
## 响应参数
`DaxResult`，`data` 字段结构（18 字段）：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| orderNo | string | 平台网关单号 |
| bizOrderNo | string | 商户业务单号 |
| gatewayType | string | 网关类型（`cashier` / `aggregate`） |
| title | string | 标题 |
| description | string | 描述 |
| amount | long | 金额（分） |
| currency | string | 币种 |
| status | string | 业务状态（`GatewayOrderStatusEnum`） |
| expiredTime | string | 过期时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| payTime | string | 支付成功时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| channel | string | 支付通道（用户最终选择的通道） |
| method | string | 支付方式 |
| product | string | 支付产品 |
| tradeNo | string | 资金交易号 |
| outOrderNo | string | 通道订单号 |
| fundStatus | string | 资金状态（`PayFundStatusEnum`） |
| attach | string | 商户附加参数（原样返回） |
| returnUrl | string | 同步跳转地址 |
### 网关订单状态（GatewayOrderStatusEnum）
| status | 说明 |
| --- | --- |
| wait_pay | 待支付 |
| paying | 支付中 |
| paid | 已支付 |
| failed | 支付失败 |
| closed | 已关闭 |
| expired | 已过期 |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderNo": "G2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"gatewayType": "cashier",
"title": "测试商品",
"amount": 100,
"currency": "CNY",
"status": "paid",
"payTime": "2024-12-01 12:05:00",
"channel": "wechat",
"method": "wechat_jsapi",
"tradeNo": "T2024120112345700001",
"fundStatus": "success",
"attach": "{\"orderId\": 123}",
"returnUrl": "https://your-domain.com/return"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:20:00",
"reqId": "REQ20241201011"
}
```
---
# 查询支付订单
**源**: https://doc.plus.daxpay.cn/api/query/pay-order.md
# 查询支付订单
## 接口说明
通过订单号查询系统订单详情，包含当前支付状态、金额等信息。
## 请求地址
`POST /unipay/query/pay-order`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| orderNo | string | 否* | 100 | 平台业务单号 |
| bizOrderNo | string | 否* | 100 | 商户订单号 |
> *`orderNo`、`bizOrderNo` 至少传一个，优先级：orderNo > bizOrderNo
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201003",
"reqTime": "2024-12-01 12:10:00",
"sign": "Base64签名值",
"orderNo": "P2024120112345700001"
}
```
## 响应参数
`DaxResult`，`data` 字段结构：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| orderNo | string | 平台业务单号 |
| bizOrderNo | string | 商户订单号 |
| tradeNo | string | 资金交易号 |
| outOrderNo | string | 通道支付订单号 |
| title | string | 订单标题 |
| description | string | 订单描述 |
| channel | string | 支付通道（`ChannelEnum`） |
| method | string | 支付方式（`PayMethodEnum`） |
| limitPay | string | 限制支付类型（`PayLimitPayEnum`） |
| amount | long | 订单金额（分） |
| realAmount | long | 实际支付金额（分） |
| refundableBalance | long | 可退款余额（分） |
| status | string | 支付状态（[PayStatusEnum](https://doc.plus.daxpay.cn/api/payment/create.md#支付状态-paystatusenum)） |
| refundStatus | string | 退款状态（[PayRefundStatusEnum](#退款状态-payrefundstatusenum)） |
| provider | string | 支付渠道（`PayProviderEnum`，如 `WECHAT`/`ALIPAY`） |
| payTime | string | 支付时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| closeTime | string | 关闭时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| expiredTime | string | 过期时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| terminalNo | string | 终端设备编码 |
| storeNo | string | 门店号 |
| buyerId | string | 付款用户 ID |
| attach | string | 附加数据（原样返回） |
| errorMsg | string | 错误信息 |
### 退款状态（PayRefundStatusEnum）
支付订单维度的退款标记：
| refundStatus | 说明 |
| --- | --- |
| no_refund | 未退款 |
| refunding | 退款中 |
| partial_refund | 部分退款 |
| refunded | 全部退款 |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"orderNo": "P2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"tradeNo": "T2024120112345700001",
"outOrderNo": "WX2024120100001",
"title": "测试商品",
"channel": "wechat",
"method": "wechat_qr",
"amount": 100,
"realAmount": 100,
"refundableBalance": 100,
"status": "success",
"refundStatus": "no_refund",
"provider": "WECHAT",
"payTime": "2024-12-01 12:00:00",
"expiredTime": "2024-12-01 12:30:00",
"attach": "{\"orderId\": 123}"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:10:00",
"reqId": "REQ20241201003"
}
```
---
# 退款列表与详情
**源**: https://doc.plus.daxpay.cn/api/query/refund-list.md
# 退款列表与详情
提供退款订单的查询能力，均属管理 API（`/mch/*`），Sa-Token 认证。
> 按退款单号精确查询单笔退款（开放支付 API，RSA 签名，`POST /unipay/query/refund-order`）见 [查询退款单](https://doc.plus.daxpay.cn/api/query/refund-order.md)，两者字段结构不同。
## 接口列表
| 接口名称 | 接口地址 | 方法 | 描述 |
| --- | --- | --- | --- |
| 退款分页 | `/mch/order/refund/page` | GET | 分页查询退款单 |
| 退款详情 | `/mch/order/refund/get-by-id` | GET | 根据 ID 查询退款单详情 |
## 退款分页
### 请求地址
`GET /mch/order/refund/page`
- 认证：Sa-Token（请求头 `Accesstoken`）
- 响应：`Result>`
### 请求参数
通过查询字符串传递，分页参数 + 查询条件：
**分页参数（`PageParam`）：**
| 参数 | 类型 | 默认 | 描述 |
| --- | --- | --- | --- |
| current | int | 1 | 当前页码 |
| size | int | 10 | 每页条数 |
**查询条件（`RefundOrderQuery`，均可选）：**
| 参数 | 类型 | 匹配方式 | 描述 |
| --- | --- | --- | --- |
| mchNo | string | EQ | 商户号 |
| appId | string | EQ | 应用号 |
| refundNo | string | LIKE | 系统退款号（模糊匹配） |
| bizRefundNo | string | LIKE | 商户退款号（模糊匹配） |
| tradeNo | string | LIKE | 原支付资金交易号（模糊匹配） |
| tradeType | string | EQ | 交易类型（原支付形态） |
| bizOrderNo | string | LIKE | 商户业务订单号（模糊匹配） |
| status | string | EQ | 退款状态（`RefundOrderStatusEnum`） |
| product | string | EQ | 支付产品 |
| storeNo | string | EQ | 门店号 |
| createTimeStart | string | GE | 创建时间起始（`yyyy-MM-dd HH:mm:ss`，GMT+8） |
| createTimeEnd | string | LE | 创建时间结束（`yyyy-MM-dd HH:mm:ss`，GMT+8） |
### 请求示例
```http
GET /mch/order/refund/page?current=1&size=20&status=progress&createTimeStart=2024-12-01%2000:00:00 HTTP/1.1
Host: your-domain.com
Accesstoken: xxxx-xxxx-xxxx
```
### 响应参数
`Result>`：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| records | object[] | 退款单列表（每项结构同 [申请退款 - 响应参数](https://doc.plus.daxpay.cn/api/payment/refund.md#响应参数)） |
| total | long | 总记录数 |
| size | long | 每页条数 |
| current | long | 当前页码 |
### 响应示例
```json
{
"code": 0,
"message": "success",
"data": {
"records": [
{
"id": "1853123456789012345",
"refundNo": "R2024120112345700001",
"bizRefundNo": "REFUND20241201001",
"bizOrderNo": "ORDER20241201001",
"amount": 100,
"status": "progress",
"createTime": "2024-12-01T04:00:00Z"
}
],
"total": 1,
"size": 20,
"current": 1
}
}
```
## 退款详情
### 请求地址
`GET /mch/order/refund/get-by-id`
- 认证：Sa-Token（请求头 `Accesstoken`）
- 响应：`Result`
### 请求参数
| 参数 | 位置 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| id | query | long | 是 | 退款单 ID |
### 请求示例
```http
GET /mch/order/refund/get-by-id?id=1853123456789012345 HTTP/1.1
Host: your-domain.com
Accesstoken: xxxx-xxxx-xxxx
```
### 响应示例
返回完整的 `RefundOrderResult`（27 字段，结构同 [申请退款 - 响应参数](https://doc.plus.daxpay.cn/api/payment/refund.md#响应参数)）：
```json
{
"code": 0,
"message": "success",
"data": {
"id": "1853123456789012345",
"refundNo": "R2024120112345700001",
"bizRefundNo": "REFUND20241201001",
"bizOrderNo": "ORDER20241201001",
"tradeNo": "T2024120112345700001",
"amount": 100,
"orderAmount": 100,
"status": "success",
"finishTime": "2024-12-01T06:00:00Z",
"channel": "wechat",
"product": "WECHAT_PAY",
"reason": "用户申请退款",
"createTime": "2024-12-01T04:00:00Z"
}
}
```
---
# 查询退款单
**源**: https://doc.plus.daxpay.cn/api/query/refund-order.md
# 查询退款单
## 接口说明
通过退款单号查询退款单详情，包含退款金额、状态、完成时间等信息。属于开放支付 API（RSA 签名）；仅查询本地退款单，不调用通道，需要实时通道状态请走 [退款同步](https://doc.plus.daxpay.cn/api/payment/refund-sync.md)。
管理端的分页列表与详情查询（`/mch/order/refund/page`、`/mch/order/refund/get-by-id`，Sa-Token 认证）见 [退款列表与详情](https://doc.plus.daxpay.cn/api/query/refund-list.md)，两者字段结构不同，勿混淆。
## 请求地址
`POST /unipay/query/refund-order`
- 认证：RSA 签名（`@PaymentVerify`）
- 响应：`DaxResult`
## 请求参数
基础参数同 [统一支付 - 基础参数](https://doc.plus.daxpay.cn/api/payment/create.md#基础参数所有-unipay-接口通用)，业务参数：
| 参数 | 类型 | 必填 | 最大长度 | 描述 |
| --- | --- | --- | --- | --- |
| refundNo | string | 否* | 100 | 平台退款号 |
| bizRefundNo | string | 否* | 100 | 商户退款号 |
> *两个单号至少传一个，优先级：refundNo > bizRefundNo
### 请求示例
```json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201033",
"reqTime": "2024-12-01 12:33:00",
"sign": "Base64签名值",
"refundNo": "R2024120112345700001"
}
```
## 响应参数
`DaxResult`，`data` 字段结构（对外精简版）：
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| refundNo | string | 平台退款号 |
| bizRefundNo | string | 商户退款号 |
| tradeNo | string | 原支付资金交易号 |
| bizOrderNo | string | 原支付商户业务订单号 |
| outRefundNo | string | 通道退款流水号 |
| amount | long | 退款金额（分） |
| orderAmount | long | 原订单总金额（分） |
| status | string | 退款状态（`RefundOrderStatusEnum`：`progress` / `success` / `fail` / `close`） |
| reason | string | 退款原因 |
| finishTime | string | 退款完成时间（北京时间，`yyyy-MM-dd HH:mm:ss`） |
| errorMsg | string | 错误信息 |
### 响应示例
```json
{
"code": 0,
"msg": "success",
"data": {
"refundNo": "R2024120112345700001",
"bizRefundNo": "REFUND20241201001",
"tradeNo": "T2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"outRefundNo": "5000050xxxxxxxxxxxx",
"amount": 100,
"orderAmount": 100,
"status": "success",
"reason": "用户申请退款",
"finishTime": "2024-12-01 14:00:00"
},
"sign": "Base64签名值",
"resTime": "2024-12-01 12:33:00",
"reqId": "REQ20241201033"
}
```
## 使用建议
- 查询为**幂等**操作，仅返回本地已落库的数据；实时通道状态请优先使用 [退款同步](https://doc.plus.daxpay.cn/api/payment/refund-sync.md)。
- 本接口返回对外精简字段（不含 `id`、`channel`、`product`、`createTime` 等管理端字段），管理端查询请使用 [退款列表与详情](https://doc.plus.daxpay.cn/api/query/refund-list.md)。
---
# 签名机制
**源**: https://doc.plus.daxpay.cn/api/signature.md
# 签名机制
为保证数据传输安全，DaxPay 支付 API 采用 **RSA 非对称加密**签名机制。请求、响应和异步回调均需签名验证，防止篡改。
## 密钥体系
DaxPay 使用 RSA 密钥对进行签名验签：
| 密钥 | 保管方 | 用途 |
| --- | --- | --- |
| 商户私钥 | 商户服务器 | 对**请求**签名 |
| 商户公钥 | DaxPay 平台 | 平台**验证请求**签名 |
| 平台私钥 | DaxPay 平台 | 对**响应/回调**签名 |
| 平台公钥 | 商户服务器 | 商户**验证响应/回调**签名 |
推荐使用 2048 位 RSA 密钥对。可使用 OpenSSL 或 Java KeyPairGenerator 生成。
## 签名字段位置
签名相关字段在**请求/响应 JSON 体内**，不在 HTTP 请求头：
| 字段 | 位置 | 说明 |
| --- | --- | --- |
| sign | JSON 体 | 签名值（Base64 编码） |
| reqId | JSON 体 | 请求唯一标识，防重放 |
| nonceStr | JSON 体 | 随机字符串，防重放 |
| reqTime | JSON 体 | 请求时间（`yyyy-MM-dd HH:mm:ss`，北京时间） |
平台**按报文字面量生成/校验签名串**，时间字段必须与平台规范字面量完全一致，即**北京时间** `yyyy-MM-dd HH:mm:ss`（不带时区后缀、不带亚秒）：
| 字面量 | 是否可用 | 说明 |
| --- | --- | --- |
| `2024-12-01 12:00:00` | ✅ | 平台规范字面量（本文档所有示例均为此格式） |
| `2024-12-01T04:00:00Z` | ❌ | ISO 8601 写法，与规范字面量不同 → `20052` |
| `2024-12-01 12:00:00.123` | ❌ | 带亚秒，平台规范字面量无小数 → `20052` |
响应与异步通知中的时间字段（`resTime`、`payTime`、`finishTime` 等）同样是北京时间格式，直接取 JSON 中的字面量参与验签即可。
## 签名生成步骤
### 1. 构造待签名字符串
1. 获取请求 JSON 中的所有字段（含嵌套对象的扁平化展开）。
2. **排除 `sign` 字段本身**。
3. 排除值为空的字段（null 或空字符串）。
4. 将剩余字段按 key 的 **ASCII 字典序** 升序排列。
5. 拼接为 `key1=value1&key2=value2` 格式。
- 嵌套对象使用点号连接：`terminal.terminalNo=value`
- 列表元素使用中括号索引：`limitPay[0]=value`
- 展开后整体参与排序和拼接
### 2. RSA 签名
使用**商户私钥**对待签名字符串进行签名：
- 算法：`SHA256withRSA`
- 编码：UTF-8
- 输出：Base64 编码字符串
### 3. 填入 sign 字段
将 Base64 签名结果填入请求 JSON 的 `sign` 字段。
## 响应验签
商户收到响应后，使用**平台公钥**验证 `sign` 字段：
1. 获取响应 JSON 中的所有字段。
2. 移除 `sign` 字段。
3. 按与请求签名相同的方式：参数升序 → 拼接。
4. 使用平台公钥以 `SHA256withRSA` 验签。
## 代码示例
### Java — 生成签名
```java
import java.security.*;
import java.util.*;
import java.util.Base64;
// 1. 构造请求参数（TreeMap 自动按 key 排序）
Map params = new TreeMap<>();
params.put("appId", "APP001");
params.put("bizOrderNo", "ORDER20241201001");
params.put("method", "wechat_qr");
params.put("mchNo", "M200000001");
params.put("nonceStr", "5K8264ILTKCH16CQ2502SI8ZNMTM67VS");
params.put("notifyUrl", "https://your-domain.com/notify");
params.put("amount", "100");
params.put("reqId", "REQ20241201001");
params.put("reqTime", "2024-12-01 12:00:00");
params.put("title", "测试商品");
// 2. 拼接待签名字符串（排除 sign，按 ASCII 排序）
String signStr = params.entrySet().stream()
.map(e -> e.getKey() + "=" + e.getValue())
.collect(Collectors.joining("&"));
// 3. RSA 签名
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey); // 商户私钥
signature.update(signStr.getBytes(StandardCharsets.UTF_8));
String sign = Base64.getEncoder().encodeToString(signature.sign());
```
### Java — 验签响应/回调
```java
// 1. 移除 sign 字段，按 key 排序拼接
String verifyStr = sortedParams.entrySet().stream()
.filter(e -> !"sign".equalsIgnoreCase(e.getKey()))
.filter(e -> e.getValue() != null && !e.getValue().isEmpty())
.map(e -> e.getKey() + "=" + e.getValue())
.collect(Collectors.joining("&"));
// 2. 使用平台公钥验签
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initVerify(publicKey); // 平台公钥
signature.update(verifyStr.getBytes(StandardCharsets.UTF_8));
byte[] signBytes = Base64.getDecoder().decode(receivedSign);
boolean valid = signature.verify(signBytes);
if (!valid) {
throw new RuntimeException("签名验证失败");
}
```
## 签名规则要点
| 规则 | 说明 |
| --- | --- |
| 排序方式 | 按参数 key 的 ASCII 码升序 |
| 拼接格式 | `key1=value1&key2=value2`（无空格、无转义） |
| 空值处理 | 值为 null 或空字符串的参数不参与签名 |
| sign 排除 | `sign` 字段本身不参与签名计算（大小写不敏感） |
| 编码 | 签名字符串统一使用 UTF-8 |
| 签名算法 | `SHA256withRSA` |
| 输出格式 | Base64 编码字符串 |
| 签名位置 | JSON 请求体 `sign` 字段（非 HTTP Header） |
---
# 代理商管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md
# 代理商管理
> 代理商是 plus 商业版独有的渠道拓展角色：平台通过代理商发展与服务名下商户。**菜单路径**：代理商管理 → 代理商信息。
>
> 代理商的定位模型（三档定位、授权代管、与服务商 ISV 的关系）是概念话题，见[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)；本页只写运营端的页面与操作。
## 代理商列表
- **查询条件**：代理商名称、代理商层级（一级 / 二级）、主体类型、状态（未激活 / 启用 / 禁用）；
- **列表列**：代理商号、代理商名称、简称、**代理商类型**（一级 / 二级）、上级代理商、主体类型、状态、创建时间；
- **操作列**：只有一个「**管理**」按钮，进入该代理商的代理商管理总览（工作台），启停、调层级、删除等操作全部在工作台内完成。
## 创建代理商
列表页「新增」打开抽屉，表单分两组：
**代理商信息**
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 上级代理商 | 否 | 不选即为一级代理商；选择一级代理商则创建为**二级代理商** |
| 名称 | 是 | 代理商全称 |
| 简称 | 是 | 展示用简称 |
| 主体类型 | 是 | 小微 / 个体工商户 / 企业 |
**管理员信息**：账号 + 密码（留空自动生成随机初始密码）。保存成功后系统自动创建代理商号、管理员账号（绑定代理商端角色）、结果页一次性展示账号与初始密码，请立即复制转告。
系统预置角色不含代理商端角色，首次使用需运营端先创建代理商端角色（角色管理中 client_code 选代理商）并完成统一授权，再把角色分配给代理商用户，否则代理商登录后无可用菜单。
## 代理商管理总览（工作台）
从列表「管理」进入，按磁贴卡片分组：
| 分组 | 子页 | 功能 |
| --- | --- | --- |
| 基础管理 | 代理商信息 | 代理商号、名称、状态等基本信息查看与编辑 |
| | 主体信息 | 法人、联系方式、地址、营业执照等主体资料 |
| | 操作日志 | 该代理商的操作审计日志（跳转业务操作日志页） |
| | 用户管理 | 代理商端账号管理（新增、角色分配、重置密码） |
| 业务配置 | 对接配置 | 代理商公钥、通信密钥等对接密钥（仅运营端可读写） |
| | 支付产品 | 该代理商名下商户可开通的产品范围 |
| | 功能开关 | 平台授权该代理商门户可用的能力（默认全开，只能收紧） |
| | 推广邀请码 | 代为生成 / 编辑该代理商的商户拓展邀请码 |
| 管理操作 | 激活 / 启停 / 调层级 / 删除 | 见下文 |
### 功能开关（层级权限）
工作台 → 业务配置 → 功能开关，是层级权限的**能力开关层**：运营端配置代理商可用的能力面（默认全开），再由角色授权落到具体用户。代理商只能在此基础上收紧，不能放开。商户级功能开关（二期）以「平台意图 ∧ 非代理商收紧行」为生效值，见[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)。
### 归属与调拨
代理商与商户的归属关系（挂靠、调拨、历史订单边界）的操作都在**商户侧**进行：商户工作台 → 管理操作 → 调拨归属。模型说明见[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)。
## 管理操作（工作台红色组）
| 操作 | 语义 |
| --- | --- |
| 激活代理商 | 未激活 → 启用，激活后即可正常使用（新创建代理商为未激活态） |
| 禁用 / 启用 | **只禁代理商自身**，不连坐：名下商户正常交易、下级代理商不受影响；禁用后该代理商账号无法登录代理商端 |
| 调整层级 | 升为一级代理商，或更换其上级一级代理商 |
| 删除代理商 | 注销并脱敏，不可恢复；**硬阻塞条件**：名下仍有商户、二级代理商或库存设备时拒绝删除；级联逻辑删除相关配置子表，用户自动封禁并踢出在线会话 |
禁用是可逆的运营动作（代理商暂不展业时使用）；删除是不可逆注销，须先处理完名下商户（调拨或删除）、下级代理商与设备。
## 常见问题
**一级和二级代理商有什么区别？**
层级决定归属链与费率档位：二级代理商挂靠一级代理商；费率体系中一级代理商对应 L1 档（见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)）。层级可用「调整层级」变更。
**删除代理商前要准备什么？**
确认名下无商户、无二级代理商、无库存设备；有则先逐个处理（商户可调拨回平台直营或划给其他代理商）。
## 相关链接
- [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)：三档定位与授权代管模型
- [代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)：直营 / 挂靠、归属调拨、层级权限
- [邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)：代理商推广邀请码与平台直营邀请码两线
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)：归属调拨的操作入口在商户工作台
- [推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)：邀请注册链路的概念说明
---
# 数据分析
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/analytics.md
# 数据分析
> 分析页面向运营决策，按时间范围汇总交易数据，从金额、渠道、时段、商户等维度展示图表。**菜单路径**：仪表板 → 分析页。
>
> 页面只做聚合展示，不提供导出与下钻；需要单笔明细时到[支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)查询。
## 时间范围
页面顶部统一切换：今天 / 昨天 / 近 7 天（默认）/ 近 30 天 / 本月 / 自定义日期区间。
预设口径说明：「近 7 天」包含今天在内往前数 7 天；「本月」为本月 1 日至今天。选择「自定义」后使用日期区间选择器，与其他预设互斥。
## 指标卡
页面顶部六张指标卡，每张附**环比**（与等长的上一个周期比较；上期为 0 且本期有数据时显示「新增」）：
| 指标 | 口径 |
| --- | --- |
| 交易总额 | 区间内成交金额合计（元） |
| 交易笔数 | 区间内成交笔数 |
| 客单价 | 成交金额 ÷ 成交笔数 |
| 支付成功率 | 成功笔数 ÷ 总笔数 |
| 退款金额 | 区间内退款金额合计（元） |
| 退款率 | 退款金额 ÷ 成交金额 |
## 图表解读
| 图表 | 看什么 |
| --- | --- |
| 交易趋势 | 按天的折线图，可在**交易额 / 交易笔数 / 客单价**三个度量间切换，判断业务走势 |
| 支付渠道占比 | 各支付渠道（微信 / 支付宝 / 云闪付 …）成交金额的占比，识别渠道结构变化 |
| 渠道交易量 | 各渠道的成交笔数柱状图，与占比图配合看「量与额」是否匹配 |
| 渠道成功率 | 各渠道支付成功率横向条形图，横轴固定 0~100%，**成功率明显偏低的渠道需要排查**（密钥过期、通道故障、路由配置错误都会体现在这里） |
| 时段分布 | 24 小时交易笔数（按区间天数取日均），用于安排营销活动时间与值守人力 |
| 单笔金额区间 | 各金额区间的笔数分布，识别小额高频还是大额低频客群 |
| 退款趋势 | 按天的退款金额走势，配合退款率观察售后压力 |
| 商户交易额排名 | Top 10 商户的交易额、笔数与占比，头部依赖一目了然 |
「支付成功率」发现某渠道掉到明显低于其他渠道时，依次检查：该渠道的通道商户是否被停用、[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)是否命中了错误的通道商户、[支付接口日志](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)里该渠道报错是否集中出现。
## 相关链接
- [运营工作台](https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md)：每日速览区块
- [支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)：单笔订单查询与处置
- [日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)：接口调用异常的明细排查
---
# 应用配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md
# 应用配置
> 应用（appId）是商户下的**调用与配置隔离单元**：unipay 接口按应用区分来源，通道路由、网关支付、收银台等配置都挂在应用维度。
>
> **菜单路径**：商户管理 → 商户列表 → 管理 → 商户工作台 → 支付配置 → 应用管理（运营端）；商户端 → 应用管理（数据同源）。
## 应用管理
应用列表是**卡片网格**（非表格）：每张卡片展示应用名称、appId、启用状态与「默认」标签，点击卡片进入该应用的[应用工作台](#应用工作台)。
**新增 / 编辑应用**的表单只有三个字段：
| 字段 | 说明 |
| --- | --- |
| 应用名称 | 自定义名称 |
| 状态 | 启用 / 禁用 |
| 默认应用 | 仅编辑态可改的开关 |
appId 由系统自动生成（`A` 开头），**创建后不可修改**，表单中不出现。
### 默认应用规则
- 商户的**第一个应用**创建时自动设为默认；同商户至多一个默认应用。
- unipay 请求**不传 appId 时回落默认应用**；显式传 appId 则按传入值路由。
| 场景 | 后果 |
| --- | --- |
| 停用默认应用 | 不指定 appId 的下单会失败（页面会二次确认提醒） |
| 删除默认应用 | **被禁止**，先转移默认再删除 |
| 无默认应用 | 列表顶部黄色警告条提示设置默认 |
## 应用工作台
从应用卡片进入，分两组磁贴：
**支付配置**
| 卡片 | 功能 |
| --- | --- |
| 通道路由 | 指定本应用各支付方式走哪个通道商户（多通道分流），见[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md) |
| 网关支付配置 | 码牌 / 聚合支付在各客户端环境下的路由深度 |
| 收银台配置 | 收银台页面在各环境下的支付方式展示 |
| 易支付配置 | 兼容易支付 V1/V2 协议接入，详见[易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md) |
**应用管理**：编辑基本信息、设为 / 取消默认应用、删除应用（强确认，需输入应用名）。
### 网关支付配置
码牌、聚合支付等**网关链路**的路由配置，维度是「**客户端环境 × 支付形态**」（微信 / 支付宝 / 云闪付 / 抖音环境 × H5 / 小程序），每格三种模式：
| 模式 | 语义 |
| --- | --- |
| 跟随通道路由 | 使用通道路由的解析结果（推荐起点） |
| 指定支付方式 | 该格固定走某个支付方式 |
| 直接指定 | 直接选「通道商户 + 支付能力」，跳过路由（排错 / 特殊场景） |
页面下方内置**路由预览**：展示当前路由命中情况（命中数 / 总数）与待补全缺口，可一键跳转通道路由补配。
### 收银台配置
配置**统一收银台**页面在各环境下展示的支付项：一级分 H5 / WEB / 小程序，H5 与小程序再按客户端环境（浏览器 / 微信 / 支付宝 / 云闪付 / 抖音）分桶，每个桶内维护支付项列表（名称、图标、推荐标记、排序、解析方式与支付方式）。
**通道路由**是底层路由策略；**网关支付配置**决定网关链路（码牌 / 聚合）用多深的路由；**收银台配置**只决定收银台页面的展示项。初次配置建议：先配通道路由，网关支付保持「跟随」，收银台按需调整展示。
## 常见问题
**一个商户可以建多个应用吗？**
可以。应用用于隔离不同业务线的调用与配置（各自独立的路由、网关、收银台配置），unipay 请求带 appId 即路由到对应应用；不传则回落默认应用。
**删除应用有什么限制？**
默认应用不可直接删除（先转移默认）；应用下仍有存量配置（路由策略等）时建议先确认无业务依赖再删除。
## 相关链接
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)：应用管理的入口与商户域全景
- [通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)：两种路由维度的详细操作
- [易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)：应用维度的易支付协议配置
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)：统一收银台 / 聚合扫码的业务说明
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：应用在工作流中的位置
---
# 回调通知管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/callback.md
# 回调通知管理
> 回调有两条链路：**平台 → 商户**的回调推送（通知商户支付/退款结果），与**通道 → 平台**的回调接收（驱动订单状态推进）。两条链路的记录都在交易管理 → 回调通知下，重试策略与报文格式见[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)。
| 菜单项 | 链路方向 | 典型用途 |
| --- | --- | --- |
| 商户回调推送 | 平台 → 商户 | 商户说「没收到通知」时补投与排查 |
| 通道回调记录 | 通道 → 平台 | 订单状态不推进时的根因定位 |
## 商户回调推送
平台向商户 notifyUrl 推送通知的任务台账（notifyUrl 在商户应用支付配置中设定）：
- **查询**：按业务单号、事件（支付/退款等）、报文格式、商户过滤；
- **列表**：业务单号、事件、报文格式、来源、**发送成功**标记、**发送次数**、商户、最后发送时间；
- **任务详情**：查看该任务的完整报文与目标地址；
- **发送记录**：每条发送的明细——发送类型（首次/重试）、发送成功、HTTP 状态、错误信息、时间，失败原因在这里看；
- **重发**：手动补发一次通知，适合商户侧临时故障恢复后补投。
「事件」标识本条通知的业务语义（支付成功、退款状态变化等），「来源」标识触发方（支付回调、退款回调等），两者组合即可定位是哪条业务链路在通知。发送次数持续增长说明商户接口长期异常，应联系商户修复后再重发，避免无效轰炸。
## 通道回调记录
通道侧回调到达平台后的处理台账，用于排查「通道已扣款、订单未推进」类问题：
| 关注列 | 说明 |
| --- | --- |
| 回调类型 | 支付、退款、分账等 |
| 处理状态 | 成功 / 失败 / 关闭 / 忽略 / 异常 / 未找到 |
| 交易号 / 通道交易号 | 平台与通道两侧的单号对照 |
| 错误信息 | 处理失败时的原因 |
- **查询**：按通道商户、交易号、通道交易号、支付产品、回调类型、处理状态、商户过滤；
- **回调详情**：查看回调原文与解析结果。
商户反馈「扣款了但订单没成功」：先在本页按交易号或通道交易号找回调 → 无记录说明通道回调未到达（去通道侧或支付交易页做同步状态）→ 有记录但处理失败看错误信息 → 处理成功但业务单未推进则属内部转发问题，配合[异常订单](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md)处置。
## 常见问题
**商户没收到回调，先查什么？**
先查商户回调推送页该业务单的发送记录：HTTP 状态非 2xx 多为商户接口报错（看错误信息）；显示成功但商户说没收到，让商户按报文格式自行核对解析逻辑。
**通道回调显示「未找到」是什么意思？**
回调里的交易号在平台没有对应订单，常见于测试环境的单据回调到了另一环境，或重复/过期回调，属可忽略类。
**「忽略」状态的通道回调要处理吗？**
「忽略」是系统判定无需推进的回调（如已终态订单的重复通知），不需要人工处理；需要盯的是「失败」「异常」两类，按错误信息处置。
**重发会重复通知商户吗？**
会再发一次，商户侧应按通知幂等设计（同一业务单号只生效一次）；这也是通道回调与商户通知的通用约定，见[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)。
## 相关链接
- [回调与通知](https://doc.plus.daxpay.cn/common/notify.md) — 重试策略、报文格式与验签正典
- [支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md) — 订单侧的核查处置
- [对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md) — 长期不一致的兜底核对
---
# 通道配置通用操作
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md
# 通道配置通用操作
> 系统接入的每家支付通道（支付宝、微信、拉卡拉、盛付通……）配置结构高度一致：**服务商参数 → 商户进件 / 通道商户创建 → 通道商户管理**三段式。本文讲通用模型与各家差异，**逐通道的介绍见「支付通道」板块的对应通道页**（如[支付宝](https://doc.plus.daxpay.cn/extension/channels/alipay.md)、[微信支付](https://doc.plus.daxpay.cn/extension/channels/wechat.md)、[拉卡拉](https://doc.plus.daxpay.cn/extension/channels/lakala.md)）。
>
> 新系统首次对接支付宝 / 微信的完整实例见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 从哪进入
通道配置的入口统一在：**支付管理 → 通道与产品配置 → 支付和进件产品**。服务商型产品进入对应服务商管理页（平台侧参数维护在[服务商工作台](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)）；直连产品进入通道工作台。单个商户的通道侧信息在其**通道商户详情**页维护（商户管理 → 通道商户）。
## 两种接入模式
| 模式 | 含义 | 需要配置 |
| --- | --- | --- |
| **服务商（ISV）** | 平台以服务商身份代商户进件，商户是通道侧「特约 / 子商户」 | 服务商密钥（工作台「支付密钥」）+ 进件申请获得的通道侧子商户号 |
| **直连** | 商户自己在通道侧开通，平台只管发起交易 | 通道商户的**商户号与交易密钥** |
部分通道双模式都支持（支付宝、微信、汇付等），按商户实际情况选产品开通。plus 支持同一通道配置多个服务商，进件申请创建时锁定归属服务商。
## 三段式配置模型
### 第一段：服务商参数（服务商模式）
服务商模式的通道先配**平台级服务商参数**（证书、私钥、API 密钥等，按通道而异），统一在**服务商工作台**维护：
- 工作台按磁贴分组：基础信息 / **支付密钥** / 进件参数 / 服务商费率 / 应用管理，表单以抽屉分段编辑；
- 微信（服务商）特殊：**平台即服务商**，无需服务商号，直接配 API 证书、证书私钥与支付公钥；
- 聚合通道（拉卡拉等）通常还有机构代码、终端号等专属字段；
- 密钥类字段保存时只提交变化部分；证书文件（`.pem`）直接选择文件上传；
- 工作台管理操作提供**启停进件**（控制新进件候选）与**启停支付**（控制新支付）两个独立开关。
服务商工作台的完整结构见[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)。
### 第二段：商户进件（创建通道商户）
为具体商户获得通道侧收款身份，plus 有两条路：
| 路径 | 适用 | 说明 |
| --- | --- | --- |
| **进件申请**（商户管理 → 进件申请） | 服务商模式的特约 / 子商户 | 走[进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)全流程，审核通过后生成通道商户 |
| 手动创建通道商户（商户管理 → 通道商户） | 直连模式或已有通道侧商户号 | 选支付产品 → 填通道商户名称 + **通道侧商户号**直接创建 |
手动路径只录「号」，不录密钥——密钥在下一段按商户维度配置；服务商线的进件还支持选择归属服务商（多服务商通道）。
### 第三段：通道商户管理
从通道商户列表「管理」进入，维护单商户的通道侧配置：
| 分组 | 通用内容 |
| --- | --- |
| 基础管理 | 基本信息、修改名称；**直连模式在此配交易密钥**（APIv3 密钥 / 证书等）；支付宝（服务商）有**应用授权令牌**维护 |
| 交易配置 | 分账接收方绑定（见[支付分账](https://doc.plus.daxpay.cn/common/alloc.md)） |
| 应用管理 | 通道侧应用与能力绑定：微信走[微信支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)，支付宝在此维护通道商户应用（应用号 + 密钥 / 证书 + 授权类型），并可按能力绑定支付应用 |
| 终端台账 | 通道侧终端登记与报备（报备时选择商户终端即建立关联） |
支付宝（服务商）的「应用授权令牌」支持两种方式：手动粘贴商家授权后的令牌，或用**代运营授权链接**——生成授权链接 / 二维码发给商家扫码，授权回调后令牌自动更新（授权账号须与进件时绑定的子商户号一致）。
## 各通道差异速查
| 通道 | 模式 | 专有要点 |
| --- | --- | --- |
| 支付宝 | 服务商 + 直连 | 应用体系（服务商应用 / 通道商户应用）；应用授权令牌；进件走代授权 + 产品开通两线 |
| 微信支付 | 服务商 + 直连 | 平台即服务商；证书 + 支付公钥双套；特约商户进件需微信内签约确认 |
| 抖音 | 直连 | 商户号 + 密钥即可 |
| 银联 / 银联商务 | 直连 | 银联商务按支付形态拆分多个直连工作台（扫码 / 公众号 / APP / 小程序 / H5 等） |
| 拉卡拉 / 盛付通 / 乐刷 / 随行付 / 海科融通 / 河马付 / 富友 / 易宝 | 服务商（聚合） | 服务商密钥 + 商户进件；微信类支付需绑定[微信应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)（子应用维度） |
| 汇付（Adapay）/ 斗拱 | 服务商（聚合） | 同门不同线：Adapay 为进件直连型（进件凭据与交易凭据两维度），斗拱为独立机构二级型进件线 |
| 易支付 | 直连 | 易支付协议通道化接入，见[易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md) |
聚合类通道（拉卡拉、乐刷等）做微信 JSAPI / 小程序支付时，openId 依赖**子应用**（sub_appid）：在通道商户详情的「应用管理 / 能力绑定」里把商户的微信应用绑到对应能力上，否则下单会报应用缺失。
## 常见问题
**直连和服务商模式怎么选？**
商户已有通道侧账号、想自己管密钥 → 直连；平台代商户开通并统一服务商管理 → 服务商模式（需先配好服务商参数并走进件）。同一商户也可以在不同通道用不同模式。
**进件和手动创建通道商户能混用吗？**
能。同一商户在不同通道按可用模式各建各的通道商户；服务商线通道建议统一走进件申请，保持归属服务商与进件资料一致。
**通道商户建好后还差什么才能收款？**
直连模式补交易密钥；服务商模式确认进件产物已生成；然后在应用工作台配[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)。下单失败时先查路由报错，再回查通道商户状态与密钥。
## 相关链接
- [进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)：服务商线的进件全流程
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)：服务商工作台与产品启停
- [支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)：微信 / 抖音应用登记与能力绑定
- [支付通道总览](https://doc.plus.daxpay.cn/extension/channels/.md)：十六家通道的介绍页与对接流程
- [支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)：支付宝 / 微信直连的完整实例
---
# 投诉管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/complaint.md
# 投诉管理
> 支付宝、微信官方投诉渠道的工单会同步到平台，由运营端（或商户端）统一处置。菜单：交易管理 → 投诉管理 → 投诉工单。投诉处置有**处理时限**，超时会影响商户在通道侧的评级，应优先处理。
## 工单来源
- **接入范围**：当前接入支付宝、微信两个官方投诉渠道；
- **自动同步**：平台定时拉取新投诉与协商进展；
- **立即同步**：列表页可手动触发一次全量同步（后端异步执行，稍后刷新查看），适合商户反馈「刚收到投诉短信但列表没有」的场景。
## 工单列表与详情
列表字段：平台投诉单号、渠道投诉 ID、支付通道、商户、金额、投诉类型、状态（待处理 / 处理中 / 已完结）、处理时限（临期/已超时会突出显示）、创建时间。筛选项含平台投诉单号、渠道投诉 ID、商户号、支付通道、状态、是否超时。
详情抽屉展示：投诉内容、投诉人联系方式（脱敏展示）、投诉图片（经平台代理加载，通道侧临时资源可能过期）、以及与投诉人的**协商记录**（每轮回复的留痕）。
## 状态与处置动作
| 状态 | 含义 | 推进动作 |
| --- | --- | --- |
| 待处理 | 新落单，尚未有有效回复 | 首次回复 |
| 处理中 | 已与投诉人建立协商 | 继续回复直至协商一致 |
| 已完结 | 已向通道反馈完结 | —（终态） |
状态由平台按协商进展自动维护：提交回复即视为进入处理链路，**反馈完结**是唯一的人工终态动作（二次确认后向通道反馈）。列表的「处理时限」「是否超时」筛选项用于临期催办。
## 处置口径
- **回复**：在详情内填写回复内容，可附图片（上传后随回复一并提交通道侧），提交后自动刷新协商记录——回复是推进状态从「待处理」到「处理中」的常规动作；
- **反馈完结**：确认该投诉已处理完成后操作，平台向通道反馈完结，工单转为「已完结」；操作前应与投诉人协商到位，避免草率关单引发二次投诉；
- **协同商户**：涉及具体交易的纠纷，先把交易侧信息核对清楚（退款与否、订单状态），再回复投诉人，避免口径矛盾；
- **协商留痕**：所有回复都会写入协商记录并在通道侧留档，回复内容应客观、可追溯，不承诺无法兑现的补偿。
回复提交后状态自动流转，但「已完结」必须由处置人确认「已处理完成」后才反馈通道；仅商户单方面结案而平台未操作完结的，工单仍视为未结。
## 商户端协同
商户端交易管理下也有**投诉工单**入口，商户可自助查看名下投诉并完成回复/完结，适合把一线处置下放给商户；运营端保留全平台视角，用于监督超时与兜底处理。运营端 APP 亦可在移动端跟进。
## 常见问题
**投诉图片打不开？**
投诉图片是通道侧临时资源，经平台代理加载，可能已过期；过期时以投诉文字内容与交易记录为准处置。
**处理时限怎么算？**
以通道侧给出的时限为准（列表「处理时限」列），临近或超出会突出提示；超时前至少完成一次有效回复。
**回复错了能撤回吗？**
回复提交即达通道侧，无法撤回；如口径有误，在下一轮回复中更正并说明即可。
## 相关链接
- [支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md) — 涉诉交易的核对入口
- [回调通知管理](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md) — 交易状态争议时的链路排查
- [商户端交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md) — 商户侧投诉入口与自助处置
---
# 开发者调试
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md
# 开发者调试
> 五个调试工具面向**运营与对接方**：不写代码、在页面上发起真实调用，验证配置与签名是否正确。**菜单路径**：开发调试。
>
> 调试工具使用真实的商户与应用配置发起调用（不是沙箱模拟器），产生的订单是真实订单，验证后记得关单或退款。
## 支付调试（普通）
模拟商户调用统一支付接口发起一笔支付，验证「密钥配置 + 签名 + 路由 + 通道商户」整条链路：
1. **设置商户私钥**：填入商户的 RSA 私钥（仅保存在本浏览器，换电脑需重填）；
2. **选路由模式**：
- **跟随通道路由**：选商户 + 应用 + 支付方式，按[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)解析——验证路由配置首选；
- **直接指定**：选商户 + 通道商户 + 支付能力，跳过路由——隔离排查通道商户本身的问题；
3. **填订单**：订单号可一键生成，金额单位为**分**；JSAPI / 小程序方式需先填 openId（用[认证调试](#认证调试)获取）；付款码场景填 authCode 后支付方式可留空（按码前缀自动识别微信 / 支付宝 / 银联）；
4. **提交支付**：浏览器本地签名后直调接口，结果弹窗按返回形态渲染——跳转链接 / 二维码扫码支付、JSAPI 参数用 JSON 查看；业务失败（签名错、参数错）也会弹窗展示错误码。
高级参数（同步跳转地址、附加参数、限制支付类型如禁信用卡、扩展参数 JSON）按需展开。
## 支付调试（网关）
验证[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)（统一收银台 / 聚合扫码）的预下单：选网关类型（收银台 / 聚合扫码）→ 商户 + 应用 → 订单信息 → 提交预下单，结果页给出**落地页链接与小程序链接**（各带二维码，可直接扫码体验收银台全流程）。
## 支付调试（预授权）
plus 独有的预授权链路验证工具，覆盖支付宝预授权与微信支付分两条产品线：
- **支付宝预授权**：冻结 → 请款 / 解冻等单据操作；可选产品（直连 / 服务商）、预授权类型（**资金预授权** / **信用预授权**——芝麻信用，需商户签约）、场景（线上返回拉起参数 / 线下返回二维码码值）、经营场景（押金、预付款、订金、预估订单费用）；
- **微信支付分**：服务订单创建与后续操作（先享后付 / 免押场景）。
操作流：填商户私钥与订单信息发起**冻结**（或支付分服务单创建），成功后结果区会**回填预授权单号/支付分单号**，直接粘到同页的操作区继续请款、解冻等后续动作，串起完整生命周期。预授权的业务边界（如请款后退款暂不支持）见[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)。
## 签名调试
对接方排查签名问题的独立工具，不依赖商户配置：
| 页签 | 输入 | 输出 |
| --- | --- | --- |
| 签名生成 | 待签名参数 JSON + RSA 私钥 | 待签名字符串 + 签名值（可复制） |
| 签名验证 | 参数 JSON（不含 sign）+ 签名值 + RSA 公钥 | 通过 / 不通过 |
商户回调验签失败、接口报签名错误时，用此工具比对双方的签名串拼接是否一致（多为参数排序或编码差异）。
## 认证调试
验证 OAuth 授权链路能否取到 openId（JSAPI / 小程序支付的前置）：
- **认证类型**：支付宝 H5、微信公众号、微信支付、抖音 H5、抖音支付（小程序 openId 调试已移到收银台小程序）；
- 微信支付 / 抖音支付需选商户与对应应用（平台应用或商户应用）；其余类型直接使用[第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)的平台级凭据；
- 点「生成授权链接」出二维码，**手机扫码完成授权**，页面轮询结果，成功后展示 openId / userId / accessToken（可复制，粘到支付调试的 openId 字段用）。
二维码授权成功即失效，重复测试请重新生成。
「JSAPI 支付报 openId 与应用不匹配」→ 认证调试取一次 openId，确认所用应用与支付时传的 channelAppId 同源；「下单报签名错误」→ 签名调试比对签名串；「下单报无可用通道商户」→ 回[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)看命中预览；「预授权冻结失败」→ 先核对预授权类型是否需签约、服务商工作台的进件参数是否齐备。
## 相关链接
- [模拟联调通道](https://doc.plus.daxpay.cn/tools/mock/.md)：真实通道未就绪时，用独立模拟通道跑通支付/退款/分账/预授权与回调全链路
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：完整联调流程与错误对照
- [接口签名](https://doc.plus.daxpay.cn/api/signature.md)：签名规则正典
- [通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)：路由模式说明
- [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)：预授权业务边界
---
# 数据字典
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/dict.md
# 数据字典
> 数据字典维护「一类枚举值」的标准化清单（如支付宝鉴权类型），供业务表单的下拉选项与列表翻译使用。**菜单路径**：系统管理 → 基础数据 → 数据字典。
>
> 面向需要扩展枚举的进阶场景；日常业务不需要操作本页。
## 两级结构
**字典（一类枚举）→ 字典项（枚举值）**：
| 层级 | 关键字段 | 规则 |
| --- | --- | --- |
| 字典 | 字典编码、字典名称、启用状态、内置标记 | 编码全局唯一，保存时实时查重 |
| 字典项 | 字典项编码、名称、排序、启用状态 | 编码在同一字典内唯一（防抖查重）；名称直接填写中文 |
操作动线：字典列表行内「字典配置」打开该字典的字典项管理抽屉，在抽屉内增删改字典项。
## 名称直存中文
字典名称与字典项的名称都是**中文直存**：填什么显示什么，保存即生效，没有额外的翻译链路。新增字典项时把显示名直接填在「名称」字段即可，列表与业务表单按该名称展示。
## 内置字典
标记「内置」的字典由系统功能依赖（如支付宝应用密钥配置的鉴权类型下拉），**不要停用或删除其字典项**，否则对应表单的选项会缺失。自定义字典建议使用自己的编码前缀区分。
## 业务如何消费
- **下拉选项**：业务表单按字典编码拉取启用状态的字典项生成下拉；
- **列表翻译**：列表中的字典字段按「字典编码 + 字典项编码」翻译为显示名。
停用一个字典（或字典项）后，依赖它的下拉将不再出现该选项——存量数据仍保留原值，只是翻译可能退化为原编码。
## 常见问题
**停用字典项后，列表里该字段显示成了编码？**
字典项停用后不再参与翻译，存量数据退化为显示原编码。恢复启用该字典项即可还原显示。
**自定义字典怎么避免与系统内置冲突？**
内置字典由系统功能依赖，自定义字典建议使用自己的编码前缀（如 `my_` 开头）区分，避免升级同步时互相覆盖。
## 相关链接
- [权限与菜单管理](https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md)：同样采用中文直存标题的菜单管理
- [运营端使用入门](https://doc.plus.daxpay.cn/operation-guide/admin/overview.md)：系统管理分区总览
---
# 易支付插件
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md
# 易支付插件
> 易支付插件让系统**兼容易支付（EPay）协议**：存量易支付对接的业务系统不改代码，改个地址即可切到本平台收款。**菜单路径**：扩展插件 → 易支付（易支付订单 / 易支付退款）。
>
> 配置按**应用**维度：运营端在商户的应用工作台里开启并配置密钥（见[应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)）；本篇的订单页是易支付协议订单的查询与处置入口，商户端也有对应入口。
## 启用与密钥配置
应用工作台 → 易支付配置，分区如下：
**基础对接**
| 项 | 说明 |
| --- | --- |
| 启用 | 总开关，关闭后该应用拒绝一切易支付协议请求 |
| 易支付商户号（PID） | 系统按应用自动分配，只读 |
| V1 / V2 对接地址 | 只读，复制给对接方替换原易支付地址用 |
**V2 协议**（推荐）：默认**使用系统密钥**（复用应用已有的签名体系，无需额外配置）；关闭「使用系统密钥」后改为独立 RSA 密钥对——平台公钥只读展示，商户公钥可在线生成（自动去除 PEM 头尾、按易支付要求存纯 Base64），私钥仅生成时弹窗展示一次，注意留存。
**V1 协议**（存量兼容）：开启后配置 **MD5 密钥**（对应易支付传统 KEY 签名），仅在对接旧系统时使用。
本期易支付协议**不发送异步通知**，对接方需用查询接口轮询订单状态——迁移文档里要明确告知。
## 易支付订单
**菜单路径**：扩展插件 → 易支付 → 易支付订单。面向协议侧的订单视图：
- **查询**：商户订单号、平台业务单号、商品名称、协议状态（待支付 / 已支付）、支付方式、创建时间；
- **详情**：订单信息、时间信息、应用与协议（PID、应用 ID、协议版本、PC 调用方式）、支付与回调（支付用户标识、支付链接、通知与跳转地址、扩展参数）；
- **操作**：
- **同步状态**：主动向支付通道查询该订单最新状态（长时间停在「待支付」时用）；
- **关闭订单**：仅待支付状态可关，关闭后不可继续支付。
## 易支付退款
同路径下的退款单视图：
- **查询**：平台退款单号、商户退款单号、商户订单号、平台业务单号、退款状态（处理中 / 退款成功）、创建时间；
- **详情**：退款信息、应用与协议、时间信息；
- **操作**：**同步状态**（对处理中的退款主动查询通道结果）。
## 与普通订单的区别
| 维度 | 易支付订单 | 普通支付订单 |
| --- | --- | --- |
| 视角 | 易支付协议字段（PID、协议版本、商户订单号） | 平台统一订单模型（三层订单） |
| 状态 | 协议二态：待支付 / 已支付 | 完整支付状态机与资金状态 |
| 金额单位 | 元 | 元（数据库内部为分） |
| 用途 | 迁移期排查对接方请求 | 日常交易查询与处置主入口 |
易支付订单最终也映射为平台支付单；资金层面的对账与退款处理以[支付订单](https://doc.plus.daxpay.cn/common/payment-order.md)为准。
## 相关链接
- [应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)：易支付配置所在的应用维度
- [易支付接口](https://doc.plus.daxpay.cn/api/epay.md)：协议接口文档
- [支付订单](https://doc.plus.daxpay.cn/common/payment-order.md)：平台订单模型
---
# 邀请注册管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md
# 邀请注册管理
> 邀请注册是商户自助开户的入口：通过分享带邀请码的注册链接，商户自行完成注册并落到预定归属。**菜单路径**：商户管理 → 邀请注册（邀请码管理 + 注册记录）。
>
> plus 版两条线并存：**平台直营邀请码**（注册后归属平台）与**代理商推广邀请码**（注册后挂靠对应代理商）。
## 两条邀请线
| 线 | 归属 | 管理入口 |
| --- | --- | --- |
| 平台直营邀请码 | 不挂任何代理商，注册后归属**平台直营**，且新商户**默认停用**，需运营启用后才能使用 | 商户管理 → 邀请注册 → 邀请码管理 |
| 代理商推广邀请码 | 注册后**挂靠邀请码所属代理商**，系统自动创建管理员账号、默认应用、默认门店 | 运营端：代理商工作台 → 推广邀请码（代管）；代理商端：推广邀请码（自服务） |
两条线的邀请码在「邀请码管理」页**统一列表**：按「所属代理商」筛选即可区分平台码与各代理商码；代理商自己的推广码在代理商端维护（见[代理商端·推广邀请码](https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md)）。
## 邀请码管理
**菜单**：商户管理 → 邀请注册 → 邀请码管理。
- **查询条件**：所属代理商（平台直营 + 各代理商）、状态（启用 / 停用）；
- **列表列**：名称、邀请码、状态、**已注册 / 上限**、有效期（空 = 永久）、所属代理商、创建时间；
- **操作**：
- **推广**：弹窗展示注册链接二维码 + 可复制链接（平台码与代理商码通用），发给商户扫码即进入注册页；
- **启停**：停用后链接立即失效，无法再通过该码注册。
**生成平台邀请码**（工具栏新增）弹窗字段：
| 字段 | 说明 |
| --- | --- |
| 名称 | 备注用途，如「官网渠道」 |
| 过期时间 | 留空 = 永久有效 |
| 次数上限 | 留空 = 不限次数；达到上限后邀请码失效 |
平台直营线没有代理商做首道审核，为控制开户质量，通过平台邀请码注册的商户创建后为停用状态，需运营在[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)中逐个启用。代理商码注册的商户直接可用。
## 注册记录
**菜单**：商户管理 → 邀请注册 → 注册记录。
每一笔通过邀请码完成的注册都会留痕，用于审计与排查：
- **查询条件**：所属代理商、邀请码；
- **列表列**：所属代理商（挂靠目标）、邀请码、商户号、商户名称、**来源 IP**、注册时间；
- **IP 快照**：注册时的来源 IP 随记录固化，配合风控排查批量注册、同源刷号等异常。
## 注册安全配置
邀请注册整链受**注册安全配置**门禁控制（默认**关闭**）：未开启时注册入口不可用，所有邀请链接均无法完成注册。需要开放自助注册时，在系统安全配置中开启，并按需配置密码策略、短信验证等防线，见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)。
## 常见问题
**代理商如何拿到自己的推广码？**
两种方式：代理商登录代理商端「推广邀请码」页自助生成与管理；或运营在代理商工作台 → 推广邀请码代为生成，二维码 / 链接转发给代理商使用。
**邀请码过期或达上限后，已注册的商户受影响吗？**
不受影响。邀请码只控制注册入口，注册完成的商户归属与状态不受邀请码后续失效影响。
**想临时暂停某个代理商的推广？**
停用该代理商名下的邀请码即可精准暂停；停用代理商自身会影响其登录，按需选择。
## 相关链接
- [推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)：邀请注册链路与两线模型的概念说明
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)：注册完成后启用商户、归属调拨
- [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)：代理商档案与功能开关
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：注册开关等安全门禁
---
# 云音箱云打印与终端
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/iot-device.md
# 云音箱云打印与终端
> 设备管理下除[码牌管理](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md)外，还有云音箱、云打印与辅助支付终端三组。**当前版本云音箱/云打印为「基础台账管理」口径**：先把设备资产与归属链路管起来，语音播报与打印小票的实际推送依赖厂商 SDK 对接，属后续波次，本页如实按现状描述。菜单：设备管理。
## 云音箱
### 云音箱厂商
厂商接入参数的配置台账：配置名称、设备厂商、状态、配置 JSON（存放该厂商侧的接入参数）。操作为新增、编辑、删除。可选厂商与云打印共用一套枚举（见下）。
### 云音箱台账
设备资产台账，字段：设备号、设备名称、批次号、设备厂商、**绑定类型**（应用 / 商户 / 码牌）、挂靠码牌、商户、代理商、状态。操作覆盖完整归属链路：
- **批量新建**：按批次录入设备号段；
- **分拨代理商 / 收回代理商**、**绑定商户 / 解绑商户**（解绑为危险操作）；
- **绑定应用 / 解绑应用**：把设备绑定到具体支付应用；
- 编辑、启用/停用、删除。
绑定类型为「码牌」的音箱挂靠在具体码牌上，收款播报的对象即该牌；当前版本台账先行，播报链路随厂商 SDK 对接波次落地。
本页的云音箱/云打印指厂商硬件，实际推送待厂商 SDK 对接；用安卓手机替代音箱与打印机的**收款播报 APP** 已可用，部署与使用见[配套工具总览](https://doc.plus.daxpay.cn/tools/.md)。
## 云打印
### 云打印厂商
与云音箱厂商页同构：配置名称、设备厂商、状态、配置 JSON，增删改操作。
内置厂商枚举（音箱/打印共用）：**飞鹅云、易联云、365 互联、芯烨云、商米**。配置 JSON 的具体字段以各厂商接入要求为准。
### 云打印台账
字段与操作和云音箱台账一致（少了绑定类型中的「码牌」维度，以商户/应用绑定为主）。同样为台账管理口径，小票打印推送待厂商 SDK 对接波次。
## 辅助支付终端
扫码盒、收款盒等辅助支付终端的**接入功能规划中**，当前为占位页（菜单已就位，页面提示「功能规划中」）。设备域菜单结构先行，功能落地后本节将补齐操作说明。
## 归属链路总结
云音箱/云打印的资产流转与码牌同构：
```
平台库存 → 分拨代理商 → 绑定商户 →（可选）绑定应用/挂靠码牌
```
收回与解绑沿反方向执行。代理商名下的设备数量是代理商删除条件的硬阻塞项之一，处置设备归属前可参考[代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)。
## 常见问题
**音箱/打印机买好了，为什么没有播报/出小票？**
当前版本设备域为台账管理，厂商 SDK 对接（实际播报与打印）属后续波次；台账先把设备与商户/应用的归属关系配好，链路上线后无需重新录入。
**厂商列表里没有我采购的品牌？**
厂商枚举当前为飞鹅云、易联云、365 互联、芯烨云、商米五家；不在列表的设备可先按台账登记（厂商字段选最接近项并备注），品牌支持随对接波次扩展。
**码牌挂靠的音箱换牌了怎么办？**
在云音箱台账解绑原码牌后重新绑定新牌即可，设备本身无需重新入库。
## 相关链接
- [码牌管理](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md) — 同属设备管理的物料主线
- [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md) — 设备库存影响代理商删除
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md) — 系统终端与设备概念
---
# 日志与监控
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md
# 日志与监控
> 日志回答「谁在什么时候做了什么」，监控页处理「当下的会话与文件」。**菜单路径**：系统管理 → 日志管理 / 系统监控。
>
> 日志页支持按时间段清理历史数据（可选 3 / 7 / 30 / 60 / 90 / 180 / 365 天前），**清理不可恢复**，确认后执行。
## 登录日志
记录每次登录尝试（成功与失败）：
- **查询**：用户账号、登录状态；
- **列表**：账号、状态、登录 IP、操作系统、浏览器、提示消息、时间；
- **详情**额外含：登录终端（运营端 / 代理商端 / 商户端）、登录方式（账密 / 验证码 / 通行密钥等）、登录地点。
排查「账号是否被人尝试爆破」：按账号过滤看失败记录的 IP 与地点是否异常集中。
## 操作日志
记录 Web 端用户的**技术层写操作**（接口的增删改、发布、配置保存等），按接口请求留痕：
- **查询**：操作模块、操作账号、操作状态；
- **详情**含完整的请求参数与返回结果（JSON 格式化展示，便于核对「到底改了什么」）、请求方式与 URL、操作 IP 与地点。
操作日志与**业务操作日志**是两套体系：操作日志面向接口报文级排错，业务操作日志面向业务动作的语义化审计（见下节）。
## 支付接口日志
记录商户对 unipay 开放接口的每次调用，是**对接问题排查的首选入口**：
- **查询**：商户号、请求 ID、接口路径、追踪 ID、调用状态；
- **列表**：请求 ID、接口名称、调用状态、**耗时**、接入 IP、错误提示、商户、调用时间；
- **详情**：完整请求参数与响应报文、错误码、**真实接入 IP 与商户声明 IP**（两者不一致通常意味着代理或伪造，是风控排查的关键信号）。
先在支付接口日志按商户号过滤失败记录 → 看错误码与错误信息（签名错误 / 参数错误 / 权限不足各有明确码）→ 需要报文级核对时展开请求参数，与商户提供的原始请求比对。通用对接错误对照见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)。
## 业务操作日志
**业务动作的语义化审计**，与技术操作日志分两套维护，三个端都有入口（运营端在本页；商户端与代理商端在工作台「操作记录」卡进入）：
- **查询条件**：商户号、代理商号、业务类型、动作、操作人账号、状态、摘要关键字；
- **列表列**：操作时间、业务类型、动作、摘要、操作人、**归属商户、归属代理商**、状态；
- **归属的含义是操作对象的归属**——记录的是「动了哪个商户 / 哪个代理商的数据」，而不是操作人所属；运营端列表中的归属编号可点击直达对应的商户 / 代理商工作台；
- **详情**：操作记录详情抽屉，含操作终端、归属商户 / 代理商、完整摘要等追溯字段。
排查「这条业务数据是谁改的」：按业务类型 + 归属商户号（或代理商号）过滤，从摘要与详情里定位具体动作与操作人。
## 在线用户
当前登录中的会话列表，可强制下线：
- 按用户名、账号、终端（运营端 / 代理商端 / 商户端）筛选；同一账号多端登录会显示多行（每行一个会话）；
- 「强制下线」单个或勾选批量执行——只终止会话，**不锁定账号**，对方可立即重新登录；适合清理忘记退出登录的公共电脑会话。
## 登录锁定
[登录安全](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)策略触发失败锁定后的记录页：
| 状态 | 含义 |
| --- | --- |
| 计数中 | 失败未达阈值，仅累计计数 |
| 锁定中 | 已锁定，显示剩余分钟数 |
| 已到期 | 锁定时间已过，下次登录自动清除 |
「解锁」会**同时清除失败计数**，用户立即可以再试。用户反馈「登录不了」时，先来这里看是不是锁定了，再看[账号状态](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)。
若列表顶部提示「登录锁定功能未启用」，说明当前策略已关闭失败锁定，列表只是切换前的历史数据，解锁功能仍可用。
## 文件记录
平台存储中所有文件的台账（各业务上传的文件自动汇总）：
- **查询**：文件名、原始文件名、访问类型（公开 / 私有）、业务分类；
- **操作**：预览（新窗口打开）、下载、查看详情（文件大小、MIME、存储路径、业务分类等）；
- 本页**只读**——删除文件请到产生它的业务页面操作；「业务分类」可用于判断文件来源。
## 相关链接
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：日志背后的策略开关
- [用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)：账号状态与锁定机制
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：开放接口错误对照
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md) / [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)：业务操作日志归属列跳转的目的地
---
# 商户管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md
# 商户管理
> 商户管理是运营端开通与代管商户的入口。**菜单路径**：商户管理 → 商户列表。
>
> plus 版在开源基础版之上增加了商户归属体系（直营 / 挂靠代理商）、归属调拨、进件资料主档与商户功能开关；新商户从零到能收款的主线（创建 → 进件 → 通道商户 → 密钥 → 验证）见[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)。
## 商户列表
- **查询条件**：商户名称、所属代理商（可选「平台直营」或具体代理商）、主体类型（小微 / 个体 / 企业）、状态（启用 / 禁用）；
- **列表列**：商户名称、商户简称、**所属代理商**（无归属显示金色「平台直营」标签，挂靠代理商显示绿色标签）、主体类型、状态、商户号、创建时间；
- **操作列**：只有一个「**管理**」按钮，进入该商户的[商户工作台](#商户工作台)后，所有代管操作（调拨、启停、删除）都在工作台内进行，列表页不直接提供编辑与删除。
## 新增商户
工具栏「新增」打开抽屉，表单分两组：
**商户信息**
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 商户名称 | 是 | 商户全称 |
| 商户简称 | 是 | 列表与页面中展示的简称 |
| 主体类型 | 是 | 小微商户 / 个体工商户 / 企业 |
| 所属代理商 | 否 | 留空即平台直营；选择代理商则创建即挂靠该代理商 |
**管理员信息**（该商户的管理员账号，用于登录商户端）
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 账号 | 是 | 6~20 位，仅字母、数字、`_`、`-`，商户终端内唯一 |
| 名称 | 是 | 管理员显示名称 |
| 密码 / 确认密码 | 否 | **留空时自动生成随机初始密码**；填写则需两次一致 |
保存成功后系统自动完成四件事：生成商户号（`M` 开头）、创建商户管理员账号（绑定商户超管角色）、创建**默认应用**、创建**默认门店**。结果页展示账号与初始密码明文（只显示一次），请立即复制并转告商户。
## 商户归属与调拨
商户归属分两种模式：
- **平台直营**：无归属代理商，由平台直接管理；
- **挂靠代理商**：归属某个代理商，代理商端可在授权范围内代管（代建、查看订单、收紧功能开关）。
归属变更**不走编辑表单**（商户资料页的「所属代理商」为只读），统一走商户工作台的「**调拨归属**」高危操作：
1. 选择目标归属（平台直营或另一代理商），填写**调拨原因**（必填，记入审计日志）；
2. 点「**预演调拨**」查看影响：现归属 → 调拨后归属、跟随设备数（绑定该商户的 POS / 音箱 / 打印设备）；存在阻断原因时会以红字列出并拒绝调拨；
3. 确认执行（二次危险确认）后生效。
**历史订单仍归属原代理商**（新代理商不可见），仅调拨后的新交易归属变更。归属体系的完整说明（含联动矩阵）见[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)。
## 商户工作台
从商户列表「管理」进入，是运营端代管**单个商户**全部配置的枢纽，按磁贴卡片分组。商户在商户端看到的配置页与之镜像，数据同源。
| 分组 | 入口 | 功能 |
| --- | --- | --- |
| 基础管理 | 商户资料 | 查看 / 编辑商户信息（归属只读） |
| | **进件资料** | 主体 / 法人 / 执照 / 经营场所四类资料主档，创建进件申请时勾选复用 |
| | 商户用户 | 该商户的账号管理（新增、角色分配、重置密码、封禁） |
| | 门店管理 | 门店档案增删改查、默认门店 |
| | 操作日志 | 跳转业务操作日志页（自动带该商户筛选） |
| 支付配置 | 通道商户 | 在各支付产品上开通通道商户（创建入口**只在这里**），见[通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md) |
| | 应用管理 | 商户的应用（appId）管理，见[应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md) |
| | 支付应用(微信) | 登记该商户的微信公众号 / 小程序等开放应用 |
| | 支付应用(抖音) | 登记该商户的抖音开放应用 |
| | 系统终端 | 终端台账、与通道终端绑定 |
| 接入配置 | 对接配置 | 代管该商户的 API 签名密钥（与商户端「对接配置」同数据） |
| | 域名校验文件 | 上传微信域名校验文件（仅 `MP_verify_*.txt`，微信授权回调） |
| | **功能开关** | 平台直配该商户的门户功能与接口许可（见下文） |
| 风控与限额 | 风控配置 | 商户级风控开关（地理围栏等） |
| | 交易限额 | 单笔与日 / 周 / 月累计限额规则 |
| 管理操作 | 禁用商户 / 启用商户 | 切换启用状态，禁用后无法发起交易 |
| | **调拨归属** | 变更商户归属代理商（见上文） |
| | 删除商户 | 强确认（需输入商户名称），见下文删除规则 |
### 商户功能开关
工作台 → 接入配置 → 功能开关，平台直接配置该商户可用的功能项（平台意图层）：
- 代理商只能在此基准上**单向收紧**，不能放开平台已关闭的能力，生效值以「生效预览」抽屉为准；
- 开关关闭后**接口立即拦截**，菜单入口要等商户重新登录后才刷新；
- 退款 / 分账 / 预授权 / 支付分等操作类开关关闭后菜单仍可见，仅隐藏操作按钮并拦截接口。
层级权限体系的完整模型见[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)。
### 进件入口
商户维度的进件操作有两个入口：
- **进件资料**（工作台）：维护可复用的资料主档，进件申请时勾选自动带入快照；
- **进件申请**（菜单：商户管理 → 进件申请）：新建申请、工作台流转，见[进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)。
## 实名认证
商户实名认证（支付宝实名核验）由**平台单开关门禁**控制：平台在系统配置中开启实名认证开关后，商户须完成实名认证才可正常收款，认证操作在商户端「实名认证」页完成；未开启时不强制。运营端如需调整该门禁，见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)。
## 商户状态与删除
**启用 / 禁用**：在商户工作台 → 管理操作中切换。禁用的影响：
- 该商户**全部账号无法登录**商户端；
- 该商户**无法发起新的支付**（交易上下文校验不通过）；
- **在途订单不受影响**，通道回调仍会正常完成已有订单的状态更新；
- 各类商户下拉选择器中将不再出现该商户。
**删除商户**：仅商户工作台 → 管理操作 → 删除商户（需输入商户名称确认）。系统会拒绝删除**已有交易、订单、退款记录或仍有用户**的商户（硬阻塞条件）；删除为逻辑删除并级联清理子数据，请仅在测试数据清理等场景使用。
商户号、商户简称等信息修改不影响交易；但**主体类型创建后不可修改**，请创建时确认准确。挂靠商户不因代理商被删除而删除（代理商删除有独立硬阻塞条件）。
## 常见问题
**商户创建后能改挂靠代理商吗？**
能，但必须走商户工作台的「调拨归属」，不能在表单里直接改；调拨前先预演，注意历史订单归属不随调拨变化。
**平台直营与挂靠商户在功能上有差异吗？**
收款链路一致；差异在管理面——挂靠商户会受代理商功能开关收紧、代理商端可代管其部分配置。
## 相关链接
- [应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)：应用与默认应用规则
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：通道商户创建与通道侧配置的通用模型
- [进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)：商户进件全流程操作
- [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)：归属的另一端——代理商档案与管理
- [支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)：风控四层防线与限额兜底
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：通道对接主线
---
# 通知与邮件
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md
# 通知与邮件
> 本篇覆盖站内触达（**通知公告 → 通知中心**）与邮件、短信触达（**邮件模板 / 邮件发送记录 / 短信发送记录**）。**菜单路径**：系统管理 → 通知中心。
>
> 邮件能发出去的前提是已在[支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)中完成邮件服务器（SMTP）配置；短信同理依赖短信配置。
## 通知公告
面向**全体用户**（运营端、代理商端与商户端）发布公告。列表列：标题、重要程度（普通 / 重要）、置顶、状态、生效时间。
**发布流程**：新建公告（草稿）→ 编辑正文 → 发布。表单字段：
| 字段 | 说明 |
| --- | --- |
| 标题 / 正文 | 正文支持 Markdown 编辑，用户端按排版渲染 |
| 重要程度 | 「重要」的公告在通知中心以红色标题突出 |
| 置顶 | 置顶公告排在通知列表最前 |
| 生效时间 / 过期时间 | 可见窗口：生效时间前、过期时间后用户都看不到；都不填则发布后立即可见、永久有效 |
**状态流转**：`草稿` →（发布）→ `已发布` →（下线）→ `已下线`。发布与下线均需确认：发布后对所有用户可见；下线后用户端不再显示，但已读记录保留。
公告没有「指定接收人」的概念；需要定向触达单个用户时使用个人消息（当前版本由系统业务事件产生，如待办提醒）。
## 通知中心（用户视角）
每个登录用户通过顶栏铃铛进入自己的通知中心，看到**公告 + 个人消息**的聚合列表：
- 筛选「仅未读」；重要公告标题标红、置顶带标记；
- 点击标题查看正文时**自动标记已读**，铃铛未读数同步刷新；
- 「全部已读」一键清理未读。
运营、代理商与商户用户看到的通知中心功能一致。
## 邮件模板
系统内置**八个固定邮件场景**：邮箱绑定验证码、找回密码验证码、绑定邮箱变更通知、密码重置成功通知、邮箱解绑验证码、邮箱解绑通知、绑定手机号通知、绑定手机号变更通知。
**模板规则**：
- 只能改**文字内容**，不能改邮件版式（样式骨架由系统统一定义）；
- 编辑抽屉中**五个槽位**：邮件主题、邮件标题、正文文案、提示行（灰色小字，可留空）、页脚（分隔线下小字，可留空）；
- 可用变量（账号、验证码、有效分钟数、新邮箱、新手机号等）以 `{变量名}` 形式书写，点击变量标签即插入到光标处，发送时自动替换为实际值；
- 右侧**实时预览**渲染效果（示例数据，所见即所得，预览区宽度可拖拽调整）；
- 「填入默认文案」把出厂文案载入表单后再改；「发送测试邮件」按当前编辑内容发一封到指定邮箱验证效果；
- 「恢复默认」将该场景模板还原为出厂文案（仅自定义过的模板可用）。
## 邮件发送记录
所有发出的邮件（业务触发 + 测试发送）都在此留痕：
- **查询条件**：收件邮箱、发送状态（成功 / 失败 / 发送中）、业务场景；
- **详情**：失败原因、重试次数、正文渲染效果（可切 HTML 原文排查样式问题）；
- **重发**：仅失败状态可用，适合邮件服务临时故障后补发；
- **删除**：清理无价值的记录（如测试邮件）。
## 短信发送记录
验证码等业务短信的发送留痕：
- **查询条件**：收信手机号、发送状态、业务场景；
- **列表列**：收信手机号、业务场景、发送状态、供应商、发送时间——模拟短信（mock）供应商发出的记录也在此可见，便于测试环境核对；
- **详情**：查看该条短信的完整发送信息；
- **删除**：清理无价值的记录（验证码类短信不支持重发）。
## 相关链接
- [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)：邮件服务器与短信服务配置
- [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)：用户侧绑定邮箱与手机号（验证码的消费场景）
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：注册安全与短信防刷策略
- [运营工作台](https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md)：公告在工作台的展示
---
# 进件产品配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md
# 进件产品配置
> 进件产品配置回答的问题是：**哪些通道开放了进件、进件线在哪个页面维护**。**菜单路径**：支付管理 → 通道与产品配置。
>
> 该目录下有两个页面：「支付和进件产品」（常规线，进件配置并入产品级，见[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)）与「**进件产品（特殊）**」（本页主线）。
## 进件产品（特殊）
**菜单**：支付管理 → 通道与产品配置 → 进件产品(特殊)。
页面是平铺卡片网格，**只展示特殊直连进件线**（如 Adapay 直连进件、银联商务进网等不经过常规服务商线的进件形态）；微信、支付宝等常规线的进件配置已并入「支付和进件产品」的产品级，不在此页重复出现。
每张卡片展示通道图标、名称、进件方式与状态点，三种形态：
| 卡片形态 | 含义 | 可交互性 |
| --- | --- | --- |
| 已上线（绿点 + 底部「进件配置」入口） | 进件线已开放 | 点击进入对应配置页（如 Adapay 服务商配置，维护进件平台凭据） |
| 规划中（「即将支持」标签 + 灰卡） | 该通道进件在规划中、暂未实装 | **不可点击**，仅占位提示 |
| 特殊直连线（底部灰标识） | 已上线但未登记独立管理面的线 | 仅展示，无独立配置入口 |
「即将支持」灰卡是**版本规划占位**，不代表当前可用；进件线的上线状态（规划中 / 已上线）随系统版本发布流转，界面上没有人工切换开关。请勿对灰卡通道安排进件计划。
进件申请本身**不在此页办理**：无论常规线还是特殊线，申请单统一在商户管理 → 进件申请中创建与流转，见[进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)。
## 通道服务商配置
服务商型进件线（微信特约、支付宝代开通及聚合通道服务商线）的平台侧参数，入口在：
**支付管理 → 通道与产品配置 → 支付和进件产品 → 通道服务商配置**
该分组下提供各通道的服务商管理页（支付宝服务商管理、微信服务商管理及拉卡拉、乐刷、随行付、斗拱、海科融通、富友、易宝等聚合通道的服务商管理 / 工作台页）。服务商参数的维护形态（基础信息 / 支付密钥 / 进件参数 / 费率磁贴与启停进件、启停支付）统一在[服务商工作台](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md#服务商工作台)，此处不再重复。
## 进件主数据维护
「进件产品（特殊）」页展示的进件线清单来自**进件主数据**。运营侧可维护的仅是展示层：
- **维护入口**：支付管理 → 支付主数据 → 支付通道 页的「进件」列；
- **可维护项**：是否展示（visible）、文案、排序，以及为通道配置进件产品线；
- **不可维护项**：进件线状态（规划中 / 已上线）随版本发布流转，不能手工修改。
字典页的具体操作见[支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)；主数据模型与后端化设计的背景见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)。
## 常见问题
**为什么有的通道显示「即将支持」？**
该通道的进件线尚在规划中。灰卡仅是占位，等版本更新上线后卡片会转为可点击的「已上线」形态。
**微信、支付宝的进件参数在哪里配？**
在「支付和进件产品」中进入对应服务商产品 → 服务商工作台 → 进件参数磁贴（进件场景应用、优惠费率活动等），见[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)。
**进件申请应该从哪里发起？**
统一从商户管理 → 进件申请发起，本页（及其目标配置页）只负责平台侧的进件线配置与凭据维护。
## 相关链接
- [进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)：进件产品配置、通道服务商参数、申报费率的概念说明
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)：五型通道分类与多服务商模型
- [进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)：申请单的创建与流转操作
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)：常规线的产品级进件配置与服务商工作台
- [支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)：进件主数据的展示层维护入口
---
# 进件申请与工作台
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md
# 进件申请与工作台
> 进件是把商户资料报送支付通道、获得通道侧收款身份的过程。**菜单路径**：商户管理 → 进件申请。
>
> 本页写运营端的**操作**；进件体系的概念（多服务商模型、五型通道分类、状态机全景）见[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)与[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)，此处不重复。
## 申请列表
- **查询条件**：商户号、归属服务商；
- **列表列**：单据名称、商户、进件产品、归属服务商、状态、外部状态（通道侧返回的状态原文）、来源（商户创建 / 运营代理商创建 / 接口创建）、错误提示、最后提交时间；
- **操作列**：
- **管理**：进入该申请单的[工作台](#申请工作台)；
- **填报链接**：生成 H5 填报二维码与链接，**仅草稿 / 预审拒绝 / 驳回状态可用**——商户手机扫码即可**免登录**填写进件资料，适合让商户自己补齐材料。
工具栏「新建进件」进入四步向导。
## 新建申请：四步向导
### 第一步：选择商户
表格单选（服务端分页），选定进件目标商户。代理商端代建场景下，这一步由代理商在其名下商户中选择。
### 第二步：选择进件产品
进件产品按**常规服务商线 / 特殊进件线**分组展示为卡片，只列出当前可进件的通道线。通道差异（微信特约 / 支付宝代开通 / Adapay 直连等）见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
### 第三步：申请信息
| 字段 | 说明 |
| --- | --- |
| 单据名称 | 申请单显示名 |
| 进件类型 | 商户 / 企业 / 小微进件；仅一种时自动预置不显示下拉 |
| **归属服务商** | **必选且创建后锁定**——申请单创建即绑定归属服务商，之后**换服务商只能作废重开**，不能改 |
| 开通产品 | 支付宝代开通线需要勾选要开通的产品（如当面付），其余通道无此维度 |
| 复用商户资料 | 默认勾选；商户工作台「进件资料」主档维护过的主体 / 法人 / 执照 / 经营场所资料自动复制进本申请快照 |
### 第四步：资料填报
按所选进件产品动态渲染资料表单（分产品差异化），全部必填项填写完整后提交，进入通道审核。
## 申请工作台
从列表「管理」进入，是单笔申请的办理中枢：
| 磁贴 | 功能 |
| --- | --- |
| 资料填报 / 资料查看 | 可编辑状态（草稿 / 驳回 / 预审拒绝 / 数据补填）下完善资料；其余状态只读查看 |
| 进度与结果 | 通道侧审核进度与产物（商户号、应用 ID、合同等），同步后展示；「已生成商户」状态可一键前往通道商户 |
| 流转历史 | 申请单全部状态流转记录 |
**操作按钮**（按状态动态出显）：
- **提交申请**：草稿 / 数据补填 / 驳回 / 错误 / 已关闭状态可提交，提交后进入通道审核；
- **审核**：预审 / 数据补填状态出现，运营侧预审资料完整性与合规性，通过后放行提交通道；
- **生成通道商户**：通道审核**通过**后出现，把申请到的商户号生成为通道商户，与进件商户打通——这是进件的收口动作；
- **作废**：不再继续的申请可关闭作废；**换归属服务商 = 作废当前申请后重新新建**（归属锁定语义）。
## 状态机速查
| 状态 | 含义 | 关键动作 |
| --- | --- | --- |
| 草稿 | 创建未提交 | 填报、提交、H5 填报链接 |
| 预审 | 待运营预审 | 审核 |
| 预审拒绝 | 预审未通过 | 修改资料后重新提交 |
| 数据补填 | 通道要求补充资料 | 补填后提交 |
| 申请中 | 已提交通道审核 | 同步进度 |
| 驳回 | 通道驳回 | 修改后重新提交、H5 填报链接 |
| 通过 | 通道审核通过 | **生成通道商户** |
| 已生成商户 | 通道商户已建 | 前往通道商户 |
| 已关闭 / 错误 | 作废 / 异常 | 重新提交或作废重开 |
微信特约商户进件：提交后由微信审核，**审核通过后还需超级管理员在微信内完成签约确认**，签约完成分配特约商户号后才能生成通道商户。Adapay 直连进件：审核通过后自动分配商户号与应用，可在「进度与结果」中查看产物并生成通道商户。
## 常见问题
**选错了服务商怎么办？**
申请单创建即锁定归属服务商，不能改。作废当前申请（关闭），用同一商户重新走一遍新建向导并选对服务商；已复用的资料主档不受影响。
**能让商户自己填资料吗？**
可以。在列表「填报链接」生成二维码发给商户，免登录填写，仅草稿 / 预审拒绝 / 驳回状态可用；填完运营侧继续审核与提交。
**审核通过就等于能收款了吗？**
还差最后一步：在工作台点「生成通道商户」，把申请到的商户号落到通道商户档案，之后按[通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)完成路由等配置。
## 相关链接
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)：多服务商模型与五型通道分类
- [进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)：状态机、资料主档与 OCR、作废重开机制
- [进件产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)：进件产品（特殊）与通道服务商配置
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)：进件资料主档入口
- [商户开通与对接就绪](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md)：进件在上线流程中的位置
---
# 支付订单与退款
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/orders.md
# 支付订单与退款
> 交易管理是运营端的**跨商户**交易视图：不限定单一商户，可全平台检索、导出与处置。菜单：交易管理。三层订单模型（业务单/资金交易）等概念见[支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)与[退款管理](https://doc.plus.daxpay.cn/common/refund.md)，本页只讲页面操作。
## 页面一览
| 菜单项 | 看什么 | 常用操作 |
| --- | --- | --- |
| 支付交易 | 资金交易层：每笔资金往来的最终状态 | 订单明细、退款、发起分账、关闭订单、同步状态、导出 |
| 支付订单 → 普通支付 | 业务单层：商户直连 API 下单 | 查询、订单明细 |
| 支付订单 → 网关支付 | 网关形态业务单（统一收银台/聚合扫码） | 查询、订单明细 |
| 退款订单 | 全平台退款单 | 查询、详情、同步状态 |
| 异常订单 | 资金与状态不一致的疑难单 | 确认成功、忽略 |
| 资金流水 | 收款/退款两类资金流水 | 查询、导出 |
| 交易费用明细 | 每笔交易按费率快照的手续费记账 | 查询、导出 |
分账订单、预授权支付（支付宝预授权/微信支付分）同在交易管理下，概念与操作见[支付分账](https://doc.plus.daxpay.cn/common/alloc.md)与[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)。
## 通用查询能力
- **跨商户筛选**：各页均带「商户」筛选项，支持按商户名称/商户号检索，不选即全平台视角——这是运营端区别于商户端的核心能力；
- **商户应用**：进一步按应用收窄；
- **时间范围**：按创建时间区间过滤；
- **金额**：按金额（单位分）过滤；
- **导出**：支付交易、资金流水等页支持按当前查询条件导出，导出由服务端生成，期间按钮防重复提交。
## 支付交易
资金层的总台账，列包括资金交易号、交易形态、通道订单号、金额、**入账金额**、**可退金额**、资金状态、分账状态、支付通道/渠道、通道商户号、支付成功时间、商户。操作列除「订单明细」外，其余收入更多菜单：
- **退款**（危险操作）：从资金单直接发起退款，可退金额为上限；
- **发起分账**：分账状态为未分账/部分分账时可用；
- **关闭订单**（危险操作）：终态单不可关；
- **同步状态**：非终态单手动向通道查询最新状态。
业务单还在处理中时，先在支付交易页看资金状态与通道订单号：资金层已成功而业务层未推进，多半是回调或同步问题，去[通道回调记录](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md)核对。
## 普通支付与网关支付
业务单层的两个视图，字段口径一致（平台业务单号、商户订单号、订单标题、金额、业务状态、支付产品、支付能力、商户），网关支付多一个**网关类型**筛选（统一收银台/聚合扫码），用于区分下单形态。两页以查询和订单明细为主，资金操作在支付交易页做。
## 退款订单
退款单台账：退款号、资金交易号、商户订单号、金额、退款状态、交易形态、支付产品、商户、创建时间。长时间停在处理中时用**同步状态**主动查询通道侧结果。退款原因、超期处理等概念见[退款管理](https://doc.plus.daxpay.cn/common/refund.md)。
## 异常订单
发现来源（通道回调/同步查单/定时任务）与异常类型（关单后收款、失败后收款、撤销后收款）自动落入此页，处理状态有待处理/已确认成功/已忽略。两个处置动作：
- **确认成功**（高危）：确认后订单翻转为支付成功并**向商户补发支付成功通知**，执行前必须先在支付交易页核实通道侧确已收款；
- **忽略**：判定为无需处理后归档。
完整核查思路见[异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md)。
## 资金流水
收款、退款两类流水的流水账：资金交易号、流水类型、商户订单号、退款号、金额、订单标题、通道订单号、商户、创建时间。用于资金口径的核对与导出，本身无操作。
## 交易费用明细
每笔交易按**费率快照**落账的手续费明细（plus）：交易订单号、业务类型、商户号、代理商号、一级代理商号、支付方式/产品/能力、交易金额、费率、计费规则摘要、商户手续费、平台收入。筛选项含商户号、代理商号、业务类型与**费率来源**，是商户计费对账的权威口径，见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)。
## 常见问题
**商户说有笔钱收到了但订单显示未支付？**
先查[通道回调记录](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md)该笔是否有回调及处理状态，再对支付交易做一次同步状态；确属「关单/失败后收款」的落入异常订单，核实后确认成功。
**退款显示处理中很久了？**
退款是异步链路，先用退款订单页的同步状态查通道侧；通道侧已成功而平台未推进，参考[退款管理](https://doc.plus.daxpay.cn/common/refund.md)的超期处理。
**想核对某商户当月手续费？**
交易费用明细页按商户号+时间范围过滤后导出，费率口径以计费规则摘要列为准。
## 相关链接
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md) — 三层订单模型概念
- [退款管理](https://doc.plus.daxpay.cn/common/refund.md) — 退款状态机与超期处理
- [异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md) — 核查思路正典
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md) — 费用记账口径
- [回调通知管理](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md) — 回调链路排查
---
# 运营端使用入门
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/overview.md
# 运营端使用入门
> 运营端是**平台运营方**使用的统一操作平台，负责商户与代理商开通、进件审核、通道对接、费率风控与系统管理；商户自助操作在[商户端](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)完成，代理商在代理商端操作（见[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)），移动端另有运营 APP 承载高频查询与处置，各端数据同源。
>
> 本地开发环境运营端地址为 `http://localhost:16999`，默认账号 `bootx / 121212`（生产环境部署后必须立即修改）。
## 功能分区总览
运营端侧边栏按业务域分为以下分区：
| 分区 | 包含功能 | 说明 |
| --- | --- | --- |
| 仪表板 | 工作台、分析页 | 交易概览与运营数据 |
| 系统管理 | 权限管理（角色、用户）、基础数据（菜单、字典、用户协议）、系统配置（平台配置、系统安全配置、三方平台管理）、敏感词管理、通知中心、系统监控、日志管理 | 平台级系统管理 |
| 支付管理 | 支付主数据、通道与产品配置、支付应用、接入配置、支付安全 | 支付域主数据、产品与风控配置 |
| 代理商管理 | 代理商信息（档案、用户、功能开关、推广邀请码） | 代理商体系入口 |
| 商户管理 | 商户列表、通道商户、进件申请、邀请注册 | 商户开通、代管与进件 |
| 交易管理 | 支付交易、支付订单、退款订单、分账订单、预授权支付、异常订单、资金流水、交易费用明细 | 交易查询与处置 |
| 回调通知 | 商户回调推送、通道回调记录 | 回调链路排查 |
| 对账管理 | 对账单、差错单 | 通道对账与差错处理 |
| 设备管理 | 码牌管理、云音箱、云打印、辅助支付终端 | 支付设备台账 |
| 投诉管理 | 投诉工单 | 渠道投诉处置 |
| 开发调试 | 支付调试（普通/网关/预授权）、签名调试、认证调试 | 不写代码验证支付链路 |
| 扩展插件 | 易支付 | 兼容协议接入 |
刚部署完成的系统请先走[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)主线，本文只做功能地图速查。
## 常见任务入口
| 我想… | 去哪里 |
| --- | --- |
| 修改系统名称、Logo、备案信息 | 系统管理 → 系统配置 → 平台配置 → 站点配置 |
| 配置各端访问地址（支付回调依赖） | 系统管理 → 系统配置 → 平台配置 → 端点配置 |
| 创建商户 | 商户管理 → 商户列表 → 商户管理 → 新增 |
| 给商户配置支付通道 | 商户列表 → 管理 → 商户工作台 → 通道商户 |
| 配置支付宝 / 微信通道密钥 | 商户工作台 → 通道商户 → 管理 → 对应分组 |
| 配置平台级服务商密钥 / 进件产品 | 支付管理 → 通道与产品配置 → [支付和进件产品](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md) |
| 决定一笔支付走哪个通道商户收款 | 商户工作台 → 应用工作台 → [通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md) |
| 审核一笔进件申请 | 商户管理 → 进件申请 → [进件申请工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md) |
| 开通一个代理商 | 代理商管理 → 代理商信息 → [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md) |
| 查一笔支付订单 | 交易管理 → 支付交易 / 支付订单 |
| 处理退款 | 交易管理 → 退款订单 |
| 查回调有没有发出去 | 回调通知 → [商户回调推送](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md) |
| 下载通道对账单 | 对账管理 → [对账单](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md) |
| 建一个运营人员账号 | 系统管理 → 权限管理 → [用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md) |
| 验证支付链路通不通 | 开发调试 → 支付调试（普通） |
| 封禁可疑来源 IP | 支付管理 → 支付安全 → [黑名单管理](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md) |
| 排查「交易被限制」类反馈 | 支付管理 → 支付安全 → 风险命中记录 |
| 看今天 / 近期交易怎么样 | 仪表板 → [工作台](https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md) / [分析页](https://doc.plus.daxpay.cn/operation-guide/admin/analytics.md) |
| 发布一条全员公告 | 系统管理 → 通知中心 → [通知公告](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md) |
| 查开放接口为什么报错 | 系统管理 → 日志管理 → [支付接口日志](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md) |
| 查一条业务数据是谁改的 | 系统管理 → 日志管理 → [业务操作日志](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md) |
| 强制某个账号下线 / 解锁 | 系统管理 → 系统监控 → 在线用户 / 锁定用户 |
| 修改自己的密码、绑定邮箱、绑定手机号 | 右上角头像 → [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md) |
| 调整密码强度、登录锁定阈值 | 系统管理 → 系统配置 → [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md) |
## 核心概念
- **商户工作台**：运营端代管单个商户所有配置的入口（商户列表操作列「管理」进入），按磁贴卡片分组；商户在商户端看到的配置页与之镜像，数据同源。
- **通道商户**：商户在某个支付产品（如支付宝直连）上的开通记录，创建时固化沙箱/生产环境快照，是路由与密钥配置的载体；进件申请审核通过后也会自动生成通道商户绑定。
- **应用（appId）**：商户下的调用隔离单元，不指定 appId 的交易回落「默认应用」；网关支付、收银台、通道路由都按应用维度配置。
- **代理商**：平台与商户之间的展业主体，名下可挂靠商户并代管其通道配置（授权代管）；商户归属支持直营（平台）与挂靠（代理商）两种模式，可调拨。
## 权限体系
- 运营端使用**角色 - 菜单**授权：角色绑定可见菜单与操作权限码，用户分配角色（单角色），见[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)。
- 角色按终端隔离（运营端 / 代理商端 / 商户端），三类终端的账号都在用户管理页按 Tab 统一管理。
- 授权采用**统一授权**模型：权限码以菜单编码为锚点挂载在授权树上，新建或调整角色见[权限与菜单管理](https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md)；菜单树由系统版本管理，一般无需改动。
## 相关链接
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：上线主线流程
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md) / [应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md) / [进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md) / [邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)：商户开通与进件
- [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md) / [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)：代理商体系
- [支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md) / [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md) / [支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md) / [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md) / [支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)：支付域配置
- [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md) / [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md) / [通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md) / [日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)：平台级配置
- [权限与菜单管理](https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md) / [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)：授权与账号自助
- [支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)：四层防线、黑名单与命中排查
- [开发者调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md) / [易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)：调试工具与兼容协议
- [业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)：订单、退款、分账等日常操作
---
# 支付应用
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md
# 支付应用
> 支付应用域管理**平台 / 商户在开放平台申请的应用凭证**：微信公众号 / 小程序、抖音应用、收银台小程序。JSAPI 与小程序支付取 openId 时必需。**菜单路径**：支付管理 → 支付应用（微信支付应用 / 抖音支付应用 / 收银台小程序）。
>
> 通道侧的收款凭据（服务商密钥、通道商户）在[通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)维护，两者配合使用；各端小程序的登录凭证另见文末说明。
## 微信支付应用
**菜单**：支付管理 → 支付应用 → 微信支付应用。页面分两个页签：
| 页签 | 用途 |
| --- | --- |
| 平台应用 | 以**平台 / 服务商身份**登记的公众号、小程序、移动应用，供各服务商产品的默认绑定引用 |
| 商户应用 | 归属具体商户的公众号 / 小程序等，供该商户的通道商户能力绑定使用（可从商户工作台「支付应用(微信)」直达并锁定该商户） |
**登记字段**：应用名称、应用类型（公众号 / 小程序 / 移动应用）、AppId（全局唯一，保存时查重）、AppSecret。
编辑时变更应用类型，系统会自动清除与该应用不兼容的能力绑定，变更后需重新配置能力绑定。
### 能力绑定
微信支付按**支付能力**取 openId，不同能力对应用类型有兼容要求（如 JSAPI 只认公众号、小程序支付只认小程序、扫码与付款码兼容多种）。绑定发生在两个层面：
| 层面 | 入口 | 作用 |
| --- | --- | --- |
| 产品级默认 | 服务商工作台 → 默认支付应用 | 该产品下未单独绑定的通道商户回落使用 |
| 通道商户级 | 通道商户详情 → 应用管理 → 能力绑定 | 为单个通道商户指定各能力用哪个应用 |
服务商（特约）模式下每个能力还可以选择「**服务商默认**」——不单独绑定、跟随服务商侧配置。绑定选项只会列出与该能力类型兼容的应用。
## 抖音支付应用
**菜单**：支付管理 → 支付应用 → 抖音支付应用。结构与微信完全一致（平台应用 / 商户应用 / 能力绑定），差异：
- 应用类型为**小程序 / 移动应用 / 网站应用**，没有公众号；
- 支付能力对应抖音系（JSAPI、扫码、H5、APP），兼容规则随能力不同。
## 收银台小程序
**菜单**：支付管理 → 支付应用 → 收银台小程序。分**平台公共档**与**商户自定义覆盖**两层，覆盖微信 / 支付宝 / 抖音三个消费者扫码平台：
- **平台公共小程序**：未配置自定义小程序的商户共用此平台收银台，配置后全平台生效；按平台分页签维护各小程序凭证（AppId、Secret，支付宝线含证书模式三件套）；
- **商户自定义小程序**：先选商户，按平台维护其自有收银台小程序凭证（每商户每平台一条）；支持**启用 / 停用**——启用后该平台扫码优先使用商户自有小程序，停用后回退平台公共档，凭据保留可随时重新启用。
支付时的 openId 与收款应用的 channelAppId 必须同源：平台小程序的 AppId 需在所用支付通道侧完成绑定或报备（服务商模式通常是服务商小程序 + 子商户号报备，聚合通道一般为子应用维度），**并非所有通道开箱即用**，接入前先与通道确认。
收银台小程序的使用形态与发布流程见[收银台功能地图](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md)。
## 微信域名校验
微信侧配置业务域名 / JS 接口安全域名时，要求在网站根目录放置校验文件。系统提供托管，两处归属不同：
| 入口 | 支持的文件 | 场景 |
| --- | --- | --- |
| 支付管理 → 接入配置 → 域名校验文件（平台级） | 微信 `.txt` 与支付宝 `.html` 双后缀校验文件 | 平台域名与商户归档托管；可按文件名 / 验证内容 / 归属（平台 / 商户）/ 商户号检索，放置路径按需选择 |
| 商户工作台 → 接入配置 → 域名校验文件（商户级） | 仅 `MP_verify_*.txt` | 商户自有域名（如商户端回调域）的校验文件 |
上传时直接选择开放平台下载的原始文件，系统读取内容托管在支付域名下；上传后到微信公众平台按系统提示的地址完成域名配置。编辑只能改备注，文件本身如需更换请删除后重新上传。
## 常见问题
**移动端各 APP / 小程序的登录凭证在哪配？**
各端（运营端 / 代理商端 / 商户端 APP 与小程序）自身的登录凭证在支付管理 → 接入配置 → APP 应用管理 维护，与本页的支付收银凭证是两回事。
**商户自有小程序和平台小程序怎么取舍？**
默认用平台公共档即可；商户对收银页面品牌有要求（自有小程序主体）时为其配置商户自定义档。停用商户档即回退平台档，不需要删配置。
**绑定能力时选不到想要的应用？**
绑定下拉只列出与该能力类型兼容的应用：检查应用类型是否匹配（如 JSAPI 需要公众号、小程序支付需要小程序），不兼容的组合不会出现。
## 相关链接
- [收银台功能地图](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md)：收银台小程序的使用与发布
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：服务商密钥与通道商户的完整流程
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)：产品级默认应用与服务商工作台
- [微信支付](https://doc.plus.daxpay.cn/extension/channels/wechat.md)：微信直连与服务商两种接入的通道说明
---
# 支付主数据
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md
# 支付主数据
> 支付主数据是系统支持的「支付能力目录」：哪些通道、哪些产品、哪些支付方式可用，都以这里为准。**菜单路径**：支付管理 → 支付主数据。
>
> 五个页面均为**只读字典**：数据随系统版本与通道接入内置，日常用于查询编码、了解产品能力时查阅。唯一的例外是「支付通道」页附带进件能力的展示层维护（见下文）。
## 五个字典页
| 页面 | 内容 | 常见用途 |
| --- | --- | --- |
| 支付通道 | 系统支持的支付通道清单（支付宝、微信、拉卡拉……），含通道介绍、旗下支付产品列表与**进件能力标识** | 查某通道下有哪些产品、是否支持进件与沙箱 |
| 支付产品 | 通道 × 接入模式的粒度（如「微信服务商」「支付宝直连」是两个产品），含所属通道、沙箱支持、产品特性（服务商 / 终端报备 / 沙箱）与支付能力 | 开通通道商户前确认产品形态 |
| 支付能力 | 产品提供的原子收款能力（如微信 JSAPI、支付宝扫码），并反查关联产品 | 路由与收银台配置中选择能力时对照 |
| 支付渠道 | 按渠道维度（微信 / 支付宝 / 银联 …）汇总的渠道清单 | 了解渠道划分 |
| 支付方式 | 按渠道分组的支付方式目录（Tab 切换渠道），如微信下的 JSAPI、小程序、扫码、H5 | 查支付方式编码与含义 |
点行内「查看」打开详情抽屉，展示完整属性；支付产品详情还会列出该产品包含的支付能力。
## 它们之间的关系
```
支付通道 ──1:N──> 支付产品 ──关联──> 支付能力
（支付宝） （支付宝直连） （alipay_qr …）
支付渠道 ──1:N──> 支付方式
（微信） （wechat_jsapi / wechat_mini …）
```
- **通道 vs 渠道**：通道指第三方支付机构（拉卡拉、盛付通）；渠道指用户付款使用的支付品牌（微信、支付宝、银联）。聚合通道（如拉卡拉）能提供多个渠道的支付方式。
- **产品决定开通形态**：创建通道商户时选择的是**支付产品**，产品的服务商 / 直连属性决定要填的通道侧凭据。
- **支付方式是路由与收银台的配置语言**：[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)按支付方式分流，[收银台配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)按支付方式展示，编码以本目录为准。
## 进件能力维护（支付通道页）
支付通道页的「进件」列展示每个通道的进件能力标识，点击可维护其**展示层**属性：
- **可维护**：进件线是否展示（visible）、进件文案、排序，以及为通道挂载进件产品线（分化通道如汇付天下按产品线各一行）；
- **不可维护**：进件线状态（规划中 / 已上线）随版本发布流转，界面无人工开关。
维护结果直接驱动[进件产品（特殊）](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)页的卡片展示，模型背景见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)。
## 与「支付产品配置」的区别
[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)是**运营开关**：决定某产品当前是否可开通、处于沙箱还是生产环境、服务商参数怎么配；本页是**字典**：说明产品本身是什么。先在这里查清产品形态，再去产品配置里启停与配置。
配置或对接文档里出现的 `wechat_jsapi`、`alipay_qr` 等编码，统一在「支付方式」页按渠道 Tab 检索；通道侧产品编码在「支付产品」页检索。
## 常见问题
**为什么有的产品在字典里能看到，产品配置里却是灰卡？**
字典描述「系统认识这个产品」，产品配置页的「规划中」灰卡表示「当前版本尚未开放配置」——规划中的产品先入字典后实装，属正常现象。
**支付能力与支付方式是一回事吗？**
不是。支付能力挂在**产品**下（某产品在某通道形态下的原子收款能力），支付方式挂在**渠道**下（面向用户的付款方式编码）。路由与收银台配置使用支付方式编码，通道商户能力绑定使用支付能力。
**进件线状态为什么不能手动改？**
进件线的「规划中 / 已上线」是版本级红线（随版本发布流转），运营侧只能控制展示层（是否展示 / 文案 / 排序），避免人工放开未实装的进件线造成死路申请。
## 相关链接
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)：产品启停、服务商工作台与费率
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：按产品开通通道商户
- [通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)：按支付方式分流
- [支付通道总览](https://doc.plus.daxpay.cn/extension/channels/.md)：16 家通道的介绍与对接说明
---
# 通道路由
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md
# 通道路由
> 商户在同一条通道下可能有多个收款账户（通道商户）。通道路由回答的问题是：一笔支付请求进来，该走哪个通道商户收款。路由按**应用**生效，在代管的应用工作台中配置；配置好之后商户下单、网关收款都会按它自动分发。
## 路由如何工作
- **自动分发**：下单请求没有指定通道商户时，系统按该应用的路由配置匹配，回填产品、通道商户与支付能力后再进通道。
- **确定性映射**：一个渠道（或支付方式）只对应一个通道商户，当前版本**没有轮询、权重、优先级**等负载均衡策略。
- **直接指定会跳过路由**：网关支付的「直接指定」模式、或接口调用显式传入通道商户时，不走路由配置。
- 首次打开路由页会自动初始化一条默认策略（按渠道默认模式），但不会配任何通道商户，需要手动完成配置。
**入口**：商户管理 → 商户列表 → 管理 → 商户工作台 → 应用管理 → 应用工作台 → 「通道路由」卡片。路由页必须从应用工作台进入（携带商户与应用参数），直接访问会提示缺参。
## 两种配置维度
| 维度 | 配置粒度 | 每条配置的要素 | 适合场景 |
| --- | --- | --- | --- |
| 按渠道默认 | 支付渠道（微信/支付宝/银联/抖音…） | 渠道 → 通道商户 | 每条通道一个收款账户，简单省心 |
| 按支付方式 | 具体支付方式（如微信 JSAPI、微信扫码、支付宝 H5） | 支付方式 → 通道商户 + 支付能力（两者必须成对） | 同一通道下不同支付方式要分流到不同账户 |
- 按渠道默认时，支付能力由产品在运行时自动推导，无需配置；
- 两种维度**互斥**，同一时刻只有一种「生效模式」。切换维度配完后，必须点 **「设为当前生效」** 并确认，否则运行时仍按原来的模式解析——只切换单选钮不会生效。
- 生效中的模式会在工具条上标注「生效中」。
## 配置操作
### 按渠道默认（首次配置）
1. 从应用工作台进入通道路由页（首次进入自动创建默认策略，模式为按渠道默认）；
2. 点右上角「编辑」，在每个支付渠道卡片中选择该渠道的通道商户（可只配部分渠道，候选只列出本商户已启用且产品匹配的通道商户）；
3. 「保存」并确认覆盖；
4. 若生效模式不是「按渠道默认」，点「设为当前生效」。
### 按支付方式（精细分流）
1. 点「编辑」，把「配置维度」切到「按支付方式」；
2. 按渠道分组逐行选择「通道商户 + 支付能力」，两者**同时选或同时留空**，不能只填一个；不用的行留空即可；
3. 「保存」并确认覆盖；
4. 点「设为当前生效」，确认后下单即按支付方式解析。
「通道商户 + 支付能力」必须成对填写，页面与后端都会拦截只填其一的保存。每种支付方式全局只能配置一行。
## 命中预览
配置完成后不用真发起支付来验证：在应用工作台的**网关支付配置**页，当支付形态选择「跟随通道路由」或「指定支付方式」时，每个组合会显示**路由命中预览**——直接告诉你这样下单会走哪个通道商户、哪个能力；未配置的组合显示「未配置」，页头还有「路由命中 x/y」的覆盖率统计。配置完路由来这里扫一眼覆盖率，比试单更快。
## 常见拦截与排查
下单被路由拒绝时，报错会明确指向原因，对照处理：
| 报错/现象 | 原因 | 处理 |
| --- | --- | --- |
| 通道商户与产品环境不匹配 | 沙箱通道商户配在了生产产品下（或相反）；通道商户的环境标识创建时固化，不随产品切换 | 为目标环境另建通道商户，更新路由 |
| 通道商户已禁用 | 被停用的通道商户不会被路由命中 | 启用该通道商户，或换路由指向 |
| 支付产品已停用 | 停用产品不允许发起新支付 | 到[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)启用产品 |
| 支付渠道未配置通道商户 | 按渠道默认模式下，该渠道没有配置 | 补配对应渠道的路由 |
商户工作台的配置检查会提示「已启用的应用缺少路由策略」类告警，按提示进路由页配置即可消除。路由配置保存后立即生效，无需重启。
## 相关链接
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：通道商户的创建、启停与环境规则
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)：产品启停与环境（影响路由命中）
- [应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)：应用工作台与路由入口
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)：路由的主要消费方与命中预览
---
# 支付平台配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md
# 支付平台配置
> 平台配置是整站级的全局配置。**菜单路径**：系统管理 → 系统配置 → 平台配置，左侧分组导航共八个页签：**端点配置、站点配置、OSS 配置、邮件配置、短信配置、OCR 配置、实名核验、敏感词配置**（其中短信、OCR、实名核验按权限展示）。
>
> 其中端点配置与支付链路直接相关（上线必配），其余按需；上线时各页签的取舍见[上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)。
## 端点配置
告诉系统各端的对外访问地址，是**支付回调与页面跳转的基础**：
| 配置项 | 用途 |
| --- | --- |
| 运营端访问地址 | 运营端基础地址，第三方登录 client=admin 时生成回调 URL |
| 代理商端访问地址 | 代理商端基础地址，第三方登录 client=agent 时生成回调 URL |
| 商户端访问地址 | 商户端基础地址，须与商户前端访问源一致并在开放平台白名单登记 |
| **支付网关前端地址** | 收银台 / 网关页面地址，**支付页面跳转依赖此项**；同时是跳转型平台（支付宝 / 微信公众号）三方登录回调的透传入口 |
| **后端 API 地址** | 后端服务基础 API 地址，**通道回调通知等后端发起场景依赖此项，生产环境必须公网可达** |
每个地址右侧的「检查」按钮可验证连通性：后端 API 地址走部署自检探针（验证回调接口可达），其余地址校验 HTTP 可达性，通过时显示延迟。
三端地址要按实际部署填写（如 `https://admin.example.com`、`https://agent.example.com`、`https://merchant.example.com`）；未部署某端时对应地址可暂填占位值，但该端的三方登录回调不可用。
## 站点配置
控制系统的对外品牌展示，主要影响**登录页与收银台**等面向外部的页面：
| 配置项 | 说明 |
| --- | --- |
| 系统名称 | 全站显示的系统名称 |
| Logo / 暗色 Logo | 浅色与深色主题下的站点 Logo |
| 公司全称 / 电话 / 邮箱 / 微信 | 联系信息展示 |
| ICP 备案信息 / 链接 | 工信部 ICP 备案号与查询链接 |
| 公安备案信息 / 链接 | 公安联网备案号与链接 |
| 支付清算协会备案信息 / 链接 | 支付清算协会备案 |
| 增值电信业务许可信息 / 链接 | 增值电信业务许可证 |
| 版权信息 | 页面底部版权声明 |
未配置备案信息时相关页脚区域不展示，不影响功能。
## OSS 配置
平台的文件（站点素材、导入导出文件等）统一走 S3 兼容对象存储，支持 MinIO、阿里云 OSS、腾讯云 COS 等。参数较多（服务端点、路径样式、桶策略等），**完整参数说明、三家云厂商配置实例与排错见[存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md)**。
未配置 OSS 时依赖文件上传的功能不可用，但核心支付流程不受影响。
## 邮件配置
SMTP 邮件服务，用于**找回密码验证码**等邮件通知场景：
| 配置项 | 说明 |
| --- | --- |
| SMTP 服务器 / 端口 | 邮件服务商的 SMTP 地址与端口 |
| 用户名 / 密码 | SMTP 发件账号凭据 |
| 发件人地址 / 发件人昵称 | 邮件中展示的发件方 |
| 加密方式 | 默认 `ssl` |
| 超时时间（秒） | 默认 10 秒 |
| 启用状态 | 总开关 |
保存后可发送测试邮件验证。未配置时「邮箱找回密码」通道不可用（登录页找回入口会给出提示），账号密码登录不受影响。邮件正文文案可在[通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)的邮件模板中按场景自定义。
## 短信配置
短信服务配置，服务于**注册短信验证、短信找回密码**等场景：
- 支持多套供应商配置，**启用即成为默认配置**（单选模型，原启用的配置自动停用）；停用默认配置后验证码类短信将无法发送；
- 供应商列表内置**模拟短信（mock）**通道：不真实出网，测试发送时直接在页面返回验证码明文，便于本地与测试环境联调；
- 每套配置可「测试发送」验证连通性。
配套的防刷策略（发送间隔、手机号 / IP 日限、平台日总量熔断）在[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)的「短信安全」面板维护；发送明细见[通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)的短信发送记录。
## OCR 配置
进件资料录入使用的 OCR 识别服务配置，支持阿里云、腾讯云、百度云三家供应商，可识别**营业执照、身份证、银行卡**。配置好多套时指定默认供应商；未配置时进件资料需手工录入。
## 实名核验
商户实名认证（支付宝实名核验）服务配置与**收款门禁总开关**：开关开启后商户收款前必须完成实名认证；关闭时不强制。凭据复用第三方平台登录的支付宝应用凭据，详细配置见[第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)。
## 敏感词配置
控制敏感词检测的总开关。开启后，商户名称、进件名称等入口字段会经过敏感词校验（词表在「系统管理 → 敏感词管理 → 词库管理」维护，命中记录同目录可查）。一般保持默认开启，详见[敏感词管理](https://doc.plus.daxpay.cn/operation-guide/admin/sensitive-word.md)。
## 相关链接
- [存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md)：OSS 参数详解
- [敏感词管理](https://doc.plus.daxpay.cn/operation-guide/admin/sensitive-word.md)：词库与命中记录
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：注册安全与短信防刷策略
- [上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)：各页签的上线取舍
- [完整上线指南 - 平台初始化配置](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md)：配置域全景
---
# 权限与菜单管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md
# 权限与菜单管理
> 平台采用**角色 → 菜单 / 权限码 → 用户**的授权模型：角色决定能看到什么、能做什么；用户分配单角色。**菜单路径**：系统管理 → 权限管理（角色管理）/ 系统管理 → 基础数据（菜单管理）。
>
> 日常新增运营人员：[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)建账号 → 分配既有角色即可，本文面向需要**新建或调整角色**的管理员。
## 角色管理
- **列表**：角色编码、角色名称、终端类型（角色按运营端 / 代理商端 / 商户端隔离）、内置标记、备注；
- **新增 / 编辑**：角色编码（唯一，保存时查重）、角色名称、终端类型、备注；
- **删除**：需输入 `iam/role/{角色编码}` 文本确认，防止误删；**内置角色不可编辑、不可删除**。
内置角色（如商户超管）是系统功能的兜底配置。需要相近但不同的权限集合时，新建角色再分配权限，不要试图改动内置项。
## 分配权限（统一授权）
角色列表行内「分配权限」打开授权抽屉，树形结构混排**菜单节点**与**权限码节点**（用小圆点区分类型）。平台采用统一授权模型：**权限码以菜单编码为锚点挂载在授权树上**，一个权限码必须归属于至少一个已勾选的菜单才会生效——这保证了「能按到按钮的页面一定看得见」。
**工具条能力**：
| 功能 | 用途 |
| --- | --- |
| 搜索 | 按菜单名或权限码过滤，命中路径自动展开 |
| 全选 / 清空 / 展开 / 折叠 | 批量操作 |
| 勾选菜单时带权限码 | 默认开启：勾选菜单同时勾选其下全部权限码（推荐保持开启，避免「看得见页面按不了按钮」） |
| 只显示菜单 / 仅看已选 | 大树过滤视图 |
**勾选联动规则**：
- 勾选菜单 → 自动勾选其下全部子菜单（权限码视开关）；
- 勾选权限码 → 自动勾选其挂载的父菜单（保证入口可见）；
- 同一权限码挂在多个菜单下时，勾选一处即全局生效（节点上有提示标记）。
保存时显示「将保存菜单 N 项、权限码 N 项」的确认，提交后重新登录或刷新的用户按新权限渲染。
## 菜单管理
维护侧边栏菜单树与隐藏子页面。左侧骨架树 + 右侧子项面板，顶部按终端（运营端 / 商户端）切换，支持按名称 / 编码 / 路径 / 组件搜索。
**六种菜单类型**：
| 类型 | 作用 |
| --- | --- |
| 目录 | 侧边栏分组容器，不渲染页面 |
| 菜单 | 可点击的页面入口，需路径与组件 |
| 子页面 | 挂在菜单下的**隐藏路由页**（详情 / 编辑页），不出现在侧边栏 |
| 子页面分组 | 子页面的逻辑分组，纯组织用，不渲染 |
| 内嵌页 | iframe 嵌入外部页面 |
| 外链 | 新窗口打开外部地址 |
**编辑表单**要点：菜单类型决定字段（内嵌页填内嵌地址、外链填外链地址）；**标题直接填写中文**（菜单标题与权限码名称均为中文直存，保存即生效）；高级设置含排序、隐藏、缓存路由、固定标签页、徽章等。
菜单树由系统版本管理，升级时会更新。自建菜单只用于挂载自研扩展页面；随意改动内置菜单可能导致升级后功能入口丢失。
## 权限码
权限码是按钮级权限的最小单元（如「重置密码」「发布」）。代码中的权限码与库内记录通过**同步权限码**操作对齐：
- 菜单管理工具栏「同步权限码」→ 扫描后端接口 → 新增 / 更新 / 删除（结果会显示三类数量）；
- 单个菜单挂载了哪些权限码：菜单行内「权限码」抽屉查看（只读）。
系统升级引入新权限码后，不同步会导致新按钮对已授权角色不可见——**每次升级后在菜单管理执行一次「同步权限码」**。
## 常见问题
**给角色勾了权限码，用户还是提示无权限？**
统一授权要求权限码挂载的菜单也在已选集合内。检查授权树中该权限码上是否有「未勾选父菜单」的提示，把对应菜单勾上再保存。
**代理商端角色看不到新建的菜单？**
代理商端的菜单与权限码由后端种子维护，新增代理商端功能时必须保持菜单码与接口权限码同轨，存量库需执行增量 SQL 后再同步权限码。
## 相关链接
- [用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)：账号与角色分配
- [运营端使用入门](https://doc.plus.daxpay.cn/operation-guide/admin/overview.md)：权限体系速览
---
# 支付产品配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md
# 支付产品配置
> 支付产品是「商户能用哪种支付方式」的聚合载体：商户开通通道商户时选择产品，产品的能力决定他能发起哪些支付。**菜单路径**：支付管理 → 通道与产品配置 → 支付和进件产品。
>
> plus 版的产品配置形态为三层：**产品列表（平铺卡片）→ 服务商卡片列表 → 服务商工作台**；服务商参数统一在工作台维护，费率拆为独立子页。
## 产品列表页
页面是**平铺卡片网格**，每张卡片：
- **右上角性质角标**：「服务商」或「直连」，标识产品的接入模式（全通道统一展示；仅有一种模式的个别产品不强调）；
- **状态点**：绿 = 启用、灰 = 停用（纯展示，**启停入口在目标页面的标题栏**，不在卡片上）；
- **「规划中」灰卡**：暂未开放的产品不可点击，仅占位。
卡片底部入口按性质分流：
| 产品性质 | 底部入口 | 目标 |
| --- | --- | --- |
| 服务商型 | 服务商管理 | 进入该产品的[服务商卡片列表](#服务商卡片列表) |
| 直连型 | 通道配置 | 进入该产品的直连工作台（通道侧参数与费率） |
产品清单是系统内置的，**不能新增或删除**；想查产品挂了哪些能力，去[支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)只读查看。
## 服务商卡片列表
以「支付宝服务商管理」「微信服务商管理」及各聚合通道服务商管理页为代表，该列表页就是服务商型产品的**产品主页**：
- **标题栏是产品启停开关**：全局控制该产品下的所有服务商；停用后均不能发起新支付，存量订单的退款 / 同步 / 回调不受影响，重新启用即恢复；
- **服务商卡片**：展示服务商名称、应用号等信息，点击进入该服务商的[服务商工作台](#服务商工作台)；
- **新增服务商**：为产品添加一套服务商身份（同一通道可配多个服务商）。
plus 支持同一通道配置多个服务商：进件申请创建时选定归属服务商，**创建即锁定**。服务商体系详见[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)。
## 服务商工作台
服务商编辑的**唯一入口**：服务商列表、产品费率入口都汇到这里。按磁贴分组，**表单抽屉分段编辑**（整服务商一份配置，任一抽屉保存均提交全量）：
**配置磁贴**（以微信 / 支付宝服务商为例）
| 磁贴 | 维护内容 |
| --- | --- |
| 基础信息 | 服务商名称、编号等档案信息 |
| 支付密钥 | 服务商密钥 / 证书：微信为 API 证书、证书私钥、支付公钥（`.pem` 文件上传）；支付宝为应用密钥（公钥 / 证书两种模式） |
| **进件参数** | 进件场景应用、优惠费率活动等进件侧参数（微信 / 支付宝线） |
| **服务商费率** | 跳转独立费率子页维护该服务商的分层价目，见[支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md) |
| 应用管理 | 微信线跳转[微信支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)平台应用页签 |
| 默认支付应用 | 产品级平台默认应用（微信线） |
**管理操作**（红色组，三个独立开关）：
| 操作 | 语义 |
| --- | --- |
| 停用 / 启用**进件** | 只影响新进件申请能否选择该服务商（候选池），不影响已创建申请与支付 |
| 停用 / 启用**支付** | 只影响新支付请求能否使用该服务商，进件状态独立 |
| 删除服务商 | 强确认；**名下存在通道商户或进件申请时无法删除** |
聚合通道（拉卡拉、乐刷、斗拱、海科融通等）的服务商工作台结构一致，磁贴内容按通道差异增减（服务商密钥字段、微信应用绑定等），逐通道差异见[通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)。
## 直连产品工作台
直连型产品（支付宝直连、微信直连、抖音、云闪付、银联商务系列、盛付通直连等）从产品卡片进入**直连工作台**：
- 直连模式**没有平台级服务商密钥**——密钥在各商户的通道商户侧配置；
- 标题栏同样是产品启停开关；
- **费率子页**：直连产品也走分层费率（平台基准 / 代理商档 / 商户三层），入口在各产品工作台的费率配置页，见[支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)。
## 常见问题
**产品停用和服务商停用什么区别？**
产品停用是总闸（该产品下所有服务商一起停，不能发起新支付）；服务商的「停用支付」是分闸（只停一个服务商）。总闸开着分闸才有意义。
**服务商可以删吗？**
名下还有通道商户或进件申请时系统拒绝删除；确需删除先处理名下资产。
**规划中的产品什么时候能用？**
随版本发布上线，卡片转为可点击后即可配置；不要为灰卡产品排上线计划。
## 相关链接
- [支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)：服务商费率子页与直连费率页的操作
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：三段式配置模型与各通道差异速查
- [支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)：产品 / 能力字典查询
- [进件产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)：特殊直连进件线与通道服务商配置分组
- [支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md)：主数据 → 产品 → 服务商 → 费率 → 进件的上线主线
---
# 个人中心
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/profile.md
# 个人中心
> 个人中心是**当前登录用户**管理自己账号的地方（右上角头像进入），与用户管理里管理员处置他人账号是两个视角。运营端、代理商端与商户端都有同款个人中心，功能一致。
>
> 敏感操作（改密、绑定 / 解绑邮箱与手机号、管理通行密钥）都要求先输入**登录密码**确认，防止借用会话篡改。
## 基本设置
修改姓名与性别；登录账号只读。姓名保存后顶栏显示同步更新。
## 修改密码
- 旧密码 + 新密码 + 确认密码，新密码强度规则按平台[密码策略](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)动态提示；
- 密码进入[轮换周期](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)管理的账号，页面顶部会显示**过期提醒**（剩余天数 / 已过期），已过期的账号会被强制先改密再继续使用；
- 修改成功后建议同步更新密码管理器；忘记密码走登录页「忘记密码」（邮箱验证码找回，需先绑定邮箱）。
## 双因素认证（2FA）
平台开启 2FA 后可绑定认证器（Google Authenticator 等 TOTP 应用）：
1. **扫码绑定**：用认证器扫描二维码（或手动输入密钥）；
2. **输入动态码确认**：验证 6 位动态码完成绑定；
3. **保存备用验证码**：一次性使用的应急码（可复制 / 下载），**每个只能用一次**，必须勾选「已妥善保存」才能完成向导。
已绑定后可**重新生成备用码**（旧的全部作废）或**关闭** 2FA（需动态码或备用码确认）。登录时将被要求输入动态码。
## 邮箱绑定
- **绑定 / 换绑**：输入登录密码与新邮箱 → 收验证码 → 确认完成；
- **解绑**：密码 + 当前邮箱验证码；
- 已验证邮箱用于**找回密码**与安全通知——解绑前想清楚，解绑后无法邮箱找回。
## 手机号绑定
- **绑定 / 换绑**：先输入登录密码确认，再填写新手机号 → 收短信验证码 → 确认完成；
- **解绑**：密码确认后向当前手机号发送验证码，验证通过即解绑；
- 已验证手机号可用于**短信找回密码**等安全场景（需平台已配置并启用短信服务，见[支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)的短信配置）。
## 通行密钥（Passkey）
用设备指纹 / 面容 / PIN 登录，免输密码：
- **添加**：密码确认 → 系统弹出设备的生物识别验证 → 为该设备命名；
- 列表显示每把密钥的名称、是否**多设备同步**（iCloud 钥匙串等平台同步的密钥换机不丢；「仅此设备」的换机即失效）、创建与最后使用时间；
- 支持**重命名**与**删除**（删除需密码确认）；
- 浏览器不支持或页面非 HTTPS（本地 `localhost` 除外）时无法添加，但已绑定的仍可管理；需平台在[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)中开启。
## 三方账号绑定
绑定第三方平台账号（企业微信、钉钉、飞书、支付宝、抖音等平台按启用情况展示）：
- **绑定**：点对应平台的绑定按钮 → 弹窗完成 OAuth 授权 → 自动回填；
- **微信公众号**是扫码形态：绑定窗口展示二维码，用手机微信扫码、在手机确认页核对目标账号后完成授权，PC 端自动完成绑定（详见[第三方平台登录 - 扫码绑定](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md#公众号扫码登录与扫码绑定)）；
- **解绑**：确认后解除（解绑后不能用该平台账号登录本系统）。
可绑定的平台由管理员在[第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)配置决定。
## 相关链接
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：密码策略 / 2FA / 通行密钥的平台开关
- [用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)：管理员处置账号（重置密码、封禁）
- [第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)：三方登录的平台配置与机制
---
# 码牌管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md
# 码牌管理
> 码牌是线下主扫收款的核心物料。运营端负责**制牌与分发**：先在码牌模板定样式，再批量制牌入库，经「分拨代理商 → 绑定商户」链路投放。菜单：设备管理 → 码牌管理（码牌模板 / 码牌台账）。两类码牌模型与归属规则的概念见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)。
## 码牌模板
打印样式的模板库，制牌与「导出码牌图」都从这里取版式：
- **版式**：经典标准版、品牌渐变版、自定义 HTML 三类；
- **支付渠道标识**：聚合支付、微信支付、支付宝、银联、抖音——决定牌面上展示的渠道图标/文案；
- **标语**：牌面宣传语；
- **操作**：编辑、复制（快速派生变体）、**设为默认**（未指定模板时的打印兜底，二次确认）、删除（默认模板不可删）。
## 码牌台账
全部码牌的库存与归属台账。筛选维度：码牌编码、码牌名称、批次号、码牌类型（H5 / 小程序）、**归属类别**（平台级 / 商户级）、金额类型（自定义金额 / 固定金额）、状态（启用 / 停用）、所属代理商（未划拨）、商户（未绑定商户）、门店号。
**两类归属（核心概念）**
| 归属类别 | 语义 | 调拨 |
| --- | --- | --- |
| 平台级 | 库存牌，先制后派 | 可分拨给代理商、可收回，绑定商户后走商户链路 |
| 商户级 | 创建即锁定归属商户 | 不可调拨，链接中缀含商户号 |
「平台直营」的码牌在台账里统一叫**「未划拨」**——只表示还没分给任何代理商，不构成独立归属类别。
### 制牌（批量新建）
1. **码牌名称**与**批次号**（可一键生成 `Q+时间戳` 格式，批次号重复会被拦截）；
2. **归属类别**：选商户级时必须选定商户，创建即锁定归属；选商户级小程序批次时若该商户尚未配置收银台小程序，页面会黄条提醒——可以先印后配，扫码自动降级走 H5 收银页；
3. **创建数量**、**码牌类型**（H5 恒定打开 H5 收银页；小程序优先拉起小程序，前缀映射规则未配置时同样降级 H5）；
4. **是否分账**、**金额类型**（自定义金额 / 固定金额，后者需填固定金额，单位元）。
### 台账操作
- **分拨代理商 / 收回代理商**：平台级牌在平台与代理商之间的划拨；
- **绑定商户 / 解绑商户**：把牌落到具体商户（解绑为危险操作，会断开收款链路）；
- **导出 / 导出码牌图**：按筛选条件导出台账，或导出可直接送印的码牌图（用所选模板渲染）；
- **查看码**：展示该牌的码值与二维码，扫码验证用；
- 编辑、启用/停用、删除。
## 与代理商端、商户端的分工
- **代理商端**：有独立的码牌管理页，管理平台分拨过来的名下库存，可进一步绑定到名下商户，见[订单查询与码牌](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md)；
- **商户端**：商户查看/管理自己名下的码牌与自有模板，见[支付设备与码牌](https://doc.plus.daxpay.cn/operation-guide/merchant/devices.md)；
- 运营端是唯一能**制牌**和**跨代理商调拨**的入口。
## 常见问题
**商户级牌为什么不能调拨？**
商户级码牌链接中缀含商户号，绑定关系印在物料上，换商户等于换码，只能作废旧牌重新制牌。
**印好的小程序牌扫码打开了 H5？**
该商户的前缀映射规则或收银台小程序配置未就绪，码牌自动降级 H5 收银页保证可用；配置完成后无需换牌。
**「未划拨」和「绑定了商户」矛盾吗？**
不矛盾：未划拨指没有代理商归属（平台直营视角），平台直营牌仍可直接绑定商户使用。
## 相关链接
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md) — 两类模型与归属规则正典
- [订单查询与码牌](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md) — 代理商端码牌操作
- [支付设备与码牌](https://doc.plus.daxpay.cn/operation-guide/merchant/devices.md) — 商户端视角
- [网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md) — 码牌投放的上线主线
---
# 支付费率配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md
# 支付费率配置
> 费率配置决定每笔交易向商户收多少手续费。plus 版的费率是**分层链**：平台基准逐层落到商户报价，层与层之间有「下层不得低于上层」的实时校验。**入口都在支付管理 → 通道与产品配置 → 支付和进件产品**下。
>
> 本页写操作；分层模型与解析优先级见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)，规则要素与计算口径见[费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)。
## 两类入口
| 入口 | 路径 | 适用 |
| --- | --- | --- |
| 服务商费率 | 服务商产品 → 通道服务商配置 → 服务商工作台 → 服务商费率（部分聚合通道有独立的「xx服务商费率配置」子页） | 服务商型产品：每个服务商一套价目 |
| 直连费率 | 直连产品工作台的费率配置子页（如「支付宝直连费率配置」） | 直连产品：同样按分层结构配置，不经过服务商价目层 |
两类页面的表单结构一致：**列表按支付能力一行一条**，点「编辑」打开费率抽屉。
## 费率列表与三层链
列表列（每行 = 一个支付能力的费率链）：
| 列 | 层级语义 |
| --- | --- |
| 支付能力 | 费率锚定维度（如小程序支付、扫码） |
| **平台基准** | 全站基准层，差异化缺失时的兜底价 |
| **一级代理商档** | L1 增量层，**可选**——未启用时链退化为三层 |
| **二级代理商档位** | 中间层：服务商行 / 代理商分配档 |
| **商户费率** | 终端报价层，最终向商户收取的口径 |
编辑抽屉内按层分段编辑，每层输入下方有**实时链校验提示**：按「平台基准 ≤ 一级代理商档（可选）≤ 二级代理商档位 ≤ 商户费率」逐段比对，**破链当场红字**（例如商户费率低于平台基准），不必等保存报错；层未填齐时先提示待填。保存时后端按同一口径兜底校验。
费率未配置的交易照常成功，费用明细以「未配置」留痕，补配后可重算补账；0 与未配置是两回事（0 = 免费）。层级语义详见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)。
## 简单 / 高级双视图
编辑抽屉提供两种视图，**编辑的是同一份规则数据**，随时切换不丢内容：
| 视图 | 内容 | 适合 |
| --- | --- | --- |
| 简单 | 填一个百分比或固定金额 | 绝大多数常规费率 |
| 高级 | 展开完整规则要素：计费模式（百分比 / 固定 / 混合）、金额区段（阶梯）、最低费用、单笔封顶、起征点 | 阶梯价、混合计费等复杂策略 |
简单视图配好的值，在高级视图中就是一段单区段规则；高级规则退化为单段纯百分比时，回到简单视图依旧是一个数。规则摘要会在列表中以人话展示（如 `0.6% + 0.1元/笔 · 最低1元 · 封顶20元`），并随费用明细固化，历史账单文案稳定。
## 退款累计封顶
退款方向按**原支付时固化的规则快照**对退款金额重算并取负；**同一笔支付的累计退款手续费封顶为原支付手续费**——退完为止、不多收，全额退款时手续费正好轧平。该口径无需配置，引擎内置，详见[费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)。
## 配置操作
1. 进入对应费率页（服务商线从服务商工作台「服务商费率」进入；直连线从产品工作台费率子页进入）；
2. 在列表中找到目标支付能力行，点「编辑」；
3. 在抽屉中逐层配置：切简单 / 高级视图按需填写，观察每层下方的链校验提示；
4. 保存——链上任意相邻层倒挂都会被中文报错拦下，按提示调整；
5. 变更即时生效，**只影响之后的新交易**（每笔支付固化费率快照，历史不回溯）。
## 常见问题
**必须每层都配吗？**
按需配置：只配平台基准即全站统一价；为特定服务商 / 代理商档 / 商户做差异化时才补对应层。未配置的层回落上层解析结果。
**一级代理商档什么时候启用？**
需要给一级代理商划 L1 差价空间时启用；启用后它参与链校验（位于平台基准之上），未启用时链为三层。
**在哪看每笔交易实际按什么价收的？**
交易管理 → 交易费用明细，每条明细标注费率来源层级与规则摘要，见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)。
## 相关链接
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)：四级链模型与解析优先级
- [费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)：规则要素、计算顺序、双视图机制
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)：费率入口所在的产品与服务商工作台
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)：按快照落账的费用明细
---
# 对账管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md
# 对账管理
> 对账管理把「平台账」和「通道账」拉到同一张表里比：先建对账单、下载通道对账文件、执行比对，差异落入差错单。菜单：交易管理 → 对账管理（对账单 / 差错单）。费用口径的记账见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)，本页讲核对流程。
## 可用范围（如实说明）
- **已可用**：支付宝、微信的**直连**通道商户，支持对账文件下载与比对；
- **陆续支持**：聚合通道与服务商模式通道的对账文件下载在分批接入中，页面按通道商户维度创建时即可看出是否可下载；
- 通道子应用侧的支付宝/微信对账单下载端点尚未全部补齐，遇到「下载失败」先确认该通道商户是否在已支持范围。
## 对账单
对账单是每次核对的主记录：对账标题、对账日期、对账号、对账通道、对账结果、对账文件状态、比对状态。
**创建对账单**
1. 点「新建」，选择**通道商户**与**对账日期**；对账标题留空时由后端按「日期-通道商户名-产品名」自动生成；
2. 提交后系统尝试从通道下载对账文件，列表「对账文件」列显示状态；未自动完成时可**手动触发下载**；
3. 文件就绪后执行**比对**，生成对账结果与差错明细。
**文件操作**（有文件才显示）：下载通道对账单原始文件、下载平台对账单文件——两侧文件都拿到手，便于线下复核差异。
## 差错单
比对产生的差异明细，每行给出**平台信息**与**通道信息**两栏对照（交易号、交易金额、交易时间、交易状态），差异类型一目了然：
| 差异类型 | 含义 | 常见原因 |
| --- | --- | --- |
| 一致 | 双侧匹配 | 正常，仅作核对底稿 |
| 通道有平台无 | 通道账里有、平台没有 | 回调丢失且回查未触达，去[通道回调记录](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md)核实 |
| 平台有通道无 | 平台有单、通道账没有 | 通道侧未生成或下载窗口错位（跨日切单） |
| 状态金额不一致 | 双侧都有但状态/金额不同 | 退款等逆向单据两侧推进不同步 |
**处理流程**：差错单本身是**只读**的——唯一的页内动作是查看详情；修正不发生在差错单上，而是：
1. 在差错单看两侧对照，定位差异根因；
2. 到[支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md)的支付交易/异常订单处置平台侧（如通道已收款的平台单做确认成功/同步状态）；
3. 平台侧修正后，回到对应**对账单重新比对**，差异消除。
差错单没有「手工抹平」入口，平台侧永远以通道侧真实资金状态为准修正订单，再靠重新比对收敛差异。
## 常见问题
**对账文件一直下载不下来？**
确认通道商户属于已支持范围（支付宝/微信直连）；跨日订单要等通道侧账单生成（多数通道次日上午后），过早创建当日单会拿不到文件。
**差异数量突然变多？**
优先怀疑通道回调大面积失败：先看[通道回调记录](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md)的失败占比，修复回调链路后大部分「通道有平台无」会随补单消失，再重新比对。
**重复创建同一天的对账单会怎样？**
同一通道商户+日期会生成新的对账号，以最新一次比对结果为准；排障场景可用它做「重新比对」，无需等待自动任务。
## 相关链接
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md) — 平台侧费用记账口径
- [支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md) — 平台侧订单修正入口
- [回调通知管理](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md) — 差异根因的常见源头
- [运维面板总览](https://doc.plus.daxpay.cn/tools/panel/overview.md) — 定时任务与对账调度的运维视角
---
# 支付安全与风控
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md
# 支付安全与风控
> 「支付安全」分组只管**支付域**的安全：支付前后的事前拦截与事后补录、开放接口防重放。账号密码策略、登录安全属于系统域的[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)，两者分开。菜单：支付管理 → 支付安全。
>
> plus 的风控是全量四层防线（IP 黑名单 / 用户标识 / 省市地区 / 门店围栏）+ 事后补录 + 命中转黑，整体设计与各防线的边界见[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)；本页只讲这些能力在运营端页面上怎么操作。
## 页面总览
| 页面 | 角色 |
| --- | --- |
| 风控策略 | 八个分组统一配置：总开关、各维度防线、频率限制、限额兜底、接口安全 |
| 黑名单管理 | 手动维护 IP / 用户标识 / 省市黑名单 |
| 风险命中记录 | 只读命中台账，支持一键将命中值转入黑名单 |
| 风控预警 | 指标类预警的查看与标记处理 |
策略与名单是因，命中记录与预警是果。开源基础版只有 IP 级防线且命中不自动处置；plus 在此基础上补齐了用户标识、地区、围栏、事后链路，命中值可从记录页直接转黑。
## 风控策略
风控策略页左侧为分组导航、右侧为表单，整页统一「编辑 → 保存」，不是逐项即改即存：
| 分组 | 内容 |
| --- | --- |
| 通用与处置 | 风控总开关、IPv6 匹配、命中后拦截下单还是仅记录、事后补录开关 |
| 名单拦截 | IP 黑名单与用户标识黑名单两道防线开关 |
| 地域限制 | 海外 IP 拦截与省市级地区拦截 |
| 门店围栏 | 门店城市级 IP 围栏与三档策略 |
| 频率限制 | IP 日限与账号日限（每日支付笔数上限） |
| 限额兜底 | 未配限额商户的平台默认底线，全部留空即不限制 |
| 指标检测 | 自动封禁、商户成功率与通道指标预警的阈值 |
| 接口安全 | 开放接口防重放校验（见下节） |
- **总开关**关闭后所有事前风控检查跳过、不再产生事前命中记录，其余分组随之置灰；页面顶部概要标签实时汇总各维度状态；
- **门店围栏**是两级门控：平台在此开总闸，商户侧自主决定是否开启，两侧都开才生效；
- **频率限制**中 IP 日限为全平台共享计数，账号日限为 plus 独有的实时防线；
- **限额兜底**挂的是平台默认限额，商户侧完整的三级限额配置见[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/.md)。
## 接口安全（防重放）
开放支付接口的**签名校验始终强制启用**（见[签名机制](https://doc.plus.daxpay.cn/api/signature.md)），本分组配置的是额外的两道防重放防线：
| 配置项 | 默认 | 作用 |
| --- | --- | --- |
| Nonce 防重放校验 | 关 | 每个请求的随机数在有效期内只能消费一次，重复提交被拦截 |
| 请求时间窗口校验 | 关 | 请求时间与服务器时间差超过容差即拒绝（防过期/未来请求） |
| 时间窗口容差 | 300 秒 | 双向允许的最大时间偏差 |
| Nonce 有效期 | 300 秒 | 随机数的去重保留时长 |
启用后要求商户请求时携带随机数与请求时间字段；两层都关闭时直接放行。接口安全独立于风控总开关，始终展示与生效，只作用于开放支付接口。
## 黑名单管理
黑名单有五种类型，全部手动维护：
| 类型 | 名单值 | 说明 |
| --- | --- | --- |
| IP | 具体 IP 地址 | 精确匹配，不支持网段；平台全局生效，不区分商户/应用 |
| 支付宝用户 | 买家用户标识 | 按支付买家标识匹配 |
| 微信 OpenId | openId | 创建时需选择所属微信平台应用 |
| 省份 | 行政区划（下拉选择） | 按 IP 归属省份匹配 |
| 城市 | 市（省市级联选择） | 直辖市无独立市级，选省即可 |
表单字段：类型（创建后不可改）、名单值、状态（启用/禁用）、拉黑原因、过期时间（留空即永久有效，过期自动失效）、备注。同一类型下名单值不可重复。
名单只是数据，拦截还需要开关配合：IP/用户标识名单要开「名单拦截」、省市名单要开「地域限制」，且风控总开关必须开着。加了名单没生效时，先回风控策略页核对分组开关。
## 风险命中记录
只读台账，记录每次风控命中。**阶段**分两种：
- **事前拦截**：下单时检查命中（IP / 支付宝用户 / 微信 OpenId / 海外 IP / 省份 / 城市）；
- **事后命中**：开启事后补录后，支付成功的交易再比对一轮用户标识名单，命中落入此处。
列表给出命中值、IP 城市、门店城市、围栏策略、交易号、商户与时间，点开可看应用、订单号等完整信息。
页面对非围栏命中提供**转黑名单**操作：确认后命中值直接落入黑名单管理，后续交易按黑名单拦截——围栏命中表达的是「位置不对」而非「人是黑的」，没有名单语义，不提供该动作。微信 OpenId 命中缺少应用归属信息时，需到黑名单管理手动补录。
## 风控预警
指标类预警的收件箱，预警类型：
| 预警类型 | 含义 |
| --- | --- |
| IP 未支付封禁 | 某 IP 短窗口内大量下单且无一成功，触发自动封禁 |
| 商户成功率预警 | 商户支付成功率跌破阈值 |
| 通道指标预警 | 通道维度的成功率等指标异常 |
列表展示预警目标、商户、通道、统计窗口、总单数/成功数/成功率、处置动作（仅预警 / 自动封禁等）与处理状态；点开详情看完整指标。唯一的处理动作是**标记处理**：填写处理备注（如已核实、已联系商户、误报忽略）后将该条置为已处理。运营端 APP 也有只读的预警页，适合随时盯盘。
## 命中后会发生什么
- 事前检查发生在**下单时**，普通支付、网关支付、码牌收款都覆盖；退款不经过事前风控；
- 命中且开启「命中阻断下单」：订单被拒绝、不建单，商户侧收到的统一是**「交易被限制」**的模糊提示（刻意不暴露命中细节，防止探测）；
- 命中但关闭阻断：交易照常，只在命中记录里留一条，适合上线观察期；
- 事后补录开启后，支付成功但命中用户标识名单的交易落入「事后命中」，可一键转黑阻断后续交易；
- 内网地址、解析失败的 IP 等无法判定的情况会放行，属预期行为。
## 常见问题
**商户反馈「交易被限制」怎么排查？**
按顺序查：风险命中记录里有没有该笔的命中 → 有则看阶段与命中类型 → 事前命中回黑名单管理核对是否误加（比如误加了整个省市）→ 事后命中核实用户标识是否确需拉黑。
**加了黑名单为什么没拦住？**
依次核对：风控总开关是否开启 → 对应分组开关（IP/用户标识→名单拦截；省/市→地域限制）是否开启 → 名单是否处于启用状态且未过期 → 微信 OpenId 名单的应用归属是否选对。
**预警太多看不过来怎么办？**
先在风控策略「指标检测」分组校准阈值（过低会误报成灾），再按预警类型分派：成功率类找商户核实，通道类查[通道回调记录](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md)与通道侧状态。
## 相关链接
- [风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md) — 概念与设计正典
- [风控策略与处置](https://doc.plus.daxpay.cn/plus/risk-control/policy.md) — 各防线机制详解
- [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/.md) — 限额兜底挂靠的三级限额
- [签名机制](https://doc.plus.daxpay.cn/api/signature.md) — 开放接口始终启用的签名校验
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md) — 系统域安全，与支付域分开
---
# 敏感词管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/sensitive-word.md
# 敏感词管理
> 敏感词体系拦截支付标题、商品名、商户名、进件名等业务文本中的违禁词。**菜单路径**：系统管理 → 敏感词管理。
>
> 三处能力各司其职：**平台配置**里的敏感词配置（总开关与策略）、**词库管理**（词表维护）、**命中记录**（审计追溯）。
## 过滤策略（总开关）
入口在[支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)的敏感词配置页签：
| 配置项 | 说明 |
| --- | --- |
| 启用敏感词过滤 | 总开关；关闭后全部文本校验放行 |
| 错误回显命中词 | 开启后报错文案会带出具体命中的词——**有被试探词库的风险**，默认关闭 |
| 记录命中审计 | 拦截时写入命中记录（默认开启），是命中记录页的数据来源 |
## 敏感词库
- **查询**：敏感词、分类、状态；
- **分类**：政治 / 色情 / 暴力 / 广告 / 自定义；
- **匹配模式**：**包含**（文本中出现即命中，常用）/ **精确**（整段完全一致才命中）；
- **新增 / 编辑**字段：敏感词（64 字内）、分类、匹配模式、状态、备注。
系统匹配前会自动做**繁转简**与全角转半角，因此词库录入**简体中文**即可覆盖繁体与全角变体，不需要重复录多份。
### 在线试检
列表上方的试检区：输入一段文本点「检测」，立即返回是否命中及命中词列表；勾选「写入命中记录」可让试检结果进入命中记录页（配合演练 / 验证审计链路）。上线新词库前建议先试检几个典型变体验证匹配效果。
## 校验场景
敏感词校验覆盖的文本点位（命中记录中的「场景」即来源于此）：
| 场景 | 说明 |
| --- | --- |
| 支付标题 / 支付描述 | 下单请求中的订单标题与描述 |
| 商品名称 / 商品描述 | 下单请求携带的商品信息 |
| 退款原因 | 发起退款时填写的原因 |
| 商户名称 / 应用名称 / 门店名称 | 商户开通与资料维护入口 |
| 用户名称 | 平台用户（含三端账号）的显示名 |
| 码牌名称 | 码牌模板与台账命名 |
| 公告 / 协议 | 通知公告与用户协议正文 |
| 代理商名称 | 代理商名称、简称与管理员姓名 |
| 收款单 | 收款单标题与备注说明 |
| 进件名称 | 进件申请单名称 |
| 邀请码名称 | 推广邀请码的名称 / 备注名 |
| 试检 / 通用 | 在线试检与兜底通用校验 |
商户反馈「提交时提示包含违禁词」，先问清提交的是哪类文本（退款？进件？收款单？），再到命中记录按场景过滤定位具体命中的词。
## 命中记录
被拦截的每一次都会留痕：
- **查询**：命中词、场景、来源、商户号；
- **列表**：命中词、原文摘要、场景、来源、客户端 IP、商户、命中时间；
- **详情**：完整原文摘要、商户 / 应用 / 操作人、IP、请求路径等追溯字段。
**场景**标注文本来自哪个业务（见上表）；**来源**标注从哪个端触发（运营端 / 代理商端 / 商户端 / 开放支付接口等）。
命中记录里的「支付标题 / 商品描述」类高频命中，多为商户正常经营用了误伤词——在词库中调整该词（改精确匹配或删除）比反复向商户解释更有效；真违规的可结合[风控黑名单](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)处置。
## 相关链接
- [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)：过滤策略总开关
- [支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)：命中后的拦截动作与黑名单
- [收款单](https://doc.plus.daxpay.cn/common/receivable-bill.md) / [进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md) / [邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)：校验点位对应的业务
---
# 存储配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md
# 存储配置
> 平台的文件（网站素材、对账单等）统一通过 S3 兼容协议存储，支持 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等 S3 兼容的对象存储。
> 配置入口：运营端 → 系统管理 → 系统配置 → 平台配置 → OSS 配置。
## 上传机制
平台使用「预签名直传」方式上传文件，分三步：
1. 运营端向后端申请一个预签名上传地址；
2. 浏览器拿地址**直接把文件传到对象存储**（文件不经过后端服务器）；
3. 后端确认文件存在后登记文件记录。
因此有一个必须提前完成的动作：**在存储桶上配置跨域(CORS)规则**，否则「测试连接」通过、真正上传时仍然失败。配置方法与排查见 [存储跨域(CORS)配置与上传排查](https://doc.plus.daxpay.cn/getting-started/faq/oss-cors.md)。
## 参数说明
| 参数 | 必填 | 说明 |
|-----|------|-----|
| 服务端点 | 是 | 存储服务的 API 地址，**必须带 `https://`，且不要带桶名** |
| 存储区域 | 视情况 | 见下方「存储区域要不要填」 |
| 访问密钥 / 私有密钥 | 是 | 存储服务的 AccessKey / SecretKey |
| 路径样式访问 | 是 | 地址风格开关，见下方说明 |
| 公开存储桶 / 私有存储桶 | 是 | 桶名，可以填同一个桶，见「单桶说明」 |
| 公开访问域名 | 建议 | 公开桶文件的对外访问地址，**必须以 `http://` 或 `https://` 开头**，填法随「URL 拼接方式」而定，见下方说明 |
| URL 拼接方式 | 建议 | 公开文件地址的拼接形态：桶级域名（缺省）/ 带桶名，见下方说明 |
| 基础存储路径 | 否 | 对象键的统一前缀，如 `daxpay` |
| 上传预签名URL有效期 | 否 | 上传地址的有效分钟数，默认 10 分钟 |
| 下载或查看预签名URL有效期 | 否 | 私有文件访问地址的有效小时数，默认 72 小时 |
### 存储区域要不要填
「存储区域」**只参与请求签名，不决定访问哪个数据中心**，真正决定访问地址的是「服务端点」。所以多数场景这个参数可以不填：
| 存储服务 | 是否需要填写 | 示例值 |
|---------|------------|--------|
| MinIO / 自建 S3 兼容存储 | **不需要**，留空即可 | — |
| 阿里云 OSS | 留空即可，报签名区域错误时填写 | `cn-beijing` |
| 华为云 OBS | 建议填写 | `cn-north-4` |
| 腾讯云 COS | **必须填写**（校验签名区域） | `ap-shanghai`、`ap-guangzhou` |
| AWS S3 | **必须填写** | `us-east-1`、`ap-northeast-1` |
| 七牛云 Kodo | **必须填写** | `cn-east-1` |
| Cloudflare R2 | 固定值 | `auto` |
留空时按 `us-east-1` 参与签名，MinIO 等不校验签名区域的存储完全不受影响。具体区域代码以各厂商的 S3 兼容文档为准。
### 路径样式访问
同一个桶有两种地址风格：
- **路径样式（开启）**：`https://服务端点/桶名/对象`（MinIO 等自建存储必须开启）
- **虚拟主机样式（关闭）**：`https://桶名.服务端点域名/对象`（云厂商的原生风格）
自建 MinIO 一律开启；云厂商多数两种都支持，参照下方实例中的推荐值即可。
### 关于公开访问域名与 URL 拼接方式
公开文件的最终地址由「公开访问域名 + URL 拼接方式」共同决定，两种拼接形态：
- **桶级域名（缺省）**：URL = `域名/对象键`。适用于域名直接绑定在桶上的形态，如 R2 桶级自定义域、给单个桶绑定的 CDN 域名。域名直接填桶级域名。
- **带桶名**：URL = `域名/桶名/对象键`。适用于一个根地址下多个桶共存的形态，如 MinIO、阿里云 OSS、腾讯云 COS 的原生域名。域名填根地址，桶名由系统自动拼接。
域名**必须以 `http://` 或 `https://` 开头**（配置页与后端都会校验拦截）：无协议前缀的地址在文件访问跳转时会被浏览器当作相对路径，公开文件将无法访问。
配置页会随表单值实时预览拼接出的完整地址，可直接核对形态是否选对；「测试连接」在公开访问探测 404 时会自动换另一种拼法重试，另一种能通时会直接提示切换拼接方式。
### 单桶说明
公开桶和私有桶可以填同一个桶名，此时桶的读写权限建议设为「公共读」：公开文件可以直接访问，私有文件通过预签名地址访问也正常。
代价是「私有」变为名义私有：拿到完整地址的任何人都能读取该文件。生产环境建议分建两个桶，让权限语义真实成立。
## 配置实例
实例中的端点地址、地域代码等取自各云平台官方文档。云厂商可能调整 S3 兼容端点形式与配置要求，实际填写时请以官方最新文档为准。
### 实例一：MinIO 自建
| 参数 | 值 |
|-----|---|
| 服务端点 | `https://minio.example.com`（MinIO 的 API 端口，不是控制台端口） |
| 存储区域 | 留空 |
| 路径样式访问 | 开启 |
| 公开访问域名 | `https://minio.example.com`（或该 MinIO 对外的公开访问域名） |
| URL 拼接方式 | **带桶名**（MinIO 多桶共用根地址，桶名由系统拼接） |
密钥为 MinIO 的 AccessKey / SecretKey（通过 `mc admin` 创建用户时生成）。
### 实例二：阿里云 OSS（以华北2北京为例）
| 参数 | 值 |
|-----|---|
| 服务端点 | `https://s3.oss-cn-beijing.aliyuncs.com`（S3 兼容端点，带 `s3.` 前缀，见下方「S3 兼容说明」） |
| 存储区域 | 留空；报签名区域错误时填 `cn-beijing` |
| 路径样式访问 | 开启 |
| 公开存储桶 / 私有存储桶 | 如 `daxpay-pub` / `daxpay-priv`（或填同一个桶名） |
| 公开访问域名 | `https://oss-cn-beijing.aliyuncs.com`（原生域名，不带 `s3.` 前缀） |
| URL 拼接方式 | **带桶名**（原生域名下多桶共根；若给桶单独绑定了自定义域名则改选桶级域名并填该域名） |
密钥为 RAM 用户的 AccessKey，最小权限需要两个桶上的 `PutObject`、`GetObject`、`DeleteObject`、`ListObjects`、`GetBucketInfo`。
注意：即使后端部署在阿里云 ECS 上，也**不要**把服务端点换成内网地址（`-internal` 结尾）。上传是浏览器直传，用户的浏览器访问不到内网地址。
### 实例三：腾讯云 COS（以上海为例）
| 参数 | 值 |
|-----|---|
| 服务端点 | `https://cos.ap-shanghai.myqcloud.com` |
| 存储区域 | `ap-shanghai`（必须填写） |
| 路径样式访问 | 关闭 |
| 公开访问域名 | `https://cos.ap-shanghai.myqcloud.com` |
| URL 拼接方式 | **带桶名**（原生域名多桶共根；默认 CDN 加速域名同理） |
密钥为腾讯云子账号的 SecretId / SecretKey。
### 实例四：Cloudflare R2（桶级自定义域）
| 参数 | 值 |
|-----|---|
| 服务端点 | `https://<账户ID>.r2.cloudflarestorage.com`（S3 兼容端点，账户 ID 在 R2 控制台概览页查看） |
| 存储区域 | `auto` |
| 路径样式访问 | 开启 |
| 公开访问域名 | `https://cdn.example.com`（在 R2 控制台绑定到桶的自定义域） |
| URL 拼接方式 | **桶级域名**（缺省），R2 自定义域直接指向桶，URL 不含桶名 |
密钥为 R2 的 AccessKey / SecretKey（对象存储 → 管理 API 令牌创建）。注意「桶级域名」正是为 R2 这类形态准备的：自定义域绑定在桶上，地址直接是 `域名/对象键`；**不要选「带桶名」**，否则地址多出桶段必然 404。若暂时没有自定义域，R2 也提供 `https://pub-<哈希>.r2.dev` 形式的公开访问域（需在桶设置中启用），同样按桶级域名填。
## S3 兼容说明
各家对象存储都有自己的原生接口，但 S3 协议是事实标准，主流厂商都提供兼容层。系统统一用 S3 协议对接所有存储，配置时要分清两个用途不同的地址：
- **API 端点（服务端点）**：系统向它发起 S3 请求（测试连接、生成上传地址）。多数厂商的原生地址本身就是 S3 兼容端点，直接填。
- **文件访问域名（公开访问域名）**：浏览器直接访问文件用的地址，与 API 端点无关，填厂商的原生域名或绑定的 CDN 域名。
### 阿里云 OSS 为什么要用 s3. 前缀端点
阿里云 OSS 是个例外：早期它靠原生地址「顺带」兼容 S3 协议，两边行为差异带来不少问题，例如新版 AWS SDK 上传时默认启用的校验与分块传输方式，OSS 的兼容层不支持，直接报错。阿里云后来上线了**专门的 S3 兼容端点**（`https://s3.oss-<地域>.aliyuncs.com`），官方文档目前推荐一律使用它，并把不带前缀的原生地址列为配置错误的典型例子。
两点实践中的坑已经内置处理，正常情况下不需要关心：
- 上述「SDK 默认校验与分块传输」已在上传链路中禁用，不会再触发 OSS 报错；
- 签名区域留空时按默认值参与签名，若「测试连接」报 `SignatureDoesNotMatch`（签名不匹配），在「存储区域」填入地域代码（如 `cn-beijing`）即可。
服务端点换成 `s3.` 前缀地址后，**公开访问域名仍然填原生地址**（如 `https://oss-cn-beijing.aliyuncs.com`）。前者是给系统发请求用的，后者是给浏览器访问文件用的，两者本就是不同的东西。
对比：腾讯云 COS 的地址（`cos.ap-xxx.myqcloud.com`）本身就是 S3 兼容端点，直接填即可，没有单独的前缀形式。
## 测试与排错
保存配置后点「测试连接」，系统会对两个桶各执行「桶存在 → 写入探测文件 → 读取 → 删除」的完整闭环，通过即说明读写权限就绪。测试用的是**表单当前值**（未保存的修改也即时参与探测），不必先保存。
常见报错对照：
| 现象 | 原因 | 处理 |
|-----|------|------|
| 测试通过，上传文件失败 | 存储桶未配置 CORS 跨域规则 | 配置方法与排查见 [FAQ - 存储跨域配置与上传排查](https://doc.plus.daxpay.cn/getting-started/faq/oss-cors.md) |
| 写入失败，请检查密钥是否具备上传权限 | 密钥缺少写权限 / 桶策略拒绝写入 / 桶开启了 KMS 加密但密钥无 KMS 权限 | 后端日志搜「探测写入失败」看真实状态码；给密钥临时挂完全权限二分定位 |
| 文件已上传但图片显示不出来 | 「URL 拼接方式」与域名形态不匹配（桶级域名选了带桶名 / 多桶共根域名选了桶级），或公开桶权限为私有 | 按域名形态切换拼接方式（测试连接会自动纠偏提示）；公开桶权限设为公共读 |
| 公开文件访问 302 后 404 | 公开访问域名缺 `http(s)://` 协议前缀，跳转被浏览器当作相对路径解析 | 域名补全协议前缀（配置页已强制校验，存量配置注意排查） |
| 上传成功但文件记录一直处理中 | 密钥能写不能读 | 补充读权限（GetObject） |
| 测试连接报 `SignatureDoesNotMatch` | 签名时使用的区域与存储要求的区域不一致 | 「存储区域」填地域代码，如 `cn-beijing` |
「系统文件列表里有一条记录」不代表上传成功：记录在申请上传地址时就会创建，文件真正可访问才算完成。
---
# 系统安全配置
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md
# 系统安全配置
> 系统安全配置管理**平台自身的访问安全**（登录、密码、注册、短信、会话），与支付业务的[支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)互不相关。**菜单路径**：系统管理 → 系统配置 → 系统安全配置。
>
> 页面左侧列出八个配置面板，右侧编辑保存；每个面板的标题下方常驻当前配置摘要标签，一眼看清现行策略。
## 密码策略
约束所有用户的密码复杂度与轮换：
| 配置项 | 说明 |
| --- | --- |
| 最小 / 最大长度 | 6~32 位，建议最小不少于 8 位 |
| 复杂度要求 | 大写字母、小写字母、数字、特殊字符可分别强制；勾选特殊字符后可自定义允许的字符集 |
| 轮换周期（天） | 密码有效期，**0 为永不过期**；修改后对所有用户下次登录生效 |
| 过期提醒天数 | 到期前 N 天在登录页与个人中心提醒 |
| 历史记录数 | 最近 N 次用过的密码不可重复，0 为不限制 |
新增用户 / 重置密码生成的随机密码也按此策略生成；密码到期后用户会被强制修改，见[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)的过期提示。
## 登录安全
针对**登录失败**的防护：
- **失败锁定**：连续失败达到阈值（1~10 次）后锁定账号一段时间（分钟级）；失败计数在统计窗口内没有新失败则清零；
- **验证码触发**：失败达到阈值（不大于锁定阈值）后，登录页要求先过验证码，挫败暴力尝试。
锁定产生与解除的记录见[日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)的「登录锁定」。
## 注册安全
控制**商户自助注册**（邀请码注册链路）的入口与防线：
- **开放商户自助注册**：总开关，关闭后所有通过推广邀请码发起的自助注册请求将被拒绝；
- **注册短信验证**：开启后商户注册须填写手机号并通过短信验证（注册即完成绑定，可用于短信找回）；图形验证码同步前移到获取短信验证码环节；开启前需已在[平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)中启用默认短信服务；
- **强制图形验证码**：注册提交必须携带有效的图形验证码；
- **IP 每日注册上限**：按注册提交次数计数（含失败尝试），防「换手机号灌注册」，超限后当日拒绝。
## 短信安全
验证码短信的**防刷阈值与日总量熔断**：
- **最小发送间隔**：同一手机号两次发码的最小间隔；
- **手机号每日上限**：单手机号每日最多接收条数；
- **IP 每日上限**：单 IP 每日最多触发次数；
- **平台每日总量熔断**：全平台（含运营端测试发送）每日验证码短信总量上限，达到后当日停发——保证最坏情况下短信费用损失封顶，触发熔断后请联系服务商核查异常流量。
## 会话管理
控制登录会话的时长与并发：
| 配置项 | 说明 |
| --- | --- |
| 最大在线时长 | 单次会话最长存续时间（小时） |
| 最大活跃时长 | 无操作多久后失效，0 为不限制 |
| 最大并发会话数 | 同一账号同时在线的会话数（1~10） |
| 并发计数范围 | **全局共享**（所有终端共用配额）或**按终端独立**（运营端、代理商端与商户端分开计数） |
| 并发超限策略 | 允许新会话 / 踢出最早会话 / 拒绝新会话 |
被踢出的会话可在[在线用户](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)页观察到「已下线」。
## 双因素认证（2FA）
- 开关启用后，用户可在[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)自行绑定 TOTP 动态口令（Google Authenticator 等认证器）；
- 可配置认证器中显示的**发行者名称**与**备用验证码数量**（10~20 个）；
- 平台未开启时用户侧不显示绑定入口；关闭后登录不再校验动态码。
## 通行密钥（Passkey）
允许用户用指纹 / 面容 / PIN 免密登录，绑定后登录**豁免两步验证**：
| 配置项 | 说明 |
| --- | --- |
| 站点域名 | 通行密钥绑定的纯域名（如 `admin.example.com`，本地调试用 `localhost`），**不带协议与端口** |
| 显示名称 | 系统弹窗中展示的站点名 |
| 访问地址 | 允许使用通行密钥的完整地址（协议 + 域名 + 端口），可填多个；多端同时启用时**各端地址都要加** |
站点域名变更会导致**已绑定的通行密钥全部失效**，用户需重新绑定；保存时系统会再次确认。通行密钥要求页面为 HTTPS（本地 `localhost` 除外）。
## 防重放校验
防止登录、注册、改密等敏感操作的请求报文被截获重放：
- **Nonce 有效期**（秒）：平台签发的一次性随机值的有效时长；
- **时间戳容差**（秒）：请求时间与服务器时间的最大允许偏差。
关闭后所有标记防重放的敏感接口将跳过校验。仅在排查对接问题或内网隔离环境临时关闭，验证完立即恢复。
## 相关链接
- [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)：用户侧的改密、2FA 绑定、通行密钥管理
- [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)：短信服务供应商配置
- [日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)：登录锁定、在线用户与登录日志
- [邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)：注册安全策略作用的邀请注册链路
---
# 第三方平台登录
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md
# 第三方平台登录
> 配置用第三方平台账号（企业微信、钉钉、飞书、支付宝、抖音等）登录本系统。**菜单路径**：系统管理 → 系统配置 → 三方平台管理。
>
> 平台清单由系统内置驱动，无需新增「平台」，只需为要用的平台填入凭据并启用。
## 登录方式与机制总览
登录页共有四类登录方式：账号密码、通行密钥（Passkey）、第三方平台登录、微信公众号扫码登录。前两类见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)，本文只讲后两类。
第三方平台登录内置 11 个平台，按**回调链路形态**分三类：
| 形态 | 平台 | 用户操作 | 回调链路 |
| --- | --- | --- | --- |
| 标准型（9 个） | 企业微信、钉钉、飞书、QQ、GitHub、Gitee、Google、微信开放平台、抖音 | 当前浏览器跳到平台授权页，授权后自动跳回 | 回调直接落回发起端（运营端 / 代理商端 / 商户端），无需网关参与 |
| 跳转型（2 个） | 支付宝、微信公众号 | 同上；微信内浏览器打开时微信公众号自动发起授权 | 回调统一落**支付网关域名**的透传路径，再自动跳回发起端（原因见下方提示框） |
| 扫码型 | 微信公众号（PC / 非微信浏览器） | 弹出二维码，手机微信扫码、在手机上确认授权 | 手机经网关域名完成授权，PC 轮询票据自动登录（见[下文专节](#公众号扫码登录与扫码绑定)） |
同一个「微信公众号」按打开环境自动分流：手机微信内打开 → 直接跳授权（跳转型）；PC 或其他浏览器 → 弹二维码扫码（扫码型）。
平台开启 2FA 且用户已绑定认证器时，上述所有三方登录方式（含扫码登录）在授权完成后都会再要求输入动态码（或备用码）才进入系统；唯一豁免是通行密钥，它本身已完成「持有设备 + 用户验证」。
## 页面结构（五个页签）
| 页签 | 内容 |
| --- | --- |
| 三方平台登录配置 | 各平台登录的**启用开关与 OAuth 凭据**（卡片墙） |
| 应用内自动登录 | 在飞书 / 企业微信 / 钉钉**内置浏览器**打开时自动登录 |
| 支付宝应用配置 | 支付宝 OAuth 凭据（登录 + 支付通道认证 + 实名核验共用） |
| 微信公众号配置 | 公众号凭据（网页授权登录 + 模板通知） |
| 抖音 H5 应用 | 抖音开放平台 H5 凭据 |
## 登录配置（卡片墙）
每个平台一张卡片，显示 Logo、名称与状态（已启用 / 已停用 / 未配置），点「配置」打开抽屉：
- **标准平台**（企业微信、钉钉、飞书、QQ、GitHub、Gitee、Google、微信开放平台、抖音）：填客户端 ID、客户端密钥；企业微信还需应用 ID；
- **跳转型平台**（支付宝、微信公众号）：凭据在专属页签维护，抽屉内提供「前往配置凭据」直达；
- 标准平台抽屉内展示各平台的**回调地址**：**运营端、代理商端、商户端各一组**（登录回调与绑定回调，共六条），复制到第三方平台的后台做授权配置——多端启用同一平台时三端的回调都要登记；
- **跳转型平台**抽屉内展示**开放平台登记指引**：登录与绑定回调统一经支付网关域名透传跳回各端，开放平台只需登记网关域名相关信息（支付宝登记「授权回调地址」，填带协议的网关完整地址（如 `https://gw.example.com`）并在同一页面开启域名级校验；微信公众号登记「网页授权域名」，填不带协议的纯域名）。
回调地址由[平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)的端点地址拼出，端点没配时抽屉会提示，先去补端点配置。多端登录场景下，运营端、代理商端、商户端三个访问地址都要配置，否则对应端的回调地址为空。跳转型平台额外要求配置**支付网关前端地址**（回调透传的入口）。
支付宝的授权回调地址与支付认证共用同一应用（同一 AppId），回调名额只有一份：登录回调若直接用运营端 / 代理商端 / 商户端自己的域名，会与支付回调互相顶替（启用登录后支付认证失败）。因此跳转型平台的登录与绑定回调统一落在支付网关域名的透传路径，由网关页自动跳回对应端，登录与支付互不影响。
密钥类字段保存时只提交发生变化的部分，未改动的密钥不会被覆盖。
## 平台级凭据
| 页签 | 字段 | 服务于 |
| --- | --- | --- |
| 支付宝应用 | AppId、鉴权方式（公钥 / 证书）、私钥与公钥或三张证书 | 三方登录的支付宝授权 + [支付调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md)中的支付宝 H5 认证 + 商户实名核验；须使用**网页应用（自用型）** |
| 微信公众号 | 公众号 AppId、AppSecret | 公众号网页授权登录 + 通知中心模板消息 |
| 抖音 H5 | Client Key、Client Secret | H5 场景授权（与三方登录里的「抖音」是两套独立凭据） |
## 公众号扫码登录与扫码绑定
微信公众号的网页授权只能在微信内浏览器完成，PC 上发起不了。因此 PC 上点「微信公众号」不是跳转授权，而是**弹二维码、手机扫码**的跨设备流程（登录与绑定同款机制）。二维码 5 分钟有效，过期可在弹窗内刷新。
### 扫码登录
1. 登录页点「微信公众号」→ 弹出二维码；
2. 手机微信扫码，手机上出现确认页，点「确认」后跳微信公众号授权（点「取消」则本次作废，PC 弹窗提示已取消）；
3. 授权完成后 PC 弹窗自动登录。扫码成功到授权完成之间，弹窗会显示「已扫码、等待手机操作」的中间状态。
- **未绑定的微信号不会自动注册账号**：手机端会提示先用账号密码登录，再到[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)绑定微信，防止陌生人扫别人的二维码直接建号；
- 开启 2FA 的用户，授权完成后会在 PC 弹窗内接着输入动态码。
### 扫码绑定
[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md) → 三方账号绑定 → 点「微信公众号」，同样弹二维码。手机扫码后的确认页会显示**即将绑定的账号（脱敏展示）**，核对是自己的账号再确认，防止把微信绑到别人的账号上；确认授权后 PC 端自动完成绑定。
登录二维码等同于一次待确认的登录，只扫自己发起的二维码；手机确认页展示的操作内容与目标账号，是核对「这一码到底在做什么」的唯一机会。
整条扫码链路的页面落在支付网关域名（复用公众号网页授权域名，公众号后台无需为新流程额外登记），页面构成见[收银台 - 认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md)。
## 应用内自动登录
用户在**飞书 / 企业微信 / 钉钉客户端内置浏览器**里打开运营端、代理商端或商户端时，按 UA 自动匹配已启用平台发起 OAuth 登录：
- 按端（运营端 / 代理商端 / 商户端）分别开关，各选至少一个自动登录平台；
- 候选平台必须是「登录配置里已启用」的飞书 / 企微 / 钉钉；
- **用户须先绑定过该平台账号**，未绑定的会静默回到账密登录页；钉钉首次授权需确认一次。
## 相关链接
- [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)：用户侧绑定 / 解绑三方账号（微信公众号为扫码绑定）
- [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)：端点地址（回调地址的前置）
- [收银台 - 认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md)：扫码登录 / 绑定与透传在网关侧的页面
- [开发调试 - 认证调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md)：OAuth 链路验证
---
# 用户管理
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md
# 用户管理
> 用户管理用于维护系统的登录账号。**菜单路径**：系统管理 → 权限管理 → 用户管理。
>
> 这里统一管理**运营端、代理商端、商户端**三类终端的账号；商户与代理商用户的运营侧代管入口分别在[商户工作台](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)与[代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)，账号本身也可在本页切换对应 Tab 直接查到并处置（封禁、重置密码等）。
## 页面结构
列表顶部按**终端**分 Tab（运营端 / 代理商端 / 商户端，按终端主数据动态生成），默认展示运营端。各 Tab 页面能力一致，本文以运营端为例。
- **查询条件**：姓名、账号、状态（正常 / 锁定 / 封禁）、邮箱；
- **列表列**：名称、身份、账号、手机号、邮箱、状态、密码到期时间、初始密码标记、创建时间。
**身份列**显示该账号的身份：内置超管显示金色标签，普通用户显示蓝色**角色**标签（该账号被分配的角色名），一眼区分平台超管与普通运营、代理商、商户账号。
其中「初始密码」标记为橙色的账号还未修改过管理员设置/生成的密码，首次登录时会被强制修改。
## 新增用户
操作：工具栏「新增」。表单字段：
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 名称 | 是 | 3~15 个字符 |
| 账号 | 是 | 6~20 位，仅字母、数字、`_`、`-`，输入时实时查重 |
| 密码 / 确认密码 | 否 | **留空时按密码策略自动生成随机初始密码**；填写则需两次一致 |
保存成功后弹窗切换为结果态，展示**账号与初始密码明文**（可一键复制）——初始密码只显示这一次，请立即转告使用者。
## 角色分配
操作：行「更多 → 分配角色」。当前为**单角色**模式：弹窗以单选卡片列出可分配的角色，选中保存即生效。
角色决定了该账号登录后能看到的菜单与可执行的操作；新建与调整角色、给角色分配菜单与权限码见[权限与菜单管理](https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md)。
## 编辑与详情
- **编辑**：只能改姓名；账号不可改，**邮箱只读**（变更需用户本人在[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)走验证流程）。若用户邮箱已失效无法自助解绑，管理员可用编辑页的「强制解绑邮箱」清空（代管通道，谨慎使用）；
- **查看**：详情抽屉含角色、最后登录时间与 IP、登录次数、密码到期时间、是否初始密码等；
- **三方绑定**（更多 → 三方绑定）：查看该用户绑定的第三方平台账号，管理员**只能解绑不能代绑**。
## 批量操作
勾选多行后从工具栏「批量操作」执行：**批量封禁 / 批量解锁 / 批量重置密码**（未勾选时禁用）。批量重置密码的结果为表格清单，可「复制全部」分发。
系统内置超管不可编辑、不可分配角色、不可封禁；列表身份列显示金色「内置超管」。日常运营账号建议单独建角色分配，不要共用超管。
## 重置密码
操作：行「更多 → 重置密码」，也可勾选多行后批量重置。
- 重置**不接受指定新密码**：系统按密码策略随机生成，结果页一次性展示明文（批量时为表格，可「复制全部」）；
- 重置成功后该用户的**全部登录会话立即下线**，需要用新密码重新登录；
- 重置出的密码记为初始密码，用户下次登录时会被要求先修改密码。
## 账号状态与锁定
系统存在两套「锁」，排查登录问题时先分清是哪一套：
| 机制 | 触发方式 | 查看位置 | 解除方式 |
| --- | --- | --- | --- |
| **账号状态**（正常 / 锁定 / 封禁） | 管理员手动设置 | 用户管理列表「状态」列 | 行「更多 → 解锁」恢复正常 |
| **登录失败锁定** | 密码连续错误达到阈值后自动锁定一段时间（阈值与时长的开关见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)） | 系统管理 → 系统监控 → 锁定用户（含失败次数、剩余锁定时间） | 到期自动解锁，或在「锁定用户」页手动解锁（同时清零失败计数） |
「解锁」操作会同时清除以上两种锁；「封禁」则是明确拒绝登录，需人工恢复。
商户端或代理商端账号无法登录时，除了账号本身的锁，还可能是**所属商户或代理商被禁用**（主体被禁用时其名下账号都不能登录，见[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)与[代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)）。
## 相关链接
- [运营端使用入门](https://doc.plus.daxpay.cn/operation-guide/admin/overview.md)：功能地图
- [权限与菜单管理](https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md)：角色、菜单与权限码维护
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md) / [代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)：商户与代理商侧账号的代管入口
- [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)：用户自助操作（改密、绑定邮箱与手机号）
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：密码策略与登录锁定阈值
---
# 用户协议
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/user-protocol.md
# 用户协议
> 维护登录页与协议页展示的《用户协议》《隐私政策》等文本，支持**多语言、多版本**。**菜单路径**：系统管理 → 基础数据 → 用户协议。
>
> 协议内容未配置时，协议页显示空态，登录不受影响；要合规上线就先把两个协议的当前语言版本发布好。
## 两级结构
**协议（定义）→ 版本（内容）**：
**协议**的字段：名称、显示名称、协议类型（用户协议 / 隐私政策等）、端类型（面向哪个端展示）、默认语言、是否默认协议。
协议级操作：
| 操作 | 说明 |
| --- | --- |
| 设为 / 取消默认 | 同类型多协议时，对外展示的是**默认协议** |
| 复制到其他端 | 连同各语言当前生效版本一起复制到目标端（运营端、代理商端与商户端各自维护一份时用） |
| 删除 | 连同全部版本删除，需确认 |
**版本**挂在协议下，按**语言**维度各维护一条版本线。列表列：版本号、版本标签、标题、语言、状态、生效时间、变更说明。
## 版本状态机
```
草稿 ──发布──> 已发布 ──归档──> 已归档
│ │
└──删除 └──复制为草稿 / 归档
```
- **发布**：草稿发布后对外生效；**同语言原已发布版本自动归档**——每个协议每种语言永远只有一个生效版本；
- **新建草稿自动继承**：默认载入同语言上一版正文，改完发布即为新版本，无需从头写；
- **切换语言**：草稿未改动时自动载入目标语言的上一版；已改动会先确认再覆盖；
- 编辑中的正文关闭前有未保存提醒，防手滑丢稿。
协议条款变更留有完整历史（何时发布、变更说明是什么），合规审计时可直接引用。
## 用户侧如何看到
- **登录页**：底部「我已阅读并同意《用户协议》《隐私政策》」勾选，链接打开协议页；勾选状态记住在本机，下次登录免勾；
- **协议页**：展示该语言当前**已发布**版本（标题、正文、版本标签、生效时间）；
- **新版本发布后**：已勾选过的用户不会被强制重新确认——需要强制用户重新同意时，配合公告告知并让用户自行查看。
## 相关链接
- [通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)：新协议版本上线的告知渠道
- [运营端使用入门](https://doc.plus.daxpay.cn/operation-guide/admin/overview.md)：系统管理分区总览
---
# 运营工作台
**源**: https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md
# 运营工作台
> 工作台是登录运营端后看到的第一个页面，聚合了**配置待办提醒**、核心运营统计和日常高频入口。**菜单路径**：仪表板 → 工作台。
>
> 它只做「速览与跳转」，各项数据的完整查询与处置在对应的业务页面完成。
## 页面构成
| 区块 | 内容 |
| --- | --- |
| 配置告警横条 | 系统检测到的未完成配置项，可点击直达处理（无待办时不显示） |
| 工作台头部 | 问候语、当前登录用户、四项核心统计（商户总数 / 通道商户 / 代理商 / 用户总数） |
| 快捷入口 | 可自定义的高频功能入口卡片 |
| 交易概览 | 今日 / 昨日的成交金额、成交笔数、退款金额、退款笔数 |
| 资金交易 | 最近交易明细，点「更多」跳转[支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)列表 |
| 系统公告 | 最新公告与个人消息，点击查看 |
| 支付渠道分布 | 近 7 天 / 30 天各支付渠道的成交金额占比（环形图） |
| 交易趋势 | 近 7 天 / 30 天成交金额走势（折线图） |
## 配置告警横条
新系统刚部署或配置不全时，工作台顶部会出现「您有 N 项配置待完成」的提示条，点击展开详情列表。每一条都标注了类别与待办数量，点击条目**直接跳转到对应的配置页**处理。
覆盖的检测类别包括：站点信息、平台访问地址、对象存储、社交登录、商户应用、API 凭证、通道商户、支付路由、通知配置。
告警条只是提醒入口，处理完对应配置后刷新页面即自动消失。点提示条上的关闭只是**当次会话不再显示**，重新登录后会再次出现——建议按列表逐项处理而不是关闭它。
## 快捷入口
默认展示九个常用入口：商户管理、通道商户、通知中心、用户管理、字典管理、登录日志、安全管理、进件申请、代理商管理。
点区块右上角的「编辑」可以自定义：
- **已选区**：拖拽调整顺序，可移除；
- **可选区**：从目录中追加，包括支付订单、退款订单、资金交易、角色管理、菜单管理、操作日志、通知公告、支付和进件产品、平台配置、在线用户、分析页、支付调试、三方平台登录等。
保存后入口按你的顺序展示；无权限的入口会自动隐藏，其他登录账号不受影响（快捷入口是每个账号各自的配置）。
## 交易与公告区块
- **交易概览**按「今日 / 昨日」切换，金额与笔数一目了然，适合每天开工先扫一眼；
- **资金交易**列出最近的交易流水（含资金状态标签），异常资金状态可从这里点进列表追查；
- **系统公告**展示平台发布的公告，**点击阅读后自动标记已读**，顶栏铃铛的未读数同步减少；公告的发布与管理见[通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)。
## 常见问题
**告警条点关闭后，下次登录又出现了？**
关闭只是当次会话不再显示，配置项本身未处理时告警会一直回来。按详情列表逐项处理完，刷新后告警条自然消失。
**我自定义的快捷入口，其他账号能看到吗？**
不能。快捷入口是每个账号各自的配置，保存只影响自己；无权限的入口会自动隐藏。
**头部统计与实际商户数对不上？**
头部统计为聚合口径（通道商户含进件申请生成的绑定），与各管理页列表的筛选口径可能不同，以对应管理页列表为准。
## 相关链接
- [数据分析](https://doc.plus.daxpay.cn/operation-guide/admin/analytics.md)：多维度的交易分析报表
- [通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)：公告的发布与通知中心
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：配置告警各项对应的配置主线
---
# 推广邀请码
**源**: https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md
# 推广邀请码
> 「商户管理 → 推广邀请码」是代理商的**商户拓展**工具：生成邀请码，把推广链接发给潜在商户，商户自助注册后自动挂靠到你名下。页面分**邀请码**与**注册记录**两个页签。
## 邀请码管理
「邀请码」页签维护你的推广载体：
- **生成邀请码**：填写名称（备注）、**有效期**（留空 = 永久有效）与**使用次数上限**（留空 = 不限次），可按推广活动批次建多个码分开投放；
- **编辑**：修改名称、有效期与次数上限；
- **启用 / 停用**：停用即撤销推广，未完成的注册不能再使用该码；停用不影响已注册商户；
- 列表展示每个码的**已注册 / 上限**计数与有效期，点击邀请码可复制。
一个码可以给多个商户用（在次数上限内）；按渠道 / 活动分码建，方便在注册记录里对照推广效果。
## 注册记录
「注册记录」页签是你的**推广成果台账**，每条记录展示：使用的邀请码、注册商户号与名称、注册手机号、**注册来源 IP**（快照留证）与注册时间。
注册记录是只读的：商户档案的后续维护在[名下商户](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)，注册链路本身无需你做任何确认动作。
## 邀请注册链路
```mermaid
flowchart LR
A[你生成邀请码] --> B[推广链接发给商户]
B --> C[商户打开注册页
手机号+验证码]
C --> D[自动挂靠到你名下
自动创建管理员与应用/门店]
D --> E[默认停用
待平台开通后交易]
```
- 推广链接 = **H5 收银台地址 + 邀请码参数**，注册页基地址由平台配置；若平台未配置推广地址，页面上会提示，联系平台运营开通；
- 商户注册成功即**自动初始化**（管理员账号、默认应用与门店、注册 IP 快照），无需人工建户；
- 新注册商户**默认停用**，需平台开通后方可使用——这是平台的管控点，你在名下商户列表看到停用状态属正常流程；
- 整个邀请注册体系（含平台直营邀请码的另一条线）的机制说明见[推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)。
## 常见问题
- **商户说打不开注册页？** 先确认邀请码处于启用状态且未过期、未超次数；其次可能是平台未配置推广基地址或未开放注册开关，联系平台运营确认。
- **想让某个码以后不再被使用？** 直接停用即可，已通过它注册的商户不受影响。
- **注册记录里的 IP 有什么用？** 注册来源 IP 是平台留存的风控快照，用于异常注册的溯源核对。
## 相关链接
- [推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)：邀请码体系与注册链路的机制说明
- [名下商户与代建](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)：注册成果的后续管理
- [邀请注册管理（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)：平台侧的两线邀请码管理
---
# 名下商户与代建
**源**: https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md
# 名下商户与代建
> 「商户管理 → 名下商户」是代理商端商户域的首页：查名下商户、替商户代建账号、进入功能开关代配。商户的归属模型（挂靠 / 调拨 / 层级权限）见[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)。
## 名下商户列表
**菜单路径**：商户管理 → 名下商户。按**商户名称（模糊）**与**商户状态**筛选，列表展示商户号、名称 / 简称、主体类型、状态与创建时间。
- 可见范围 = **本代理商名下**商户（含名下二级代理商的商户）；商户被平台调拨出去后自动从列表消失；
- 列表为只读档案视图：商户的资料修改、进件、通道配置等由商户在商户端自助或由平台运营处理；
- 每行提供**功能开关**操作，跳转该商户的能力代配页（见下文）；
- 新通过[邀请码](https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md)注册的商户为**停用**状态，需平台开通后方可交易——列表中看到停用记录属正常流程。
## 代建商户
**菜单路径**：商户管理 → 名下商户 → 代建商户。替不会自助注册的商户**直接创建账号**，创建后商户归属本代理商：
| 字段 | 说明 |
| --- | --- |
| 管理员登录账号 | 商户端登录用，商户终端内唯一 |
| 管理员名称 / 手机号 | 手机号选填，默认作为门店联系电话 |
| 初始密码 | 选填；**留空由系统生成随机密码**，创建成功后在结果中**一次性**展示明文 |
| 商户名称 / 简称 | 对外展示名 |
| 主体类型 | 小微商户 / 个体工商户 / 企业 |
留空生成的初始密码仅在创建成功的返回中展示一次，请当场转交商户并提醒其首次登录后修改密码。
代建入口受运营端能力开关「**代建商户**」管辖：开关关闭时入口隐藏、接口拦截，需要开放时联系平台运营方。
## 商户功能开关代配
**菜单路径**：名下商户列表 → 行内「功能开关」。对名下商户可用的功能项做代管配置，规则是**只能收紧、不能放开**：
- 每项展示**平台意图值**（运营端设定的上限）与**当前生效值**；已被你收紧的项带「已收紧」标记；
- 平台已关闭的项**不可代开**（置灰不可操作）；你只能把平台开放的能力**收紧**，撤销收紧后恢复到平台意图值；
- 平台专属档的能力不会出现在代理商端视角，可见即可代管的都属可代管范围；
- **生效节奏**：保存后接口层立即拦截；商户端的菜单入口要等商户**重新登录**后才刷新消失；
- 越过平台意图的放开操作会被显式拒绝。
代配入口受能力开关「**代管商户配置**」管辖，关闭时列表行的「功能开关」按钮隐藏。
## 常见问题
- **代建的商户能马上交易吗？** 不能。商户创建后还需平台侧开通（进件、通道配置等）方可收款，进度可与平台运营确认。
- **误关了商户某个功能怎么恢复？** 回到该商户的功能开关页，把该项撤销收紧即恢复到平台意图值（前提是平台本身未关闭该项）。
- **列表里找不到某个商户了？** 多半是平台做了归属调拨（划给其他代理商或收回直营），可在操作记录中追溯，或与平台运营确认。
## 相关链接
- [代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)：挂靠、调拨与层级权限的完整模型
- [推广邀请码](https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md)：商户自助注册的拓展方式
- [代理商管理（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)：平台侧的代理商能力开关配置
---
# 订单查询与码牌
**源**: https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md
# 订单查询与码牌
> 代理商端有两类「跨商户」工具：**订单查询**（名下商户支付 / 退款订单的只读视图）与**码牌管理**（代理商库存码牌的分发台账）。码牌的业务模型见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)。
## 订单查询
**菜单路径**：订单查询 → 支付订单 / 退款订单。
| 页面 | 筛选条件 | 列表要点 |
| --- | --- | --- |
| 支付订单 | 资金交易号（模糊）、支付通道、订单状态、创建时间区间 | 交易号、标题、通道 / 方式、金额、状态、**商户号 / 商户名称**、支付时间 |
| 退款订单 | 退款号（模糊）、支付通道、退款状态、创建时间区间 | 退款号、关联交易号、金额、状态、退款原因、**商户号 / 商户名称**、完成时间 |
- **跨商户视角**：列表覆盖你名下全部商户（含名下二级代理商的商户），靠「商户号 / 商户名称」列区分归属；商户归属调拨后数据实时跟随切换；
- **只读**：查询、导出核对可以，不能发起退款、关单等任何交易动作——操作类动作由商户在商户端或平台在运营端执行；
- 金额在页面上按元展示（接口层单位为分，展示层已换算）。
## 码牌管理
**菜单路径**：商户管理 → 码牌管理。管理**你持有的库存码牌**：筛选维度覆盖码牌编码 / 名称 / 批次号、绑定商户（可筛「未绑定商户」）、门店、落地程序类型（H5 / 小程序）、归属类别（平台级 / 商户级）、金额类型（随机 / 固定）与状态。
先建立一个关键概念——**库存态**：未绑定商户的**平台级**码牌。只有库存态的牌才能参与分发；已绑定商户或商户级的牌不属于你的可操作库存。
### 分发操作
| 操作 | 适用 | 说明 |
| --- | --- | --- |
| 绑定商户 | 库存态平台级牌 | 批量绑定到名下商户（含本人与名下启用二级的商户），可选指定应用；绑定后扫码即走该商户 |
| 解绑商户 | 已绑定商户的平台级牌 | 行内解绑，解绑后回到空白库存可再分发 |
| 分拨给二级 | 库存态平台级牌 | **仅一级代理商可见**：批量分拨给名下二级代理商作为其库存 |
| 从二级收回 | 二级持有的未绑定库存牌 | 批量收回已分拨给名下二级、尚未绑定商户的牌 |
| 启用 / 停用 | 名下持有的牌 | 停用后扫码不受理 |
| 复制扫码链接 | 名下持有的牌 | 获取完整落地地址，用于线上投放核验 |
批量操作不前置拦截：勾选中不满足条件的牌（商户级、已绑定商户等）会在确认弹窗中**点名跳过**，只处理合法部分。
商户级码牌固定归属其商户（编码含商户号中缀），不参与绑定 / 解绑 / 分拨任何流程；同样，平台把牌划拨给其他代理商后，该牌自动离开你的列表。未分拨给任何代理商的牌显示为「未划拨」。
## 常见问题
- **绑定商户时下拉里没有目标商户？** 下拉只列本人与名下**启用状态**二级代理商的商户，先确认商户已开通且状态正常。
- **为什么「分拨给二级」按钮不见了？** 该入口仅一级代理商可见；二级代理商登录时本身没有可分拨对象。
- **牌绑定商户后商户那边能看到吗？** 能。绑定后牌出现在该商户的码牌管理里，商户可启停与查看二维码详情。
- **想查某张牌今天的收款？** 码牌页只管台账；按商户 + 时间到订单查询页筛选对应商户的支付订单核对。
## 相关链接
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)：码牌两类模型、归属调拨与打印
- [名下商户与代建](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)：码牌分发对象的管理
- [码牌管理（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md)：平台侧的制牌与全局台账
---
# 代理商端使用入门
**源**: https://doc.plus.daxpay.cn/operation-guide/agent/overview.md
# 代理商端使用入门
> 代理商端是商业版**独有**的管理入口，面向平台的**渠道拓展方（代理商）**：你负责拓展和服务名下商户，平台负责通道与基础设施。本文给出功能地图与使用边界，具体操作见各分页。
## 定位
代理商是平台与商户之间的渠道角色：平台把商户**挂靠**到你名下，你负责拓展（邀请注册、代建）、日常服务（码牌分发、订单查询）与受限的配置代管。代理商体系的完整模型（三档定位、层级与归属调拨）见[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)。
代理商端**没有**通道配置、费率定价、进件审核等平台级操作——这些始终在运营端；代理商做的是「名下商户」视角的拓展、查询与受限代管。
## 功能分区
| 分区 | 页面 | 用途 |
| --- | --- | --- |
| 仪表板 | 工作台 | 今日 / 本月交易额与笔数四张统计卡，操作记录入口 |
| 仪表板 | 操作记录 | 名下商户与自身相关操作的历史记录（业务操作日志） |
| 订单查询 | 支付订单 | 名下商户支付订单查询（只读） |
| 订单查询 | 退款订单 | 名下商户退款订单查询（只读） |
| 商户管理 | 名下商户 | 名下商户列表，进入功能开关代配 |
| 商户管理 | 代建商户 | 替商户创建账号，创建后归属本代理商 |
| 商户管理 | 商户功能开关 | 对名下商户的能力做**单向收紧**代配 |
| 商户管理 | 推广邀请码 | 生成与管理邀请码，查看注册记录 |
| 商户管理 | 码牌管理 | 代理商库存码牌的绑定与分发 |
## 账号体系
- 代理商账号（管理员与普通用户）由**平台运营方在运营端创建**，并按角色授予代理商端菜单与权限；代理商自身无法注册或新建代理商；
- 登录后可在**个人中心**维护账号安全：修改密码、绑定邮箱与手机、两步验证（TOTP）、Passkey 等，与运营端同款能力；
- 代理商可用的功能面受运营端**能力开关（牌照）**控制：开关关闭的菜单入口直接隐藏，对应接口同时拦截。
## 与运营端、商户端的关系
```mermaid
flowchart TB
OP[运营端
平台方] -->|创建代理商、配置能力开关| AG[代理商端
渠道拓展方]
OP -->|创建商户 / 归属调拨 / 进件| MCH[商户端
商户自助]
AG -->|邀请注册、代建、码牌分发| MCH
```
- **运营端**：平台自留面。创建与管理代理商档案、决定代理商可用能力、执行商户归属调拨与进件审核；
- **代理商端**：渠道拓展面。把商户拓展到名下（邀请码 / 代建），并做只读查询与受限代管；
- **商户端**：商户自助面。商户自己配置应用、通道商户与查单交易；代理商对其可见但不可代操作交易。
## 数据边界
- 所有查询**限定名下商户**（含名下二级代理商的商户），登录态强制，无跨代理商数据；
- 商户发生**归属调拨**（划给其他代理商或收回直营）后，相关数据从你的视图实时移出，调拨历史在操作记录中可追溯；
- 订单查询为**只读**：可查、可导出核对，不能发起或变更任何交易动作。
## 相关链接
- [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)：三档定位与体系模型
- [名下商户与代建](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md) / [推广邀请码](https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md) / [订单查询与码牌](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md)：分页操作说明
- [代理商管理（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)：平台侧如何管理代理商
---
# 应用与对接配置
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/app-config.md
# 应用与对接配置
> 应用(AppId)是商户对接开放接口的身份单元。手机上可完成应用管理、密钥配置、网关支付配置、收银台配置、路由与易支付——商户详情宫格的「业务配置」与「支付配置」两组的配置类入口都归这里。
## 应用管理
- **列表**:应用名称、默认应用标记、AppId、状态;未设默认应用时有警示条;
- **编辑**:名称、状态、是否默认应用(停用默认应用需二次确认);
- **应用管理宫格**(进入某应用后):通道路由、网关支付配置、收银台配置、异步通知配置、易支付协议配置,另可编辑、设 / 取消默认、删除(默认应用禁删,删除强确认需输入应用名)。
## 密钥配置
对接开放接口的三件套:
| 密钥 | 说明 | 操作 |
| --- | --- | --- |
| 平台公钥 | 验签平台下发报文用 | 只读,可复制 |
| 商户公钥 | 供平台验签商户请求 | 可一键生成 RSA 密钥对 |
| 通信密钥 | 接口报文加解密 | 可一键生成 AES 密钥 |
生成的**私钥只在弹窗里展示一次**,立即复制并妥善保存;保存前有二次确认。
## 网关支付配置
收银台 / 聚合码 / 码牌三类收款场景的支付方式分发,三种模式按 4 渠道(微信 / 支付宝 / 云闪付 / 抖音)× 2 形态(H5 / 小程序)逐格配置:
- **AUTO 自动**:只读展示系统默认的支付方式,零配置;
- **METHOD 按方式**:每格指定一个支付方式(如「微信 JSAPI」);
- **DIRECT 直连**:每格指定「通道商户 + 支付能力」组合(必须成对,至少配一行)——适合一个商户多家通道分流。
## 收银台配置
统一收银台顾客看到的支付方式列表:按 **H5 / Web / 小程序**三类收银台分别配置,H5 与小程序再细分打开环境(浏览器 / 微信 / 支付宝 / 云闪付 / 抖音)。每行配置:名称、排序、解析模式(按支付方式或按通道商户 + 能力)、是否推荐。顾客端「推荐」标签与置顶逻辑就来自这里。
## 异步通知配置
应用级事件订阅:勾选关注的业务事件(支付、退款等),平台将通知发布到按应用隔离的消息 Topic,商户系统用持久订阅消费(离线不丢消息)。适合走消息队列对接的商户系统。
## 通道路由
按渠道维度指定默认通道商户,两种模式:
- **基础**:微信 / 支付宝 / 云闪付 / 抖音各选一个通道商户;
- **场景**:按「渠道 + 支付方式」组合逐行配通道商户 + 支付能力,更细的分流控制。
## 易支付协议
兼容易支付(Epay)协议的对接配置:启用总开关;接入信息(商户号、V1 / V2 接口地址)只读可复制;V1 配 MD5 密钥,V2 可选平台托管密钥(只读展示平台公钥)或自管 RSA 公钥。
## 微信域名校验文件(商户级)
微信域名归属验证的文件托管:上传时文件名必须符合 `MP_verify_XXX.txt` 格式(微信官方下发格式),内容粘贴文件全文,放置位置按验证用途选择(网页授权域名、JS 接口域名、小程序业务域名等微信要求置于域名根目录)。列表可查看 / 编辑备注 / 删除。平台级托管的校验文件在 Web 端维护。
## 相关链接
- [应用配置(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md):Web 端详解
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md):三类收款场景的业务链路
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 通道商户
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/channel-merchant.md
# 通道商户
> 通道商户是商户在微信 / 支付宝 / 抖音侧的收款账号。手机上支持五个产品(微信直连 / 微信服务商 / 支付宝直连 / 支付宝服务商 / 抖音)的完整操作;其余产品在手机上创建入口会提示到电脑端处理。
## 列表
从商户详情宫格进入时,展示该商户名下全部通道商户;工作台的「通道商户」入口则进入**全局列表**(跨商户),可按商户号、通道商户号、环境(生产 / 沙箱)筛选。
卡片:通道图标 + 产品名、启停状态、通道商户号、通道商户名称。
## 创建(向导)
1. **选产品**:从支持的五个产品中选一个;
2. **填通道信息**:通用填通道商户名称,再按产品填对应账号——
- 支付宝服务商:服务商应用 AppId + 支付宝用户号(授权令牌可暂不填)
- 支付宝直连:支付宝用户号
- 微信服务商:特约商户号
- 微信直连:微信商户号
- 抖音:抖音商户号
提交成功后进入详情。不在此列的产品(云闪付、乐刷等)在手机上显示「请到 PC 端创建」。
## 详情
按产品与权限自动过滤入口:
| 入口 | 说明 |
| --- | --- |
| 基本信息 | 只读子页:通道商户号、名称、产品、通道账号、来源与创建时间 |
| 分账接收方 | 见下文,全产品可用 |
| 授权令牌 | 仅支付宝服务商,见下文 |
| 启用 / 禁用、删除 | 删除为强确认,需输入通道商户名称 |
通道商户的密钥等敏感凭证配置在手机上不提供入口,请到 Web 运营端[通道配置](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)操作。
## 授权令牌(支付宝服务商)
服务商模式需要子商户的授权令牌才能代其发起交易,两种获取方式:
- **手动粘贴**:在支付宝后台拿到令牌后粘贴更新,二次确认后立即生效;
- **代运营授权链接**(推荐):生成授权链接发给子商户,对方在浏览器里打开(落在 H5 收银台的[代运营授权页](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md))并确认后,令牌**自动更新**——不用再手工传递。
页面展示当前令牌状态(已配置 / 未配置、尾 4 位掩码、所属服务商应用与支付宝用户号)。
## 分账接收方
管理分账资金的接收方(分给谁、分多少在[分账订单](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md#分账订单)侧控制)。
- **列表**:别名(优先显示)/ 接收方名称、状态(已绑定 / 已解绑 / 绑定失败)、类型、账号、失败原因;
- **详情**:完整档案(类型、账号、关系类型、绑定的应用、绑定 / 解绑时间)。操作按状态:已绑定 → 仅**解绑**;绑定失败或已解绑 → **重新绑定** + 删除;别名在详情里修改;
- **新增并绑定**:选接收方类型(按产品提供商户号 / 个人 openid 等选项)→ 填账号与名称 → 选绑定应用 → 提交后立即向通道发起绑定。
个人类型的接收方(openid 类)账号难复制?新增时可用**扫码授权**:生成二维码让对方扫码确认,页面自动查询结果,对方确认后账号自动回填——省去手抄 openid。
## 常见问题
**为什么手机上创建不了云闪付通道商户?**
APP 只实装了微信 / 支付宝 / 抖音五个高频产品的创建向导,其余产品请到 Web 端操作,配置语义完全一致。
**授权令牌过期了怎么办?**
重新走代运营授权链接流程,子商户确认后令牌自动更新;期间该子商户的代发起交易会失败。
## 相关链接
- [交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md):分账单查询与明细
- [通道配置(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md):通道配置详解
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 登录与账号安全
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md
# 登录与账号安全
> 运营端 APP 与 Web 运营端共用同一套账号:一边改密码、绑邮箱、开关双因素认证,另一边立即生效。本文讲手机上的登录链路与个人设置。
## 登录
1. 输入账号与密码(密码加密传输),首次登录需勾选用户协议与隐私政策(勾选结果会记住,下次不用再勾);
2. 连续失败达到阈值后,会出现**图形验证码**,输入正确才能继续尝试——防撞库;
3. 开启了双因素认证的账号,密码通过后再输入 **TOTP 动态码**或**备用码**完成第二步验证;
4. 登录页右上角可切换浅色 / 深色外观;页面品牌信息跟随站点的系统名配置。
**强制改密**:账号处于初始密码或密码已过期状态时,登录后会被直接带去修改密码页,改完才能进入系统。
**忘记密码**:登录页进入找回流程,两步完成——①输入账号、绑定邮箱与图形验证码,系统发验证码到邮箱;②输入邮箱验证码与新密码完成重置。前提是账号已绑定邮箱且邮件服务已配置,否则无法提交。
## 「我的」页面
### 账户与安全
| 设置项 | 说明 |
| --- | --- |
| 个人资料 | 头像、昵称等基本信息 |
| 修改密码 | 校验旧密码后设置新密码,符合密码策略 |
| 邮箱管理 | 绑定、换绑、解绑邮箱——忘记密码自助找回依赖它 |
| 手机号管理 | 绑定与维护手机号 |
| 三方应用绑定 | 微信等第三方登录的绑定关系 |
| 双因素认证 | 开启 / 关闭 TOTP,可重新生成、查看备用码 |
### 通用设置
- **深色模式**:跟随系统或手动指定。
### 关于
用户协议、隐私政策与版本信息。
## 多端会话关系
- 密码被重置(含管理员在后台重置)后,APP 与 Web 端**同时下线**,需重新登录;
- 双因素认证的开关与备用码多端同步。
## 常见问题
**手机上能开启双因素认证吗?**
可以。「我的 → 账户与安全 → 双因素认证」按引导扫二维码绑定,开启后 Web 端同样要求第二步验证。
**登录一直提示验证码错误?**
先确认邮件与账号输入无误;若账号被登录锁定策略锁定,需等锁定期结束或由管理员在 Web 端解锁。
## 相关链接
- [用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md):Web 端视角的账号安全机制详解
- [通知与系统](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md):登录日志排查入口
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 商户管理
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/merchant.md
# 商户管理
> 商户域的入口都在这里:从商户列表进入某商户后,详情页以宫格聚合该商户的全部资源(用户 / 门店 / 通道商户 / 应用 / 密钥),一页直达。
## 商户列表
- **筛选**:商户名称、状态(启用 / 禁用)、主体类型(小微 / 个体 / 企业);
- **卡片**:商户名称、状态、主体类型、商户号、简称;
- **操作**:点卡片进商户详情宫格;**长按**卡片弹操作面板(启用 / 禁用、删除——删除是强确认,需输入商户名称匹配才能执行);
- **新增商户**:底部按钮进入创建页。
## 创建商户
表单分两段:
- **商户信息**:商户名称、商户简称、主体类型(单选);
- **管理员信息**:登录账号、手机号(选填)、密码与确认密码——密码带强度指示与策略校验,这是该商户第一个管理员账号,创建后用它登录商户端。
商户的归属代理商分配、进件申请、限额与功能开关、费率等深配置域在 APP 上不提供,请到 Web 运营端[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)操作。
## 商户详情(宫格)
进入某商户后,全部入口按三组展开:
| 分组 | 入口 |
| --- | --- |
| 基础管理 | 商户信息、用户管理、门店管理、系统终端、风控配置 |
| 支付配置 | 通道商户管理、应用管理、支付应用(微信)、支付应用(抖音) |
| 业务配置 | 密钥配置、微信域名校验 |
其中通道商户、应用与密钥的配置方法见[通道商户](https://doc.plus.daxpay.cn/operation-guide/app/admin/channel-merchant.md)与[应用与对接配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/app-config.md)各篇;系统终端见[风控与终端](https://doc.plus.daxpay.cn/operation-guide/app/admin/risk.md#终端设备)。
### 商户信息
查看 / 编辑两态:商户号与主体类型只读,可改商户名称、简称与状态。
### 风控配置(商业版独有)
门店地理围栏的**商户级开关**:地理围栏为两级门控——需先在[风控策略](https://doc.plus.daxpay.cn/operation-guide/app/admin/risk.md#风控策略)开启平台围栏总闸,再在此处为商户开启围栏,开关才会生效。开启后比对支付 IP 归属城市与门店所在城市,不在放行范围按平台策略拦截。
## 门店管理
- **列表**:门店名称、默认门店标记、门店号、联系电话、地址、状态;商户还没有默认门店时顶部有告警提示;
- **操作**:点卡片弹面板——设为 / 取消默认门店、编辑、删除(默认门店不可删);
- **编辑**:名称、联系电话、状态、是否默认门店、地址、备注。把启用中的默认门店改为停用时会二次确认。
## 商户用户
商户的用户账号(区别于[平台用户](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md#平台用户),商户用户登录商户端):
- **列表**:姓名、管理员标记、账号、状态;
- **新增**:姓名、账号(自动查重)、密码(留空则由系统生成随机密码,创建成功后展示一次);同时为该用户选择角色(默认商户用户);
- **详情操作**:编辑(仅姓名可改)、**重置密码**(系统生成随机初始密码,仅展示一次,需立即转告用户)、分配角色、封禁 / 解锁。
一个用户同时只挂一个角色;内置角色(如商户管理员、商户用户)带标记。角色定义与菜单授权在 Web 运营端维护。
## 相关链接
- [通道商户](https://doc.plus.daxpay.cn/operation-guide/app/admin/channel-merchant.md):通道侧商户号管理
- [应用与对接配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/app-config.md):应用 / 密钥 / 网关配置
- [商户管理(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md):Web 端详解
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 通知与系统
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md
# 通知与系统
> 平台侧的通知与日志、用户管理。通道回调与商户通知推送属交易域,见[交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md#回调与通知)。
## 通知中心
收件视角的公告列表:
- 顶部操作条显示未读数,可**全部已读**(确认后生效);
- 行项:未读红点、重要度标签(重要标红)、置顶标记、标题(未读加粗)、时间;
- 点进详情自动标记已读;正文为富文本渲染。工作台公告卡的未读状态随之联动。
公告的发布、下线与邮件发送在 Web 运营端「通知与邮件」操作,见[通知与邮件(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)。
## 日志
四类日志均可在手机上查:
| 日志 | 筛选 | 卡片要点 |
| --- | --- | --- |
| 登录日志 | 账号、结果(成功 / 失败) | 方式与终端、IP、失败原因、时间 |
| 操作日志 | 账号、结果 | 操作模块、失败原因、时间;详情含请求方式 / 地址 / 参数 |
| 业务操作日志 | 账号、结果 | 商户 / 代理商 / 限额 / 进件等业务域的创建修改删除流水;详情含**变更明细** |
| 支付接口日志 | 接口路径或标题、结果 | 路径、**耗时超 3 秒标红「慢调用」**、失败原因;详情含商户与完整报文 |
排查登录异常先看登录日志的失败原因;开放接口对接问题看支付接口日志的报文与耗时。业务操作日志与技术操作日志是两套体系:前者记业务事件(谁把哪个商户改成了什么),后者记技术请求(谁调了哪个接口)。
## 平台用户
平台自身的运营账号(登录运营端的账号,区别于[商户用户](https://doc.plus.daxpay.cn/operation-guide/app/admin/merchant.md#商户用户)):
- **列表**:姓名、账号、管理员标记、状态圆点(正常 / 锁定 / 封禁);**长按**卡片弹操作面板;
- **详情操作**:编辑、**重置密码**(系统生成随机初始密码,仅展示一次)、分配角色(单角色,内置角色带标记)、锁定 / 封禁(正常态)、解锁(异常态);管理员账号不提供状态操作;
- **新增**:姓名、账号、密码等,同商户用户的创建流程。
## 常见问题
**手机上能发公告吗?**
不能。APP 的通知中心是收件视角;公告的新建、发布、下线在 Web 运营端完成,发布后自动推送到各端通知中心与工作台公告卡。
**业务操作日志和操作日志看哪个?**
查「业务上改了什么」(如某商户被谁停用)看业务操作日志的变更明细;查「技术上谁调了什么」(如安全审计)看操作日志的请求参数。
## 相关链接
- [通知与邮件(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md):公告管理与邮件模板详解
- [日志与监控(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md):日志体系详解
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/merchant.md):商户用户与平台用户的边界
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 运营端 APP 功能地图
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md
# 运营端 APP 功能地图
> 运营端 APP 是 Web 运营端的移动版:覆盖商户、支付配置、交易、风控、日志、系统六大域的高频操作,适合外出、值班时的移动巡检。各功能的业务语义与 Web 端一致,本组教程只讲「手机上有什么、怎么用」。
## 页面结构(三 Tab)
- **工作台**:统计行直达 + 交易概览 + 可自定义的快捷入口 + 通知公告,详见[工作台](https://doc.plus.daxpay.cn/operation-guide/app/admin/workspace.md);
- **应用**:全部功能的入口,按七个分组以卡片宫格展示;
- **我的**:账户与安全、通用设置、关于,详见[登录与账号安全](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md)。
## 功能分组与教程导览
「应用」Tab 的七个分组对应以下教程:
| 分组(应用 Tab) | 入口 | 教程 |
| --- | --- | --- |
| 商户管理 | 商户管理、通道商户 | [商户管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/merchant.md)、[通道商户](https://doc.plus.daxpay.cn/operation-guide/app/admin/channel-merchant.md) |
| 支付管理 | 支付产品(启停)、支付渠道、支付产品(配置)、码牌管理、微信支付应用、抖音支付应用 | [支付配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/pay-config.md) |
| 支付安全 | 风控黑名单、风险命中记录、风控预警、风控策略 | [风控与终端](https://doc.plus.daxpay.cn/operation-guide/app/admin/risk.md) |
| 交易订单 | 普通订单、异常订单、资金流水、退款订单、支付交易、网关订单、分账订单 | [交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md) |
| 回调与通知 | 通知中心、商户回调、通道回调 | [交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md)、[通知与系统](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md) |
| 系统日志 | 登录日志、操作日志、业务操作日志、支付接口日志 | [通知与系统](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md) |
| 系统管理 | 用户管理 | [通知与系统](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md) |
部分低频入口(如支付安全分组、分账订单、业务操作日志)默认不显示,可在工作台的入口管理里按需开启。商户的应用、密钥、网关配置等对接类入口从商户详情宫格进入,见[应用与对接配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/app-config.md)。
## 与 Web 运营端的差异
- **深配置域不在手机上**:进件审核、费率、限额、代理商管理等商业版深配置域,以及通道凭证类敏感配置,APP 不提供入口,请到 Web 运营端操作;
- 支付产品的通道参数(服务商应用 / 密钥 / 授权)手机上只看配置进度,参数到 Web 端填;
- 风控预警在手机上为**只读**查看,处置与规则维护在 Web 端;
- 通知为站内通知中心(公告、未读角标),暂无系统级消息推送;
- 各功能的操作逻辑与 Web 端一致,业务语义见 [Web 运营端文档](https://doc.plus.daxpay.cn/operation-guide/admin/overview.md)对应各篇。
## 编译形态
同一套代码可编译为:微信 / 支付宝 / 抖音小程序、H5、App(安卓 / iOS)。界面文案为简体中文单语。
## 相关链接
- [运营工作台](https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md):Web 端功能地图见[运营端总览](https://doc.plus.daxpay.cn/operation-guide/admin/overview.md)
- [移动端使用入门](https://doc.plus.daxpay.cn/operation-guide/app/overview.md):三端 APP 与收银台的定位对比
---
# 支付配置
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/pay-config.md
# 支付配置
> 平台级的支付产品 / 渠道 / 码牌 / 开放应用配置。产品与渠道的语义详解见 Web 端[支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md),本文讲手机上的操作。
## 支付产品(启停)
- **列表**:产品卡片带品牌图标、产品名与编码、通道、特征标签(服务商 / 支持沙箱)、描述;
- **产品详情**:基本信息(编码、通道、生效环境、是否终端、API 调用方式、支付标识类型、是否 ISV、支付能力、产品介绍);
- **可编辑项只有「生效环境」**(生产 / 沙箱,仅支持沙箱的产品可选沙箱)+ 启停开关——通道参数(服务商应用、密钥、授权)在手机上引导到 Web 运营端维护。
## 支付产品(配置)
全部产品的配置总览宫格:每格显示产品与状态(已停用 / 沙箱 / 生产),点击进入对应配置页——支付宝服务商与微信服务商跳**通道 ISV 配置页**,其余产品落到产品详情(生效环境配置)。
**通道 ISV 配置页**(以支付宝服务商为例):身份卡 + 配置进度检查(逐项显示已配置 / 未配置与完成度)+ 沙箱环境管理。检查项点开是引导——手机上看进度,参数到 Web 端填。微信服务商另有**支付能力绑定**页:按产品把「微信支付应用」绑定到各支付能力(可清除绑定),候选应用按能力所需类型自动过滤。
## 支付渠道
渠道是 C 端支付品牌(微信支付 / 支付宝 / 抖音 / 云闪付等,顾客手机里的付款工具)的只读列表:品牌图标、名称、编码、描述、支付方式数量。
## 码牌管理
静态收款码牌的全生命周期:
- **列表**:按编码、名称、状态、程序类型(H5 / 小程序)、金额类型(随机 / 固定)筛选;卡片显示绑定商户(未绑定显示「未绑定」);
- **批量创建**:批次号自动生成(也可手填,提交前自动查重)、数量 1-999、名称、程序类型(整批统一,创建后不可改)、金额类型、固定金额(固定金额类码牌必填)、状态、备注;
- **详情操作**:启用 / 禁用、编辑(名称、金额类型、固定金额、**分账开关**——开启时自动预检分账可用性并列出风险项,不阻断保存、备注)、**绑定商户 / 解绑**、**归属设置**(已绑定码牌可再指定应用与门店)、删除(强确认,需输入码牌名称)。
绑定弹窗:先选商户,再可选应用与门店——码牌收款归集到哪个应用 / 门店台账由此决定。码牌归属与调拨的完整规则(商户级牌别、未划拨口径等)见 Web 端[码牌管理](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md)。
## 平台微信 / 抖音支付应用
平台级开放应用(公众号 / 小程序 / 移动应用等)的登记:应用名称、类型、AppId、AppSecret(编辑留空 = 不修改)。同商户下 AppId 唯一(自动查重);删除强确认需输入 AppId;变更应用类型会清理不兼容的能力绑定(强确认)。
微信 / 抖音的小程序与公众号 AppId 在对应开放平台注册后,先登记到这里,再在通道能力绑定与商户侧引用。
## 常见问题
**手机上能改产品的通道参数吗?**
不能。APP 上只维护生效环境与启停,服务商应用、密钥、授权等参数到 Web 运营端「支付产品配置」填写;手机端的 ISV 配置页可随时查看配置进度。
**码牌批量创建后还能改程序类型吗?**
不能。程序类型(H5 / 小程序)整批统一且创建后不可改,需要另一种形态时另开批次。
## 相关链接
- [支付产品配置(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md):产品 / 渠道语义详解
- [码牌支付](https://doc.plus.daxpay.cn/common/gateway-payment.md):码牌收款链路
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 风控与终端
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/risk.md
# 风控与终端
> 风控入口(黑名单 / 命中 / 预警 / 策略)与终端设备台账。风控体系的语义与层级见 Web 端[支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md),本文讲手机上能做什么。
## 黑名单
事前拦截的第一道防线,按 **IP / 支付宝用户 / 微信 OpenId / 省份 / 城市**五类拉黑:
- **列表**:按名单值、类型、状态筛选;卡片显示区划名(省市自动编码转文本)、状态、类型、原因、过期时间(留空 = 永久);
- **新增 / 编辑**:类型(手动输入;省市走行政区划联动选择)、名单值、状态、过期时间(可清除 = 永久)、拉黑原因、备注。类型与值创建后不可改;**微信 OpenId 类型需再选所属微信平台应用**;
- **详情操作**:启用 / 禁用、编辑、删除。
黑名单支持批量导入,批量操作在 Web 端完成。
## 风险命中
风控规则的命中台账,只读排查用:
- **列表**:按阶段(事前拦截 / 事后命中)、命中类型(IP / 支付宝用户 / 微信 OpenId / 海外 IP / 省份 / 城市 / 门店围栏)、命中值、来源场景(商户 API / 支付网关 / 码牌 / 手工补录)筛选;
- **详情**:命中信息 + **交易上下文**(商户、交易号、交易类型、支付方式、产品、通道)+ 客户端信息(IP、买家标识)——排查「这笔单为什么被拦」先看这里。
## 风控预警
风控指标扫描产生的预警,移动端**只读**查看:
- **列表**:按预警类型(IP 未支付封禁 / 商户成功率预警 / 通道指标预警)、处理状态(未处理 / 已处理)筛选;
- **卡片**:预警类型、商户、通道、通道商户号、窗口指标、处置动作、发生时间。
预警的处置与规则阈值配置在 Web 端[支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)完成;值班时在手机上发现异常,回电脑处理。
## 风控策略
全局开关与拦截策略:
- **风控总开关**:关闭需输入确认关键词强确认——关闭后所有拦截规则失效;
- **公共设置**:IPv6 地区匹配开关(开启时提示精度影响);
- **名单拦截**:黑名单拦截开关;用户标识拦截级别(正常拦截 / 增强拦截);
- **地域限制**:海外 IP 拦截(中国大陆以外)、地区拦截开关;
- **门店围栏**:地理围栏总闸 + 围栏策略三档——严格(仅允许门店所在市)/ 平衡(门店市 + 接壤邻市,推荐)/ 宽松(门店市 + 邻市 + 同省);
- **拦截策略**:命中阻断下单(事前拦截)、事后补录命中开关。
门店围栏是两级门控:平台总闸(这里)开启后,还需在[商户详情 → 风控配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/merchant.md#风控配置商业版独有)为具体商户开启围栏,开关才会生效。
## 终端设备
终端台账,双 Tab:
- **系统终端**:平台登记的终端(云音箱、收银插件等),按终端号、名称、启用状态筛选;详情含门店归属与备注,并展示**已关联的通道终端**(一个系统终端在同一通道商户下按报送类型各一条);
- **通道终端**:微信 / 支付宝等通道侧登记的终端,按名称、通道、登记状态(初始 / 待提交 / 已提交 / 已登记 / 登记失败)筛选;详情含通道商户号、产品、错误信息。
从商户详情宫格的「系统终端」进入时,列表自动限定该商户。终端台账为**纯查看**,登记与绑定操作在 Web 端完成。
当前终端管理是「会话级台账」:只记录设备标识与归属,不做在线状态与远程指令——IoT 设备服务属后续独立能力。
## 常见问题
**手机上能配开放接口的防重放参数吗?**
不能。开放接口的签名与防重放(nonce、超时)等 API 安全参数在 Web 端「系统安全」维护,APP 不提供该入口。
**黑名单里的省市和风控策略的地区拦截是什么关系?**
黑名单省市是名单式拉黑(具体到某省某市,可设过期);风控策略的「地区拦截」是地域黑名单防线的总开关。两者叠加生效。
## 相关链接
- [支付安全与风控(Web)](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md):四层防线体系详解
- [交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md):被拦截交易在风险命中里交叉排查
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 交易管理
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md
# 交易管理
> 交易域是运营端 APP 使用频率最高的部分:八类单据的查询与处置都能在手机上完成,包括发起退款、关闭订单、异常订单人工处置、通知重推等值班场景的操作。
## 通用交互
各单据页面遵循同一套交互习惯,会用了其中一类,其余都是同款:
- **列表**:下拉刷新、上滑加载;卡片直接展示单号、状态、金额等关键信息,失败原因直接印在卡片上;
- **筛选**:列表右下角有可拖动的悬浮筛选按钮,点开底部抽屉设置条件(关键字、状态、时间等),有生效条件时按钮带红点提醒;
- **详情**:点卡片进详情页,信息按「基本信息 / 金额与时间 / 商户与通道」分组展示,单号类字段可一键复制;
- **操作**:详情页底部是操作条——只有一个操作时直接显示按钮,多个时点开选择;危险操作(关闭、忽略)标红;所有写操作都弹确认框,避免手机上误触;
- **刷新联动**:在详情页完成操作(如退款)返回列表后,列表自动静默刷新,不用手动下拉。
## 支付交易
支付交易是资金层的核心单据,展示每笔钱的最终状态。
- **列表**:按关键字(交易号 / 商户订单号)、资金状态、时间筛选;状态六态(初始化 / 处理中 / 成功 / 失败 / 关闭 / 撤销);
- **详情**:身份卡 + 金额大字 + 失败原因;交易信息(平台交易号 / 商户订单号 / 业务号 / 标题 / 币种)、金额与支付信息(**可退金额**、支付方式、支付 / 关闭 / 创建时间)、商户与通道信息(商户号 / 通道商户号 / 买家标识);
- **操作**(按权限与状态动态出现):
- **发起退款**:仅成功状态且有可退余额时可用;弹窗填退款金额与原因,金额校验 0 < 退款额 ≤ 可退余额;
- **同步状态**:向通道查询最新状态并回写;
- **关闭订单**:仅非终态订单,标红,二次确认。
## 订单查询(普通 / 网关)
普通订单、网关订单是业务层的容器单据,与支付交易一对多关联。
- **普通订单**:状态五态(待支付 / 已支付 / 失败 / 已关闭 / 过期);详情操作有退款(已支付且有可退金额)、同步、关闭(仅待支付);
- **网关订单**:状态多一个「支付中」;**详情没有退款入口**——网关单的退款请到支付交易或退款订单页操作;可关闭的状态为待支付 / 支付中。
## 退款订单
- **列表**:按退款号 / 商户退款号 + 状态筛选(处理中 / 成功 / 失败 / 关闭),卡片带退款原因与失败原因;
- **详情**:退款金额以危险色大字展示;含原单金额、原交易号、通道退款单号等;
- **操作**:仅「同步状态」一项——退款是资金操作,手机上只做状态核对,新退款从支付交易详情发起。
## 分账订单
- **列表**:按分账单号 + 状态(处理中 / 成功 / 部分成功 / 失败)+ 通道筛选;
- **详情**:分账信息、原交易信息、通道信息,以及**分账明细时间轴**——每笔分账的收款方类型 / 账户 / 名称 / 金额 / 结果 / 完成时间,「部分成功」时在这里看哪些接收方失败了;
- **操作**:仅「同步」(处理中状态)。
## 资金流水
资金流水是只读账目:每笔收款 / 退款对商户可用资金的影响记录,按交易号、业务单号、退款号、流水类型(收款 / 退款)筛选。详情无任何操作按钮——流水由交易派生,不单独维护。交易手续费的明细口径见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)。
## 异常订单处置
异常订单是值班场景的重点:**终态单据又收到了通道成功回调**(关单后收款 / 失败后收款 / 撤销后收款),系统拿不准要不要入账,等人拍板。
- **列表**:按交易号 / 业务单号 / 异常类型 / 处理状态(待处理 / 已确认成功 / 已忽略)筛选;
- **详情**:异常信息、通道信息(含通道侧状态与回调时间)、商户信息、**通道回调原始报文**(JSON 格式化展示,可展开滚动查看——核实通道侧真实状态就看它)、已处置时展示处置人与处置时间;
- **处置操作**(仅待处理状态):
- **确认成功**:强确认弹窗,提示先核实通道状态;确认后订单按成功入账;
- **忽略**:标红;确认后不再提醒,订单保持原状态。
两个操作都不可逆。先看详情里的通道回调报文与通道状态,再决定入账还是忽略。
## 回调与通知
### 通道回调记录
通道通知平台的原始回调台账:按交易号、通道交易号、通道商户号、商户号、回调类型(支付 / 退款 / 分账)、支付产品、处理状态(成功 / 失败 / 关闭 / 忽略 / 异常 / 未匹配)筛选。**详情可查看通道原始报文**(格式化 JSON,默认折叠、点击展开、可复制)——排查「通道说成功、平台没入账」类问题时先来这里。
### 商户通知推送
平台推送给商户系统的通知台账:
- **列表**:按业务单号、商户号、事件码(如 `pay.success`)、报文格式、发送结果筛选;卡片展示发送次数与下次推送时间;
- **详情**:回调地址、发送情况(发送状态 / 次数 / 退避延迟次数 / 下次推送时间)、通知内容(JSON 可展开复制)、**发送记录时间轴**(每次的请求次数、成功 / 失败、HTTP 状态码、错误信息,点开可看请求摘要);
- **重推**:底部固定按钮,确认后立即重发一次——商户说没收到回调时,核实地址与报文后手动补推。
## 常见问题
**手机上能看交易趋势图表吗?**
APP 侧不提供图表分析,聚焦单据查询与处置;趋势、占比等分析在 Web 运营端「数据分析」页查看。
**网关订单为什么没有退款按钮?**
网关单是容器单据,资金落在支付交易上;请从关联的支付交易详情或退款订单页发起退款。
## 相关链接
- [商户端 APP 交易与退款](https://doc.plus.daxpay.cn/operation-guide/app/merchant/trade.md):商户视角的查单与退款
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md) / [退款管理](https://doc.plus.daxpay.cn/common/refund.md):单据业务语义详解
- [异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md):核查流程详解
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 运营端 APP 工作台
**源**: https://doc.plus.daxpay.cn/operation-guide/app/admin/workspace.md
# 运营端 APP 工作台
> 工作台是打开 APP 后的第一屏:商户规模、今日交易、常用功能、待看公告一屏尽览,所有数字区块都能点击直达对应列表。
## 页面构成
### 头部问候
品牌色块内按时段显示问候语(早上好 / 下午好 / 晚上好)与你的昵称,副标题为站点名称(与 Web 运营端同源的系统名配置)。
### 统计行
三个数字:**商户总数 / 通道商户数 / 用户总数**,各自点击直达对应列表——巡检时最快的入口。
### 交易概览卡
- **今日 / 昨日**切换,展示成交金额、成交笔数、退款金额、退款笔数四项指标;
- 点击成交指标进入[支付交易](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md#支付交易)列表,点击退款指标进入退款订单列表——发现退款异常时一步到位。
### 快捷入口宫格
常用功能的宫格,支持**自定义**:
- 进入入口管理页,从完整目录里挑选常用项、调整顺序;
- 你的选择会记住,换设备登录后同样生效;
- 完整功能目录见[功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)的七个分组。
### 通知公告卡
展示最新公告:未读条目带红点与加粗标题,重要公告标红、置顶公告带标记。点击进公告详情,点「更多」进[通知中心](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md#通知中心)。
## 刷新行为
- 下拉刷新整页数据;
- 在通知中心读完公告返回后,公告卡的未读状态自动同步。
## 常见问题
**工作台能看到交易分析图表吗?**
不能。APP 侧重巡检与处置,趋势图表等分析能力在 Web 运营端「数据分析」页查看。
**快捷入口最多能放几个?**
无硬性上限,按手机屏幕一屏四到八个为宜;低频功能建议留在「应用」Tab 里按分组查找。
## 相关链接
- [交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md):概览卡背后的单据列表
- [通知与系统](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md):通知中心与日志
- [运营端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md)
---
# 代理商端 APP 名下商户
**源**: https://doc.plus.daxpay.cn/operation-guide/app/agent/merchants.md
# 代理商端 APP 名下商户
> 代理商的移动巡检视角：名下商户一览，以及跨商户的支付交易与退款订单查询。全部页面**只读**——这里是「看得见的驾驶舱」，不是操作台。
## 名下商户
名下商户列表（含挂靠到你名下的二级代理商的商户）：
- **筛选**：商户名称模糊搜索 + 状态 Tab（全部 / 启用 / 禁用）；
- **卡片信息**：商户号、商户名称、商户简称、主体类型（小微商户 / 个体工商户 / 企业）、状态。
列表为只读查询，不提供商户资料编辑。代建商户、功能开关代配等管理操作请在 Web 代理商端完成，见[名下商户与代建（Web）](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)；商户自己的资料由商户在商户端维护。
## 名下商户支付交易
跨商户的交易凭证查询：
- **筛选**：交易号搜索 + 资金状态 Tab（全部 / 处理中 / 成功 / 失败 / 关闭）；
- **卡片信息**：交易号、金额、状态、所属商户与应用等；
- **详情**：金额信息（含可退余额）、交易与订单信息、通道信息（通道 / 产品 / 支付方式）、时间信息——每笔交易都能看清是哪个商户、哪个应用发生的。
## 名下商户退款订单
- **筛选**：退款交易号搜索 + 状态 Tab（全部 / 退款中 / 退款成功 / 退款失败 / 退款关闭）；
- **详情**：退款金额、原交易信息、状态与时间信息。
## 数据边界与处理分工
- **数据边界**：订单与商户数据按代理商归属范围自动隔离，只能看到名下（含二级代理商）商户的数据；平台直营、其他代理商的商户不可见。
- **只读定位**：支付与退款页面均不提供退款、同步等操作——退款由商户在商户端发起或由平台处置，代理商在 App 上跟进进度即可。
## 常见问题
### 发现一笔异常交易想马上处理怎么办？
App 端定位为巡检：先记下交易号，退款类处置联系商户在商户端操作；涉及平台侧处置（如订单长时间未同步）时联系平台运营。
## 相关链接
- [订单查询与码牌（Web）](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md)：Web 代理商端的订单查询与码牌管理
- [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)：商户归属与层级规则
- [代理商端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/agent/overview.md)
---
# 代理商端 APP 功能地图
**源**: https://doc.plus.daxpay.cn/operation-guide/app/agent/overview.md
# 代理商端 APP 功能地图
> 代理商端 APP 是商业版**独有**的移动端，面向代理商的日常巡检场景：随时随地查看名下商户的交易与退款动态。功能面是 Web 代理商端的**只读查询子集**，不承载代建商户、邀请码管理等操作。
## 页面结构
与商户端 APP 同骨架，底部三个 Tab：
- **工作台**：问候语、核心统计（今日 / 本月交易额、今日笔数）、交易概览、快捷入口、通知公告，详见[工作台与登录](https://doc.plus.daxpay.cn/operation-guide/app/agent/workspace.md)；
- **应用**：全部功能的分组九宫格入口；
- **我的**：账户与安全、关于、退出登录，与商户端 APP 同款。
## 功能分组与教程导览
「应用」Tab 按三个分组组织，对齐 Web 代理商端菜单：
| 分组 | 入口 | 教程 |
| --- | --- | --- |
| 订单查询 | 支付交易、退款订单 | [名下商户](https://doc.plus.daxpay.cn/operation-guide/app/agent/merchants.md) |
| 商户管理 | 名下商户 | [名下商户](https://doc.plus.daxpay.cn/operation-guide/app/agent/merchants.md) |
| 通用 | 通知中心 | —— |
四个入口（支付交易、退款订单、名下商户、通知中心）同时也是工作台快捷入口的默认集合，支持自定义显隐与排序。
## 与 Web 代理商端的关系
两端共用同一套账号与权限码：Web 代理商端是完整操作面（名下商户代建、功能开关代配、推广邀请码、码牌管理、订单查询），App 端只保留**跨商户的只读查询**能力。在手机上看到的，永远是名下商户的聚合数据。
代理商体系本身（三档定位、商户归属、层级权限）的概念详见[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)。
## 登录与安全
与 Web 代理商端共用账号体系：账号密码 + 图形验证码（失败达阈值后出现）+ 双因素认证，忘记密码走邮箱验证码找回；重置密码后多端同时下线。登录链路与「我的」页面设置和[运营端 APP 完全同款](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md)，不在此重复。
## 编译形态
同一套代码可编译为：微信 / 支付宝 / 抖音小程序、H5、App（安卓 / iOS），各形态功能一致。
## 相关链接
- [移动端使用入门](https://doc.plus.daxpay.cn/operation-guide/app/overview.md)：三个移动端应用的定位对比
- [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)：代理商域的概念与规则
- [名下商户与代建（Web）](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)：Web 代理商端操作面
---
# 工作台与登录
**源**: https://doc.plus.daxpay.cn/operation-guide/app/agent/workspace.md
# 工作台与登录
> 代理商端 APP 的第一屏，围绕名下商户的聚合交易数据展开；登录链路与账号安全复用与商户端 APP 同款的体系。
## 页面构成
### 头部与核心统计
问候语 + 平台品牌欢迎语，下方三个数字：**今日交易额 / 本月交易额 / 今日笔数**，点击直达支付交易列表。统计口径为**名下商户聚合**，与 Web 代理商端工作台同口径。
### 交易概览卡
今日 / 本月切换，展示交易额（大字）与交易笔数，点击同样进入支付交易列表，可下钻查看是哪些商户贡献的交易。
### 快捷入口宫格
默认收录四个入口：支付交易、退款订单、名下商户、通知中心。点「管理」可增删与排序——你的配置会记住，并在「全部应用」Tab 里保持一致。
### 通知公告卡
平台公告前 5 条，未读角标、重要 / 置顶标记。点公告进详情，点「查看更多」进通知中心。
页面支持下拉刷新，一次性重载统计与公告数据。
## 登录
使用代理商账号（由平台或代理商管理员在 Web 端创建分配）：
- **账号密码 + 图形验证码**：连续失败达到阈值后出现验证码；
- **双因素认证**：账号开启后登录需追加验证；
- **忘记密码**：走邮箱验证码找回；
- **重置密码后多端同时下线**。
## 「我的」与账号安全
「我的」Tab 提供：账户信息、修改密码、账户与安全（邮箱管理、双因素认证、三方应用绑定）、关于、退出登录。各设置项的行为与运营端 APP 一致，机制详解见[登录与账号安全](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md)。
## 常见问题
### 工作台交易额包含哪些商户？
名下商户（含挂靠到你名下的二级代理商的商户）的聚合数据；每个代理商只能看到自己归属范围内的数据，平台直营与其他代理商的商户不可见。
## 相关链接
- [名下商户](https://doc.plus.daxpay.cn/operation-guide/app/agent/merchants.md)：列表与订单查询详解
- [代理商端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/agent/overview.md)
- [登录与账号安全](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md)：登录链路与账号安全机制说明
---
# 商户中心
**源**: https://doc.plus.daxpay.cn/operation-guide/app/merchant/mch.md
# 商户中心
> 商户自助管理自己的基础资料：商户信息、用户、门店、码牌。深色操作（商户主体变更等）需联系平台运营。
## 我的商户
展示商户名称、商户号、状态与主体类型（只读）；**仅商户简称可自行修改**——简称用于收银台等顾客侧展示，保存前有二次确认。
## 商户用户
商户自己的账号管理：
- **列表**：姓名、管理员标记、账号、状态；
- **新增**：填写姓名与登录账号，账号自动查重；
- **详情操作**：编辑、重置密码、分配角色、封禁 / 解锁（封禁后该用户无法登录，有确认提示）。
角色与账号安全机制的说明见[商户用户（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md)。
## 门店管理
- **列表**：门店名、默认门店标记、联系电话、地址、状态；
- **新增 / 编辑**：门店名称、联系电话、详细地址、状态、备注，从底部按钮进入。
App 端维护门店的常用字段，完整的门店资料管理以 Web 商户端为准，见[商户资料与门店](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md)。
## 码牌管理
商户名下码牌的自助管理：
- **筛选**：状态（启用 / 停用）、程序类型（H5 / 小程序）、金额类型（自定义金额 / 固定金额）；
- **认领码牌**：平台批量制发的空白码牌，点击底部「认领码牌」，输入或扫描印制在物料上的编号，确认后即认领绑定到自己名下——比找运营登记快得多；
- **编辑**：码牌编码等标识信息只读，可调整归属应用与门店；开启分账开关时保存前会做分账能力预检并给出预警。
码牌的批量**创建**属平台制发能力，由运营端操作，见[码牌管理](https://doc.plus.daxpay.cn/common/qrcode.md)。
微信 / 支付宝域名校验文件的自助上传是 Web 商户端「对接配置」的能力，App 端未提供，请前往 Web 端操作，详见[对接配置（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)。
## 相关链接
- [商户资料与门店（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md)：Web 商户端视角
- [支付配置](https://doc.plus.daxpay.cn/operation-guide/app/merchant/pay-config.md)：应用 / 密钥 / 通道商户
- [商户端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md)
---
# 商户端 APP 功能地图
**源**: https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md
# 商户端 APP 功能地图
> 商户端 APP 是 Web 商户端的移动版：提供**常用功能的子集**，查交易、查回调、改基础配置都能做，适合不开电脑的日常巡检场景。
## 页面结构
底部三个 Tab：
- **工作台**：问候语、统计行（我的应用 / 我的门店 / 通道商户数，点击直达）、交易概览（今日 / 昨日）、快捷入口（可自定义）、通知公告，详见[工作台](https://doc.plus.daxpay.cn/operation-guide/app/merchant/workspace.md)；
- **应用**：全部功能的分组九宫格入口；
- **我的**：账户与安全、关于、退出登录，与运营端 APP 同款。
## 功能分组与教程导览
「应用」Tab 与快捷入口按四个分组组织：
| 分组 | 入口 | 教程 |
| --- | --- | --- |
| 商户中心 | 我的商户、商户用户、门店管理、码牌管理 | [商户中心](https://doc.plus.daxpay.cn/operation-guide/app/merchant/mch.md) |
| 支付配置 | 应用管理、对接配置、通道商户、微信 / 抖音应用 | [支付配置](https://doc.plus.daxpay.cn/operation-guide/app/merchant/pay-config.md) |
| 交易订单 | 支付交易、退款订单、支付订单、普通 / 网关订单 | [交易与退款](https://doc.plus.daxpay.cn/operation-guide/app/merchant/trade.md) |
| 回调与通知 | 通道回调记录、商户回调推送、通知中心 | [交易与退款](https://doc.plus.daxpay.cn/operation-guide/app/merchant/trade.md) |
App 端有意裁剪了低频运营项（系统终端管理、域名校验文件上传等），请在 Web 商户端操作。交易类页面在 App 端定位为**只读巡检**，退款发起等写操作同样在 Web 端完成。各功能的业务口径与 Web 端一致，详解见[业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)。
## 登录与安全
与 Web 商户端共用同一套账号：账号密码 + 图形验证码（失败达阈值后出现）+ 双因素认证，忘记密码走邮箱验证码找回；重置密码后多端同时下线。登录链路与「我的」页面设置和[运营端 APP 完全同款](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md)，不在此重复。
## 编译形态
同一套代码可编译为：微信 / 支付宝 / 抖音小程序、H5、App（安卓 / iOS），各形态功能一致。
## 相关链接
- [移动端使用入门](https://doc.plus.daxpay.cn/operation-guide/app/overview.md)：三个移动端应用的定位对比
- [商户工作台（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)：Web 商户端视角
- [登录与账号安全](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md)：登录链路与账号安全机制说明
---
# 商户端 APP 支付配置
**源**: https://doc.plus.daxpay.cn/operation-guide/app/merchant/pay-config.md
# 商户端 APP 支付配置
> 商户自助的对接配置：应用、密钥、通道商户、开放应用。核心高频配置手机全量可做，与运营端 APP 同款交互。
## 应用管理
- **列表**：应用名、默认应用标记、应用号、状态；有应用但未设默认时顶部有警示条；
- **编辑**：名称、状态、默认应用设置。
进入某个应用后的**配置宫格**分两组：
- **支付配置**：通道路由、网关支付配置、收银台配置、异步通知配置、易支付配置五项自助配置；
- **应用管理**：编辑、设为 / 取消默认、删除——默认应用不可删除（需先取消默认），删除有强确认，提示应用及其支付配置、通知配置等数据将无法恢复。
各项配置的操作与 Web 端是同一个配置页，谁登录谁改，口径详见[应用支付配置（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)。
## 异步通知配置
应用级事件订阅：勾选需要订阅的事件，平台据此向你的系统推送回调。事件口径与 Web 端一致，详见[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)。
## 对接配置（密钥）
对接开放接口的三件凭证：
- **平台公钥**：只读，可复制，用于验签平台报文；
- **商户公钥**：可生成 RSA 密钥对——**私钥仅在生成后的弹窗里展示一次**（掩码显示，仅可复制获取），务必立即妥善保管，丢失无法找回；
- **通信密钥**：可生成 AES 密钥。
已有公钥 / 密钥时重新生成会覆盖原值，均有二次确认。凭证用途详见[对接配置（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)。
## 通道商户
自己名下通道收款账号的自助维护：
- **列表**：产品图标 + 产品名、启停标签、通道商户号、商户全称；
- **详情**分两组（商户端**无删除**——删号找平台运营）：
- **交易配置**：分账接收方（支持微信直连 / 微信服务商 / 支付宝直连 / 支付宝服务商 / 抖音五个产品）、应用授权令牌（支付宝服务商）；
- **基础管理**：基本信息（只读）、修改名称（仅名称可改，通道商户号 / 产品不可变更）、密钥 / 证书配置（涉及密钥安全，提示在 PC 端操作）、启用 / 禁用。
商户可自助**改名与启停**全部通道商户；新通道商户的**创建**由平台完成（涉及进件开通），找平台开通后在手机上维护。
## 微信 / 抖音开放应用
登记自己用于收款的公众号 / 小程序 / 移动应用（JSAPI 支付、小程序登录都依赖它）：
- **登记**：应用名称、类型（微信：公众号 / 小程序 / 移动应用；抖音：小程序 / 移动应用 / 网页应用）、AppId、AppSecret；
- 同商户下 AppId 唯一（自动查重）；
- 变更应用类型会清理不兼容的能力绑定，保存后有相应提示。
## 常见问题
### 通道商户的密钥 / 证书为什么点不动？
密钥类配置涉及安全红线，移动端不提供入口，请在 PC（Web）端操作，App 内点击会给出指引。
## 相关链接
- [通道商户（Web 商户端）](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)：通道自助维护详解
- [易支付插件](https://doc.plus.daxpay.cn/operation-guide/merchant/easypay.md)：易支付协议的启用与密钥
- [商户端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md)
---
# 交易与退款
**源**: https://doc.plus.daxpay.cn/operation-guide/app/merchant/trade.md
# 交易与退款
> 查交易是商户端 APP 的主场景。**App 端交易类页面全部为只读查询**：退款发起、订单同步、关单等写操作请在 Web 商户端完成，App 适合随时随地查单与核对回调。
## 通用查询交互
各列表页共用一套交互：顶部搜索框 + 状态筛选 Tab、下拉刷新、上拉加载更多；点击卡片进入详情，详情按信息分组展示（金额、订单、通道、时间等）。
## 支付交易
资金交易凭证，商户端最常用的查单入口：
- **筛选**：交易号搜索 + 资金状态 Tab（全部 / 处理中 / 成功 / 失败 / 关闭）；
- **详情**：金额信息（含可退余额）、交易与订单信息、通道信息（通道 / 产品 / 通道单号）、时间信息。
三层订单模型（支付交易 / 普通订单 / 网关订单）的口径详见[支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)。
## 订单查询
| 单据 | 说明 |
| --- | --- |
| 支付订单 | 订单的资金侧视图，与普通订单同源 |
| 普通订单 | 业务层订单查询 |
| 网关订单 | 走统一收银台的网关形态订单 |
| 退款订单 | 退款中 / 退款成功 / 退款失败 / 退款关闭 |
以上页面均为只读，退款订单详情同样只做查询。
## 退款在哪里发起
App 端不提供退款入口。请在 Web 商户端的[退款管理](https://doc.plus.daxpay.cn/operation-guide/merchant/refund.md)发起，填写退款金额（上限为可退余额）与原因；App 端的退款订单页可随时跟进退款进度。
## 回调与通知
- **商户回调推送**：平台发给**你自己系统**的通知台账——回调地址、发送次数、退避与下次发送时间、通知内容、发送记录（含请求摘要，可展开）；确认地址与报文无误后可**重发**（需二次确认）；
- **通道回调记录**：通道 → 平台的回调台账，可查状态与失败原因；**原始报文不下发商户端**，需要报文级排查时联系平台客服。
## 与其他端的分工
| 能力 | 商户端 APP | Web 商户端 | 运营端 APP |
| --- | --- | --- | --- |
| 查单 / 查回调 | 支持 | 支持 | 支持（全平台视角） |
| 发起退款 / 同步 / 关单 | 不支持 | 支持 | 平台侧处置 |
| 通道回调原始报文 | 不下发 | 不下发 | 可查看 |
## 常见问题
### 为什么支付交易详情里没有操作按钮？
App 端交易页面定位为只读巡检，所有写操作（退款、同步、关单）统一收敛到 Web 商户端，避免移动端误操作。
### 商户回调一直失败怎么办？
先在推送详情里核对回调地址与通知报文，确认无误后可手动重发一次；仍失败则检查你方接口的签名验签与响应格式，详见[商户回调通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md)。
## 相关链接
- [交易订单管理（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md)：Web 商户端全部单据详解
- [退款管理](https://doc.plus.daxpay.cn/common/refund.md)：退款状态流转与规则
- [商户回调与通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md)：回调配置与推送策略
- [商户端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md)
---
# 商户端 APP 工作台
**源**: https://doc.plus.daxpay.cn/operation-guide/app/merchant/workspace.md
# 商户端 APP 工作台
> 商户端 APP 的第一屏，围绕「我的」三个数字与今日交易展开。页面构成与运营端 APP 工作台同款交互，数据口径换成商户自己的。
## 页面构成
### 统计行
三个数字：**我的应用 / 我的门店 / 通道商户数**，点击直达对应管理页。未配置的项点进去是空列表，也是提醒你补配置的信号。
### 交易概览卡
今日 / 昨日切换，展示成交金额（大字）、成交笔数、退款金额、退款笔数。点成交指标进支付交易列表、退款指标进退款订单列表。
### 快捷入口宫格
默认收录 11 个常用入口（我的商户、商户用户、码牌管理、应用管理、对接配置、通道商户、微信 / 抖音应用、支付交易、退款订单、通知中心等）。点「管理」可增删与排序——你的配置会记住，并在「全部应用」Tab 里保持一致。
### 通知公告卡
平台公告前 5 条，未读角标、重要 / 置顶标记。点公告进详情，点「查看更多」进通知中心。
页面支持下拉刷新，一次性重载统计、交易概览与公告数据。
## 全部应用 Tab
按四个分组（商户中心 / 支付配置 / 交易订单 / 回调与通知）九宫格展示全部入口，另有仅收纳演示类入口的「系统」分组（默认隐藏）。系统终端、域名校验等低频项不设移动端入口；按应用维度的配置页（通道路由 / 网关支付配置 / 收银台配置）统一从应用管理进入，不单独设入口。
## 常见问题
### 普通订单、网关订单默认不在快捷入口里？
这些单据页面向进阶查询场景，默认收起，可在快捷入口「管理」里自行开启；「全部应用」Tab 的「交易订单」分组中始终可以找到。
### 调整快捷入口会影响「应用」Tab 吗？
不会。「应用」Tab 始终展示全部分组入口；快捷入口的自定义只影响工作台首页宫格的显隐与顺序。
## 相关链接
- [商户工作台（Web）](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)
- [交易与退款](https://doc.plus.daxpay.cn/operation-guide/app/merchant/trade.md)：概览卡背后的单据
- [商户端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md)
---
# 移动端使用入门
**源**: https://doc.plus.daxpay.cn/operation-guide/app/overview.md
# 移动端使用入门
> 系统在 Web 三端(运营端 / 代理商端 / 商户端)之外,提供**三个移动形态的 APP** 与**收银台**,先按使用者区分清楚:
| | 运营端 APP | 商户端 APP | 代理商端 APP | 收银台(小程序 / H5) |
| --- | --- | --- | --- | --- |
| 使用者 | **平台运营人员** | **商户**(老板 / 店员) | **代理商** | **顾客**(付款人) |
| 打开方式 | 主动登录使用 | 主动登录使用 | 主动登录使用 | 微信 / 支付宝 / 抖音内扫商家码自动拉起,或浏览器打开支付链接 |
| 是否登录 | 运营账号登录 | 商户账号登录 | 代理商账号登录 | 免登录 |
| 核心能力 | Web 运营端的移动版,巡检 + 高频操作 | Web 商户端的移动版,日常查单退款 | 名下商户与订单的移动查询 | 在小程序或网页里完成一笔付款 |
| 详见 | [运营端 APP](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md) | [商户端 APP](https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md) | [代理商端 APP](https://doc.plus.daxpay.cn/operation-guide/app/agent/overview.md) | [收银台使用入门](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md) |
代理商端 APP 为商业版独有,开源基础版没有这一端。
## 按角色对号
- **平台运营方**:日常操作在 Web 运营端完成;需要外出、值班时用手机处理交易和配置,就部署**运营端 APP**;
- **代理商**:名下商户巡检、支付与退款订单查询用**代理商端 APP**;推广邀请码等复杂操作回 Web 代理商端;
- **商户**:不开电脑的日常巡检(查交易、退款、看通知)用**商户端 APP**;复杂配置回 Web 商户端操作;
- **顾客**:什么都不用装——微信 / 支付宝 / 抖音里扫商家出示的码,进入**收银台小程序**;支付链接在浏览器(含电脑浏览器)打开,就是 **H5 收银台**的收款页。两者背后是同一套收款链路,按打开环境自动落到对应形态。
## 账号体系
三端 APP 与对应的 Web 端**共用同一套用户与权限体系**:同一个账号在手机和电脑上登录,看到的菜单与数据范围完全一致(由角色授权决定),一处修改、多端同时生效。收银台面向付款人,无需注册登录(用户侧的三方登录只会经过收银台的中转页,不在此登录)。
## 上线各需要什么
| 应用 | 上线要点 |
| --- | --- |
| 运营端 APP | 小程序形态:平台注册 + 替换正式 AppId + 编译上传过审;App 形态:打包分发 |
| 商户端 APP | 同上;微信场景下登录所用的小程序 AppId 需在「微信支付应用」登记 |
| 代理商端 APP | 同上;上线前先在 Web 运营端建好代理商账号与角色授权 |
| 收银台小程序 | 平台注册 + 域名验证 + 普通链接二维码规则,见[小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md) |
| H5 收银台 | 作为独立前端部署在收款域名下,见[收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md) |
三个 APP 工程交付时的小程序 AppId 均为占位值,**上线前必须替换为各自在对应平台注册的正式 AppId**,否则无法上传与审核。
三个 APP 都基于 uni-app 开发,同一套代码可编译为微信 / 支付宝 / 抖音小程序及 H5、App 等多个目标平台;界面文案为简体中文单语。
## 相关链接
- [运营端 APP](https://doc.plus.daxpay.cn/operation-guide/app/admin/overview.md):[工作台](https://doc.plus.daxpay.cn/operation-guide/app/admin/workspace.md) / [登录与账号安全](https://doc.plus.daxpay.cn/operation-guide/app/admin/login-security.md) / [商户管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/merchant.md) / [通道商户](https://doc.plus.daxpay.cn/operation-guide/app/admin/channel-merchant.md) / [应用与对接配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/app-config.md) / [支付配置](https://doc.plus.daxpay.cn/operation-guide/app/admin/pay-config.md) / [风控与终端](https://doc.plus.daxpay.cn/operation-guide/app/admin/risk.md) / [交易管理](https://doc.plus.daxpay.cn/operation-guide/app/admin/trade.md) / [通知与系统](https://doc.plus.daxpay.cn/operation-guide/app/admin/notify-system.md)
- [商户端 APP](https://doc.plus.daxpay.cn/operation-guide/app/merchant/overview.md) / [代理商端 APP](https://doc.plus.daxpay.cn/operation-guide/app/agent/overview.md)
- [收银台使用入门](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md):[收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md) / [小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md)
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md):收银页背后的业务链路
---
# 认证与中转
**源**: https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md
# 认证与中转
> H5 收银台(支付网关域名)下还有一类页面**不收款**:认证落地与中转跳转。付款人通常只是「经过」它们——授权一闪而过、登录跳回 Web 端。这些页面由后端生成的地址驱动,相关配置分散在运营端各处,本文集中说明它们在整条链路里的位置。
## 支付认证落地页(付款人无感)
选择**需要用户身份**的支付方式(微信 / 支付宝 / 抖音的 JSAPI 类)时,收款页会先跳到对应平台的授权页拿 openId,授权完成后回到网关域名的落地页,再自动继续支付——付款人全程无感,最多看到一次页面切换。
| 落地路径 | 平台 | 说明 |
| --- | --- | --- |
| `/auth/wechat` | 微信公众号 OAuth 网页授权 | PC 微信内置浏览器里同样走通 |
| `/auth/alipay` | 支付宝授权 | |
| `/auth/douyin` | 抖音静默授权(silent_auth) | |
授权的回跳落点是收银台的环境页(`/cashier/{订单号}/{环境}`),回来后从断点继续支付流程。
排查:授权环节报「域名未登记 / 回调不合法」,多半是开放平台侧登记的域名与支付网关域名不一致——微信登记**网页授权域名**(纯域名)、支付宝登记**授权回调地址**(带协议的完整地址),登记的都是网关域名,见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 代运营授权落地页(商家)
`/isv-auth/alipay` 是服务商模式下**支付宝代运营授权**的回跳页:商家在商户端「通道商户 → 授权令牌」点击授权链接,到支付宝授权页确认后回到这里换取 app_auth_token,令牌自动更新、无需手工传递。发起方式见[商户端 - 通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)。
## 三方登录与绑定的中转透传页
**谁会经过**:在 Web 运营端 / 代理商端 / 商户端使用微信 / 支付宝登录,或绑定三方账号的用户。
**为什么需要中转**:支付宝同一应用的授权回调名额只有一份,而登录与支付认证共用同一 AppId——登录回调若直接用各端自己的域名,会与支付回调互相顶替(启用登录后支付认证失败);微信公众号的网页授权域名也有登记限制。因此跳转型平台的登录 / 绑定回调**统一落在支付网关域名**,再由收银台跳回实际发起的端,登录与支付互不影响。
**机制**:回调地址形如 `/auth/oauth-callback/{端标识}/{平台}`,页面凭「端标识 + 平台」查到目标端的回调地址,把授权参数原样透传跳回;账号绑定走同款机制(`/auth/social-bind-callback/...`)。三端的回调地址在端点配置中分别维护(运营端 / 代理商端 / 商户端访问地址)。
**用户视角**:登录过程中的一个一闪而过的中转页,正常情况无需关注。
**配置与排查**:三方登录的开放平台登记在运营端维护(见[第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md));登录后跳 404 / 跳不回发起端,先核对端点配置的「支付网关前端地址」与实际部署域名一致。
## 公众号扫码登录 / 绑定页(跨设备)
**谁会经过**:在 PC(或任何非微信浏览器)上用微信公众号登录、或在个人中心绑定微信公众号的用户。
**为什么需要**:微信公众号网页授权只能在微信内浏览器完成,PC 发起不了——于是 PC 弹二维码,由**手机微信**扫码后在收银台页面上走完授权,PC 端轮询结果自动收尾。
**机制**:二维码指向收银台上的发起页(`/social/login-scan`、`/social/bind-scan`,携带一次性票据,5 分钟有效)→ 手机上依次经过**确认页**(绑定场景会展示脱敏的目标账号,防把微信绑到别人账号上;可取消)与微信授权 → 授权回调落在 `/social/{login|bind}-scan-callback/weChat` → 结果页显示成败、可关闭页面。PC 端每 3 秒轮询票据状态,自动完成登录 / 绑定。
**域名**:整条链路复用公众号**网页授权域名**(即网关域名),公众号后台无需为新流程额外登记。
未绑定的微信号扫码登录**不会自动注册**,手机端会引导先用账号密码登录再到个人中心绑定。配置侧见[第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)。
## 协议展示页
`/protocol/{类型}`:用户协议、隐私政策的独立展示页,收款页脚等处的链接落在这里,可单独分享。协议内容在运营端维护,见[用户协议](https://doc.plus.daxpay.cn/operation-guide/admin/user-protocol.md)。
## 相关链接
- [收银台总览](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md):职责全景与地址生成机制
- [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md):收款面的页面交互
- [收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md):域名契约——认证与透传地址同样由后端按网关域名生成
- [第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md):Web 端的配置侧
- [支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md):域名登记与联调
---
# 收款页面
**源**: https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md
# 收款页面
> 收款页面是付款人在**浏览器**里付款的入口:统一收银台、码牌、聚合三条链路,加上收款单支付页与支付结果回跳,构成 H5 收银台的收款面。微信 / 支付宝 / 抖音内扫码会拉起[收银台小程序](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md),两者是同一套收款链路在不同环境下的两种形态(分工与链接前缀见[收银台总览](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md))。
## 统一收银台
预下单后的落地页(`/cashier/{订单号}`),付款人选择支付方式完成付款:
- **页面内容**:大号金额、剩余有效时间倒计时、订单标题与订单号;
- **支付方式列表**:图标 + 名称 + 「推荐」标签,单选;被锁定的方式(商户配置了锁定)只有指定项可选,其余置灰;
- **支付动作**:选好方式后点底部「立即支付」——选择不会自动触发支付,防止误点;
- **倒计时结束**:订单过期,支付按钮禁用;
- **需要用户身份的方式**(如微信 JSAPI 类):自动跳授权拿 openId,回来后自动继续支付流程,付款人无感(机制见[认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md));
- **支付后**:二维码类方式直接展示二维码供扫码;其余调起对应支付。页面每 2 秒查询一次订单状态(约 3 分钟),到达终态展示结果;
- **支付成功跳回**:订单配置了回跳地址时,结果页 3 秒倒计时后自动返回商户页面;重复打开已支付订单不重复跳转,只显示「返回商户」按钮。
电脑浏览器打开同一链接是**网页版收银台**:支付方式以网格展示,其余逻辑相同。
## 码牌收款
扫静态码牌后在浏览器打开的收款页(`/h/{码牌编号}`):
- **页面内容**:商家头像、码牌名称、副标题「向 {商户简称} 付款」;
- **随机金额码牌**:数字键盘输入金额(最多两位小数),键盘的确认键即「确认支付」;
- **固定金额码牌**:大号金额直接展示,点「确认支付」即可;
- **备注**:点备注行弹窗输入(50 字以内),会随订单传给商家;
- **环境要求**:码牌页在微信 / 支付宝 / 抖音 / 云闪付内打开时走对应通道;**普通浏览器打开会提示「请使用钱包扫码」**——码牌的单通道特性决定了它只在钱包环境付款;
- 小程序类型的码牌不在 H5 侧支付,扫码直接进小程序(两类码牌模型见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md))。
## 聚合支付
聚合扫码订单的确认页(`/aggregate/{订单号}`):订单标题、金额、订单号与倒计时,点「立即支付」完成;支持的场景下自动拉起支付(按钮变为「重试」)。仅在钱包环境可用,浏览器打开显示不支持提示。
## 收款单支付页
商户通过[收款单](https://doc.plus.daxpay.cn/common/receivable-bill.md)远程催款时,客户打开 `/b/{收款单号}` 的支付页:展示单据金额与备注等表单内容,确认后按统一收银流程付款,一单一付。页面形态与码牌收款页同范式。
## 支付结果页
通道回跳与支付完成的统一结果页(`/pay-result/{交易号}`):
- 多种状态:支付成功 / 失败 / 已关闭 / 已过期 / 加载失败;
- 未到终态时每 2 秒轮询一次(约 3 分钟),状态变化自动刷新;
- 成功且有回跳地址时 3 秒倒计时自动返回商户;没有回跳地址则显示「关闭页面」按钮。
## 电脑与手机自适应
同一链接,按设备自动展示两套页面:
- **手机浏览器**:完整收银流程(输金额 / 选方式 / 付款);
- **电脑浏览器**:统一收银台为网页版收银页;码牌 / 聚合页显示「请用手机扫一扫」引导;
- iPad 等触屏设备会被正确识别为移动端;
- 调试时可在链接后加 `?device=pc` / `?device=mobile` 强制指定形态。
## 支付方式展示由谁决定
收银台展示的支付方式列表 = **商户的收银台配置**(在商户端「支付配置 → 收银台配置」维护)按**打开环境**过滤后的结果。配置按终端分桶:H5 桶按打开环境细分浏览器 / 微信 / 支付宝 / 云闪付 / 抖音,小程序桶按平台分档,Web 桶为扁平列表——同一订单在浏览器、微信、支付宝内看到的可选项可以不同;电脑版收银台展示 Web 桶配置。配置操作见[应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)。
## 界面语言
收银台界面为中文(单语直写)。
## 相关链接
- [收银台总览](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md):职责全景与地址生成机制
- [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md):收款之外的收银台页面
- [收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md):构建、部署与域名契约
- [小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md):钱包内的付款形态
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md):三类收款链路详解
---
# 收银台部署与上线
**源**: https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md
# 收银台部署与上线
> H5 收银台是独立的前端工程(Vite + Vue3 + Vant,PC / 移动双形态),构建产物是纯静态文件,部署方式与 Web 运营端一致(静态托管 + 接口反代)。它的特殊性在**域名契约**:收款链接、回跳与认证回调地址都由后端按支付网关域名生成,部署域名要与平台配置对齐。整体上线链路(域名验证 → 网关支付配置 → 码牌 → 小程序)见[网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md)。
## 构建
- Node 22+ 与 pnpm 10+ 环境;
- 生产构建产物为纯静态文件(`dist/vant-mobile/`),自动移除调试控制台输出。
关键构建配置(写在环境文件 `.env.production` 里,按需修改后构建):
| 配置 | 说明 |
| --- | --- |
| 后端接口地址 | 生产留空 = 使用相对路径请求,靠同域反代转到后端(推荐) |
| 接口前缀 | 固定 `/api/`,请求形如 `https://h5.example.com/api/...` |
本地开发时 dev server 端口为 `19500`(已把 `/api` 代理到后端 `19999`);生产端口与访问入口由部署方自定,以支付网关域名为准(示例 `h5.example.com`)。
## 部署四要点
1. **静态托管**:构建产物交给 nginx 等静态服务器,与其他前端(Web 运营端等)互不依赖、可分开部署;
2. **接口反代**:同域下把 `/api/` 反向代理到后端服务(与 Web 端同策略),无需跨域配置:
```nginx
location /api/ {
proxy_pass http://后端服务地址/;
}
```
3. **SPA 回退**:所有路径回退到 `index.html`——收银台上的地址是 `/cashier/xxx`、`/h/xxx`、`/auth/xxx` 这样的深路径,刷新与直达都不能 404:
```nginx
location / {
try_files $uri $uri/ /index.html;
}
```
4. **HTTPS**:面向付款人的页面必须 HTTPS,证书配在 nginx 层。
使用运维面板部署时,面板已内置上述反代与回退,只需在域名绑定中填好支付网关域名,见[运维面板](https://doc.plus.daxpay.cn/tools/panel/deployment.md)。
## 域名契约(重点)
H5 收银台的页面地址**大部分是后端生成给通道、付款人和登录用户的**,不是前端自己拼的:
| 地址 | 谁用 | 生成时机 |
| --- | --- | --- |
| 收款链接 `/cashier/...`、`/h/...`、`/aggregate/...`、`/b/...` | 付款人 | 预下单 / 生成码牌 / 开收款单时返回给商户系统 |
| 小程序入口 `/m/...`、`/cm/...`、`/am/...` | 扫码付款人 | 预下单 / 生成码牌时一并返回,由二维码规则拉起小程序 |
| 支付结果页 `/pay-result/{交易号}` | 付款人 | 配置了回跳的支付,通道处理完跳转 |
| 预授权冻结落地 `/preauth/alipay/...` | 付款人 | 发起支付宝线上预授权冻结时生成 |
| 邀请注册 `/register` / 进件填报 `/onboarded` | 受邀商户 | 生成推广链接 / 进件填报链接时生成 |
| 认证回跳 | 付款人 | 微信网页授权域名 / 支付宝授权回调地址登记的就是网关域名 |
| 三方登录透传入口 `/auth/oauth-callback/...` | Web 三端登录用户 | 跳转型平台登录 / 绑定回调统一落网关域名 |
因此 **H5 收银台必须部署在平台的支付网关域名之下**(该域名在运营端「系统管理 → 系统配置 → 平台配置 → 端点配置」的「支付网关前端地址」维护),后端生成地址、前端提供页面,两边对得上才不会 404。部署前与后端侧的网关域名配置核对一致;认证与透传的机制见[认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md)。
## 与收银配置的联动
H5 收银台上线后,收银台展示效果还依赖两处配置(页面本身不用改):
- **商户的收银台配置**:支付方式列表、推荐与锁定(见[应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md));
- **域名验证**:微信 / 支付宝侧 JSAPI 支付需要完成域名归属验证(校验文件上传),见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 常见部署问题
| 现象 | 原因 |
| --- | --- |
| 直达链接 / 刷新 404 | 没配 SPA 回退(`try_files ... /index.html`) |
| 页面开了但请求全失败 | `/api/` 反代没配或指错后端 |
| 付款成功后回跳 404 | 部署域名与后端支付网关域名配置不一致 |
| 三方登录后跳 404 / 跳不回发起端 | 端点配置的「支付网关前端地址」与实际部署域名不一致 |
| 支付认证报域名未登记 / 回调不合法 | 开放平台登记的授权域名与支付网关域名不一致 |
| 电脑打开是手机版页面 | 正常按设备自适应分发;确认链接没带 `?device=mobile` 参数 |
| 微信内付款提示域名未验证 | 域名校验文件未上传或支付目录未配置 |
## 相关链接
- [收银台总览](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md):职责全景与地址生成机制
- [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md):认证回调与登录透传
- [网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md):网关收款五环节上线主线
- [项目构建](https://doc.plus.daxpay.cn/deployment/build.md):源码获取与静态部署
- [支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md):域名验证与联调
---
# 小程序发布上线
**源**: https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md
# 小程序发布上线
> 收银台小程序按平台分别发布(微信 / 支付宝 / 抖音各一个小程序)。核心是两件事:**域名验证**(证明域名归你)与**普通链接二维码规则**(让现有二维码能拉起小程序)。编译与上传操作见[跨端应用](https://doc.plus.daxpay.cn/deployment/uniapp.md)。
## 上线检查单
1. 平台注册小程序主体并获得 AppId,替换工程内的占位 AppId;
2. 完成**域名验证**(校验文件上传);
3. 配置**普通链接二维码规则**;
4. 配置 **request 合法域名**;
5. 编译上传、提审、发布。
## 第一步:注册与 AppId
在微信 / 支付宝 / 抖音的开放平台分别注册小程序主体,拿到各自的 AppId。三端 AppId 独立,一个平台发一个小程序,互不影响。
工程交付时 `env/.env` 里的四个 AppId(DCloud uni appid、微信 / 支付宝 / 抖音各自的小程序 AppId)均为占位值,上线前**必须**替换为正式值,否则无法上传与提审。收银台小程序在平台侧的配置(平台公共小程序与商户自有小程序)见[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)。
## 第二步:域名验证
微信要求小程序调用的域名必须完成归属验证:
1. 微信公众平台下发校验文件(`MP_verify_xxx.txt`);
2. 把文件内容在**运营端「支付管理 → 接入配置 → 域名校验文件」**上传托管(商户自有小程序的商户级校验文件,商户可在商户端「业务配置 → 域名校验文件」自助上传,见[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md));
3. 在微信公众平台配置业务域名时,微信会访问该文件完成校验。
详细说明见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 第三步:普通链接二维码规则(关键)
商家的收款二维码是**已印好的普通链接二维码**(内容是 `https://h5.example.com/m/xxx` 这样的 URL),小程序规则的作用是:**扫码时微信 / 支付宝发现 URL 命中规则,直接拉起小程序对应页面**,不需要专门的小程序码。
在微信公众平台的「普通链接二维码跳转小程序」中配置:
| 规则前缀 | 拉起的页面 |
| --- | --- |
| `https://域名/m/*` | 码牌收款页 |
| `https://域名/cm/*` | 统一收银台页 |
| `https://域名/am/*` | 聚合支付页 |
- 三条规则分别配置,前缀按上表(域名 = H5 收银台的部署域名,即支付网关域名);
- 配置时平台会下发**随机校验文件**,同样在运营端上传托管(同第二步);
- 支付宝在开放平台的「扫码进入小程序」做对应配置;
- 商户配置了自己的收银台小程序时,还需为商户级前缀 `/mx/{商户号}/*` 配置对应规则。
规则没配或没命中时,小程序不会被拉起,扫码打开的是 H5 收银台侧页面(引导改用钱包扫码或降级 H5 收款)。这不是故障,但意味着小程序形态未生效——上线后务必用真码全链路验证一遍。
## 第四步:合法域名
在小程序后台把后端接口域名(支付网关域名)加入 **request 合法域名**,否则正式环境请求全部失败(开发工具里勾选「不校验域名」只对调试有效)。
## 第五步:编译、上传与审核
1. 编译对应平台产物并上传(操作详见[跨端应用](https://doc.plus.daxpay.cn/deployment/uniapp.md));
2. 提交平台审核:收款类小程序需如实填写类目与资质;
3. 审核通过后发布。发布后用**真实二维码**验证三条链路(码牌 / 收银台 / 聚合)都能拉起小程序并完成付款。
## 兜底行为与排查
| 现象 | 原因与处理 |
| --- | --- |
| 扫码进的是 H5 页而非小程序 | 二维码规则未命中:检查前缀拼写、域名一致性、小程序是否已发布 |
| 钱包内提示「收款小程序暂不可用」 | 同上(钱包环境命中了 H5 兜底页) |
| 正式环境请求失败 | request 合法域名没配 |
| 域名校验不通过 | 校验文件未上传或传错归属(平台级 / 商户级) |
| 无法上传 / 提审被拒 | AppId 仍为占位值未替换,或类目资质不符 |
## 相关链接
- [小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md):页面与流程详解
- [跨端应用](https://doc.plus.daxpay.cn/deployment/uniapp.md):编译与上传操作
- [网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md):整体上线主线
- [支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md):收银台小程序的平台侧配置
---
# 小程序使用与付款流程
**源**: https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md
# 小程序使用与付款流程
> 收银台小程序是**顾客付款页**:顾客扫商家出示的二维码后被拉起,输入金额(或确认金额)选择支付方式完成付款,付完自动关闭。它**不是**收银员工具,商家侧的操作在商户端 / 商户端 APP 完成。链接在浏览器(而非微信 / 支付宝)打开时,由 [H5 收银台](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md)的收款页承接。发布流程见[小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md)。
## 三种进入方式
对应网关支付的三类码(详见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)):
| 码类型 | 小程序路径 | 顾客看到的页面 |
| --- | --- | --- |
| 码牌(静态牌) | `/m/{码牌编号}` | **输入金额页**:显示商户名,输入金额(固定金额码牌直接确认)、可加备注,然后付款 |
| 聚合扫码 | `/am/{订单号}` | 聚合支付页:确认订单金额后付款 |
| 统一收银台 | `/cm/{订单号}` | 收银台页:展示订单信息,顾客**选择支付方式**(推荐项置顶,可被锁定)后付款 |
二维码是「普通链接二维码」:同一张码在微信内扫码拉起微信小程序、支付宝内扫码拉起支付宝小程序,由平台侧自动适配。若小程序未发布或二维码规则未命中,扫码会落到 [H5 收银台](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md)的兜底页,提示改用钱包扫码。商户配置了自己的收银台小程序时,商户级码牌(`/mx/{商户号}/...` 前缀)拉起的是该商户的小程序,流程相同(两层模型见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md))。
## 付款流程(逐页)
### 码牌收款页
1. 顾客扫码,小程序解析码牌编号并加载信息:码牌名称、副标题「向 {商户简称} 付款」;
2. **随机金额码牌**:数字键盘输入金额(最多两位小数),确认即发起;**固定金额码牌**:金额直接展示,点按钮确认;
3. 备注可选(弹窗输入,50 字以内),随订单传给商家;
4. 所选支付方式需要用户身份时(如微信 JSAPI),自动静默授权获取,顾客无感;
5. 拉起平台支付组件完成付款,页内展示结果,点完成退出小程序。
### 统一收银台页
1. 扫 `/cm/` 码或从订单链接进入,加载订单:标题、金额、订单号;
2. 支付方式列表(图标 + 名称 + 「推荐」标签;被锁定时其余项置灰不可选),默认选中顺序:锁定项 → 推荐项 → 第一项;
3. 确认支付拉起平台支付组件,页内展示结果。展示哪些方式由商户的收银台配置(小程序桶)决定。
### 聚合支付页
加载订单信息后单按钮「确认支付」;支持自动拉起的场景无需再点。付款完成后页内展示结果。
## 支付结果页
付款成功后进入绿色对勾的成功页(附副文案与备案信息),点「完成」退出小程序。结果页是静态结束页——订单状态在付款页内已确认,不做重复查单。
## 授权页(排查工具)
获取当前用户的 openId / userId(缓存 30 分钟,可清除重取)的独立页面。日常付款**不会**进入此页(需要身份时在流程内静默完成);排查 JSAPI 类支付的用户身份问题时手动使用。
## 开发调试
小程序首页提供调试入口:
- **码牌收银**:主功能卡,扫码或手动输入码牌编号直达付款页;
- **统一收银台调试 / 聚合支付调试**:**仅开发模式可见**(生产构建自动移除),扫码或手填订单号直达对应页面;
- **获取用户标识**:进入授权页。
配合商户端「开发调试 → 支付调试(网关)」生成的订单,可以完整调试三类链路,见[开发者调试](https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md)。
## 平台差异
微信 / 支付宝 / 抖音三端页面同构:三个平台的页面分包对称,平台差异统一收敛在小程序的差异层处理,业务逻辑一套。差异仅在平台能力:
- 支付宝端导航栏做透明穿透处理,视觉更沉浸;
- 抖音端支付通道暂未对接,当前以模拟结果联调页面流程,正式收款以微信 / 支付宝为准。
## 相关链接
- [小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md):域名验证、二维码规则与平台审核
- [收银台总览](https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md):H5 收银台的职责与两种形态分工
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md):三类收款链路详解
---
# 收银台总览
**源**: https://doc.plus.daxpay.cn/operation-guide/cashier/overview.md
# 收银台总览
> 收银台是**面向付款人的前端页面集合**,有两种形态:**H5 收银台**(部署在支付网关域名上的独立前端工程)与**收银台小程序**(微信 / 支付宝 / 抖音三平台分别发布)。付款人看到的收款页、通道与授权的回调落地、Web 端的三方登录中转、协议展示,都由 H5 收银台承接。它不只服务手机——电脑浏览器打开的网页收银台同样是它(同一工程内 PC / 移动两套页面自动适配)。后端「端点配置」里的**支付网关前端地址**,指向的就是它。
## 它负责什么
| 职责 | 地址(网关域名下) | 谁在用 | 详见 |
| --- | --- | --- | --- |
| 收款页面(统一收银台 / 码牌 / 聚合) | `/cashier/{订单号}`、`/h/{码牌编号}`、`/aggregate/{订单号}` | 付款人 | [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md) |
| 收款单支付页 | `/b/{收款单号}` | 付款人 | [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md) |
| 支付结果回跳 | `/pay-result/{交易号}` | 付款人 | [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md) |
| 支付认证落地 | `/auth/wechat`、`/auth/alipay`、`/auth/douyin` | 付款人(无感经过) | [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md) |
| 代运营授权落地 | `/isv-auth/alipay` | 商家 | [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md) |
| 三方登录 / 绑定中转 | `/auth/oauth-callback/...` | Web 运营端 / 代理商端 / 商户端登录用户 | [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md) |
| 协议展示 | `/protocol/{类型}` | 付款人 | [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md) |
| 预授权冻结落地(支付宝) | `/preauth/alipay/{预授权号}` | 付款人 | [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md) |
| 邀请注册 / 进件填报落地 | `/register`、`/onboarded` | 受邀商户 | [推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md) |
另有三个**小程序入口的兜底页**:码牌 `/m/{码牌编号}`、聚合 `/am/{订单号}`、收银台 `/cm/{订单号}`——这些链接在普通浏览器里打开时,展示「请用钱包扫码」的引导,不发起支付;在微信 / 支付宝内扫码则由平台规则拉起小程序(见下文分工)。
## 这些地址是谁生成的
H5 收银台上的绝大多数地址**不是前端自己拼的,而是后端按「支付网关前端地址」生成的**:收款链接(预下单返回给商户系统的付款地址)、通道回跳的结果页、认证授权的回跳路径、三方登录的透传入口,全部如此。
因此 H5 收银台必须部署在与端点配置一致的**支付网关域名**之下(菜单路径:运营端 → 系统管理 → 系统配置 → 平台配置 → 端点配置),两边对得上,付款人与登录用户才不会被带到 404。这是它部署上的最大特殊性,详见[收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md)。
## 与收银台小程序的分工
- 微信 / 支付宝 / 抖音内扫商家出示的码 → 拉起**收银台小程序**付款;
- 支付链接在浏览器打开(短信、邮件、网页按钮,手机或电脑均可)→ **H5 收银台的收款页**付款;
- 二维码命中小程序失败(小程序未发布、普通链接二维码规则未配置)→ 落到 H5 收银台侧兜底,提示改用微信 / 支付宝扫码。
三类收款在两种形态下各有一套链接前缀(域名相同,路径不同):
| 收款方式 | H5 收银台(浏览器打开) | 收银台小程序(钱包内打开) |
| --- | --- | --- |
| 码牌 | `/h/{码牌编号}` | `/m/{码牌编号}` |
| 聚合支付 | `/aggregate/{订单号}` | `/am/{订单号}` |
| 统一收银台 | `/cashier/{订单号}` | `/cm/{订单号}` |
plus 的码牌短链分两层:上表为**平台级**前缀(拉起平台公共收银台小程序);商户配置了自己的收银台小程序时,码牌与收款链接使用**商户级**前缀 `/mx/{商户号}/...`(如 `/mx/{商户号}/{码牌编号}`),由该商户小程序的二维码规则拉起,两层模型详见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)。
收银台小程序按微信 / 支付宝 / 抖音**三平台分别注册发布**(同一工程编译三份产物,页面分包对称、付款流程一致),发布流程见[小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md),页面与流程见[小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md)。
## 电脑与手机自适应
同一链接按设备自动展示两套页面:手机浏览器走完整收银流程;电脑浏览器打开统一收银台是网页版收银页,码牌 / 聚合页显示「请用手机扫一扫」引导。调试时可在链接后加 `?device=pc` / `?device=mobile` 强制指定形态。各页面的具体交互见[收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md)。
## 相关链接
- [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md):统一收银台 / 码牌 / 聚合的页面交互
- [认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md):认证落地、代运营授权与三方登录透传
- [收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md):构建、部署与域名契约
- [小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md):钱包内的付款形态
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md):收银页背后的业务链路
---
# 数据分析
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/analytics.md
# 数据分析
> 分析页按时间范围汇总**本商户**的交易数据，从金额、渠道、时段、维度等方向展示图表。**菜单路径**：仪表板 → 分析页。
>
> 统计口径与运营端[数据分析](https://doc.plus.daxpay.cn/operation-guide/admin/analytics.md)一致，区别是数据范围限定本商户、且排名图为维度排名而非商户排名。页面只做聚合展示，需要单笔明细到[支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)查询。
## 时间范围
页面顶部统一切换：今天 / 昨天 / 近 7 天（默认）/ 近 30 天 / 本月 / 自定义日期区间。
预设口径：「近 7 天」**包含今天**在内往前数 7 天；「本月」为本月 1 日至今天。
## 指标卡
顶部六张指标卡，每张附**环比**（与等长的上一个周期比较；上期为 0 且本期有数据时显示「新增」而不是造假百分比）：
| 指标 | 口径 |
| --- | --- |
| 交易总额 | 区间内成交金额合计（元） |
| 交易笔数 | 区间内成交笔数 |
| 客单价 | 成交金额 ÷ 成交笔数 |
| 支付成功率 | 成功笔数 ÷ 总笔数 |
| 退款金额 | 区间内退款金额合计（元） |
| 退款率 | 退款金额 ÷ 成交金额 |
## 图表解读
| 图表 | 看什么 |
| --- | --- |
| 交易趋势 | 按天折线图，可在**交易额 / 交易笔数 / 客单价**三个度量间切换 |
| 支付渠道占比 | 各支付渠道成交金额占比，识别渠道结构变化 |
| 渠道交易量 | 各渠道成交笔数柱状图，与占比图配合看「量与额」是否匹配 |
| 渠道成功率 | 各渠道支付成功率横向条形图，横轴固定 0~100%，**明显偏低的渠道需要排查** |
| 时段分布 | 24 小时交易笔数（按区间天数取日均），安排活动时间与值守人力 |
| 单笔金额区间 | 各金额区间的笔数分布，识别小额高频还是大额低频客群 |
| 退款趋势 | 按天的退款金额走势，配合退款率观察售后压力 |
| 维度交易额排名 | 按**通道商户 / 应用 / 门店**三个维度切换的交易额排名（本商户自己的维度拆解） |
「渠道成功率」发现某渠道明显偏低时，依次检查：该渠道的[通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)是否被停用、[通道路由](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)是否命中了错误的通道商户、[交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md)里该渠道的失败订单报错信息是否集中。仍定位不了时，把时间范围与现象反馈给平台运营协助排查。
## 相关链接
- [商户工作台](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)：每日速览区块
- [支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)：单笔订单查询与处置
- [交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md)：订单与资金单据的完整入口
---
# 应用管理
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md
# 应用管理
> 应用（appId）是商户下的**调用与配置隔离单元**：unipay 接口按应用区分来源，[通道路由](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)、网关支付、收银台等配置都挂在应用维度。**菜单路径**：商户中心 → 支付配置 → 应用管理。
>
> 应用的配置模型与运营端[应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)完全同源（运营端从商户工作台代管同一份数据），本文按商户端自助视角说明。
## 应用列表
应用列表是**卡片网格**（非表格）：每张卡片展示应用名称、appId、启用状态，默认应用置顶并带「默认」标签；点卡片进入该应用的[应用工作台](#应用工作台)。
**新增 / 编辑**只有三个字段：应用名称、状态、默认应用开关（仅编辑态可改）。appId 由系统自动生成（`A` 开头），创建后不可修改。
### 默认应用规则
- 商户的**第一个应用**创建时自动设为默认；至多一个默认应用；
- unipay 请求**不传 appId 时回落默认应用**，显式传 appId 则按传入值路由；
- 列表顶部会提示「有应用但无默认应用」的警告——此时不传 appId 的下单会失败，设一个默认即可。
| 场景 | 后果 |
| --- | --- |
| 停用默认应用 | 不指定 appId 的下单被阻断（页面会二次确认提醒） |
| 删除默认应用 | **被禁止**，先转移默认再删除 |
| 删除应用 | 危险操作，需**手动输入应用名**确认 |
## 应用工作台
从应用卡片进入，页签标题为「{应用名} · 应用配置」，分两组磁贴：
**支付配置**（每张卡独立权限控制）：
| 卡片 | 功能 | 详见 |
| --- | --- | --- |
| 通道路由 | 指定本应用各支付方式走哪个通道商户 | [应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md) |
| 网关支付配置 | 码牌 / 聚合支付在各客户端环境下的路由深度 | [应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md) |
| 收银台配置 | 收银台页面在各环境下的支付方式展示 | [应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md) |
| 异步通知配置 | 业务事件回调地址与订阅事件 | 建设中，见下节 |
| 易支付配置 | 兼容易支付 V1/V2 协议接入 | [易支付插件](https://doc.plus.daxpay.cn/operation-guide/merchant/easypay.md) |
**应用管理**：编辑基本信息、设为 / 取消默认应用（二次确认）、删除应用（红色卡片，强确认）。
### 异步通知配置（建设中）
当前版本该界面**建设中**，工作台卡片带角标且不可点击。开放后将支持配置回调地址（HTTP）或 MQ 订阅（按应用隔离的 Topic）并勾选订阅事件。回调链路的排查现可先用[商户回调推送](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md)页。
## 相关链接
- [应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)：通道路由 / 网关支付配置 / 收银台配置详解
- [应用配置（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)：同一配置的运营代管视角
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：应用在对接主线中的位置
---
# 回调通知
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md
# 回调通知
> 回调相关页面在「回调通知」分区下，分**商户回调推送**与**通道回调记录**两页。回调的机制说明（推送策略、重试节奏、报文结构）统一在[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)中，本文讲商户端的查看与操作。
先分清两条链路：
```mermaid
flowchart LR
A[支付通道
微信/支付宝等] -->|通道回调| B[平台]
B -->|商户回调推送| C[你的业务系统]
```
- **通道回调记录**：支付通道 → 平台的受理记录，用于核对「通道那边到底有没有通知到平台」；
- **商户回调推送**：平台 → 你的业务系统的推送任务，用于核对「平台有没有通知到我」。
## 商户回调推送
**菜单路径**：回调通知 → 商户回调推送。列表展示本商户应用的推送任务（订单号、推送状态、推送次数、最近推送时间等），支持按状态筛选：
- 点击记录查看**推送详情**：请求地址、发送的报文与平台的响应结果，排查「我方接口为什么没接住」的第一站；
- **手动重发**：对推送失败 / 需要重推的记录可手动触发一次重发（有确认框）。重发使用原报文原地址，你的业务系统应按订单号**幂等处理**，重复通知不产生重复入账。
推送地址不是在本页配置的：到[应用工作台](https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md)的**通知配置**里维护每个应用的回调地址，可用[开发者调试](https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md)先行验签联调。
## 通道回调记录
**菜单路径**：回调通知 → 通道回调记录。支付通道 → 平台的回调受理记录，按处理状态筛选，用于对照「通道有结果但订单状态没动」的场景。
通道回调的**原始报文不向商户端开放**（详情页会引导联系平台），需要原始报文取证时联系平台运营获取。
## 常见问题
- **业务系统收不到回调？** 按顺序排查：① 应用工作台 → 通知配置的回调地址是否正确、服务是否公网可达（防火墙 / 白名单放行平台出口）；② 商户回调推送页看该订单有无推送任务、平台侧响应是什么（连接超时还是业务系统返回错误）；③ 地址无误仍收不到，手动重发一次验证链路。
- **订单状态长时间不变，推送也没有记录？** 可能是通道回调未到平台，先在通道回调记录页核对受理状态，再用订单页的「同步」主动拉取通道最新状态兜底。
- **重发会重复扣账吗？** 不会。重发只是把同一份结果通知再推一次，消费侧做好幂等即可。
- **通道回调有记录、商户推送条数对不上？** 正常现象。一条通道回调对应一次首次推送，手动重发会在商户推送侧增加记录但不影响通道侧；两边按各自的「处理状态」核对即可。
## 相关链接
- [回调与通知](https://doc.plus.daxpay.cn/common/notify.md)：推送策略、重试节奏与报文说明
- [回调通知接口](https://doc.plus.daxpay.cn/api/notice/callback.md)：接收侧的报文与应答规范
- [交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md)：订单页「同步」操作的入口
- [开发者调试](https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md)：签名调试辅助验签排查
---
# 通道商户
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md
# 通道商户
> 「通道商户」是你的商户在具体支付通道（微信、支付宝……）侧的收款身份，概念与接入模式见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。本文只讲**商户端自助**的部分：哪些通道参数可以自己维护、在哪里改。**菜单路径**：通道商户。
>
> 通道商户的**创建在运营端**完成（手动创建，或[进件](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)申请通过后自动生成并绑定到你的商户）；商户端不提供新增与删除入口。
## 列表页
列表展示当前商户名下的全部通道商户（因此没有筛选区）：
- **支付产品**列带通道 Logo 与产品名；支持沙箱的产品会显示环境列（沙箱 / 生产，颜色区分）——环境标识是创建时固化的快照，不随产品切换变化；
- **来源**列标识创建方式：**手动创建**（运营端手工配置）或**进件申请生成**（进件通过后自动落地）；
- **启用开关**：停用后该通道商户立即不能收款、路由不再命中；切换有二次确认；
- 商户端**没有删除入口**——不想用了停用即可；删除属于运营端操作（有交易记录的通道商户也不允许删除）。
通过进件线开通的通道商户，其通道参数沿进件体系由平台或代理商维护，商户端通常只做查看与启停；确需调整参数时联系平台运营，走变更申请而不是自行修改。
## 自助维护范围
从列表点「管理」进入通道商户详情页。**详情页按支付产品加载不同的管理界面**，当前支持自助维护的产品：
| 支付产品 | 商户端可自助维护 | 说明 |
| --- | --- | --- |
| 支付宝（直连） | **参数最全**：应用增删改、密钥 / 证书、能力绑定、分账接收方 | 应用管理在详情页内二级页面 |
| 支付宝（服务商） | ISV 代运营授权链接自助生成、分账接收方、改名、启停 | 通道参数在服务商 / 平台侧 |
| 微信（直连） | APIv3 密钥 + 商户证书 + 平台公钥全套、微信应用、能力绑定、分账接收方 | |
| 微信（服务商） | 微信应用、能力绑定、分账接收方、改名、启停 | 服务商密钥在平台侧 |
| 抖音（直连） | 商户私钥 / 序列号 / 加密密钥三件、抖音应用、能力绑定、分账接收方 | |
| 乐刷 | **仅**基本信息查看、改名、微信应用能力绑定 | 通道参数全部由运营配置 |
其余通道（银联商务、拉卡拉、汇付、富友等）的详情页显示「暂不支持」——参数由运营端代配，联系平台运营人员处理。所有通道商户都可以在商户端**改名**与**启停**，不分通道。
## 密钥配置（直连通道）
三个直连产品的密钥入口都在详情页的「密钥配置」卡片：
| 产品 | 需要配置 |
| --- | --- |
| 微信（直连） | APIv3 密钥（`apiKeyV3`）；商户证书 `apiclient_cert.pem`、私钥 `apiclient_key.pem`、平台公钥 `pub_key.pem` 三个 pem 文件上传；证书序列号、公钥 ID |
| 抖音（直连） | 商户私钥、商户序列号、报文加密密钥 |
| 支付宝（直连） | 在应用维度配置（见下节），支持「公钥模式」与「证书模式」两种验签方式 |
密钥保存有二次确认，且**只提交发生修改的敏感字段**——证书文件回显文件名，重传才覆盖。
## 支付宝应用管理
支付宝直连通道商户的详情页内有独立的「应用管理」二级页面（卡片网格 + 新增虚线卡）。每个支付宝应用（对应支付宝开放平台的一个 App）维护：
- **基本信息**：应用名称、应用类型（小程序 / 手机应用 / 网页应用）、支付宝 appId（同通道商户下防重）；
- **密钥配置**：环境跟随通道商户（沙箱 / 生产只读展示）；公钥模式填支付宝公钥 + 应用私钥，证书模式上传三张 `crt` 证书；接口加密密钥选填。
删除应用需要**手动输入 appId 匹配**确认。修改应用类型会自动清除不兼容的能力绑定，页面会提示需要重新配置。
## ISV 代运营授权（支付宝服务商）
支付宝服务商模式下，子商户需要完成一次「代运营授权」，商户可以自助完成：详情页 → ISV 代运营授权卡片 → 「生成代运营授权链接」，出二维码让商户支付宝主账号扫码确认即可。授权状态与授权回调地址在卡片中可见。
## 分账接收方
需要[分账](https://doc.plus.daxpay.cn/common/alloc.md)的通道商户，在详情页「分账接收方」卡片维护接收方名单：新增即绑定、扫码获取账号、重新绑定、改别名、解绑、删除。
两个使用要点：
- **扫码获取账号**：openid / 用户号类型可生成授权二维码让对方扫码回填，微信、抖音需先选定应用（账号与应用维度绑定）；
- **绑定失败会留痕**：失败记录保留并可查看失败原因，修正后「重新绑定」即可。
## 相关链接
- [支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)：通道商户的概念、创建流程与接入模式
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)：进件线如何自动生成通道商户（plus）
- [支付分账](https://doc.plus.daxpay.cn/common/alloc.md)：分账业务与接收方的使用场景
- [通道路由](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)：通道商户如何被路由命中
---
# 对接配置
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md
# 对接配置
> 对接配置是商户调用[开放接口](https://doc.plus.daxpay.cn/api/overview.md)前必拿的凭证：**平台公钥、商户公钥、通信密钥**三件套，以及微信 / 支付宝域名验证需要的**校验文件托管**。**菜单路径**：商户中心 → 业务配置 → 对接配置 / 域名校验文件。
>
> 对接配置是**商户级**配置（全商户只有一套，不按应用区分）；应用级的配置见[应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)。
## 三件凭证
| 凭证 | 用途 | 页面行为 |
| --- | --- | --- |
| 平台公钥 | 提供给你用于**验证平台返回数据与回调的签名**（确认报文确实来自平台） | 只读展示，可复制 |
| 商户公钥 | 你持有配对的私钥、公钥配置到平台，供平台**验证你的请求签名** | 可编辑，支持在线「生成密钥对」 |
| 通信密钥 | AES 对称密钥，用于接口报文的**加密传输** | 脱敏回显，可编辑，支持在线「生成密钥」 |
三件凭证如何参与签名与加密，见[签名机制](https://doc.plus.daxpay.cn/api/signature.md)；SDK 已内置整套流程，接入方式见[接入指南](https://doc.plus.daxpay.cn/api/getting-started.md)。
## 在线生成与轮换
没有现成密钥时可以直接在页面上生成，不必本地装工具：
- **生成密钥对**（RSA）：生成后**私钥只在弹窗中展示一次**，关闭后无法找回——立即复制并妥善保存。已有公钥时重新生成会覆盖原密钥，需二次确认；
- **生成密钥**（AES）：重新生成通信密钥，已有值时同样二次确认。
更换商户公钥或通信密钥后，**所有使用旧密钥的调用方**（业务系统、SDK 实例）都会验签 / 解密失败。轮换前先确认所有对接方都换到了新密钥，再点保存。
保存时只有**发生修改的字段**会被提交：通信密钥在页面上是脱敏回显的，不改动就不会覆盖服务端的真实值——看到掩码不用紧张，这不是「密钥丢了」。
## 域名校验文件
部分支付场景要求收款域名下存在平台校验文件：微信网页授权 / JS 接口安全域名 / 小程序业务域名需要根目录的 `MP_verify_*.txt`；微信「扫普通链接二维码」与支付宝「关联普通二维码」需要与二维码前缀同目录的随机名 txt / 32 位十六进制 html 文件。**菜单路径**：商户中心 → 业务配置 → 域名校验文件。
**上传**：点「上传验证文件」选择文件（只接受 `.txt` / `.html`），并声明**放置路径**档位：
| 放置路径 | 适用场景 |
| --- | --- |
| 根目录 | 微信 `MP_verify_*.txt`（域名类校验） |
| 网关支付 | 微信随机名 txt、支付宝 32 位十六进制 html（二维码前缀类校验） |
| 两处均可 | 默认档，两种访问路径都托管 |
- 上传后系统托管该文件并提供访问；列表可按文件名、验证内容、放置路径检索；
- 编辑**只能改放置路径与备注**，文件名与内容不可改；传错了删除重传即可；
- 删除即失效——支付宝会定期复查校验文件，删除后关联能力立即中断，谨慎操作。
运营端可代管同一份数据（商户管理 → 商户工作台 → 业务配置），两边修改即时生效。
## 相关链接
- [接入指南](https://doc.plus.daxpay.cn/api/getting-started.md)：用三件凭证发起第一笔请求
- [签名机制](https://doc.plus.daxpay.cn/api/signature.md)：公私钥与通信密钥的算法细节
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：完整联调流程与常见报错对照
- [商户管理（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)：运营侧代管视角的凭证说明
---
# 开发者调试
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md
# 开发者调试
> 五个调试工具让你**不写代码**、在页面上发起真实调用，验证自己的配置与签名是否正确。**菜单路径**：开发调试。
>
> 工具使用**真实的商户与应用配置**发起调用（不是沙箱模拟器），产生的订单是真实订单，验证后记得关单或退款。
## 商户端的便利：免选商户
与运营端同款工具相比，商户端的最大差异是**登录态自动绑定本商户**：支付调试（普通/网关/预授权）与认证调试中的商户字段自动回填且只读展示，不必也不能选择其他商户；应用下拉也只列**本商户的启用应用**。对接自测时比运营端少一步、也不会选错商户。
## 支付调试（普通）
模拟你的系统调用统一支付接口发起一笔支付，验证「密钥配置 + 签名 + 路由 + 通道商户」整条链路：
1. **设置商户私钥**：填入[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)中的商户私钥（仅保存在本浏览器，换电脑需重填）；
2. **选路由模式**：
- **跟随通道路由**：选应用 + 支付方式，按[通道路由](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)解析——验证路由配置首选；
- **直接指定**：选通道商户 + 支付能力，跳过路由——隔离排查通道商户本身的问题；
3. **填订单**：订单号可一键生成，金额单位为**分**；JSAPI / 小程序方式需先填 openId（用[认证调试](#认证调试)获取）；付款码场景填 authCode 后支付方式可留空（按码前缀自动识别）；
4. **提交支付**：浏览器本地签名后直调接口，结果弹窗按返回形态渲染（跳转链接 / 二维码 / JSAPI 参数），业务失败也会展示错误码。
## 网关支付调试
验证[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)（收银台 / 聚合扫码）的预下单：选网关类型 → 应用 → 订单信息 → 提交，结果页给出**落地页链接与小程序链接**（各带二维码），扫码即可体验收银台全流程。
## 支付调试（预授权）
商业版实装的预授权链路调试工具：对预授权类接口（授权后的请款、转支付等）发起调试调用，验证预授权相关的密钥与链路配置。免选商户与真实配置的规则与其他工具一致；预授权的业务边界（请款后退款暂不支持等）见[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)。
## 签名调试
排查签名问题的独立工具，不依赖商户配置：
| 页签 | 输入 | 输出 |
| --- | --- | --- |
| 签名生成 | 待签名参数 JSON + RSA 私钥 | 待签名字符串 + 签名值 |
| 签名验证 | 参数 JSON（不含 sign）+ 签名值 + RSA 公钥 | 通过 / 不通过 |
回调验签失败、接口报签名错误时，用它比对两边的签名串拼接是否一致（多为参数排序或编码差异）。
## 认证调试
验证 OAuth 授权链路能否取到 openId（JSAPI / 小程序支付的前置）：选认证类型 → 生成授权链接出二维码 → 手机扫码授权 → 页面自动轮询，成功后展示 openId / userId（复制后粘到支付调试的 openId 字段用）。二维码授权成功即失效，重复测试重新生成。
## 相关链接
- [模拟联调通道](https://doc.plus.daxpay.cn/tools/mock/.md)：真实通道未就绪时，用独立模拟通道跑通支付/退款/分账/预授权与回调全链路
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：完整联调流程与错误对照
- [接口签名](https://doc.plus.daxpay.cn/api/signature.md)：签名规则正典
- [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)：预授权业务说明
- [开发者调试（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md)：含平台级应用场景的工具说明
---
# 支付设备与码牌
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/devices.md
# 支付设备与码牌
> 设备域分**码牌**与**终端**两类，业务模型与操作详解统一在[支付码牌与终端（业务功能）](https://doc.plus.daxpay.cn/common/qrcode.md)中说明，本文只做入口速查。**菜单路径**：设备管理（顶级菜单）。
## 入口对照
| 内容 | 菜单入口 | 说明 |
| --- | --- | --- |
| 码牌 | 设备管理 → 码牌管理 | 码牌由**平台批量制作**后分发给商户，商户在此认领归属、启停与查看二维码详情 |
| 码牌打印模板 | 设备管理 → 我的码牌模板 | 维护本商户的码牌**打印样式模板**，码牌制作 / 补牌时按所选模板输出印刷稿 |
| 系统终端 | 设备管理 → 系统终端 | 系统内的终端台账；「绑定管理」仅查看已关联的通道侧终端，关联由运营在通道终端报备时建立 |
| 通道终端 | 运营端通道商户详情内管理 | 通道侧的终端设备，经绑定与系统终端对应 |
## 码牌管理要点
- **认领制**：商户端没有创建码牌的入口。平台制好牌后分发到商户（平台直接分发，或经代理商的库存划拨），商户在码牌管理中认领并启用，需要新码牌时联系平台运营方；
- **落地程序两类**：每张码牌固定为 H5 收银台或小程序其中一种落地形态（`h5` / `mini`），扫码后按该形态打开对应收银页；
- **牌别**：商户级码牌固定归属本商户（编码含商户号中缀，不可跨商户调拨）；平台级码牌归属可由平台 / 代理商调拨；
- **金额类型**：随机金额（收银台输入）或固定金额（扫码即按牌面金额收款）；
- **应用归属**：码牌可指定绑定到某个应用，未指定时走商户默认应用——路由解析、收银台展示都按该应用的[支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)生效；
- 列表按码牌编码 / 名称 / 批次号、绑定商户与门店、金额类型、状态筛选，点击码牌可查看二维码详情与完整扫码链接。
## 码牌打印模板
设备管理 → 我的码牌模板维护本商户可用的**打印样式模板**：牌面文案、门店信息、二维码位置等版式要素。码牌制作 / 补牌时按所选模板输出印刷稿，一商多套模板可对应不同门店或场景的牌面。
模板只影响**印刷样式**，不影响码牌的收款路由与金额口径；线上投放（朋友圈 / 群发图片）直接用码牌详情里的扫码链接即可。
## 系统终端与通道终端
- **系统终端**：平台侧的终端台账（编号、名称、状态）。云喇叭、收银插件等设备由运营在通道侧登记时直接关联到某个系统终端（报备即绑定）；「绑定管理」只读，可查看本终端已关联的通道侧终端。一个系统终端在同一通道商户下按报送类型（通用 / 微信 / 支付宝 / 银联）各对应一条通道终端；
- **通道终端**：通道侧的终端设备，在运营端的通道商户详情内管理，商户侧经绑定关系间接使用。
## 常见问题
- **扫码后打不开收银页？** 先确认码牌处于「启用」状态，再检查对应应用的[网关支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)是否覆盖了当前客户端环境。
- **码牌可以换绑到其他门店吗？** 码牌可绑定到门店（见详情页），但商户级牌不能划给其他商户；更换归属联系平台运营方。
- **云音箱不播报？** 到系统终端页确认设备已关联通道终端且状态启用；关联错位请联系运营在通道商户的「终端台账」中注销后重新报备。
- **想用手机播报、不买云音箱？** 用安卓手机装收款播报 APP 即可替代音箱与小票打印机，见[配套工具总览](https://doc.plus.daxpay.cn/tools/.md)。
## 相关链接
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)：码牌模型、归属调拨与终端绑定的完整说明
- [应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)：码牌扫码后的路由去向配置
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)：码牌收款的业务链路
---
# 易支付插件
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/easypay.md
# 易支付插件
> 易支付（Epay）是国内聚合站点的通用兼容协议。开启后，现有易支付程序**不改代码**即可把下单地址指向 DaxPay 运行。**菜单路径**：配置在应用工作台 → 易支付配置；订单查询在扩展插件 → 易支付。
>
> 协议背景与「和普通订单的区别」见运营端[易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)篇；配置是**应用级**，每个应用独立开关。
## 启用与密钥配置
入口：[应用工作台](https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md) → 易支付配置。页面三段：
| 段 | 配置 |
| --- | --- |
| 基础对接 | 总开关、商户号 `pid`（只读 + 复制）、V2 / V1 网关地址（只读 + 复制，给对接方填） |
| V1 协议 | 启用开关 + MD5 密钥（V1 是简单的 MD5 签名，安全性弱，仅老程序需要时开启） |
| V2 协议 | 启用开关 + 「使用系统密钥」开关——开启则直接复用[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)的 RSA 密钥对；关闭则单独生成一对 |
**RSA 密钥对在线生成**：已有公钥时重新生成会二次确认（覆盖原钥）；公私钥会去掉 PEM 头尾转成纯 Base64（易支付协议要求）；**私钥仅在弹窗展示一次**，立即复制保存。
保存有二次确认，密钥字段未修改不会重复提交。
## 易支付订单
扩展插件 → 易支付 → 易支付订单：按商户订单号、平台订单号、商品名、状态、支付方式、创建时间查询；操作有查看详情、同步、关单（同步与关单有确认框）。
**易支付退款**页同构：按退款号、商户退款号、订单号、状态查询，支持同步。
易支付协议金额单位为**元**（两位小数），与 unipay 接口的「分」不同——页面上展示的就是元，不需要换算。
## 对接方需要填什么
把以下三项交给运行易支付程序的对接方，替换其原有支付网关配置即可（其余业务代码不动）：
| 参数 | 取值来源 |
| --- | --- |
| 商户号（pid） | 易支付配置页只读展示，一键复制 |
| 网关地址 | V2 / V1 网关地址按所选协议复制 |
| 密钥 | V2 填 RSA 公钥（V1 填 MD5 密钥），与协议版本对应 |
## 常见问题
- **V1 还是 V2？** 优先 V2（RSA 签名，安全性强）；只有对接方是仅支持 MD5 的老程序时才开 V1。两者可同时开启，分别走各自的网关地址。
- **改了密钥老订单会受影响吗？** 密钥只影响后续请求的验签，已有订单的查询 / 同步 / 退款照常进行。
## 相关链接
- [易支付插件（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)：协议背景、与普通订单的区别
- [易支付对接](https://doc.plus.daxpay.cn/api/epay.md)：接口侧的协议参数说明
- [应用管理](https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md)：配置所属的应用与工作台
---
# 商户资料与门店
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md
# 商户资料与门店
> 本组页面维护**本商户**的基础档案：商户资料是收款身份，门店是收款与对账的物理归属单元（不传门店号的交易回落默认门店）；**实名认证**与**风控与限额**是商户中心的另两张自助页。**菜单路径**：商户中心 → 基础管理。
>
> 同组的[商户用户](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md)（子账号）单独成篇。
## 商户资料
本商户的基础信息页：
| 字段 | 可否修改 |
| --- | --- |
| 商户号 | 只读（系统分配，对接时使用） |
| 主体类型 | 只读（开通时由运营确定） |
| 商户简称 | **可改**（必填，展示在收银台与账单等对客场景） |
| 状态 | 只读（商户启停由运营端控制，需调整联系运营） |
## 门店管理
门店列表按门店名称、门店号、状态查询，展示默认门店标记与「省市区 + 详细地址」拼接的完整地址。
**表单字段**：门店名称、状态、联系电话、所在地区（省 / 市 / 区级联）、详细地址、经纬度（供地图场景）、门店门头 / 内景图片、备注。
**默认门店规则**（与[应用管理](https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md)的默认应用同构）：
- 不传门店号的交易回落默认门店；
- **默认门店不可删除**——先设其他门店为默认；
- 默认门店停用前页面会二次确认；
- 有门店但无默认时列表顶部出黄色警告。
运营端可从商户工作台代管同一份数据，两边修改即时生效。
## 实名认证
商户端的自助实名页（plus 提供）。平台开启实名门禁后，需要先完成实名认证才能继续使用相关功能；平台未开启时页面显示空态提示，无需操作。
**认证流程**（当前支持支付宝实名核验）：
1. 填写**真实姓名**与 **18 位身份证号**，提交认证；
2. 页面弹出二维码，用支付宝 App 扫码并确认授权；
3. 页面自动轮询认证结果，无需手动刷新；通过后显示认证结果卡（真实姓名、身份证号、认证方式、认证时间）。
提交的信息加密存储、仅用于身份核验；认证失败会展示失败原因，修正后可重新提交。
## 风控与限额
只读查看本商户「生效中的」风控与限额状态，四个区块：
| 区块 | 内容 |
| --- | --- |
| 当前生效限额 | 按方向（支付 / 退款）× 周期（单笔 / 日累计 / 周累计 / 月累计）列出单笔下限、金额上限、笔数上限；「来源」列区分**自定义**与**平台默认** |
| 今日 / 本周 / 本月用量 | 与限额校验同口径的成功累计读数，有上限的维度附进度条 |
| 风控参与状态 | 地理围栏校验是否参与、每 IP 每日支付笔数上限（商户级专属值） |
| 风控拦截记录 | 时间、阶段、拦截类型、命中标识、支付单号、IP 城市、门店城市，支持分页查询 |
规则要点：
- 商户自定义限额**优先**生效；未配置支付规则时整体使用平台默认模板；超出限额的订单在下单时被拒绝；
- 拦截记录中的命中标识做**掩码展示**，完整值仅平台侧留存，兼顾排障与隐私；
- 本页**只读**——限额与风控策略由平台（或按平台安排由代理商）配置，需要调整联系平台运营。
## 常见问题
**实名认证页提示「平台未开通实名认证服务」？**
门禁开关由平台运营控制，未开启时无需认证；确有需要联系平台运营。
**下单被限额拦截了怎么办？**
先到「风控与限额」页看用量是否已接近上限（进度条）；确需放宽限额，联系平台运营调整限额配置。
**命中标识为什么看不全？**
出于隐私保护做了掩码处理；如需核对完整值，由平台运营在风控命中记录中查询。
## 相关链接
- [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)：三级限额配置的完整口径（plus）
- [风控策略与处置](https://doc.plus.daxpay.cn/plus/risk-control/policy.md)：平台侧风控策略、黑名单与命中记录（plus）
- [商户用户](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md)：同组的子账号管理
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)：码牌 / 终端可归属门店
---
# 商户用户
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md
# 商户用户
> 商户用户是**本商户**的登录账号（区别于平台运营账号）：给收银员、财务、店长分别开账号并按角色授权，各自登录商户端只看到职责内的菜单。**菜单路径**：商户中心 → 基础管理 → 商户用户。
>
> 账号规范与运营端[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)同构；角色是**商户端角色集合**，与运营端角色互不相通。
## 新增用户
表单字段：姓名、账号、密码（留空自动生成初始密码，结果页一次性展示）、**角色**（单选）。
角色下拉**默认选中内置的「商户普通用户」角色，创建时即绑定**——新账号登录后不会面对空菜单。需要不同权限时在创建时改选，或创建后在列表里「分配角色」。
## 日常操作
| 操作 | 说明 |
| --- | --- |
| 查询 | 按姓名、账号、状态筛选；列表含身份列（商户管理员显示金色标签，普通用户显示角色名） |
| 编辑 | 修改姓名；邮箱只允许用户本人在[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)走绑定流程变更 |
| 分配角色 | 单选角色；下拉只列出**你有权分配**的角色集合 |
| 重置密码 | 生成新初始密码，结果页一次性展示，转告用户后尽快修改 |
| 封禁 / 解锁 | 封禁后账号立即无法登录；连续输错密码触发的锁定也可在此解锁；支持批量封禁 / 解锁 |
**商户管理员**角色固定不可变更，且管理员账号**不可封禁**（封禁会导致商户失管，页面直接拦截）。需要更换管理员时，先建好新账号、交接完再处理旧账号。
## 角色从哪来
商户端角色由运营端预置并授权（角色 - 菜单体系在运营端维护），商户端只能把**已开放给你的角色**分配给子账号。需要新角色或调整角色的菜单范围时，联系平台运营。
## 常见问题
**新账号登录后菜单是空的？**
新增时默认绑定内置「商户普通用户」角色，正常不会为空；若确实为空，多为该角色未被授权任何菜单，联系平台运营检查角色的菜单范围。
**商户管理员和普通用户有什么区别？**
商户管理员是创建商户时生成的负责人账号，可管理子账号、分配角色，角色固定不可变更；普通用户按所分配角色看到职责内的菜单。
**被封禁的账号还能找回吗？**
可以，封禁只拦截登录不删数据；管理员在列表中「解锁」或重新启用即可恢复。
## 相关链接
- [用户管理（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)：账号体系全景与密码策略
- [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)：用户本人改密码、绑邮箱、开两步验证
- [商户端使用入门](https://doc.plus.daxpay.cn/operation-guide/merchant/overview.md)：功能地图与常见任务入口
---
# 交易订单管理
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md
# 交易订单管理
> 商户端的交易查询与操作集中在「交易订单」「回调通知」两个分区，各页面的**操作详解**（查单、同步、关单、退款、导出、异常处置等）统一在[业务功能](https://doc.plus.daxpay.cn/common/overview.md)中说明，本文只做入口对照。
>
> 所有列表**只能看到本商户的数据**（登录态强制，无商户筛选）；时间列统一按东八区显示；支持导出的页面导出为 Excel。
## 入口对照
| 我想… | 菜单入口 | 详见 |
| --- | --- | --- |
| 查一笔钱到账没有（资金交易） | 交易订单 → 支付交易 | [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md) |
| 按下单渠道查（普通 / 网关） | 交易订单 → 支付订单 → 普通订单 / 网关订单 | [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md) |
| 发起 / 查询退款 | 交易订单 → 退款订单 | [退款管理](https://doc.plus.daxpay.cn/common/refund.md) |
| 查分账单 | 交易订单 → 分账订单 | [支付分账](https://doc.plus.daxpay.cn/common/alloc.md) |
| 查资金收支明细（对账） | 交易订单 → 资金流水 | [异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md) |
| 处置关单后又收款的订单 | 交易订单 → 异常订单 | 见下方说明 |
| 处理用户投诉 | 交易订单 → 投诉工单 | 见下方说明 |
| 查预授权订单（授权 / 请款 / 转支付） | 交易订单 → 预授权订单 | [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md) |
| 查微信支付分订单 | 交易订单 → 支付分订单 | [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md) |
| 给客户远程开单催款 | 交易订单 → 收款单 | [收款单](https://doc.plus.daxpay.cn/common/receivable-bill.md) |
| 查回调推送记录 | 回调通知 → 商户回调推送 | [回调通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md) |
| 查通道侧回调受理记录 | 回调通知 → 通道回调记录 | [回调通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md) |
其中**投诉工单、预授权订单、支付分订单、收款单**为商业版增强能力，开源基础版不含。
## 异常订单与投诉工单
- **异常订单**：本地已关单 / 撤销但通道实际收了款的资金记录。商户端**只能查看**（含通道回调原始报文），处置动作（确认、退回等）由平台运营执行——发现异常记录请联系运营处理；
- **投诉工单**：用户通过支付渠道（微信 / 支付宝等）提交的投诉单。商户端查看投诉内容并在处理时限内跟进处置，平台运营端可看到全量工单协同督办。
## 回调通知分区
回调相关两个页面的商户视角说明（含**手动重发**操作）见[回调通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md)：
- **商户回调推送**：平台 → 你的业务系统的推送任务记录；
- **通道回调记录**：支付通道 → 平台的回调受理记录（按处理状态筛选），**原始报文不向商户端开放**，需要原始报文时联系平台获取。
## 说明
- 三层订单模型（支付订单 / 支付交易 / 通道单）的概念见[支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)开篇——查账优先用「支付交易」，它是资金视角的唯一真相；
- 各列表支持时间 / 状态 / 单号组合查询与导出；
- 运营端「交易管理」分区是同构的全商户视图，代理商端「订单查询」则是名下商户视角（只读）。
## 相关链接
- [业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)：各订单类型的操作详解
- [回调通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md)：回调两个页面的商户视角说明
- [退款管理](https://doc.plus.daxpay.cn/operation-guide/merchant/refund.md)：退款的入口与流程速查
---
# 商户端使用入门
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/overview.md
# 商户端使用入门
> 商户端是**商户自助**使用的管理平台：日常交易查询与退款在这里，对接密钥、通道商户、收银台等配置也可以在这里自助完成（运营端商户工作台提供同数据的代管入口）。
>
> 登录账号由运营方创建商户时生成（初始密码只展示一次），也可以由平台或代理商通过邀请注册自助开通。首次登录后请及时修改密码并建议开启两步验证（右上角头像 → [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md) → 安全设置）。
## 功能分区总览
商户端侧边栏按业务域分为八个分区：
| 分区 | 包含功能 | 说明 |
| --- | --- | --- |
| 仪表板 | 工作台、分析页 | 交易概览、快捷入口、公告；多维交易分析 |
| 商户中心 | 基础管理 / 支付配置 / 业务配置 三组 | 商户自助配置的核心 |
| 通道商户 | 通道商户列表与详情管理 | 各支付通道的收款身份与密钥 |
| 设备管理 | 码牌管理、系统终端、我的码牌模板 | 收款物料与终端 |
| 交易订单 | 支付交易、退款订单、支付订单（普通 / 网关）、分账订单、收款单、预授权订单、支付分订单、异常订单、投诉工单、资金流水 | 日常交易操作 |
| 回调通知 | 商户回调推送、通道回调记录 | 回调链路自查 |
| 开发调试 | 支付调试（普通 / 网关 / 预授权）、签名调试、认证调试 | 不写代码验证支付链路 |
| 扩展插件 | 易支付（易支付订单 / 易支付退款） | 兼容协议接入 |
**商户中心**三组：
- **基础管理**：商户资料、[商户用户](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md)（子账号）、门店管理、[风控与限额](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md#风控与限额)（只读）、[实名认证](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md#实名认证)；
- **支付配置**：[应用管理](https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md)（应用工作台内含通道路由 / 网关支付配置 / 收银台配置 / 易支付配置）、微信应用、抖音应用、收银台小程序；
- **业务配置**：[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)（API 签名与加密密钥）、域名校验文件。
另有「操作记录」隐藏页（不在侧边栏），从[工作台](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)的快捷入口进入，记录本商户的关键业务操作。
**个人中心**（右上角头像进入）：基本资料、修改密码、邮箱绑定、三方账号绑定、通行密钥、双因素认证——功能与运营端一致，见[个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md)。
## 常见任务入口
| 我想… | 去哪里 |
| --- | --- |
| 拿对接密钥（私钥 / 平台公钥 / 通信密钥） | 商户中心 → 业务配置 → [对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md) |
| 查今天的收款 | 仪表板 → [工作台](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)，或交易订单 → 支付交易 |
| 给某一笔退款 | 交易订单 → [退款订单](https://doc.plus.daxpay.cn/operation-guide/merchant/refund.md) |
| 配置收款通道的密钥参数 | 通道商户 → [通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md) |
| 看哪些通道参数能自己改 | [通道商户 - 自助维护范围](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md#自助维护范围) |
| 决定一笔支付走哪个通道 | 商户中心 → 支付配置 → [应用管理](https://doc.plus.daxpay.cn/operation-guide/merchant/app-manage.md) → 通道路由 |
| 配收银台展示哪些支付方式 | 应用工作台 → [收银台配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md) |
| 给店长 / 收银员开账号 | 商户中心 → 基础管理 → [商户用户](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md) |
| 完成实名认证 | 商户中心 → 基础管理 → [实名认证](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md#实名认证) |
| 查限额用量 / 被风控拦截的记录 | 商户中心 → 基础管理 → [风控与限额](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md#风控与限额) |
| 查回调发出去了没有 | 回调通知 → [商户回调推送](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md) |
| 查我有哪些收款码 | 设备管理 → [码牌管理](https://doc.plus.daxpay.cn/operation-guide/merchant/devices.md) |
| 看交易趋势和渠道成功率 | 仪表板 → [分析页](https://doc.plus.daxpay.cn/operation-guide/merchant/analytics.md) |
| 试试支付通不通 | 开发调试 → [支付调试](https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md) |
| 改密码 / 开两步验证 | 右上角头像 → [个人中心](https://doc.plus.daxpay.cn/operation-guide/admin/profile.md) |
## 和运营端的关系
商户端与运营端[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)的商户工作台大量页面互为镜像（应用管理、通道商户、对接配置等），数据同源、任一端修改即时生效。区别在于：
- 商户端只能操作**自己商户**的数据，天然隔离；
- 商户创建、商户启停、进件审核、归属调拨等平台动作只在运营端出现；
- **通道商户的创建只在运营端**——运营端手动创建，或由[进件](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)申请通过后自动生成；商户端只做自助维护（密钥、改名、启停等），不提供新增与删除入口；
- 挂靠代理商的商户，通道相关事务也可以由代理商（服务商）侧协助维护，具体分工以平台运营的安排为准；
- 少数页面与原始报文只开放给运营端（如通道回调原始报文），见对应页面说明。
## 相关链接
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：商户端视角的上线主线
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：对接配置凭证的使用
- [业务功能](https://doc.plus.daxpay.cn/common/overview.md)：订单、退款、分账等操作详解
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)：通道商户的进件开通线（plus）
---
# 应用支付配置
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md
# 应用支付配置
> 应用工作台里有三个容易混淆的配置：**通道路由**（底层路由策略）、**网关支付配置**（网关链路用多深的路由）、**收银台配置**（收银台页面展示什么）。本文逐个说明。**菜单路径**：商户中心 → 支付配置 → 应用管理 → 应用工作台。
>
> 三个配置都是**应用级**——换一个 appId 就是一套独立配置；商户级凭证见[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)。
初次配置建议：**先配通道路由**，网关支付配置保持「自动」，收银台按需调整展示。配完可用[开发者调试](https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md)发一笔验证。
## 通道路由
决定「某笔支付走哪个通道商户」的基础配置。**菜单路径**：应用工作台 → 通道路由。
两种策略模式**二选一生效**，工具栏可「启用该模式」切换（二次确认，当前生效模式带「生效中」标签）：
| 模式 | 配置粒度 | 适合 |
| --- | --- | --- |
| 基础模式（按渠道默认） | 每个支付渠道（聚合支付 / 微信 / 支付宝 / 银联 / 抖音等）配一个默认通道商户 | 单通道或简单主备 |
| 场景模式（按支付方式） | 每个支付方式（`wechat_jsapi`、`alipay_qr` …）配「通道商户 + 支付能力」 | 不同方式走不同通道的精细分流 |
- 基础模式的下拉候选来自该渠道下**已配置的通道商户**，没有候选说明还没开通对应通道（见[通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)，或联系平台运营方通过[进件](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)开通）；
- 场景模式的两级联动（通道商户 → 支付能力）中，能力候选随商户切换刷新，只填一半视为不完整。
## 网关支付配置
码牌、聚合扫码等**网关链路**的路由深度配置。**菜单路径**：应用工作台 → 网关支付配置。**码牌与聚合扫码共用这一份配置**，不必分开设。
配置维度是「**客户端环境 × 支付形态**」矩阵：微信 / 支付宝 / 云闪付 / 抖音四种环境 × H5 / 小程序两种形态。整页先选**配置深度**（三档 radio）：
| 深度 | 语义 |
| --- | --- |
| 自动 | 每格使用系统默认支付方式（微信环境走 `wechat_jsapi` / `wechat_mini`、支付宝 H5 默认 `alipay_qr` 免 OAuth 等），推荐起点 |
| 按支付方式 | 逐格下拉指定支付方式 |
| 直接指定 | 逐格直接选「通道商户 → 支付能力」，跳过路由（排错 / 特殊场景） |
页面内置两个辅助块：
- **路由命中预览**：每格实时显示「命中的通道商户 / 能力」或「未配置」，不用真的扫码就能预判落到哪；
- **覆盖摘要**：顶部显示已配置格数与缺口（「同环境另一形态已配」的格子会橙字列出），并可一键跳转[通道路由](#通道路由)补配。
「按支付方式」和「直接指定」模式下至少要配一行，全部留空无法保存。保存有二次确认。
## 收银台配置
配置**统一收银台**页面在各环境下展示哪些支付项。**菜单路径**：应用工作台 → 收银台配置。
桶结构一级分 **H5 / WEB / 小程序**三种终端：H5 按客户端环境分五桶（浏览器 / 微信 / 支付宝 / 云闪付 / 抖音），小程序四桶（无浏览器），WEB 不分桶。每个桶内维护支付项列表：
| 字段 | 说明 |
| --- | --- |
| 名称 / 图标 | 收银台上显示的按钮文案与图标；「按支付方式」解析时图标自动跟随该方式的渠道图标 |
| 推荐标记 | 绿色标签，引导用户优先选择 |
| 排序 | 桶内展示顺序 |
| 解析模式 | **按支付方式**（走[通道路由](#通道路由)解析，适合常规场景）或**直接指定**（固定「通道商户 + 能力」，跳过路由） |
删除支付项为危险操作，有二次确认。
## 常见问题
- **基础模式下拉里没有候选通道商户？** 说明该渠道尚未开通或未配置通道商户，先到[通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)确认；进件类通道需由平台运营方发起[进件申请](https://doc.plus.daxpay.cn/plus/onboarding/process.md)。
- **码牌扫出来提示「未配置路由」？** 网关支付配置处于「按支付方式 / 直接指定」深度但对应环境形态的格子留空，回到覆盖摘要查看缺口并补配。
## 相关链接
- [通道路由（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)：路由策略的运营视角说明
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)：统一收银台 / 聚合扫码的业务说明
- [通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)：路由候选「通道商户」的来源
- [开发者调试](https://doc.plus.daxpay.cn/operation-guide/merchant/develop-tools.md)：配完发一笔验证
---
# 退款管理
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/refund.md
# 退款管理
> 退款支持**页面操作**与**接口调用**两种方式，操作详解统一在[退款管理（业务功能）](https://doc.plus.daxpay.cn/common/refund.md)中说明。
## 快速上手
- **页面退款**：交易订单 → 支付交易，找到对应交易后发起退款（支持部分退款，退款金额受可退余额约束）；
- **接口退款**：业务系统调用 unipay 退款接口，见[退款接口](https://doc.plus.daxpay.cn/api/payment/refund.md)；
- **查进度**：交易订单 → 退款订单；状态长时间未变可手动「同步」拉取通道最新状态；
- **手动关闭**：退款中且**超过 7 天**未收到通道确认的退款单，可在退款订单页手动关闭（危险操作，二次确认）。
退款成功与否以**通道回调**为准；本地收不到回调时用「同步」兜底，与支付订单的处理方式一致。
## 退款订单页操作
交易订单 → 退款订单，列表按退款号 / 关联订单号 / 状态 / 时间组合查询，操作列提供：
- **查看**：退款单详情（金额、通道、原因、完成时间）；
- **同步**：向通道拉取最新状态（长时间停留「退款中」时使用）；
- **关闭**：仅对超过 7 天未确认的退款单开放（危险操作，二次确认）。
退款单的状态枚举与流转（退款中 / 成功 / 失败 / 关闭）见[交易状态](https://doc.plus.daxpay.cn/getting-started/codes/trade-status.md)字典，速查：
| 状态 | 含义 | 下一步 |
| --- | --- | --- |
| 退款中 | 已受理，等通道确认 | 等回调或手动「同步」 |
| 成功 | 通道已确认退回 | 资金流水可查 |
| 失败 | 通道拒绝 / 受理异常 | 按详情错误信息处理后重试 |
| 关闭 | 超期手动关闭或系统关闭 | 终态，不可再操作 |
商业版对退款设有**日累计限额兜底**（防批量退款搬钱），触发拦截时页面会提示限额来源，可联系平台运营方核增。
## 常见问题
- **退款失败常见原因？** 通道侧商户账户余额不足、超出通道允许的可退期限、订单本身未支付成功——按详情页的错误信息对照处理。
- **多次部分退款怎么算？** 每次退款的金额受「可退余额 = 订单金额 − 已退总额」约束，各笔退款单独立流转、独立对账。
- **预授权订单的退款？** 预授权类订单的退款边界（如请款后退款暂不支持）见[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)，与普通订单不同。
## 相关链接
- [退款管理详解](https://doc.plus.daxpay.cn/common/refund.md)：退款规则、部分退款与常见问题
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)：可退余额的来源
- [交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md)：退款订单页的入口对照
---
# 商户工作台
**源**: https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md
# 商户工作台
> 工作台是登录商户端后看到的第一个页面，聚合**配置待办提醒**、本商户核心统计与日常高频入口。**菜单路径**：仪表板 → 工作台。
>
> 页面结构与运营端[运营工作台](https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md)同构，只是统计与入口面向**本商户**；它只做速览与跳转，完整查询在业务页面完成。
## 页面构成
| 区块 | 内容 |
| --- | --- |
| 配置告警横条 | 本商户未完成的配置项，点击直达处理（无待办时不显示） |
| 工作台头部 | 问候语、当前登录用户、三项统计：**应用数 / 门店数 / 通道商户数** |
| 快捷入口 | 可自定义的高频功能入口卡片 |
| 交易概览 | 今日 / 昨日的成交金额、成交笔数、退款金额、退款笔数 |
| 资金交易 | 最近交易明细，点条目进[支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)详情 |
| 系统公告 | 平台发布的公告与个人消息，点击查看 |
| 支付渠道分布 | 近 7 天 / 30 天各支付渠道的成交金额占比 |
| 交易趋势 | 近 7 天 / 30 天成交金额走势 |
## 配置告警横条
有未完成配置时顶部出现配置待办提示条，点击展开列表、点击条目跳转对应配置页。本商户的检查项包括：
- **商户应用**：尚未创建或启用任何商户应用；
- **API 凭证**：商户通信凭证（公钥 / 密钥）未生成；
- **通道商户**：尚未配置任何启用的通道商户；
- **支付路由**：部分应用尚未配置支付路由策略；
- **通知配置**：部分应用未配置回调通知地址。
两个行为细节：
- 提示条上的关闭只是**当次会话不再显示**，重新登录后还会出现；处理完配置后刷新即自动消失；
- 个别待办对应的页面如果尚未对你的角色开放，列表中会**置灰不可点**，联系运营处理。
## 快捷入口
默认展示十一个入口：个人中心、通知中心、分析页、商户资料、应用管理、微信应用、抖音应用、对接配置、支付交易、支付调试、操作记录。
点「编辑」可自定义：已选区拖拽排序、可移除；可选区可追加商户用户、门店管理、码牌管理、系统终端、通道商户、域名校验文件等。保存后按你的顺序展示，无权限的入口自动隐藏，其他账号不受影响。
「操作记录」是隐藏菜单页，侧边栏不显示，从工作台快捷入口进入——记录本商户关键业务操作的日志（谁在什么时间做了什么），便于自助追溯与配合平台审计。
## 交易与公告区块
- **交易概览**按「今日 / 昨日」切换，每天开工先扫一眼；
- **资金交易**列出最近交易（含资金状态标签），异常资金状态可点进[支付交易](https://doc.plus.daxpay.cn/common/payment-order.md)追查；
- **系统公告**点击阅读后自动标记已读，顶栏铃铛未读数同步减少（公告与消息的完整列表在铃铛 → 查看全部的**通知中心**）。
## 相关链接
- [数据分析](https://doc.plus.daxpay.cn/operation-guide/merchant/analytics.md)：多维度的交易分析报表
- [商户端使用入门](https://doc.plus.daxpay.cn/operation-guide/merchant/overview.md)：功能地图与常见任务入口
- [日志与监控（运营端）](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)：业务操作日志的平台侧全景
---
# 网关收款上线
**源**: https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md
# 网关收款上线
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的第五阶段，也是**只在网关收款场景才需要**的阶段：让付款人可以不经过商户自己的页面，直接在平台托管的收银页/码牌上付款。
>
> 五个环节（H5 收银台部署 → 域名验证 → 网关支付配置 → 码牌 → 收银台小程序发布）分别在不同页面配置，本篇按上线顺序把它们串起来。每环节末尾链接到对应的详解文档。
## 先选收款形态
| 形态 | 付款人体验 | 需要本篇哪些环节 | 适合 |
| --- | --- | --- | --- |
| **API 直连** | 商户自己的页面/系统完成支付 | 都不需要（跳过本篇） | 有开发能力的业务系统，见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md) |
| **统一收银台** | 打开平台托管收银页，自选支付方式 | 环节 1~3（+5 若要小程序内收银） | PC/H5 商城、账单收款 |
| **聚合扫码** | 印制静态码，微信/支付宝等扫码自动识别支付 | 环节 1~3 + 环节 4（+5） | 线下桌牌/贴纸/立牌 |
| **码牌** | 聚合扫码的物理承载 | 同上（码牌即聚合扫码入口） | 线下门店 |
```mermaid
graph LR
A[1 H5 收银台部署] --> B[2 域名验证]
B --> C[3 网关支付配置]
C --> D[4 码牌制作认领]
C --> E[5 收银台小程序发布]
D --> F[真码全链路验收]
E --> F
```
本篇假定[支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md)已完成（生产通道商户 + 密钥 + 路由）。网关支付的路由解析依赖应用路由，路由没配好，网关页面打开也无法付款。
## 环节一：H5 收银台部署
H5 收银台是独立前端工程，承载统一收银台、聚合扫码、认证中转等**面向付款人**的页面（PC/移动双形态）。部署方式随主部署路径：
| 部署路径 | H5 收银台 | 你要做的事 |
| --- | --- | --- |
| 运维面板（主流） | 面板托管部署 | 面板域名绑定中填好支付网关域名（如 `h5.example.com`）即可 |
| 源码静态部署 | 独立构建静态产物 | 自行 nginx 托管：静态托管 + `/api/` 反代 + **SPA 回退**（`try_files ... /index.html`）+ HTTPS，示例见[项目构建 - 静态部署](https://doc.plus.daxpay.cn/deployment/build.md#静态部署) |
**域名契约（本环节的核心）**：收款链接、支付结果回跳、认证回调地址**全部由后端按「端点配置的支付网关前端地址」生成**，不是前端自己拼的。因此：
- H5 部署域名必须与[端点配置](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#端点配置)的「支付网关前端地址」**严格一致**；
- 不一致的后果：付款成功后回跳 404、微信/支付宝授权回调失败、三方登录跳转丢失（地址清单见[收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md)）。
## 环节二：域名验证
微信/支付宝要求域名完成归属验证后才允许在其生态内使用（JSAPI 支付目录、小程序业务域名、二维码规则）。**两场景两入口**，网关侧应答反代已在[基础设施](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md#域名验证文件的网关侧预留)预留：
| 场景 | 上传入口 | 触发时机 |
| --- | --- | --- |
| 平台级（支付宝 `.html` / 微信 `.txt`） | 运营端 → 支付管理 → 接入配置 → 域名校验文件 | 环节五配置「普通链接二维码规则」时平台下发；支付宝「关联普通二维码」同理 |
| 商户级（`MP_verify_*.txt`） | 商户端/商户工作台 → 业务配置 → 域名校验文件 | 商户自己的公众号网页授权、小程序业务域名验证 |
机制详解见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 环节三：网关支付配置与收银台配置
网关支付配置是**应用级**的（每个应用独立一套），入口：商户端 → 商户中心 → 支付配置 → 应用管理 → 应用工作台 → **网关支付配置**（运营端在商户工作台同位）。
配置分两层，职责不同（配置模型详解见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)与[应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)）：
- **网关支付配置（路由层，决定「能不能付」）**：配置维度是「打开环境（微信/支付宝/云闪付/抖音）× 形态（H5/小程序）」矩阵，三档深度：**跟随通道路由（auto，推荐起步）→ 指定支付方式（method）→ 直接指定（direct）**。生产上线建议从 auto 起步，用**路由命中预览**逐格核对命中的通道商户与缺口，有缺口跳「通道路由」补配；
- **收银台配置（展示层，决定「长什么样」）**：按终端分桶配置支付项展示、推荐与排序，与路由独立，后配也不影响支付。
「开发调试 → 支付调试(网关)」选择网关支付类型提交预下单，返回**网关落地页 URL**。扫码或打开即可验证收银页渲染与路由，不用真码。见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)与[开发者调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md)。
## 环节四：码牌制作与认领
码牌是聚合扫码的物理物料，采用「**平台制牌、商户认领**」模式（操作详解见[码牌管理](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md)）。plus 的码牌有两个关键分类维度（模型详解见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)）：
- **程序类型（两类模型）**：聚合 **H5** 码牌（扫码打开 H5 收银页）与**收银台小程序**码牌（扫码拉起小程序收款页）。小程序码牌依赖环节五完成，**未发布小程序前先投 H5 码牌**；
- **牌别（归属）**：平台「未划拨」码牌（认领前不属任何商户，可分配）与**商户码牌**（锁定商户号中缀，**禁止调拨**给其他商户）。批量制牌时按投放策略选牌别。
```mermaid
graph LR
A[运营端批量创建
空白码牌] --> B[批量绑定商户
或留未划拨]
B --> C[商户端认领
绑定应用与门店]
C --> D[设置金额类型
启用]
D --> E[下载二维码/打印模板
印制投放]
```
上线要点：
- 码牌认领后必须**绑定应用与门店**：扫码后的路由走「该码牌绑定应用的网关支付配置」，没绑应用 = 扫码无法付款；
- 金额类型二选一：**随机金额**（用户自填，桌牌通用）/ **固定金额**（定价商品）；
- 「启用/停用」控制投放状态；投放前用「查看二维码」真码扫码走一遍全链路；
- 打印用平台内置**打印模板**，不要自行截屏放大（二维码失真会扫不出）；
- 代理商可在代理商端查看管理名下商户的码牌（见[订单查询与码牌](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md)）。
被扫设备（云音箱、扫码盒子等）另走「系统终端 ↔ 通道终端」绑定，见[云音箱云打印与终端](https://doc.plus.daxpay.cn/operation-guide/admin/iot-device.md)。
## 环节五：收银台小程序发布
收银台小程序让微信/支付宝/抖音**扫普通二维码直接拉起小程序**收款页（体验优于 H5）。按平台分别注册发布，检查单与操作详解见[小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md)：
1. **注册与 AppId**：各平台注册小程序主体，AppId 配置到工程平台参数（三端独立）；
2. **域名验证**：小程序后台下发校验文件 → 平台级入口上传（环节二）；
3. **普通链接二维码规则（关键）**：让已印制的普通链接二维码命中规则拉起小程序，三条前缀对应三个收款入口：`https://域名/m/*`（码牌）、`/cm/*`（统一收银台）、`/am/*`（聚合支付）；配置时平台再下发随机校验文件，同样平台级上传；
4. **request 合法域名**：把支付网关域名加入小程序后台 request 合法域名，**不配则正式环境请求全部失败**（开发工具「不校验域名」只对调试有效）；
5. **编译上传提审发布**：收款类小程序需如实填写类目资质；发布后用**真码**验证三条链路。
小程序的日常使用与付款流程见[小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md)。
规则未配或未命中时，扫码打开的是 H5 引导页（提示改用对应 App 扫码），小程序不会被拉起。这是设计的兜底行为，不是故障；上线后务必真码全链路验证。
收银台小程序**全平台共用一套凭证**，且 openId 与收款应用必须同源。平台小程序 AppId 需在所用通道侧完成**绑定或报备**（服务商模式通常服务商小程序 + 子商户号报备）。并非所有通道开箱即用，接入前先与通道确认（见[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)）。
## 全链路验收
五环节完成后，按**真实二维码**验证每条链路（不开发工具、不模拟）：
| 验收入口 | 动作 | 预期 |
| --- | --- | --- |
| 码牌 `/m/*` | 微信、支付宝（+云闪付/抖音按需）分别扫码 | 拉起对应收款页 → 小额付款 → 订单成功 |
| 统一收银台 `/cm/*` | 预下单生成链接，扫码/浏览器打开 | 收银页展示配置的支付方式 → 付款成功 |
| 聚合页 `/am/*` | 扫码打开聚合页 | 环境自动识别 → 付款成功 |
| 回调与订单 | 每笔验证后核对 | 支付交易状态成功、商户回调推送记录正常（有 notifyUrl 时） |
## 常见问题速查
| 现象 | 环节 | 处理 |
| --- | --- | --- |
| 收款链接/回跳 404 | 环节一 | H5 部署域名与端点配置不一致；或 SPA 回退未配 |
| 微信内提示域名未验证 | 环节二 | 校验文件未上传或传错归属（平台级/商户级两入口勿混） |
| 收银页打开但支付失败 | 环节三 | 网关支付配置有缺口，看路由命中预览；或通道路由未「设为当前生效」 |
| 扫码牌无反应/无法付款 | 环节四 | 码牌未绑应用、未启用；或绑定应用的网关支付配置未就绪 |
| 扫码进 H5 引导页而非小程序 | 环节五 | 二维码规则未命中：查前缀拼写、域名一致、小程序是否已发布 |
| 小程序内请求全失败 | 环节五 | request 合法域名未配 |
更多部署层问题见[收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md)与[小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md)。
下一阶段：[可选功能上线](https://doc.plus.daxpay.cn/operation-guide/production/optional-features.md)或直接进入[上线验收与运维交接](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md)。
## 相关链接
- [收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md)：构建、域名契约与部署要点
- [小程序发布上线](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-publish.md)：上线检查单与提审
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)：码牌两类模型与认领
- [码牌管理](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md)：模板、台账与打印
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)：配置模型与接入流程
---
# 上线验收与运维交接
**源**: https://doc.plus.daxpay.cn/operation-guide/production/go-live.md
# 上线验收与运维交接
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的最后一阶段：配置全部完成后，**用真实交易证明系统可用**，并把日常运维责任交接清楚。验收全部通过后再放开业务。
## 生产专项检查
先过一遍**只在生产才有意义**的检查项（通用配置项见[上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)，此前各阶段的分项清单见各篇末尾）：
- [ ] **PROD 启动校验通过**：`SPRING_PROFILES_ACTIVE=prod` 与 PROD 部署模式已生效，启动期 fail-fast 九项校验无拦截（沙箱关、开发超管关、全量异常信息关、接口文档与 Swagger 关、CORS 关、监控端点收紧等，完整清单见[配置说明 - 部署模式与生产校验](https://doc.plus.daxpay.cn/deployment/configuration.md#部署模式与生产校验)）；界面无任何沙箱入口，开发超管账号无法登录
- [ ] 全站 HTTPS 生效，各域名与[端点配置](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#端点配置)一致
- [ ] 网关已放行 `/unipay` 与 `/unipay/callback`（易支付另开 `/epay`）
- [ ] `/demo/`、`/test/`、swagger 未暴露公网
- [ ] 中间件强口令、业务密钥未重新生成、通道子应用不对公网暴露
- [ ] **风控策略确认**：四层防线（IP 黑名单/用户标识/省市地区/门店围栏）开关逐项过一遍；「命中阻断下单」按观察期策略设定（建议初期仅记录）；[限额兜底](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)的平台默认值已复核
- [ ] **费率抽查**：抽 2~3 个商户核对费率链解析结果（服务商 → 代理商 → 商户逐段取值），确认与商务约定一致，且申报费率未被下限拦截
- [ ] **限额抽查**：抽商户核对单笔/日累计/日笔数配置与平台模板回退关系
- [ ] 运维面板自身安全就位：安全入口保留、初始密码已改、（按需）IP 白名单与两步验证（见[面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md)）
## 小额真实支付端到端验证
对**每一个上线的通道产品**执行一遍，金额用 0.01~1 元：
1. **下单**：业务系统（或支付调试页）发起真实支付，核对生成的付款链接/二维码正常；
2. **付款**：用真实的微信/支付宝完成支付（微信无沙箱，本来就要真实验证）；
3. **回调**：核对订单业务状态自动变为「成功」，且不是靠手动「同步」拉出来的，这样才证明回调链路通；「同步」只是回调不可用时的兜底手段；
4. **通知**：有 `notifyUrl` 的，核对商户业务系统收到通知且验签通过；平台侧「商户回调推送」页发送记录正常；
5. **退款**：对验证单发起一笔全额退款，核对退款状态成功、资金到账；
6. **费用与对账**：「交易费用明细」核对手续费按费率快照计算正确（口径见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)）；「资金流水」按当日区间导出，与通道侧对账单核对这笔交易金额一致（导出与对账口径见[异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md)）。
网关收款场景另按[网关收款上线 - 全链路验收](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md#全链路验收)用真码过三条链路。
## 首日观察
上线后 24~72 小时最容易暴露问题，建议每日固定巡检：
| 观察点 | 位置 | 关注什么 |
| --- | --- | --- |
| 商户回调推送 | 回调通知 → 商户回调推送 | 有无持续失败的任务（失败会自动重试，持续失败=商户接收端问题） |
| 通道回调记录 | 回调通知 | 处理状态有无异常堆积 |
| 异常订单 | 交易订单 → 异常订单 | close_paid 等不一致单，出现即按[异常订单](https://doc.plus.daxpay.cn/common/trade-records.md)核实处置 |
| 风险命中记录 / 风控预警 | 支付管理 → 支付安全 | 观察期判断误拦情况，决定何时开「命中阻断」 |
| 交易费用明细 | 交易管理 | 手续费计算与费率链是否一致，有无解析落空的交易 |
| 支付接口日志 | 系统管理 → 日志管理 | 验签失败类报错是否集中出现（提示某商户密钥/签名实现有问题） |
| 应用日志 | 运维面板 / `LOG_PATH`（源码） | ERROR 级别有无持续输出 |
## 升级流程
系统升级按以下步骤执行（顺序错了会出现「新按钮不可见」「数据结构不一致」）：
1. **看官方更新日志**确认本次升级内容与破坏性变更；跨大版本或长期未跟进时，面板建议**全新安装再迁移数据**（见[安装、升级与卸载](https://doc.plus.daxpay.cn/tools/panel/install.md#升级)）；
2. 备份：面板「数据安全」导出数据备份（或自建场景自行 pg_dump）；
3. 升级后端/前端（面板「版本与构建」检查更新；**升级面板不会自动重建业务容器**，drift 横幅提示的服务要手动重部署）；
4. 数据库执行升级脚本：`update-tables.sql → update-datas.sql`，**仅适用上一版本→当前版本，不能跨版本**（见[项目构建 - 数据库准备](https://doc.plus.daxpay.cn/deployment/build.md#数据库准备)）；
5. **执行「同步权限码」**（菜单管理页），让新版本新增的按钮权限对已授权角色生效；
6. 小额真实支付再验证一笔（回归）。
## 应急排查链
上线初期最高频的三类故障与排查路径：
**「订单一直待支付」**
通道回调没进来 → 查端点配置后端 API 地址公网可达 → 网关 `/unipay/callback` 已放行 → 通道回调记录有无该单 → 有记录但订单未更新看异常订单 → 兜底用订单「同步」拉状态。
**「商户说收不到回调」**
先看「商户回调推送」：**有记录且失败** → 商户接收端问题（地址不通/验签失败/应答格式不对，发送详情里有 HTTP 状态码与错误信息，可手动重发）；**无记录** → 商户下单没传 `notifyUrl` 或传错。排查方法论见[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)。
**「面板进不去」**
面板安全防线（安全入口/IP 白名单/两步验证/登录锁定）任一触发都会表现为进不去，按[锁死恢复通道汇总](https://doc.plus.daxpay.cn/tools/panel/security.md#锁死恢复通道汇总)用 `daxpay-plus` 命令行恢复（不依赖面板进程，用法见[运维面板命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)）。
## 运维交接清单
把以下信息交接给日常运维责任人：
- 部署形态与入口：部署路径（面板/源码）、面板安全入口与恢复命令、各端域名清单
- 凭证保管：管理员账号发放记录、业务密钥不重新生成的红线、[商户对接密钥的保管规范](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)
- 日常巡检项：上文首日观察表转为日常频率（建议回调推送/异常订单每日，风险命中每周）
- 数据备份策略：面板导出或自建 pg_dump 的周期与保留（注意日志清理**不可恢复**，见[日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)）
- 升级流程：上文六步
- 应急联系路径：通道侧（微信/支付宝服务商平台工单）、面板故障（命令行恢复）、业务排查（接口日志与回调推送）
---
至此[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)全部阶段完成。日常业务操作见[业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)各章，各端使用见运营端、[商户工作台](https://doc.plus.daxpay.cn/operation-guide/merchant/workspace.md)与[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)入门。
## 相关链接
- [上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)：两阶段验收清单
- [配置说明](https://doc.plus.daxpay.cn/deployment/configuration.md)：生产校验与环境变量
- [风控策略与处置](https://doc.plus.daxpay.cn/plus/risk-control/policy.md)：观察期策略与命中处置
- [运维面板使用入门](https://doc.plus.daxpay.cn/tools/panel/overview.md)：日常运维与巡检
---
# 基础设施与域名规划
**源**: https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md
# 基础设施与域名规划
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的第一阶段：让系统以生产配置对外提供服务，讲清楚域名怎么分、证书谁来管、哪些环境变量缺了起不来、网关对外开哪些口。部署操作本身见对应部署文档，本篇只做**决策与核对**。
>
> 面向本地联调（内网穿透、自签证书）的方案不在本篇，见[本地联调](https://doc.plus.daxpay.cn/deployment/debug.md)。
## 域名规划
系统对外的域名矩阵如下。示例口径：后端 API 用 `pay.example.com`，面向付款人的 H5 收银台用 `h5.example.com`，其余端各自规划独立域名（可共享一台服务器，但不要共用域名）：
| 域名 | 承载 | 访问者 | HTTPS |
| --- | --- | --- | --- |
| 运营端域名 | 运营端 Web（平台方） | 内部运营人员 | 必须 |
| 商户端域名 | 商户端 Web | 商户 | 必须 |
| 代理商端域名（按需） | 代理商端 Web | 代理商 | 启用代理商体系时必须 |
| **支付网关域名（H5 收银台）** | 统一收银台 / 聚合扫码 / 认证中转页 | **付款人** | 必须（面向付款人的页面，HTTP 会被浏览器与微信/支付宝拒绝） |
| **后端 API 域名** | unipay 开放接口 + 通道回调入口 | 商户业务系统、微信/支付宝服务器 | 必须 |
| Artemis 控制台域名 | 消息队列控制台 | 内部运维 | 必须（不建议走 CDN） |
| 移动端 API 域名（可选） | 三端 APP 与收银台小程序的登录态接口专用入口 | 运营/商户/代理商 APP、收银台小程序 | 必须（小程序仅允许 HTTPS 域名） |
| 文档站域名（可选） | 对外对接文档 / API 文档站 | 商户开发人员 | 建议 |
两点补充说明：
- **收银台小程序不占独立域名**：微信/支付宝/抖音小程序的 request 合法域名、业务域名校验全部发生在**支付网关域名**上，把 `h5.example.com` 登记到各平台小程序后台即可（见[网关收款上线 - 收银台小程序发布](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md)）；
- **文档站域名**是纯静态站点，可独立域名，也可挂在任一现有域名的子路径下，不参与支付链路。
四点决策依据：
- **域名须完成 ICP 备案**：微信/支付宝在配置支付目录、授权域名、二维码规则时都会校验备案与归属，未备案域名无法通过通道侧配置。
- 运营端 / 代理商端 / 商户端 / 支付网关 / 后端 API 五类域名与后端「端点配置」一一对应（见[平台初始化 - 端点配置](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#端点配置)），**部署域名与端点配置不一致**是上线后跳转 404、回调失败的最常见原因。
- **移动端 API 域名是可选的隔离进阶项**：不绑定时小程序/APP 经后端 API 域名接入即可正常使用（见下文[网关对外接口](#网关对外接口)）；需要把自家客户端与第三方对接分开、让登录接口只经专用域名暴露时再绑定。它不对应「端点配置」中的任何一项，小程序合法域名登记两者取一即可。
- 运维面板部署时会按各域名绑定目标生成网关路由（[面板配置 - 域名绑定与 CDN 外层接入](https://doc.plus.daxpay.cn/tools/panel/configuration.md#域名绑定与-cdn-外层接入)）；源码静态部署需自行在 nginx 中规划，示例见[项目构建 - 静态部署](https://doc.plus.daxpay.cn/deployment/build.md#静态部署)。
## 部署路径选择
| 路径 | 适合 | 依赖 |
| --- | --- | --- |
| [一键部署（运维面板）](https://doc.plus.daxpay.cn/deployment/installer.md) | 多数生产部署（主流交付形态）：单机 Docker 化，面板托管网关/证书/升级/移动端构建 | x86_64 Linux、≥8GB 内存、root、联网拉镜像 |
| [源码构建 + 静态部署](https://doc.plus.daxpay.cn/deployment/build.md) | 需要定制 nginx/自管 K8s、或离线裁剪 | 自备 JDK/Node/中间件与 nginx 配置能力 |
两条路径的应用配置项**完全一致**（见[配置说明](https://doc.plus.daxpay.cn/deployment/configuration.md)），差异只在证书与网关的托管方式：
- **面板部署的证书归属**：网关源站**零证书、恒走 HTTP**，HTTPS 由外层 CDN / 网关终结，证书的签发、续期、验证都在外层控制台完成，面板不负责证书。生产推荐「经 CDN 回源」模式（含回源鉴权 Token）。
- **静态部署的证书归属**：证书配在你自己的 nginx 层，面向付款人的 H5 域名必须配。
## 中间件生产要求
PostgreSQL 14+、Redis 7+、Artemis 三件中间件的生产要求（面板部署已按此装配，自建时逐项核对）：
- **凭证**：三者全部改掉默认/空密码（面板部署在「数据安全」中改密）；Artemis 默认空口令在生产环境必须设置。
- **资源**：内存档位参考[面板配置 - 内存档位](https://doc.plus.daxpay.cn/tools/panel/configuration.md#内存档位)。
- **可达性**：中间件与业务容器端口默认**不映射宿主机**（端口暴露默认 off），保持默认即可；调试时临时开 `local`（仅绑本机回环），不要开 `public`。
- **通道子应用**：通道子应用 1（10100）与通道子应用 2（10200）与主应用同机或同内网部署即可，**不对公网暴露**，主应用经 HTTP + AES-GCM 传输密钥调用（密钥见下文环境变量）。
## 生产环境变量
源码/静态部署从 `application-prod.yml` 占位符读取环境变量；面板部署在面板「业务环境 → 主应用 → 应用配置」中维护等价项。**标必填的变量缺失时启动直接失败**（fail-fast），漏配在启动时就会暴露，不会拖到运行期。
变量分几组，完整清单见[配置说明 - 生产环境变量清单](https://doc.plus.daxpay.cn/deployment/configuration.md#生产环境变量清单)：
| 组 | 关键项 | 说明 |
| --- | --- | --- |
| 运行 profile | `SPRING_PROFILES_ACTIVE=prod`（必填） | **最高频事故是忘切 profile**，缺失会以 dev 启动且生产校验不拦截，见下节 |
| 部署模式 | `DEPLOY_MODE=PROD` | 见下节[切换生产模式](#切换生产模式) |
| 数据库 | `DB_USERNAME` / `DB_PASSWORD`（必填） | PostgreSQL 凭证 |
| Redis | `REDIS_PASSWORD`（必填） | — |
| 消息队列 | `ARTEMIS_USER` / `ARTEMIS_PASSWORD` | 默认空串，生产必须设置 |
| 业务密钥 | `RSA_PRIVATE_KEY` / `RSA_PUBLIC_KEY` / `ENCRYPT_KEY`（32 字符，必填） | 平台级签名与数据加密密钥 |
| 通道子应用 | `CHANNEL_ONE_TRANSPORT_KEY` / `CHANNEL_TWO_TRANSPORT_KEY`（必填） | 主应用与两个通道子应用的 AES 传输密钥，缺失启动失败 |
| IP 库 | `IP2REGION_*` | 风控地区拦截依赖，路径与版本须与实际 xdb 文件一致 |
RSA/AES/通道传输密钥在首次部署时自动生成并固化。**重新生成会导致已加密数据无法解密**（通道密钥密文、敏感配置等），生产环境不要执行「重新生成」。
## 网关对外接口
面板部署的网关在「对外接口」按路径前缀放行外部请求，未放行的路径一律拒绝（[面板配置 - 对外接口](https://doc.plus.daxpay.cn/tools/panel/configuration.md#对外接口)）。四个接口组的默认状态与上线核对点：
| 接口 | 用途 | 默认 | 说明 |
| --- | --- | --- | --- |
| `/unipay` | 商户业务系统调用开放接口 | 开 | 有 API 对接商户时**必须保持开启** |
| `/unipay/callback` | 微信/支付宝等通道回调平台 | 开 | 走支付宝/微信通道时**必须保持开启** |
| `/app-*`（小程序 / APP API） | 三端 APP 与收银台小程序的登录态接口 | 开 | 小程序/APP 的接入生命线，见下文 |
| `/epay` | 易支付兼容接口 | 关 | 用易支付协议对接时开（见[可选功能](https://doc.plus.daxpay.cn/operation-guide/production/optional-features.md)） |
| `/admin/`、`/mch/`、`/swagger-ui/` 等 | 运营端与商户端 Web API | 恒封禁 | 管理流量由前端域名的 `/api/` 转发承载；`/demo/`、`/test/` 保持封禁 |
**小程序/APP 接入路线**（面板开关卡底部的状态行实时显示当前生效路线）：
- **兼容方式（默认）**：小程序构建时 API 地址留空（即用后端 API 域名），依赖 `/app-*` 开关开启——默认开箱即用，不要随意关闭；
- **专用入口（需独立移动端 API 域名）**：绑定移动端 API 域名并在小程序构建时填入该地址，该域名恒放行、不受开关影响；存量小程序/APP 全部切换后，建议关闭 `/app-*` 开关，让登录接口只经专用域名暴露；
- **失联**：关闭 `/app-*` 且未绑定移动端 API 域名 = 小程序无法登录（面板关闭时有防呆确认）；直接用 IP 访问时登录态接口恒不开放（登录端点防暴力破解）。
**关闭 `/unipay` 的后果**：商户系统所有 API 调用被网关拒绝；**关闭 `/unipay/callback` 的后果**：通道回调进不来，所有订单停在待支付，只能靠手动「同步」拉状态。上线后「接口全不通」先查这里。
源码静态部署没有这层开关，等价控制在你自己的 nginx 路由中，注意**不要**把 `/demo/`、`/test/`、swagger 一并暴露到公网。
## 切换生产模式
面板部署默认以 **DEV 模式**完成安装（放开沙箱与开发超管，便于联调）。上线前必须切换：
1. 在面板「业务环境 → 主应用 → 应用配置」中将部署模式切为 **PROD**，系统会强制关闭沙箱与开发超管；PROD 下手工开启这两个值会被启动检查直接拦截；
2. 重启业务容器生效（运行时配置只需重启，无需重建镜像，见[面板配置 - 生效方式判断](https://doc.plus.daxpay.cn/tools/panel/configuration.md#生效方式判断)）；
3. 确认启动后界面不再出现任何沙箱入口（沙箱产品被自动重置为生产，详见[支付能力 - 产品环境](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#产品环境)）。
PROD 模式在启动期执行 **fail-fast 生产校验**：沙箱关闭、开发超管入口关闭、全量异常信息关闭、接口文档与 Swagger 关闭、CORS 关闭（走网关）、监控端点收紧等九项，任一违规直接拒绝启动，完整清单见[配置说明 - 部署模式与生产校验](https://doc.plus.daxpay.cn/deployment/configuration.md#部署模式与生产校验)。
开发超管账号（固定弱口令）在 DEV 模式下可登录运营端、沙箱产品可见。**对外网开放的部署不能停留在 DEV 模式**，且必须显式 `SPRING_PROFILES_ACTIVE=prod`——忘切 profile 时按 DEV 形态运行，校验不会拦截。
源码部署对应为启动参数 `--spring.profiles.active=prod`，效果一致。
## 域名验证文件的网关侧预留
微信/支付宝的域名归属验证会在域名根路径与 `/m/`、`/cm/`、`/am/` 目录下抓取校验文件（上传入口见[支付能力 - 域名验证](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#域名验证)）：
- **面板部署**：网关接入已包含校验文件请求的应答转发，把校验文件上传到平台后即可被通道侧抓取到；
- **静态部署**：须自行在 nginx 中为校验文件路径配置反代（正则 location，且必须排在 SPA 兜底 `try_files` 之前），配置示例见[项目构建 - 静态部署](https://doc.plus.daxpay.cn/deployment/build.md#静态部署)，漏配的后果是通道/平台侧域名校验始终不通过。
## 本阶段核对清单
- [ ] 域名矩阵规划完毕且已备案（含按需的代理商端与文档站），与端点配置一一对应
- [ ] HTTPS 全站生效（付款人页面与 API 域名必须）
- [ ] 中间件三件套全部强口令，端口未映射公网；通道子应用不对公网暴露
- [ ] 生产环境变量齐备（必填项无一缺失），业务密钥未重新生成
- [ ] 网关对外接口核对完毕：`/unipay`、`/unipay/callback`、`/app-*` 保持开启，`/epay` 按需开启
- [ ] 小程序/APP 接入路线已确定（默认经后端 API 域名；需隔离时绑定移动端 API 域名并在构建时填入）
- [ ] `SPRING_PROFILES_ACTIVE=prod` 与 PROD 部署模式已确认并重启，沙箱与超管已关闭
- [ ] 校验文件反代路径已预留
下一阶段：[平台初始化配置](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md)。
## 相关链接
- [配置说明](https://doc.plus.daxpay.cn/deployment/configuration.md)：生产环境变量清单与部署模式校验
- [一键部署](https://doc.plus.daxpay.cn/deployment/installer.md) / [项目构建](https://doc.plus.daxpay.cn/deployment/build.md)：两条部署路径
- [运维面板使用入门](https://doc.plus.daxpay.cn/tools/panel/overview.md)：面板托管的部署与网关接入
- [本地联调](https://doc.plus.daxpay.cn/deployment/debug.md)：内网穿透与自签证书方案
---
# 商户开通与对接就绪
**源**: https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md
# 商户开通与对接就绪
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的第四阶段：把商户开通到「可以发起收款」的状态。plus 先明确**运营模式**（直营还是代理商挂靠，它决定创建路径与进件归属），再按「创建商户 → 进件 → 应用 → 对接密钥 → 就绪检查」走完。
>
> 商户日常操作（订单/退款/配置维护）见商户端各文档；本篇只讲上线期的开通动作。
## 先定运营模式
plus 的商户有**归属维度**：直营（平台）或挂靠（代理商），与商户规模维度组合出三种典型运营模式：
| 模式 | 商户归属 | 典型用法 | 本篇重点 |
| --- | --- | --- | --- |
| **平台直营多商户** | 直营（平台） | 平台方自营 SaaS：运营代开通 + 商户自助维护 | 全流程 |
| **代理商挂靠** | 挂靠（代理商） | 代理商展业：代建或邀请码注册，平台管进件与归属 | 创建路径二/三 + 归属与代管 |
| **单体自用** | 直营，仅一户 | 自己的公司/业务线对接 | 可跳过商户用户管理，聚焦对接密钥 |
三点决策依据（体系详解见[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)与[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)）：
- **归属可调拨**：平台可把商户从一代理商划给另一代理商或收回直营（调拨走专用流程并留审计），所以初始归属不必过度纠结，但**尽量一次定准**——码牌商户级编号、进件服务商归属都会随归属联动；
- **代理商是展业主体**：名下商户的正常交易不受代理商禁用连坐（禁用只禁代理商自身登录）；
- 不启用代理商体系时全部商户天然直营，本篇按路径一走即可。
## 创建商户的三条路径
### 路径一：运营端手工创建
**菜单路径**：支付管理 → 商户管理 → 商户列表 → 新增（操作细节见[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)）
生产开通要点：
- 表单分「商户信息 + 管理员信息」两组，**主体类型创建后不可修改**；
- 管理员密码留空时系统生成随机初始密码，**结果页只展示一次**。生产流程建议固定三步：复制密码 → 安全渠道转告商户 → 提醒**首次登录立即改密**；
- 创建后系统自动完成四件事：商户号（M 开头）、管理员账号（绑商户超管角色）、**默认应用**（A 开头）、默认门店，无需手动补建；
- **禁用商户**的语义：全部账号无法登录、无法发起新支付，但**在途订单回调照常完成**。上线初期临时停某个商户用禁用，不要用删除（删除仅限无交易数据的测试商户）。
### 路径二：邀请注册
适合批量拓客，两条邀请线并存（详解见[邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)与[推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)）：
| 邀请线 | 发放方 | 注册后归属 |
| --- | --- | --- |
| 平台直营邀请码 | 运营端 | 平台直营 |
| 代理商推广邀请码 | 代理商端（[推广邀请码](https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md)） | 挂靠到邀请码所属代理商 |
生产要点：
- **注册入口默认关闭**（系统安全配置中的注册开关），需要自助注册时先开启，并在[平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#邮件与短信配置)确认**短信验证码链路可用**（邀请注册走手机号 + 验证码）；
- 经邀请码注册的商户**自动创建**管理员账号、默认应用与门店（含注册 IP 快照），注册后即可登录商户端，但仍需完成进件/通道配置才能收款；
- 注册记录可查、可追溯邀请关系，便于后续归属核对。
### 路径三：代理商代建
代理商在代理商端「名下商户 → 代建」直接创建挂靠商户（操作见[名下商户与代建](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)）：
- 代建商户自动挂靠该代理商，创建体验与运营端一致（初始密码一次性展示）；
- 代理商可对名下商户**代配功能开关**（在平台授权的能力范围内单向收紧），平台保留全量视图与处置权；
- 平台侧仍可通过[商户归属调拨](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)把代建商户划转或收回直营。
## 商户进件
服务商模式下，商户创建后必须**进件**才能获得通道商户（完整链路见[支付能力开通 - 进件开通主线](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#进件开通主线)，流程详解见[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)）。上线期的动作序列：
1. **维护资料主档**：运营在商户工作台「进件资料」维护该商户的主体/法人/执照/门店四档（一次维护，多张申请单复用），或由商户在商户端补充；
2. **创建申请单**：进件申请工作台选商户 + 服务商 + 通道，**创建即锁死归属服务商**，换服务商 = 作废重开；
3. **跟踪审核**：申请单经平台审核 → 渠道处理，通过后**自动生成通道商户**；
4. 暂不支持进件的通道（抖音、银联等）走[直连配置辅线](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#直连通道商户与密钥)手工建号。
微信/支付宝服务商进件通常需要 1~3 个工作日，材料不齐会被驳回。批量开通商户时按「先创建商户、立即发进件、再发对接凭证」并行推进，不要串行等待。
## 应用管理
**入口**：商户工作台 → 支付配置 → 应用管理
应用是调用隔离单元（appId），生产要点（详解见[应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)）：
- **不传 appId 的请求回落默认应用**。停用默认应用会导致不指定 appId 的下单全部失败，删除默认应用被系统禁止；
- 第一个创建的应用自动成为默认，同商户至多一个默认；
- 多业务线区分对账时才需要多应用；单业务单应用即可。
## 对接配置
**菜单路径**：商户端 → 商户中心 → 业务配置 → 对接配置（运营代管：商户工作台 → 业务配置 → 对接配置）
业务系统调用的四件凭证（详解见[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)与[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)）：
| 凭证 | 生产发放动作 |
| --- | --- |
| 商户号 `mchNo` | 从商户资料复制给业务系统方 |
| 应用号 `appId` | 应用管理卡片查看（单应用可不传，回落默认） |
| 商户公钥 / 私钥 | 在线「生成密钥对」，**私钥仅弹窗展示一次**。生产建议**重新生成一套**（不复用沙箱期密钥），生成后立即交业务系统方妥善保管 |
| 平台公钥 | 只读复制给业务系统方，用于验证平台响应与回调签名 |
密钥是**商户级**的（所有应用共用一套），轮换会连锁影响所有用旧密钥的调用方。密钥保管规范（禁止入库/写死、按环境隔离）见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)。
## 商户用户
商户自助运营时的账号体系（详解见[商户用户](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-user.md)与[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)）：
- 商户**管理员角色固定**（不可变更、管理员不可封禁）；普通店员/财务账号由商户管理员在商户端自建；
- 商户端角色由运营端**预置授权**（角色管理中终端选商户端）。上线前把「商户操作员」类角色准备好，商户才有可分配的角色；
- 运营端可通过用户管理（商户端 Tab）介入处理：重置密码（全部会话立即下线）、封禁/解锁。
## 实名认证与自助边界
**实名认证**：平台开启实名门禁后（见[平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#实名认证)），商户需在商户端「实名认证」页完成核验后才能正常开展业务；批量开通时把这一项写进商户告知清单。
**自助边界**——提前说清「商户能自己做什么、什么必须找运营」，上线后可减少商户来回询问（能力矩阵见[商户端通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)）：
| 商户可自助 | 必须运营端处理 |
| --- | --- |
| 直连通道密钥维护、分账接收方绑定 | 商户创建/删除/禁用、**归属调拨** |
| 对接配置密钥、域名校验文件（商户级） | **进件申请审核**、通道商户删除 |
| 应用/门店/码牌认领/系统终端 | 风控策略与限额模板、平台级域名验证 |
| 订单/退款操作、回调推送排查 | 异常订单处置（商户端只读） |
另有 **ISV 代运营授权**（可选）：商户可把通道配置维护授权给服务商身份的代理商代管，适合无运维能力的中小商户（见[商户端通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md)）。
## 就绪检查
每个商户上线前逐项核对（通用清单见[上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)）：
- [ ] 管理员初始密码已安全转告，首次登录已改密
- [ ] 默认应用与默认门店自动创建无误
- [ ] 进件申请已通过、通道商户已自动生成（或直连通道商户已手工配置 + 密钥完成，见[支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#进件开通主线)）
- [ ] 商户费率在费率链中解析正确（实时链校验通过）
- [ ] 通道路由已生效（应用工作台，[支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#通道路由)）
- [ ] 对接密钥已按生产标准发放/重新生成，业务系统方已拿到四件凭证
- [ ] 实名认证（若平台门禁开启）已完成
- [ ] 商户端「工作台」告警横条已清零（无未配通道商户/路由/凭证告警）
- [ ] 小额真实支付一笔成功，订单/回调/推送链路核对
下一阶段：API 直连到此即可进入[上线验收](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md)；要用统一收银台、聚合扫码或码牌，继续[网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md)。
## 相关链接
- [商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)：运营端商户全生命周期操作
- [进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)：进件审核与状态机
- [代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)：直营/挂靠与归属调拨
- [邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)：两线邀请码
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：凭证、回调联调与密钥保管
---
# 可选功能上线
**源**: https://doc.plus.daxpay.cn/operation-guide/production/optional-features.md
# 可选功能上线
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的第六阶段：**用到才配**的可选功能。除收款单与投诉外，其余功能都有**通道侧前置**，不是平台内配完就能用；先确认通道侧已开通，再配平台。
>
> 统一收银台/聚合扫码/码牌虽然也是可选项，但链路长单独立篇，见[网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md)。
## 功能速览
| 功能 | 定位 | 通道侧前置 | 平台侧入口 |
| --- | --- | --- | --- |
| [分账](#分账) | 收款后把资金分给接收方 | 通道商户开通分账产品权限 | 通道商户 → 分账接收方 |
| [预授权与支付分](#预授权与支付分) | 先冻结后扣款 / 先享后付 | 通道侧产品权限（支付宝预授权、微信支付分） | 交易管理 → 预授权支付 |
| [收款单](#收款单) | 商户开单远程催款 | 无（复用普通支付链路） | 商户端开单 |
| [对账](#对账) | 通道对账单核对与差错处理 | 通道侧可下载对账单 | 对账管理 |
| [投诉](#投诉) | 通道投诉工单处置 | 通道侧投诉推送配置 | 投诉管理 |
| [易支付](#易支付) | 兼容易支付协议的商户接入 | 无（平台内开关） | 网关对外接口 + 应用工作台 |
## 分账
**资金链路**：下单声明分账（冻结资金）→ 支付成功 → 发起分账 → 接收方入账。上线三前置（流程详解见[支付分账](https://doc.plus.daxpay.cn/common/alloc.md)）：
1. **通道侧**：在微信/支付宝商户平台为该商户开通**分账产品权限**（进件生成的通道商户在申请单里勾选，手工建的直连通道商户去通道商户平台开通）。平台内配得再全，通道侧没权限分账请求也会失败；
2. **绑定接收方**：通道商户 → 分账接收方（微信/支付宝/抖音），支持表单填写与**扫码授权**两种方式；注意**删除只解绑平台侧档案，不影响通道侧已建立的绑定**，换绑走「重新绑定」；
3. **下单声明**：业务系统下单时带 `allocation=true` 冻结资金，未冻结的交易**无法**发起分账。这是业务系统对接契约的一部分，要提前告知。
上线时还要注意**分账比例上限**（如微信默认 30%）与**可分余额**约束：部分分账受「支付金额 − 已退款 − 已分账」限制，发起页面会实时校验。分账订单状态可查询、可手动「同步」对齐通道侧。
## 预授权与支付分
plus 实装了两个「先享后付/先冻结」类能力，**分属两个独立域**、分开建模（详解见[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)）：
- **支付宝预授权**：授权（冻结）→ 请款（扣款）→ 转支付 / 退款。适合押金、租车、酒店预扣等场景。注意**请款后暂不支持退款**，业务流程要留好转支付路径；
- **微信支付分**：先享后付，需在微信侧开通支付分服务并配置**确认模式**的双轨策略（免确认/需确认），回调链与预授权不同，不要混用。
上线前置：通道侧分别开通对应产品权限（支付宝预授权产品、微信支付分服务），绑定收款目录；平台入口在 交易管理 → 预授权支付（运营端），商户端在交易订单区有对应入口。
## 收款单
商户**开单远程催款**：商户在商户端创建收款单（可带备注、金额、表单字段），把单据链接发给付款人，**一单一付**、付完即止（详解见[收款单](https://doc.plus.daxpay.cn/common/receivable-bill.md)）。
上线要点：
- 无通道侧前置，复用普通支付全链路，通道商户与路由就绪即可用；
- 每张收款单有独立短链（`/b/单号` 形式），经 H5 收银台渲染，依赖[网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md)的环节一（域名契约）就绪；
- 单据支持配置表单字段（收款说明等），提交时服务端复核，防止绕过；
- 适用场景：定金/尾款、服务费、定制商品等不便上架商城的一次性收款；
- **防重复开单**：同一商户对同一付款对象重复开单会「关旧建新」，旧单自动作废，避免多付。
## 对账
通道对账单下载与差错处理（操作详解见[对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md)）：
- **可用范围**：支付宝、微信通道的对账单下载已可用（**仅直连模式**），聚合通道陆续支持中——服务商模式账单以通道服务商平台侧为准，暂不能平台内下载；
- **差错单**：账单与平台订单比对不一致时生成差错单，人工核实处置（漏单、金额差、状态差分类处理）；
- 处理节奏建议日清：每日固定时间下载账单并处理差错单，避免跨日堆积难核对；
- 开放 API `/unipay/reconcile/*` 可供业务系统拉取对账数据。
## 投诉
通道侧（微信/支付宝等）投诉工单同步到平台内处置，运营端与商户端都有入口（操作见[投诉管理](https://doc.plus.daxpay.cn/operation-guide/admin/complaint.md)）：
- 上线前置：通道侧投诉推送配置到位（通常随通道商户开通自动生效）；
- 处置动作：查询工单详情、回复/提交处理结果，均在时限内完成（超时影响通道侧评级）；
- 处理记录留档在工单详情中，可作为通道侧检查时的应答材料；
- 建议把投诉页纳入日常巡检，与[上线验收](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md#首日观察)的观察点并列。
## 易支付
面向使用**易支付协议**的存量商户（论坛/发卡等场景），无需商户改造签名体系即可接入。上线两步（配置详解见[易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)）：
1. **网关开启接口**：运维面板 → 网关管理 → 对外接口，开启 `/epay`（默认关闭，见[基础设施 - 网关对外接口](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md#网关对外接口)）；
2. **应用配置**：应用工作台 → 易支付配置，开启总开关并记录 PID；协议版本二选一或并用：V1（MD5 密钥，仅下单/查单）、V2（RSA，可用「使用系统密钥」复用对接配置密钥对或单独生成，全能力），版本签名字段不可混用（商户侧说明见[易支付插件](https://doc.plus.daxpay.cn/operation-guide/merchant/easypay.md)）。
易支付订单与退款订单在插件页面统一查询，运营端与商户端各有入口。
易支付协议金额单位是**元**（字符串），与标准 unipay 接口的**分**（整数）不同。给商户的对接说明里务必写清，见[易支付对接](https://doc.plus.daxpay.cn/api/epay.md)。
下一阶段：[上线验收与运维交接](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md)。
## 相关链接
- [支付分账](https://doc.plus.daxpay.cn/common/alloc.md) / [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md)：资金类可选能力详解
- [收款单](https://doc.plus.daxpay.cn/common/receivable-bill.md)：开单催款详解
- [对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md) / [投诉管理](https://doc.plus.daxpay.cn/operation-guide/admin/complaint.md)：核查处置页面
- [易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)：协议配置与订单
---
# 完整上线指南
**源**: https://doc.plus.daxpay.cn/operation-guide/production/overview.md
# 完整上线指南
> 本指南面向把 DaxPay Plus **正式推向生产**的实施与运营人员：每个配置域要不要配、什么时候配、不配会怎样，全部给出决策依据与文档跳转。
>
> - 与[快速上线](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)的关系：快速上线解决「尽快跑通第一笔支付」，只走最小必要集；本指南覆盖生产上线的**全量配置域**，两者读者与目标不同
> - 写作原则：本指南只讲**决策、时序与后果**，字段级操作细节链接到各专题文档，避免两处维护
> - 部署本身（装好、跑起来）不在本指南范围，见[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md)（推荐）或[项目构建](https://doc.plus.daxpay.cn/deployment/build.md)
## 上线阶段总览
```mermaid
graph LR
A[基础设施
与域名] --> B[平台
初始化]
B --> C[支付能力开通
产品/费率/进件]
C --> D[商户开通与对接
直营或挂靠]
D --> E{收款形态}
E -- API 直连 --> F[业务系统对接]
E -- 收银台/码牌 --> G[网关收款上线]
F --> H[上线验收
与运维交接]
G --> H
```
| 阶段 | 指南章节 | 解决什么问题 |
| --- | --- | --- |
| 1. 基础设施 | [基础设施与域名规划](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md) | 域名怎么规划、HTTPS 与证书谁负责、生产环境变量、网关对外接口开关、生产模式切换 |
| 2. 平台初始化 | [平台初始化配置](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md) | 账号权限收紧、端点、站点合规、存储、邮件与短信、安全策略、敏感词与实名认证 |
| 3. 支付能力 | [支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md) | 主数据核对 → 支付产品配置 → 费率链 → 进件开通（自动生成通道商户）→ 密钥/应用/路由，风控与限额默认值 |
| 4. 商户开通 | [商户开通与对接就绪](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md) | 运营模式（直营/挂靠）、创建商户三径、进件申请、商户用户、对接密钥发放与就绪检查 |
| 5. 网关收款 | [网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md) | 统一收银台、聚合扫码、码牌、收银台小程序的五环节上线链路（API 直连可跳过） |
| 6. 可选功能 | [可选功能上线](https://doc.plus.daxpay.cn/operation-guide/production/optional-features.md) | 分账、预授权与支付分、收款单、对账、投诉、易支付按需开通的前置条件 |
| 7. 验收运维 | [上线验收与运维交接](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md) | 生产专项检查、费率与限额抽查、小额真实支付、首日观察、升级与应急 |
## 配置域全景地图
按「必须性」分三档：**必须**（不配核心流程不通或有安全风险）、**强烈建议**（影响运营/合规/体验）、**按需**（用到才配）。
| 配置域 | 必须 | 不配 / 配错的后果 | 详情 |
| --- | --- | --- | --- |
| 域名与 HTTPS | 必须 | 付款人页面被浏览器告警、微信/支付宝拒绝回调与跳转 | [基础设施](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md) |
| 生产环境变量 | 必须 | 必填变量缺失**启动直接失败**（数据库/Redis/业务密钥/通道传输密钥） | [配置说明 - 生产环境变量清单](https://doc.plus.daxpay.cn/deployment/configuration.md#生产环境变量清单) |
| 生产 profile 与部署模式 | 必须 | 未切 `prod` 时按 DEV 形态运行：沙箱入口可见、超管放行、接口文档暴露 | [基础设施 - 切换生产模式](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md#切换生产模式) |
| 网关对外接口 | 必须 | 网关按路径前缀放行：`/unipay`、`/unipay/callback`、`/app-*` 默认开启，`/epay` 默认关闭；误关则对应调用全不通 | [基础设施 - 网关对外接口](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md#网关对外接口) |
| 端点配置 | 必须 | 收银台跳转、回调通知、三方登录回调地址全部错误 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#端点配置) |
| 运营管理员账号 | 必须 | 只依赖开发超管账号登录，生产环境不可用 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#账号与权限) |
| 支付产品环境 | 必须 | 沙箱/生产环境固化错乱，下单被路由拒绝 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#产品环境) |
| 支付产品与服务商工作台 | 必须 | 产品未启用无法收款；服务商模式下进件参数无处置放 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#支付产品配置与服务商工作台) |
| 费率链 | 必须 | 费率解析落空、费用明细无法记账；申报低于平台下限被拦截 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#费率链) |
| 进件开通（服务商模式） | 必须 | 无进件则无通道商户，商户无法收款 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#进件开通主线) |
| 直连通道商户与密钥 | 按需 | 走直连模式的通道需手工配置；不涉及则免 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#直连通道商户与密钥) |
| 通道路由 | 必须 | 下单报路由无法解析，无法收款 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#通道路由) |
| 商户对接密钥 | 必须 | 业务系统无法完成签名互信 | [商户开通](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md#对接配置) |
| 存储配置（OSS） | 强烈建议 | 文件上传类功能不可用（站点素材、进件图片、对账单、导入导出） | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#存储配置) |
| 邮件（SMTP） | 强烈建议 | 邮箱找回密码、验证码通道不可用 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#邮件与短信配置) |
| 短信 | 强烈建议 | 验证码与邀请注册链路不可用 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#邮件与短信配置) |
| 用户协议 | 强烈建议 | 合规缺口：登录页协议空态 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#用户协议) |
| 系统安全策略 | 强烈建议 | 默认策略宽松（密码永不过期、会话不限时），生产应人工收紧 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#系统安全策略) |
| 风控策略（四层防线） | 强烈建议 | 默认仅部分防线生效；上线初期建议「仅记录」观察 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#支付安全风控与商户限额) |
| 商户限额 | 强烈建议 | 无限额兜底，异常交易无刹车 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#支付安全风控与商户限额) |
| 实名认证 | 按需 | 平台开关开启后才强制；不开启不影响支付 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md#实名认证) |
| 支付应用（微信/抖音） | 按需 | 微信 JSAPI/小程序收款必需；不涉及则免 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#支付应用) |
| 域名验证 | 按需 | 微信内打开页面/小程序拉起失败 | [支付能力](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#域名验证) |
| 代理商体系 | 按需 | 不启用代理商则全部商户直营；启用后需规划邀请与代管 | [商户开通](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md#先定运营模式) |
| 网关收款五环节 | 按需 | 仅 API 直连可跳过；用收银台/码牌必须完成 | [网关收款](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md) |
| 分账 / 预授权 / 收款单 / 对账 / 易支付 | 按需 | 各有通道侧前置，用到才配 | [可选功能](https://doc.plus.daxpay.cn/operation-guide/production/optional-features.md) |
## 建议时间线
以正式收款日为 T 日倒排（中小规模部署参考）。**进件审核是外部依赖**：微信/支付宝服务商进件通常需要 1~3 个工作日，材料不齐会被驳回重来，务必预留窗口：
| 时间 | 事项 |
| --- | --- |
| T-10 ~ T-7 | 域名注册备案、服务器与中间件就绪、按[基础设施](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md)完成部署与生产模式切换 |
| T-7 ~ T-5 | [平台初始化](https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md)全部必配项 + 强烈建议项；准备服务商资质（微信/支付宝服务商平台材料） |
| T-5 ~ T-3 | [支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md)：产品配置 → 费率链 → 服务商参数，随后发起进件申请并跟踪审核 |
| T-3 ~ T-1 | [商户开通](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md)与对接密钥发放；网关收款链路按需上线；沙箱联调（仅支付宝直连可用） |
| T-1 ~ T | 进件通过、通道商户就绪后，小额真实支付端到端验证（见[上线验收](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md)），核对[检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md) |
| T+1 ~ T+7 | 观察期：风控「仅记录」模式观察命中情况，日志与回调推送日常巡检 |
## 从这里开始
- 还没部署：先看[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md)（推荐，运维面板托管网关/证书/升级）或[项目构建](https://doc.plus.daxpay.cn/deployment/build.md)
- 只想快速跑通流程：走[快速上线](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)，之后再回来补全
- 系统已在运行、要补生产配置：直接按[配置域全景地图](#配置域全景地图)定位缺口
## 相关链接
- [快速上线](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：最小集跑通第一笔支付
- [上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)：两阶段验收清单
- [配置说明](https://doc.plus.daxpay.cn/deployment/configuration.md)：生产环境变量与生产校验清单
- [运维面板使用入门](https://doc.plus.daxpay.cn/tools/panel/overview.md)：面板托管的部署与日常运维
---
# 支付能力开通
**源**: https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md
# 支付能力开通
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的第三阶段：让平台**具备收款能力**。plus 的主线是「**主数据核对 → 支付产品配置 → 费率链 → 进件开通 → 审核通过自动生成通道商户 → 支付应用 / 通道路由 → 验证**」，各配置之间有严格的**先后依赖**；直连商户手工配置作为辅线并存。
>
> 通道侧（微信/支付宝服务商平台）的资质申请不在本篇展开，见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)与[支付通道](https://doc.plus.daxpay.cn/extension/channels/index.md)各篇。
## 开通主线
```mermaid
graph LR
A[核对支付主数据] --> B[支付产品配置
与服务商工作台]
B --> C[配置费率链
平台/服务商/代理商/商户]
C --> D[进件申请
资料主档+OCR+费率申报]
D --> E[审核通过
自动生成通道商户]
E --> F[支付应用登记
微信/抖音按需]
F --> G[通道路由
设为当前生效]
G --> H[域名验证与
支付调试验证]
B -. 直连辅线 .-> I[手工创建通道商户
配置直连密钥]
I --> F
```
## 产品环境
**菜单路径**：支付管理 → 通道与产品配置 → 支付和进件产品
两层环境控制（机制详解见[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)）：
| 层 | 控制 | 生产要求 |
| --- | --- | --- |
| 全局开关 | 部署配置 `sandbox-enabled` | PROD 模式强制 `false`，启动时把遗留沙箱产品**自动重置为生产** |
| 产品环境 | 产品卡片环境单选 | 上线前确认全部产品处于「生产」 |
**环境快照规则**（生产上线最容易踩的机制）：通道商户创建时按产品当时的环境**固化快照**，此后不随产品切换改变；环境不一致的通道商户被路由排除、下单直接报错。因此：
- 沙箱联调期建的通道商户（含沙箱期进件生成的）**不能复用为生产**，生产必须另走一套；
- 沙箱仅支付宝直连支持，微信只能生产小额验证（见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)）。
## 核对支付主数据
**菜单路径**：支付管理 → 支付主数据（支付通道 / 支付产品 / 支付方式等字典页）
支付主数据是通道、产品、方式、能力五个字典的**只读基线**，随平台版本演进维护，运营侧上线时只做**核对**：确认要开通的通道与支付方式在列、命名无歧义，无需关心创建顺序（页面详解见[支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)）。
与之配套的**进件主数据**决定「哪些通道可以发起进件」：进件申请下拉只列出可进件通道，运营侧可控制对客可见性与展示文案；暂不支持进件的通道会以占位形式呈现，属预期而非缺陷（见[进件产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)）。
## 支付产品配置与服务商工作台
**菜单路径**：支付管理 → 通道与产品配置 → 支付和进件产品
支付产品是收款的开关与参数载体（启停、环境、聚合方式），生产要点（详解见[支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)）：
- 上线前逐个确认目标产品处于**启用**状态，停用产品对路由不可见；
- 服务商模式（微信/支付宝 ISV）下，**服务商工作台**是进件参数的维护入口：服务商号、接口凭证、证书等都在产品配置的服务商维度维护，后续进件申请直接引用，不必重复录入；
- **进件产品（特殊）**与**通道服务商配置**也在本组页面维护：前者管理各通道的进件产品定义，后者维护每个通道的服务商参数与密钥（详解见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)与[进件产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)）。
## 费率链
**菜单路径**：支付管理 → 通道与产品配置 → 支付和进件产品 → 服务商费率 / 直连费率配置
plus 的费率是**四级链**，不是单点数字（模型详解见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)）：
```
平台费率 → 服务商费率 → 一级代理商（L1 档） → 商户费率
```
生产配置要点：
- **先配平台侧、再配服务商侧**：服务商行（微信/支付宝 ISV 定价）同时覆盖「商户实收费率」与「平台留存」，是整条链的枢纽；
- 解析链按「服务商能力 > 服务商方式 > 平台能力 > 平台方式」逐段回退，配完用**实时链校验**逐段比对，防止中间层漏配导致解析落空（操作见[支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)）；
- 费率规则支持固定金额、比例、阶梯、单笔封顶、退款累计封顶等形态，简单/高级双视图编辑同一份规则，按需选用（见[费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)）；
- **直连产品费率同样三级化全必填**，与服务商口径对齐，不要漏配；
- 费率落账：每笔交易按**费率快照**记入交易费用明细（纯费用记账，与通道侧实际扣费口径独立），上线后核对费用以此为准（见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)）。
进件时随单申报的商户费率受**平台费率下限**约束（三道闸校验，通道无关）。先在平台侧定好下限，再发起进件，否则申报会被直接拦截。
## 进件开通主线
服务商模式下，商户的通道商户**由进件自动生成**，不需要手工创建。完整链路（详解见[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)与[进件申请与工作台](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)）：
**菜单路径**：支付管理 → 商户管理 → 进件申请 → 进件申请工作台
1. **前置**：完成上文的服务商参数配置（通道服务商配置），确保目标通道的服务商凭证就位；
2. **创建申请单**：选择商户 + 服务商 + 通道。**申请单创建即锁死归属服务商**，后续换服务商只能作废重开，对外锚点始终是商户号与通道商户号；
3. **资料填报**：优先复用**进件资料主档**——商户工作台「进件资料」维护主体、法人、执照、门店四档（按商户唯一），一次维护、多张申请单勾选复用；证照图片支持 **OCR 识别**（营业执照/身份证/银行卡，多家云供应商可切），图片统一走平台媒体存储（依赖 OSS 先行配置）；
4. **费率申报**：当面付费率等随单申报，受平台费率下限三道闸拦截（见上节警示）；
5. **提交与状态机**：申请单在「待提交 → 审核中 → 渠道处理 → 成功 / 失败 / 作废」间流转，平台侧审核在运营端完成，渠道侧处理进度需跟踪；
6. **成功落地**：审核通过后系统**自动生成通道商户并绑定到商户**，后续路由、网关、分账全部挂其上，无需手工建号。
**通道差异**（决定每条通道怎么走，详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)）：
| 通道 | 进件形态 |
| --- | --- |
| 微信 | 子商户（特约商）进件，参数在服务商工作台 |
| 支付宝 | 代授权 + 产品开通两线并行 |
| Adapay | 直连进件（进件凭据与交易凭据两维度） |
| 斗拱 | 汇付旗下独立进件线 |
| 银联商务 | 平台商户进网（特殊线） |
| 抖音、银联等 | 暂不支持进件，走下文直连配置辅线 |
## 直连通道商户与密钥
**入口**：商户工作台 → 支付配置 → 通道商户（全局列表在 商户管理 → 通道商户，创建仍须从工作台进入）
不走进件的通道（直连模式，或暂不支持进件的通道）手工创建通道商户，生产要点（创建与密钥详解见[通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)与[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)）：
- **先切产品环境，再建通道商户**（环境固化，见[产品环境](#产品环境)）；
- 商户要收款**必须至少有一个启用状态的通道商户**（进件生成或手工创建均可）；
- 支付产品与系统通道商户号**创建后不可改**，只能改名称；
- **密钥配置入口按模式分工**：
- **直连模式**（微信直连/支付宝直连等）：交易密钥在**通道商户详情**配置；
- **服务商模式**（微信/支付宝 ISV）：平台级密钥在**服务商工作台**维护，进件只录「号」不录密钥。
## 支付应用
**菜单路径**：支付管理 → 支付应用（微信支付应用 / 抖音支付应用 / 收银台小程序）
微信/抖音收款前必须登记**支付应用**（AppId 所在），两条强规则（类型与绑定详解见[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)）：
- **支付方式强绑应用类型**：`wechat_jsapi` 只认公众号、`wechat_mini` 只认小程序、`wechat_app` 只认移动应用。做对应收款前先登记对应类型，否则路由无法解析；**编辑时变更应用类型会清除不兼容的能力绑定**；
- **收银台小程序全平台共用一套凭证**，且**openId 与收款应用必须同源**：平台小程序 AppId 需在所用通道侧完成绑定/报备（服务商模式通常服务商小程序 + 子商户号报备），并非所有通道开箱即用，接入前先与通道确认；这条直接影响[网关收款上线](https://doc.plus.daxpay.cn/operation-guide/production/gateway-launch.md)。
## 通道路由
**入口**：商户工作台 → 应用管理 → 应用工作台 → 通道路由
路由决定「每种支付方式走哪个通道商户」，生产要点（两种策略详解见[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)）：
- 两种策略二选一：**按渠道默认**（基础模式，一渠道一通道商户）/ **按支付方式**（场景模式，方式+能力成对配置）；当前版本**无轮询/权重/优先级**，一个维度只对应一个通道商户；
- 切换策略维度后**必须点「设为当前生效」并确认**，只切单选钮不生效，是「配了路由还是下单失败」的常见原因；
- 首次打开会初始化默认策略但**不配通道商户**，需手动补全；
- 配完用「路由命中预览」核对每个支付方式命中的通道商户与缺口。
## 域名验证
微信/支付宝在配置域名与二维码规则时会抓取支付网关域名下的校验文件核对归属（支付宝为 `.html`、微信为 `.txt` 双后缀）。**两场景两入口**，不要传错归属（机制详解见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)）：
| 场景 | 校验文件 | 上传入口 | 何时需要 |
| --- | --- | --- | --- |
| 商户级 | `MP_verify_*.txt` 等 | 商户端/商户工作台「域名校验文件」 | 商户自己的公众号网页授权、小程序业务域名 |
| 平台级 | 随机名 `.txt` / `.html` | 支付管理 → 接入配置 → 域名校验文件 | 收银台/聚合小程序「扫普通链接二维码」规则、支付宝关联普通二维码 |
文件放置方式支持手动选择（本地直传 / 平台应答等模式按页面提示选择）。网关侧的文件应答反代已在[基础设施](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md#域名验证文件的网关侧预留)预留，**文件上传后无需改 nginx**，但域名须先公网可达。
## 支付安全风控与商户限额
**菜单路径**：支付管理 → 支付安全（风控策略等页面）
plus 的风控是**四层事前防线 + 事后闭环**，不是单一 IP 名单（防线全景见[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)，页面操作见[支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)）：
| 防线 | 机制 | 上线建议 |
| --- | --- | --- |
| IP 黑名单 | 名单维护 + 批量导入 | 上线即启用；命中可自动转黑 |
| 用户标识黑名单 | openid 等用户标识级 | 启用 |
| 省市地区 | 放行/拦截名单双模式 | 按业务地域定；IPv6 精度有限，谨慎开 |
| 门店围栏 | 平台总闸 + 商户自主开启，三档策略 | 平台先开总闸，商户按需自主收紧 |
| 事后闭环 | 风险命中事后补录、命中转黑名单 | 配合「风控预警」页观察 |
| 频率限制 | 请求频率、账号日限、IP 日限 | 保持启用；IP 日限全平台共享计数，商户侧重叠配置只改阈值 |
- **命中阻断下单**：上线初期建议先「仅记录」观察误拦，再切换为阻断；命中拦截时商户侧只收到统一的「交易被限制」提示（刻意不暴露细节），排查看「风险命中记录」；
- **商户限额**：平台模板 / 商户 / 应用三级配置，限额类型含单笔、日累计、日笔数（矩阵化表单配置，见[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)）。**平台默认限额挂在风控策略页的「限额兜底」**，是所有商户的最后一道刹车，上线前必须确认兜底值；退款侧另有日累计限额兜底，防批量退款搬钱。
注意：风控检查发生在**下单时**（普通/网关/码牌均覆盖），退款不经过风控、由限额兜底。
## 验证
每个产品开通完成后，用商户端「开发调试 → 支付调试(普通)」走一遍（操作见[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)）：
- 生产环境用**小额真实支付**（如 0.01 元）验证全链路（下单 → 付款 → 回调 → 订单成功）；
- 微信无沙箱，本就只能小额真实验证；
- 验证失败按支付方式逐环排查：路由命中预览 → 支付应用类型 → 通道密钥 → 产品环境，常见错误对照见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 本阶段核对清单
- [ ] 全部产品环境为「生产」，沙箱产品已被自动重置
- [ ] 服务商工作台参数（微信/支付宝 ISV 凭证）配置完成
- [ ] 费率链四级配置完成，实时链校验无缺口，平台费率下限已定
- [ ] 进件申请已提交并跟踪至通过，通道商户自动生成（服务商模式）
- [ ] 直连通道（如使用）手工创建通道商户 + 密钥配置完成
- [ ] 微信/抖音支付应用按收款方式登记齐（类型匹配）
- [ ] 通道路由已「设为当前生效」，命中预览无缺口
- [ ] 域名验证两场景按需完成
- [ ] 风控四层防线与「命中阻断」按观察期策略设定，限额兜底值已确认
- [ ] 每个通道产品小额真实支付验证通过
下一阶段：[商户开通与对接就绪](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md)。
## 相关链接
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md) / [进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)：进件主线详解
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md) / [费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)：费率体系详解
- [风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md) / [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)：安全防线详解
- [支付产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md) / [进件产品配置](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)：产品与服务商配置页面
---
# 平台初始化配置
**源**: https://doc.plus.daxpay.cn/operation-guide/production/platform-init.md
# 平台初始化配置
> 本篇是[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)的第二阶段：系统已按[基础设施](https://doc.plus.daxpay.cn/operation-guide/production/infrastructure.md)以 PROD 形态运行，现在把**平台自身**配置到可运营状态。每个配置域说明是否必须、不配的后果、配置入口与详情链接，字段级操作见对应文档。
>
> 菜单均指**运营端**。商户侧配置在[商户开通](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md)阶段处理。
## 配置域速览
| 配置域 | 必须 | 不配后果 | 详情 |
| --- | --- | --- | --- |
| 运营管理员账号 | 必须 | 无人可安全登录运营端 | [用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md) |
| 端点配置 | 必须 | 跳转、回调、登录回调地址全部错误 | [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md) |
| 系统安全策略 | 强烈建议 | 默认宽松：密码永不过期、会话不限时 | [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md) |
| 存储配置（OSS） | 强烈建议 | 文件上传类功能全不可用（含进件图片） | [存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md) |
| 邮件（SMTP） | 强烈建议 | 邮箱找回密码、验证码不可用 | [通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md) |
| 短信 | 强烈建议 | 短信验证码与邀请注册链路不可用 | [通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md) |
| 用户协议 | 强烈建议 | 登录页协议空态，合规缺口 | [用户协议](https://doc.plus.daxpay.cn/operation-guide/admin/user-protocol.md) |
| 实名认证 | 按需 | 平台门禁开启后才强制 | [商户资料与门店](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md) |
| 站点配置 | 按需 | 页脚缺备案信息（对外站点建议配） | [支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md) |
| 三方登录 | 按需 | 不影响支付；依赖端点配置先行 | [第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md) |
| 敏感词 / 字典 | 默认即可 | 保持默认即可，一般无需动 | [敏感词管理](https://doc.plus.daxpay.cn/operation-guide/admin/sensitive-word.md) |
## 账号与权限
生产环境的账号基本要求（操作细节见[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)与[权限与菜单管理](https://doc.plus.daxpay.cn/operation-guide/admin/perm-menu.md)）：
- **创建正式运营管理员账号**并分配角色与菜单权限，日常只用它登录。开发超管（`enable-admin=false`）在 PROD 已强制关闭，仅 dev 联调可用；
- **不要共用内置超管**，按职责建独立角色（建议复制内置角色再裁剪，不要直接改内置角色）；
- 角色规划建议至少分：运营管理员（全量）、风控/客服（订单与日志只读）、只读审计；启用代理商体系时，另为代理商端预置「代理商操作员」类角色（终端选代理商端）。
**每次系统升级后必须执行一次「同步权限码」**（菜单管理页）：不执行则新版本新增的按钮权限对已授权角色不可见。升级时的完整步骤见[上线验收与运维交接](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md#升级流程)。
## 端点配置
**菜单路径**：系统管理 → 系统配置 → 平台配置 → 端点配置
端点配置是全系统对外地址的**真相源**，生产要求（字段说明与检查按钮见[支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)）：
| 端点 | 生产要求 | 不配/配错后果 |
| --- | --- | --- |
| 支付网关前端地址 | 与 H5 收银台部署域名**严格一致**，HTTPS | 收款链接、支付结果回跳 404；微信/支付宝授权回调失败 |
| 后端 API 地址 | **公网可达** HTTPS（通道回调依赖） | 通道回调进不来，订单停在待支付 |
| 运营端访问地址 | 运营端实际域名 | 三方登录运营端回调地址错误 |
| 代理商端访问地址 | 代理商端实际域名（启用代理商体系时） | 三方登录代理商端回调地址错误 |
| 商户端访问地址 | 商户端实际域名 | 三方登录回调、跨端跳转错误 |
配置后用每个地址旁的「检查」按钮验证（后端 API 走部署自检探针）。
「页面跳 404」「回调收不到」「三方登录跳转异常」这类问题，先核对端点配置与实际部署域名是否一致，再看[收银台部署与上线](https://doc.plus.daxpay.cn/operation-guide/cashier/deploy.md)的域名契约。
## 系统安全策略
**菜单路径**：系统管理 → 系统配置 → 系统安全配置
策略默认偏宽松（便于首次体验），**生产必须人工收紧**。默认值与收紧建议（配置项详解见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)）：
| 面板 | 默认宽松点 | 生产建议 |
| --- | --- | --- |
| 密码策略 | 轮换周期 0=永不过期、历史记录 0=不限 | 按合规要求设轮换周期与历史限制；最小长度 ≥8 |
| 登录安全 | 失败锁定与验证码阈值默认可用 | 保持开启，验证码阈值 ≤ 锁定阈值 |
| 会话管理 | 最大活跃时长 0=不限 | 设上限；并发超限策略按业务选（推荐「踢出最早」） |
| 双因素认证 | 默认关 | 运营端账号建议开启（用户在个人中心绑定 TOTP） |
| 通行密钥 | 默认关 | 按需；**依赖 HTTPS**，且改站点域名会使已绑密钥全部失效 |
| 防重放校验 | 默认关 | 开启后商户请求须带随机数与时间字段。开放给外部商户前先评估对方接入成本，详见[支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md) |
注意区分：这里的「防重放」属于 IAM 登录/API 层安全；**支付域**的风控在[支付能力 - 支付安全风控与商户限额](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md#支付安全风控与商户限额)。
## 存储配置
**菜单路径**：系统管理 → 系统配置 → 平台配置 → OSS 配置
平台文件统一走 S3 兼容对象存储，**没有本地存储兜底**。不配置的后果：站点素材、进件图片、对账单、导入导出等一切文件上传/下载功能不可用（核心支付不受影响）——**进件资料里的证照图片依赖平台媒体存储，开通进件前必须配好**。
上线两个高频坑（配置详解见[存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md)）：
- **桶必须配 CORS 跨域规则**：上传是「浏览器预签名直传」对象存储，「测试连接」通过≠能上传，CORS 漏配是上线后上传失败的常见原因；
- **单桶方案使「私有」名义化**：生产建议公开桶 + 私有桶分开建，公开桶设公共读。
## 邮件与短信配置
**菜单路径**：系统管理 → 系统配置 → 平台配置 → 邮件配置；通知中心 → 短信发送记录
- **邮件（SMTP）**：不配的后果是邮件全链路不可用，**邮箱找回密码通道关闭**（登录页找回入口会给提示）、邮箱绑定/解绑验证码全部发不出；账号密码登录不受影响。面向商户开放的部署建议配好，保存后发一封测试邮件验证。邮件模板按场景维护，支持在线预览后再启用（配置字段见[通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)）。
- **短信**：短信验证码是**邀请注册**（手机号 + 验证码注册商户/代理商）的依赖，未配置时注册链路不可用。生产要点：
- 开发环境内置 mock 供应商（不出网、仅联调），生产必须切换为真实供应商并验证发送；
- **防刷保护默认生效**：单号频次、单号日限、平台总量三道闸，上线前按业务量复核阈值；
- 「短信发送记录」页可查每条短信的发送结果，作为投诉时的第一排查入口。
## 用户协议
**菜单路径**：系统管理 → 基础数据 → 用户协议
未配置时登录页协议为空态、登录不受影响，但**对外运营属合规缺口**：上线前把《用户协议》《隐私政策》**发布**（草稿不生效）。注意「同一协议只有一个生效版本」，新版本发布不会强制已同意用户重新确认，重大变更需配合公告（见[用户协议](https://doc.plus.daxpay.cn/operation-guide/admin/user-protocol.md)）。
## 站点配置
**菜单路径**：系统管理 → 系统配置 → 平台配置 → 站点配置
系统名称、Logo、ICP/公安/支付清算/增值电信备案号、版权信息。对外运营的站点**必须展示备案号**（页脚渲染依赖此配置），与域名备案信息保持一致。
## 三方登录（可选）
**菜单路径**：系统管理 → 系统配置 → 第三方平台
支持微信、支付宝、抖音开放平台扫码登录，平台级凭据统一维护、各端应用按需启用。上线依赖链（配置详解见[第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)）：
1. **端点配置先行**：三方回调地址由端点按运营端、代理商端、商户端分别拼出，端点没配会直接提示；
2. 跳转型平台额外依赖「支付网关前端地址」（经收银台中转页回跳，见[认证与中转](https://doc.plus.daxpay.cn/operation-guide/cashier/auth.md)）；
3. 开放平台侧登记回调域名，再回平台配密钥。
不启用不影响支付功能。
## 敏感词
**菜单路径**：系统管理 → 基础数据 → 敏感词
系统在代理商名称、收款单、退款原因、用户名、进件名称、邀请码名称等关键录入点做敏感词校验。默认词库可直接使用；有行业合规要求时补充自有词库并选择过滤策略（词库与命中记录见[敏感词管理](https://doc.plus.daxpay.cn/operation-guide/admin/sensitive-word.md)）。一般无需在上线期特别处理，属「默认即可」项。
## 实名认证
平台级**单开关门禁**：开启后商户需在商户端「实名认证」页完成（支付宝实名核验），不开启则全流程不强制、不影响支付。面向外部商户开放、且资金合规要求实名时开启；凭据复用三方平台 OAuth 凭据体系，无需单独申请（商户侧操作见[商户资料与门店](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md)）。
## 本阶段核对清单
- [ ] 正式运营管理员账号可登录，角色按职责分配，超管不共用
- [ ] 端点配置五项与部署域名一致，检查按钮全部通过
- [ ] 密码/会话策略已收紧，运营端 2FA 已评估
- [ ] OSS 已配置且桶 CORS 已加，真实上传验证过（进件图片依赖此项）
- [ ] SMTP 已配置，测试邮件可达
- [ ] 短信已切真实供应商，防刷阈值已复核，发送记录可查
- [ ] 用户协议与隐私政策已发布
- [ ] 站点备案信息已填
- [ ] 实名认证门禁已决策（开或不开，明确口径）
下一阶段：[支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md)。
## 相关链接
- [运营工作台](https://doc.plus.daxpay.cn/operation-guide/admin/workspace.md)：运营端首页与配置告警
- [通知与邮件](https://doc.plus.daxpay.cn/operation-guide/admin/notify-mail.md)：邮件模板与短信发送记录
- [系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)：各安全面板详解
- [第三方平台登录](https://doc.plus.daxpay.cn/operation-guide/admin/third-platform.md)：三方登录配置
---
# 支付通道对接
**源**: https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md
# 支付通道对接
> 本文是[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)第五步的展开。plus 的通道开通分两种模式：**服务商进件**（主线，提交进件申请，审核通过自动生成通道商户）与**直连自助配置**（辅助线，商户已有直连商户号时手工登记）。
>
> 其他通道的对接流程同构，具体参数见[支付通道总览](https://doc.plus.daxpay.cn/extension/channels/.md)各篇。
## 通用链路
```mermaid
graph LR
A[选择接入模式] --> B{服务商进件?}
B -- 主线 --> C[服务商工作台
配置服务商参数与费率]
C --> D[创建进件申请
资料填报 + 提交]
D --> E[审核通过
自动生成通道商户]
B -- 辅助线 --> F[创建通道商户
选择环境并固化]
F --> G[配置通道密钥]
E --> H{微信通道?}
G --> H
H -- JSAPI/小程序等 --> I[配置支付应用]
H -- 其他 --> J[支付调试验证]
I --> J
```
直连模式下创建通道商户时，若产品声明「支持沙箱」且平台沙箱总闸（`daxpay.platform.config.sandbox-enabled`）开启，表单会出现运行环境选择（生产 / 沙箱），**创建时固化、不可修改**；沙箱通道商户需在密钥配置中维护沙箱密钥。进件线没有沙箱概念，申请通过即生产可用。
两种接入模式对比：
| 接入模式 | 适用产品举例 | 前置条件 | 通道商户来源 |
| --- | --- | --- | --- |
| **服务商进件（主线）** | 微信（服务商）、支付宝（服务商）、拉卡拉、乐刷、汇付 Adapay / 斗拱等聚合通道 | 通道服务商配置：服务商参数 + 服务商费率 | 进件审核通过后**自动生成** |
| 直连自助配置（辅助线） | 支付宝（直连）、微信支付（直连）等直连产品 | 商户已有通道侧商户号与应用 | 运营端手工创建 |
## 服务商模式（主线）：进件开通
三步完成，详细操作见[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)：
1. **配置服务商参数**：「支付管理 → 通道与产品配置 → 通道服务商配置」，在**服务商工作台**维护服务商参数（如微信服务商进件参数、支付宝服务商应用信息）与**服务商费率**；服务商行同时决定商户费率与平台留存，配置说明见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)；
2. **创建进件申请**：「商户管理 → 进件申请 → 新建进件申请」，选商户、选进件产品、选**归属服务商（创建后锁定不可变更）**，复用进件资料主档填报资料，费率随申请申报（受平台费率下限约束）；
3. **审核通过**：状态机流转（草稿 → 预审 → 申请中 → 通过 → 已生成商户），到达「通过」后系统**自动生成通道商户**并完成绑定，**无需也不应再手工创建通道商户**。
进件开通的通道没有沙箱环境，验证方式是**小额真实支付**（如 0.01 元扫码）走完整链路，确认订单、回调、退款均正常后放开业务。
各通道进件方式差异（微信子商户特约商进件、支付宝代授权与产品开通两线、Adapay 直连进件、斗拱独立进件线等）见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 直连模式（辅助线）：支付宝（直连）示例
### 通道侧准备
1. 注册[支付宝开放平台](https://open.alipay.com)账号，创建**网页 / 移动应用**，获得应用 AppId；
2. 用支付宝官方**密钥工具**生成 RSA2 密钥对（公钥模式），应用公钥配置到开放平台，**支付宝公钥**从开放平台「开放平台密钥」页面获取；
3. 沙箱联调使用开放平台「沙箱环境」页提供的沙箱应用与沙箱买家账号，无需企业认证。
### 创建通道商户
入口：**商户工作台 → 支付配置 → 通道商户 → 创建通道商户**（独立发起时先选商户），两步向导：
- **Step 1 选择支付产品**：卡片式列出已启用产品，选择「支付宝（直连）」；
- **Step 2 填写通道信息**：通道商户名称 + **支付宝商家用户 ID**（`2088` 开头的 PID，沙箱环境填沙箱商家账号）；支持沙箱的产品在此步选择运行环境（创建时固化）。
微信（直连）对照：通道信息为通道商户名称 + **微信支付商户号**（`mchId`）。
### 应用管理与密钥配置
支付宝直连的密钥按「**应用**」维度组织：通道商户详情 → **应用管理**，先登记支付宝应用（应用名称、支付宝应用 ID、应用类型），再进入应用的**密钥配置**：
| 认证方式 | 需配置的字段 | 说明 |
| --- | --- | --- |
| 公钥（`public_key`） | 应用ID、**支付宝公钥**、**应用私钥** | 配置最简单，联调首选 |
| 证书（`cert`） | 应用ID、应用公钥证书、支付宝公钥证书、支付宝根证书（三个 `.crt` 文件上传）、应用私钥 | 部分接口要求证书模式 |
**通信密钥**（可选）：AES 密钥，从开放平台控制台获取，仅部分接口报文加解密使用。网关地址无需配置：系统按通道商户的环境自动选择支付宝网关（沙箱 / 生产）。密钥是否正确在支付调试发起交易时验证。
「支付宝公钥」填的是**开放平台展示给你**、用于验签支付宝报文的公钥，**不是**你自己生成的「应用公钥」。两者填反是联调失败的最常见原因；证书模式还需与开放平台「接口加签方式」的设置保持一致。
### 微信（直连）密钥对照
微信直连在通道商户详情的**直连密钥配置**中维护，凭据分两组：
| 分组 | 字段 |
| --- | --- |
| 接口密钥 | API V3 密钥（商户平台「API 安全」中设置） |
| 支付证书 | API 证书（`apiclient_cert.pem`）、API 证书私钥（`apiclient_key.pem`）、证书序列号、支付公钥（`pub_key.pem`）、支付公钥 ID |
微信 2024 年后新发放的商户使用「支付公钥」替代「平台证书」，老商户仍走证书体系；按商户平台实际提供的材料如实填写即可，编辑时留空的密文字段表示保留原值。
微信官方不提供沙箱联调环境（支付宝才有）。微信直连通道商户只能以**生产环境**创建，用**小额真实支付**验证，通过后可直接投入使用。
## 支付应用(微信)
微信的 `wxAppId` 不在密钥里，而在**应用维度**单独登记：商户工作台 → 支付配置 → **支付应用(微信)**（或支付管理 → 支付应用）。每条记录登记应用名称、应用类型、微信 AppId 与 AppSecret。
**应用类型与支付方式的强绑定关系**：
| 支付方式 | 要求的应用类型 |
| --- | --- |
| `wechat_jsapi` / 统一收银台（微信内打开） | **公众号**（场景强绑 openId，需网页授权） |
| `wechat_mini` 小程序支付 | **小程序** |
| `wechat_app` APP 支付 | **移动应用** |
| `wechat_qr` / `wechat_h5` / `wechat_barcode` | 兼容以上类型 |
做微信 JSAPI 或小程序收款前，必须先登记对应类型的应用，否则路由无法解析。
## 域名牌验证文件
微信 / 支付宝在配置域名归属与二维码规则时，会抓取支付网关域名下的校验文件核对归属。文件上传到系统即可（存库由后端动态应答，无需手工往服务器放文件）：
- **商户级**：商户自己公众号 / 小程序的域名验证（网页授权域名、业务域名），微信公众平台下载 `MP_verify_*.txt` 后上传到「商户端 → 商户中心 → 业务配置 → 域名校验文件」（运营可在商户工作台「接入配置 → 域名校验文件」代传）；
- **平台级**：收银台小程序「扫普通链接二维码」规则的校验文件（微信为随机名 `.txt`，支付宝为 32 位 hex 的 `.html`），由运营在「支付管理 → 接入配置 → 域名校验文件」上传，校验文件会对域名根路径与 `/m/`、`/cm/`、`/am/` 目录下的同名请求原样应答。
## 通道商户详情总览
创建通道商户后，从列表「管理」进入详情页：顶部展示基础信息与**环境标识**（创建时固化，不随产品切换改变），主体区按通道装配该通道的功能磁贴：
| 功能 | 支付宝（直连） | 微信（直连） |
| --- | --- | --- |
| 密钥 / 参数配置 | **应用管理**（支付宝应用 → 密钥配置） | **直连密钥配置** |
| 应用绑定 | 支付宝应用（应用 ID + 应用类型） | 经「支付应用(微信)」登记 wxAppId |
| 危险操作 | 删除通道商户（不可撤销，删除后该商户所有配置不可用） | 同左 |
进件生成的通道商户与手工创建的通道商户使用同一套详情页，差异在于进件线的通道侧编号由机构返回、凭据由系统代持，一般无需手工维护密钥。
## 常见问题
| 现象 | 原因与处理 |
| --- | --- |
| 支付宝报「密钥错误 / 验签失败」 | 支付宝公钥与应用公钥填反；或认证方式与开放平台「接口加签方式」不一致 |
| 微信（服务商）报「受理机构必须传入 sub_mch_id」 | 服务商模式下特约商户参数缺失，排查步骤见[微信服务商 sub_mch_id 专项 FAQ](https://doc.plus.daxpay.cn/getting-started/faq/wechat-isv-sub-mch-id.md) |
| 微信报「证书序列号不匹配」 | 序列号与上传的 `apiclient_cert.pem` 不是同一份，重新从商户平台下载 |
| 微信 JSAPI 报「缺少 appid / openid」 | 未在「支付应用(微信)」登记**公众号**类型应用，或未获取用户 openId |
| 微信内打开支付页白屏 / 提示域名未验证 | 域名校验文件未上传或未在微信侧完成域名配置 |
| 发起支付报「通道商户环境不匹配」 | 通道商户固化的环境与产品当前环境不一致，按正确环境重建通道商户 |
## 相关链接
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：上线主线（含沙箱验证全流程）
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：密钥验证之后的系统接入
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：直连 / 服务商两种模式与三段式配置模型
- [进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md) / [通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)：主线进件详解
- [完整上线指南 - 支付能力开通](https://doc.plus.daxpay.cn/operation-guide/production/payment-capability.md)：生产环境开通主线
- [支付通道总览](https://doc.plus.daxpay.cn/extension/channels/.md)：全部通道参数索引（[支付宝](https://doc.plus.daxpay.cn/extension/channels/alipay.md)、[微信支付](https://doc.plus.daxpay.cn/extension/channels/wechat.md)）
---
# 上线检查清单
**源**: https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md
# 上线检查清单
> 系统部署完成后，按本清单逐项核对即可完成上线。**✳️ 为必须项**，不完成将影响核心流程；**🌟 为推荐项**，按实际场景选择。
>
> 各项的具体操作见[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)对应步骤。生产环境的全量配置与验收流程见[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)。
## 第一阶段：运营端初始化
让系统具备基本的可登录、可配置、可收款状态。
### 账号与安全
- ✳️ 生产环境：创建正式运营管理员账号并分配权限，确认配置项 `enable-admin=false` 关闭开发超管（开发超管仅 dev 环境可登录，生产环境无法登录）
- ✳️ 修改超级管理员默认密码（`bootx` / `121212` 为种子数据默认值，登录运营端后立即修改）
- 🌟 为不同职责的运营人员分配独立角色（见[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)）
- 🌟 按需配置密码策略、登录锁定与 2FA（见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)）
### 部署模式与生产校验（plus）
- ✳️ 生产环境：显式设置 `SPRING_PROFILES_ACTIVE=prod`（最高频事故是忘切 profile，dev 不会被拦截）
- ✳️ 生产环境：确认部署模式为 PROD（`daxpay.platform.deployment.mode=PROD`，未显式配置按 profile 推断）；PROD 模式启动会 fail-fast 校验生产配置（沙箱总闸关闭、超管入口关闭、api-docs / swagger 关闭、CORS 关闭、actuator 收紧等），不满足直接拒绝启动
- ✳️ 生产环境：确认 `sandbox-enabled=false`（沙箱总闸，生产强制关闭）
### 平台配置（系统管理 → 系统配置 → 平台配置）
- ✳️ 端点配置 — **支付网关前端地址**（收银台跳转依赖）与**后端 API 地址**（回调通知依赖），填写后用「检查」按钮验证连通性
- ✳️ 生产环境：后端 API 地址须为**公网可达**地址（支付宝 / 微信等通道回调依赖），建议启用 HTTPS；本地 / 内网联调场景参见[本地联调](https://doc.plus.daxpay.cn/deployment/debug.md)
- 🌟 端点配置 — 运营端 / 代理商端 / 商户端访问地址（三方登录回调用）
- 🌟 站点配置 — 系统名称、Logo、备案与版权信息
- 🌟 OSS 配置 — 文件存储，详见[存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md)
- 🌟 邮件配置 / 短信配置 — 找回密码、通知与验证码场景
- 🌟 OCR 配置 — 进件资料识别用（启用进件线时建议配置）
### 支付产品与进件准备（支付管理 → 通道与产品配置）
- ✳️ 「支付和进件产品」中确认目标产品已启用；「支付主数据」核对内置产品 / 通道 / 方式的启用状态（主数据只读）
- ✳️ 进件线：在「通道服务商配置」的**服务商工作台**核对服务商参数（微信服务商进件参数、支付宝服务商应用等）
- ✳️ 进件线：核对**服务商费率**与平台费率下限（服务商行同时决定商户费率与平台留存，见[支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)）
- 🌟 沙箱联调时：确认平台沙箱总闸开启，且目标产品声明支持沙箱（沙箱环境在创建通道商户时选择并固化）
### 支付安全与风控（plus）
- 🌟 配置[风控策略](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)：四层事前防线（IP 黑名单 / 用户标识 / 省市地区 / 门店围栏）按需启用，上线初期可保持默认，运行期按风险情况收紧
- 🌟 配置**频率限制**（请求频率、账号日限、IP 日限）与风控预警接收人；「黑名单管理」「风险命中记录」供事后回查
- 🌟 配置[商户限额](https://doc.plus.daxpay.cn/plus/mch-limit/.md)：平台默认限额（挂风控策略「限额兜底」）、限额模板与重点商户的单笔 / 日累计 / 日笔数限额
- 🌟 如启用**实名认证门禁**：在平台配置「实名核验」中完成凭据配置（复用三方平台 OAuth 凭据），开启后商户需通过实名认证后方可交易
## 第二阶段：商户与支付就绪
让一个商户可以真正收到钱。
### 商户开通（商户管理 → 商户列表）
- ✳️ 创建商户（或发放邀请码走邀请注册）：填写商户信息与管理员信息，**记录只展示一次的管理员初始密码**
- 🌟 将初始密码转告商户管理员，并提醒其首次登录商户端后修改密码
- ✳️ 确认商户的默认应用与默认门店已自动创建（商户工作台 → 应用管理）
- 🌟 挂靠代理商的商户：确认归属代理商正确（商户归属调拨有审计记录，见[商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)）
### 支付能力开通（进件主线 / 直连辅助线）
- ✳️ 进件线：**进件状态核对** — 申请单状态到达「通过 / 已生成商户」，通道商户已自动生成并绑定（商户管理 → 进件申请）
- ✳️ 进件线：**费率配置核对** — 通过后确认该商户费率（商户工作台 → 支付配置），费率解析链为 服务商 > 平台 逐级回退
- ✳️ 直连线：创建通道商户（选产品并填写通道参数，支付宝为商家用户 ID，微信为商户号），配置通道密钥（支付宝：应用ID + 认证方式 + 支付宝公钥 + 应用私钥；微信：API V3 密钥 + API 证书 + 证书序列号 + 支付公钥）
- ✳️ 核对通道商户的环境标识与预期一致（沙箱联调时应为「沙箱」；环境创建时固化，不可修改）
- 🌟 沙箱与生产各建一套直连通道商户与密钥（环境固化互不通用，生产上线时必须重建），详见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)
### 对接签名（商户端 → 商户中心 → 业务配置 → 对接配置）
- ✳️ 生成商户 RSA 密钥对并保存商户公钥（**私钥只显示一次，妥善保管**）
- ✳️ 复制平台公钥到业务系统（用于验证响应与回调签名）
- 🌟 通信密钥（AES，数据加密预留字段，可后补）
### 可选功能配置
- 🌟 网关支付配置（应用工作台）：使用统一收银台 / 聚合扫码 / 码牌场景时配置，普通接口对接不需要，详见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)
- 🌟 域名校验文件（商户端业务配置 / 运营端接入配置）：需在微信内打开 H5 / JSAPI 支付页或收银台时，先上传微信侧下发的 `MP_verify_*.txt` 完成归属校验；收银台小程序「扫普通链接二维码」规则的校验文件由运营端上传
- 🌟 收银台配置（应用工作台）：自定义收银台页面在各环境下的支付方式展示
- 🌟 通道路由（应用工作台）：指定应用各支付方式走哪个通道商户（多通道分流场景），详见[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)
- 🌟 分账收款：先在微信 / 支付宝等商户平台为商户开通**分账产品权限**，再进入通道商户管理页**绑定分账接收方**；下单时声明 `allocation=true` 冻结资金后方可发起分账，详见[支付分账](https://doc.plus.daxpay.cn/common/alloc.md)
- 🌟 易支付兼容接口（`/epay`）：面向使用易支付协议对接的商户，详见[易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)
## 验收
- ✳️ 「开发调试 → 支付调试(普通)」设置商户私钥后，成功发起一笔支付并展示二维码（沙箱线用沙箱环境；进件线与微信直连用小额真实支付）
- ✳️ 完成付款后，订单业务状态变为「成功」（回调不可达时手动「同步」亦可）
- ✳️ 「支付交易」页可查到该笔资金交易，金额与可退余额正确；进件线另核对一笔**交易费用明细**的费率与预期一致
- 🌟 用「签名调试」页面复核一次待签名原文，确认业务系统签名实现与平台一致
- 🌟 生产上线前用小额真实支付做一次端到端验证（含真实回调），并执行[上线验收与运维交接](https://doc.plus.daxpay.cn/operation-guide/production/go-live.md)的检查项
## 相关链接
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：各项对应的详细操作步骤
- [支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md) / [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：通道与系统对接细节
- [完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)：生产环境全量配置与验收
- [支付安全与风控](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md) / [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/.md)：plus 安全防线配置
---
# 业务系统对接
**源**: https://doc.plus.daxpay.cn/operation-guide/setup/integration.md
# 业务系统对接
> [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)第七、八步已经跑通了系统内置的支付调试；本文讲的是下一步，**让你的业务系统真正调用 unipay 开放接口**：凭证从哪来、怎么保管，回调怎么联调，错了去哪查。
>
> 本文讲**操作与决策**；请求参数、签名算法、报文格式等协议细节见[接口文档](https://doc.plus.daxpay.cn/api/overview.md)。
## 凭证清单
业务系统接入需要以下四样东西，全部来自**对接配置**页面（商户端：商户中心 → 业务配置 → 对接配置；运营端可代管：商户工作台 → 接入配置 → 对接配置）：
| 凭证 | 获取操作 | 用途 |
| --- | --- | --- |
| **商户号 `mchNo`** | 商户列表 / 商户资料中查看 | 请求身份标识 |
| **应用号 `appId`** | 应用管理卡片上查看（`A` 开头） | 调用隔离单元；不传则回落默认应用 |
| **商户私钥** | 对接配置 → 商户公钥区「生成密钥对」，**私钥在弹窗中只展示一次** | 业务系统给**请求**签名 |
| **平台公钥** | 对接配置 → 平台公钥区「复制」 | 业务系统验证平台**响应与回调**的签名 |
可选：**通信密钥**（AES），用于接口敏感数据加解密，联调阶段可以先不配。
商户私钥不展示第二次、平台侧不留存。丢失后只能在对接配置页重新「生成密钥对」并「保存」（旧公钥被覆盖，用旧私钥签名的请求会验签失败）。生成后立即妥善保存。
### 密钥保管规范
- 私钥**禁止**提交进代码仓库、禁止写死在代码里；通过环境变量或配置中心注入，生产环境建议独立于应用配置管理。
- 业务系统与平台**各自只保管自己的私钥**和对方的公钥，不交换私钥。
- 密钥按环境隔离：沙箱与生产使用不同的密钥对，避免测试系统用生产私钥签名。
## 回调通知联调
支付 / 退款结果通过**异步回调**推送给业务系统（`notifyUrl` 在下单时按请求传入）：
1. **准备接收端**：`notifyUrl` 必须是**公网可达**的 HTTP(S) 地址，与「后端 API 地址」的公网要求同理；本地联调可参照[本地联调](https://doc.plus.daxpay.cn/deployment/debug.md)处理；
2. **验证回调链路**：在支付调试页的「异步通知地址」填入你的接收地址并发起支付，确认服务端收到报文；
3. **先验签再处理**：回调报文带平台签名，**必须先用平台公钥验签**再处理业务，防止伪造通知；应答格式与重推规则见[异步回调](https://doc.plus.daxpay.cn/api/notice/callback.md)；
4. **幂等处理**：同一笔订单可能收到多次通知（重试机制存在），以订单号幂等去重；
5. **查推送记录**：平台侧在「交易管理 → 回调通知 → 商户回调推送」可查看每次通知的发送记录与响应，失败任务可手动**重推**，这里是联调排错最先要看的地方。
本地能下单但收不到回调时，先看商户回调推送页：有记录且失败 → 检查你的接收端；无记录 → 检查下单参数里的 `notifyUrl` 是否正确。
## 对接方式选型
plus 开放接口协议与签名机制完全公开（RSA 签名 + 统一报文），业务系统可直接按[签名机制](https://doc.plus.daxpay.cn/api/signature.md)自行对接：请求组参 → 字典序排序 → 拼接待签名串 → 商户私钥签名，响应与回调用平台公钥验签。
- 常规语言按签名机制实现即可，参数排序为字典序，时间字段统一东八区 `yyyy-MM-dd HH:mm:ss`；
- 对接前先用「开发调试 → 签名调试」页比对待签名串，可以少走大部分弯路；
- 各接口的路径、参数与响应结构见[接口文档](https://doc.plus.daxpay.cn/api/overview.md)。
## 联调流程建议
```mermaid
graph LR
A[沙箱环境
跑通下单/查询] --> B[回调联调
notifyUrl 收到并验签]
B --> C[退款/关单等
全接口过一遍]
C --> D[切换生产密钥
与通道商户]
D --> E[小额真实支付
端到端验证]
```
- 沙箱环境不产生真实资金，接口行为与生产一致，尽量在沙箱把主流程与异常流（支付超时、退款）都过一遍；
- 沙箱仅部分直连产品（如支付宝直连）支持；微信等其他通道无沙箱环境，用生产通道商户以**小额真实支付**验证；进件开通的通道同样以小额真实支付验证；
- 切生产时需要替换三处：**基础地址**（后端 API 地址）、**商户密钥对**（建议生产重新生成）、**通道商户**（生产环境的通道商户与密钥）；
- 生产首笔用小额真实支付验证完整链路（含真实回调），确认后再放开业务。
## 排错工具
| 工具 | 位置 | 用途 |
| --- | --- | --- |
| 支付调试(普通/网关) | 开发调试 | 不写代码复现下单、组参与签名全链路 |
| **签名调试** | 开发调试 | 输入参数与私钥复现**待签名串与签名值**；「签名验证」页签反向验证，排查验签失败首选 |
| 支付接口日志 | 系统管理 → 日志管理 → 支付接口日志 | 平台侧收到的完整请求 / 响应报文 |
| 商户回调推送 | 交易管理 → 回调通知 | 平台→业务系统通知的发送记录与重推 |
| 通道回调记录 | 交易管理 → 回调通知 | 通道→平台通知的接收记录 |
## 常见联调错误对照
| 现象 | 原因与处理 |
| --- | --- |
| 验签失败 / 签名不正确 | 私钥与平台上保存的商户公钥不配对（重新生成过密钥对？）；时间字段未按东八区 `yyyy-MM-dd HH:mm:ss` 传输；参数排序非字典序。用签名调试页比对待签名串 |
| 请求被拒绝：缺必填字段 | 检查 `mchNo`、`reqId`、`reqTime`、`sign` 与业务必填项；`appId` 不传时确认商户已配置默认应用 |
| 提示商户或应用不可用 | 商户被禁用、应用被停用或 appId 与商户号不匹配（对照[应用配置](https://doc.plus.daxpay.cn/operation-guide/admin/app-config.md)） |
| 下单成功但收不到回调 | 见「回调通知联调」第 5 步；本地环境可用订单「同步」主动拉取状态 |
| 回调收到了但业务没生效 | 未做幂等去重导致重复处理被业务侧拒绝，或验签失败被业务代码吞掉，先查接收端日志 |
| 报文解析错误 | 基础地址配错（多拼了路径前缀或指向了前端地址）；对照接口文档的环境配置 |
## 相关链接
- [接口文档](https://doc.plus.daxpay.cn/api/overview.md)：协议与字段参考
- [签名机制](https://doc.plus.daxpay.cn/api/signature.md)：签名算法与密钥体系
- [异步回调](https://doc.plus.daxpay.cn/api/notice/callback.md)：回调报文格式与重推规则
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)：前置的主线流程
- [完整上线指南 - 商户开通与对接就绪](https://doc.plus.daxpay.cn/operation-guide/production/merchant-onboarding.md)：生产环境密钥发放与就绪检查
---
# 从部署到第一笔支付
**源**: https://doc.plus.daxpay.cn/operation-guide/setup/overview.md
# 从部署到第一笔支付
> 本文介绍系统部署成功后，如何通过一系列必要配置，最终**跑通第一笔支付**。
>
> - 支付能力开通提供两条路径：**服务商进件**（主线，提交进件申请，审核通过自动生成通道商户）与**直连自助配置**（辅助线，商户已有直连商户号时手工登记密钥，可用支付宝沙箱联调）
> - 只讲解必要流程，可选项会单独标注
> - 通用功能（订单、退款、分账等日常操作）见[业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)各章节
> - 正式生产上线的全量配置（域名规划、HTTPS、风控收紧、网关收款等）见[完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)
**前置条件**：
- 系统已完成部署并通过健康检查（`{"status":"UP"}`），初始化 SQL 已导入
- 可使用开发环境超级管理员账号登录运营端（种子数据默认账号 `bootx` / `121212`）
- 主线进件：已确定目标通道与归属服务商；辅助线沙箱验证：已注册[支付宝开放平台](https://open.alipay.com)账号（沙箱无需企业认证）
**全程约需 30~60 分钟**（进件线因机构审核可能更长），各步耗时见下表。
## 上线流程总览
整个上线过程分为两个阶段：**运营端配置**让系统具备收款条件，**商户端配置**完成对接签名并验证支付。
```mermaid
graph LR
A[账号安全] --> B[端点配置]
B --> C[环境确认]
C --> D[创建商户]
D --> E[开通支付能力]
E --> F[对接签名配置]
F --> G[第一笔支付]
G --> H[回调与签名联调]
```
| 步骤 | 操作端 | 菜单入口 | 耗时 |
| --- | --- | --- | --- |
| 1. 账号安全 | 运营端 | 系统管理 → 权限管理 → 用户管理 | 5 分钟 |
| 2. 端点配置 | 运营端 | 系统管理 → 系统配置 → 平台配置 → 端点配置 | 5 分钟 |
| 3. 环境确认 | 运营端 | 配置项 + 支付管理 → 支付主数据 | 2 分钟 |
| 4. 创建商户 | 运营端 | 商户管理 → 商户列表 | 5 分钟 |
| 5. 开通支付能力 | 运营端 | 商户管理 → 进件申请 / 商户工作台 → 通道商户 | 15~30 分钟（进件审核另计） |
| 6. 对接签名配置 | 商户端 | 商户中心 → 业务配置 → 对接配置 | 5 分钟 |
| 7. 第一笔支付 | 商户端 | 开发调试 → 支付调试(普通) | 5 分钟 |
| 8. 回调与签名联调（可选） | 商户端 | 开发调试 → 签名调试 | 10 分钟 |
逐项勾选清单见[上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)。
## 第一步：首次登录与账号安全
使用部署时初始化的超级管理员账号登录运营端（默认账号 `bootx` / `121212`，由种子数据写入）。**登录后第一件事：立即修改默认密码**（右上角头像进入个人中心，或让管理员在用户管理中重置）。
超级管理员入口由配置项 `daxpay.platform.starter.auth.enable-admin` 控制，dev 默认开启，prod 强制关闭；生产环境该配置未关闭会被部署模式校验直接拒绝启动。详见[系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)。
**建议立即完成**：在「系统管理 → 权限管理 → 用户管理」创建正式的运营管理员账号，分配角色与菜单权限后，日常使用该账号操作。用户管理的详细操作见[用户管理](https://doc.plus.daxpay.cn/operation-guide/admin/user-management.md)。
## 第二步：配置平台端点
**菜单路径**：运营端 → 系统管理 → 系统配置 → 平台配置 → **端点配置**
端点配置告诉系统各端的对外访问地址，进入编辑态填写后保存：
| 配置项 | 用途 |
| --- | --- |
| 运营端访问地址 | 运营端基础访问地址，三方登录等场景生成回调 URL |
| 代理商端访问地址 | 代理商端基础访问地址，三方登录回调用 |
| 商户端访问地址 | 商户端基础访问地址，须与商户端实际访问源一致 |
| **支付网关前端地址** | 收银台 / 网关页面的访问地址，**支付页面跳转依赖此项** |
| **后端 API 地址** | 后端服务基础 API 地址，**支付回调通知等后端发起的场景依赖此项** |
示例格式：`https://admin.example.com`、`https://pay.example.com`、`https://api.example.com`。
本地没有公网地址时，先填写**格式合法的占位域名**（如 `https://pay.example.com`）保证接口调用不报错；需要真实接收回调时，按[本地联调](https://doc.plus.daxpay.cn/deployment/debug.md)配置域名直连或穿透后替换为真实地址。
同级的其他页签均为可选，按需配置：站点配置（系统名称、Logo、备案与版权）、OSS 配置（对象存储，详见[存储配置](https://doc.plus.daxpay.cn/operation-guide/admin/storage-config.md)）、邮件配置、短信配置、OCR 配置（进件资料识别用）、实名核验配置、敏感词配置。各配置域的说明见[支付平台配置](https://doc.plus.daxpay.cn/operation-guide/admin/payment-config.md)。
## 第三步：确认环境（沙箱 / 生产）
plus 的支付环境由两层机制组成：
| 层级 | 控制方式 | 说明 |
| --- | --- | --- |
| 平台沙箱总闸 | 配置项 `daxpay.platform.config.sandbox-enabled` | dev 默认开启；生产环境强制关闭，且属于生产 fail-fast 校验项 |
| 通道商户环境 | 创建通道商户时选择 | 产品声明「支持沙箱」且总闸开启时可选生产 / 沙箱；**创建时固化，此后不可修改** |
因此辅助线（支付宝直连沙箱联调）的正确顺序是：**确认平台沙箱总闸开启 → 第五步创建通道商户时选择「沙箱」环境 → 在密钥配置中维护沙箱密钥**。沙箱与生产的通道商户互不通用，切换生产需重建并配置生产密钥。
**主线（服务商进件）说明**：进件走服务商在渠道机构的真实开通链路，**没有沙箱环境**，申请通过即生产可用，验证使用小额真实支付。
「支付管理 → 支付主数据」下的支付产品、支付通道、支付方式、支付能力是系统内置主数据，**只读不可新建**；哪些产品支持沙箱在主数据的产品页查看，产品的启停与开通配置在「支付管理 → 通道与产品配置」进行，详见[支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)。
## 第四步：创建商户
**菜单路径**：运营端 → 商户管理 → 商户列表 → **新增**
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 商户名称 | 是 | 商户全称 |
| 商户简称 | 是 | 列表与页面中展示的简称 |
| 主体类型 | 是 | 小微商户 / 个体工商户 / 企业 |
| 所属代理商 | 否 | 选择后商户挂靠该代理商，留空为平台直营 |
| 账号 | 是 | 该商户管理员的登录账号（用于商户端登录） |
| 名称 | 是 | 管理员显示名称 |
| 密码 / 确认密码 | 否 | **留空时系统自动生成随机初始密码**；如填写则需输入两次且一致 |
点击「保存」后，系统自动完成四件事，**无需手动操作**：
1. 生成全局唯一的商户号（`M` 开头）；
2. 创建该商户的**管理员账号**，绑定商户超管角色（可登录商户端）；
3. 创建**默认应用**（`A` 开头的 appId，发起支付时不指定 appId 则默认使用它）；
4. 创建**默认门店**。
初始密码**仅在创建结果页展示一次**，关闭抽屉后无法再次查看，只能通过重置密码处理。请立即复制并转告商户管理员，提醒其首次登录商户端后修改密码。
除手工创建外，也可走**邀请注册**：运营端生成平台直营邀请码（或代理商生成推广邀请码），商户用手机号验证码注册，系统自动建立管理员、默认应用与门店（注册开关默认关闭，需在安全配置中开启）。详见[邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)。
## 第五步：开通支付能力（主线进件 / 辅助线直连）
plus 开通支付能力有两条线路：
| 线路 | 适用产品 | 开通方式 |
| --- | --- | --- |
| **服务商进件（主线）** | 微信（服务商）、支付宝（服务商）、拉卡拉、乐刷、汇付 Adapay / 斗拱等聚合通道 | 提交进件申请（商户资料 + 费率申报），审核通过后**自动生成通道商户** |
| 直连自助配置（辅助线） | 支付宝（直连）、微信支付（直连）等直连产品 | 运营端手工创建通道商户并配置密钥，商户须已有通道侧商户号 |
### 主线：服务商进件开通
**① 配置支付产品与服务商参数**（每通道一次性）
进入「支付管理 → 通道与产品配置」：
- **支付和进件产品**：确认目标产品已启用，点击产品卡片进入配置详情；
- **通道服务商配置**：在**服务商工作台**维护该通道的服务商参数（如微信服务商进件参数、支付宝服务商应用信息），并核对**服务商费率**——服务商行同时决定商户费率与平台留存，详见[支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)。
**② 创建进件申请**
**菜单路径**：商户管理 → 进件申请 → **新建进件申请**
向导分四步：选择商户 → 选择进件产品（按「服务商进件 / 特殊进件产品」分组，仅列出当前可进件的通道）→ 填写申请信息 → 分产品资料填报。申请信息关键字段：
| 字段 | 说明 |
| --- | --- |
| 申请名称 | 自定义名称，便于在列表中辨识 |
| 进件类型 | 商户进件 / 企业进件 / 小微进件 |
| **归属服务商** | **创建后锁定不可变更**；换服务商 = 作废重开 |
| 开通产品 | 草稿阶段可增删，提交进件后锁定，同一申请单一并开通 |
| 复用商户资料 | 勾选后自动从进件资料主档复制快照；主档（主体 / 法人 / 执照 / 门店）在商户工作台「进件资料」维护，支持营业执照、身份证 OCR 识别 |
资料填报完成后**提交申请**，费率随申请一并申报（受平台费率下限约束，申报费率低于下限会被拦截）。
**③ 审核与自动生成通道商户**
申请单状态机：**草稿 → 预审 → 申请中 → 通过 → 已生成商户**（流转中可能出现驳回、预审拒绝、数据补填等分支，补正后在进件申请工作台重新提交）。
- 审核与推进操作在**进件申请工作台**完成：提交申请、审核、同步状态、作废；
- 状态到达「通过」后系统**自动生成通道商户**并完成绑定，工作台出现「前往通道商户」入口；
- 通过后还需确认该商户的费率配置（工作台提供费率配置跳转）。
进件全流程详解见[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)，各通道进件差异见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
草稿 / 驳回 / 预审拒绝状态的申请单可生成 **H5 填报链接**，商户手机扫码免登录填写进件资料，避免来回传递文件。
### 辅助线：直连通道自助配置
以支付宝（直连）为例：进入商户工作台 → 支付配置分组 → **通道商户** → **创建通道商户**，两步向导（选产品 → 填通道信息），支持沙箱的产品在此步选择运行环境。通道参数与密钥配置的完整说明见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)。
## 第六步：商户对接配置（互换签名公钥）
业务系统调用 unipay 开放接口使用 **RSA 签名**，签名是**商户级**的（同一商户的所有应用共用）：
- 商户**请求**：用商户私钥签名 → 平台用「商户公钥」验签；
- 平台**响应**与**回调**：用平台私钥签名 → 商户用「平台公钥」验签。
因此需要互换一次公钥。
**菜单路径**：商户端 → 商户中心 → 业务配置 → **对接配置**
| 区块 | 操作 | 用途 |
| --- | --- | --- |
| 平台公钥 | 只读，点「复制」带回业务系统 | 业务系统用它验证平台响应与回调的签名 |
| 商户公钥 | 点击「生成密钥对」自动填入，或粘贴已有公钥 | 平台用它验证商户请求的签名 |
| 通信密钥 | 可选，点击「生成密钥」 | 接口调用时数据加密（AES） |
操作要点：点击「生成密钥对」→ 弹窗展示生成的**私钥**（**仅展示一次，丢失无法找回**）→ 立即复制私钥并妥善保存 → 关闭弹窗后「保存」。
运营端也可以代管此配置：商户工作台 → 接入配置分组 → 对接配置。详细说明见[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md)。
## 第七步：发起第一笔支付
系统内置的开发调试页面可以模拟真实的 unipay 调用，无需编写代码即可验证整条支付链路。
**菜单路径**：商户端 → 开发调试 → **支付调试(普通)**（模拟商户 API，提交后真实调用 `/unipay/pay` 接口）
操作步骤：
1. **设置商户私钥**：点击「设置私钥」，粘贴第六步保存的商户私钥（仅存于浏览器本地缓存，用于生成请求签名）；
2. **选择支付模式**：**跟随通道路由**（推荐，选「商户 + 应用 + 支付方式」由路由解析）或**直接指定**（手动选「通道商户 + 支付能力」，排错时用）；
3. **填写订单信息**：订单号（可自动生成）、支付金额（**单位：分**，最低 1）、支付标题，支付方式选择如 `支付宝扫码`（`alipay_qr`）；
4. **提交支付**：页面自动完成组参与签名并调用统一支付接口；
5. **查看结果**：扫码类支付显示**支付二维码**与支付链接，可复制完整响应报文；
6. **完成付款**：进件线商户用真实支付宝做**小额支付**（如 0.01 元）；支付宝直连沙箱线在**沙箱版支付宝 App** 中登录沙箱买家账号扫码支付。
支付成功后核对订单：商户端「交易订单 → 支付订单 → 普通订单」或「支付交易」页可看到订单，业务状态变为「成功」。如果本地环境无法接收通道回调，订单会停留在待支付，在订单列表对该单执行「**同步**」操作即可拉取最新状态。
如需验证**统一收银台**或**聚合扫码**（码牌、一码多付）链路，先在应用工作台完成「网关支付配置」，再使用「开发调试 → 支付调试(网关)」：选择网关支付类型，提交预下单后返回**网关落地页 URL**（可扫码或打开）。详见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)。
## 第八步（可选）：回调验证与签名联调
支付跑通后，建议再验证回调与签名，之后即可正式对接业务系统：
- **异步回调**：在支付调试的「异步通知地址」字段填写你的接收地址并发起支付，验证报文接收与验签；平台侧可在「交易管理 → 回调通知 → 商户回调推送」查看每次通知的发送记录并重推；
- **签名排查**：验签失败时使用「开发调试 → 签名调试」复现**待签名字符串**与签名值，常见失败原因是时间字段未按东八区 `yyyy-MM-dd HH:mm:ss` 格式传输；
- **正式对接**：凭证保管、回调联调与排错工具见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)。
## 切换生产环境
1. 辅助线（直连沙箱）验证通过后：重建**生产**环境的通道商户（环境创建时固化，沙箱商户不可复用），配置从支付宝开放平台正式应用获取的生产密钥；
2. 主线（进件）本身即为生产开通，无需切换动作；
3. 生产部署确认两项：**`SPRING_PROFILES_ACTIVE=prod` 必须显式设置**（最高频事故是忘切 profile）；部署模式 `daxpay.platform.deployment.mode` 未显式配置时按 profile 推断为 PROD，PROD 模式启动会 fail-fast 校验生产配置（沙箱总闸关闭、超管入口关闭、api-docs 关闭、CORS 关闭、actuator 收紧等 9 项），不满足直接拒绝启动；
4. 上线前用**小额真实支付**做一次端到端验证（含真实回调），逐项核对[上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)。
## 常见问题
| 现象 | 原因与处理 |
| --- | --- |
| 发起支付报「通道商户环境不匹配」 | 通道商户创建时固化的环境与产品当前环境不一致。按正确环境重建通道商户 |
| 进件提交时提示费率低于下限 | 平台费率下限保护（申报费率不得低于平台下限），调整申报费率或由平台侧调整下限配置 |
| 进件长时间停在「申请中」 | 渠道机构侧未返回结果，在进件申请工作台执行「同步状态」拉取最新进度 |
| 验签失败 / 签名不正确 | 商户公钥未保存或私钥不配对；用「签名调试」页核对；确认时间字段为东八区格式 |
| 支付宝接口报密钥错误 | 「支付宝公钥」误填成自己生成的「应用公钥」，或公钥 / 证书模式与开放平台侧设置不一致 |
| 二维码出来了但订单一直待支付 | 本地收不到通道回调。用订单「同步」拉取状态；生产环境检查「后端 API 地址」公网可达 |
| 初始密码丢了 | 无法找回，重置该商户管理员密码（运营端用户管理或商户端找回密码通道） |
## 相关链接
- [上线检查清单](https://doc.plus.daxpay.cn/operation-guide/setup/checklist.md)：逐项核对上线完成度
- [支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)：进件与直连两种模式的通道配置详解
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)：凭证、回调联调与排错工具
- [进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)：主线进件的完整流程
- [业务功能总览](https://doc.plus.daxpay.cn/common/overview.md)：订单、退款、分账等日常业务操作
- [完整上线指南](https://doc.plus.daxpay.cn/operation-guide/production/overview.md)：生产环境全量配置
---
# 收款精灵：收款、播报与账务
**源**: https://doc.plus.daxpay.cn/tools/elf/collect.md
# 收款、播报与账务
> 精灵旁挂在收银软件旁边：框选一次金额位置后持续读取，顾客亮付款码即完成被扫收款；收款成功本机播报、自动打印小票，订单同步到平台。
金额框选的界面操作、扫码盒适配清单与账务核对细节仍在补充；当前以交付包内说明与技术支持为准。
## 屏幕金额识别
1. 在收银软件界面上框选一次金额显示位置；
2. 精灵持续读取该区域，连续多帧一致才采信，避免把中间态当金额；
3. 识别不准或金额区域变化时，提示手动输入，不盲收。
金额是文字显示的才能识别；金额做成图片或走远程桌面时无法识别。
## 被扫收款
- 扫码盒接入后扫一张码完成绑定，之后顾客亮付款码即可收款，无需切换收银软件；
- 支持键盘仿真与 HID POS 扫码盒；
- 没有收银软件时，可手动输入金额或直接扫码收款，适合临时收银与备用机。
## 桌面形态
- 待收金额悬浮在屏幕角落，不遮挡收银软件；
- 热键唤出收银台，关窗后驻留托盘；
- 支持开机自启。
## 播报与小票
| 项 | 说明 |
| --- | --- |
| 到账播报 | 本机语音播报金额与渠道，音箱与音量可调；系统缺中文语音时用预录语音兜底 |
| 小票打印 | 网口 9100 / USB 免驱，58mm、80mm 热敏小票机 |
| 模板 | 在平台设置，各门店共用，换样式不用重装 |
## 账务口径
- 每笔订单同步平台，记录门店与终端；本地只保留一份**镜像账**，以平台订单为准；
- 支付处理中的订单不直接入账，先记「待确认」，由后台向平台核对；成功补播报、补打票，失败写明原因；
- **待确认与失败不计入营业额**；
- 同一笔重复提交只收一次（客户端单号幂等）；
- 退款与关单入口以当前交付版本界面为准，操作结果同样以平台订单为准。
---
# 收款精灵：工具概览
**源**: https://doc.plus.daxpay.cn/tools/elf.md
# 收款精灵：工具概览
> 收款精灵是运行在 Windows 收银电脑上的桌面应用（WPF / .NET 10）：常驻收银软件旁边，读取屏幕上显示的金额，顾客亮付款码即完成被扫收款；收款成功本机播报、自动打印小票，订单同步到 DaxPay 平台。不改造收银软件、不装驱动。
>
> 当前版本 v0.2.0，支持 Windows 10 1607 及以上（64 位）。
本页为工具概览；安装与登录、金额识别框选、扫码盒与小票打印、门店与终端、退款与关单、排障等完整章节仍在编写。当前请以交付包内说明与技术支持为准。
## 适用场景
| 场景 | 说明 |
| --- | --- |
| 已有收银软件 | 老收银软件稳定好用但缺扫码收款，旁挂精灵补齐，不动原系统 |
| 台卡收款靠盯 | 顾客扫码后盯手机等到账，高峰分不清哪单是谁付的 |
| 到账、小票、对账三头忙 | 到账播报、小票打印、订单核对由精灵统一完成 |
## 收款链路
1. **登录即用** — 平台开好收银员账号、分好门店，电脑上登录即可收款；精灵不保存商户私钥；
2. **认金额、扫付款码** — 在屏幕上框选一次金额位置，之后自动读取；顾客亮付款码即收；没有收银软件时可手输金额或直接扫码；
3. **播报打印、同步平台** — 收款成功本机播报并打印小票，订单同步到平台。
## 核心能力
| 能力 | 说明 |
| --- | --- |
| 屏幕金额识别 | 框选一次金额位置后持续读取，连续多帧一致才采信；识别不准时提示手输 |
| 被扫收款 | 扫码盒（键盘仿真 / HID POS）扫顾客付款码完成收款 |
| 无收银软件也能收 | 手动输金额或直接扫码，适合临时收银与备用机 |
| 多门店 | 登录商户账号后自动带出门店，收款、流水、小票跟随当前门店 |
| 到账播报 | 本机语音播报金额与渠道，音箱与音量可调，支持预录语音兜底 |
| 小票打印 | 网口 9100 / USB 免驱，58mm 与 80mm；模板在平台设置、各门店共用 |
| 订单进平台 | 每笔订单同步平台，记录门店与终端；本地只保留镜像账，以平台订单为准 |
| 常驻桌面 | 待收金额悬浮在屏幕角落，热键唤出收银台，关窗驻留托盘，开机自启 |
## 运行环境
| 项 | 要求 |
| --- | --- |
| 操作系统 | Windows 10 1607+（64 位） |
| 技术形态 | .NET 10 / WPF 原生自绘，旁挂部署，不改造收银软件 |
| 扫码设备 | 键盘仿真 / HID POS 扫码盒 |
| 小票打印 | 网口 9100 / USB 免驱，58mm、80mm 热敏小票机 |
## 账号与安全
- 使用平台分配的**收银员账号**登录，权限由平台角色控制（查单、收款、退款等按角色授予）；
- 精灵不持有商户 RSA 私钥；「记住密码」由 Windows 加密保存；
- 同一笔重复提交只收一次（客户端单号幂等）；
- 支付处理中的订单不会直接入账，先记「待确认」，由后台向平台核对，成功补播报补打票，失败写明原因；待确认与失败不计入营业额。
## 获取与版本
收款精灵商业版 **App 扩展版起**随源码交付（含成品安装包），不单独销售；具体交付范围以商业版合同为准。
## 继续阅读
- [安装与登录](https://doc.plus.daxpay.cn/tools/login.md)：运行环境、安装升级、收银员账号与门店
- [收款、播报与账务](https://doc.plus.daxpay.cn/tools/collect.md)：金额识别、扫码盒被扫、播报打印与账务口径
---
# 收款精灵：安装与登录
**源**: https://doc.plus.daxpay.cn/tools/elf/login.md
# 安装与登录
> 精灵通过平台分配的收银员账号登录，登录后自动带出该账号可用的门店；「记住密码」由 Windows 加密保存，精灵不持有商户私钥。
安装包获取、更新校验与首次登录的界面步骤仍在补充；当前以交付包内安装说明与技术支持为准。
## 运行环境
| 项 | 要求 |
| --- | --- |
| 操作系统 | Windows 10 1607+（64 位） |
| 技术形态 | .NET 10 / WPF 原生自绘，旁挂部署，不改造收银软件 |
| 扫码设备 | 键盘仿真 / HID POS 扫码盒 |
| 小票打印 | 网口 9100 / USB 免驱，58mm、80mm 热敏小票机 |
## 安装与升级
- 交付包提供成品安装包与完整源码，安装包随源码交付，不单独提供下载；
- 支持一键打包；「检查更新」手动触发，下载后校验 SHA-256 再安装；
- 本地数据（配置、日志、镜像账）保存在用户数据目录，升级不覆盖业务数据。
## 账号与门店
- 在平台创建收银员账号并分配角色，权限按角色控制（查单、收款、退款等）；
- 首次登录按平台规则修改密码，并选择默认门店；
- 登录后自动带出账号名下门店，之后可在设置页随时切换；收款、流水、小票跟随当前门店，不串账。
## 登录与安全
- 精灵不保存商户 RSA 私钥；「记住密码」由 Windows 加密保存，令牌仅内存持有；
- 登录失效（令牌过期 / 被踢）时统一回到登录页，重新登录即可；
- 同一笔重复提交只收一次（客户端单号幂等）。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 忘记密码 | 在平台重置后重新登录 |
| 登录后被退回登录页 | 令牌失效或被踢，重新登录；长期出现请联系管理员检查账号状态 |
| 门店列表为空 | 确认账号已分配门店与收银员角色 |
---
# 配套工具总览
**源**: https://doc.plus.daxpay.cn/tools.md
# 配套工具总览
> 配套工具是**独立部署、独立版本节奏**的辅助程序，不是支付平台的业务模块：运维面板负责部署与运维，模拟联调通道负责在没有真实通道时跑通链路，压测验收工具负责容量验收，收款播报 APP 与收款精灵负责柜台侧的播报与打印。
>
> 本栏目只讲"怎么装、怎么配、怎么用"；工具随哪个版本交付、如何授权，以官网价格页与商务确认为准。
>
> 本页是配套工具的索引页（位于「快速开始 → 参考资料」），只承担选型、文档状态与使用边界；各工具完整文档见顶部「配套工具」下拉对应入口。
## 工具矩阵
| 工具 | 解决什么问题 | 主要使用者 | 交付方式 | 文档状态 |
| --- | --- | --- | --- | --- |
| [运维面板](https://doc.plus.daxpay.cn/tools/panel/overview.md) | 服务器上的可视化部署、升级、日常运维与排障 | 实施、运维 | 一键部署自带 | 可用 |
| [模拟联调通道](https://doc.plus.daxpay.cn/tools/mock/.md) | 不接真实通道，跑通支付、退款、分账、预授权与回调全链路 | 开发、联调、售前 POC | 商业版基础版起随源码附带 | 可用 |
| [压测验收工具](https://doc.plus.daxpay.cn/tools/perf/.md) | 测接口吞吐边界与订单数据量拐点，产出可留档的验收报告 | 实施、架构、验收方 | 全渠道版起随源码附带 | 编写中 |
| [收款播报 APP](https://doc.plus.daxpay.cn/tools/voice/.md) | 用安卓手机替代云音箱与小票打印机，收款即播报、自动出票 | 商户、门店 | App 扩展版起 | 编写中 |
| [收款精灵](https://doc.plus.daxpay.cn/tools/elf/.md) | PC 旁挂监听收银软件金额，完成被扫收款、播报与打印 | 零售门店 | App 扩展版起（含源码） | 编写中 |
## 按任务选工具
| 我要做的事 | 先用哪个 | 说明 |
| --- | --- | --- |
| 在一台新服务器上把系统跑起来 | [运维面板](https://doc.plus.daxpay.cn/tools/panel/overview.md) | 从环境检查到网关接入的可视化流程；手动部署见[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md) |
| 真实通道还没下号，先把支付链路调通 | [模拟联调通道](https://doc.plus.daxpay.cn/tools/mock/.md) | 扮演三方通道，支付/退款/分账/预授权全链路可演练 |
| 造失败、超时、掉回调、对账差异 | [模拟联调通道](https://doc.plus.daxpay.cn/tools/mock/rules.md) | 确认页人工裁决、主体覆盖、全局旁路、对账造数 |
| 上线前确认能扛多少单 | [压测验收工具（文档编写中）](https://doc.plus.daxpay.cn/tools/perf/.md) | 先看工具概览与交付包内 README，完整正文编写中 |
| 柜台要听到到账、打出小票 | [收款播报 APP（文档编写中）](https://doc.plus.daxpay.cn/tools/voice/.md) | 手机方案，概览已给出链路与兼容清单；云音箱/云打印硬件见[设备管理](https://doc.plus.daxpay.cn/operation-guide/admin/iot-device.md) |
| 收银软件不改代码，旁挂完成被扫收款 | [收款精灵（文档编写中）](https://doc.plus.daxpay.cn/tools/elf/.md) | PC 旁挂方案，概览已给出能力与安全边界 |
## 文档状态说明
- **可用**：正文已完整覆盖安装/接入/使用/排障，可直接按页操作。
- **编写中**：产品已交付，完整正文尚未成稿；已提供工具概览页（定位、能力、前提与安全边界），细节以交付包内 README、管理台内文档与技术支持为准。
- **规划**：产品形态或交付范围尚未定稿，暂不提供文档。
完整正文未成稿的工具不建空页：概览页只写已有能力与边界，不承诺日期；状态变更时本页、顶部导航与左侧导航同批更新。
## 使用边界
模拟联调通道的管理台**无鉴权**，且提供"强制改单、补发回调"等危险操作；只能部署在开发机或可信内网，**不得暴露公网**。生产环境主应用不会装配模拟通道模块，误配路由会直接报"产品策略不存在"。
运维面板本身不参与业务流量，但拥有部署、改配置、看日志的高权限。上线前请保留随机安全入口、修改初始密码，按需开启 IP 白名单与两步验证，见[面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md)。
---
# 模拟联调通道：管理台导览
**源**: https://doc.plus.daxpay.cn/tools/mock/console.md
# 管理台导览
> 管理台地址 `http://127.0.0.1:10400`，侧栏按 **总览 / 交易管理 / 商户档案 / 模拟控制 / 系统** 五组排列，共 19 个视图；另有 6 个不套侧栏的独立页面，由支付参数或二维码直接打开。
>
> 管理台**无鉴权**，只应部署在开发机或可信内网。
## 分组地图
| 分组 | 视图 | 这一组解决什么 |
| --- | --- | --- |
| 总览 | 仪表盘 | 今天发生了什么：笔数、金额、成功率、状态分布、商户排行、实时事件流 |
| 交易管理 | 支付订单、退款订单、投诉中心、分账管理、转账订单、预授权 | 查单据、推终态、补回调、处理投诉 |
| 商户档案 | 主体档案、进件管理、接收方管理、终端台账、微信模拟 | 主应用调用后同步过来的主体与终端档案，以及微信 openid 数据源 |
| 模拟控制 | 联调配置、对账造数、支付参数模拟 | 主动配置"这笔交易应该成功还是失败"，以及造对账差异 |
| 系统 | 运行设置、联调材料、接口文档、关于 | 运行参数、密钥材料、开放网关契约、版本信息 |
## 交易管理
| 视图 | 用途 | 常用操作 |
| --- | --- | --- |
| 支付订单 | 全量支付台账，按渠道、方式、状态、商户筛选 | 行内推成功/失败/关单、补发回调、发起投诉、打开确认页 |
| 退款订单 | 退款台账，含微信默认"处理中"的单 | 人工确认成功/失败，触发退款回调 |
| 投诉中心 | 支付宝/微信投诉契约模拟 | 从支付订单发起投诉、查看时间线、买家留言、联动退款 |
| 分账管理 | 分账发起与完结台账 | 查看分账状态、接收方明细 |
| 转账订单 | 转账台账（网关层预留，主应用当前未接通） | 查看留痕 |
| 预授权 | 冻结、请款、解冻、撤销全生命周期 | 对冻结单做请款/解冻/撤销，或人工置失败 |
挂起族订单（扫码、H5、PC、APP、公众号、JSAPI、小程序）下单后不会立即定终态，终态由**收款确认页**人工裁决，或在「联调配置」里开启自动推进。订单列表的行内操作适合批量处置，单笔演示优先用确认页。
## 商户档案
| 视图 | 用途 |
| --- | --- |
| 主体档案 | 服务商与直连商户两级档案；可冻结主体（级联拒单）、配置该主体的支付/退款/分账覆盖动作 |
| 进件管理 | 进件受理与查询留痕，对应网关 `/v3/mock/onb/**` |
| 接收方管理 | 分账接收方绑定/解绑留痕 |
| 终端台账 | 终端报备、注销、查询留痕 |
| 微信模拟 | 微信应用与用户档案，JSAPI/小程序 openid 的发放与校验数据源 |
主体档案是"按商户造异常"的入口：给某个商户配置支付覆盖为失败后，该商户的支付都按覆盖结果走，不影响其他商户。判定优先级见[场景规则与运行开关](https://doc.plus.daxpay.cn/tools/mock/rules.md)。
## 模拟控制
| 视图 | 用途 | 关键点 |
| --- | --- | --- |
| 联调配置 | 分账金额尾号规则 + 运行开关 | 0.4 起支付/退款/预授权不再有规则表，页面只保留分账规则与全局开关 |
| 对账造数 | 制造长款、短款、状态不一致 | 三个差异开关默认全开，按金额尾号命中 |
| 支付参数模拟 | 粘贴渠道支付参数 → 校验 → 生成短码二维码 → 手机模拟结果 | 用于"拿到真实形态的支付参数后，反向进入模拟支付" |
## 系统
| 视图 | 用途 |
| --- | --- |
| 运行设置 | 对外访问地址、数据容量、自动回调、扫码推进、回调重试、微信 openid 校验、清空数据 |
| 联调材料 | 开放网关地址与全局密钥对的只读展示，可复制到主应用侧凭证配置 |
| 接口文档 | 21 个 `/v3/mock/**` 端点、三签名头、错误码与请求示例 |
| 关于 | 版本号与构建信息 |
## 六个独立布局页
这些页面不套管理台侧栏，通常由 `payBody`、二维码或材料页链接直接打开：
| 页面 | 地址 | 用途 |
| --- | --- | --- |
| 收款确认页 | `/#/pay/{tradeNo}` | 扫码/H5/PC/APP 下单后的落地页，人工点"确认支付成功/失败/继续挂起" |
| 模拟支付页 | `/#/sim/{code}` | 支付参数模拟生成的短码落地页，手机端点成功或失败 |
| 微信授权页 | `/#/wxauth?appId=&state=&redirect=` | 拟真公众号/JSAPI 授权，选模拟用户发 code 回跳 |
| 拟真微信支付页 | `/#/wxpay/{tradeNo}` | 微信 JSAPI 单的拟真收银界面 |
| 预授权确认页 | `/#/preauth/{authNo}` | 预授权冻结的落地确认页 |
| 手机付款码 | `/#/authcode?provider=&mode=` | 拟真微信/支付宝/云闪付付款码，供收银端被扫或手输 |
## 常用操作速查
| 我想… | 去哪里 |
| --- | --- |
| 让一笔挂起订单成功 | 支付订单 → 打开确认页 → 确认支付成功 |
| 让一笔订单失败 | 确认页点"支付失败"，或在主体档案配置支付覆盖 |
| 补发一次回调 | 支付/退款订单行内 → 补发回调；确认页可看每次送达的 HTTP 状态与应答 |
| 演练微信异步退款 | 退款订单 → 找到"处理中"的单 → 人工确认成功 |
| 造对账长款/短款 | 对账造数 → 打开差异开关 → 下单金额命中尾号 → 触发对账任务 |
| 手机扫码打开确认页 | 运行设置把对外访问地址改为局域网 IP，重新下单取新的 `payBody` |
| 清空模拟数据 | 运行设置 → 清空全部数据（规则与开关保留） |
## 界面产物说明
管理台的正式形态是后端 `static/` 里的已构建产物。改过 `ui/` 后必须重新构建并提交产物，否则你看到的是旧界面：
```bash
cd ui
pnpm install
pnpm build
```
只改前端时可用 `pnpm dev`（10500，`/mock` 前缀代理到 10400）做热更新调试。
---
# 模拟联调通道：常见问题与排障
**源**: https://doc.plus.daxpay.cn/tools/mock/faq.md
# 常见问题与排障
> 排障顺序建议固定为：**先看单据是否存在 → 再看确认页的回调送达记录 → 再看主应用回调日志 → 最后查网络与密钥**。多数"没生效"其实是路由没命中或版本口径不同。
## 回调没有到主应用
| 检查项 | 怎么看 | 处理 |
| --- | --- | --- |
| 回调地址是否配置 | 运营端「平台配置 → 访问地址」的后端地址 | 配成模拟通道进程可达的地址 |
| 地址是否可达 | 在模拟通道所在机器 `curl` 主应用回调地址 | 不通则改网络、端口或 hosts |
| 是否发出 | 确认页的回调送达记录（HTTP 状态 + 应答体） | 没发出说明订单没有终态；发出了看对方应答 |
| 是否 2xx | 送达记录里的状态码 | 非 2xx 看主应用日志与安全策略 |
| 是否验签失败 | 主应用回调日志 | 用平台公钥验签；检查三签名头是否被网关改写 |
主应用配置的是公网回调域名、模拟通道在本机时，需要在模拟通道所在机器加 hosts 指回本机，否则回调会绕公网。
## 下单报"产品策略不存在"
两个原因，按顺序查：
1. **路由没纳入模拟通道**：运营端「通道路由」里，目标应用的对应渠道/支付方式没有绑定模拟通道商户；
2. **主应用以 PROD 模式启动**：模拟通道编排模块按部署模式条件装配，PROD 下不注册，任何模拟路由都不存在。
## 路由候选里没有模拟通道
不是通道商户没建，而是**能力挂载种子缺失**：保存路由时后端会校验该支付方式下是否有可用能力。检查：
- `pay_md_product` 是否有 `mock_pay` / `mock_isv` 产品行；
- `pay_md_product_capability` 是否有 21 项能力 × 2 产品的挂载行；
- 缺行时补 `data.sql` / `update-datas.sql` 对应种子。
## 确认页打不开 / 手机扫码 404
- 确认页地址由「运行设置 → 对外访问地址」拼接，默认 `127.0.0.1`，手机访问不到；
- 改成局域网 IP 或内网域名后，**重新下单**取新的 `payBody`，旧链接不会变；
- 跨网访问还要确认防火墙放行 10400。
## 规则不生效
先确认版本口径：
| 你的版本 | 支付/退款/预授权规则 | 造失败的正确方式 |
| --- | --- | --- |
| 0.4 起 | 已退役，只有分账规则 | 确认页人工裁决、主体覆盖、全局旁路 |
| 0.3.x 及更早 | 四类交易各有规则表 | 规则表按金额尾号命中 |
0.4 下如果"配了支付规则却没生效"，不是 bug——支付已经不看规则表。分账规则不生效时检查：金额尾号是否命中、规则是否被清空（清空会自动补种默认两条）、全局旁路是否覆盖了规则。
## 聚合支付推成功被拒（40404）
聚合单推成功必须带实际钱包。确认页选钱包按钮即成功；如果用接口直接推终态，`actual_provider` 不能为空。失败、挂起不要求钱包。
## 数据不见了 / 想清空重来
- 数据在 SQLite 单文件（默认 `data/mock-channel.db`），重启不清零；
- 容量上限默认订单/退款/分账各 5000、回调 2000，超出按创建时间淘汰最老；
- 清空用「运行设置 → 清空全部数据」，规则与开关保留；
- 换工作目录启动会连到另一个相对路径的库文件，表现为"数据全没了"，查 `mock.db-path`。
## 改了管理台界面不生效
正式形态走后端 `static/` 的构建产物。改完 `ui/` 必须重新构建并提交产物：
```bash
cd ui
pnpm build
```
只跑 `pnpm dev` 看到的是 10500 的热更新页面，不是 10400 的实际界面。
## 模拟通道能启动，但下单没反应
| 检查项 | 说明 |
| --- | --- |
| 子应用是否在跑 | 主应用不会拉起模拟通道，需单独保持运行 |
| 端口是否被占 | 默认 10400；改端口后主应用侧地址要同步 |
| transport key 是否一致 | 不一致时请求解密失败，主应用日志会有明确报错 |
| 是否连到错误实例 | 多实例联调时确认路由指向的通道商户属于哪个实例 |
## 生产环境要不要装
不要。模拟通道只用于开发联调与演示：
- 主应用生产模式不装配模拟通道模块；
- 管理台无鉴权、可强制改单，公网可达等于把支付结果裁决权交给任何访客；
- 生产部署清单中不应出现该子应用。
## 还是排查不出来
按这个顺序收集信息，再找技术支持：
1. 下单请求的商户号、应用号、支付方式、金额、时间；
2. 模拟通道「支付订单」里的单据状态与 `trade_no`；
3. 确认页的回调送达记录截图（HTTP 状态 + 应答体）；
4. 主应用回调日志与错误码；
5. 模拟通道版本（「关于」页）与主应用版本。
---
# 模拟联调通道：工具概览与边界
**源**: https://doc.plus.daxpay.cn/tools/mock.md
# 模拟联调通道：工具概览与边界
> 模拟联调通道是一个**独立部署的通道子应用**，扮演"三方支付平台"：主应用把模拟通道当作真实通道调用，它在内部完成下单、回调、退款、分账、预授权与对账，不需要任何真实通道凭据。
>
> 它解决的是"通道还没下号、异常场景复现不了、对账差异造不出来"这三类问题，**不承载真实资金**。管理台默认地址 `http://127.0.0.1:10400`。
本文按 **0.4 判定链**（2026-10 收敛后）编写：支付、退款、预授权不再有金额规则表，只有分账保留一张。若界面仍显示"支付/退款/预授权规则"页签，说明你的版本较早，以实际界面为准；升级后旧规则行会在启动时自动清理。
## 三类用途
| 用途 | 典型场景 | 你能得到什么 |
| --- | --- | --- |
| 开发联调 | 通道未下号、沙箱额度受限、回调地址未备案 | 支付→回调→订单翻转的完整链路，可反复重放 |
| 演示 POC | 给客户演示聚合支付、分账、预授权、对账 | 不依赖真实通道与真实资金的端到端演示 |
| 异常演练 | 支付失败、超时、异步退款、掉回调、对账长款/短款 | 可控、可复现的异常分支，不靠真实通道"碰运气" |
## 能力地图
| 域 | 覆盖内容 |
| --- | --- |
| 支付 | 下单、关单、同步查询；9 种支付方式（扫码/跳转/付款码/H5/PC/APP/公众号/JSAPI/小程序） |
| 退款 | 退款发起、退款同步；微信退款默认"处理中"，用于演练异步回调翻转 |
| 分账 | 发起、完结、同步、接收方绑定/解绑；唯一保留金额尾号规则表的交易类型 |
| 转账 | 转账订单台账（主应用当前未接通网关，属预留能力） |
| 预授权 | 冻结、请款、解冻、撤销、查询；支付宝预授权与微信支付分同源模拟 |
| 进件与终端 | 进件受理/查询、终端报备/注销/查询 |
| 微信生态 | 应用与用户档案、openid 发放、OAuth 授权页、拟真微信支付页 |
| 投诉 | 支付宝/微信投诉契约模拟，可从支付订单发起并联动退款 |
| 对账 | 对账单下载、长款/短款/状态不一致造数 |
| 开放网关 | `/v3/mock/**` 21 个端点，RSA 双向签名 + 防重放，附 6 个 C 端拟真页 |
## 与相邻能力的区别
| 能力 | 运行位置 | 用什么配置 | 适合做什么 | 不适合做什么 |
| --- | --- | --- | --- | --- |
| [开发者调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md) | 运营端页面内 | 真实商户与应用配置 | 验证签名、路由、通道商户是否配对 | 造异常、造对账差异、压全链路 |
| **模拟联调通道** | 独立子应用（10400） | 独立的模拟通道商户与路由 | 全链路联调、异常演练、POC 演示 | 真实收款、生产流量 |
| 真实通道沙箱 | 三方平台 | 真实进件与密钥 | 上线前最终验证 | 异常场景可控复现、批量造数 |
## 五分钟最短路径
目标：在本机发起一笔模拟支付，看到订单变成"支付成功"，并收到回调。
1. **拉起子应用**：`cd basic/daxpay-plus-mock-channel && mvnd spring-boot:run`，浏览器打开 `http://127.0.0.1:10400`，能看到仪表盘即成功。
2. **建模拟通道商户**：运营端「通道商户」新增，产品选「模拟支付」，通道商户号任意（如 `MOCK001`），凭证全部留空。
3. **配路由**：运营端「通道路由」把该通道商户纳入候选（基础模式按渠道默认绑定，场景模式按支付方式选择）。
4. **配回调地址**：运营端「平台配置 → 访问地址」的后端地址必须是本机可达地址（如 `http://127.0.0.1:19999`）。
5. **对齐传输密钥**：主应用 `daxpay.channel.mock.transport-encrypt.key` 与本仓 `daxpay.channel.transport-encrypt.key` 保持一致，重启主应用。
6. **下单验证**：用开发者调试或业务系统发起一笔扫码支付，打开返回的确认页，点「确认支付成功」，回主应用看订单状态与回调记录。
每一步的细节与失败表现见[接入配置](https://doc.plus.daxpay.cn/tools/mock/setup.md)。
## 数据与生命周期
- 订单、规则、回调记录全部落在 **SQLite 单文件**（默认 `data/mock-channel.db`），重启不清零。
- 订单/退款/分账默认各保留 5000 条、回调记录 2000 条，超出按创建时间淘汰最老；容量可在「运行设置」调整，`0` 表示不限（压测场景）。
- 需要清空重来时用「运行设置 → 清空全部数据」，规则与运行开关不受影响。
## 安全边界
1. **只部署在开发机或可信内网**：管理台无鉴权，且能强制改单、补发回调，公网可达等于把支付结果裁决权交给任何访客。
2. **不进生产部署清单**：主应用侧模拟通道模块按部署模式条件装配，生产模式不注册；误配模拟路由会直接报"产品策略不存在"。
3. **不承载真实资金**：所有单据都是模拟数据，不要把它当作对账或资金依据。
## 下一步
| 你的目标 | 阅读 |
| --- | --- |
| 把模拟通道接进主应用 | [接入配置](https://doc.plus.daxpay.cn/tools/mock/setup.md) |
| 认识管理台 19 个视图 | [管理台导览](https://doc.plus.daxpay.cn/tools/mock/console.md) |
| 造失败、挂起、异步退款 | [场景规则与运行开关](https://doc.plus.daxpay.cn/tools/mock/rules.md) |
| 联调开放网关 | [联调材料与接口](https://doc.plus.daxpay.cn/tools/mock/materials.md) |
| 排障 | [常见问题与排障](https://doc.plus.daxpay.cn/tools/mock/faq.md) |
---
# 模拟联调通道：联调材料与接口
**源**: https://doc.plus.daxpay.cn/tools/mock/materials.md
# 联调材料与接口
> 模拟通道对外提供两套协议：主应用内部链路走 `/channel/**`（AES-GCM 密文），**开放网关**走 `/v3/mock/**`（RSA 双向签名 + 防重放）。做代码级联调、验证签名与回调解析时，用后者。
>
> 本文只讲怎么用；字段级契约以管理台「系统 → 接口文档」页为准，两者冲突时以该页与源码为准。
## 材料在哪
管理台「系统 → 联调材料」实时展示：
| 材料 | 用途 |
| --- | --- |
| 网关地址 | `/v3/mock/**` 的基地址，默认 `http://127.0.0.1:10400` |
| 商户私钥（PKCS#8 PEM） | 你签名请求用 |
| 商户公钥（SPKI PEM） | 模拟通道验你的请求签名 |
| 平台私钥（PKCS#8 PEM） | 模拟通道签响应与回调用（不要拿它签请求） |
| 平台公钥（SPKI PEM） | 你验响应与回调签名用 |
当前实例只使用**一套全局密钥对**，不再按服务商/商户分发。主应用侧每个服务商、每个直连商户仍各有一行接入配置，但同一实例下应粘贴同一套密钥；不同主体指向不同模拟实例时才各用各的。
## 三个签名头
请求、响应、回调统一使用三个头：
```http
Mock-Sign:
Mock-Timestamp: <秒级时间戳>
Mock-Nonce: <32 位随机 hex>
```
签名串是三行文本（`\n` 分隔）：
```text
{timestamp}
{nonce}
{body}
```
- `body` 为报文 JSON 原文；GET/DELETE 无 body 时签空串；
- 请求用**商户私钥**签，模拟通道用商户公钥验；
- 响应与回调用**平台私钥**签，你用平台公钥验；
- 时间戳与服务器时间差超过 **300 秒** → `401 SIGNATURE_EXPIRED`；
- 同一 nonce 在 **5 分钟内**重复 → `401 NONCE_REPLAYED`。
## 报文约定
| 项 | 约定 |
| --- | --- |
| 命名 | JSON + snake_case |
| 金额 | 整数，单位分，字段名 `amount` |
| 时间 | RFC3339 带偏移，如 `2026-10-26T23:38:00+08:00` |
| 状态 | 大写枚举串，如 `SUCCESS` / `FAIL` / `CLOSED` / `PENDING` |
| 主体编号 | 主体配置了独立凭证时携带 `key_owner_no`：POST 放报文顶层并参与签名，GET/DELETE 放查询串且不进签名 |
## 端点总表
21 个出站端点，全部挂在 `/v3/mock` 下：
| # | 操作 | 方法与路径 |
| --- | --- | --- |
| 1 | 支付下单 | `POST /pay` |
| 2 | 支付查询 | `GET /pay/{outTradeNo}?mchid=` |
| 3 | 关单 | `POST /pay/{outTradeNo}/close` |
| 4 | 退款发起 | `POST /refund` |
| 5 | 退款查询 | `GET /refund/{outRefundNo}?mchid=` |
| 6 | 分账发起 | `POST /alloc` |
| 7 | 分账完结 | `POST /alloc/finish` |
| 8 | 分账查询 | `GET /alloc/{allocNo}?mchid=` |
| 9 | 接收方绑定 | `POST /alloc/receivers` |
| 10 | 接收方解绑 | `POST /alloc/receivers/unbind` |
| 11 | 对账单下载 | `GET /bill?bill_date=&mchid=` |
| 12 | 进件受理 | `POST /onb/apply` |
| 13 | 进件查询 | `GET /onb/{outApplyNo}` |
| 14 | 终端报备 | `POST /terminal` |
| 15 | 终端注销 | `DELETE /terminal/{terminalNo}?mchid=` |
| 16 | 终端查询 | `GET /terminal/{terminalNo}?mchid=` |
| 17 | 预授权冻结 | `POST /preauth/freeze` |
| 18 | 预授权请款 | `POST /preauth/{authNo}/capture` |
| 19 | 预授权解冻 | `POST /preauth/{authNo}/unfreeze` |
| 20 | 预授权撤销 | `POST /preauth/{authNo}/cancel` |
| 21 | 预授权查询 | `GET /preauth/{authNo}?mchid=` |
另有 3 个回调解析端点在通道子应用内部（`parse-pay` / `parse-refund` / `parse-preauth`），不出现在网关层。
## 错误规范
失败响应统一为 4xx + JSON，并带响应签名头：
```json
{ "code": "BIZ_REJECTED", "message": "商户不存在, 请先在模拟通道控制台建档", "internal_code": 10013 }
```
| HTTP | code | 场景 |
| --- | --- | --- |
| 401 | `SIGN_ERROR` | 缺签名头或签名验证失败 |
| 401 | `SIGNATURE_EXPIRED` | 时间戳超窗 |
| 401 | `NONCE_REPLAYED` | nonce 重放 |
| 400 | `PARAM_ERROR` | 参数校验失败 |
| 400 | `BIZ_REJECTED` | 业务拒单，`internal_code` 透传模拟通道内部码 |
| 404 | `RESOURCE_NOT_EXISTS` | 查询单据不存在 |
| 500 | `SYSTEM_ERROR` | 内部异常 |
## 回调报文
回调是**明文单层 JSON**，带同一套三签名头，平台私钥签名：
```json
{
"event_type": "PAY.SUCCESS",
"summary": "支付成功",
"out_biz_no": "P20261026xxx",
"data": {
"mock_trade_type": "PAY",
"out_trade_no": "P20261026xxx",
"trade_no": "MOCKTRADE...",
"status": "SUCCESS",
"amount": 100,
"finish_time": "2026-10-26T23:38:00+08:00"
}
}
```
| 字段 | 说明 |
| --- | --- |
| `event_type` | `{类型}.{状态}`：`PAY.SUCCESS` / `PAY.FAIL` / `PAY.CLOSED`、`REFUND.*`、`PREAUTH.SUCCESS` / `PREAUTH.CLOSED` |
| `out_biz_no` | 业务单号锚点：支付=商户订单号，退款=商户退款号，预授权=预授权单号 |
| `data` | 明文业务对象，snake_case，时间 RFC3339 |
送达判定只看 HTTP 2xx，不检查应答体文本。验签时用**平台公钥**，不是商户公钥——你验的是"通知确实来自平台"。
## 用代码跑通一次
1. 从「联调材料」复制商户私钥、平台公钥与网关地址；
2. 按 `{timestamp}\n{nonce}\n{body}` 拼串，RSA-SHA256 签名，放入三个头；
3. 调 `POST /v3/mock/pay` 下一笔扫码单，拿到 `pay_body`；
4. 浏览器打开 `pay_body` 完成支付，接收回调；
5. 用平台公钥验回调三签名头，解析 `data`。
请求体字段、响应字段全集与示例见管理台「接口文档」；需要签名参考实现时，以该页的示例与交付包内示例代码为准。
---
# 模拟联调通道：支付方式与模拟支付
**源**: https://doc.plus.daxpay.cn/tools/mock/pay-methods.md
# 支付方式与模拟支付
> 模拟通道按"渠道 × 方式"两个维度拟真：渠道决定付款方是谁，方式决定怎么拉起、返回什么、什么时候定终态。理解这两层，才能判断一笔下单为什么返回 URL、JSON 还是没有 `payBody`。
## 渠道（provider）
| 渠道 | 枚举名 | 说明 |
| --- | --- | --- |
| 微信支付 | `WECHAT` | JSAPI/小程序返回 prepay JSON，付款码即时判定 |
| 支付宝 | `ALIPAY` | JSAPI 返回交易号形态（`PARAMS`），其余同微信 |
| 银联支付 | `UNION` | 主应用侧 `UNION_PAY` 映射为 `UNION` |
| 抖音支付 | `DOUYIN` | 付款码无公开格式，跳过格式校验 |
| 聚合支付 | `AGGREGATE` | 一码多付：下单记聚合渠道，付款时再选实际钱包 |
## 九种支付方式（way）
| 方式 | 枚举名 | 终态时机 | `payBody` 形态 |
| --- | --- | --- | --- |
| 扫码 | `QR` | 挂起，等确认页 | URL（确认页地址） |
| 扫码跳转 | `SCAN` | 挂起 | URL |
| H5 | `H5` | 挂起 | URL（手机浏览器打开） |
| 电脑网站 | `PC` | 挂起 | URL |
| APP | `APP` | 挂起 | URL（确认页替代 APP 内收银界面） |
| 公众号 | `MP` | 挂起 | JSON（拟真 prepay 结构） |
| JSAPI | `JSAPI` | 挂起 | 微信为 JSON；支付宝为 `PARAMS`（交易号形态） |
| 小程序 | `MINI_APP` | 挂起 | JSON（拟真 prepay 结构） |
| 付款码 | `BARCODE` | **即时** | 无 `payBody` |
兼容规则：老调用的 `method=qr` / `method=bar` 分别映射为 `QR` / `BARCODE`；`method` 与 `way` 同时传时 `way` 优先；都不传默认 `QR`。
## 挂起族怎么完成支付
八种挂起族方式下单后只落单，`payBody` 指向确认页（`/#/pay/{tradeNo}`）。用浏览器或手机打开确认页，点「确认支付成功」完成终态，触发回调。确认页的详细行为见[交易与人工裁决](https://doc.plus.daxpay.cn/tools/mock/trade.md)。
确认页地址由"对外访问地址"拼接。默认是 `127.0.0.1`，手机访问不到；到「运行设置」改成局域网 IP 后重新下单。
## 聚合支付（一码多付）
- 下单 `provider=AGGREGATE`，按 `QR` 挂起，返回确认页地址，即"一码多付"的码；
- 确认页展示微信 / 支付宝 / 云闪付 / 抖音四个钱包按钮，点哪个就按哪个钱包成功；
- 订单记录实际钱包 `actual_provider`，通过同步响应 `provider` 字段与回调 `data.provider` 回传主应用；
- 推成功未带钱包按 `40404` 拒绝；失败、挂起不要求钱包。
## 付款码（被扫）
付款码是即时族：没有确认页，下单时按场景引擎直接定结果。模拟通道会做基础格式校验：
| 渠道 | 格式 |
| --- | --- |
| 微信 | 18 位，10~15 开头 |
| 支付宝 | 16~24 位，25~30 开头 |
| 银联 | 19 位，62 开头 |
| 抖音 | 无公开权威格式，跳过校验 |
格式不合法返回 `10022`。要造"识别不出渠道"，用非预置段开头的码值（如 77 开头）。
## 支付参数模拟
用途：拿到一笔真实形态的支付参数（微信 JSAPI / 小程序 prepay JSON、支付宝 JSAPI 交易号）后，**反向进入模拟支付**，验证 App 或小程序的支付回调处理。
1. 打开「模拟控制 → 支付参数模拟」；
2. 粘贴支付参数，点「解析并校验」——后端做字段级校验（appId、prepay_id、签名、时间窗）并识别场景与单号；
3. 点「生成模拟二维码」，得到短码与 `/#/sim/{code}` 链接；
4. 手机扫码打开模拟支付页，点「模拟支付成功」或「模拟支付失败」。
结果分两种：
| 情况 | 行为 |
| --- | --- |
| 参数里的单号命中模拟订单 | 手机端操作推进订单终态并触发回调；PC 页每 3 秒轮询回显手机已打开、操作结果与最近一次回调送达 |
| 未命中订单 | 只记录模拟结果，手机页提示"不会触发支付回调"，PC 页降级为"仅参数验证" |
## 手机付款码模拟器
打开 `/#/authcode`（联调材料页底部也有入口），可预置参数：`?provider=WECHAT&mode=CONFIRM`。
| 模式 | 结果 |
| --- | --- |
| 立即成功 | 码值被收银端识别后直接成功 |
| 模拟输密 | 停在等待态，模拟用户输密码过程 |
| 延时成功 | 延迟一段时间后成功，用于验证轮询/超时 |
| 立即失败 | 直接失败，用于验证失败分支 |
## 微信模拟
「商户档案 → 微信模拟」维护微信应用与用户档案，是 JSAPI/小程序 openid 校验的数据源：
- 应用档案提供 appId；
- 用户档案提供 openid，可在授权页选用户后发放；
- 拟真授权页 `/#/wxauth` 模拟公众号/JSAPI 授权并回跳；
- 拟真微信支付页 `/#/wxpay/{tradeNo}` 模拟微信内收银界面。
「运行设置 → 微信 openid 校验」关闭后，JSAPI/小程序的 appid/openid 校验整段跳过，仅用于调试对比，不建议长期关闭。
## 返回形态速查
| 你拿到的东西 | 说明 | 下一步 |
| --- | --- | --- |
| URL | 挂起族确认页 | 浏览器/手机打开，人工裁决 |
| prepay JSON | 微信 MP/JSAPI/小程序 | 交给前端 `wx.requestPayment` 或参数模拟 |
| 交易号字符串 | 支付宝 JSAPI | 交给支付宝 SDK 拉起，或参数模拟 |
| 无 `payBody` | 付款码即时判定 | 直接查订单状态 |
---
# 模拟联调通道：对账与造数
**源**: https://doc.plus.daxpay.cn/tools/mock/reconcile.md
# 对账与造数
> 对账差异不需要手工改库：模拟通道在生成对账单时按三条规则"做手术"，再配合造数单，就能稳定复现长款、短款与金额不符。规则在**下一次对账单下载**时生效。
## 页面在哪
「模拟控制 → 对账造数」，分三块：
| 区块 | 作用 |
| --- | --- |
| 对账造数 | 凭空生成指定日期的成功假单，供隔天对账演练 |
| 对账差异规则 | 三个开关，决定对账文件里制造哪种差异 |
| 对账文件预览 | 选日期预览将生成的对账行，差异行高亮 |
## 造数单
| 字段 | 说明 |
| --- | --- |
| 目标日期 | 假单的完成日期，建议选前一天，便于当天跑对账 |
| 笔数 | 1~1000 |
| 固定金额 | 单位分；留空则随机 100~10000（1~100 元） |
生成的单是**成功的假单**，带 `synthetic` 标记，会出现在支付订单列表里。它没有真实支付链路，只用于让对账文件里有"平台侧有、通道侧也有"的正常行，以及作为差异规则的命中样本。
## 三条差异规则
| 开关 | 效果 | 差异类型 |
| --- | --- | --- |
| 漏单（单号尾号 7 不出现在对账文件） | 平台有单、通道文件没有 | 平台单边（长款） |
| 金额不符（单号尾号 3 金额减 1 分） | 通道文件金额比平台少 1 分 | 金额差异 |
| 凭空追加 1 笔平台不存在的交易 | 通道文件多一行 | 通道单边（短款） |
三个开关默认全开、持久化保存，重启不丢失。规则按**订单号尾号**命中，不是金额尾号——下单时让业务订单号尾号落在 3 或 7，才能命中对应差异。
## 对账文件预览
选日期点「预览」，页面按将生成的文件内容展示每一行，差异行会高亮并标注差异说明。预览与真实下载走同一套生成逻辑，可以先用预览确认规则是否命中，再去主应用触发对账任务。
## 对账单下载契约
主应用或调试工具通过开放网关下载对账单：
```http
GET /v3/mock/bill?bill_date=2026-10-30&mchid=MOCK001
```
响应直接返回 Base64 编码的 CSV（一跳，不模拟微信的两跳下载）：
```json
{ "bill": "" }
```
CSV 契约：
| 项 | 约定 |
| --- | --- |
| 编码 | UTF-8 |
| 分隔符 | 逗号 |
| 换行 | `\n` |
| 首行 | 列头 |
| 列 | `tradeNo,outTradeNo,amount,status,finishTime,sub_mch_id` |
`sub_mch_id` 为 ISV 模式子商户号；直连单、造数单、凭空差异行恒为空串。
## 推荐演练顺序
1. 前一天用「造数单」生成 20 笔成功单，金额尾号覆盖 3 与 7；
2. 确认三个差异开关处于期望状态，保存；
3. 选前一天预览，确认差异行数量与标注；
4. 在主应用「对账管理」发起对账任务，选择同一日期；
5. 查看差错单：应出现平台单边、金额不符、通道单边三类；
6. 处置差错单，验证主应用的差错处理流程。
## 常见问题
| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 对账文件没有差异 | 单号尾号没命中 3/7；或规则开关被关 | 看造数单号尾号；检查开关并保存 |
| 预览有差异，主应用对账没差异 | 主应用选的日期与文件日期不一致；或下载的不是本实例 | 对齐 `bill_date` 与实例地址 |
| 造数单查不到 | 造数选的是未来日期，或订单列表筛选条件过滤掉了 | 改选当天/前一天，清筛选 |
| 差异规则改了不生效 | 规则只在下一次 `bill-download` 生效 | 重新触发对账任务 |
---
# 模拟联调通道：场景规则与运行开关
**源**: https://doc.plus.daxpay.cn/tools/mock/rules.md
# 场景规则与运行开关
> 0.4 起判定链收敛为四层，页面只剩两块可配内容：**分账金额尾号规则**与**运行开关**。支付、退款、预授权不再有规则表——它们的默认结果写死，要造其它结果靠人工裁决、主体覆盖或全局旁路。
## 判定优先级
对一笔交易，按以下顺序取第一个命中的结果（高 → 低）：
| 层级 | 来源 | 作用范围 | 说明 |
| --- | --- | --- | --- |
| 1 | 订单手动覆盖 | 单笔 | 确认页裁决、订单列表行内操作、手机虚拟码模式写入 |
| 2 | 商户级覆盖 | 该商户全部交易 | 主体档案里配置的支付/退款/分账覆盖 |
| 3 | 服务商级覆盖 | 该服务商名下交易 | 服务商档案的同款覆盖，商户未配时生效 |
| 4 | 全局旁路开关 | 全实例 | 全部成功 / 全部失败；跳过交易类型默认 |
| 5 | 交易类型默认 | — | 见下表，写死不可配 |
即使开了"全部失败"，确认页点"确认支付成功"仍然成功——手动覆盖在旁路之前。这是为了保留单笔演示能力。
## 各交易类型的默认结果
| 交易 | 无覆盖时的默认 | 要造其它结果 |
| --- | --- | --- |
| 支付 | 即时成功 | 确认页点"支付失败/继续挂起"；主体档案配支付覆盖；全局旁路"全部失败" |
| 退款 · 支付宝/银联/抖音/聚合 | 即时成功 | 主体档案配退款覆盖；全局旁路"全部失败" |
| 退款 · 微信 | **处理中** | 退款订单列表人工确认；主体档案配退款覆盖 |
| 分账 | 金额尾号规则 → 未命中处理中 | 分账规则表；主体档案配分账覆盖 |
| 预授权 | 冻结成功 | 预授权页 fail 操作；全局旁路"全部失败" |
**支付没有金额尾号规则**：规则表退役后，不再有"按金额尾号造支付失败"的约定。付款码要失败，用手机付款码模拟器的"立即失败"模式；挂起族直接由确认页人工点。
## 分账规则（唯一保留的规则表）
分账是纯查询式、无回调的交易：没有落地页，也没有回调让它翻转，规则是它唯一的自动判定手段，因此保留这一张表。
| 项 | 规则 |
| --- | --- |
| 维度 | 只有**金额个位**（分位金额的最后一位） |
| 匹配顺序 | 按列表顺序先命中先赢 |
| 默认规则 | 尾号 `1` → 成功；尾号 `2` → 失败 |
| 未命中兜底 | 处理中 |
| 持久化 | SQLite，重启不清零 |
要造"分账处理中"，用一个未配置的尾号（如 `0`、`5`）下单；要造成功或失败，用 `1` 或 `2`，或自行增删规则。
## 主体覆盖能配什么
商户/服务商档案的覆盖项支持参数化动作，不只"成功/失败"两种：
| 动作 | 语义 | 参数 |
| --- | --- | --- |
| `SUCCESS` | 即时成功 | — |
| `FAIL` | 即时失败 | 可带自定义错误码与错误消息 |
| `PENDING` | 挂起，等人工或同步推进 | — |
| `DELAY_SUCCESS` | 延迟 N 秒后成功 | 延迟秒数，默认 10 |
| `DELAY_FAIL` | 延迟 N 秒后失败 | 延迟秒数 + 自定义错误码/消息 |
| `FAIL_RATE` | 按概率失败 | 失败概率 0~100 |
| `EVERY_NTH_FAIL` | 每第 N 笔失败 | N ≥ 1 |
覆盖项按交易类型独立配置：支付、退款、分账各有各的动作，未配置的项走下一层。预授权没有主体覆盖项，只能人工 fail 或全局旁路。
## 运行开关
| 开关 | 默认 | 说明 |
| --- | --- | --- |
| 全局旁路模式 | 跟随规则 | `跟随规则` / `全部成功` / `全部失败`；后两者跳过交易类型默认，手动覆盖与主体覆盖仍优先 |
| 自动回调 | 关 | 开启后所有支付/退款终态自动发回调 |
| 扫码单推进 | 人工 | `人工推进` / `自动成功`；自动成功按延迟秒数由调度器推进 |
| 回调重试次数 | 3 | 0~10；失败退避 5s / 30s / 60s |
| 微信 openid 校验 | 开 | JSAPI/小程序支付的 appid/openid 拟真校验；关闭后整段跳过，仅作调试对比 |
开关都在「模拟控制 → 联调配置」页，保存即持久化到 SQLite。
## 常见造场景配方
| 目标 | 做法 |
| --- | --- |
| 一笔支付失败 | 确认页点"支付失败"（单笔）；或主体档案配 `FAIL`（该商户全部） |
| 一笔支付一直挂起 | 确认页点"继续挂起"；或主体档案配 `PENDING` |
| 支付延迟成功，验证"查询先于回调" | 主体档案配 `DELAY_SUCCESS`，延迟 10 秒；下单后立即查单 |
| 10% 的支付失败 | 主体档案配 `FAIL_RATE`，概率 10 |
| 每第 5 笔支付失败 | 主体档案配 `EVERY_NTH_FAIL`，N=5 |
| 微信退款异步翻转 | 直接用微信渠道下单并退款，退款单默认处理中，去退款列表人工确认 |
| 分账成功/失败/处理中 | 金额尾号用 `1` / `2` / 其它数字 |
| 全部交易失败（演示降级） | 全局旁路切"全部失败"；单笔仍可用确认页覆盖 |
## 版本差异
0.3.x 及更早版本在支付、退款、预授权上也有金额规则表，页面会显示四个规则页签。升级到 0.4 后：
- 旧规则行由启动迁移自动清理，只保留分账规则；
- 支付/退款/预授权的默认结果改为写死；
- 需要失败、挂起、延迟时改用确认页、主体覆盖或全局旁路。
如果你的界面仍有四个规则页签，说明版本较早，按界面实际能力操作，不要对照本文的"支付无规则表"结论。
---
# 模拟联调通道：接入配置
**源**: https://doc.plus.daxpay.cn/tools/mock/setup.md
# 接入配置
> 目标：让主应用把模拟通道当成一个真实通道来调用，完成"下单 → 支付 → 回调 → 订单翻转"的闭环。
>
> 配置分两侧：**模拟通道路由与商户在主应用运营端配**，**运行参数在模拟通道管理台配**。两侧都完成后才生效。
## 前置检查
| 项 | 要求 | 怎么确认 |
| --- | --- | --- |
| 模拟通道子应用 | 已启动，监听 10400 | 浏览器打开 `http://127.0.0.1:10400` 能看到仪表盘 |
| 主应用部署模式 | 非 `PROD`（dev 默认装配） | 主应用以 `PROD` 启动时模拟通道模块不注册，下单会报"产品策略不存在" |
| dev 库种子 | 已有 mock 通道、产品与 21 项能力挂载 | `pay_md_channel` 的 mock 行（92001）、`pay_md_product` 的 `mock_pay`/`mock_isv`（97001/97002）、`pay_md_product_capability` 能力行 |
| 传输密钥 | 两侧 32 字符且一致 | 见下文第 4 步 |
`mock_pay` / `mock_isv` 产品与能力挂载已包含在 `data.sql` 与 `update-datas.sql` 中。若路由候选里看不到模拟通道，先确认这些种子行是否存在，而不是反复保存路由。
## 第 1 步：建模拟通道商户
运营端 → **通道商户** → 新增：
| 字段 | 填什么 | 说明 |
| --- | --- | --- |
| 产品 | 模拟支付 | 服务商形态选 `mock_isv`，直连形态选 `mock_pay` |
| 通道商户号 | 任意占位，如 `MOCK001` | 后续路由与对账都按它识别 |
| 其余凭证 | 全部留空 | 模拟通道零资料接入，不需要真实密钥 |
保存后记下通道商户号，下一步要用。
## 第 2 步：把模拟通道纳入路由
运营端 → **通道路由** → 选择目标应用：
- **基础模式**：在"按渠道默认"的微信 / 支付宝 / 银联 / 抖音四个渠道下，绑定第 1 步的通道商户号。模拟产品策略声明覆盖平台全部 21 个真实支付方式，四个渠道下任意方式都能路由到模拟通道。
- **场景模式**：在对应支付方式行选择该通道商户与支付能力。
保存路由时后端会校验"该支付方式下是否有可用能力"。如果下拉里没有模拟通道，先查 `pay_md_product_capability` 的 21 项能力行是否齐全，而不是重复新增通道商户。
## 第 3 步：配置回调地址
运营端 → **系统配置 → 平台配置 → 访问地址**，把**后端访问地址**配成模拟通道进程可达的地址：
```text
http://127.0.0.1:19999
```
模拟通道用它拼装异步回调 URL。地址不可达时，订单能支付成功，但回调发不回主应用——表现是"确认页点了成功，主应用订单仍是支付中"。
模拟通道与主应用不在同一台机器时，这里要填主应用在模拟通道侧可达的 IP 或域名；本机联调时若主应用配的是公网域名，需要在模拟通道所在机器加 hosts 指回本机。
## 第 4 步：对齐传输密钥
主应用与模拟通道之间的内部通道链路走 AES-GCM 加密，两侧密钥必须完全一致（32 字符）：
| 位置 | 配置项 |
| --- | --- |
| 主应用 `application-dev.yml` | `daxpay.channel.mock.transport-encrypt.key` |
| 模拟通道 `application.yml` | `daxpay.channel.transport-encrypt.key` |
dev 环境两处默认值已配好，**不要只改一侧**。改完重启主应用；模拟通道改完也需要重启。
## 第 5 步：重启并验证首笔支付
1. 重启主应用（模拟通道子应用不随主应用启动，需单独保持运行）。
2. 用[开发者调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md)或业务系统发起一笔扫码支付，路由选择模拟通道。
3. 打开返回的 `payBody` 确认页，点「确认支付成功」。
4. 回主应用查看：订单状态应为支付成功，回调记录里能看到模拟通道的回调与应答。
## 运行参数（模拟通道侧）
以下参数在管理台「系统 → 运行设置」修改，保存后写入 SQLite，**优先生效于 `application.yml`**：
| 参数 | 默认 | 作用 |
| --- | --- | --- |
| 对外访问地址 | `http://127.0.0.1:10400` | 生成确认页、授权页、付款码模拟链接的前缀；手机扫码联调时改成局域网 IP 或内网域名 |
| 订单/退款/分账容量 | 各 5000 | 超出按创建时间淘汰最老；压测时设为 0 表示不限 |
| 回调记录容量 | 2000 | 同上 |
| 自动回调 | 关 | 开启后所有支付/退款终态自动发回调 |
| 扫码单推进 | 人工 | 自动成功时按延迟秒数由调度器推进 |
| 回调重试次数 | 3 | 失败退避 5s / 30s / 60s |
## 启动方式
```bash
# 开发态（含管理台静态产物）
cd basic/daxpay-plus-mock-channel
mvnd spring-boot:run
# 只改前端时另起 UI dev server（/mock 前缀代理到 10400）
cd ui && pnpm install && pnpm dev
```
- 后端端口 `10400`，UI dev server `10500`。
- 生产形态是后端 `static/` 内的已构建产物；改过 UI 必须 `cd ui && pnpm build` 重新生成并提交，否则改动只存在于 dev server。
## 失败表现对照
| 现象 | 最可能的原因 | 处理 |
| --- | --- | --- |
| 下单报"产品策略不存在" | 路由没纳入模拟通道；或主应用以 `PROD` 模式启动，模块未装配 | 查路由；确认部署模式非 PROD |
| 路由候选里没有模拟通道 | 21 项能力挂载种子缺失 | 补 `pay_md_product_capability` 种子行 |
| 确认页打不开 / 404 | 对外访问地址不可达，或手机与电脑不在同一网段 | 改运行设置里的对外地址为局域网 IP |
| 点了成功，主应用仍是支付中 | 回调地址不可达、密钥不一致、回调被安全策略拦截 | 看确认页的回调送达记录与主应用回调日志 |
| 请求解密失败 / 签名错误 | 两侧 transport key 不一致 | 对齐 32 字符密钥并重启两侧 |
| 管理台能开，但页面数据为空 | 连到了错误的 SQLite 文件 | 查 `mock.db-path` 与启动工作目录 |
## 下一步
- 认识管理台每个视图：[管理台导览](https://doc.plus.daxpay.cn/tools/mock/console.md)
- 造失败、挂起、异步退款：[场景规则与运行开关](https://doc.plus.daxpay.cn/tools/mock/rules.md)
- 对接开放网关：[联调材料与接口](https://doc.plus.daxpay.cn/tools/mock/materials.md)
---
# 模拟联调通道：交易与人工裁决
**源**: https://doc.plus.daxpay.cn/tools/mock/trade.md
# 交易与人工裁决
> 模拟通道的单据不是"下单即终态"：挂起族支付要人工裁决，微信退款默认处理中，分账靠金额尾号规则，预授权要显式请款。理解每类单据的推进方式，才能造出想要的联调场景。
## 五类单据一览
| 交易 | 下单后默认 | 谁来推进终态 | 是否有回调 |
| --- | --- | --- | --- |
| 支付（挂起族） | `PENDING` | 收款确认页人工裁决，或开启自动推进 | 有 |
| 支付（付款码 BARCODE） | 即时判定 | 下单时按场景引擎直接定结果 | 有 |
| 退款 | 微信 `PENDING`，其余即时成功 | 退款订单列表人工确认，或主体覆盖 | 有 |
| 分账 | 按金额尾号规则，未命中 `PENDING` | 分账管理行内操作 | 无（纯查询式） |
| 转账 | 台账留痕 | 当前无网关推进链路 | 无 |
| 预授权 | 冻结成功 | 请款 / 解冻 / 撤销 | 冻结成功与关闭产生回调 |
## 支付：确认页是主战场
扫码、跳转、H5、PC、APP、公众号、JSAPI、小程序八种挂起族方式，下单只落单，`payBody` 指向收款确认页（`/#/pay/{tradeNo}`）。确认页提供三个动作：
| 动作 | 结果 | 适用场景 |
| --- | --- | --- |
| 确认支付成功 | 订单转成功，触发支付回调 | 演示正常收款、验证回调与订单翻转 |
| 支付失败 | 订单转失败，触发失败回调 | 验证失败分支、前端错误提示 |
| 继续挂起 | 保持 `PENDING` | 验证超时关单、轮询查单、异步回调竞态 |
确认页同时展示**回调送达记录**：每次回调的 HTTP 状态与应答体。排查"主应用没收到回调"时，先看这里有没有发出、对方回了什么。
### 聚合支付（一码多付）
下单渠道为 `AGGREGATE` 时，确认页不显示单一"确认支付"按钮，而是展示微信 / 支付宝 / 云闪付 / 抖音四个钱包按钮，**点哪个钱包就按哪个钱包成功**。订单会记录实际钱包 `actual_provider`，并通过同步响应与回调回传主应用。
- 聚合单推成功时**必须带实际钱包**，否则按 `40404` 拒绝——这是为了拟真"聚合成功必须明确付款方式"的契约。
- 失败、挂起不要求钱包。
### 付款码（BARCODE）
付款码是即时族：下单时按场景引擎直接定结果，没有 `payBody`，也没有确认页。要造付款码失败，用手机付款码模拟器的"立即失败"模式，或在主体档案配置支付覆盖。
## 退款：微信默认异步
| 原支付渠道 | 默认结果 | 为什么 |
| --- | --- | --- |
| 微信 | `PENDING` | 演练"发起退款 → 异步回调 → 退款单翻转"的完整链路 |
| 支付宝 / 银联 / 抖音 / 聚合 | 即时成功 | 大多数真实通道的同步退款语义 |
| 未知 | 即时成功 | 兜底 |
退款单在「退款订单」列表人工确认成功或失败；确认后触发退款回调。要批量造退款失败，给主体档案配置退款覆盖，而不是逐单点。
## 分账：唯一保留规则表的交易
分账是纯查询式、无回调的交易——没有落地页，也没有回调让它翻转，所以规则表是它唯一的自动判定手段：
- 规则只有**金额个位**一个维度，按列表顺序先命中先赢；
- 默认两条：尾号 `1` 成功、尾号 `2` 失败；未命中兜底**处理中**；
- 分账金额取订单总额，尾号按分位金额的最后一位计算。
规则编辑与默认值的完整说明见[场景规则与运行开关](https://doc.plus.daxpay.cn/tools/mock/rules.md)。
## 预授权：冻结之后还要请款
预授权不是"冻结即完成"，完整生命周期是：
```text
冻结（freeze） → 请款（capture） / 解冻（unfreeze） / 撤销（cancel）
```
- 冻结默认成功，可在预授权页对单据做请款、解冻、撤销，或人工置失败；
- 冻结与终态会产生回调，用于验证主应用预授权单的状态流转；
- 支付宝预授权与微信支付分共用同一套模拟台账，按产品类型区分。
## 投诉：从支付订单发起
「投诉中心」模拟支付宝/微信的消费者投诉契约：从支付订单行内发起投诉，进入投诉时间线，可查看买家留言、商家处理动作，并与退款联动。用于验证主应用的投诉工单接收与处置流程，不涉及真实渠道。
## 回调：发出、重试与补发
| 机制 | 行为 |
| --- | --- |
| 自动回调 | 默认关闭；开启后所有支付/退款终态自动发回调 |
| 失败重试 | 默认 3 次，退避 5s / 30s / 60s |
| 人工补发 | 支付/退款订单行内"补发回调"，可重复触发 |
| 送达判定 | HTTP 2xx 即成功，不检查应答体文本 |
| 报文形态 | 明文 JSON，带 `Mock-Sign` / `Mock-Timestamp` / `Mock-Nonce` 三签名头，平台私钥签名 |
回调未达时的排查顺序见[常见问题与排障](https://doc.plus.daxpay.cn/tools/mock/faq.md)。
## ISV（服务商）模式
服务商形态下，主应用在请求里带 `isvNo` 与 `subMchId`，模拟通道不做模式分套，只在订单、分账接收方与对账文件里留痕，并在回调报文追加 `subMchNo`。直连形态这两个字段为空，回调不带 `subMchNo`。
---
# 运维面板命令行用法
**源**: https://doc.plus.daxpay.cn/tools/panel/commands.md
# 运维面板命令行用法
安装完成后，系统会创建 `daxpay-plus` 管理命令（通常位于 `/usr/local/bin/daxpay-plus`）。面板无法访问、需要远程自动化，或希望直接查看服务状态时，可以使用命令行管理。
也可以直接调用 `/opt/daxpay-plus/daxpay-plus-installer` 二进制；下文统一使用 `daxpay-plus` 示例。管理面板通常需要 root 权限，非 root 用户请在命令前加 `sudo`。
终端日常管理推荐直接执行 `daxpay-plus`（无参）进入交互式管理界面，按菜单操作即可，无需记忆命令，见[终端管理界面](https://doc.plus.daxpay.cn/tools/panel/terminal.md)。
## 命令分层
`daxpay-plus help` 只列出日常命令（面板生命周期与总览巡检），并附分层引导。**应急与账号类命令不在 help 中露出**，但命令本身照常可用，供脚本化执行；交互界面的「访问恢复 / 账号恢复」分组是它们的引导入口（完整清单在交互界面的「命令帮助」页，比 `daxpay-plus help` 更全）。
## 基础命令
| 命令 | 用途 |
| --- | --- |
| `daxpay-plus start` | 后台启动面板 |
| `daxpay-plus stop` | 停止运行中的面板 |
| `daxpay-plus restart` | 重启面板，并保留原启动参数 |
| `daxpay-plus status` | 查看面板运行状态，包括 PID、端口、鉴权和安全入口 |
| `daxpay-plus logs [-f]` | 查看运行日志；`-f` 跟随日志，`--installer` 切换到安装器应用日志 |
| `daxpay-plus version` | 查看面板版本、二进制路径与运行形态 |
| `daxpay-plus info` | 查看首次启动生成的初始管理员凭据 |
| `daxpay-plus help` | 查看帮助（日常命令清单与分层引导） |
| `daxpay-plus upgrade [--force]` | 升级脚本和面板程序（`--force` 强制重装同一版本） |
## 总览巡检
```bash
daxpay-plus overview
```
一条命令查看系统全貌：系统信息与面板版本 / 系统负载 / 服务状态（产品矩阵视角，未安装灰态可见）/ Docker 引擎占用 / 端口冲突检测 / 三栈配置生效状态。免登录、不依赖面板进程运行，与 Web 总览同一实现。
## 安全入口命令
安全入口会把登录页和面板 API 放到随机或自定义路径下。不带入口路径的访问会返回 404，从而减少公网扫描和密码爆破风险。
### 命令语法
```bash
daxpay-plus entrance show
daxpay-plus entrance enable
daxpay-plus entrance rotate [--yes|-y]
daxpay-plus entrance set <路径> [--yes|-y]
daxpay-plus entrance disable [--yes|-y]
```
### 命令说明
| 命令 | 用途与行为 |
| --- | --- |
| `daxpay-plus entrance show` | 查看当前安全入口状态、入口路径和完整访问地址；省略子命令时等同于 `show` |
| `daxpay-plus entrance enable` | 确保安全入口开启；未开启时随机生成，已开启时保留原入口，不需要确认 |
| `daxpay-plus entrance rotate` | 随机更换入口；旧地址立即失效，默认需要二次确认 |
| `daxpay-plus entrance set <路径>` | 设置自定义入口；路径须为 8-64 位字母、数字、下划线或连字符，默认需要二次确认 |
| `daxpay-plus entrance disable` | 关闭安全入口；登录页和全部 API 将直接暴露，默认需要二次确认 |
入口变更写盘后，运行中的 Web 面板会在缓存刷新后生效，通常不需要重启服务。`rotate` 和 `set` 成功后，原入口立即失效，请及时更新书签或反向代理配置。
### 确认规则
- `rotate`、`set`、`disable` 默认会提示确认，输入 `y` 或 `yes` 才会继续。
- 在 cron、CI、脚本或其他非交互环境中，未提供确认时默认拒绝操作，不会误改入口。
- 自动化执行时使用 `--yes` 或 `-y` 跳过二次确认，例如：
```bash
sudo daxpay-plus entrance rotate --yes
sudo daxpay-plus entrance set my-panel-entry-2026 -y
sudo daxpay-plus entrance disable --yes
```
`--yes` 只跳过确认，不会跳过自定义路径校验，也不会改变 Web API 的安全入口 action。
### 常用场景
忘记入口地址时，直接在服务器执行：
```bash
sudo daxpay-plus entrance show
```
怀疑入口已经泄露时，随机更换入口：
```bash
sudo daxpay-plus entrance rotate
```
需要在自动化脚本中更换入口时：
```bash
sudo daxpay-plus entrance rotate --yes
```
关闭入口仅适合本机调试或明确受控的内网环境：
```bash
sudo daxpay-plus entrance disable
```
## 访问与账号应急命令
以下命令属于应急域，不在 `daxpay-plus help` 露出（照常可用）。面板打不开或登录不上时，交互界面的「访问恢复 / 账号恢复」分组是引导入口，见[终端管理界面](https://doc.plus.daxpay.cn/tools/panel/terminal.md)；各防线的背景说明见[面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md)。
### 命令语法
```bash
daxpay-plus domain show | enable <域名> | disable
daxpay-plus ipallow show | set <条目> | disable
daxpay-plus unlock
daxpay-plus reset-password [--username ] [--password ]
daxpay-plus twofactor status | disable
daxpay-plus uninstall [--purge]
```
### 命令说明
| 命令 | 用途与行为 |
| --- | --- |
| `daxpay-plus domain show` | 查看域名访问限制状态、绑定域名与完整访问地址；缺省子命令等同 `show` |
| `daxpay-plus domain enable <域名>` | 开启域名限制（先探测域名可达性）；`disable` 关闭后恢复 IP 直接可访问 |
| `daxpay-plus ipallow show` | 查看当前生效的授权 IP 白名单条目 |
| `daxpay-plus ipallow set <条目>` | 设置白名单，多条 IP 或 CIDR 网段用逗号分隔；`disable` 关闭后恢复全部来源可访问 |
| `daxpay-plus unlock` | 解除登录锁定，清零连续登录失败计数 |
| `daxpay-plus reset-password` | 重置面板账号密码并吊销全部已登录会话；支持 `--username` / `--password` 非交互执行 |
| `daxpay-plus twofactor status` | 查看两步验证启用状态与剩余恢复码；`disable` 为验证器丢失且恢复码耗尽时的兜底关闭通道 |
| `daxpay-plus uninstall` | 卸载面板程序，默认保留业务数据与配置；`--purge` 连同工作目录和业务数据一起删除，危险操作 |
`domain enable`、`ipallow set`、`twofactor disable`、`uninstall` 等变更类命令默认有确认提示，脚本化执行同样使用 `--yes` / `-y` 跳过。
## 通用选项
| 选项 | 用途 |
| --- | --- |
| `--workdir ` | 指定面板工作目录，默认 `/opt/daxpay-plus` |
| `--service ` | 指定 systemd 服务名，默认 `daxpay-plus-panel` |
| `--yes` / `-y` | 跳过需要确认的危险操作；主要用于安全入口变更和卸载脚本化执行 |
| `--username ` | 配合 `reset-password` 指定面板账号 |
| `--password ` | 配合 `reset-password` 指定新密码 |
例如，自定义目录安装的面板可以这样查看入口：
```bash
sudo daxpay-plus entrance show --workdir /srv/daxpay-plus
```
---
# 配置与排障
**源**: https://doc.plus.daxpay.cn/tools/panel/configuration.md
# 配置与排障
本页集中说明不会每天修改、但会直接影响部署安全性和运行稳定性的配置。配置变更后要区分"重启服务""重新部署容器"和"应用网关配置"三种生效方式。
## 内存档位
面板提供三个预设档位，会批量调整服务内存上限和 JVM 类型：
| 档位 | 推荐宿主内存 | 合计占用 | JVM 默认 | 适用场景 |
|------|-------------|---------|---------|----------|
| 紧凑 compact | ≥ 4 GB | 约 3.1 GB | OpenJ9 | 低配服务器或测试 |
| 标准 standard（推荐） | ≥ 8 GB | 约 6.3 GB | HotSpot | 常规生产 |
| 增强 enhanced | ≥ 16 GB | 约 12.9 GB | HotSpot | 高并发生产 |
面板会根据宿主机内存自动推荐档位，并保留约 512 MB 容差（云服务器固件保留内存导致标称与实测有差时不会误降档）。应用档位只修改配置，必须重新部署受影响的服务才会改变容器限制。单服务手工修改后会标记为"自定义"，重新应用预设档位可以恢复统一配置。
## 运行时配置
业务运行时配置位于：
~~~text
`/data/biz/runtime-conf/runtime.env`
~~~
常用配置项：
| 配置项 | 说明 |
|--------|------|
| DEPLOY_MODE | DEV 联调模式；PROD 生产模式 |
| SANDBOX_ENABLED | 沙箱开关，仅 DEV 有效 |
| ENABLE_ADMIN | 超管开关，仅 DEV 有效，PROD 强制关闭 |
| LOG_ROOT_LEVEL | 日志级别：INFO / WARN / DEBUG |
| DB_PASSWORD | PostgreSQL 密码 |
| REDIS_PASSWORD | Redis 密码 |
| ARTEMIS_PASSWORD | Artemis 密码 |
运行时配置在面板「业务环境 → 主应用 → 应用配置」抽屉中修改，重启业务容器即生效，不需要重新构建镜像（中间件密码只挂载给主应用，通道子应用不消费凭据）。正式上线前必须切换到 PROD，并确认沙箱和超管已关闭。
## 端口暴露
除网关外，基础环境和业务容器默认不发布端口到宿主机，所有服务通过 Docker 网络互通并由网关代理。
| 模式 | 行为 | 适用场景 |
|------|------|----------|
| off（默认） | 不发布宿主机端口 | 生产环境 |
| local | 绑定 127.0.0.1 | 本机调试或 SSH 隧道 |
| public | 绑定 0.0.0.0 | 特殊场景，必须配合防火墙 |
切换端口映射后需要重新部署对应容器。除非明确需要，否则不要使用 public，避免数据库、缓存或后端调试端口直接暴露到公网。
## 域名绑定与 CDN 外层接入
网关支持以下绑定目标：
| 目标 | 用途 |
|------|------|
| ui-admin | 运营管理端 |
| ui-agent | 代理商端 |
| ui-merchant | 商户端 |
| h5 | H5 端 |
| backend | 后端 API |
| artemis | Artemis 控制台 |
域名只填写裸域名，不要带协议和路径。
### 接入模式
网关源站不配置任何证书，恒只监听 80 回源 HTTP；HTTPS 统一由外侧 CDN / 网关层终结（证书的签发、续期、验证都在外层控制台完成）。接入模式两种：
| 模式 | 行为 | 适用场景 |
|------|------|----------|
| 直连源站（默认） | 域名直接解析到服务器，网关不校验请求来源 | 未接入 CDN、内网或临时联调 |
| 经 CDN / 外层网关回源 | 各绑定域名入口只放行带正确回源 Token 的请求，其余 404 | 生产环境，域名已接入 CDN |
### CDN 接入清单
切换为「经 CDN / 外层网关回源」后，按面板「CDN 外层接入」页展示的清单操作：
1. 在 CDN 控制台为各绑定域名配置 HTTPS 证书（免费证书即可）；
2. 回源协议选 HTTP，回源端口填网关监听端口（默认 80）；
3. 域名解析指向 CDN 分配的 CNAME；
4. CDN 厂商公布回源网段（阿里云 / 腾讯云等）时，建议在云控制台安全组只对网段放行 80 端口（云侧操作），与回源 Token 双层叠加。
切入 CDN 回源模式并应用网关后，在 CDN 控制台配置好回源头之前，直接解析到本机的域名访问将被 404 拒绝——这是预期的防护行为。面板在切换时会给出二次确认提示。
### 回源 Token
开启 CDN 回源模式后，面板生成回源 Token。在 CDN 控制台配置自定义回源头 `X-Daxpay-Origin` 的值为该 Token：各绑定域名入口只放行带正确 Token 的请求，防止伪造 Host 绕过 CDN 直连源站。
- 仅**绑定域名的入口**参与校验：商户 API、通道回调的直连入口不校验 Token（回调服务器不会携带自定义头，必须放行）；
- 「重新生成」Token 后须点击「应用网关配置」生效，旧 Token 立即失效，必须同步修改 CDN 控制台的回源头，否则 CDN 回源请求被 404 拒绝、网站立即断流；
- 绑定**后端 API 域名**时，该域名必须 CNAME 到 CDN 并配好回源头，微信 / 支付宝等通道回调才能正常回源；
- **Artemis 控制台**域名不建议走 CDN（多数 CDN 对 WebSocket 支持有限，控制台实时视图可能异常），保持仅内网访问或经 SSH 隧道管理。
域名、接入模式与接口开关保存后，点击「应用网关配置」渲染 nginx 配置并 reload 生效。
## 对外接口
后端接口的对外开关在「网关管理 → 对外接口」调整：
| 路径前缀 | 名称 | 默认 | 用途 |
|---------|------|------|------|
| /unipay | 商户开放 API | 开启 | DaxPay Plus 原生支付开放接口（下单/退款/分账/查询/同步），商户系统用 mchNo+AppId+RSA 签名直连，免登录，对接方优先使用 |
| /unipay/callback | 通道回调 | 开启 | 第三方支付通道异步回调，由通道服务器主动调用，必须放行已启用通道的回调；建议配合防火墙限制来源 IP |
| /epay | 易支付兼容 API | 关闭 | 易支付协议兼容接口，功能与商户开放 API 相同，仅供已对接易支付协议的第三方不改代码接入；未启用易支付协议商户请保持关闭 |
`/admin/`、`/mch/`、`/demo/`、`/test/`、`/swagger-ui/` 等管理或调试路径保持封禁。上线前只开放确实需要的接口，并结合域名、网关规则和防火墙限制来源。
## 生效方式判断
| 变更类型 | 生效方式 |
|----------|----------|
| runtime.env 中业务运行参数 | 重启对应业务容器 |
| 内存档位、运行形态、镜像版本 | 重新部署对应容器 |
| 单服务的端口暴露、资源上限、暴露模式 | drift 横幅出现「重新部署 <该服务>」按钮，仅重建该容器 |
| 网关域名、接入模式、接口开关 | 应用网关配置；必要时重新部署网关 |
| Docker 引擎配置 | 按提示重启 Docker |
| 面板账号、安全入口 | 保存后立即生效，入口变更会使旧地址失效 |
## 故障排查
### 安装阶段
**在线下载失败或 SHA256 校验失败**
确认服务器能访问下载源，重新执行安装命令。也可以用环境变量 `DAXPAY_MIRROR` 指定镜像源，或改用[离线安装](https://doc.plus.daxpay.cn/tools/panel/install.md#离线安装)。不要跳过 SHA256 校验。
**xz 缺失**
~~~bash
# RHEL 系
dnf install -y xz
# Debian 系
apt-get install -y xz-utils
~~~
安装完成后重新执行安装脚本。
**离线安装没有识别安装包**
确认 install.sh 与 .xz 文件在同一目录，并使用 bash install.sh 或授权后的 ./install.sh 执行。脚本不检查 $PWD 中的文件。
**源码拉取失败 / 仓库无权限**
代码源凭据错误时全部仓库认证失败（凭据卡顶部红条）；部分仓库无权限属授权范围问题，联系服务商开通对应仓库。内网镜像场景确认仓库地址与分组结构正确。
### 登录阶段
**打开面板返回 404**
安全入口开启时，不带入口路径访问 IP 和端口会返回 404。执行：
~~~bash
daxpay-plus entrance show
~~~
**忘记初始密码**
~~~bash
daxpay-plus info
cat /opt/daxpay-plus/installer-initial-password.txt
~~~
**登录失败被锁定**
连续输错密码会触发锁定，执行：
~~~bash
daxpay-plus unlock
~~~
**开了域名限制或 IP 白名单后面板打不开**
从新网络 / 新 IP 访问会被拒绝或伪装 404。执行以下命令查看当前限制，必要时关闭：
~~~bash
daxpay-plus domain show
daxpay-plus ipallow show
~~~
**两步验证的验证器不可用**
验证器丢失且恢复码耗尽时，在服务器执行 `daxpay-plus twofactor disable` 关闭后重新绑定。全部锁死场景的恢复通道见[面板安全 - 锁死恢复通道汇总](https://doc.plus.daxpay.cn/tools/panel/security.md#锁死恢复通道汇总)。
### 运行阶段
**端口冲突**
确认 18060、80、443 是否被其他进程占用。面板可以用 --port 更换端口，网关端口则需要停止占用服务或调整网关规划。总览页也会列出端口冲突。
**业务后端 unhealthy 或反复重启**
优先查看业务容器日志和任务终端，确认数据库已按 `table.sql → data.sql → iam_perm_menu.sql` 完整初始化（半初始化状态在数据库初始化任务中会被检测并提示强制重建），再检查磁盘、内存和运行时配置。
**页面出现 drift 横幅**
提示条按服务精准分流：
- 「重新部署 <某服务>」：该服务的端口暴露、资源上限或暴露模式已改但尚未同步到容器，点击仅重建这一个容器，其他服务不受影响；
- 「重新部署」（整栈，附影响面说明）：版本、JVM 类型、内存档位等栈级变更影响全部服务，需要重建所有已启用容器、全部服务短暂中断；
- 「应用网关配置」：网关配置已保存但 nginx 尚未 reload，点击应用即可。
**面板显示未部署但容器实际运行**
面板依据运行时容器探测和部署快照判断状态。手动启动的容器可能没有快照，先刷新面板；仍未识别时到对应页面执行一次部署，让面板接管当前环境。
## 获取诊断信息
面板无法访问时，执行以下命令收集状态和日志：
~~~bash
daxpay-plus status
daxpay-plus logs --installer
daxpay-plus logs -f
~~~
同时记录操作系统和架构、面板版本、daxpay-plus status 输出、失败任务的完整日志、相关容器状态以及最近一次配置变更。涉及密码、私钥和 token 的日志发给他人前必须脱敏。
---
# 首次部署
**源**: https://doc.plus.daxpay.cn/tools/panel/deployment.md
# 首次部署
首次部署或重新搭建一套 DaxPay Plus 环境时，在运维管理的各页面按依赖顺序完成：**源码管理 → 全局配置 → 基础环境 → 镜像构建与业务部署 → 移动端（可选） → 网关接入**。前一个环节的产物（源码、镜像、数据库）是后一个环节的输入，顺序不能颠倒；已经部署完成的服务器，日常启停和配置修改应优先使用[日常运维](https://doc.plus.daxpay.cn/tools/panel/operations.md)。
只想跟着步骤快速走完，见[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md)；面板本身的安装见[安装、升级与卸载](https://doc.plus.daxpay.cn/tools/panel/install.md)。
## 部署前检查
开始前确认：
- 服务器为 amd64 Linux，内存至少 4 GB，生产环境建议 8 GB 以上。
- Docker、Docker Compose 和 Git 可用；Docker 未安装时可在「Docker 管理 → 配置」页签一键安装（基于国内源），Git 未安装时在「源码管理」页按提示一键安装。
- 已从服务商获取**代码源访问凭据**（云效 Codeup 私服的账号与克隆密码）。凭据未配置时无法下载源码。
- 18060、80、443 等端口没有冲突。
- 生产部署已经规划域名、CDN / HTTPS 接入方式和数据库持久化空间。
## 第 1 步：源码管理与代码源凭据
进入「交付配置 → 源码管理」页，页面分三段：
### 代码源凭据
DaxPay Plus 的源码托管在代码源（默认云效 Codeup 私服）上，按仓库粒度授权。填写服务商提供的用户名与克隆密码并保存：
- 保存后自动探测一轮权限，结论直接显示在卡片上——全部可访问、部分仓库无权限（联系服务商开通）或凭据错误；
- 每个仓库的访问状态在下方状态板逐仓标注，无权限的仓库在后续构建与部署中会自动跳过或置灰，属预期而非卡死；
- 服务器访问不了公网云效时，可自定义**仓库地址**（厂商内网镜像，必须 https 且保持同构的分组结构），换址后本地源码远程地址自动重设。
### 下载代码
凭据就绪后，在源码仓库状态板拉取全部服务仓库源码（默认 `4.0` 分支）。拉取、更新与删除重下都在本页操作；下载输出通过右下角[任务中心](https://doc.plus.daxpay.cn/tools/panel/operations.md#任务中心)实时查看，长任务刷新页面后仍可恢复日志。
移动端四个工程（运营 / 商户 / 代理商 APP 与收银台小程序）的源码在「移动端管理」页单独拉取，见[移动端管理](https://doc.plus.daxpay.cn/tools/panel/miniprograms.md)。
## 第 2 步：全局配置
进入「交付配置 → 全局配置」页。全局配置会影响后续构建和运行：
| 配置 | 作用 |
|------|------|
| 内存档位 | 批量设置基础环境、业务服务的资源上限和 JVM 类型 |
| 运行形态 | 选择 HotSpot / OpenJ9 |
| 构建加速源 | 配置 Maven、npm 依赖下载加速 |
| 构建并发 | 智能 / 低内存单并发 / 均衡 / 并行四档，决定同时构建的容器数 |
部署版本（分支或 Release Tag）在「业务环境 → 版本与构建」区切换，切换后要回源码管理更新源码并重新构建镜像。修改全局配置后，如果已有容器配置产生 drift，必须按提示重新部署对应服务才能生效。
## 第 3 步：基础环境
进入「服务运维 → 基础环境」页，点击「部署基础环境」启动 PostgreSQL、Redis、Artemis 三个中间件。
- 密码由面板生成并写入工作目录配置，可在「凭据与连接」区域查看；
- 默认不把中间件端口映射到宿主机，只允许业务容器通过 Docker 网络访问；
- 需要本机调试时，在对应服务卡片临时开启端口映射（优先仅绑定 127.0.0.1）；
- 修改凭据后要按面板提示同步并重启依赖服务。
基础环境必须健康后再初始化数据库和部署业务服务。
## 第 4 步：镜像构建
进入「服务运维 → 业务环境」页，在「版本与构建」区准备镜像。
### IP 数据文件
构建前先准备 `data/ip/` 下的 ip2region 数据文件：v4 数据可通过面板一键下载，v6 数据通常需要手动下载或上传。这是后端镜像构建的前置条件——构建时会把这两个文件打进镜像并校验，缺失则构建失败。
### 一键构建
点击「一键构建」以并行流水线构建全部镜像（后端 Maven 组、Web 三端、H5 多路同时推进），覆盖：
1. 主后端与默认 / 扩展两个通道子应用；
2. 运营端、代理商端、商户端三个 Web 端；
3. H5 端。
构建耗时取决于并发档位、CPU、内存、网络和依赖缓存。部分服务构建失败时任务终态为「部分成功」，失败清单见任务中心日志，单独重建失败的服务即可，不要反复重建全部镜像。
## 第 5 步：业务部署
### 初始化数据库
执行数据库初始化任务，按 `table.sql → data.sql → iam_perm_menu.sql` 顺序导入建表、种子数据与三端菜单种子（菜单种子是三端菜单的数据来源，跳过会导致登录后无菜单）。
生产环境不要随意勾选强制重建，这会清理现有表和数据。
### 部署业务容器
当「镜像已构建 + 数据库已初始化 + IP 数据文件就绪」齐备后，点击「一键部署」启动七个业务服务：
- 后端主应用；
- 默认通道子应用与扩展通道子应用；
- 运营端、代理商端、商户端和 H5 端。
首次部署会生成 RSA、AES 和通道传输密钥。密钥生成后会固化到运行时配置，生产环境不要重复生成，否则已有加密数据可能无法解密。
业务容器默认不映射宿主机端口，统一由网关对外提供访问。需要直连调试时，前往[配置与排障](https://doc.plus.daxpay.cn/tools/panel/configuration.md)查看端口暴露策略。
## 第 6 步：移动端（可选）
需要在手机上使用运营 / 商户 / 代理商 APP 或上线聚合收银台小程序时，进入「DaxPay Plus 平台 → 移动端管理」页拉取源码并构建。版本默认跟随业务部署版本，构建产物为各平台小程序包与 App 资源包，完整说明见[移动端管理](https://doc.plus.daxpay.cn/tools/panel/miniprograms.md)。
## 第 7 步：网关接入
进入「服务运维 → 网关管理」页，点击部署网关启动独立 nginx 容器，默认使用 80 端口作为整个系统的对外入口。
### 域名
可分别为运营端、代理商端、商户端、H5、后端 API 和 Artemis 控制台配置域名。填写裸域名，不要带 http:// 或路径。
### CDN / 外层接入
网关源站不配置证书，恒只监听 80 回源 HTTP；HTTPS 统一由外侧 CDN / 网关层终结（证书的签发、续期、验证都在外层控制台完成）。接入模式两种：
- 直连源站：域名直接解析到服务器，适合未接入 CDN 或临时联调；
- 经 CDN / 外层网关回源：各绑定域名入口只放行带正确回源 Token 的请求，生产环境推荐。
CDN 接入清单与回源 Token 的完整说明见[配置与排障 - 域名绑定与 CDN 外层接入](https://doc.plus.daxpay.cn/tools/panel/configuration.md#域名绑定与-cdn-外层接入)。
### 对外接口
默认已开启商户开放 API `/unipay` 与通道回调 `/unipay/callback`（回调由通道服务器主动调用，必须放行已启用通道的回调）；易支付兼容 `/epay` 默认关闭，仅供已对接易支付协议的第三方不改代码接入时开启。管理调试路径保持封禁。
域名、接入模式和接口开关属于网关配置，点击「应用网关配置」即可 reload；内存档位等全局配置则需要重新部署容器，两者不要混淆。
## 部署验证
部署完成后逐项验证：
1. 总览页显示基础环境和业务服务健康；
2. 通过绑定域名打开运营端、代理商端、商户端和 H5；
3. 通过后端域名访问健康检查或允许的开放接口；
4. 检查网关日志、业务日志和任务终端没有持续报错；
5. 生产上线前将部署模式从 DEV 切换为 PROD，关闭沙箱和超管，再重启业务容器。
## 常见失败位置
| 现象 | 优先检查 |
|------|----------|
| 源码拉取失败 / 仓库无权限 | 代码源凭据是否正确、服务商是否开通对应仓库权限、仓库地址是否可达 |
| Docker / Git 安装失败 | sudo 权限、发行版软件源、网络和服务状态 |
| 镜像构建失败 | IP 数据文件、依赖下载源（构建加速源）、内存和具体任务日志 |
| 基础环境不健康 | 容器日志、磁盘空间、端口映射和自动生成的凭据 |
| 业务容器反复重启 | 数据库初始化是否完成、运行时配置、镜像版本和后端日志 |
| 网关访问 404/502 | 域名、接口开关、容器网络、服务健康状态 |
更完整的分阶段处理方法见[配置与排障](https://doc.plus.daxpay.cn/tools/panel/configuration.md#故障排查)。
---
# 安装、升级与卸载
**源**: https://doc.plus.daxpay.cn/tools/panel/install.md
# 安装、升级与卸载
本页说明如何把 DaxPay Plus 运维面板安装到 Linux 服务器，以及安装后的托管、升级、卸载和目录结构。首次部署业务系统请继续阅读[首次部署](https://doc.plus.daxpay.cn/tools/panel/deployment.md)；只想快速完成一次部署，可直接看[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md)。
## 安装前提
| 项目 | 要求 | 说明 |
|------|------|------|
| 架构 | x86_64（amd64） | 当前安装包不支持 arm64（业务镜像链未端到端验证） |
| 操作系统 | Ubuntu / Debian / CentOS / Rocky / RHEL / AlmaLinux / Fedora | 其他发行版仅提示警告，不一定阻断 |
| 磁盘 | 安装目录所在分区至少 500 MB | 业务镜像和数据还需要额外空间 |
| 权限 | root 或 sudo | 需要安装依赖、操作 Docker 和绑定端口 |
| 必需依赖 | xz、sha256sum | 缺失的 xz 会按发行版尝试自动安装 |
| 在线安装依赖 | curl 或 wget | 用于下载脚本和安装包 |
建议生产服务器使用 Ubuntu 22.04 及以上版本、8 GB 以上内存，并提前确认 18060、80、443 端口没有被其他服务占用。
## 在线安装
在线安装会下载脚本和 amd64 安装包，完成 SHA256 校验、解压、安装和启动：
~~~bash
curl -fsSL https://download.daxpay.top/plus/install/install.sh | sudo bash
# 或
wget -qO- https://download.daxpay.top/plus/install/install.sh | sudo bash
~~~
脚本执行流程如下：
1. 检查架构、发行版、磁盘和运行权限。
2. 检查或安装 xz，并确认 curl、sha256sum 可用。
3. 下载压缩包并执行强制 SHA256 校验。
4. 安装到 /opt/daxpay-plus，创建 daxpay-plus 命令软链。
5. 按选择生成 systemd 服务，或使用后台进程模式启动。
6. 启动面板并打印带安全入口的完整访问地址和初始管理员密码。
安装完成后不要只保存 IP 和端口，必须保存完整地址，例如：
~~~text
http://192.168.1.10:18060/k3x9m2qp4w7nbd5e
~~~
其中最后一段是随机安全入口。直接访问 IP 和端口返回 404 属于正常防护；忘记入口时执行 `daxpay-plus entrance show`。
校验失败时安装会直接终止，不会跳过校验强行安装。常见原因是下载不完整、脚本和压缩包版本不匹配或下载源异常。重新执行安装命令后再试；网络受限时使用离线安装。
## 离线安装
离线安装适合服务器访问不了下载源的场景。它只解决安装包传输问题，DaxPay Plus 后续拉取源码、构建镜像、安装依赖和访问支付渠道仍然需要网络。
准备以下两个文件并放到同一目录：
| 文件 | 作用 |
|------|------|
| install.sh | 安装脚本，内置对应安装包的 SHA256 |
| daxpay-plus-installer-linux-amd64.xz | 运维面板压缩包 |
在目标服务器执行：
~~~bash
sudo bash install.sh
~~~
或：
~~~bash
chmod +x install.sh
sudo ./install.sh
~~~
脚本只检查脚本自身所在目录的 .xz 文件，不检查当前工作目录。两个文件缺一不可，也必须来自同一版本，否则会因 SHA256 不匹配而终止。
## systemd 与后台模式
安装器会自动判断当前环境是否支持 systemd。普通 Linux 服务器通常使用 systemd；容器、WSL 等没有可用 systemd 时会退回后台进程模式。
| 项目 | systemd 可用 | systemd 不可用（容器 / WSL） |
|------|-------------|------------------------------|
| 开机自启 | 支持 | 不支持 |
| 崩溃拉起 | Restart=on-failure | 不支持 |
| 启停命令 | systemctl start daxpay-plus-panel | daxpay-plus start / daxpay-plus stop |
| 端口 | 默认 18060 | 可用 --port 自定义 |
| 日志 | journalctl -u daxpay-plus-panel | `/logs/installer-stdout.log` |
服务单元位于 /etc/systemd/system/daxpay-plus-panel.service，服务名为 daxpay-plus-panel。安装时使用 --yes 会采用默认选项并跳过交互确认。
## 升级
DaxPay Plus 处于快速迭代阶段，版本更新可能包含破坏性变更（面板配置不保证跨版本兼容）。生产环境升级前请先关注官方更新日志确认影响；跨大版本或长期未跟进的部署，推荐直接全新安装一套新环境再迁移数据。
日常升级统一使用 `daxpay-plus upgrade`，它会拉取版本清单校验、自更新管理脚本并重装程序，全程保留工作目录与业务数据：
~~~bash
daxpay-plus upgrade # 升级脚本和面板程序
daxpay-plus upgrade --force # 强制重装同一版本
~~~
需要强制重新下载并覆盖当前面板时，也可以使用安装入口的 `--force`：
~~~bash
# 在线覆盖安装（数据保留）
curl -fsSL https://download.daxpay.top/plus/install/install.sh | sudo bash -s -- install --force
# 离线覆盖：用同一版本的两个文件覆盖旧文件后执行
sudo bash install.sh install --force
~~~
覆盖前旧二进制会备份为 `<二进制>.bak`。升级后用以下命令确认面板正常：
~~~bash
daxpay-plus status
daxpay-plus entrance show
~~~
升级面板不会自动重建 DaxPay Plus 业务容器。业务版本切换、镜像构建和业务重部署请进入面板的「业务环境」页操作，见[日常运维 - 业务环境](https://doc.plus.daxpay.cn/tools/panel/operations.md#业务环境)。
## 卸载
默认卸载只移除面板程序、软链、脚本和 systemd 单元，保留工作目录与业务数据：
~~~bash
daxpay-plus uninstall
~~~
彻底清理面板工作目录需要显式使用 --purge，并经过两次确认：
~~~bash
daxpay-plus uninstall --purge
~~~
uninstall 不会自动停止或删除已部署的业务容器。若确认要清理业务环境，需另行执行：
~~~bash
cd /opt/daxpay-plus
docker compose -f docker-compose.biz.yml down -v
docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.gateway.yml down -v
~~~
## 安装目录
默认工作目录为 /opt/daxpay-plus：
~~~text
/opt/daxpay-plus/
├── installer-state.json 面板状态、账号凭据与部署快照
├── installer.db 操作审计日志（SQLite）
├── installer-initial-password.txt 首次启动生成的初始密码（修改密码后自动删除）
├── daxpay-plus-installer 面板二进制
├── install.sh 管理脚本
├── docker-compose.yml 基础环境（部署中间件时生成）
├── .env 基础环境凭据
├── docker-compose.biz.yml 业务系统（部署业务时生成）
├── .env.biz 业务系统配置
├── docker-compose.gateway.yml 网关（部署网关时生成）
├── .env.gateway 网关配置
├── logs/
│ ├── installer.log 面板访问日志
│ └── installer-stdout.log 后台启动输出（systemd 模式进 journald）
└── data/ 数据卷（bind mount，删容器不清空）
├── postgresql/ redis/ artemis/ 基础环境数据
├── build/ 源码与构建产物
├── ip/ ip2region 数据文件
├── biz/ 业务数据与运行时配置
└── nginx/ 网关配置与日志
~~~
## 下一步
- [首次部署](https://doc.plus.daxpay.cn/tools/panel/deployment.md)：按环节顺序完成源码、配置、中间件、业务和网关部署。
- [日常运维](https://doc.plus.daxpay.cn/tools/panel/operations.md)：查看服务状态、启停容器、查看日志和管理安全入口。
- [命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)：在面板不可访问或需要自动化时使用 daxpay-plus 命令。
---
# 移动端管理
**源**: https://doc.plus.daxpay.cn/tools/panel/miniprograms.md
# 移动端管理
「DaxPay Plus 平台 → 移动端管理」页管理四个移动端工程的源码与构建：
| 工程 | 产物 |
|------|------|
| 运营端 APP | 微信 / 支付宝 / 抖音小程序 + App 资源包 |
| 商户端 APP | 同上 |
| 代理商端 APP | 同上 |
| 聚合收银台小程序 | 微信 / 支付宝 / 抖音小程序 |
移动端工程的源码与构建都通过[代码源凭据](https://doc.plus.daxpay.cn/tools/panel/deployment.md#第-1-步-源码管理与代码源凭据)访问——凭据未配置时页面顶部引导去「源码管理」页；四个工程都无访问权限时（源码未开通或账号无权限），页面横幅提示联系服务商，开通后自动恢复可用。
## 版本体系
每个工程卡内选择拉取类型：**跟随 `4.0` 分支** 或 **指定 Release Tag**。
- 默认跟随业务部署版本（与「业务环境」所选版本联动），卡内提示条说明跟随来源；
- 手动选择版本后停止跟随，仅保留「与业务部署版本不一致」的灰提示；
- 进入页面与刷新时自动检测各工程版本更新：跟随分支比远端 HEAD，发布版比最新 Tag 版本号。
## 拉取与更新
每个工程卡的主按钮即当前状态，四态自动流转：
| 状态 | 主按钮 |
|------|--------|
| 未拉取 | 拉取源码 |
| 有新版本 | 更新到 vX（落后详情见 Tag 悬浮提示） |
| 已选手动版本未拉取 | 拉取所选版本 |
| 已同步 | 重新拉取（弱化显示） |
拉取与更新是异步任务，输出在右下角[任务中心](https://doc.plus.daxpay.cn/tools/panel/operations.md#任务中心)实时查看。
## 构建
点击工程卡的「构建」打开构建弹窗：
- **构建平台**：微信 / 支付宝 / 抖音小程序，以及 App 资源包（收银台小程序无 App 平台，不显示该选项）；
- **小程序 AppID**：按平台分开记录，构建时注入源码并写进 manifest；留空沿用源码内置值。App 平台填的是 DCloud 分配的 uni-app 应用标识，不是开放平台 appid；
- **API 接口地址**：移动端连接的后端地址，留空时自动使用网关后端域名（HTTPS）。
App 平台的产物是 **uni-app App 资源包**（非 APK），供 HBuilderX 云打包或 Android 离线打包使用——正式 App 包需要小程序主体自己的签名与证书，由交付方自行完成打包。
构建表单的参数按工程记忆：取消 / 重开弹窗不丢草稿，切换平台时回填该平台已保存的 appid。卡内状态行常驻「已配 appid」摘要，平时浏览看摘要，改参数开弹窗。
## 构建历史
每个工程卡下方展示构建历史：平台、版本、产物 SHA256 与构建时间。产物文件落在面板工作目录的 `data/build/` 下，供下载分发；SHA256 用于校验交付给打包方或小程序后台上传的文件完整性。
## 小程序上架提醒
- 小程序构建产物需在对应平台（微信 / 支付宝 / 抖音）的小程序后台或开发者工具中上传发布；
- 上线前确认 appid 已换成各主体正式申请的 appid，`TODO_REPLACE` 占位appid不可用于发布；
- 收银台小程序需要后端网关域名与[网关接入](https://doc.plus.daxpay.cn/tools/panel/deployment.md#第-7-步-网关接入)配置的域名一致，否则支付回调与跳转不可用。
---
# 日常运维
**源**: https://doc.plus.daxpay.cn/tools/panel/operations.md
# 日常运维
部署完成后，日常工作都在运维管理的各页面中进行。它们不要求按固定顺序操作，适合服务启停、配置调整、查看日志、版本升级和问题定位。
侧栏按功能分组：**系统运维**（总览、基础环境、业务环境、网关管理、Docker 管理、数据存储、操作审计、面板设置）、**DaxPay Plus 平台**（移动端管理）、**交付配置**（源码管理、全局配置）。
## 总览
总览页集中展示：
- 系统信息与 CPU、内存、磁盘和平均负载；
- 基础环境和业务服务健康状态（服务卡片只读平铺）；
- 面板、网关及业务端口冲突检测；
- 当前部署版本、运行版本和 drift 状态。
代码源凭据未配置时，总览页顶部显示首启引导卡，一键跳转「源码管理」页完成配置。点击服务卡片可以进入对应管理页。
## 任务中心
右下角任务入口打开任务中心：右侧抽屉展示运行中（置顶）与历史任务，每个任务可打开日志浮窗查看输出（支持拖拽缩放、复制与下载）。
- 构建源码、拉取源码、部署、网关应用等耗时操作都作为任务执行，发起后切页不中断，随时回来看进度；
- 任务支持多任务并行：不同类任务可同时进行（如镜像构建中同时应用网关配置），同类或独占任务冲突时会说明占用中的任务；
- 发起任务时会自动弹出日志浮窗，「过程即结果」的任务（如源码拉取）发起即见输出；
- 部分服务构建失败时任务终态为「部分成功」，失败清单见任务日志，可单独重建失败的服务；
- 失败 / 部分成功会弹全局通知，未处理的失败在任务入口上有红色角标；历史任务支持单删与清空。
## 基础环境
基础环境包含 PostgreSQL、Redis 和 Artemis。每个服务卡片支持启动、停止、重启、重新部署、删除容器、查看日志、查看详情和配置。
- 「启动全部」「停止全部」「重启全部」适合维护窗口批量操作；
- 「重新部署」会重建容器，是否保留数据取决于是否删除数据卷；生产环境先确认操作提示；
- 凭据与连接区域可以查看或修改中间件密码，修改后自动同步配置并重启消费凭据的主应用容器（通道子应用不连中间件，不重启）；
- 端口默认不映射到宿主机，临时调试时优先选择仅绑定 127.0.0.1。
## 业务环境
业务环境分为上半运行态管理和下半「版本与构建」变更闭环。
### 运行态
七个业务服务（后端主应用、默认 / 扩展通道子应用、运营端、代理商端、商户端、H5）支持分组启停、重启、单服务部署、重部署、删除容器和日志查看。扩展通道子应用随代码源权限置灰——凭据未开通该仓权限时不可用。
应用配置抽屉可以调整运行时参数（部署模式、沙箱、超管、日志级别）、端口映射和部署模式；密钥管理和通道信息位于独立抽屉中，避免误改其他服务配置。
### 版本与构建
下半区收拢日常升级操作：源码下载 / 更新、检查更新、切换 branch / Release Tag、数据库初始化、IP 数据文件与镜像构建。
- 版本切换后按新版本拉取源码，仍需重新构建镜像并重新部署才生效；
- 页面会用 drift 横幅提示哪些服务需要重新部署，按服务精准分流（只重建受影响容器）；
- 「一键构建」为并行流水线，构建并发档位在全局配置页调整，低配机器建议锚定单并发。
版本、构建与升级的完整说明见[首次部署](https://doc.plus.daxpay.cn/tools/panel/deployment.md)。
## 网关管理
网关是对外流量的统一入口，页面分五个页签：总览、域名绑定、CDN 外层接入、对外接口、网关日志。
- 绑定运营端、代理商端、商户端、H5、后端 API 和 Artemis 控制台域名；
- 配置 CDN / 外层接入模式与回源 Token（源站零证书，HTTPS 由外层 CDN / 网关终结）；
- 开关 `/unipay`、`/unipay/callback`、`/epay` 对外接口（前两项默认开启，回调必须放行已启用通道）；
- 网关的部署、启停、重启和卸载；
- 查看 nginx 访问日志和错误日志。
域名、接入模式和接口开关保存后点击「应用网关配置」即可 reload；需要重建 nginx 容器的变化才使用「重新部署」。接入模式、回源 Token 与 CDN 接入清单的完整说明见[配置与排障 - 域名绑定与 CDN 外层接入](https://doc.plus.daxpay.cn/tools/panel/configuration.md#域名绑定与-cdn-外层接入)。
## Docker 管理
Docker 管理提供配置、容器、镜像三个页签：
- 配置页查看 Docker 引擎信息、一键安装 Docker（基于国内源）、切换镜像加速器并按提示重启 Docker；
- 容器页搜索、启停、查看日志、详情和磁盘明细（按基础环境 / 业务 / 网关标注归属）；
- 镜像页删除指定镜像或清理悬空镜像。
删除镜像前确认没有服务依赖；清理悬空镜像不会代替业务版本回滚。
## 数据存储
数据存储页以只读方式统计宿主机磁盘和 `data/` 目录，包括用途分类、大小和文件数量。面板的全部数据都是 bind mount 落在宿主机 `data/` 下，停止或删除容器不会清空。这里用于判断磁盘压力，不执行高风险清理；容器、镜像和数据卷清理应到 Docker 管理或终端按明确命令执行。
## 操作审计
部署、构建、启停、配置更新和登录等写操作会自动留痕到操作审计（SQLite）。可按功能域、动作、对象类型和结果多维筛选，并查看操作详情与原始 JSON。排查"谁在什么时候改了配置"时，先查审计记录，再结合任务终端和服务日志确认结果。
## 源码管理
「交付配置 → 源码管理」页日常用于：更新代码源凭据（服务商换钥匙、加开仓库权限后重新探测）、拉取 / 更新 / 删除重下源码、查看各仓库的分支与最近提交。凭据配置与内网镜像地址的完整说明见[首次部署 - 源码管理与代码源凭据](https://doc.plus.daxpay.cn/tools/panel/deployment.md#第-1-步-源码管理与代码源凭据)。
## 全局配置
全局配置提供内存档位、运行形态和构建加速源的日常入口。
修改后：
1. 保存配置；
2. 查看 drift 横幅确认影响的服务；
3. 按提示重新部署或重启；
4. 在总览和日志中确认新配置已经生效。
## 安全入口
安全入口把登录页和全部面板 API 放在随机路径下。安装完成后，应直接打开包含安全入口的完整地址，例如 `http://192.168.1.10:18060/k3x9m2qp4w7nbd5e`；其中随机路径是完整 URL 的一部分，必须保留。不能只打开 `http://192.168.1.10:18060`，裸访问 IP 和端口会返回 404，这是正常的安全防护。
右上角用户菜单 →「安全设置」跳转[面板设置](https://doc.plus.daxpay.cn/tools/panel/security.md#面板设置页)页（访问控制页签），支持：
- 查看当前入口；
- 随机更换入口；
- 设置自定义入口；
- 关闭入口。
安全入口与域名限制、IP 白名单、两步验证等防线共同构成面板的访问安全体系，见[面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md)。更换后旧地址立即失效，页面会跳转到新地址。自动化和无法打开 Web 面板时使用[命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)：
~~~bash
daxpay-plus entrance show
daxpay-plus entrance rotate --yes
~~~
rotate、set、disable 默认二次确认；脚本或 CI 环境必须显式使用 --yes / -y。
## 面板无法访问时
先在服务器执行：
~~~bash
daxpay-plus status
daxpay-plus logs --installer
daxpay-plus entrance show
~~~
也可以直接运行 `daxpay-plus`（无参）进入[终端管理界面](https://doc.plus.daxpay.cn/tools/panel/terminal.md)，「访问恢复」分组按安全入口 / 域名限制 / IP 白名单三道防线引导排查。
登录失败锁定执行 `daxpay-plus unlock`；忘记密码执行 `daxpay-plus reset-password`。更多按安装、登录和运行阶段划分的排查方法见[配置与排障](https://doc.plus.daxpay.cn/tools/panel/configuration.md#故障排查)。
---
# 运维面板使用入门
**源**: https://doc.plus.daxpay.cn/tools/panel/overview.md
# 运维面板使用入门
> 运维面板是 DaxPay Plus 官方安装器自带的可视化管理界面。服务器上装好面板之后，首次部署、日常配置、升级和排查都可以在浏览器里完成；面板无法访问或需要自动化时，再使用服务器上的 `daxpay-plus` 命令。
## 面板能做什么
- **首次部署** — 配置代码源凭据、拉取源码、构建镜像、部署中间件与业务服务、接入网关
- **运行管理** — 查看服务状态与资源占用、容器管理、任务中心与实时日志
- **移动端构建** — 运营 / 商户 / 代理商 APP 与收银台小程序的源码拉取和多平台构建
- **配置调整** — 内存档位、镜像加速、端口暴露、域名与 CDN 外层接入
- **访问安全** — 安全入口、域名限制、IP 白名单、两步验证、验证码与登录锁定
- **数据安全** — 修改数据库等中间件密码、查看数据目录占用
- **故障排查** — 配置漂移提示、安装 / 登录 / 运行各阶段的问题处理
> 面板本身不参与业务流量，只负责管理和监控 Docker 中的各服务。
## 首次使用
1. 在服务器上安装面板，一条命令即可，见[一键部署 - 安装运维面板](https://doc.plus.daxpay.cn/deployment/installer.md#安装运维面板)
2. 安装完成后，直接打开安装器输出的完整访问地址，例如 `http://192.168.1.10:18060/k3x9m2qp4w7nbd5e`；随机安全入口必须保留，不能只打开 `http://192.168.1.10:18060`，裸地址会返回 404
3. 使用安装时生成的初始账号密码登录。忘记初始密码时，在服务器执行 `daxpay-plus info` 查看；忘记安全入口时，执行 `daxpay-plus entrance show` 查看完整地址
4. 按[首次部署](https://doc.plus.daxpay.cn/tools/panel/deployment.md)的顺序完成源码、配置、中间件、业务与网关各环节
从零部署的最短路径见[一键部署](https://doc.plus.daxpay.cn/deployment/installer.md)，每个环节的深入说明见[首次部署详解](https://doc.plus.daxpay.cn/tools/panel/deployment.md)。
## 阅读路径
| 你的目标 | 推荐阅读 |
|---------|---------|
| 第一次安装面板 | [安装、升级与卸载](https://doc.plus.daxpay.cn/tools/panel/install.md) |
| 从零部署一套 DaxPay Plus | [一键部署](https://doc.plus.daxpay.cn/deployment/installer.md) → [首次部署详解](https://doc.plus.daxpay.cn/tools/panel/deployment.md) |
| 日常启停服务、查看日志 | [日常运维](https://doc.plus.daxpay.cn/tools/panel/operations.md) |
| 构建移动端 APP / 小程序 | [移动端管理](https://doc.plus.daxpay.cn/tools/panel/miniprograms.md) |
| 加固面板访问安全 | [面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md) |
| SSH 场景终端管理、不记得命令 | [终端管理界面](https://doc.plus.daxpay.cn/tools/panel/terminal.md) |
| 远程或自动化管理面板 | [命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md) |
| 修改资源、端口、域名或接口 | [配置与排障](https://doc.plus.daxpay.cn/tools/panel/configuration.md) |
| 遇到安装、登录或运行错误 | [配置与排障 - 故障排查](https://doc.plus.daxpay.cn/tools/panel/configuration.md#故障排查) |
## 日常操作速查
| 想做什么 | 在面板哪里 | 深入说明 |
|---------|-----------|---------|
| 看服务是否正常运行、资源占用 | 总览页 | [日常运维 - 总览](https://doc.plus.daxpay.cn/tools/panel/operations.md#总览) |
| 配置代码源凭据、拉取 / 更新源码 | 源码管理 | [首次部署 - 源码管理](https://doc.plus.daxpay.cn/tools/panel/deployment.md#第-1-步-源码管理与代码源凭据) |
| 调整内存档位（改完需重新部署生效） | 全局配置 | [配置与排障 - 内存档位](https://doc.plus.daxpay.cn/tools/panel/configuration.md#内存档位) |
| 修改数据库 / Redis / 消息队列密码 | 基础环境 - 凭据与连接 | [日常运维 - 基础环境](https://doc.plus.daxpay.cn/tools/panel/operations.md#基础环境) |
| 绑定域名、接入 CDN | 网关管理 | [配置与排障 - 域名绑定与 CDN 外层接入](https://doc.plus.daxpay.cn/tools/panel/configuration.md#域名绑定与-cdn-外层接入) |
| 控制哪些端口对外可见 | 基础环境 / 业务环境服务卡 | [配置与排障 - 端口暴露](https://doc.plus.daxpay.cn/tools/panel/configuration.md#端口暴露) |
| 查看任务输出与服务日志 | 任务中心 / 网关日志 | [日常运维 - 任务中心](https://doc.plus.daxpay.cn/tools/panel/operations.md#任务中心) |
| 构建 APP 资源包或小程序 | 移动端管理 | [移动端管理](https://doc.plus.daxpay.cn/tools/panel/miniprograms.md) |
| 开启两步验证、IP 白名单 | 面板设置 | [面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md) |
| 查看磁盘与数据目录占用 | 数据存储 | [日常运维 - 数据存储](https://doc.plus.daxpay.cn/tools/panel/operations.md#数据存储) |
## 不开面板的时候：终端
服务器上的 `daxpay-plus` 命令可以做同样的事。直接运行 `daxpay-plus`（无参）进入交互式管理界面，跟着菜单操作即可，无需记忆命令，见[终端管理界面](https://doc.plus.daxpay.cn/tools/panel/terminal.md)；需要脚本化或自动化时使用子命令，完整命令和参数说明见[运维面板命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)。
## 遇到问题?
- 安装、登录、运行各阶段的排查步骤见[配置与排障](https://doc.plus.daxpay.cn/tools/panel/configuration.md#故障排查)
- 面板完全打不开时，先在服务器执行 `daxpay-plus status`、`daxpay-plus logs --installer`、`daxpay-plus entrance show` 收集现场，再按[故障排查](https://doc.plus.daxpay.cn/tools/panel/configuration.md#故障排查)定位
> 本章节持续完善中，更多操作指引将陆续补充。
---
# 面板安全
**源**: https://doc.plus.daxpay.cn/tools/panel/security.md
# 面板安全
运维面板掌管整台服务器的部署与凭据，而它自身往往就暴露在公网。面板提供多层访问防线，从「找不到入口」到「进不来」再到「密码之外还有第二因素」，逐层提高攻击成本；每一层都可以独立启用，锁死时都有服务器本机的命令行恢复通道。
## 防线总览
| 防线 | 拦截什么 | 开启后 |
|------|---------|--------|
| 安全入口 | 公网扫描与爆破 | 登录页与全部 API 移到随机路径下，裸地址返回 404 |
| 域名访问限制 | 直接用 IP 访问 | 仅绑定域名可打开面板 |
| 授权 IP 白名单 | 任意来源访问 | 仅白名单内来源可访问，其余返回伪装 404 |
| 两步验证 | 密码泄露 | 密码之后再验一道动态口令 |
| 验证码 + 登录锁定 | 自动化爆破 | 连续失败触发验证码，达到 5 次锁定 365 天 |
安全入口的日常管理（查看 / 更换 / 关闭）见[日常运维 - 安全入口](https://doc.plus.daxpay.cn/tools/panel/operations.md#安全入口)，本页讲其余防线与整体配置入口。
## 面板设置页
所有安全配置集中在「面板设置」页（侧栏系统运维组），顶栏用户菜单的「安全设置」也会跳转到这里。页面分三个页签：
| 页签 | 内容 |
|------|------|
| 安全概览 | 五道防线状态卡墙，一眼看清哪些开了哪些没开，点击直达对应页签 |
| 账号安全 | 修改密码、密码复杂度开关、两步验证、验证码触发阈值 |
| 访问控制 | 安全入口、域名限制、授权 IP 白名单 |
## 域名访问限制
开启后面板只接受通过**绑定域名**的访问，直接用 IP 打开将不可达。适合面板域名已接入 CDN / 外层网关的场景，把面板流量收敛到与业务一致的入口上。
- 开启 / 换绑前会先探测域名可达性，结论展示在页面上；
- 命令行：`daxpay-plus domain show / enable / disable`。
## 授权 IP 白名单
开启后仅白名单内的来源可以访问面板，其余请求返回伪装 404（与真实 404 无差别，不向探测方暴露「这里有个面板」）。
- 支持 CIDR 网段与裸 IP，多条用逗号分隔；
- 校验的是 TCP 对端地址，不可伪造，不信任 `X-Forwarded-For` 等请求头；
- 本机回环与健康检查接口恒放行，不会把面板自身锁死；
- 网页上开启时会校验「当前访问来源必须命中新白名单」，防止保存瞬间把自己锁在门外。
换了网络或填错网段导致无法访问面板时，SSH 登录服务器执行：
```bash
sudo daxpay-plus ipallow disable
```
## 两步验证（TOTP）
为账号开启第二因素：登录时在密码之后追加验证器动态口令。
- 绑定：面板设置页开启后，用 Google / Microsoft Authenticator、1Password 等扫码添加；
- **恢复码**：绑定时一次性展示，务必保存；每个恢复码只能使用一次，可替代动态口令登录，也可重新生成；
- 同一格口令不可重复使用（防重放），口令错误同样计入锁定计数。
验证器不可用且恢复码耗尽时，在服务器执行以下命令关闭两步验证后重新绑定：
```bash
sudo daxpay-plus twofactor disable
```
## 验证码与登录锁定
面板登录有两道自动防爆破机制，都不需要手动开启：
- **图形验证码**：连续登录失败达到阈值次数后，下次登录要求输入验证码（验证码即焚防重放）。阈值可在面板设置页「账号安全」分区调整（1-5 次，默认 1；上界即锁定阈值，验证码作为摩擦层不可关闭）。
- **登录锁定**：连续失败 5 次锁定 365 天，这是独立兜底的硬防线；验证码错误不消耗失败计数，防止借验证码耗尽锁定配额。
锁定后联系不到服务器也无妨——有服务器权限时执行 `daxpay-plus unlock` 清零失败计数即可解锁，交互界面里的入口在「账号恢复」组（见[终端管理界面](https://doc.plus.daxpay.cn/tools/panel/terminal.md#账号恢复)）。
## 密码安全
- 面板设置页可开启**密码复杂度开关**：开启后修改或重置的新密码须 8-30 位且字母 / 数字 / 特殊字符至少两类（存量密码不追溯）。
- 忘记密码时执行 `daxpay-plus reset-password` 重置（支持 `--username` / `--password` 非交互执行），重置会吊销全部已登录会话。
## 锁死恢复通道汇总
| 场景 | 恢复命令 | 交互界面入口 |
|------|---------|-------------|
| 忘记安全入口路径 | `daxpay-plus entrance show` | 访问恢复 → 安全入口 → 查看状态 |
| 域名限制填错域名 | `daxpay-plus domain disable` | 访问恢复 → 域名限制 → 关闭 |
| IP 白名单锁死 | `daxpay-plus ipallow disable` | 访问恢复 → IP 白名单 → 关闭 |
| 登录被锁定 | `daxpay-plus unlock` | 账号恢复 → 解除登录锁定 |
| 忘记密码 | `daxpay-plus reset-password` | 账号恢复 → 重置账号密码 |
| 两步验证验证器丢失 | `daxpay-plus twofactor disable` | 账号恢复 → 两步验证 · 关闭 |
命令参数细节见[命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)。
---
# 终端管理界面
**源**: https://doc.plus.daxpay.cn/tools/panel/terminal.md
# 终端管理界面
在服务器终端直接执行 `daxpay-plus`（不带任何子命令），或显式执行 `daxpay-plus menu`，会进入交互式管理界面（TUI）。它把常用管理动作组织成菜单，SSH 连接服务器没有浏览器、或不记得具体命令时，跟着菜单走即可完成面板管理和应急恢复。
日常终端管理推荐直接运行 `daxpay-plus` 进交互界面，不需要记忆命令；具体子命令的完整参数说明见[命令行用法](https://doc.plus.daxpay.cn/tools/panel/commands.md)。
## 进入与退出
```bash
daxpay-plus # 无参默认进入交互界面
daxpay-plus menu # 显式进入，效果相同
```
- 管理面板通常需要 root 权限，非 root 用户加 `sudo`。
- 管道、CI 等非交互环境不会进入界面，自动回退显示帮助文本，脚本化用法不受影响。
- 键位语义全局统一：
- `q` 与 `Esc`：逐级返回（子菜单返回主菜单、结果页返回菜单）；
- `Ctrl+C`：唯一无条件退出键，任何页面按它直接退出界面；
- 查询类结果页支持 `r` 键原地刷新（标题旁有刷新指示）。
## 界面结构
进入后首屏常驻一个状态总览头，显示：
- 运行形态（systemd / 后台进程）、面板 PID 与端口；
- 安全入口、域名限制、IP 白名单三道防线的开启状态；
- 账号锁定与两步验证状态；
- 当前 UID 与工作目录。
状态头在进入时、按 `r` 或动作执行返回后刷新，直接读本地状态文件，不依赖面板进程是否在运行——面板挂了它照样能看、能查、能恢复。
主菜单实际画面：
```ansi
[0m[1;38;2;0;175;255mDaxPay Plus 运维面板 · 交互管理[0m[38;2;98;98;98m v0.3.0[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[38;2;98;98;98m运行状态 [0m[38;2;0;215;135m● 运行中[0m[38;2;98;98;98m（systemd 托管，PID 1556876，端口 18060）[0m
[0m[38;2;98;98;98m访问限制 [0m[38;2;98;98;98m安全入口 [0m[38;2;255;175;0m已开启[0m[38;2;98;98;98m · 域名限制 未开启 · IP 白名单 未开启[0m
[0m[38;2;98;98;98m登录账号 [0m[38;2;0;215;135m已设置[0m[38;2;98;98;98m · 未锁定 · 两步验证未启用[0m
[0m[38;2;98;98;98m当前环境 [0m[38;2;98;98;98muid=0 · /opt/daxpay-plus · 服务 daxpay-plus-panel[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[48;2;95;95;215m [0m[38;2;255;255;215;48;2;95;95;215mDaxPay Plus 运维面板 · 交互管理[0m
[0m[38;2;173;88;179m│ [0m[38;2;238;111;248m总览[0m
[0m[38;2;173;88;179m│ [0m[38;2;173;88;179m系统信息 · 负载 · 服务状态 · Docker 占用 · 端口冲突 · 生效状态[0m
[0m[38;2;221;221;221m面板管理[0m
[0m[38;2;119;119;119m启停 · 日志 · 版本 · 访问信息 · 卸载[0m
[0m[38;2;221;221;221m访问恢复[0m
[0m[38;2;119;119;119m面板打不开时（入口 · 域名 · 白名单）[0m
[0m[38;2;221;221;221m账号恢复[0m
[0m[38;2;119;119;119m登录不上（锁定·密码·两步验证）[0m
[0m[38;2;221;221;221m命令帮助[0m
[0m[38;2;119;119;119m查看全部子命令与子动作细则（比 daxpay-plus help 全，含应急命令）[0m
[0m[38;2;98;98;98m↑↓ 选择 · enter 打开 · r 刷新 · q 退出[0m
```
主菜单为「顶层动作 + 分组」形态：
| 菜单项 | 内容 |
|--------|------|
| 总览 | 一级直达的系统巡检（与 `daxpay-plus overview` 同款，见下文） |
| 面板管理 | 启停 · 日志 · 版本 · 访问信息 · 卸载 |
| 访问恢复 | 面板打不开时：安全入口 · 域名限制 · IP 白名单 |
| 账号恢复 | 登录不上时：锁定 · 密码 · 两步验证 |
| 命令帮助 | 完整命令清单与子动作细则 |
## 面板管理
```ansi
[0m[1;38;2;0;175;255mDaxPay Plus 运维面板 · 交互管理[0m[38;2;98;98;98m v0.3.0[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[38;2;98;98;98m运行状态 [0m[38;2;0;215;135m● 运行中[0m[38;2;98;98;98m（systemd 托管，PID 1556876，端口 18060）[0m
[0m[38;2;98;98;98m访问限制 [0m[38;2;98;98;98m安全入口 [0m[38;2;255;175;0m已开启[0m[38;2;98;98;98m · 域名限制 未开启 · IP 白名单 未开启[0m
[0m[38;2;98;98;98m登录账号 [0m[38;2;0;215;135m已设置[0m[38;2;98;98;98m · 未锁定 · 两步验证未启用[0m
[0m[38;2;98;98;98m当前环境 [0m[38;2;98;98;98muid=0 · /opt/daxpay-plus · 服务 daxpay-plus-panel[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[48;2;95;95;215m [0m[38;2;255;255;215;48;2;95;95;215m面板管理[0m
[0m[38;2;173;88;179m│ [0m[38;2;238;111;248m查看访问信息[0m
[0m[38;2;173;88;179m│ [0m[38;2;173;88;179m外网与本机访问地址、初始管理员凭据[0m
[0m[38;2;221;221;221m启动面板[0m
[0m[38;2;119;119;119m后台启动（systemd 安装自动走 systemctl）[0m
[0m[38;2;221;221;221m停止面板[0m
[0m[38;2;119;119;119m停止运行中的面板[0m
[0m[38;2;221;221;221m重启面板[0m
[0m[38;2;119;119;119m保留原启动参数重启[0m
[0m[38;2;221;221;221m查看日志[0m
[0m[38;2;119;119;119m最近 200 行运行日志[0m
[0m[38;2;221;221;221m跟随日志[0m
[0m[38;2;119;119;119m持续输出新增日志，Ctrl+C 结束后返回菜单[0m
[0m[38;2;221;221;221m查看面板版本[0m
[0m[38;2;119;119;119m版本号、二进制路径与运行形态[0m
[0m[38;2;221;221;221m卸载面板[0m
[0m[38;2;119;119;119m仅移除面板程序，业务容器/镜像/数据不受影响（--purge 见命令帮助）[0m
[0m[38;2;98;98;98m↑↓ 选择 · enter 执行 · esc/q 返回上级 · r 刷新[0m
```
| 动作 | 说明 |
|------|------|
| 查看访问信息 | 外网与本机访问地址、初始管理员凭据 |
| 启动 / 停止 / 重启面板 | systemd 安装自动走 systemctl；保留原启动参数 |
| 查看日志 | 最近 200 行运行日志 |
| 跟随日志 | 持续输出新增日志，Ctrl+C 结束后返回菜单 |
| 查看面板版本 | 版本号、二进制路径与运行形态 |
| 卸载面板 | 仅移除面板程序，业务容器与数据不受影响，界面内确认后执行 |
## 访问恢复
面板打不开时按「三道门」逐项排查。进入分组后按防线分节，**分节行实时显示该防线的开启状态与关键值**（如安全入口当前路径），一眼看出是被哪道门挡住的：
```ansi
[0m[1;38;2;0;175;255mDaxPay Plus 运维面板 · 交互管理[0m[38;2;98;98;98m v0.3.0[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[38;2;98;98;98m运行状态 [0m[38;2;0;215;135m● 运行中[0m[38;2;98;98;98m（systemd 托管，PID 1556876，端口 18060）[0m
[0m[38;2;98;98;98m访问限制 [0m[38;2;98;98;98m安全入口 [0m[38;2;255;175;0m已开启[0m[38;2;98;98;98m · 域名限制 未开启 · IP 白名单 未开启[0m
[0m[38;2;98;98;98m登录账号 [0m[38;2;0;215;135m已设置[0m[38;2;98;98;98m · 未锁定 · 两步验证未启用[0m
[0m[38;2;98;98;98m当前环境 [0m[38;2;98;98;98muid=0 · /opt/daxpay-plus · 服务 daxpay-plus-panel[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[48;2;95;95;215m [0m[38;2;255;255;215;48;2;95;95;215m访问恢复[0m
[0m[38;2;173;88;179m│ [0m[38;2;238;111;248m安全入口[0m
[0m[38;2;173;88;179m│ [0m[38;2;173;88;179m已开启 · /k4obnd2e4ctjdefl[0m
[0m[38;2;221;221;221m域名限制[0m
[0m[38;2;119;119;119m未开启[0m
[0m[38;2;221;221;221mIP 白名单[0m
[0m[38;2;119;119;119m未开启[0m
[0m[38;2;98;98;98m↑↓ 选择 · enter 进入 · esc/q 返回上级 · r 刷新[0m
```
选中某道防线后进入该防线的动作列表：
| 分节 | 动作 |
|------|------|
| 安全入口 | 查看状态 / 开启 / 随机更换 / 自定义路径 / 关闭 |
| 域名限制 | 查看状态 / 开启·换绑（先探测域名可达性再开启，结论展示在结果页）/ 关闭 |
| IP 白名单 | 查看状态 / 设置（逗号分隔多条 IP 或网段）/ 关闭 |
## 账号恢复
登录不上时使用：
```ansi
[0m[1;38;2;0;175;255mDaxPay Plus 运维面板 · 交互管理[0m[38;2;98;98;98m v0.3.0[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[38;2;98;98;98m运行状态 [0m[38;2;0;215;135m● 运行中[0m[38;2;98;98;98m（systemd 托管，PID 1556876，端口 18060）[0m
[0m[38;2;98;98;98m访问限制 [0m[38;2;98;98;98m安全入口 [0m[38;2;255;175;0m已开启[0m[38;2;98;98;98m · 域名限制 未开启 · IP 白名单 未开启[0m
[0m[38;2;98;98;98m登录账号 [0m[38;2;0;215;135m已设置[0m[38;2;98;98;98m · 未锁定 · 两步验证未启用[0m
[0m[38;2;98;98;98m当前环境 [0m[38;2;98;98;98muid=0 · /opt/daxpay-plus · 服务 daxpay-plus-panel[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[48;2;95;95;215m [0m[38;2;255;255;215;48;2;95;95;215m账号恢复[0m
[0m[38;2;173;88;179m│ [0m[38;2;238;111;248m解除登录锁定[0m
[0m[38;2;173;88;179m│ [0m[38;2;173;88;179m清零失败计数，解锁后可重新登录[0m
[0m[38;2;221;221;221m重置账号密码[0m
[0m[38;2;119;119;119m重置管理员账号密码并吊销全部已登录会话[0m
[0m[38;2;221;221;221m两步验证 · 查看状态[0m
[0m[38;2;119;119;119m启用状态与剩余恢复码[0m
[0m[38;2;221;221;221m两步验证 · 关闭（兜底）[0m
[0m[38;2;119;119;119m验证器不可用且恢复码耗尽时的最后手段[0m
[0m[38;2;98;98;98m↑↓ 选择 · enter 执行 · esc/q 返回上级 · r 刷新[0m
```
| 动作 | 说明 |
|------|------|
| 解除登录锁定 | 清零连续失败计数，解锁后可重新登录 |
| 重置账号密码 | 重置管理员账号密码，并吊销全部已登录会话 |
| 两步验证 · 查看状态 | 启用状态与剩余恢复码 |
| 两步验证 · 关闭（兜底） | 验证器不可用且恢复码耗尽时的最后手段 |
安全防线的背景与建议配置见[面板安全](https://doc.plus.daxpay.cn/tools/panel/security.md)。
## 总览巡检
主菜单的「总览」（等价命令 `daxpay-plus overview`）一条命令看全系统，免登录、不依赖面板进程运行：
- 系统信息：OS / 架构 / 内核、面板版本与运行形态；
- 系统负载与 Docker 引擎资源占用；
- 服务状态：产品矩阵视角，全部已知服务都列出，未安装的灰态可见，运行中的带健康检查与容器 CPU / 内存占用；
- 端口检测：无冲突时给出确认行，有冲突逐条列出监听地址；
- 三栈（基础环境 / 业务 / 网关）配置生效状态。
结果页实际画面（示例服务器尚未部署业务系统，各服务显示「未安装」灰态；已部署的服务器会显示运行状态、健康检查与资源占用）：
```ansi
[0m[1;38;2;0;175;255mDaxPay Plus 运维面板 · 交互管理[0m[38;2;98;98;98m v0.3.0[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[38;2;98;98;98m运行状态 [0m[38;2;0;215;135m● 运行中[0m[38;2;98;98;98m（systemd 托管，PID 1556876，端口 18060）[0m
[0m[38;2;98;98;98m访问限制 [0m[38;2;98;98;98m安全入口 [0m[38;2;255;175;0m已开启[0m[38;2;98;98;98m · 域名限制 未开启 · IP 白名单 未开启[0m
[0m[38;2;98;98;98m登录账号 [0m[38;2;0;215;135m已设置[0m[38;2;98;98;98m · 未锁定 · 两步验证未启用[0m
[0m[38;2;98;98;98m当前环境 [0m[38;2;98;98;98muid=0 · /opt/daxpay-plus · 服务 daxpay-plus-panel[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[1;38;2;0;175;255m▍总览[0m
[0m[1;38;2;0;175;255m▍系统信息[0m
[0m[38;2;98;98;98m系统 Ubuntu 24.04 LTS · amd64 · 内核 6.18.33.2-microsoft-standard-WSL2 [0m
[0m[38;2;98;98;98m面板 [0m[38;2;0;215;135mv0.3.0 · systemd 运行中（PID 1556876 · 端口 18060）[0m
[0m[1;38;2;0;175;255m▍系统负载[0m
[0m[38;2;98;98;98mCPU 47.7%（16 核） 负载 0.00 / 0.04 / 0.01（1/5/15 分钟） [0m
[0m[38;2;98;98;98m内存 3.0G / 19.5G [██[0m[38;2;98;98;98m░░░░░░░░] 16% [0m
[0m[38;2;98;98;98m磁盘 41.0G / 1006.9G [[0m[38;2;98;98;98m░░░░░░░░░░] 4% [0m[38;2;98;98;98m工作目录所在分区[0m
[0m[1;38;2;0;175;255m▍服务状态[0m
[0m[38;2;98;98;98m共 11 个 · 运行 0 · 停止 0 · 未安装 11[0m
PostgreSQL [0m[38;2;98;98;98m未安装 [0m
Redis [0m[38;2;98;98;98m未安装 [0m
Artemis [0m[38;2;98;98;98m未安装 [0m
后端主应用 [0m[38;2;98;98;98m未安装 [0m
默认通道子应用 [0m[38;2;98;98;98m未安装 [0m
扩展通道子应用 [0m[38;2;98;98;98m未安装 [0m
运营管理端 [0m[38;2;98;98;98m未安装 [0m
代理商端 [0m[38;2;98;98;98m未安装 [0m
商户端 [0m[38;2;98;98;98m未安装 [0m
H5 端 [0m[38;2;98;98;98m未安装 [0m
Nginx [0m[38;2;98;98;98m未安装 [0m
[0m[1;38;2;0;175;255m▍Docker 引擎占用[0m
镜像 7.7G · 容器可写层 572.0K · 卷 22.0M · 构建缓存 3.3G · 容器日志 223.7K [0m
[0m[1;38;2;0;175;255m▍端口检测[0m
[0m[38;2;255;175;0m端口 80（Nginx HTTP）被其他进程占用 · 0.0.0.0:80 有监听[0m
[0m[1;38;2;0;175;255m▍配置生效状态[0m
[0m[38;2;98;98;98m基础环境 – 未部署[0m
[0m[38;2;98;98;98m业务系统 – 未部署[0m
[0m[38;2;98;98;98m统一网关 – 未部署[0m
[0m[38;2;98;98;98m↑↓ 滚动 · r 刷新 · q/esc/enter 返回菜单[0m
```
采集多路并行，总耗时约等于最长一路。SSH 场景下想快速确认「服务都在跑、端口没冲突、配置都生效」，直接执行：
```bash
sudo daxpay-plus overview
```
## 表单与执行结果
- **带参数的动作**（如自定义入口路径、设置白名单）以表单收集输入，风险确认直接内嵌在表单里，`Esc` 取消返回菜单，`Shift+Tab` 在字段间回退。
- **查询与日志类动作**完成后进入结果页，内容原生排版（段标题 / 状态语义色 / 进度条 / 分组表格），`r` 键原地刷新；变更类结果页不提供刷新，防误重放危险操作。
- **变更类动作**（启停、三道门开关、解锁、重置密码等）完成后展示统一执行结果页：成功 / 失败语义、执行前后状态对比（运行状态、防线开关、锁定状态等字段变化一目了然）、原始输出保留在尾部；域名开启 / 换绑为捕获执行（探测结论在结果页完整展示），执行期间菜单按键提示上方显示 spinner 指示。
## 与 help 的关系
`daxpay-plus help` 只列日常命令并附分层引导，**应急与账号类命令不在 help 中露出**（命令本身照常可用）；交互界面的「访问恢复 / 账号恢复」分组是这些命令的引导入口，「命令帮助」页则展示包含应急命令在内的完整清单与子动作细则，比 `daxpay-plus help` 更全：
```ansi
[0m[1;38;2;0;175;255mDaxPay Plus 运维面板 · 交互管理[0m[38;2;98;98;98m v0.3.0[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[38;2;98;98;98m运行状态 [0m[38;2;0;215;135m● 运行中[0m[38;2;98;98;98m（systemd 托管，PID 1556876，端口 18060）[0m
[0m[38;2;98;98;98m访问限制 [0m[38;2;98;98;98m安全入口 [0m[38;2;255;175;0m已开启[0m[38;2;98;98;98m · 域名限制 未开启 · IP 白名单 未开启[0m
[0m[38;2;98;98;98m登录账号 [0m[38;2;0;215;135m已设置[0m[38;2;98;98;98m · 未锁定 · 两步验证未启用[0m
[0m[38;2;98;98;98m当前环境 [0m[38;2;98;98;98muid=0 · /opt/daxpay-plus · 服务 daxpay-plus-panel[0m
[0m[38;2;88;88;88m────────────────────────────────────────────────────────────────────────[0m
[0m[1;38;2;0;175;255m▍命令帮助[0m
[0m[1;38;2;0;175;255m▍面板管理[0m
start [0m[38;2;98;98;98m后台启动面板[0m
stop [0m[38;2;98;98;98m停止运行中的面板[0m
restart [0m[38;2;98;98;98m重启面板（保留原启动参数）[0m
status [0m[38;2;98;98;98m查看面板运行状态（PID/端口/鉴权/安全入口）[0m
logs [0m[38;2;98;98;98m查看运行日志（-f 跟随，--installer 切应用日志）[0m
version [0m[38;2;98;98;98m查看面板版本[0m
info [0m[38;2;98;98;98m查看初始管理员凭据（首次启动生成的账号密码）[0m
uninstall [0m[38;2;98;98;98m卸载面板（仅移除面板程序，业务容器与数据不受影响；--purge 连数据清除）[0m
[0m[1;38;2;0;175;255m▍业务总览[0m
overview [0m[38;2;98;98;98m总览巡检：系统信息 / 负载 / 服务状态 / 端口冲突 / 配置生效状态[0m
[0m[1;38;2;0;175;255m▍访问控制[0m
entrance [0m[38;2;98;98;98m管理安全入口（show/enable/rotate/set/disable，缺省 show）[0m
domain [0m[38;2;98;98;98m管理域名访问限制（show/enable/disable，缺省 show）[0m
ipallow [0m[38;2;98;98;98m管理授权 IP 白名单（show/set/disable，缺省 show）[0m
[0m[1;38;2;0;175;255m▍账号安全[0m
unlock [0m[38;2;98;98;98m解除登录锁定（清零失败计数）[0m
reset-password [0m[38;2;98;98;98m重置面板账号密码（--username/--password 可非交互）[0m
twofactor [0m[38;2;98;98;98m管理两步验证（status/disable，缺省 status；验证器丢失时兜底）[0m
[0m[1;38;2;0;175;255m▍通用[0m
menu [0m[38;2;98;98;98m交互式管理界面（终端下 daxpay-plus 无参默认进入）[0m
help [0m[38;2;98;98;98m显示本帮助[0m
[0m[1;38;2;0;175;255m▍子动作细则[0m
安全入口子命令（rotate/set/disable 默认需要确认，可用 --yes/-y 跳过）: [0m
daxpay-plus entrance show 查看当前入口状态与完整访问地址 [0m
daxpay-plus entrance enable 确保入口开启（已开启时保持原入口） [0m
daxpay-plus entrance rotate [--yes|-y] 随机更换入口（旧地址立即失效，默认需确认） [0m
daxpay-plus entrance set <路径> [--yes|-y] 设置自定义入口（默认需确认） [0m
daxpay-plus entrance disable [--yes|-y] 关闭入口（登录页与 API 直接暴露，默认需确认） [0m
域名访问限制子命令（开启后仅绑定域名可访问，IP/其他域名返回伪装 404）: [0m
daxpay-plus domain [show] 查看当前状态与完整访问地址 [0m
daxpay-plus domain enable <域名> [--yes|-y] 探测验证后开启/换绑（默认需确认） [0m
[--skip-probe 跳过探测强开，hairpin NAT 场景] [0m
daxpay-plus domain disable [--yes|-y] 关闭限制，IP 恢复直接可访问（默认需确认） [0m
两步验证子命令（面板设置页自助管理的兜底通道，root 本机执行）: [0m
daxpay-plus twofactor [status] 查看启用状态 [0m
daxpay-plus twofactor disable [--yes|-y] 关闭两步验证（验证器不可用且恢复码耗尽时的兜底） [0m
授权 IP 白名单子命令（开启后仅白名单来源可访问，其余返回伪装 404）: [0m
[0m[38;2;98;98;98m↑↓ 滚动 · q/esc/enter 返回菜单[0m
```
---
# 压测验收工具：快速开始
**源**: https://doc.plus.daxpay.cn/tools/perf/getting-started.md
# 快速开始
> 本文按「拿到交付包 → 生成配置 → 体检 → 开压」的顺序给出最短路径；完整参数与字段说明以交付包内 `README.md` 为准。
完整的配置字段说明与跨机部署细节仍在补充；本页覆盖已经稳定、可直接执行的步骤。
## 1. 准备运行环境
- 工具为 Go 单二进制（`perfctl`），自带 Web 管理台，文件存储，无需额外数据库或前端依赖；
- 压测目标与模拟联调通道需在同一内网；
- 主应用侧准备独立的压测库（建议 `daxpay4-perf`），不要使用生产库。
## 2. 生成配置
```bash
# 从主项目 yml 生成候选配置(主项目 yml 只读,平台私钥不导入)
perfctl config import \
--server-dir <主项目 resources 目录> \
--testhub-env \
--db-name daxpay4-perf
# 查看差异并合并(默认只补空字段,手工值优先)
perfctl config diff
perfctl config apply
```
最终运行配置只读 `configs/_perf.yaml`（不入库）；`config show` 输出脱敏值，可安全截图。
## 3. 启动管理台
```bash
perfctl serve
# 浏览器打开 http://127.0.0.1:19700
```
跨机使用时 `perfctl serve --addr 0.0.0.0:19700` 并放行端口；控制台无鉴权，必须前置带鉴权的反向代理，切勿直接暴露公网。
## 4. 体检闸门
```bash
perfctl doctor --capacity --tps 200 --duration 60s
```
- 生成 `results/doctor-*.json` 与 `doctor.md`；
- FAIL 直接阻断，WARN 需逐项确认（管理台勾选或 `--accept-warn ID`）；
- 管理台开压前必须先点「重新检测」，体检结果有时效（应急可 `--skip-doctor`）。
## 5. 准备压测库与商户
工具**不切库、不改主程序配置**，以下步骤由操作者完成：
1. 创建压测库：`perfctl db create --name daxpay4-perf --yes`；
2. 初始化 schema 与种子：`perfctl db init --yes`（或手工执行建表 / 种子 SQL）；
3. 一键准备商户与路由：`perfctl db prepare --yes`（可先 `--dry-run` 演练），按输出的 YAML 片段回填 `_perf.yaml`；
4. 把主应用指向压测库并重启；
5. 模拟联调通道容量设为 0（不限）或大于本轮总单量，容量场景关闭自动回调；
6. 重新体检，数据库 / 绑定 / mock 检查全部 PASS 后开压。
## 跨机导入（压测机没有主项目源码）
管理台「配置」页支持上传 `application.yml`、`application-.yml`、testhub `_env.yaml` 与商户私钥 PEM，上传后生成候选配置；导入时填写主应用主机并修正 target / mock / 数据库地址。目标地址不在内网时体检 `ENV-05` 会 FAIL，确需跨网须显式勾选「允许跨网访问目标」。
## 下一步
- 场景选择、造数与报告解读见[场景与报告](https://doc.plus.daxpay.cn/tools/perf/scenarios-reports.md)；
- 能力范围与安全红线见[工具概览](https://doc.plus.daxpay.cn/tools/perf/.md)。
---
# 压测验收工具：工具概览
**源**: https://doc.plus.daxpay.cn/tools/perf.md
# 压测验收工具：工具概览
> 压测验收工具是 DaxPay Plus 的容量验收工具：Go 单二进制 + 内置 Web 管理台，文件存储、零前端构建链。两条主线——对开放网关接口施压测出吞吐边界，直连 PostgreSQL 造订单数据验证规模拐点，产出可离线留档、可横向对比的 HTML 报告。
>
> 管理台默认地址 `http://127.0.0.1:19700`。
本页为工具概览；安装部署、场景包编写、报告解读与跨机压测等完整章节仍在编写。当前请以交付包内 `README.md` 与技术支持为准，完整正文上线后本页与导航同批更新。
## 适用角色与场景
| 角色 | 用途 |
| --- | --- |
| 实施、运维 | 上线前容量验收，产出可留档的压测报告 |
| 架构、开发 | 定位慢查询、连接池与索引失效点，验证扩容方案 |
| 售前、POC | 用实测数据支撑容量规划与机器采购 |
## 两条主线
| 主线 | 压什么 | 怎么压 | 产出 |
| --- | --- | --- | --- |
| 开放 API 吞吐边界 | 主应用 `/unipay/**`（支付、退款、关单、网关、预授权、分账等） | 模拟联调通道承接通道侧，按 TPS 阶梯施压至崩点 | TPS-延迟曲线、稳定上限与崩点、瓶颈归因 Top 2 |
| 数据量性能 | 订单数据规模 | 直连 PostgreSQL 用 COPY 造 10 万 / 100 万 / 500 万级订单 | 列表查询基准、数据量阶梯、EXPLAIN 与慢查询定位 |
推荐容量按「稳定上限 × 0.7」给出：连续满足 SLA（p99、错误率、背压）的最高 TPS 为稳定上限，首个失败档为崩点。
## 管理台与常用命令
管理台页面：总览、压测、实时任务、造数、查询基准、阶梯实验、报告、配置、关于。发起压测前必须先完成体检，FAIL 阻断，WARN 需逐项确认。
| 命令 | 说明 |
| --- | --- |
| `perfctl serve` | 启动管理台（默认仅监听本机 `127.0.0.1:19700`） |
| `perfctl doctor --capacity --tps N --duration 60s` | 开压前体检，生成体检报告 |
| `perfctl run --scenario scenarios/pay-barcode.yaml` | 执行压测场景 |
| `perfctl datagen --dataset datasets/orders-1m.yaml --yes` | COPY 造订单数据 |
| `perfctl clean --tag PERF-1M --yes` | 按 tag 清理造数 |
| `perfctl dbcheck --queries queries/orders-baseline.yaml` | 列表 SQL 计时 + EXPLAIN |
| `perfctl ladder --experiment experiments/volume-ladder.yaml --yes` | 数据量阶梯实验 |
| `perfctl report --run run-...` | 生成离线自包含 HTML 报告 |
内置场景覆盖 ping、付款码支付、混合支付、退款、关单、网关、预授权、分账、对账、回调、长稳与 ramp-to-break。
## 使用前提
1. 准备独立压测库（默认 `daxpay4-perf`），初始化 schema 与种子数据；
2. 一键准备压测商户、应用、公钥、模拟通道商户与路由；
3. 把主应用指向压测库并重启——**工具不启停主程序、不改主程序配置、不切库**；
4. 模拟联调通道容量设为不限或大于本轮总单量，容量场景关闭自动回调；
5. `perfctl doctor` 的数据库、绑定与 mock 检查全部 PASS 后开压。
## 安全红线
- 只允许内网目标；目标库名含生产标识一律拒绝执行；
- 开发库写入需显式 `--allow-dev-db`，报告会标注开发库口径；
- 管理台无鉴权且可发起压测、造数等写操作，仅限可信内网；对外必须前置带鉴权的反向代理；
- API、报告与日志中的密码、传输密钥、私钥一律脱敏展示。
## 获取与版本
压测验收工具随**全渠道版起**附带源码交付，不单独销售；版本与授权范围以商业版合同为准。
## 继续阅读
- [快速开始](https://doc.plus.daxpay.cn/tools/getting-started.md)：配置导入、管理台启动、体检闸门与压测库准备
- [场景与报告](https://doc.plus.daxpay.cn/tools/scenarios-reports.md)：内置场景、造数与阶梯、指标口径与报告解读
---
# 压测验收工具：场景与报告
**源**: https://doc.plus.daxpay.cn/tools/perf/scenarios-reports.md
# 场景与报告
> 场景包是声明式 YAML，内置 12 个常用场景；压测与造数结束都会产出可离线归档的 HTML 报告。完整字段定义以交付包内 `README.md` 与 `scenarios/_common.md` 为准。
本页覆盖内置场景、造数与报告口径；自定义场景 DSL 的逐字段说明仍在补充。
## 内置场景
| 场景 | 用途 |
| --- | --- |
| `ping` | 连通性与签名基线，最小流量冒烟 |
| `pay-barcode` | 付款码支付 |
| `pay-mixed` | 多种支付方式混合施压 |
| `refund-flow` | 支付后退款全链路 |
| `close-flow` | 支付后关单 |
| `gateway` | 网关预下单链路 |
| `preauth` | 预授权冻结、请款、解冻 |
| `alloc` | 分账发起与同步 |
| `reconcile` | 对账链路 |
| `callback` | 回调 / 通知链路 |
| `soak` | 长稳场景 |
| `ramp-to-break` | TPS 阶梯递增至崩点 |
场景要点：
- 容量场景**不传 `notifyUrl`**，避免商户通知干扰吞吐口径；
- 单号统一带 `PERF-${runTag}` 前缀；
- 付款码尾号有约定（如 1 = 即时成功、3 = 处理中 / 可关单），用于构造不同终态；
- 场景 DSL 严格校验字段，未知字段直接报错；`perfctl scenario validate` 可离线自检。
## 造数与数据量阶梯
| 数据集 | 规模 |
| --- | --- |
| `orders-100k.yaml` | 10 万订单 |
| `orders-1m.yaml` | 100 万订单 |
| `orders-5m.yaml` | 500 万订单 |
| `orders-ladder.yaml` | 阶梯实验用 |
- 造数直连 PostgreSQL 用 COPY 写入，支持多商户（按订单行号轮转，同一源订单的业务单 / 退款 / 流水共用同一商户）；
- `perfctl clean --tag PERF-1M --yes` 按 tag 清理（退款 → 流水 → 资金单 → 业务单）；
- `perfctl verify --tag PERF-1M` 做库内一致性核对；
- `perfctl ladder` 按实验配置跑数据量阶梯，产出每档延迟与慢查询变化。
## 指标口径
- 客户端延迟直方图（0.5ms~60s 对数桶）：p50 / p90 / p95 / p99 / p999 / max；
- 维度：run / stage / flow / step / 错误类，1 秒时间序列，签名耗时单列；
- 资源采样：主应用与 mock 的 actuator（CPU / GC / Hikari / Tomcat）、PG、Redis、压测机自身；
- **稳定上限**：连续满足 SLA（p99、错误率、背压）的最高 TPS；
- **崩点**：首个失败档；
- **推荐容量**：稳定上限 × 0.7。
## 报告与对比
每次压测在 `results/run-*/` 下产出：
| 文件 | 内容 |
| --- | --- |
| `report.html` | 离线自包含报告（可直接归档 / 外发） |
| `meta.json` | 场景快照、主机核数、mock 配置、压测库基线 |
| `steps.jsonl` | 每步骤每秒请求 / 错误 / p50 / p95 / p99 |
| `timeseries.jsonl` | 1 秒时间序列 |
| `resources.jsonl` | 资源采样 |
| `attribution.json` | 瓶颈归因 Top 2 嫌疑（CPU / RSA、Hikari、Tomcat、Redis 池、PG、压测机） |
| `verify.json` | 响应验签抽样结果 |
- `perfctl compare --a run-... --b run-...` 横向对比两次压测的 TPS / p99 / 错误率 / 边界；
- 阶梯报告：`perfctl report --ladder results/dbcheck/ladder-*.json`；
- 一致性核对：按成功请求数与库内订单 / 退款数比对，组合场景同样适用。
## 常见问题速查
| 现象 | 处理 |
| --- | --- |
| `DB-01 database does not exist` | 压测库未创建，按快速开始建库 |
| `DB-02 配置库与实际连接不一致` | 应用仍连旧库，按目标库重启应用（工具不切库） |
| `MOCK-03 容量不足` | 模拟通道订单容量调大或设 0 |
| `APP-04 日志 DEBUG` | 窗口期改 INFO / WARN 并重启 |
| 造数 tag 已存在 | 换 tag，或 `clean --tag` 后重造（续造用 `--append`） |
| 查询基准出现 Seq Scan | 预期会命中缺失的联合索引，报告会标注 |
---
# 收款播报 APP：激活与设备
**源**: https://doc.plus.daxpay.cn/tools/voice/activation.md
# 激活与设备
> 播报 APP 按设备身份接入平台：激活时用「设备编号 + 商户激活码」双因子校验，激活即完成密钥轮换；之后设备在运营端统一管理，收款消息按设备主题推送。
设备激活的界面步骤与「MQTT 接入配置」章节仍在补充；MQTT 接入方式依赖面板侧能力确认，当前请以交付包内说明与技术支持为准。
## 设备要求
| 项 | 要求 |
| --- | --- |
| 系统 | Android 8.0 及以上，不提供 iOS 版本 |
| 设备 | 一台常开的手机或平板，建议插电 |
| 系统设置 | 允许通知、关闭电池优化、允许开机自启 |
| 网络 | 稳定联网（播报依赖平台推送） |
## 激活流程
1. 在平台侧准备设备与激活码（设备编号 + 商户激活码）；
2. 打开 APP 进入激活页，扫描 / 输入设备编号与激活码；
3. 激活成功后设备与商户绑定，密钥完成轮换；
4. 在运营端确认设备在线状态。
激活为一次性动作，换机或重装后按平台流程解绑再重新激活。
## 设备管理
- 运营端统一管理设备、激活码与在线状态；
- 设备定时心跳，平台据此校准在线 / 离线；
- 换机解绑可追溯，避免旧设备继续接收消息；
- 设备主题由平台下发，APP 不手工配置主题。
## 消息通道
| 项 | 说明 |
| --- | --- |
| 推送方式 | MQTT over WSS，持久会话 |
| 加密与验签 | 消息 AES-256-GCM 加密，HMAC-SHA256 验签 |
| 主题 | 由平台按设备分配 |
| 离线行为 | 播报依赖平台推送，当前版本不承诺离线补播 |
> MQTT 接入（broker 地址、账号与 ACL）在平台侧配置；面板是否提供可视化 MQTT 接入页签仍在确认，确认后补本章节。
---
# 收款播报 APP：工具概览
**源**: https://doc.plus.daxpay.cn/tools/voice.md
# 收款播报 APP：工具概览
> 收款播报 APP 是常驻柜台的安卓应用：支付成功后由平台经 MQTT WSS 推送收款消息，手机解密后播报金额与渠道，并按配置自动打印小票。不改造收银软件、不额外接音箱与打印机驱动，一台常开的手机即可补齐播报与打印。
>
> 当前版本 v0.2.1，支持 Android 8.0 及以上（不提供 iOS 版本）。
本页为工具概览；安装与扫码激活、MQTT 接入配置、播报与小票设置、设备管理与排障等完整章节仍在编写。其中「MQTT 接入配置」依赖面板侧能力确认后补充。当前请以交付包内说明与技术支持为准。
## 适用场景
| 场景 | 说明 |
| --- | --- |
| 台牌静态码 | 没有收银系统，手机放在柜台，顾客扫码到账即时播报 |
| 小摊与夜市 | 一台手机加一台蓝牙小票机，播报与小票一起解决 |
| 已有收银系统 | 不改造收银软件，补一台播报与打印终端 |
| 多门店 | 运营端统一管理设备、激活码与在线状态，换机解绑可追溯 |
收款播报只做到账播报与小票打印，**不发起收款**。
## 收款链路
1. **支付成功** — 微信、支付宝等通道收款成功，交易在 DaxPay 支付平台完成；
2. **平台推送** — 平台通过 MQTT WSS 将收款消息推送到对应设备主题；
3. **播报与打印** — 手机解密消息后播报金额与渠道，按配置自动打印小票；
4. **回执与心跳** — 播后回执、定时心跳，设备状态与平台校准。
## 核心能力
| 能力 | 说明 |
| --- | --- |
| 到账语音播报 | 播报金额与渠道，音量与播报开关可调 |
| 小票自动打印 | 支付成功按配置出票，样式在平台设置后各设备共用 |
| 扫码激活 | 设备编号 + 商户激活码双因子，激活即轮换密钥 |
| 设备管理 | 运营端管理设备、激活码与在线状态，换机解绑可追溯 |
| 收款流水 | 手机端查看收款记录，与平台订单对应 |
| 加密通道 | 消息 AES-256-GCM 加密，HMAC-SHA256 验签 |
| 夜间免打扰 | 跨零点免打扰时段内只记账与打印、不播语音 |
| 打印机断连保护 | 断连自动熔断，小票进入待打队列不丢失，恢复后自动续打，也可从平台补打 |
## 设备与打印兼容
| 项 | 要求 |
| --- | --- |
| 运行环境 | Android 8.0 及以上；一台常开的手机或平板，建议插电并加入电池优化白名单 |
| 打印机 | 经典蓝牙 SPP / USB / 网络 ESC/POS 热敏小票机，58mm 与 80mm 纸宽；网络打印默认端口 9100 |
| 不支持 | 仅 BLE 的打印机机型；iOS 设备 |
| 离线行为 | 播报依赖平台推送，当前版本不承诺离线补播；打印有本地待打队列 |
## 使用前提
- 平台侧完成设备与激活码准备，运营端可查看设备在线状态；
- 平台具备 MQTT 接入配置（面板侧接入方式待补充文档）；
- 手机保持联网、允许通知、关闭电池优化并允许开机自启。
## 获取与版本
收款播报 APP 商业版 **App 扩展版起**含源码交付，不单独销售；安装包随交付包提供，具体交付范围以商业版合同为准。
## 继续阅读
- [激活与设备](https://doc.plus.daxpay.cn/tools/activation.md)：激活流程、设备管理与消息通道要求
- [播报与小票打印](https://doc.plus.daxpay.cn/tools/print.md)：到账播报、夜间免打扰、打印兼容与断连保护
---
# 收款播报 APP：播报与小票打印
**源**: https://doc.plus.daxpay.cn/tools/voice/print.md
# 播报与小票打印
> 支付成功后 APP 播报金额与渠道，并按配置自动打印小票；打印机断连时小票进入待打队列，恢复后自动续打，也可从平台补打。
播报与小票的具体设置项、模板字段与排障步骤仍在补充，当前以 APP 内界面与交付包说明为准。
## 到账播报
- 播报内容：收款金额 + 支付渠道；
- 音量与播报开关可调；
- **夜间免打扰**：支持跨零点时段，时段内只记账与打印、不播语音；
- 系统缺少中文语音时，可放置提前录好的语音兜底，保证一定有声音。
## 小票打印
| 项 | 说明 |
| --- | --- |
| 连接方式 | 经典蓝牙 SPP / USB / 网络，网络打印默认端口 9100 |
| 纸宽 | 58mm 与 80mm 热敏小票机 |
| 指令集 | ESC/POS |
| 不支持 | 仅 BLE 的打印机机型 |
| 模板 | 小票样式在平台设置，各设备共用 |
## 打印机断连保护
- 断连自动熔断，不阻塞收款主流程；
- 小票进入本地待打队列，不丢失；
- 恢复连接后自动续打；
- 也可从平台发起补打。
## 排障速查
| 现象 | 排查方向 |
| --- | --- |
| 不播报 | 确认播报开关与音量、是否处于夜间免打扰时段、设备是否在线 |
| 播报但无小票 | 打印开关、打印机连接方式与端口、纸宽与指令集是否匹配 |
| 小票丢单 | 查看待打队列是否积压、恢复连接后是否续打；必要时平台补打 |
| 设备离线 | 网络、电池优化白名单、通知权限；运营端查看在线状态 |
---
# 汇付天下(Adapay)
**源**: https://doc.plus.daxpay.cn/extension/channels/adapay.md
# 汇付天下(Adapay)
## 通道概述
汇付天下旗下 Adapay 聚合支付通道。DaxPay 以**直连**产品 `ada_pay` 对接 Adapay API，一个应用 ID 覆盖微信、支付宝、银联全场景，是聚合通道中**支付方式覆盖最全**的一条。与[斗拱支付](https://doc.plus.daxpay.cn/extension/channels/dougong.md)共用 `huifu` 通道，按支付产品区分接入形态。
## 支持的支付产品
| 支付产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `ada_pay`（直连） | 进件直连型 | 经平台 Adapay 进件或自有 Adapay 商户号的商户 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 扫码、JSAPI（公众号）、APP、H5、小程序、付款码 |
| 支付宝 | 扫码、JSAPI（生活号）、APP、H5、PC 网页、付款码 |
| 银联（云闪付） | 扫码、JSAPI、H5、付款码 |
微信 JSAPI 与小程序支付需在通道配置中绑定微信应用（AppId）。
## 配置结构
Adapay 的凭据分**两层**：
1. **Adapay 服务商配置**（平台级，承接进件）：服务商编号、Adapay 应用 ID、API Key、商户 RSA 私钥与平台公钥，在「Adapay 服务商配置 / 工作台」页面维护；
2. **通道商户交易密钥**（通道商户维度）：进件通过后生成，也可手动维护：
| 字段 | 说明 |
|------|------|
| 应用 ID | Adapay 支付应用 app_id |
| API Key | 请求头 Authorization 凭据 |
| 商户 RSA 私钥 | Base64 字符串（PKCS#8），请求签名用 |
| 平台公钥 | Base64 字符串（X509），响应与回调验签用 |
创建通道商户时只登记基本信息，进件获得的凭据在密钥配置中维护。
## 回调处理
- 请求签名：SHA1withRSA，商户私钥签名 / Adapay 平台公钥验签；
- 密钥为 **Base64 裸字符串**（非 PEM 格式），从 Adapay 商户平台获取；
- 微信 / 银联聚合动态二维码走预下单特殊路径，由平台自动处理。
## 进件与开通
Adapay 走 **E 型直连进件**线：进件凭据与交易凭据两维度分离，进件申请审核通过后自动生成通道商户绑定与交易凭据。详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- Adapay 无沙箱环境，配置后直接小额生产验证；
- Adapay 与斗拱同属汇付通道但**产品独立**，密钥不要混用；
- 需在 Adapay 商户平台配置回调地址。
---
# 支付宝
**源**: https://doc.plus.daxpay.cn/extension/channels/alipay.md
# 支付宝
## 通道概述
支付宝是国内最大的第三方支付平台。DaxPay 支持支付宝**直连**与**服务商（ISV）**两种接入模式，方式覆盖扫码、JSAPI、APP、H5、PC 网页与付款码六类，并支持分账接收方绑定。
> 支付宝（直连）从通道侧准备到密钥配置的**完整对接教程**（含沙箱联调、公钥 / 证书双模式说明）见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)，本文是参数与结构的速查参考。
## 支持的支付产品
| 支付产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `alipay`（直连） | 商户直连 | 有自己支付宝商户号的商户 |
| `alipay_isv`（服务商） | 服务商代子商户发起 | 服务商帮旗下特约商户收款 |
## 支持的支付方式
| 支付方式 | 说明 | 前提 |
|---------|------|------|
| `alipay_qr`（扫码） | 返回二维码，用户扫码支付 | — |
| `alipay_jsapi`（JSAPI） | 支付宝端内调起，含小程序场景 | 需 openId；应用类型须为**小程序** |
| `alipay_app`（APP） | 商户 APP 内调起支付宝 | 应用类型须为**移动应用** |
| `alipay_h5`（H5） | 手机网页内完成支付 | — |
| `alipay_pc`（PC 网页） | 电脑网站支付 | — |
| `alipay_barcode`（付款码） | 商户扫用户付款码 | — |
## 配置结构
支付宝的配置按「通道商户 → 应用 → 应用密钥」三层组织，密钥**按应用**维度配置，不是通道商户级一份：
1. **创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选支付产品后填写：
- 直连：商户名称 + **支付宝商家用户 ID**（`2088` 开头的 PID）；
- 服务商：商户名称 + 支付宝应用（下拉选择）+ **子商户号** + 应用授权令牌（可后补）。
2. **登记应用**（直连在通道商户详情 → 应用管理；服务商在「支付宝服务商管理」页面维护）：应用名称、应用类型（**小程序 / 移动应用 / 网站应用**）、支付宝应用 ID（AppId）。
3. **配置应用密钥**：应用详情 → 密钥配置，认证方式二选一：
| 分组 | 字段 | 说明 |
|------|------|------|
| 基础配置 | 环境 | 生产 / 沙箱 |
| | 应用 ID | 支付宝 AppId |
| | 认证方式 | **公钥模式** 或 **证书模式** |
| 密钥配置（公钥模式） | 支付宝公钥 | 开放平台「开放平台密钥」页获取 |
| | 应用私钥 | 密钥工具生成的商户私钥 |
| 证书模式 | 应用公钥证书 / 支付宝公钥证书 / 支付宝根证书 | 三个证书缺一不可，安全性更高 |
| 通信密钥 | 通信密钥（AES） | 可选，接口加密场景 |
## 回调处理
- 异步通知由支付宝服务端 POST 到回调地址，平台完成验签与订单更新后应答 `success`；
- 「等待买家付款」（`WAIT_BUYER_PAY`）是**中间态**通知，不是支付成功，平台记录后忽略；
- 回调地址由平台统一生成，无需在支付宝开放平台逐应用配置；收到的原始报文可在[回调通知管理](https://doc.plus.daxpay.cn/operation-guide/admin/callback.md)查询。
## 进件与开通
支付宝走进件（代开通）线：商家先完成**代授权**，平台再走**产品开通**，两线合一完成商户开通，审核通过后自动生成通道商户绑定。详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)与[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)。
## 注意事项
- **先切环境再建商户**：沙箱与生产要各建一套通道商户，环境不匹配的商户会被路由排除；
- 证书模式更安全，建议生产环境使用；
- JSAPI 支付依赖 openId，须用**小程序**类型的应用承接；
- 服务商模式下子商户的授权令牌会过期，可在通道商户详情「应用授权令牌」处手动更新或走代运营授权；
- 常见问题见 [FAQ](https://doc.plus.daxpay.cn/getting-started/faq/.md)。
---
# 斗拱支付
**源**: https://doc.plus.daxpay.cn/extension/channels/dougong.md
# 斗拱支付
## 通道概述
斗拱支付是汇付天下旗下的聚合支付产品。DaxPay 以**服务商模式**通过汇付 V2 Trade 接口对接（产品 `dougong_pay`），与[汇付天下(Adapay)](https://doc.plus.daxpay.cn/extension/channels/adapay.md)共用 `huifu` 通道，按支付产品区分接入形态。
## 支持的支付产品
| 支付产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `dougong_pay`（服务商） | 机构二级型服务商模式 | 经斗拱进件的二级商户 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 扫码、JSAPI（公众号）、小程序 |
| 支付宝 | 扫码、JSAPI |
| 银联（云闪付） | 扫码 |
微信 JSAPI 与小程序支付需在通道配置中绑定微信应用（AppId）。斗拱不提供付款码、APP 与 H5 方式。
## 配置结构
斗拱的密钥为**服务商级配置**（「斗拱服务商管理 / 工作台」页面，全局一份）：
| 分组 | 字段 | 说明 |
|------|------|------|
| 服务商身份 | 服务商系统 ID | 汇付分配的 sysId |
| | 产品号 | 斗拱产品编号 |
| 密钥配置 | 斗拱公钥 | PEM 格式，验签用 |
| | 商户私钥 | PEM 格式（PKCS#8），签名用 |
**创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选斗拱产品后填写商户名称 + **汇付商户号**（huifuId，进件后获得，每笔交易必带）。
## 回调处理
- 请求签名：RSA（汇付 SDK 内部处理），商户私钥签名 / 斗拱公钥验签；
- 异步通知由平台验签后处理，回调地址需在汇付商户平台配置。
## 进件与开通
斗拱是汇付旗下**独立进件线**（C 型机构二级），与 Adapay 同门不同线，进件申请与凭据互不通用。详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- 斗拱与 Adapay 同属汇付通道，商户号体系互通，但**密钥与产品独立**，不要混用；
- 确保服务器出口 IP 在汇付白名单内。
---
# 抖音支付
**源**: https://doc.plus.daxpay.cn/extension/channels/douyin.md
# 抖音支付
## 通道概述
抖音支付是字节跳动旗下抖音平台的支付服务。DaxPay 支持**直连**模式对接（产品 `douyin_pay`），覆盖抖音小程序与 APP 场景，并支持分账接收方绑定。
## 支持的支付产品
单一产品 `douyin_pay`（直连），创建通道商户时无需在多个产品间选择。
## 支持的支付方式
| 支付方式 | 说明 | 前提 |
|---------|------|------|
| `douyin_jsapi`（JSAPI） | 抖音端内调起支付，小程序场景也走该方式 | 需 openId；须登记**小程序**应用 |
| `douyin_app`（APP） | 商户 APP 内调起抖音支付 | — |
| `douyin_h5`（H5） | 抖音内 H5 页面拉起收银台 | — |
| `douyin_qr`（扫码） | 返回二维码，抖音扫码支付 | — |
## 配置结构
抖音的密钥按通道商户维度配置，应用信息独立维护：
1. **创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选产品后填写商户名称 + **抖音商户号**（MCHID）；
2. **配置密钥**：通道商户详情 → 密钥配置：
| 字段 | 说明 |
|------|------|
| 商户私钥 | 抖音开放平台生成的商户私钥，请求签名用 |
| 商家公钥证书序列号 | 与上传到抖音平台的公钥证书对应 |
| 接口加密密钥 | 回调报文 AES 解密用，抖音平台「加密验签」页获取 |
3. **登记抖音应用**（[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)页面，平台应用 / 商户应用两组）：应用名称、应用类型（**小程序 / 移动应用 / 网站应用**）、AppId、应用密钥（Client Secret），并在能力绑定中为各支付方式指定所用应用。
## 回调处理
- 异步通知为**加密报文**，平台凭接口加密密钥解密后处理，应答 `{"code":"SUCCESS"}`；
- 回调地址由平台统一生成，无需在抖音开放平台逐应用配置。
## 进件与开通
抖音支付暂不支持平台在线进件：商户需自行在抖音开放平台开通商户号，再手动创建通道商户并配置密钥。
## 注意事项
- 抖音无沙箱环境，配置后直接小额生产验证；
- 仅支持抖音生态内的支付场景；
- 小程序支付需先在抖音开放平台注册小程序并获取 openId；
- 确保回调地址可外网访问。
---
# 易支付(通道)
**源**: https://doc.plus.daxpay.cn/extension/channels/easypay.md
# 易支付(通道)
## 通道概述
易支付是三方聚合支付平台，以统一协议聚合微信、支付宝等主流支付方式，**接入门槛低、开通快**。DaxPay 按易支付协议对接（产品 `easy_pay`），一期覆盖微信与支付宝扫码收款。
> 易支付在本系统有两种形态：本文的**通道化接入**（把上游易支付平台当作一条通道用），以及对外提供易支付协议的[易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)，两者独立配置、互不冲突。
## 支持的支付产品
单一产品 `easy_pay`（直连），创建通道商户时无需在多个产品间选择。不同易支付平台（上游站点）各自的网关与密钥独立。
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 扫码 |
| 支付宝 | 扫码 |
H5、JSAPI 等场景依赖通道级微信授权体系，一期暂未开放，后续版本增量支持。
## 配置结构
易支付的商户建档与对接配置分离：
1. **创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选易支付产品后填写商户名称（建档即可，无需通道侧信息）；
2. **配置密钥**：通道商户详情 → 密钥配置：
| 分组 | 字段 | 说明 |
|------|------|------|
| 基础配置 | 平台网关地址 | 所用易支付平台的站点地址 |
| | 商户 ID | 上游平台分配的 pid |
| 密钥配置 | 商户私钥 | PKCS#8 格式，请求签名用 |
| | 平台公钥 | 上游平台验签公钥，响应与回调验签用 |
协议报文格式与签名算法的完整定义见[易支付接口文档](https://doc.plus.daxpay.cn/api/epay.md)。
## 回调处理
- 请求签名：SHA256withRSA，商户私钥签名 / 平台公钥验签；
- 支付有异步通知回调；**退款无异步通知**，退款结果通过退款查询接口获取。
## 进件与开通
易支付无平台进件线：直接在上游易支付平台注册账号、获取商户 ID 与密钥，回平台创建通道商户并配置即可。
## 注意事项
- 易支付平台无沙箱环境，全部走配置中的平台地址，建议先小额验证；
- 切换上游平台时需同步更新网关地址与全部密钥；
- 上游平台质量参差，生产使用前先确认其稳定性与结算资质。
---
# 富友支付
**源**: https://doc.plus.daxpay.cn/extension/channels/fuyou.md
# 富友支付
## 通道概述
上海富友支付旗下的聚合支付通道。DaxPay 以**服务商模式**对接（产品 `fuyou_pay`），覆盖微信、支付宝、云闪付的扫码与端内收款。
## 支持的支付产品
| 支付产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `fuyou_pay`（服务商） | 服务商代子商户发起 | 经富友服务商进件的商户 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 扫码、JSAPI（公众号）、小程序、付款码 |
| 支付宝 | 扫码、JSAPI、付款码 |
| 银联（云闪付） | 扫码 |
微信 JSAPI 与小程序支付需在通道配置中绑定微信应用（AppId）。
## 配置结构
富友的密钥为**服务商级配置**（「富友服务商管理 / 工作台」页面，全局一份）：
| 分组 | 字段 | 说明 |
|------|------|------|
| 基础配置 | 富友应用编号 | 机构号 ins_cd |
| | 订单前缀 | 可选，回调凭订单号前缀反查平台订单 |
| 密钥配置 | 商户 RSA 私钥 | Base64（PKCS#8），签名用 |
| | 富友 RSA 公钥 | Base64（X509），验签用 |
**创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选富友产品后填写商户名称 + **富友商户号** + **终端号**。
## 回调处理
- 请求签名：RSA（私钥签名 / 公钥验签）；
- 支付与退款均有异步通知，平台验签后按结果应答。
## 进件与开通
富友商户经服务商在富友侧完成入网后，回平台创建通道商户并录入商户号与终端号；平台侧的进件差异说明见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **先切环境再建商户**：沙箱与生产各建一套；
- 确保服务器出口 IP 在富友白名单内。
---
# 海科融通
**源**: https://doc.plus.daxpay.cn/extension/channels/hkrt.md
# 海科融通
## 通道概述
北京海科融通旗下的聚合支付通道。DaxPay 以**服务商模式**对接（产品 `hkrt_pay`），覆盖微信、支付宝、云闪付的扫码与端内收款。海科融通采用 **MD5 签名、无需证书**，是聚合通道中对接最轻的一种。
## 支持的支付产品
| 支付产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `hkrt_pay`（服务商） | 服务商代子商户发起 | 经海科融通进件的商户 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 付款码、JSAPI（公众号）、小程序 |
| 支付宝 | 付款码、扫码、JSAPI |
| 银联（云闪付） | 付款码、扫码 |
微信 JSAPI 与小程序支付需在通道配置中绑定微信应用（AppId）。
## 配置结构
海科融通的密钥为**服务商级配置**（「海科融通服务商管理 / 工作台」页面，全局一份）：
| 分组 | 字段 | 说明 |
|------|------|------|
| 基础配置 | 服务商编号 | agent_no |
| | 接入机构标识 | access_id |
| 密钥配置 | 签名密钥 | access_key，请求签名与回调验签共用 |
**创建通道商户与终端**：商户工作台 → 通道商户 → 创建通道商户，选海科融通产品后填写商户名称 + **海科商户编号**，再在通道商户详情中绑定 SAAS 终端号（pn）。
## 回调处理
- 请求签名：MD5（参数按字母升序拼接后附签名密钥，结果大写），无需任何证书；
- 异步通知由平台验签后处理并应答。
## 进件与开通
海科融通支持平台**在线进件**：用服务商凭证走 SaaS 聚合进件接口代商户入网，通过后返回海科商户号与电签链接，自动生成通道商户绑定。详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **先切环境再建商户**：沙箱与生产各建一套；
- 确保服务器出口 IP 在海科融通白名单内。
---
# 河马付
**源**: https://doc.plus.daxpay.cn/extension/channels/hmpay.md
# 河马付
## 通道概述
河马付是杉德支付旗下的聚合支付产品。DaxPay 以**服务商模式**对接(产品 `hm_pay`,归属杉德通道),子商户绑定杉德商户号后即可受理微信、支付宝的扫码与端内收款。
## 支持的支付产品
| 支持产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `hm_pay`(河马付) | 服务商模式 | 服务商代旗下子商户收款 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 聚合 | 聚合扫码(通用二维码,自动识别微信/支付宝) |
| 微信 | 扫码、JSAPI(公众号)、小程序 |
| 支付宝 | 扫码、JSAPI |
微信 JSAPI 与小程序支付需在平台微信应用配置中绑定 AppId。
## 配置结构
河马付为**多服务商模型**:同一通道可登记多个服务商,密钥按服务商维度配置,通道商户创建时选定归属(创建后不可更改):
1. **登记服务商并配置密钥**:运营端「支付和进件产品 → 通道服务商配置 → 河马付服务商工作台」:
| 字段 | 说明 |
|------|------|
| 服务商应用号 | 服务商资料登记,杉德分配的代理号(sandAppId) |
| 应用私钥 | RSA 私钥,PKCS#8 Base64,签名用 |
| 河马付公钥 | RSA 公钥,X509 Base64,验签用 |
2. **创建通道商户**:商户端「通道商户」页创建(运营端可代建),选河马付产品与归属服务商,登记**杉德商户号**(merchantNo)与**门店号**(storeId)。
## 回调处理
支付与退款的异步通知统一由平台接收(路径 `/unipay/callback/{mchNo}/{channelMchNo}/hmpay`),杉德 RSA 验签在通道子应用侧完成后,平台凭订单号反查并推进订单状态,商户系统只需处理平台回调。
## 进件与开通
平台内河马付进件线暂未开通,杉德商户号需在杉德侧完成开通后登记到通道商户。各通道进件能力差异见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **归属服务商创建后不可更改**,录入前先确认商户所属服务商;
- 服务商的支付开关停用后仅拦截新支付下单,退款、关单、同步与回调不受影响;
- 沙箱与生产为不同的商户与网关环境,先切环境再建商户。
---
# 支付通道总览
**源**: https://doc.plus.daxpay.cn/extension/channels.md
# 支付通道总览
DaxPay 将各类支付通道封装为统一接口，业务系统对接一次即可使用全部通道。通道按接入形态分两层：**直连通道**（5 条，商户直连通道侧开通）与**聚合通道**（11 条，一次进件受理微信、支付宝、银联等多渠道收款）。
## 通道、产品与支付方式
三个词的完整辨析见[业务术语](https://doc.plus.daxpay.cn/getting-started/glossary.md)，这里只说和选型相关的两点：
1. **一条通道可以下挂多个支付产品**。产品决定接入身份与模式，例如汇付天下通道下挂 Adapay 与斗拱两个产品，银联商务按收款场景拆分 6 个产品。创建通道商户时先选产品，再填通道侧信息。
2. **每个产品支持若干支付方式**（扫码、JSAPI、APP、H5、小程序、付款码等），方式级清单见各通道页的「支持的支付方式」。
## 直连通道
| 通道 | 通道编码 | 支付产品 | 接入模式 | 说明 |
|------|---------|---------|---------|------|
| [支付宝](https://doc.plus.daxpay.cn/extension/alipay.md) | `alipay` | `alipay` / `alipay_isv` | 直连 / 服务商 | 方式覆盖最全，支持分账接收方绑定 |
| [微信支付](https://doc.plus.daxpay.cn/extension/wechat.md) | `wechat` | `wechat_pay` / `wechat_isv` | 直连 / 服务商 | API v3 证书模式，服务商线平台即服务商 |
| [抖音支付](https://doc.plus.daxpay.cn/extension/douyin.md) | `douyin` | `douyin_pay` | 直连 | 抖音小程序与 APP 场景 |
| [银联支付](https://doc.plus.daxpay.cn/extension/union.md) | `union_pay` | `union_pay` | 银联网关直连 ACP | 云闪付扫码 / H5 / 付款码，RSA2 三证书 |
| [银联商务](https://doc.plus.daxpay.cn/extension/ums.md) | `ums_pay` | 6 个产品（C扫B / 公众号 / APP / 小程序 / H5 / B扫C） | 直连 | 银联旗下全渠道收单，无证书签名 |
## 聚合通道
均为聚合收单机构通道，一次进件可受理微信、支付宝、银联等多种付款渠道：
| 通道 | 通道编码 | 支付产品 | 接入模式 | 说明 |
|------|---------|---------|---------|------|
| [汇付天下（Adapay）](https://doc.plus.daxpay.cn/extension/adapay.md) | `huifu` | `ada_pay` | 直连（进件直连型） | 一个应用 ID 覆盖微信 / 支付宝 / 银联全场景 |
| [斗拱支付](https://doc.plus.daxpay.cn/extension/dougong.md) | `huifu` | `dougong_pay` | 服务商 | 汇付旗下独立进件线，机构二级型 |
| [富友支付](https://doc.plus.daxpay.cn/extension/fuyou.md) | `fuyou_pay` | `fuyou_pay` | 服务商 | 聚合接口，商户号 + 终端号 |
| [海科融通](https://doc.plus.daxpay.cn/extension/hkrt.md) | `hkrt_pay` | `hkrt_pay` | 服务商 | MD5 签名、无需证书，支持在线进件 |
| [河马付](https://doc.plus.daxpay.cn/extension/hmpay.md) | `sand_pay` | `hm_pay` | 服务商 | 杉德旗下产品，底层走杉德通道 |
| [拉卡拉](https://doc.plus.daxpay.cn/extension/lakala.md) | `lakala_pay` | `lakala_pay` | 服务商 | V3 接口，扫码与付款码 |
| [乐刷支付](https://doc.plus.daxpay.cn/extension/leshua.md) | `leshua_pay` | `leshua_pay` | 服务商 | 扫码与付款码，MD5 / SM3 签名 |
| [盛付通](https://doc.plus.daxpay.cn/extension/sheng.md) | `sheng_pay` | `sheng_pay`（`sheng_isv` 规划中） | 直连 | 普通商户自有密钥对接 |
| [随行付](https://doc.plus.daxpay.cn/extension/vbill.md) | `vbill_pay` | `vbill_pay` | 服务商 | 天阙接口，含小程序收银台 |
| [易宝支付](https://doc.plus.daxpay.cn/extension/yeepay.md) | `yee_pay` | `yee_isv` | 服务商 | YOP 平台，密钥挂服务商配置 |
| [易支付（通道）](https://doc.plus.daxpay.cn/extension/easypay.md) | `easy_pay` | `easy_pay` | 直连 | 易支付协议通道化接入，开通快、门槛低 |
## 规划中通道
以下通道的产品主数据已预留、对接尚未实现，正式发布后会陆续开放：
| 通道 | 通道编码 | 支付产品 | 说明 |
|------|---------|---------|------|
| 星驿付 | `xingyi_pay` | `xingyi_pay` | 新大陆旗下国通星驿 |
| 通联支付 | `allin_pay` | 云商通 / 收银宝 / 收付通 | 三个产品线共用一条通道 |
| 收钱吧 | `shouqianba` | `shouqianba` | 门店聚合扫码收单 |
| 建行龙支付 | `long_pay` | `long_pay` | 建设银行聚合支付 |
| 银盛支付 | `ysep_pay` | `ysep_pay` | 银盛支付服务 |
| 快钱支付 | `quick_pay` | `quick_pay` | 快钱清算旗下 |
| Jeepay | `jee_pay` | `jee_pay` | 聚合支付平台 |
## 通用对接流程
所有通道的配置链路同构：**开通 / 进件 → 创建通道商户 → 配置通道密钥 → 支付调试验证**。
- 通道配置的三段式模型（服务商参数 → 商户进件 / 通道商户创建 → 通道商户管理）与各通道差异速查见[通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)；
- 支付宝与微信的完整对接教程（含通道侧准备、密钥配置、沙箱联调）见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)，其他通道流程相同、参数见各通道页；
- 服务商线通道的商户开通走[进件体系](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)，申请审核通过后自动生成通道商户绑定；
- 对接完成后用[开发者调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md)发起支付验证链路。
通道商户创建时会按支付产品当时的环境固化沙箱 / 生产快照，此后不随产品切换改变，环境不匹配的通道商户会被路由排除。**先在「支付管理 → 通道与产品配置 → 支付和进件产品」切好环境，再创建通道商户**，沙箱与生产各建一套。详见[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)。
通道的实际 SDK 调用运行在独立部署的通道子应用中（子应用一 10100、子应用二 10200），与主应用经加密 HTTP 通信、互不影响；通信不通的排查见 [FAQ](https://doc.plus.daxpay.cn/getting-started/faq/channel-subapp.md)。
## 编码字典
以下编码取自系统真实枚举（字典 `channel` / `pay_product` / `pay_method`），以代码为准。通道编码与产品编码见上方两张表，这里补充命名约定与支付方式全表。
直连品牌通道一般无 `_pay` 后缀（`alipay` / `wechat` / `douyin`）；间连 / 聚合通道多带 `xxx_pay` 后缀（`lakala_pay` 等，`huifu` 除外）。
### 支付产品
通道路由的真实锚点是**产品**而非通道：每笔交易先选产品，再由产品定位通道与接入模式。一通道多产品的关键设计：
- `huifu`（汇付天下）→ `ada_pay` + `dougong_pay`，两个产品共用一条汇付通道；
- `ums_pay`（银联商务）→ 6 个产品，按收款场景分别开通；
- `alipay` / `wechat` → 各 2 个产品，直连 + 服务商（ISV）；
- `sand_pay`（杉德）→ `hm_pay`，河马付底层走杉德通道。
### 支付方式
`code` 全局唯一，每个支付方式绑定一个支付渠道：
| 渠道 | 支付方式 | code |
|------|---------|------|
| 聚合 | 聚合扫码 | `aggregate_pay_qrcode` |
| 微信 | 微信小程序收银台 | `wechat_cashier` |
| 微信 | 微信扫码（Native） | `wechat_qr` |
| 微信 | 微信 JSAPI | `wechat_jsapi` |
| 微信 | 微信小程序 | `wechat_mini` |
| 微信 | 微信 H5 | `wechat_h5` |
| 微信 | 微信 APP | `wechat_app` |
| 微信 | 微信付款码 | `wechat_barcode` |
| 支付宝 | 支付宝扫码 | `alipay_qr` |
| 支付宝 | 支付宝 JSAPI（含小程序） | `alipay_jsapi` |
| 支付宝 | 支付宝电脑支付 | `alipay_pc` |
| 支付宝 | 支付宝 H5 | `alipay_h5` |
| 支付宝 | 支付宝 APP | `alipay_app` |
| 支付宝 | 支付宝付款码 | `alipay_barcode` |
| 银联 | 银联扫码 | `union_qr` |
| 银联 | 银联 JSAPI | `union_jsapi` |
| 银联 | 银联 H5 | `union_h5` |
| 银联 | 银联付款码 | `union_barcode` |
| 抖音 | 抖音扫码 / JSAPI / H5 / APP | `douyin_qr` / `douyin_jsapi` / `douyin_h5` / `douyin_app` |
| 其他 | 其他支付方式 | `other`（无固定渠道归属） |
被扫收款不提供聚合付款码方式：商户只需传 `authCode`、不传 `method`，平台按付款码前缀识别所属渠道后映射为 `wechat_barcode` / `alipay_barcode` / `union_barcode` 再走路由。前缀规则：微信 `10–15`、支付宝 `25–30`、银联 `62`。
## 选型建议
- 只需国内主流收款：直连通道即可覆盖，支付宝 + 微信是绝大多数场景的标配；
- 需要一码多渠道收款或线下门店聚合：选择聚合通道，一次进件受理多渠道，具体机构按费率与当地服务能力选择；
- 服务商（帮子商户收款）模式：支付宝 / 微信支持 ISV 模式，聚合通道多数为服务商模式；代理商以服务商身份代管商户通道配置的玩法见[代理商体系](https://doc.plus.daxpay.cn/plus/agent/overview.md)；
- 通道相关的排查问题（回调验签失败、IP 白名单、子应用通信等）见 [FAQ](https://doc.plus.daxpay.cn/getting-started/faq/.md)。
## 相关链接
- [通道配置通用操作](https://doc.plus.daxpay.cn/operation-guide/admin/channel-config.md)：三段式配置模型与各通道差异速查
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)：服务商线商户的进件流程
- [支付主数据](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)：通道 / 渠道 / 方式 / 产品 / 能力五个字典页
- [业务术语](https://doc.plus.daxpay.cn/getting-started/glossary.md)：通道 / 产品 / 方式 / 渠道的完整辨析
---
# 拉卡拉
**源**: https://doc.plus.daxpay.cn/extension/channels/lakala.md
# 拉卡拉
## 通道概述
拉卡拉是国内头部第三方支付机构,提供聚合收单服务。DaxPay 通过拉卡拉 V3 接口以**服务商模式**对接(产品 `lakala_pay`),商户进件到拉卡拉后即可受理微信、支付宝、云闪付收款。
## 支持的支付产品
| 支持产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `lakala_pay`(拉卡拉支付) | 服务商模式 | 服务商代旗下子商户收款 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 付款码、JSAPI(公众号)、小程序、APP |
| 支付宝 | 付款码、扫码、JSAPI |
| 银联(云闪付) | 付款码、扫码、JSAPI |
微信 JSAPI 与小程序支付需在平台微信应用配置中绑定 AppId。
## 配置结构
拉卡拉为**多服务商模型**:密钥按服务商维度配置,通道商户创建时选定归属:
1. **登记服务商并配置密钥**:运营端「支付和进件产品 → 通道服务商配置 → 拉卡拉服务商工作台」:
| 字段 | 说明 |
|------|------|
| 拉卡拉应用号 | 服务商资料登记,拉卡拉服务商平台分配 |
| 机构代码 | 服务商机构代码 |
| 商户证书序列号 | 与上传到拉卡拉的证书对应 |
| 应用私钥 | PEM 格式(PKCS#8),签名用 |
| 拉卡拉公钥证书 | PEM 格式,验签用 |
| SM4 密钥 | 可选,进件敏感字段加密用 |
2. **创建通道商户**:登记**拉卡拉商户号**(进件后获得)与**终端号**(termNo,每商户一个收款终端标识),并选定归属服务商。
## 回调处理
异步通知由平台统一接收,验签要素在 `Authorization` 请求头中,平台以拉卡拉公钥证书完成 SHA256withRSA 验签后处理并应答,回调地址由平台统一生成。
## 进件与开通
拉卡拉支持平台内进件,在进件工作台创建申请单后经服务商线路完成商户入驻,详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **先切环境再建商户**:沙箱与生产使用不同网关地址,各建一套;
- 支付宝收单场景需上送门店编号,创建通道商户时确认门店信息完整;
- 各底层渠道(微信/支付宝/银联)的收款权限随拉卡拉进件开通情况而定。
---
# 乐刷支付
**源**: https://doc.plus.daxpay.cn/extension/channels/leshua.md
# 乐刷支付
## 通道概述
乐刷科技旗下的聚合支付通道。DaxPay 以**服务商模式**对接乐刷(产品 `leshua_pay`),一次开通即可受理微信、支付宝、云闪付的扫码与端内收款。
## 支持的支付产品
| 支持产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `leshua_pay`(乐刷支付) | 服务商模式 | 服务商代旗下子商户收款 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 付款码、JSAPI(公众号)、小程序 |
| 支付宝 | 付款码、扫码、JSAPI |
| 银联(云闪付) | 付款码、扫码、JSAPI |
微信 JSAPI 与小程序支付需在平台微信应用配置中绑定 AppId。
## 配置结构
乐刷为**多服务商模型**:密钥按服务商维度配置,通道商户创建时选定归属:
1. **登记服务商并配置密钥**:运营端「支付和进件产品 → 通道服务商配置 → 乐刷服务商工作台」:
| 字段 | 说明 |
|------|------|
| 乐刷服务商编号 | 服务商资料登记,进件等接口场景必传 |
| 签名类型 | MD5 或 SM3 |
| 交易密钥 | 交易与进件接口的请求签名 |
| 异步通知密钥 | 回调验签用 |
2. **创建通道商户**:登记**乐刷商户号**(进件后获得),并选定归属服务商。
## 回调处理
异步通知由平台统一接收,凭异步通知密钥验签后处理并应答,回调地址由平台统一生成。
## 进件与开通
乐刷支持平台内进件,进件线包含微信与支付宝的授权绑定及费率配置,详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **先切环境再建商户**:沙箱与生产各建一套;
- 交易密钥与异步通知密钥是两个不同用途的密钥,均从乐刷服务商平台获取;
- 各底层渠道的收款权限随乐刷进件开通情况而定。
---
# 盛付通
**源**: https://doc.plus.daxpay.cn/extension/channels/sheng.md
# 盛付通
## 通道概述
盛付通旗下的聚合支付通道,支持微信、支付宝、银联的扫码、JSAPI、APP 及付款码收单,方式覆盖面在聚合通道中位居前列。DaxPay 提供**普通商户**(`sheng_pay`)与**服务商**(`sheng_isv`)两种接入产品。
## 支持的支付产品
| 支持产品 | 接入模式 | 状态 |
|---------|---------|------|
| `sheng_pay`(盛付通直连) | 商户直连 | 可用 |
| `sheng_isv`(盛付通服务商) | 服务商代子商户发起 | 规划中 |
## 支持的支付方式
直连产品支持的方式如下(服务商产品待规划落地后开放):
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 扫码、JSAPI(公众号)、小程序、APP、H5、付款码 |
| 支付宝 | 扫码、JSAPI、APP、H5、PC 网页、付款码 |
| 银联(云闪付) | 扫码、JSAPI、付款码 |
银联 H5 一期未接入,若在支付配置中勾选该能力,实际发起支付时会报「不支持」。
## 配置结构(普通商户模式)
密钥按**通道商户维度**配置:
1. **创建通道商户**:选盛付通直连产品,填写商户名称 + **盛付通商户号**;
2. **配置密钥**:运营端「支付和进件产品 → 盛付通直连工作台」维护:
| 字段 | 说明 |
|------|------|
| 盛付通商户号 | mchId |
| 盛付通应用 ID | 可选,直连场景建议填写 |
| 商户 RSA 私钥 | PKCS#8 Base64,签名用 |
| 盛付通公钥 | Base64,验签用 |
## 配置结构(服务商模式)
服务商模式当前按「规划中」展示,形态为**产品级全局密钥 + 子商户行级绑定**:服务商密钥(服务商商户号 + 服务商私钥 + 盛付通公钥)全局一份,创建通道商户时登记子商户号与应用 ID。
## 回调处理
- 请求签名:SHA1withRSA,商户/服务商私钥签名、盛付通公钥验签;
- 支付与退款均支持异步通知,由平台统一接收验签后处理。
## 进件与开通
平台内盛付通进件线暂未开通,盛付通商户号需在盛付通侧完成开通后登记。各通道进件能力差异见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- 盛付通**不提供沙箱/集测环境**,只有生产网关,配置后直接小额验证;
- 服务商模式落地后多个子商户共用一套密钥,无需逐户录入。
---
# 银联商务
**源**: https://doc.plus.daxpay.cn/extension/channels/ums.md
# 银联商务
## 通道概述
银联商务（UMS）是中国银联旗下综合支付服务机构。DaxPay 对接银联商务**直连**模式（通道 `ums_pay`），一次进件即可受理微信、支付宝、云闪付等多渠道收款，**无证书签名**，配置相对简单。
> 银联商务（UMS）与[银联支付](https://doc.plus.daxpay.cn/extension/channels/union.md)（云闪付，通道 `union_pay`）是两条相互独立的通道，区别详见[银联支付 - 与银联商务的区别](https://doc.plus.daxpay.cn/extension/channels/union.md#与银联商务的区别)。
## 支持的支付产品
银联商务按**收款场景**拆分为 6 个支付产品，创建通道商户时按场景选择：
| 支付产品 | 场景 | 受理的支付方式 |
|---------|------|--------------|
| `ums_qrcode`（C扫B） | 用户扫商户二维码 | 聚合扫码、微信扫码、支付宝扫码、银联扫码 |
| `ums_barcode`（B扫C） | 商户扫用户付款码 | 银联付款码 |
| `ums_h5`（H5） | 手机浏览器支付 | 微信 H5、支付宝 H5、银联 H5 |
| `ums_jsapi`（公众号） | 微信 / 支付宝端内 | 微信 JSAPI、支付宝 JSAPI |
| `ums_mini`（小程序） | 小程序内支付 | 微信小程序、支付宝 JSAPI |
| `ums_app`（APP） | 商户 APP 内 | 微信 APP、支付宝 APP |
## 支持的支付方式
通过上表产品受理微信 / 支付宝 / 银联三渠道的扫码、H5、付款码与端内方式；一码多渠道场景选 `ums_qrcode` 即可覆盖主流收款。
## 配置结构
1. **创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选场景产品后填写商户名称 + **银联商务商户号**（mid）；
2. **配置密钥**：通道商户详情 → 密钥配置：
| 字段 | 说明 |
|------|------|
| 环境 | 生产 / 沙箱 |
| 终端号 | tid，服务商分配 |
| 应用 ID | 银联商务开放平台的应用标识 |
| 应用 Key / Secret Key | 接口请求签名与异步通知验签用（HmacSHA256） |
## 回调处理
- 支持支付与退款的异步通知，平台验签后按结果应答；
- 回调地址由平台统一生成，无需在银联商务平台逐商户配置。
## 进件与开通
银联商务走**平台商户进网**特殊线，不在标准在线进件流程内：由平台在银联商务侧完成进网拿到商户号后，回填创建通道商户。详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- 无需证书，应用 Key / Secret Key 即可完成全部对接；
- 银行卡、网关等收银方式需向银联商务单独申请开通；
- 微信 / 支付宝 JSAPI 场景需先在对应平台完成应用配置。
---
# 银联支付
**源**: https://doc.plus.daxpay.cn/extension/channels/union.md
# 银联支付
## 通道概述
银联支付（即云闪付）是中国银联旗下的全渠道支付服务，通过银联全渠道支付平台（95516.com）网关直连 ACP 对接。DaxPay 支持银联网关直连模式，覆盖扫码、H5、付款码等主流收单场景。它与[银联商务](https://doc.plus.daxpay.cn/extension/channels/ums.md)（UMS）是**两条相互独立的通道**，区别详见文末[与银联商务的区别](#与银联商务的区别)。
## 支持的支付产品
单一产品 `union_pay`，创建通道商户时无需在多个产品间选择，沙箱与生产环境由支付产品配置决定。
## 支持的支付方式
| 支付方式 | 说明 |
|---------|------|
| `union_qr`（银联扫码，主扫） | 返回二维码链接，用户用云闪付 App 扫码支付 |
| `union_h5`（银联 H5） | 在手机浏览器中通过前台表单跳转完成支付 |
| `union_barcode`（银联付款码，被扫） | 商户扫描用户云闪付付款码 |
`union_jsapi`（银联 JSAPI）在银联网关直连通道**仅枚举定义、暂未实现**；公众号 / 小程序内的银联支付可经聚合通道（如 Adapay、拉卡拉等）承担。
## 配置结构
1. **创建通道商户**：商户工作台 → 通道商户 → 创建通道商户，选银联产品后填写商户名称 + **银联商户号**（merId）；
2. **配置密钥**：通道商户详情 → 密钥配置：
| 字段 | 说明 |
|------|------|
| PKCS12 私钥证书（`.pfx`）及证书密码 | 请求签名用 |
| 中级证书 / 根证书 | 银联 ACP 平台证书，验签链用 |
银联网关采用 **RSA2 证书签名**（`signMethod=01`，SHA256withRSA），报文为 `application/x-www-form-urlencoded` 格式（非 JSON），三证书缺一不可。
## 回调处理
- 支持同步返回与异步通知，异步通知为 `form-urlencoded` 参数，用银联公钥证书验签；验签通过后取 `queryId` 作为通道订单号，退款回调以 `origQryId` 关联原交易；
- 需在银联商户平台配置回调地址，且回调地址须可外网访问。
## 进件与开通
银联支付暂不支持平台在线进件：商户号与证书需自行向银联申请，拿到后手动创建通道商户并配置密钥。
## 注意事项
- 网关地址：沙箱 `test.95516.com` / 生产 `95516.com`；私钥证书需妥善保管并定期更新，证书过期会导致签名失败；
- 付款码被扫按 `authCode` 前缀（银联 `62`）识别后映射为 `union_barcode` 再路由；
- 部分功能需单独向银联申请开通。
## 与银联商务的区别
银联支付（云闪付）与[银联商务](https://doc.plus.daxpay.cn/extension/channels/ums.md)（UMS）常被混淆，但两者是**完全不同的通道**：
| 维度 | 银联支付（云闪付） | [银联商务](https://doc.plus.daxpay.cn/extension/channels/ums.md)（UMS） |
|------|---------------|------------------------------|
| 通道编码 | `union_pay` | `ums_pay` |
| 对接主体 | 中国银联全渠道支付平台（95516.com） | 银联商务有限公司开放平台 |
| 签名方式 | RSA2 证书签名（PKCS12 私钥 + 中级 / 根证书） | HmacSHA256 无证书 |
| 报文格式 | `form-urlencoded` | JSON |
| 产品数量 | 单产品，3 种支付方式 | 6 个产品（C扫B / 公众号 / APP / 小程序 / H5 / B扫C） |
- 接入**银联支付（云闪付）**：直接对接中国银联网关，适合需要云闪付原生扫码 / 付款码的场景；
- 接入**银联商务（UMS）**：通过银联商务收单，一次进件受理微信 / 支付宝 / 云闪付等多渠道，银行卡等收银方式更全。
---
# 随行付
**源**: https://doc.plus.daxpay.cn/extension/channels/vbill.md
# 随行付
## 通道概述
随行付旗下的聚合支付通道(天阙开放平台)。DaxPay 以**服务商模式**对接(产品 `vbill_pay`),覆盖统一下单、扫码、付款码与小程序收银台场景,是聚合通道中唯一支持**微信小程序收银台**方式的通道。
## 支持的支付产品
| 支持产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `vbill_pay`(随行付) | 服务商模式 | 服务商代旗下子商户收款 |
## 支持的支付方式
| 底层渠道 | 支持的支付方式 |
|---------|--------------|
| 微信 | 付款码、扫码、JSAPI(公众号)、小程序、**小程序收银台** |
| 支付宝 | 付款码、扫码、JSAPI |
| 银联(云闪付) | 付款码、扫码、JSAPI |
微信 JSAPI 与小程序支付需在平台微信应用配置中绑定 AppId。
## 配置结构
随行付为**多服务商模型**:密钥按服务商维度配置,通道商户创建时选定归属:
1. **登记服务商并配置密钥**:运营端「支付和进件产品 → 通道服务商配置 → 随行付服务商工作台」:
| 字段 | 说明 |
|------|------|
| 天阙机构 ID | 服务商资料登记,随行付分配的合作机构标识(orgId) |
| 商户 RSA 私钥 | Base64(PKCS#8),签名用 |
| 天阙 RSA 公钥 | Base64(X509),验签用 |
2. **创建通道商户**:登记**天阙商户号**(mno,进件后获得),并选定归属服务商。
## 回调处理
异步通知由平台统一接收,以天阙公钥完成 SHA1withRSA 验签后凭订单号反查并处理,回调地址由平台统一生成。
## 进件与开通
随行付支持平台内进件,进件线包含微信绑定、支付宝授权、协议签约与费率配置,详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **先切环境再建商户**:沙箱与生产各建一套;
- 密钥为 Base64 字符串(非 PEM 格式),从天阙开放平台获取;
- 微信小程序收银台方式需收银台小程序与微信应用配置就绪后启用。
---
# 微信支付
**源**: https://doc.plus.daxpay.cn/extension/channels/wechat.md
# 微信支付
## 通道概述
微信支付是腾讯微信平台的支付服务。DaxPay 采用 **API v3 证书模式**对接，支持**直连**与**服务商（ISV）**两种接入模式，方式覆盖 JSAPI、小程序、扫码、APP、H5 与付款码，并支持分账接收方绑定。
> 微信支付（直连）从通道侧准备到密钥配置的**完整对接教程**（含两组必填凭据、支付应用类型矩阵）见[支付通道对接](https://doc.plus.daxpay.cn/operation-guide/setup/channel-integration.md)，本文是参数与结构的速查参考。
## 支持的支付产品
| 支付产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `wechat_pay`（直连） | 商户直连 | 有自己微信支付商户号的商户 |
| `wechat_isv`（服务商） | 服务商代特约商户发起 | 服务商帮旗下二级商户收款；此模式下**平台即服务商**，无需服务商号 |
## 支持的支付方式
| 支付方式 | 说明 | 前提 |
|---------|------|------|
| `wechat_qr`（扫码） | Native 支付，返回二维码 | — |
| `wechat_jsapi`（JSAPI） | 微信内网页调起支付 | 需 openId；须绑定**公众号**应用 |
| `wechat_mini`（小程序） | 微信小程序内调起支付 | 需 openId；须绑定**小程序**应用 |
| `wechat_app`（APP） | 商户 APP 内调起微信 | — |
| `wechat_h5`（H5） | 手机浏览器外部跳转支付 | — |
| `wechat_barcode`（付款码） | 商户扫用户付款码 | — |
JSAPI 与小程序支付依赖 openId，需要先在[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)登记对应类型的微信应用（公众号 / 小程序），并在能力绑定中关联。
## 配置结构
- **直连**的密钥**按通道商户维度**配置：创建通道商户时填商户名称 + **微信支付商户号**（mchId），再在通道商户详情 → 基础管理 → 密钥配置中维护；
- **服务商**的密钥在**服务商工作台**「支付密钥」中维护，一份管全部特约商户；创建通道商户时填商户名称 + **特约商户号**（subMchId）。
| 分组 | 字段 | 说明 |
|------|------|------|
| 接口密钥 | API v3 密钥 | 商户平台「API 安全」中设置 |
| 支付证书 | 商户 API 证书 | `apiclient_cert`，上传 |
| | 商户 API 证书私钥 | `apiclient_key`，上传 |
| | 证书序列号 | 与上传证书对应 |
| | 支付公钥 / 支付公钥 ID | 微信支付公钥新模式；留空则走平台证书模式 |
**登记应用**（「支付应用」页面，平台应用 / 商户应用两组）：应用名称、应用类型（**公众号 / 小程序 / 移动应用**）、AppId、应用密钥（AppSecret），再在能力绑定中为各支付方式指定所用应用。
## 回调处理
- 异步通知为加密报文，平台验签（回调头 `Wechatpay-Serial` / `Wechatpay-Signature` 等）并解密后应答 `{"code":"SUCCESS"}`；
- 回调地址由平台统一生成，无需在微信商户平台逐单配置；
- 5 秒内未收到应答微信会按频次重试。
## 进件与开通
微信走**子商户特约商户进件线**（A 型）：平台以服务商身份提交特约商户进件申请，商家在微信内完成签约确认，审核通过后自动生成通道商户绑定。详见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- **先切环境再建商户**：沙箱与生产各建一套；
- 商户 API 证书有有效期，到期前在微信商户平台更换后同步更新配置；
- 服务商模式下「特约商户号」与「服务商商户号」是两个号，密钥配置用服务商侧一份；
- 服务商子商户号相关问题见 [FAQ](https://doc.plus.daxpay.cn/getting-started/faq/wechat-isv-sub-mch-id.md)。
---
# 易宝支付
**源**: https://doc.plus.daxpay.cn/extension/channels/yeepay.md
# 易宝支付
## 通道概述
易宝支付旗下的聚合支付通道(YOP 开放平台)。DaxPay 以**服务商模式**对接(产品 `yee_isv`),特色是**聚合扫码**——不指定底层渠道返回通用二维码,用户扫码后自动识别微信、支付宝,也支持按渠道指定下单。
## 支持的支付产品
| 支持产品 | 接入模式 | 适用身份 |
|---------|---------|---------|
| `yee_isv`(易宝支付) | 服务商模式 | 服务商代旗下子商户收款 |
## 支持的支付方式
| 类型 | 支持的支付方式 |
|------|--------------|
| 聚合 | 聚合扫码(通用二维码,自动识别渠道) |
| 微信 | 扫码、H5 |
| 支付宝 | 扫码、H5 |
| 银联(云闪付) | 扫码 |
## 配置结构
易宝为**多服务商模型**:密钥按服务商维度配置,且**沙箱与生产各一套**(按环境分开保存):
1. **登记服务商并配置密钥**:运营端「支付和进件产品 → 通道服务商配置 → 易宝服务商工作台」:
| 字段 | 说明 |
|------|------|
| 易宝服务商商编 | 服务商资料登记(parentMerchantNo) |
| 环境 | 生产 / 沙箱 |
| 通道应用 AppKey | YOP 平台的应用标识 |
| 服务商 RSA 私钥 | PEM 格式(PKCS#8),YOP SDK 签名用 |
| 易宝平台公钥 | 预留,当前验签走 SDK 内置平台证书 |
| 微信 AppId / AppSecret | 可选,微信 H5 场景用 |
2. **创建通道商户**:登记**易宝商户号**,并选定归属服务商(绑定关系不可更改)。
## 回调处理
请求签名与验签由 YOP SDK 自动完成(RSA2048 数字信封),异步通知由平台统一接收、解密验签后处理,无需手工处理报文。
## 进件与开通
平台内易宝进件线暂未开通,易宝商户号需在易宝侧完成开通后登记。各通道进件能力差异见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 注意事项
- 服务商商编与商户号的绑定关系录入前先与易宝确认;
- 微信 H5 场景需补充微信应用配置(AppId / AppSecret);
- 沙箱与生产的密钥分开配置,通道商户按创建时的环境快照取用对应密钥。
---
# 支付分账
**源**: https://doc.plus.daxpay.cn/common/alloc.md
# 支付分账
> 分账将一笔支付交易的资金按规则分给多个接收方(合伙人、加盟商、平台抽成等)。使用流程:先在通道商户上**绑定分账接收方**,支付成功后在支付交易上**发起分账**。
## 整体流程
```mermaid
graph LR
A[绑定分账接收方] --> B[支付交易成功]
B --> C[发起分账]
C --> D[分账订单处理]
D --> E[完成/部分完成]
```
## 第一步:绑定分账接收方
**入口**:运营端进入商户的**通道商户**管理页;商户端 商户中心 → 支付配置 → 通道商户 → 进入微信 / 支付宝 / 抖音通道商户的**管理**页 → **交易配置**分组 → **分账接收方**
分账接收方绑定在**通道商户**维度(不同通道的接收方账号体系不同),没有独立的顶级菜单。
**接收方类型**(按通道支持情况可选):
| 类型 | 说明 |
| --- | --- |
| 商户号(MERCHANT_ID) | 接收方为另一商户 |
| 个人 openid(PERSONAL_OPENID / PERSONAL_SUB_OPENID) | 微信个人收款 |
| 支付宝用户 ID(USER_ID) | 支付宝个人 |
| 登录名(LOGIN_NAME) | 支付宝登录账号 |
绑定方式支持**表单填写**与**扫码授权**两种:扫码授权会生成授权二维码,接收方扫码确认后自动回填账号,避免手抄账号出错。
## 第二步:发起分账
分账针对**支付成功**的交易发起,入口在支付交易列表:
1. 进入 交易管理(运营端)/ 交易订单(商户端)→ **支付交易**,找到资金状态为「成功」且分账状态为「无」的交易;
2. 操作列「更多 → **发起分账**」;
3. 在抽屉中添加接收方:顶部「**从已绑定接收方快捷填入**」可直接选通道侧已绑定成功的接收方(自动填入类型与账号,免手抄;通道侧暂无绑定档案时不显示该项),也可逐行手工填写**接收方类型、账号**(个人 openid 类型还需填姓名);
4. 为每个接收方填写**分账金额**,金额合计校验通过后二次确认提交。
也可以由业务系统调用 `POST /unipay/alloc` 发起,对接说明见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)。
分账比例上限由**通道侧**控制(如微信默认为交易金额的 30%,超出会被通道拒绝;平台不做比例校验);分账金额本身受交易可分余额约束。
## 第三步:分账订单查询
**入口**:运营端 交易管理 → **分账订单**;商户端 交易订单 → **分账订单**
**查询条件**:平台分账号、商户分账号、原支付交易号、分账状态、创建时间。
**列表列**:分账号、商户分账号、交易号、金额、状态、商户、创建时间。
**操作**:查看(详情含**分账明细**:每个接收方的类型、账号、金额、处理结果与完成时间)、同步(拉取通道侧最新结果)。
**分账状态**:
| 状态 | 说明 |
| --- | --- |
| 处理中(processing) | 通道处理中 |
| 成功(success) | 全部接收方分账完成 |
| 部分完成(partial) | 部分接收方成功、部分失败 |
| 失败(fail) | 分账失败 |
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 发起分账时找不到「从已绑定接收方快捷填入」 | 通道侧暂无绑定成功的接收方档案,先到通道商户管理页完成绑定 |
| 分账被通道拒绝 | 优先核对是否超出通道侧分账比例上限(如微信默认 30%),与平台侧校验无关 |
| 分账订单长时间「处理中」 | 通道回调未到达,对该分账单执行「同步」拉取最新结果 |
## 相关链接
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md):支付交易层的其他操作
- [商户端 · 通道商户](https://doc.plus.daxpay.cn/operation-guide/merchant/channel-merchant.md):分账接收方绑定的页面操作
- [可选功能上线](https://doc.plus.daxpay.cn/operation-guide/production/optional-features.md):分账作为可选能力的开通主线
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md):API 发起分账的对接说明
---
# 网关支付
**源**: https://doc.plus.daxpay.cn/common/gateway-payment.md
# 网关支付
> 网关支付是平台提供的**托管收款页**能力：商户只需调用网关预下单接口拿到一个链接或二维码，用户打开后由平台的页面完成支付方式选择与收款。两种形态：**统一收银台**（用户在落地页上选支付方式）与**聚合扫码**（一码多付，按扫码环境自动识别）。
## 两种形态
| 形态 | 网关支付类型 | 适用场景 |
| --- | --- | --- |
| 统一收银台 | `cashier` | PC / H5 收银台，用户在落地页选择支付方式（微信、支付宝等） |
| 聚合扫码 | `aggregate` | 印在物料上的静态二维码，微信 / 支付宝 / 云闪付 / 抖音扫同一个码，自动识别环境跳转对应支付 |
两种形态都通过 `POST /unipay/gateway/pre-pay`（网关预下单接口）发起；码牌（见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)）生成的静态码同样走聚合扫码链路。
普通支付（`/unipay/pay`）由业务系统自己确定支付方式并处理各环境的跳转；网关支付把「选方式、适配环境」这件事交给平台的托管页，业务系统只需管理一个链接。开发调试可用「支付调试(网关)」页模拟。
## 配置入口
**菜单路径**：商户端 → 商户中心 → 支付配置 → 应用管理 → 进入应用工作台 → **网关支付配置**（运营端在商户工作台的应用配置内，同一功能）
网关支付配置是**应用级**的（每个应用独立配置），商户端操作的详细页面说明见[应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)。
## 配置模型
### 配置层级
| 层级 | 说明 |
| --- | --- |
| 跟随自动（auto） | 最省心：按用户打开页面的环境与形态（H5 / 小程序）自动选择支付方式，再走应用的通道路由解析通道商户 |
| 指定支付方式（method） | 按打开环境逐格指定支付方式（如微信环境用 `wechat_mini`），通道商户仍跟随应用路由 |
**建议从自动档开始**，遇到默认推导不满足需求（如某环境要走指定支付方式）再逐格调整。
### 环境 × 形态矩阵
配置以矩阵形式呈现：**4 个打开环境**（微信 / 支付宝 / 云闪付 / 抖音——由扫码或浏览器的 UA 决定）× **2 种形态**（H5 / 小程序）。自动档下系统按环境给出默认支付方式（如微信 H5 用 `wechat_jsapi`、微信小程序用 `wechat_mini`）；某环境两种形态默认值相同时合并为一行展示。
### 路由命中预览
配置区提供**路由命中预览**：逐格展示当前配置会命中的通道商户与支付能力、路由覆盖情况（已配置数 / 缺口），配置不完整一目了然。预览与「通道路由」页同源，缺口可跳转[通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)补配。
## 收银台配置
统一收银台落地页的**展示内容**在「应用工作台 → 收银台配置」中自定义，与上面的通道路由配置相互独立：
- 按终端分桶配置：**H5**（按打开环境细分浏览器 / 微信 / 支付宝 / 云闪付 / 抖音五档）、**Web**（扁平列表）、**小程序**（微信 / 支付宝 / 云闪付 / 抖音四档）；
- 每个桶内配置支付项的展示与解析模式（按支付方式 / 直接指定通道商户）。
### 收银台小程序：三平台 × 平台档/商户档
小程序形态的落地页是**收银台小程序**，在微信 / 支付宝 / 抖音三平台各部署一套。配置分两档：
| 档位 | 说明 |
| --- | --- |
| 平台收银台 | 平台统一的公共小程序，商户无需自建即可使用 |
| 商户收银台 | 商户在三平台自有小程序的覆盖配置（appid、密钥等），商户级码牌靠它拉起商户自己的小程序 |
H5 收银台与小程序收银台的关系、以及收银台各页面的收款流程，见[收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md)与[小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md)；收银台小程序的配置操作见[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)。
## 完整接入流程
1. （可选）应用工作台 → 网关支付配置：确认配置层级，按需调整环境 × 形态矩阵；
2. （可选）收银台配置：调整落地页展示；
3. 业务系统调用网关预下单接口（`POST /unipay/gateway/pre-pay`），或直接使用**码牌**承载聚合扫码链接；
4. 用「开发者调试 → 支付调试(网关)」验证：选择网关支付类型提交后，返回**网关落地页 URL**（H5，可扫码或直接打开）与小程序映射链接，检查实际支付链路。
网关支付与普通支付共用同一条交易链路，平台的四层风控防线（IP 黑名单 / 用户标识 / 省市地区 / 门店围栏）与交易限额对码牌、收银台扫码同样生效，见[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)。
## 常见问题
### 码牌扫码后提示路由未命中？
码牌收款依赖：码牌绑定了应用 + 该应用的网关支付配置与通道路由就绪。先在网关支付配置的**路由命中预览**里看缺口，再按缺口补配通道商户或调整路由。
### 小程序码牌扫出来是 H5 页面？
小程序码牌「小程序优先、未映射自动降级 H5」是固有行为：微信 / 支付宝后台未配置（或已失效）「扫普通链接二维码打开小程序」前缀规则时，自动降级到 H5 收银页，不影响收款、无需换牌。详见[支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)。
## 相关链接
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)：码牌批量生成与绑定
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)：网关订单查询
- [应用支付配置](https://doc.plus.daxpay.cn/operation-guide/merchant/pay-config.md)：商户端配置操作
- [通道路由](https://doc.plus.daxpay.cn/operation-guide/admin/pay-route.md)：路由配置与命中排查
- [支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)：收银台小程序三平台配置
- [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md)：收银台与聚合扫码的页面流程
---
# 回调与通知
**源**: https://doc.plus.daxpay.cn/common/notify.md
# 回调与通知
> 回调链路分两段:**通道 → 平台**(通道回调记录)与**平台 → 商户**(商户回调推送)。排查「商户没收到通知」类问题时,先看通道回调是否到达,再看商户推送是否成功。
## 链路总览
```mermaid
graph LR
A[支付通道] -- 通道回调 --> B[DaxPay 平台]
B -- 商户回调推送 --> C[商户业务系统]
```
- **通道回调记录**:平台收到通道(支付宝、微信等)通知的原始记录,只读;
- **商户回调推送**:平台把订单结果以 HTTP POST 推送到商户配置的回调地址,失败可**重发**。
## 商户回调推送
**入口**:回调通知(顶级菜单)→ **商户回调推送**(运营端与商户端菜单结构一致)
**查询条件**:业务单号、事件、报文格式、商户(运营端)。
**列表列**:业务单号(可点开详情)、事件、报文格式、来源(订单 / 应用 / 协议)、是否成功、发送次数、商户、最近发送时间。
**操作**:
| 操作 | 说明 |
| --- | --- |
| 发送记录 | 抽屉展示该通知任务的每次发送明细:序号、发送类型(自动 / 手动)、是否成功、HTTP 状态码、错误信息、创建时间 |
| 重发 | 手动重新推送该通知(回调地址暂时不可用、商户侧处理异常后补推等场景) |
**任务详情**:通知 URL、下次发送时间、重试次数、完整报文内容(JSON)。
通知推送失败后系统会按策略自动重试(发送次数与下次时间在任务详情中可见);持续失败的任务在修复回调地址后可手动「重发」。
## 通道回调记录
**入口**:回调通知 → **通道回调记录**(两端入口一致)
**查询条件**:通道商户、交易号、通道交易号、支付产品、回调类型(支付 / 退款 / 分账等)、处理状态、商户。
**操作**:仅「查看」——详情展示通道通知的原始报文(JSON),用于核对通道侧的返回内容。原始报文**仅运营端可见**,商户端只展示回调受理状态(需要报文时联系平台获取)。
## 回调地址配置
商户接收回调的地址由业务系统在**发起支付时**通过 `notifyUrl` 参数指定;报文格式、签名与应答要求的对接细节见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md)的回调联调一节。
应用级的统一通知订阅(按应用配置回调地址、订阅支付 / 退款事件)在商户端应用工作台的「通知配置」中维护。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 商户没收到回调 | 按顺序排查:①「通道回调记录」确认通道通知到达且处理成功;②「商户回调推送」看推送任务是否成功、HTTP 状态码多少;③核对发起支付时传入的 `notifyUrl` 是否公网可达 |
| 回调收到了但验签失败 | 用平台公钥(商户端「对接配置」中复制,见[对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md))验证签名,报文口径见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md) |
| 推送一直失败 | 检查回调地址服务状态,修复后对任务执行「重发」 |
| 本地联调收不到回调 | 本地环境回调地址不可达,参考[本地联调](https://doc.plus.daxpay.cn/deployment/debug.md)的回调穿透方案 |
## 相关链接
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md):回调联调、验签与 SDK 选型
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md):平台公钥的获取(商户对接配置一节)
- [商户端 · 对接配置](https://doc.plus.daxpay.cn/operation-guide/merchant/credential.md):三件凭证与平台公钥
- [商户端 · 回调通知](https://doc.plus.daxpay.cn/operation-guide/merchant/callback.md):商户视角的通知页面
- [本地联调](https://doc.plus.daxpay.cn/deployment/debug.md):回调穿透方案
---
# 业务功能总览
**源**: https://doc.plus.daxpay.cn/common/overview.md
# 业务功能总览
> 本单元按**业务域**讲解系统的日常使用,每个功能同时给出运营端与商户端的操作入口;「操作指南」章节则按**端**组织各端整体功能,两者互为补充。
>
> 如果系统刚部署完成,建议先阅读[从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)完成上线配置,再回到本单元查阅各业务域的日常操作。
## 订单与资金
支付体系分为**业务订单**(普通订单 / 网关订单)与**资金交易**(支付交易)两层,退款、分账等资金操作都在支付交易层发起。
| 功能 | 入口 | 说明 |
| --- | --- | --- |
| [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md) | 运营端 交易管理 → 支付订单;商户端 交易订单 → 支付订单 | 普通订单、网关订单、支付交易三层查询与操作 |
| [退款管理](https://doc.plus.daxpay.cn/common/refund.md) | 运营端 交易管理 → 退款订单;商户端 交易订单 → 退款订单 | 界面与 API 发起退款、退款状态流转、超期处理 |
| [预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md) | 运营端 交易管理 → 预授权支付;商户端 交易订单 → 预授权订单 / 支付分订单 | 支付宝预授权冻结请款、微信支付分先享后付(plus 独有实装) |
| [支付分账](https://doc.plus.daxpay.cn/common/alloc.md) | 运营端 交易管理 → 分账订单;商户端 交易订单 → 分账订单 | 分账接收方绑定、发起分账、分账结果查询 |
| [收款单](https://doc.plus.daxpay.cn/common/receivable-bill.md) | 商户端 交易订单 → 收款单 | 商户开单远程催款,一单一付(plus) |
| [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md) | 运营端 交易管理 → 交易费用明细 | 按费率快照记录的每笔交易手续费明细(plus) |
## 核查与通知
| 功能 | 入口 | 说明 |
| --- | --- | --- |
| [回调与通知](https://doc.plus.daxpay.cn/common/notify.md) | 回调通知(顶级菜单,两端同名) | 商户回调推送(重发)、通道回调记录查询 |
| [异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md) | 运营端 交易管理;商户端 交易订单 → 异常订单 / 资金流水 | 异常收款核查处理、收款退款流水与导出 |
| 支付接口日志(见[异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md#支付接口日志)) | 运营端 系统管理 → 日志管理 → 支付接口日志 | 商户经开放接口调用的审计记录(请求 ID、耗时、接入 IP、错误信息) |
## 收款场景
| 功能 | 入口 | 说明 |
| --- | --- | --- |
| [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md) | 应用工作台 → 网关支付配置 | 统一收银台与聚合扫码(一码多付)两种形态 |
| [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md) | 运营端 支付管理 → 码牌管理;商户端 设备管理 → 码牌管理 / 系统终端 | 平台批量制牌、商户认领绑定、系统终端管理 |
## 常用排查路径
日常运营中最常见的几类问题,按下面的路径快速定位到对应页面:
| 问题 | 排查路径 |
| --- | --- |
| 订单一直停在「支付中 / 处理中」 | 先对交易执行「同步」;仍无结果按[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)排查回调是否到达 |
| 商户说没收到支付结果通知 | 「商户回调推送」看任务状态与 HTTP 状态码,再核 `notifyUrl` 可达性 |
| 关单后用户又付了钱 | [异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md)的异常订单核查与处置 |
| 金额对不上 / 需要对账 | 「资金流水」导出核对;通道侧对账单见[对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md) |
| 接口调用报错 | 「支付接口日志」按请求 ID 查错误信息与耗时 |
## plus 增强域
以上是交易与收款主链路。plus 在主链路之外提供一组商业增强能力,按域分列在本单元后续侧栏分组中,主链路页面涉及相关能力时会交叉引用:
- **代理商体系**:[代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)、[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md);
- **商户进件**:[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md);
- **风控与限额**:[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)、[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/.md);
- **费率体系**:[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)、[费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)。
## 约定
- 各功能页面的操作权限与菜单可见性由角色授权决定,文中所述按钮在无权限时不会显示;
- 文中「菜单路径」若未特别说明,同时适用于运营端与商户端;交易一级菜单两端命名略有差异(运营端为「交易管理」,商户端为「交易订单」),以实际系统为准;
- 运营端比商户端多出「商户」「应用」筛选维度(跨商户视角),其余功能两端一致;
- 本章覆盖交易与收款主链路;「易支付插件」等协议兼容类功能见[操作指南 · 易支付插件](https://doc.plus.daxpay.cn/operation-guide/admin/easypay.md)。
## 相关链接
- [从部署到第一笔支付](https://doc.plus.daxpay.cn/operation-guide/setup/overview.md)
- [交易状态字典](https://doc.plus.daxpay.cn/getting-started/codes/trade-status.md)
- [业务术语表](https://doc.plus.daxpay.cn/getting-started/glossary.md)
---
# 支付订单管理
**源**: https://doc.plus.daxpay.cn/common/payment-order.md
# 支付订单管理
> 系统的支付体系分为两层:**业务订单**承载商户发起的支付请求(普通订单与网关订单两种形态),**支付交易**承载实际资金流转(退款、分账等资金操作都在这一层发起)。理解这个分层是查询和处理订单的基础。
## 三层订单模型
| 层 | 页面 | 承载内容 | 典型操作 |
| --- | --- | --- | --- |
| 业务订单 | 普通订单 | 商户通过 `/unipay/pay` 发起的支付单(扫码、JSAPI、H5 等) | 查看、关闭、导出 |
| 业务订单 | 网关订单 | 通过统一收银台 / 聚合扫码(`/unipay/gateway/pre-pay`)生成的支付单 | 查看、关闭、导出 |
| 资金交易 | 支付交易 | 与通道实际发生资金往来的交易记录,一个业务订单可能对应多笔 | 查看、退款、发起分账、同步、关闭 |
「普通订单」「网关订单」页面只有查看与关闭;**退款、发起分账**在「支付交易」页的操作列「更多」菜单中——因为退款分账针对的是资金,而不是业务单。
## 页面入口
| 端 | 菜单路径 |
| --- | --- |
| 运营端 | 交易管理 → 支付订单 → 普通支付 / 网关支付;交易管理 → 支付交易 |
| 商户端 | 交易订单 → 支付订单 → 普通订单 / 网关订单;交易订单 → 支付交易 |
两端页面结构一致,仅菜单命名略有差异(运营端叫「普通支付 / 网关支付」,商户端叫「普通订单 / 网关订单」)。运营端的查询条件比商户端多出「商户」「应用」筛选(跨商户视角),其余功能一致。
## 普通订单
**查询条件**:商户订单号、标题、商户(运营端)、应用、业务状态、支付产品、支付能力、创建时间、金额区间。
**列表列**:平台订单号、商户订单号、标题、金额、业务状态、支付产品、支付能力、商户、创建时间。
**操作**:
| 操作 | 条件 | 说明 |
| --- | --- | --- |
| 查看 | — | 打开详情抽屉 |
| 关闭 | 待支付 | 手动关闭未支付订单(需订单管理权限) |
| 导出 | — | 右上角导出列表数据 |
**详情抽屉**包含:商户与订单标识(平台订单号 / 商户订单号 / 资金交易号)、业务状态与金额、支付产品 / 能力 / 通道 / 方式 / 通道商户号 / 通道订单号、资金状态、门店号、支付时间组、买家信息、**退款可退余额**、通知与回跳地址、错误信息。
## 网关订单
网关订单是经统一收银台或聚合扫码产生的业务订单,除了普通订单的查询维度外,还可以按**网关类型**(统一收银台 / 聚合扫码)筛选,业务状态包含「支付中」。
操作与普通订单一致(查看、关闭、导出),其中**关闭条件为「待支付 / 支付中」**(网关订单支付中也可关闭);详情抽屉额外包含资金状态、可退余额、客户端 IP 等信息。
网关订单的产生与配置见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)。
## 支付交易
支付交易是资金层的记录:每笔成功支付对应一笔交易,记录通道、通道商户号、入账金额、可退余额与分账状态。plus 会按下单时的费率快照为成功交易计算手续费,记入[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)。
**查询条件**:资金交易号、通道订单号、商户、应用、资金状态(初始化 / 处理中 / 成功 / 失败 / 关闭 / 撤销)、交易形态(普通 / 网关)、分账状态(无 / 处理中 / 完成 / 不支持)、通道商户号、创建时间、金额区间。
**列表列**:交易号、交易形态、通道订单号、金额、入账金额、**可退余额**、资金状态、分账状态、支付通道、支付渠道、通道商户号、支付时间、商户、创建时间。
**操作**(操作列「更多」下拉,按状态动态显示):
| 操作 | 显示条件 | 说明 |
| --- | --- | --- |
| 订单明细 | — | 按业务订单号跳转到对应的普通订单 / 网关订单页 |
| 查看 | — | 详情抽屉 |
| 退款 | 资金状态=成功且有可退余额 | 发起退款,见[退款管理](https://doc.plus.daxpay.cn/common/refund.md) |
| 发起分账 | 资金状态=成功且分账状态=无 | 发起分账,见[支付分账](https://doc.plus.daxpay.cn/common/alloc.md) |
| 关闭 | 初始化 / 处理中 | 关闭未完成的交易 |
| 同步 | 非终态 | 向通道主动拉取最新状态 |
支付依赖通道回调推进状态。如果回调丢失(网络原因、地址不可达),订单会停留在中间态——对这笔交易执行「同步」,系统会主动查询通道并回填状态。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 普通订单 / 网关订单页找不到退款按钮 | 退款与发起分账都在「支付交易」页,业务订单层不承载资金操作 |
| 订单长时间停在「支付中 / 处理中」 | 通道回调可能丢失,对该交易执行「同步」;仍无结果时按[回调与通知](https://doc.plus.daxpay.cn/common/notify.md)的思路排查 |
| 业务系统没收到支付结果通知 | 先查「商户回调推送」任务是否成功,排查链路见[回调与通知](https://doc.plus.daxpay.cn/common/notify.md) |
## 相关链接
- [退款管理](https://doc.plus.daxpay.cn/common/refund.md)、[支付分账](https://doc.plus.daxpay.cn/common/alloc.md)、[预授权与支付分](https://doc.plus.daxpay.cn/common/preauth.md):资金侧操作详解
- [异常订单与资金流水](https://doc.plus.daxpay.cn/common/trade-records.md):关单后收款等异常场景的处理
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md):成功交易的手续费记账
- [运营端 · 支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md)、[商户端 · 交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md):两端页面操作细节
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md):下单接口的对接与联调
---
# 预授权与支付分
**源**: https://doc.plus.daxpay.cn/common/preauth.md
# 预授权与支付分
> 预授权与支付分解决的是**资金延后结转**场景:先冻结或先享受、后按实际金额结清,典型如酒店押金、租车、共享租借。两者在系统内是**相互独立的业务域**,订单模型与回调链路分开建模,入口也分列。本能力为 plus 独有实装,开源基础版未内置。
## 能力概览
| 能力 | 通道 | 结算模式 | 典型场景 |
| --- | --- | --- | --- |
| 支付宝预授权 | 支付宝 | 冻结 → 按实际金额请款,剩余额度解冻 | 酒店押金、租车、充电宝 |
| 微信支付分 | 微信支付 | 先享后付,服务完结后按实际金额结算 | 免押租借、先享后付 |
预授权面向**资金冻结**,支付分面向**信用履约**;开放接口前缀分别为 `/unipay/preauth` 与 `/unipay/payscore`,订单查询页面也分列为「支付宝预授权」与「微信支付分」。
## 支付宝预授权
### 业务流程
```mermaid
graph LR
A[授权冻结] --> B[请款 / 转支付]
A --> C[解冻]
A --> D[当日撤销]
B --> E[交易完成]
C --> F[资金退回买家]
```
### 开放接口
| 接口 | 说明 |
| --- | --- |
| `POST /unipay/preauth/create` | 预授权冻结下单,冻结买家资金 |
| `POST /unipay/preauth/capture` | 预授权请款(转支付),按实际金额扣款完成交易 |
| `POST /unipay/preauth/unfreeze` | 预授权解冻,释放冻结金额退回买家 |
| `POST /unipay/preauth/close` | 预授权撤销,冻结当日取消 |
| `POST /unipay/preauth/query` | 预授权状态查询(本地) |
| `POST /unipay/preauth/sync` | 预授权状态同步,查询通道并纠正本地状态 |
**各阶段说明**:
- **授权(create)**:冻结买家相应额度的资金,授权金额即本单最大可请款金额;
- **请款 / 转支付(capture)**:服务结束后按实际消费金额请款,资金真正扣款入账,剩余冻结额度随之释放;
- **解冻(unfreeze)**:对未请款的授权单释放冻结,资金退回买家;
- **撤销(close)**:冻结当日内直接取消授权单。
请款(转支付)完成后,暂不支持对该笔授权单再发起退款类操作。业务上需要在请款前完成资金安排,确有多收的走线下或通道侧流程处理。
### 落地页拉起授权
支付宝线上预授权通过收银台 H5 落地页拉起授权:下单后返回落地页地址(形如 `{收银台域名}/preauth/alipay/{预授权单号}`),买家在落地页完成授权,落地页轮询冻结状态并展示结果。
### 页面入口
| 端 | 菜单路径 |
| --- | --- |
| 运营端 | 交易管理 → 预授权支付 → 支付宝预授权 |
| 商户端 | 交易订单 → 预授权订单 |
订单页提供授权单的查询与详情(授权金额、冻结 / 请款进度、通道单号等);运营端比商户端多出跨商户筛选维度,其余一致。
## 微信支付分
微信支付分是**先享后付**的信用支付产品:用户先享受服务,商户在服务完结时按实际金额发起完结,微信侧异步完成扣款。plus 实装的是**需确认模式**——用户需先在微信侧确认服务开通,订单才继续推进;订单状态与回调链独立于普通支付与预授权域,采用双轨策略推进。
### 开放接口
| 接口 | 说明 |
| --- | --- |
| `POST /unipay/payscore/create` | 服务订单创建(需确认模式),等待用户确认 |
| `POST /unipay/payscore/cancel` | 服务订单取消,仅待确认状态可取消 |
| `POST /unipay/payscore/complete` | 支付分完结,按实际金额结算,微信侧异步扣款 |
| `POST /unipay/payscore/query` | 支付分状态查询(本地) |
| `POST /unipay/payscore/sync` | 支付分状态同步,查询通道并纠正本地状态 |
### 页面入口
| 端 | 菜单路径 |
| --- | --- |
| 运营端 | 交易管理 → 预授权支付 → 微信支付分 |
| 商户端 | 交易订单 → 支付分订单 |
## 开发调试
联调阶段可用「支付调试（预授权）」验证链路连通性与参数:运营端与商户端的「开发调试」菜单 → 支付调试（预授权）。签名不通过、参数组装有疑问时,优先用调试工具定位,再接入业务系统。
## 常见问题
| 问题 | 说明 |
| --- | --- |
| 预授权单可以转成普通支付交易吗 | 可以,「请款(转支付)」即把授权单按实际金额转为支付完成;反向不行 |
| 请款后发现多收了怎么办 | 请款后退款暂不支持,需在请款前核实金额;确有差错的走线下或通道侧流程 |
| 支付分订单一直停在待确认 | 用户未在微信侧完成确认;确认超时的订单可调用取消接口关闭后重新创建 |
| 预授权和支付分是同一套接口吗 | 不是,分别为 `/unipay/preauth/*` 与 `/unipay/payscore/*`,两个独立域 |
## 相关链接
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md):业务订单与支付交易的分层说明
- [运营端 · 支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md):运营端交易页操作
- [支付宝通道](https://doc.plus.daxpay.cn/extension/channels/alipay.md):支付宝直连与服务商接入配置
- [交易状态字典](https://doc.plus.daxpay.cn/getting-started/codes/trade-status.md):预授权 / 支付分相关状态枚举
- [开发者调试](https://doc.plus.daxpay.cn/operation-guide/admin/develop-tools.md):支付调试（预授权）入口说明
---
# 支付码牌与终端
**源**: https://doc.plus.daxpay.cn/common/qrcode.md
# 支付码牌与终端
> 码牌是承载**聚合扫码**收款链接的物理物料（桌牌、立牌、贴纸）。plus 采用「平台/代理商制牌并管理库存、商户绑定使用」的模式：码牌创建时即确定**程序类型**与**归属类别**两个模型属性，两者共同决定扫码链接形态与能否划拨。
## 两类模型
### 程序类型（programType）
| 类型 | 扫码链接 | 说明 |
| --- | --- | --- |
| H5 码牌 | `/h/{code}` | 扫码恒进入 H5 收银页，不参与任何小程序前缀映射 |
| 小程序码牌 | 平台级 `/m/{code}`、商户级 `/mx/{mchNo}/{code}` | 小程序优先：微信/支付宝后台配置了「扫普通链接二维码打开小程序」前缀规则则拉起小程序，未配置/失效时公开端点自动 302 降级到 H5 收银页，不影响收款、无需换牌 |
### 归属类别（ownerType）
| 类别 | 说明 |
| --- | --- |
| 平台级（库存牌） | 生来空白，链接无商户身份，**可自由划拨给商户、回收、再划拨**；小程序码牌默认拉起平台公共收银台小程序 |
| 商户级（定制牌） | **创建时锁定归属商户且不可划拨/解绑**，链接恒为 `/mx/{mchNo}/{code}`（中缀=商户号，永不变）；由商户自有小程序靠前缀规则拉起，规则未配置时同样 H5 兜底 |
H5 链接没有商户中缀，不存在「商户级 H5 牌」；创建商户级批次时程序类型自动锁定为小程序型。
## 码牌生命周期
```mermaid
graph LR
A[运营端批量制牌] --> B[平台库存（未划拨）]
B --> C[分拨给代理商]
B --> D[绑定商户]
C --> D
D --> E[商户认领/绑定应用与门店]
E --> F[投放使用（扫码收款）]
F --> G[解绑回收]
G --> B
D -->|商户级牌| H[固定归属
不支持划拨回收
退出流通走删除]
```
- 库存态码牌归属代理商为空时称**未划拨**（平台库存）；绑定商户后归属代理商始终跟随商户挂靠关系。
- 商户级牌创建即锁定归属，是生命周期之外的一条「直线」：只能使用或删除，不进入划拨流转。
## 运营端：码牌管理
**菜单路径**：设备管理 → 码牌管理（含**码牌模板**与**码牌台账**两个页面）
**批量创建**：选择归属类别（平台级 / 商户级，商户级须选定锁定商户并建议先完成其收银台小程序配置）、程序类型、金额类型（随机金额 / 固定金额）、批次号与数量，一次生成一批码牌。
**码牌台账操作**：
| 操作 | 说明 |
| --- | --- |
| 绑定商户 | 仅平台级牌；可一并指定应用与门店（均可空，空则支付时按商户默认解析） |
| 解绑商户 | 仅平台级牌；保留编码/批次/金额配置，回归属代理商库存（未划拨牌回平台库存），同步清空应用与门店 |
| 分拨代理商 / 收回 | 平台库存 ↔ 代理商库存之间调拨；绑定商户中的牌须先解绑 |
| 启用 / 停用 | 控制码牌是否可收款 |
| 删除 | 停用后可删除；商户级牌退出流通走删除 |
**解绑的三类拒绝**：
1. **未选择码牌**——直接拒绝，不做任何变更；
2. **勾选中含商户级牌**——整批拒绝：商户级码牌固定归属商户，不可解绑回收；
3. **所选均未绑定商户**——拒绝避免「假成功」；混合勾选时仅解绑已绑定的牌，未绑定者跳过，审计按实际解绑数记录。
## 商户端：认领与绑定
**菜单路径**：商户端 → 设备管理 → 码牌管理（模板在**我的码牌模板**）
商户端**不能创建码牌**（制牌是平台/代理商行为），核心动作是「认领」：
- **认领空白码**：输入平台发放的空白码编号，认领到本商户名下；归属校验——代理商库存牌仅同代理商名下商户可认领，未划拨的平台库存牌任何商户可认领，并发场景由条件更新兜底（仅一个认领生效）；
- 认领或被绑定后，通过「编辑」绑定**应用与门店**（决定收款走哪个应用的网关支付配置）、设置金额类型（随机金额让客户自填，固定金额锁定收款额）；
- 「启用 / 停用」控制投放状态；可查看二维码大图并**复制扫码链接**，转给制作方印制物料。
代理商端可在「商户管理 → 码牌管理」查看名下商户的码牌，见[订单查询与码牌](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md)。
## 码牌模板与打印
- **运营端**：设备管理 → 码牌管理 → **码牌模板**维护打印版式（内置版式 + 自定义版式；自定义版式上传 HTML 模板按占位符渲染），支持复制、设为默认、删除——默认模板是平台打印的兜底版式；**码牌台账**点编码打开预览抽屉，套用模板整牌预览并打印；
- **商户端**：设备管理 → **我的码牌模板**维护自有版式，用于自助印制。
## 扫码链路
用户扫码牌 → 打开聚合扫码落地页（环境自动识别）→ 按该码牌绑定应用的**网关支付配置**路由到通道商户。所以码牌收款依赖：码牌绑定了应用 + 该应用的网关支付配置就绪，详见[网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)。
## 终端管理
- **系统终端**（商户端 设备管理 → 系统终端；运营端在商户工作台）：商户的**逻辑终端编号**，用于需要终端报文的通道场景。系统终端（本系统逻辑用）与通道终端（通道侧登记的终端号）的关联由运营在通道终端报备时建立，一个系统终端在同一通道商户下按报送类型各对应一条通道终端，「绑定管理」仅查看；
- **云音箱 / 云打印**等 IoT 终端在运营端 设备管理 下统一管理（厂商配置与台账），见[云音箱云打印与终端](https://doc.plus.daxpay.cn/operation-guide/admin/iot-device.md)。
## 常见问题
### 商户级牌想换商户怎么办？
不支持。商户级码牌的链接中缀是商户号，划拨会导致已印物料指向错误商户，系统在绑定/解绑/分拨/收回处全部拦截。需要变更归属时只能废弃旧牌（删除）重新制牌。
### 小程序码牌没有配置前缀规则，印了会不会浪费？
不会。小程序码牌未映射时自动降级 H5 收银页收款；后续在微信/支付宝后台补配前缀规则即可拉起小程序，**存量牌无需重印**。商户级牌的前缀规则材料（前缀 URL `/mx/{mchNo}/`、校验文件）见[支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)。
### 认领时提示已被认领？
空白码认领是并发安全的：该码已被认领或已分配商户（含分配给自己）时按已被认领处理，请走运营端划拨渠道调整归属。
## 相关链接
- [网关支付](https://doc.plus.daxpay.cn/common/gateway-payment.md)：码牌背后的路由配置
- [码牌管理](https://doc.plus.daxpay.cn/operation-guide/admin/qrcode-device.md)：运营端台账与模板操作详解
- [支付设备与码牌](https://doc.plus.daxpay.cn/operation-guide/merchant/devices.md)：商户端操作详解
- [云音箱云打印与终端](https://doc.plus.daxpay.cn/operation-guide/admin/iot-device.md)：IoT 终端管理
- [支付应用](https://doc.plus.daxpay.cn/operation-guide/admin/pay-app.md)：收银台小程序与商户自有小程序配置
- [小程序使用与付款流程](https://doc.plus.daxpay.cn/operation-guide/cashier/mini-usage.md)：小程序码牌扫码后的付款流程
---
# 收款单
**源**: https://doc.plus.daxpay.cn/common/receivable-bill.md
# 收款单
> 收款单是商户发起的**单笔远程催款**凭证：商户先开一张「账单」，生成链接或二维码发给客户，客户点开付款。典型用户是餐饮、批发、微商等需要远程收款的小微商户。收款单本身不碰钱，只是一张「皮」——真正的支付走平台普通支付全链路（路由 / 风控 / 通道 / 回调 / 通知）。
## 与码牌的差异
| | 码牌 | 收款单 |
| --- | --- | --- |
| 谁创建 | 平台/代理商批量制牌 | 商户在界面临时开一张 |
| 生命周期 | 长期有效，一码多笔 | **一单一付，付完即关** |
| 典型场景 | 柜台摆着随便扫 | 微信里发给客户「这单 350，请付一下」 |
## 入口与单号
- **商户端入口**：交易订单 → **收款单**（列表 + 创建 + 分享 + 取消）；
- **单号形态**：收款单号（billNo）= `RBL` 前缀 + 雪花序号 + 随机因子，随机因子用于防枚举猜测——单号是链接公开暴露的唯一凭证；
- **支付地址**：H5 收银台地址 + `/b/{billNo}`（与码牌 `/h/{code}` 同范式），客户在微信 / 支付宝 / 云闪付 / 抖音环境内打开即进入对应支付页，PC 打开则展示扫码引导页。
## 开单配置
创建收款单时配置：
- **标题与备注**：标题展示在客户支付页；
- **金额类型**：固定金额，或客户自填（可设上下限）；
- **有效期**：到期后不可支付（默认 24 小时）；
- **表单字段**：按需配置收集项，支持 6 种字段类型——单行文本 / 多行文本 / 数字 / 手机号 / 下拉选择 / 日期。字段定义存为 JSON 结构，客户支付前由**服务端复核**（必填 / 类型 / 长度 / 选项合法性，前端校验只是体验）；提交数据随单落库，一单一份，重复发起支付时覆盖更新并在支付页回显，客户中途失败重开不必重填；
- **门店**（可选）：远程收款默认不挂门店，不触发门店围栏。
支付成功后，商户回调通知参数中会带上客户填写的表单数据，业务系统可直接取用（如学员姓名 + 年级 + 手机号），无需再查单补录。
## 状态机
```mermaid
graph LR
W[wait_pay 待支付] -->|支付成功回调| P[paid 已支付]
W -->|商户取消| C[canceled 已取消]
W -->|到期| E[expired 已过期]
```
- 三个终态不可逆；已支付后再次打开链接展示「已支付」结果页；
- **过期双管**：公开查单/发起支付时惰性判定（过期顺手置为已过期并拒绝支付），加定时任务批量扫描，保证列表展示准确；
- **资金安全**：客户支付在途而商户取消等极端并发下，状态回写失败会转**异常订单**人工处置，资金风险不静默吞掉。
## 防重复支付（关旧建新）
收款单名下任何时刻只有一笔**活跃支付订单**：客户每次发起支付前，系统先检查当前活跃订单，非终态则先走关单再建新单。客户在多个环境反复点开链接、或中途放弃后重新支付，都不会产生重复扣款。
## 支付链路与风控
收款单发起的支付走普通支付全链路（交易来源标记为收款单），因此：
- 平台**四层风控**（IP 黑名单 / 用户标识 / 省市地区 / 门店围栏）与**商户限额**对远程催款同样生效——远程收款恰是欺诈高发场景，风控白捡，详见[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)；
- 订单在各端「支付交易 / 订单查询」页天然可见，可与收款单详情互相关联；
- 支付成功后按应用配置推送商户回调通知。
## 常见问题
### 客户说付了，商户列表还是待支付？
支付成功回写依赖通道回调，偶发延迟可稍候或在订单查询页确认支付交易状态；确实回调丢失的，按异常订单流程处理，不要直接重开单。
### 收款单可以重复使用吗？
不可以，一单一付。金额或内容有变的催款需求，重新开一张新单即可，旧单到期自动关闭，无残留。
### 创建时没配表单，客户还能填备注吗？
表单字段是开单时配置的，未配置则客户只确认金额直接支付；需要收集信息请在创建收款单时配置表单字段。
## 相关链接
- [支付码牌与终端](https://doc.plus.daxpay.cn/common/qrcode.md)：长期有效的柜台收款形态
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)：收款单产生的交易订单查询
- [交易订单管理](https://doc.plus.daxpay.cn/operation-guide/merchant/orders.md)：商户端收款单页面入口
- [收款页面](https://doc.plus.daxpay.cn/operation-guide/cashier/cashier-page.md)：客户侧支付页流程
- [风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)：对远程收款生效的风控防线
---
# 退款管理
**源**: https://doc.plus.daxpay.cn/common/refund.md
# 退款管理
> 退款针对**支付交易**发起(不是业务订单),支持界面操作与 API 两种方式。退款金额受原交易的「可退余额」约束,支持多次部分退款;plus 另在商户限额体系中设有**退款日累计**兜底限额,防止批量退款异常搬钱。
## 入口
| 方式 | 入口 | 说明 |
| --- | --- | --- |
| 界面发起 | 支付交易列表 → 操作列「更多 → 退款」 | 运营端(交易管理 → 支付交易)与商户端(交易订单 → 支付交易)均可,运营端代发会携带商户号 |
| API 发起 | `POST /unipay/refund` | 业务系统调用,对接与联调说明见[业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md) |
| 退款单查询 | 运营端 交易管理 → 退款订单;商户端 交易订单 → 退款订单 | 两端均可查看退款单状态与明细 |
## 界面发起退款
在「支付交易」列表找到目标交易(资金状态为「成功」且可退余额大于 0),点击操作列「更多 → 退款」:
1. 系统先查询交易详情,回填资金交易号与**当前可退余额**;
2. 填写**退款金额**(弹窗已默认预填全部可退余额,改小即为部分退款;点「一键全额退款」可重新填满)与**退款原因**;
3. 二次确认后提交,生成退款单。
一笔支付交易可以多次部分退款,累计退款金额不能超过原交易金额;「可退余额」在每次退款成功后会相应扣减,在支付交易与退款单详情中都可查看。
## 退款状态流转
```mermaid
graph LR
A[退款中] --> B[成功]
A --> C[失败]
A --> D[已关闭]
```
| 状态 | 说明 |
| --- | --- |
| 退款中(progress) | 已提交通道处理,等待结果 |
| 成功(success) | 退款到账 |
| 失败(fail) | 通道拒绝或处理失败(余额不足、超过可退期限等) |
| 已关闭(close) | 退款单被关闭,不再处理 |
## 退款订单页
**查询条件**:退款单号、资金交易号、商户、应用、商户订单号、退款状态、交易类型(普通 / 网关)、支付产品、创建时间。
**列表列**:退款单号、交易号、商户订单号、金额、退款状态、交易类型、产品、商户、创建时间。
**操作**:
| 操作 | 条件 | 说明 |
| --- | --- | --- |
| 查看 | — | 详情抽屉(身份信息 / 关联资金 / 金额与状态 / 通道快照 / 通知与审计) |
| 同步 | 退款中 | 向通道拉取退款结果,回调丢失时使用 |
| 手动关闭 | 「退款中」且**超过 7 天** | 长期无结果的退款单人工关闭归档 |
| 导出 | — | 右上角导出 |
## 退款限额兜底(plus)
除「可退余额」外,商户限额体系为退款单独设置了**日累计限额**:当日退款总额超过该上限时,后续退款会被拦截,需次日再退或由平台调整限额。退款限额在限额配置矩阵中独立一格,配置与生效规则见[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/.md)。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 退款一直「退款中」 | 通道回调未到达,对该退款单执行「同步」;超过 7 天可手动关闭后重新发起 |
| 退款失败提示余额不足 | 原交易可能已被部分退款或通道侧结算变动,核对「可退余额」 |
| 提示超出退款日累计限额 | 当日退款总额已达限额上限,次日再发起;确需当日处理的,由运营端调整商户限额 |
| 订单页找不到退款按钮 | 退款入口在「支付交易」页而非「普通订单 / 网关订单」页 |
## 相关链接
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md):支付交易层的其他操作
- [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/.md):退款日累计兜底限额的配置口径
- [商户端 · 退款管理](https://doc.plus.daxpay.cn/operation-guide/merchant/refund.md):商户视角的快速上手
- [运营端 · 支付订单与退款](https://doc.plus.daxpay.cn/operation-guide/admin/orders.md):运营端跨商户视角操作
- [业务系统对接](https://doc.plus.daxpay.cn/operation-guide/setup/integration.md):API 发起退款的对接说明
---
# 交易费用明细
**源**: https://doc.plus.daxpay.cn/common/trade-fee.md
# 交易费用明细
> 交易费用明细是平台侧的**费用记账**：每笔支付交易成功后，按交易发生时点解析到的**费率快照**计算手续费并落一条明细；退款对应生成负数冲减明细。它与通道侧实际结算费率脱钩，回答的是「这笔交易按平台费率体系该收多少、记给谁」。
## 记账规则
- **异步计算**：支付成功后异步落明细，不阻塞支付链路；退款成功后按原支付的费率快照生成**负数金额**的冲减明细（关联退款单号）；
- **快照锁定**：商户费率在交易时点解析并锁定，之后调整费率配置不影响已生成的明细——保证历史账目可复核；
- **归属快照**：明细记录交易时点的商户号、代理商号（随商户归属）、应用号与通道 / 产品 / 支付方式 / 支付能力，代理商归属调拨不回溯已落明细；
- **当前记账口径**：商户手续费全额记为平台收入；服务商、代理商维度字段为预留扩展位，当前不参与记账。
## 入口与页面
**菜单路径**：运营端 → 交易管理 → **交易费用明细**
- **查询条件**：商户号、代理商号、业务类型（支付 / 退款）、费率来源、创建时间范围；
- **列表与详情**：明细行字段完整，点开详情抽屉查看全部口径；退款明细的金额与手续费为负数，原样展示。
## 字段口径
| 字段 | 说明 |
| --- | --- |
| 交易金额 | 退款明细为负 |
| 商户费率 | 交易时点解析并锁定的费率快照；退款明细复制原支付快照 |
| 商户手续费 | 按快照计算、向商户收取的费用；退款为负，未配置费率时为空 |
| 平台收入 | 当前口径 = 商户手续费全额 |
| 费率来源 | 该笔费率是从费率链的哪一层解析到的（见下） |
| 归属 | 商户号 / 代理商号（交易时点）/ 应用号 / 通道 / 产品 / 支付方式 / 支付能力 |
## 费率来源
费率来源标明快照取自费率解析链的哪一层，解析优先级为**服务商产品能力 > 服务商方式默认 > 平台产品能力 > 平台方式默认**：
| 来源 | 含义 |
| --- | --- |
| 服务商产品能力 | 服务商对特定支付能力（如微信 JSAPI）的覆盖定价 |
| 服务商方式默认 | 服务商对支付方式维度的默认定价 |
| 平台产品能力 | 平台对特定支付能力的定价 |
| 平台方式默认 | 平台对支付方式的默认定价 |
| 未配置 | 费率链上无可用配置，手续费为空——补配后可重算 |
| 形态不计费 | 该交易形态不参与计费 |
费率链的完整模型与解析规则见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)，计费规则（固定金额 / 比例 / 阶梯 / 封顶等）见[费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)。
## 手动重算
未配置费率的交易仍会落明细（费率来源=未配置），补配费率后可在明细行发起**重算**：删除旧明细、按当前费率链重新计算，是费率补配后的兜底入口。重算是危险操作（覆盖原明细），由独立权限码控制并需二次确认。
## 与对账的关系
交易费用明细是**平台侧应收记账**，对账管理是**通道侧实收核对**：对账单核对「通道实际扣了多少」，费用明细记录「平台按费率该收多少」，两者口径独立、互为参照。费率配置变动或通道侧费率调整引起差异时，先看明细的费率来源定位是哪一层定价，再决定是调配置还是走[对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md)的差错处理。
## 常见问题
### 明细里手续费是空的？
该笔交易的费率来源为「未配置」：费率链上没有覆盖到它的层级。补配费率后对该明细发起重算即可回填。
### 调了费率，历史明细会变吗？
不会。明细按交易时点的费率快照锁定，调整只影响之后的新交易；确需重算历史，用手动重算（慎用）。
### 退款的手续费怎么算？
退款明细复制原支付的费率快照，按退款金额生成负数手续费冲减，与原支付明细在同一条资金交易名下对冲。
## 相关链接
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md)：费用明细对应的交易订单
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)：四级费率链与解析优先级
- [费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)：规则化计费与双视图配置
- [对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md)：通道侧对账与差错处理
---
# 异常订单与资金流水
**源**: https://doc.plus.daxpay.cn/common/trade-records.md
# 异常订单与资金流水
> 这几个页面是交易侧的「核查工具」:**异常订单**处理订单状态与资金不一致的特殊场景,**资金流水**提供逐笔资金往来的对账视角,**支付接口日志**记录商户接口调用的审计明细。
## 异常订单
**入口**:运营端 交易管理 → **异常订单**;商户端 交易订单 → **异常订单**(两端都可查看;**确认成功 / 忽略的处置动作仅运营端可用**,商户端发现异常记录请联系运营处理)
### 什么是异常订单
订单在通道侧的最终状态与本地状态不一致时形成异常单,典型场景是**关单后收款**:用户扫码后长时间未付,平台按超时规则关闭了订单,但用户随后在原二维码上完成了支付——通道侧收到了钱,本地订单却是「已关闭」。
| 异常类型 | 说明 |
| --- | --- |
| 关单后收款(close_paid) | 订单已关闭,通道侧收到该笔资金 |
| 失败后收款(fail_paid) | 订单标记失败后,通道侧收到该笔资金 |
| 撤销后收款(cancel_paid) | 订单撤销后,通道侧收到该笔资金 |
异常单的发现来源有三种:通道回调(callback)、手动 / 自动同步(sync)、定时任务(job)。
### 处理方式
**查询条件**:资金交易号、商户订单号、异常类型、发现来源、处理状态、通道订单号。
**操作**:
| 操作 | 条件 | 说明 |
| --- | --- | --- |
| 查看 | — | 详情抽屉:通道状态、处理人 / 时间 / 备注、原始回调报文(两端均可) |
| 确认成功 | 待处理 | 人工核实资金确实到账后,将订单修正为成功状态(仅运营端) |
| 忽略 | 待处理 | 判定无需处理(如重复通知、金额不符已线下处理)(仅运营端) |
「确认成功」会把订单修正为支付成功、写入资金流水并补发支付成功通知,操作前务必与通道侧对账核实资金确实到账。
## 资金流水
**入口**:运营端 交易管理 → **资金流水**;商户端 交易订单 → **资金流水**
资金流水按**逐笔资金往来**记录(一笔支付交易收款 + 可能的多笔退款),是对账的基础数据。
**查询条件**:创建时间(**导出时必填,单次上限 90 天**)、资金交易号、商户订单号、退款单号、流水类型(收款 / 退款)、通道订单号、商户。
**列表列**:交易号、流水类型、商户订单号、金额、标题、商户、通道订单号、完成时间。
**操作**:查看(只读详情)、导出(按查询条件导出,需先限定创建时间范围)。
定期(如每日)按时间区间导出资金流水,与通道侧对账单核对金额与笔数;发现差异时结合「异常订单」页排查。plus 支持支付宝 / 微信(直连)的通道对账单下载与差错单处理,见[对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md)。
## 支付接口日志
**入口**:运营端 系统管理 → 日志管理 → **支付接口日志**(全商户视角)
记录商户经开放接口发起的**每一次调用**(请求 ID、接口、耗时、接入 IP、错误信息),排查「接口为什么报错」的第一站。
- 详情中的请求参数与响应报文**写入时已脱敏**,可直接查看;
- 按请求 ID、接口路径、链路 ID、调用状态筛选;
- 只读页面:日志不允许删除或修改。
运营端可在[日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md)了解该页与其他系统日志的关系。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 异常订单待处理但资金未到账 | 不要点「确认成功」,先与通道侧对账核实;确属重复通知的走「忽略」 |
| 资金流水导出失败 | 先限定创建时间范围(必填,单次上限 90 天),再按条件导出 |
| 接口报错但订单页无异常 | 到「支付接口日志」按时间与调用状态筛出请求,看错误信息与耗时定位 |
## 相关链接
- [支付订单管理](https://doc.plus.daxpay.cn/common/payment-order.md):订单与交易层说明
- [回调与通知](https://doc.plus.daxpay.cn/common/notify.md):回调链路排查
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md):手续费口径的资金对账补充
- [对账管理](https://doc.plus.daxpay.cn/operation-guide/admin/reconcile.md):通道对账单下载与差错单处理
- [日志与监控](https://doc.plus.daxpay.cn/operation-guide/admin/log-monitor.md):运营端日志体系总览
---
# 代理商层级与商户归属
**源**: https://doc.plus.daxpay.cn/plus/agent/hierarchy.md
# 代理商层级与商户归属
> 本页说明商户与代理商的归属模型、平台如何调拨归属,以及「功能开关 × 角色授权」的层级权限体系。适合平台运营与代理商管理者阅读。
## 归属模型:直营与挂靠
每个商户的归属只有两种形态:
| 归属 | 含义 | 典型来源 |
|------|------|---------|
| 平台直营 | 商户直接归平台管理,不属于任何代理商 | 平台自行拓展的商户、平台直营邀请码注册 |
| 挂靠代理商 | 商户归属某一代理商,进入其名下管理体系 | 代理商邀请码注册、代理商代建、运营创建时指定归属 |
运营端商户列表提供「所属代理商」筛选与展示,直营商户显示「平台直营」。代理商支持层级(如一级/二级),名下数据按归属子树过滤——上级可以看到下级代理商名下的商户,但每家商户的直接归属始终精确到具体代理商。
## 归属调拨
商户归属不是一锤定音,平台可以随时划拨:
- **入口**:运营端商户管理提供调拨操作,支持「代理商之间划转」与「收归平台直营」两个方向;
- **预演与执行**:调拨前先预演,系统汇总将跟随划拨的资源与阻断原因——存在进行中的进件申请时会阻断,待其到达终态后再调;
- **联动**:商户名下的应用、通道商户、终端与已绑定设备会跟随划拨;代理商库存中尚未绑定商户的设备不动,仍归设备分拨体系管理;
- **审计留痕**:每次调拨落一条记录,含商户快照、调出方/调入方、调拨原因与操作人,可追溯完整调拨史。
历史订单按交易时点快照归属,不随调拨迁移:调拨前的订单仍归原代理商(新代理商不可见),调拨后的新交易才归属新方。确需核对历史数据,由平台运营在运营端查询导出。
## 层级权限与功能开关
权限体系由「功能开关 × 角色授权」两层收敛:角色授权决定用户能做什么(通用权限体系),功能开关决定这个代理商/商户被允许开放到什么程度,最终生效取两者交集。
### 代理商功能开关
运营端「代理商管理」提供每个代理商的功能开关配置面,当前清单 7 项:
| 开关 | 默认 | 说明 |
|------|------|------|
| 推广邀请码 | 开 | 生成与管理拓展商户的邀请码 |
| 操作记录查看 | 开 | 查看名下业务的操作记录 |
| 订单查询 | 开 | 名下商户支付/退款订单查询 |
| 名下商户查询 | 开 | 名下商户列表查看 |
| 代建商户 | 关 | 代理商代平台创建商户主体 |
| 代配通道商户 | 关(预留) | 授权代管方向,功能落地后生效 |
| 代管商户配置 | 关(预留) | 授权代管方向,功能落地后生效 |
关闭能力后接口立即拦截;菜单入口需对方重新登录后刷新。未显式配置的代理商始终跟随默认值。
### 商户功能开关
商户侧同样有功能开关,并引入「平台意图 + 代理商单向收紧」的分权模型:
- **平台直配**:运营端可对任意商户配置 19 项功能开关,商户用户的最终权限 = 角色授权 ∩ 功能开关;
- **可代管 13 项**:订单查询、退款订单、分账订单、预授权订单、异常订单与工单、资金流水、回调通知、门店与码牌、系统终端、应用管理、收银台与通知配置、操作记录、开发调试——这些代理商可在平台意图范围内代配;
- **平台专属 6 项**:通道商户自配、对接凭证、商户资料自改、网关支付配置、通道路由、易支付——只能平台配置,代理商端不可见;
- **单向收紧**:代理商代配只能收紧(关闭),不能放开超过平台意图;平台已关的项直接灰化不可动;代理商可以恢复自己收紧的项,恢复后回到平台意图值。商户被调拨时,原代理商的收紧配置自动清除,平台意图保留。
### 一级代理商分档
代理商在费率体系中对应「一级代理商档(L1)」的增量定价概念,与服务商定价共同构成费率四级链,详见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)。
## 禁用与删除
- **禁用**:代理商被禁用只影响自身——无法再登录代理商端、邀请码等拓展入口同步失效;名下商户的正常交易不受影响,不连坐;
- **删除**:删除前有硬阻塞校验——名下仍有商户、仍有下级代理商、仍有库存设备时均拒绝删除;条件满足执行删除后,相关配置数据随之级联清理,代理商的用户账号被封禁并强制下线。
## 常见问题
**商户能自己更换归属代理商吗?**
不能。归属变更(划拨/收归直营)是平台运营的专用操作,代理商与商户都没有权限发起。
**调拨后原代理商还能看到这个商户的订单吗?**
调拨前的历史订单仍按快照归原代理商可见;调拨后的新交易归新代理商,原代理商不再看到新数据。
**平台直营商户受代理商开关影响吗?**
不受。代理商只能代配「挂靠自己」的商户;直营商户没有归属代理商,只受平台直配控制。
## 相关链接
- [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)
- [推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)
- [运营端·代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)
- [运营端·商户管理](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)
- [代理商端·名下商户与代建](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)
---
# 代理商体系总览
**源**: https://doc.plus.daxpay.cn/plus/agent/overview.md
# 代理商体系总览
> 本页介绍 plus 商业版独有的代理商体系:它在平台与商户之间引入渠道层级,解决支付业务规模化拓展中的商户拓展、授权代管与数据隔离问题。适合平台运营与代理商管理者阅读。
## 为什么需要代理商体系
支付平台的商户增长往往不靠平台自己一家家谈,而是依赖渠道力量:地推团队、行业服务商、软件代理商把商户批量带进来,并长期承担装机与售后。代理商体系就是为这类渠道角色建立的专属层级:
- **平台(运营端)**:负责通道对接、进件审核、费率定价、风控与全局运营,是规则的制定者;
- **代理商**:组织树上的销售与服务节点,负责拓展商户、协助进件与装机维护,按归属关系管理名下商户;
- **商户**:交易树上的主体,拥有自己的商户号、通道配置与结算资金,是最终收款方。
代理商是组织树上的销售/服务节点,永远不是交易树上的资金主体——商户的钱不经过代理商。
```mermaid
flowchart TB
subgraph platform ["平台(运营端)"]
A1["通道对接与进件审核"]
A2["费率定价与风控"]
end
subgraph agent ["代理商(一级 / 二级)"]
B1["拓展商户 · 邀请注册"]
B2["名下商户管理 · 授权代管"]
end
subgraph mch ["商户"]
C1["交易与结算主体"]
C2["商户端自助配置"]
end
platform -->|"归属与权限约束"| agent
agent -->|"名下商户"| mch
platform -->|"直营商户"| mch
```
## 三档定位
市面所说的「代理商」实际横跨三个档位,plus 在产品设计上明确分档、各归其位:
| 档位 | 形态 | plus 的处理 |
|------|------|------------|
| 档1 展业主体 | 拓展商户的渠道/销售代理:看名下商户、协助进件、装机维护 | **体系基线**,代理商端现有功能均属此档 |
| 档2 授权代管 | 以服务商身份受商户授权代管通道配置等事务 | **演进主线**:代建商户已落地,代配通道商户、代管商户配置等能力沿授权代管方向逐步开放 |
| 档3 集团商户 | 「钱先进我账上再分给门店」的大商户模式 | **不做**:由商户体系的门店与分账能力承接,不进代理商体系 |
判断口径可以很简单:要「介绍商户进来」是档1;要「帮商户跑腿干活」是档2 加授权;要「资金先进自己账户再分」那是集团商户需求,应走商户产品加通道原生分账,并须持牌合规。
## 代理商端功能面
代理商端提供 Web 与 APP 双入口(APP 支持移动化查看,功能以 Web 端为准),核心功能面:
| 功能 | 说明 |
|------|------|
| 工作台 | 名下商户与交易的统计概览 |
| 操作记录 | 名下业务的业务操作日志查询 |
| 名下商户 | 名下商户列表、代建商户、商户功能开关代配 |
| 推广邀请码 | 生成与管理邀请码,发展商户自助注册挂靠 |
| 码牌管理 | 名下商户码牌的查看与管理 |
| 订单查询 | 名下商户支付/退款订单查询(只读) |
详细操作见各端操作指南(见页尾链接)。
## 数据边界
代理商的一切数据访问都以归属关系为边界:
- **只见名下商户**:商户、订单、码牌等数据按代理商归属过滤,非名下数据不可见也不可操作;
- **对商户数据以只读为主**:订单查询等均为只读视角,涉商户配置的写操作沿授权代管方向逐步开放,并全程留痕;
- **不持有商户资金**:体系内没有代理商代收代付的环节,商户结算资金与代理商无关;
- **通道凭证由平台管理**:通道密钥等敏感凭证仅平台运营维护,代理商不可接触。
## 常见问题
**代理商能操作名下商户的退款吗?**
不能。订单查询为只读;退款属于商户侧操作,代理商代操作类能力属授权代管方向,须按授权与留痕机制开放。
**「钱先进代理商再分给商户」为什么不行?**
该模式属于大商户/二清形态,存在合规风险,plus 明确不做;有此类需求应使用商户门店与通道原生分账能力,并确保持牌合规。
**代理商和进件里的「服务商」是什么关系?**
在微信/支付宝服务商(ISV)模式下,代理商可以以服务商身份参与名下商户的进件与通道配置代管,这是档2 授权代管主线的衔接点,详见[代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)与[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)。
## 相关链接
- [代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)
- [推广与邀请注册](https://doc.plus.daxpay.cn/plus/agent/promotion.md)
- [运营端·代理商管理](https://doc.plus.daxpay.cn/operation-guide/admin/agent-management.md)
- [代理商端·名下商户与代建](https://doc.plus.daxpay.cn/operation-guide/agent/merchants.md)
- [代理商端·订单查询与码牌](https://doc.plus.daxpay.cn/operation-guide/agent/orders-qrcode.md)
- [代理商端 APP 功能地图](https://doc.plus.daxpay.cn/operation-guide/app/agent/overview.md)
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)
---
# 推广与邀请注册
**源**: https://doc.plus.daxpay.cn/plus/agent/promotion.md
# 推广与邀请注册
> 本页说明商户如何通过邀请码自助注册并挂靠到代理商,以及两条邀请码线路(代理商推广码/平台直营码)的管理方式。适合平台运营与代理商管理者阅读。
## 推广链路总览
```mermaid
flowchart LR
A["代理商生成邀请码"] -->|"发送链接/二维码"| B["商户打开注册页"]
B --> C["填写注册信息"]
C --> D{"注册校验"}
D -->|"通过"| E["创建商户并挂靠
默认停用"]
D -->|"拒绝"| F["提示原因: 开关未开/
验证码错误/超IP上限/码失效"]
E --> G["平台运营启用商户"]
G --> H["商户登录商户端
办理进件"]
```
注册成功的商户即完成挂靠,系统同时自动创建商户管理员账号(登录账号=注册手机号)、默认应用与默认门店,代理商端「名下商户」立即可见其状态。
## 注册要素与注册安全配置
注册页部署在收银台 H5 域名下(形如 `https://h5.example.com/register?inviteCode=码值`),注册要素为:
- **手机号**:即商户管理员的登录账号,重复注册会被账号唯一性校验拦下;
- **密码**:商户自设,强度受平台密码策略约束;
- **图形验证码**:防机器注册。
注册入口受「注册安全配置」控制,位于运营端「系统管理 → 系统配置 → 系统安全配置」,与登录安全成对:
| 配置项 | 默认 | 说明 |
|--------|------|------|
| 注册开关 | 关 | 自助注册总开关,开放注册前必须显式开启 |
| 强制图形验证码 | 开 | 开启后注册必须通过图形验证码 |
| 单 IP 每日注册上限 | 开(10 次/日) | 防同一 IP 批量灌注册 |
注册开关默认关闭是刻意的安全基线:平台尚未准备好时,邀请码链路不会意外开放;需要推广时由运营显式开启。
## 代理商推广邀请码
代理商端「商户管理 → 推广邀请码」管理自己的码:
- **生成**:随机生成(不是明文代理商号,防伪造),可设置备注、有效期(默认永久)与使用次数上限(默认不限);
- **停用/启用**:随时撤销某个码的注册资格;
- **推广物料**:一键复制推广链接、展示二维码,发给商户即可注册;
- **计数**:每个码记录已成功注册次数,便于按码统计推广效果。
**注册记录**:代理商可查询谁通过自己的码注册——产出商户、手机号、注册时间、来源 IP。记录为快照语义,码事后停用或删除不影响历史记录。
## 平台直营邀请码
平台自己也有一条邀请线,与代理商线并存,共用同一条注册链路与安全配置:
- 运营端「商户管理 → 邀请注册 → 邀请码管理」可生成**平台直营邀请码**(不挂任何代理商),并同样获取推广链接与二维码;
- 商户通过平台码注册时,落地页显示「平台官方邀请」,产出的商户为平台直营归属;
- 该页同时是全量视角:可查看全平台所有邀请码(含各代理商的码)与全部注册记录,并可按代理商筛选;
- 平台码注册的商户后续如需交给代理商,走商户归属调拨即可。
## 常见问题
**注册完成后商户能马上收款吗?**
不能。注册产出的商户默认为停用状态,需平台运营启用后方可登录商户端;要收款还须完成通道进件,两道闸门先后生效。
**代理商码和平台码注册的商户有什么区别?**
仅归属不同:前者挂靠对应代理商、进入其名下管理体系;后者为平台直营。注册流程、校验与默认停用口径完全一致。
**邀请码泄露被恶意刷注册怎么办?**
可立即停用该码;配合注册开关、图形验证码与单 IP 每日上限三层防刷,风险可控;注册记录中可追溯每次注册的来源 IP。
## 相关链接
- [代理商体系总览](https://doc.plus.daxpay.cn/plus/agent/overview.md)
- [代理商层级与商户归属](https://doc.plus.daxpay.cn/plus/agent/hierarchy.md)
- [运营端·邀请注册管理](https://doc.plus.daxpay.cn/operation-guide/admin/invite-register.md)
- [代理商端·推广邀请码](https://doc.plus.daxpay.cn/operation-guide/agent/invite-code.md)
- [运营端·系统安全配置](https://doc.plus.daxpay.cn/operation-guide/admin/system-security.md)
---
# 商户限额体系
**源**: https://doc.plus.daxpay.cn/plus/mch-limit.md
# 商户限额体系
> 商户限额约束「单商户能收多大、多频繁的钱」:单笔上下限、日/周/月累计金额与笔数,以及退款方向的日累计兜底。它与[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)互补——防线拦「坏人」,限额拦「超额」。限额维度为商户级,对商户名下全部支付应用统一生效。
## 生效模型:平台兜底 + 商户覆盖
限额配置分两级:
| 层级 | 配置位置 | 作用 |
|---|---|---|
| 平台默认限额模板 | 运营端「支付安全 → 风控策略 → 限额兜底」 | 全局兜底,商户无自定义规则时按此执行 |
| 商户自定义规则 | 运营端「商户管理 → 商户工作台 → 交易限额」 | 逐商户定制,存在即整体覆盖模板 |
生效语义(整体回退,不做逐维度合并):
- 支付方向:商户配置了**任一条**支付规则,该方向即整体以商户规则为准;一条都没配,回退平台默认模板;
- 退款方向:平台模板不覆盖退款,商户不配即不限;需要约束时在商户规则中配置退款日累计;
- 模板与规则中留空的维度都表示「不限」;支付方向全部留空时等同未配置,仍回退平台默认限额。
## 三段闭环
限额不是「配完就完」,平台内部按三段闭环运转:
1. **配置**:运营端维护平台模板与商户规则;
2. **生效**:每笔交易在下单时经限额校验链(下文流程图),支付/退款成功后按规则累计用量;
3. **对账修正**:指标检测任务定时用数据库实际成功金额与笔数修正内存计数,消除计数漂移——即使计数组件短暂异常,限额口径也会被拉回真实值。
## 矩阵化配置表单
商户「交易限额」页是一张矩阵表单:**方向(支付/退款)× 限额类型**,留空即不限:
| 方向 | 可配维度 |
|---|---|
| 支付 | 单笔下限、单笔上限、日/周/月累计金额上限、日/周/月累计笔数上限 |
| 退款 | 仅日累计金额上限 |
周期按东八区自然日、自然周(周一起)、自然月计算。平台默认模板在风控策略「限额兜底」分区维护,维度与商户规则的支付方向一致(单笔上下限 + 日/周/月累计金额与笔数)。
## 限额类型速查
| 类型 | 用途 | 典型场景 |
|---|---|---|
| 单笔下限/上限 | 约束单笔金额 | 下限防小额测试单刷接口,上限防单笔大额风险敞口 |
| 日/周/月累计金额 | 约束周期收款总额 | 控制商户资金规模上限 |
| 日/周/月累计笔数 | 约束周期交易频率 | 金额限额拦不住「一天 8000 笔 × 5 元」式小额高频,笔数维度补位 |
## 退款日累计兜底
退款方向只保留**日累计金额上限**一个维度,这是刻意设计:退款金额天然受原支付单约束(退不了比收到的多),精细矩阵没有意义;真正要防的是**商户账号或接口凭证泄露后被批量退款搬钱**——一个日累计上限即可兜底。
## 校验流程
一笔交易经过限额校验的路径:
```mermaid
flowchart TD
A["支付/退款请求"] --> B{"商户配了该方向规则?"}
B -->|是| C["按商户规则校验
(单笔 / 日周月累计金额与笔数)"]
B -->|否, 支付方向| D["按平台默认限额模板校验"]
B -->|否, 退款方向| P["放行(不限)"]
C --> E{"超限?"}
D --> E
E -->|是| R["拦截下单, 提示超限维度与限额值"]
E -->|否| P2["放行"]
P2 --> F["交易成功后累计用量
(金额与笔数双计数)"]
F --> G["定时对账修正计数"]
```
超限拦截的提示会带上限额值,便于商户自助判断;若平台模板与商户规则都不限,交易不受限额约束。
## 商户端只读视角
商户对自己「被约束了什么、用了多少」有知情权,但配置权全在运营端:
- 商户端「基础管理 → 风控与限额」页展示**生效限额**(注明来源是自定义还是平台默认)、**实时用量**(已用金额与笔数,有上限时带进度条)、风控参与状态与本商户的**拦截记录**(命中值脱敏);
- 未配置规则的商户在这里看到的是平台模板展开的限额与来源标识,而不是一片空白——避免误以为「没有限额」。
## 常见问题
**只想限笔数不限金额,可以吗?**
可以。金额与笔数两个维度独立配置,留空的维度不限制;单笔维度没有笔数概念,只配上下限。
**改了限额,已产生的用量会清零吗?**
不会。用量按周期累计,改配置只影响后续校验口径;当前周期结束后自然归零,也可等待对账修正拉齐口径。
**为什么商户不能自己调限额?**
限额属于平台风控约束,放权给被约束方会让防线失效;商户侧只提供只读透明化视图。
## 相关链接
- [风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)
- [风控策略与处置(限额兜底配置所在页)](https://doc.plus.daxpay.cn/plus/risk-control/policy.md)
- [支付安全与风控(运营端操作)](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)
- [商户资料与门店(商户端风控与限额只读)](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md)
---
# 通道进件差异
**源**: https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md
# 通道进件差异
> 各通道的进件接口形态、资料要求与商户侧动作差异极大。本页按通道逐一说明差异,办理通用流程见[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md),五型分类模型见[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)。
## 差异总表
| 通道 | 型 | 进件形态 | 商户侧动作 | 产出 |
|---|---|---|---|---|
| 微信支付 | A | 特约商户进件,单次全量提交 | 超管需完成账户确认 | 微信子商户号 |
| 支付宝 | B | 产品开通(如当面付)多步签约 | 支付宝 App 内确认 | 商户账号签约关系 |
| 斗拱支付 | C | 机构下开二级商户 | 无 | 机构二级商户号 |
| 拉卡拉 / 乐刷 / 海科融通 / 随行付 | C | 机构下开二级商户 | 无 | 机构二级商户号 |
| 汇付天下(Adapay) | E | 平台凭据入网,商户获自有凭据 | 无 | 商户自有 Adapay 应用凭据 |
| 银联商务 | 特殊 | 平台商户进网(规划中) | — | — |
| 其他通道 | — | 暂不支持进件 | — | — |
## 微信支付(A 型·子商户进件)
微信走**特约商户进件**线:平台以服务商身份为商户提交全量资料,通道审核通过后发放子商户号,商户即以特约商户身份挂在服务商名下收款。
要点:
- **进件参数在服务商工作台维护**:每个微信服务商的进件参数(进件场景应用与优惠费率活动)在其服务商工作台的「进件参数」中配置,不在申请单里逐单填写;
- **销售场景按应用开放**:线下门店场景恒可用;公众号、小程序、APP 等线上场景要求服务商先配置对应类型的应用,商户在申请单内从可用场景中多选;
- **优惠费率活动**:服务商可配置借记卡/贷记卡优惠费率参与平台默认主营行业优惠活动,提交时按申请单的行业与结算规则自动判断是否适用;
- **超管确认**:审核通过前后需商户超级管理员完成确认与账户验证,申请单会给出待确认提示。
## 支付宝(B 型·产品开通)
支付宝的进件语义是**代商户开通产品**(如当面付),采用多步事务式签约编排,通道不发商户号——收款身份就是商户自己的支付宝账号。
要点:
- **开通产品**:创建申请单时勾选要开通的产品(如当面付),签约范围随申请提交;
- **经营类目**:按支付宝类目字典选择签约类目,通道级默认类目在进件配置中预填、申请单内可改;
- **申报费率**:当面付费率随申请申报,默认值取归属服务商的费率政策,受平台费率下限校验(见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md));
- **商户确认**:签约事务需商户在支付宝 App 内确认,超时未确认的事务作废,需重新提交;
- **授权线独立**:商户开通产品后,如需平台代运营收款,另行走服务商授权(商户授权令牌)链路,与进件申请单解耦。
## 聚合通道(C 型·机构二级商户)
拉卡拉、乐刷、海科融通、随行付、斗拱等聚合通道同属**机构二级商户**模型:平台先在收单机构开设机构户,进件即在该机构下为商户开二级商户,提交 → 轮询 → 发号,流程形态与微信 A 型同构。
要点:
- 各机构的行业码、费率组、结算周期等资料字段互不相同,申请单表单按通道分化;
- 部分通道对门店资料有额外要求(如斗拱要求门店收银台照片必填);
- 多数机构无商户侧确认动作,审核通过即完成。
其中**斗拱支付**是汇付天下旗下的独立进件线,与同门的 Adapay 各走各的进件通道,互不共用资料与凭据。
## 汇付天下 Adapay(E 型·进件直连)
Adapay 是特殊的**直连进件**形态:平台用自己的 Adapay 凭据替商户完成入网报备,审核通过后商户获得**自有的 Adapay 应用凭据**,后续交易以商户凭据直连 Adapay,不经服务商代调。
要点:
- 进件凭据与交易凭据分离:入网用平台凭据(在「进件产品(特殊)」页的 Adapay 服务商配置中维护),交易用商户自有凭据;
- 进件通过后回执的商户凭据自动落入商户级密钥配置,凭据不全时引导补配;
- 入网时勾选开通的支付渠道,决定该商户可用的支付方式矩阵。
## 银联商务(特殊线·规划中)
银联商务规划走**平台商户进网**特殊线:报备主体与常规服务商线不同,当前版本在「进件产品(特殊)」页保持「即将支持」占位,暂不可办理。通道本身的支付对接不受影响,商户号可通过通道后台人工开通后登记为通道商户。
## 其他通道
富友、盛付通、易宝、抖音、银联等通道当前**暂不支持进件**:需要收款时可先在通道侧重人工方式开通,再把商户号与密钥登记到平台的通道商户配置中使用。各通道的进件支持范围会随后续版本逐步扩大,以「进件产品(特殊)」页与新建申请单的可选通道清单为准。
## 常见问题
**同一商户能同时进件微信和支付宝吗?**
能。归属锁定是「商户 × 通道」维度,不同通道互不影响;聚合通道(如斗拱)覆盖微信/支付宝等多个支付方式,一次进件即可同时获得多方式收款能力。
**通道进件被驳回,资料会丢吗?**
不会。驳回后申请单回到可编辑状态,已填资料保留,补正通道给出的驳回原因后可重新提交。
## 相关链接
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)
- [进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)
- [进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)
- [微信支付(通道文档)](https://doc.plus.daxpay.cn/extension/channels/wechat.md)
- [支付宝(通道文档)](https://doc.plus.daxpay.cn/extension/channels/alipay.md)
- [汇付天下 Adapay(通道文档)](https://doc.plus.daxpay.cn/extension/channels/adapay.md)
- [斗拱支付(通道文档)](https://doc.plus.daxpay.cn/extension/channels/dougong.md)
- [银联商务(通道文档)](https://doc.plus.daxpay.cn/extension/channels/ums.md)
- [支付通道总览](https://doc.plus.daxpay.cn/extension/channels/index.md)
---
# 进件配置管理
**源**: https://doc.plus.daxpay.cn/plus/onboarding/config.md
# 进件配置管理
> 进件域的配置分三个层面:哪些进件线对外开放(进件产品配置)、服务商持有哪些进件参数(服务商工作台)、申报费率如何约束(服务商费率政策与平台下限)。本页面向平台配置管理员。
## 配置面总览
| 层面 | 回答的问题 | 配置入口 |
|---|---|---|
| 进件线开放面 | 哪些通道开放进件、哪些还在规划 | 运营端「通道与产品配置 → 进件产品(特殊)」+ 支付主数据通道管理 |
| 通道服务商参数 | 服务商用什么凭据与参数办进件 | 各通道服务商工作台 |
| 申报费率 | 进件向通道申报的费率与平台下限 | 服务商工作台进件参数 + 费率体系平台下限 |
## 进件产品配置
「进件产品(特殊)」页(运营端「通道与产品配置」目录下)管理进件线的对外呈现:
- **只展示特殊直连线**:Adapay(进件直连)、银联商务(平台商户进网,规划占位)等特殊进件线在本页以卡片呈现,点击卡片进入对应管理页(如 Adapay 的服务商配置页,维护入网平台凭据);
- **常规线并入产品级**:微信、支付宝、拉卡拉、斗拱等常规服务商线的进件配置不设独立卡片,统一并入「支付和进件产品」的产品级维护,避免两处入口;
- **规划占位**:尚未上线的进件线显示「即将支持」灰卡,不可点击,给使用者明确预期。
进件线的开放状态由主数据驱动:哪些通道有进件接入面、是否可见、展示名称与排序,在支付主数据的通道管理中维护;新建申请单的进件产品下拉**只列出当前开放且可见的进件线**。规划中的通道不要提前对商户开放,调低可见性即可。
进件线主数据只管「有没有、显不显示」;某条线能不能真正办成,还取决于服务商凭据与进件参数是否配置齐全——两层面都要就绪。
## 通道服务商参数
服务商是进件的实际执行者,其进件参数统一在**服务商工作台**维护。以微信为例,在「微信服务商管理」列表点击服务商卡片进入工作台,工作台按磁贴分组:
| 磁贴 | 内容 |
|---|---|
| 基础信息 | 服务商编号、名称、服务商商户号、支付应用 |
| 支付密钥 | API V3 密钥、证书与公钥(交易调用凭据) |
| 进件参数 | 进件场景应用与优惠费率活动 |
| 服务商费率 | 按服务商逐能力定价,交易手续费按此计量 |
| 应用管理 / 默认支付应用 | 通道支付应用的创建与按方式指定默认应用 |
| 管理操作 | 启用/停用进件、启用/停用支付、删除服务商 |
支付宝的服务商即服务商应用,申报费率与密钥同样在工作台完善。两个关键口径:
- **启停分离**:「停用进件」只是把服务商从新申请单的可选池移除,存量申请单照常流转、支付不受影响;「停用支付」独立控制新支付请求,不牵连进件;
- **删除保护**:名下存在通道商户或进件申请的服务商无法删除。
微信进件参数(进件场景应用与优惠费率活动)说明:进件场景应用按公众号/小程序/移动应用三类分别指定,须为平台已登记且类型匹配的应用,可用销售场景由此推导(线下门店恒可用);优惠费率活动配置借记卡/贷记卡费率,参与平台默认主营行业优惠活动,提交时按申请单行业自动判断适用性。
## 申报费率管理
进件费率是**向通道申报的申请值**(不是平台记账费率,后者见费率体系):
- **来源**:申报费率默认值来自归属服务商的费率政策——支付宝服务商应用维护当面付申报费率,微信服务商维护优惠费率活动;创建申请单时预填、单内可改;
- **平台下限**:平台设费率下限校验,两道闸口——申请单创建预填时校验服务商政策自洽,提交进件前再校验申报值不低于平台下限;低于下限直接拦截,防止亏本申报;
- **冻结与回执**:申报值随资料在提交时冻结;通道批复的实际费率以回执为准,记录在通道商户档案作成本参考,不参与平台计费。
服务商费率政策(平台向商户计费的费率链)与申报费率是两套口径,前者见[费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)。
## 常见问题
**新建申请单里看不到某个通道?**
依次检查:该通道进件线是否开放且可见(支付主数据通道管理)、对应服务商是否已配置进件参数并启用进件、是否为规划中的占位线(「进件产品(特殊)」页灰卡)。
**多个服务商怎么决定商户归谁?**
申请单创建时显式选择归属服务商(必选);已在该通道有归属的商户强制锁定原服务商。没有「默认服务商」兜底,未选择会被拦截。
**服务商停用后,名下已有商户还能交易吗?**
能。停用进件只影响新申请候选;存量申请单四动作(提交/同步/审核/生成商户)与支付均不受影响。
## 相关链接
- [进件产品配置(运营端操作)](https://doc.plus.daxpay.cn/operation-guide/admin/onb-product.md)
- [支付产品配置(产品级服务商线入口)](https://doc.plus.daxpay.cn/operation-guide/admin/product-config.md)
- [支付主数据(进件线主数据维护)](https://doc.plus.daxpay.cn/operation-guide/admin/pay-masterdata.md)
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)
- [通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)
---
# 进件体系总览
**源**: https://doc.plus.daxpay.cn/plus/onboarding/overview.md
# 进件体系总览
> 本页是 plus 进件域的总纲:进件解决什么问题、服务商如何归属、各通道进件形态如何分类、一张申请单从创建到生成通道商户要经历哪些状态。具体办理操作见[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md),配置管理见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)。
## 进件是什么
商户要在某个支付通道收款,必须先通过该通道(或其服务商)的报备审核:提交营业执照、法人证件、结算账户、经营场所等资料,由通道审核通过后分配收单资格(如微信子商户号、机构二级商户号)。这套「商户入驻 → 通道报备 → 收单开通」的线上化流程,就是进件。
如果只在通道后台人工录入资料再回平台登记商户号,流程割裂、无法追溯。plus 把进件纳入平台统一管理:
- **一套申请单**:资料填报、提交、审核、状态同步全部在运营端完成,全程留痕;
- **资料一次维护**:商户进件资料主档维护一次,创建新申请单时自动带入,免重复填报;
- **自动开户**:申请通过后自动生成通道商户绑定关系,立即可用于通道路由与交易。
## 多服务商模型
plus 支持同一通道登记**多个服务商**:微信侧为多个微信服务商,支付宝侧为多个服务商应用。每个服务商持有独立的商户号、证书密钥与进件参数(场景应用、申报费率等),商户报备到哪个服务商名下,交易凭证就由哪个服务商承载。
归属规则(核心约束):
| 规则 | 说明 |
|---|---|
| 创建即锁死归属 | 申请单创建时必选归属服务商;商户在该通道已有归属(通道商户或进行中申请)时,强制同服务商且不可改选 |
| 换服务商 = 作废重开 | 归属服务商创建后不可修改,选错只能作废原申请单、重新创建 |
| 提交后全链锚定 | 提交、状态同步、生成通道商户全链按申请单锚定的服务商取凭证,服务商配置后续变更不影响存量申请单 |
| 对外不暴露 | 服务商是平台内部概念,商户端与开放 API 只感知商户号与通道商户号 |
一个商户的子商户号若散在多个服务商名下,交易凭证解析会失去唯一锚点。锁死归属保证了「商户 × 通道」维度的凭证一致性,服务商停用也只影响新申请,存量申请照常流转。
## 五型通道分类
各通道的进件接口形态差异极大,plus 按「进件凭据方 × 交易凭据方」两个维度将其归为五型:
| 型 | 进件模型 | 代表通道 | 产出 |
|---|---|---|---|
| A 子商户型 | 平台以服务商凭据全量提交资料,通道审核后**发子商户号** | 微信(特约商户进件) | 子商户号,商户侧需完成确认 |
| B 代开通型 | 事务式「代创建→签约→确认」多步编排,通道**不发号**,收款另需授权线 | 支付宝(产品开通) | 商户支付宝账号签约关系 |
| C 机构二级型 | 平台先在收单机构开机构户,进件即机构下开二级商户 | 斗拱、拉卡拉、乐刷、海科融通、随行付等聚合通道 | 机构二级商户号 |
| E 进件直连型 | 平台以自有通道凭据替商户入网报备,商户获得**自有凭据**后交易直连、不经服务商代调 | Adapay(汇付天下) | 商户自有通道应用凭据 |
| D 无 API 型 | 无进件接口,资料收集后由运营到通道后台人工录入 | 个别小通道 | 人工回填商户号 |
A/C/E 三型对平台是同一形状(提交 → 轮询 → 发号),是通道大头;B 型的差异由「授权线独立于进件域」消化;D 型零成本承接。逐通道的差异细则见[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)。
## 申请单状态机
一张进件申请单的生命周期如下(状态为平台自有口径,通道原始状态仅作参考展示):
```mermaid
flowchart TD
A["草稿"] -->|提交| B["预审"]
B -->|平台预审通过| C["申请中"]
B -->|预审拒绝| D["预审拒绝"]
D -->|修改后重新提交| B
C -->|通道驳回| E["驳回"]
C -->|通道审核通过| F["通过"]
E -->|补正资料重新提交| B
A -->|需要补料| G["数据补填"]
G -->|补填完成| B
F -->|自动生成通道商户| H["已生成商户"]
A -->|不再办理| X["已关闭(作废)"]
C -.->|异常| Y["错误"]
Y -.->|修复后重新提交| B
```
几点约定:
- **资料冻结**:只有草稿、预审拒绝、驳回、数据补填四个状态可编辑资料,提交进入申请中后锁死——提交瞬间的资料值即申报快照;
- **拉取式同步**:平台主动向通道查询审核结果(申请单上的同步动作),不依赖通道回调推送;
- **已生成商户**是终态:通道商户绑定关系已建立,可直接用于路由配置与交易。
## 从哪里开始
- 配置管理员:先读[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md),开通进件线、维护服务商进件参数;
- 日常办理人员:按[进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)创建申请、填报资料、跟进审核;
- 对接特定通道前:查[通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)确认该通道的进件形态与商户侧动作。
## 常见问题
**商户已经在微信服务商 A 名下,还能申请到服务商 B 吗?**
不能。同一商户在同一通道的归属是锁定的,创建申请单时服务商不可改选。确需更换时,作废原申请单重新创建也无法绕开既有通道商户的归属,需先在通道侧解除原归属关系。
**申请通过后还要做什么?**
部分通道需要商户侧确认(如微信超管确认链接),申请单会给出待确认提示;确认完成且状态到「已生成商户」后,通道商户即可参与路由。
## 相关链接
- [进件申请流程](https://doc.plus.daxpay.cn/plus/onboarding/process.md)
- [通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)
- [进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)
- [进件申请与工作台(运营端操作)](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)
---
# 进件申请流程
**源**: https://doc.plus.daxpay.cn/plus/onboarding/process.md
# 进件申请流程
> 本页讲一张进件申请单的完整办理过程:从创建、资料填报到审核通过与通道商户生成。体系模型见[进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md);运营端页面入口为「商户管理 → 进件申请」。
## 创建申请单
运营端「商户管理 → 进件申请」列表页发起「新建进件申请」,创建分四步:
| 步骤 | 内容 | 要点 |
|---|---|---|
| 1 选商户 | 选择办理进件的商户 | 从商户列表选择;也可从商户工作台直达,跳过本步 |
| 2 选进件产品 | 以卡片选择进件线 | 卡片分「服务商进件」与「特殊进件产品」两组,只列出当前开放进件的通道;规划中的通道显示「即将支持」 |
| 3 申请信息 | 填申请名称、进件类型、归属服务商 | 服务商为必选项;商户已有该通道归属时锁定只读。支付宝线还需勾选开通产品(如当面付) |
| 4 资料填报 | 按通道表单填报资料 | 创建成功后进入填报,支持后述的资料主档预填与 OCR 录入 |
创建成功即**锁死归属服务商**(体系语义见[总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)),后续任何状态都不可改选。
## 资料填报与资料主档复用
进件资料分两层:通用资料(主体信息、法人信息、营业执照、经营场所、结算账户等)为各通道共用;通道专属资料(如微信结算规则、支付宝经营类目)只属于该次申请。为避免逐单重复填报,plus 提供商户级**进件资料主档**:
- **维护入口**:运营端「商户管理 → 商户工作台 → 进件资料」,独立子页维护主体信息、法人信息、营业执照、经营场所四类资料,一户一套;
- **复用方式**:新建申请单时勾选「复用商户资料」(默认勾选),创建成功后平台自动把主档四类资料复制进本申请单的资料快照,打开填报页即已预填,只需补结算账户与通道专属项;
- **联动**:主体类型取自商户档案;小微商户(无营业执照)自动跳过执照资料;
- **边界**:结算账户与通道专属资料不参与复用;申请单创建后主档更新不会自动刷新到已创建的申请单,需要带入新资料就删单重建(草稿态可删)。
主档由后端在创建申请单时统一复制,运营端表单、H5 填报页等所有填报入口天然拿到预填数据,无需逐端配置映射。
## OCR 识别录入
营业执照、法人身份证支持 OCR 识别回填,减少手工录入:
- 在「进件资料」主档页上传证件图片后,点击图片旁的「OCR识别」按钮即可识别并回填——营业执照回填执照号、名称、地址与有效期;身份证人像面回填姓名、证件号与住址;国徽面回填有效期;
- 识别按次计费,故设计为手动触发而非上传即识别;识别结果请人工核对后保存;
- 支持阿里云、腾讯云、百度云三家供应商,在运营端「系统管理 → 平台配置」中配置并启用其一即可(阿里云要求文件存储公网可访问,内网部署建议选腾讯云或百度云)。
## 费率申报
部分通道的进件需要同步申报费率(如支付宝当面付费率):
- 申报费率的**默认值来自归属服务商的费率政策**(服务商维度的进件参数,见[进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)),创建申请单时预填、可改;
- 平台设有费率下限校验:申报费率不得低于平台下限,创建预填与提交前两道闸口都会拦截——防止误填低费率导致亏本放款;
- 费率申报值在提交后随资料一并冻结;通道最终批复费率以通道回执为准,回执值记录在通道商户档案作成本参考,不参与平台计费。
## 提交与审核
资料填报完整后提交申请单,进入两段审核:
1. **平台预审**:运营端在申请列表(或进件申请工作台)对「预审」状态的申请单审核,可**通过**或**驳回**;驳回后申请单回到可编辑状态,补正资料后可重新提交;
2. **通道审核**:预审通过后申请推送至通道,状态转为「申请中」;在列表上执行**同步**动作拉取通道最新审核结果——通过、驳回或仍在审核中。
部分通道有商户侧确认环节(如微信的超管确认),申请单会提示待商户完成确认,确认后才走到通过。
## 通过后:自动生成通道商户
申请状态变为「通过」后,平台自动生成本次申请的**通道商户**绑定关系:
- 通道商户继承申请单锁定的服务商归属,与交易凭证解析链路对齐;
- 生成的通道商户可直接进入通道路由配置,参与支付下单;
- 通道回执的批复费率等信息记录在通道商户档案。
## 作废与重开
- **草稿态可删**:尚未提交的申请单可直接删除,不留痕迹;
- **作废**:不再办理的申请单可关闭作废(「已关闭」状态);选错归属服务商时也走作废重开——创建新申请单重新选择;
- **重开**:作废不影响商户在该通道重新发起申请;若原服务商归属仍存在,新申请单会被强制锁定为同一服务商。
## 商户自助填报
对于由商户自己补资料的申请单,运营端列表提供「H5 填报链接」:生成二维码与链接发给商户,商户手机扫码后**免登录**填写进件资料。仅草稿、预审拒绝、驳回状态的申请单可生成填报链接。
## 常见问题
**申请单提交后还能改资料吗?**
不能。提交进入「申请中」后资料即冻结;被通道驳回后恢复可编辑,补正后重新提交。
**复用主档后图片也要重新传吗?**
不需要。主档图片按平台文件存储管理,复制到申请单后可直接复用,提交时由通道策略统一上送。
**通道审核结果多久同步一次?**
平台为拉取式同步,在申请列表手动执行同步即拉取最新状态,不存在自动推送间隔的依赖。
## 相关链接
- [进件体系总览](https://doc.plus.daxpay.cn/plus/onboarding/overview.md)
- [通道进件差异](https://doc.plus.daxpay.cn/plus/onboarding/channel-diff.md)
- [进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)
- [进件申请与工作台(运营端操作)](https://doc.plus.daxpay.cn/operation-guide/admin/onboarding.md)
- [商户管理(商户工作台与进件资料入口)](https://doc.plus.daxpay.cn/operation-guide/admin/merchant-management.md)
---
# 费率规则引擎
**源**: https://doc.plus.daxpay.cn/plus/rate-system/engine.md
# 费率规则引擎
> 本页说明费率如何从「一个百分比」升级为「一条计费规则」:规则能表达什么、保存时如何校验、交易后费用如何落明细。适合平台财务与运营阅读。
## 规则化计费
每一条费率配置本质上是一条计费规则,规则要素包括:
| 要素 | 说明 | 示例 |
|------|------|------|
| 计费模式 | 百分比 / 固定金额 / 百分比+固定金额混合 | 0.6% + 0.1 元/笔 |
| 金额区段 | 按交易金额分段计费(阶梯),区段连续无缝隙无重叠 | 1000 元以下 0.38%,以上 0.6% |
| 最低费用 | 单笔手续费不足该值时按该值收 | 最低 1 元 |
| 单笔封顶 | 单笔手续费超过该值时按该值收 | 封顶 20 元 |
| 起征点 | 交易金额低于该值整笔免收 | 500 元起征 |
配置页会把规则渲染成人话摘要,例如:`0.6% + 0.1元/笔 · 最低1元 · 封顶20元 · 1000元以下0.38%`。摘要随费用明细一并固化,历史账单文案稳定。
## 计算口径
一笔交易的手续费按固定顺序计算:
1. **起征点**:金额低于起征点,整笔免收;
2. **区段定位**:配置了金额区段时,取交易金额所在区段的模式与参数;
3. **公式计算**:百分比按金额乘费率,固定金额直接取值,混合两者相加;
4. **最低/封顶夹取**:先抬到最低费用,再压到封顶值;
5. **取整到分**:支付方向向下截断,退款方向向上取整——取整方向都偏向商户,平台宁可少收。
**退款口径**:退款手续费按原支付时固化的规则快照,对退款金额重算后取负;同一笔支付的累计退款手续费不得超过原支付手续费,超出部分截断,保证全额退款时手续费正好轧平。
## 简单与高级双视图
规则编辑提供两种视图,编辑的是**同一份规则数据**:
- **简单视图**:填一个百分比或固定金额,适合绝大多数常规费率;
- **高级视图**:展开金额区段、混合模式、最低费用、封顶、起征点等完整能力。
两个视图随时切换:简单视图配好的值,在高级视图中就是一段单区段规则;高级视图退化为单段纯百分比时,回到简单视图依旧是一个数。不存在两套数据,不存在视图间转换丢失。
## 实时链校验
保存费率时做两层校验,问题在配置时就暴露,而不是等交易出错:
- **规则自校验**:区段必须从 0 起、首尾相接无缝隙无重叠;最低费用不得大于封顶;混合模式至少一项大于 0;费率取值 0~100(0 合法,表示免费,区别于未配置);
- **层级校验**:按[费率模型](https://doc.plus.daxpay.cn/plus/rate-system/model.md)的层级逐段比对——下级规则的每个区段,其百分比与固定金额都不得低于上级规则中与之交集区段的最大值,出现「倒挂」立即以中文报错拦下,例如「商户费率规则的百分比(0.38)不能低于平台基准费率(0.6)」。
最低费用、单笔封顶、起征点不参与层级比较,它们只约束自己这一层的计算结果。
## 费用落明细
支付与退款成功后,费用异步落明细:
- 每笔支付一条、每笔退款一条负数明细,费率快照与规则摘要一并固化;
- 明细标注费率来源(服务商能力覆盖/服务商方式默认/平台能力覆盖/平台方式默认/未配置),对账时可追溯「这笔费用为什么按这个价收」;
- 未配置的形态不阻断交易,明细以「未配置」留痕,补配费率后可重算补账。
费用明细的查询与筛选见[交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)。
## 常见问题
**封顶怎么算?举例说明。**
例如「0.5%、单笔封顶 20 元」:一笔 10000 元的交易按公式应收 50 元,超过封顶,实收 20 元;一笔 100 元的交易应收 0.5 元,未触及封顶,实收 0.5 元。
**多次部分退款,手续费怎么收?**
每次退款按原支付规则重算该退款金额对应的手续费并取负;累计退款手续费封顶为原支付手续费,退完为止、不多收。
**起征点和最低费用有什么区别?**
起征点看交易金额:低于它整笔免收;最低费用看计算结果:算出的手续费不足它时补足。前者是「小单免收」,后者是「小单保底」。
## 相关链接
- [费率模型与解析链](https://doc.plus.daxpay.cn/plus/rate-system/model.md)
- [运营端·支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)
- [进件配置管理](https://doc.plus.daxpay.cn/plus/onboarding/config.md)
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)
---
# 费率模型与解析链
**源**: https://doc.plus.daxpay.cn/plus/rate-system/model.md
# 费率模型与解析链
> 本页说明 plus 商业版费率体系的分层模型:一条费率如何从平台基准逐层落到商户报价,交易发生时按什么优先级解析。适合平台财务与运营阅读。
## 费率四级链
```mermaid
flowchart TB
P["平台费率
全站基准与兜底"] --> S["服务商费率
微信/支付宝 ISV 产品定价"]
S --> L["一级代理商档 L1
代理商增量层"]
L --> M["商户费率
终端报价"]
```
| 层级 | 语义 |
|------|------|
| 平台费率 | 全站计费的基准层,也是差异化配置缺失时的兜底价;按「支付方式默认 + 产品能力覆盖」两级锚定 |
| 服务商费率 | 微信/支付宝服务商(ISV)产品的差异化定价层:每个服务商一套价目,决定该服务商名下通道商户交易的计费口径;服务商行同时承载商户报价与平台留存参数。直连产品不经过此层,维持平台价 |
| 一级代理商档(L1) | 挂在平台基准之上的增量层:该档与平台基准之间的差额即服务商增量,商户报价与该档之间的差额即代理商可用的差价空间 |
| 商户费率 | 终端报价层,即最终向商户收取手续费的口径 |
分层的目的:同一套通道,平台可以按服务商、按代理商档位、按商户给出不同的价格策略;而所有层都受「下层不得低于上层」的层级校验约束,配置时实时比对(见[费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md))。
## 两级锚定:方式默认与能力覆盖
每一层的费率都由两级锚定组成:
- **方式默认**:按支付方式(如微信小程序、支付宝扫码)配置默认费率;
- **能力覆盖**:按「产品 × 支付能力」做差异覆盖,覆盖时不看方式——例如给「微信服务商版 × 小程序支付」配了覆盖值,就走覆盖值而非方式默认。
服务商价目同样按「方式默认 + 能力覆盖」两段维护;直连产品的费率配置页也已采用与服务商对齐的三层结构(平台基准/代理商档/商户)。
## 解析优先级链
一笔交易发生时,按以下顺序解析生效费率:
```
服务商能力覆盖 → 服务商方式默认 → 平台能力覆盖 → 平台方式默认 → 未配置
```
- 前两级仅对配置了服务商价目的服务商产品生效;命中服务商行即用服务商价,未命中回落平台价;
- 代理商档与商户层报价在分层计价中按同一解析结果展开;
- **未配置不拦截交易**:解析到「未配置」时交易正常成功,费用明细以「未配置」留痕,补配费率后可重算补账。
费率配置变更即时生效,但只影响之后的新交易;每笔交易在支付成功时固化费率快照,历史账单不回溯。
## 费用归属与记账口径
- **商户手续费**:每笔交易按生效费率向商户计收的手续费,是体系内唯一的费用来源;
- **平台留存**:当前口径为商户手续费全额计入平台收入;费用明细同时按各层规则分别记录计费结果,供分层口径的对账分析;
- **纯费用记账**:费用明细只做记账,不回写订单、不做资金实扣、与通道侧费率完全脱钩;退款按原支付时的费率快照生成负数明细。
进件时向通道申报的费率(如当面付费率)是通道回执语义,与平台计费是两套体系,互不影响。
## 配置入口速览
| 配置对象 | 入口(运营端) |
|----------|--------------|
| 直连产品费率 | 支付管理 → 通道与产品配置 → 支付和进件产品,各产品的费率配置页 |
| 服务商费率 | 支付管理 → 通道与产品配置 → 支付和进件产品 → 通道服务商配置 → 服务商费率 |
| 费用明细 | 交易管理 → 交易费用明细 |
具体页面结构与操作步骤见[运营端·支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)。
## 常见问题
**直连产品走哪层费率?**
直连产品没有服务商价目层,按平台费率解析(能力覆盖优先于方式默认),配置入口在「支付管理 → 通道与产品配置」下各直连产品的费率配置页。
**没配费率的交易会被拦截吗?**
不会。未配置只是费用明细留痕「未配置」并空记金额,交易照常成功;补配后可重算补账。
**改了费率,历史订单的费用会变吗?**
不会。费率在支付成功时以快照固化,变更只对新交易生效。
## 相关链接
- [费率规则引擎](https://doc.plus.daxpay.cn/plus/rate-system/engine.md)
- [交易费用明细](https://doc.plus.daxpay.cn/common/trade-fee.md)
- [运营端·支付费率配置](https://doc.plus.daxpay.cn/operation-guide/admin/rate-config.md)
---
# 风控四层防线
**源**: https://doc.plus.daxpay.cn/plus/risk-control/overview.md
# 风控四层防线
> plus 的支付风控由**事前四层防线 + 事后闭环**组成:每笔支付请求在进入交易前逐层校验,命中即拦截;支付成功后还有事后补录与转黑名单机制兜底。策略配置与日常处置见[风控策略与处置](https://doc.plus.daxpay.cn/plus/risk-control/policy.md),交易金额约束见[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)。
## 四层事前防线
| 防线 | 拦截维度 | 说明 | 配置入口 |
|---|---|---|---|
| 一、黑名单 | IP / 支付宝用户 / 微信 OpenId | 命中名单直接拦截,支持设置过期时间与拉黑原因 | 运营端「支付安全 → 黑名单管理」 |
| 二、省市地区 | 买家 IP 归属省份 / 城市 | 按省份或城市名单拦截,另含海外 IP 拦截与地区拦截总开关 | 黑名单管理(省份/城市名单)+ 风控策略「地域限制」 |
| 三、门店围栏 | 支付 IP 归属城市 × 门店所在城市 | 比对买家城市与门店城市,不一致按围栏策略处理 | 风控策略「门店围栏」+ 商户风控配置 |
| 四、用户频率 | 单 IP 日下单笔数 / 单支付账号日下单笔数 | 小额高频刷单防线,超限拦截;账号超限自动转临时黑名单 | 风控策略「频率限制」 |
黑名单与地区名单是**平台级**名单:拉黑识别的是跨商户作案的坏人(IP、羊毛账号),一处拉黑、全平台生效,不按商户拆分。
## 门店围栏:两级门控
围栏默认不生效,需两级都开启:
1. **平台总闸**:风控策略「门店围栏」中开启地理围栏并选定围栏策略;
2. **商户自愿参与**:在商户的风控配置中为该商户单独开启围栏。
三档围栏策略,粒度从紧到松:
| 策略 | 放行范围 |
|---|---|
| 仅允许门店所在市 | 最严,只放行门店城市 |
| 门店市 + 接壤邻市 | 推荐,兼顾跨市消费 |
| 门店市 + 邻市 + 同省 | 最宽,放行同省 |
围栏按 IP 归属城市比对(不做 GPS 定位)。未录入行政区划地址的门店放行(fail-open),避免存量商户因资料不全被误杀;开启围栏前应先补齐门店地址。
## 事后闭环:补录与转黑
事前防线未命中不等于安全,plus 提供两条事后链路:
- **事后补录命中**:开启后,支付成功后补充执行一次风控校验并记录命中情况,只做记录、不影响资金态——用于发现「当时名单还没拉黑、事后已入名单」的交易线索;
- **命中转黑名单**:风险命中记录页支持把命中项一键加入黑名单;账号日限超限与指标检测封禁也会自动产生黑名单(详见[风控策略与处置](https://doc.plus.daxpay.cn/plus/risk-control/policy.md))。
## 频率限制与账号日限
频率限制是第四层防线的具体实现,两个独立开关:
- **IP 日限**:单个客户端 IP 每天下单笔数上限(含未支付),超限拦截;计数为**全平台共享**——同一 IP 换商户下单也会累计,防止灌单;商户可在自己的风控配置中覆盖阈值(只改阈值,不改计数粒度);
- **账号日限**:单个支付账号(微信 OpenId / 支付宝用户)每天下单笔数上限,超限拦截并**自动转临时黑名单**——账号维度全平台唯一,换商户无法绕过。
配套的**指标检测**会定时扫描窗口内订单,未支付笔数超标的 IP 自动封禁一段时间,把高频异常 IP 关进「临时黑名单」。
## 校验流程全景
一笔支付请求的风控校验链如下(限额校验属[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md),一并列出以见全景):
```mermaid
flowchart TD
A["支付请求"] --> B{"风控总开关开启?"}
B -->|否| P["放行"]
B -->|是| C{"黑名单
(IP / 用户标识 / 省市)"}
C -->|命中| R["拦截下单, 记录命中"]
C -->|未命中| D{"地区拦截
(海外 IP / 省市名单)"}
D -->|命中| R
D -->|未命中| E{"门店围栏
(平台总闸 + 商户参与)"}
E -->|城市不符| R
E -->|通过| F{"频率限制
(IP 日限 / 账号日限)"}
F -->|超限| R
F -->|未超限| G{"商户限额
(单笔 / 日周月累计)"}
G -->|超限| R
G -->|通过| P
R --> H["命中记录 + 可转黑名单"]
```
「命中阻断下单」开关可切换整体行为:开启时命中即拒绝下单,关闭时只记录命中、不拦交易(适合观察期);事后补录则在支付成功后再走一次校验留痕。
## 与开源基础版的差异
开源基础版的风控为 IP 级防线;plus 保留全量四层防线(IP 黑名单、用户标识、省市地区、门店围栏)并叠加事后补录、命中转黑、频率限制与账号日限,形成事前事后的完整闭环。
## 常见问题
**围栏开启了但没有拦截效果?**
按序检查:平台总闸与围栏策略是否配置、目标商户是否在自己的风控配置中开启围栏、门店是否已录入行政区划地址(未录地址放行)、买家 IP 归属地解析是否正常(IPv6 场景需开启地区匹配)。
**黑名单为什么没有商户维度?**
名单的语义是识别坏人(跨商户作案),平台级拦截才有效;按商户拆分会让同一个刷单 IP 在别的商户继续作案。商户自己的拒付名单应在其业务系统下单前拦截。
**IP 日限是按商户计数吗?**
不是。IP 日限防的是「该 IP 当日总发起数」,全平台共享计数;商户级差异只体现在阈值覆盖。
## 相关链接
- [风控策略与处置](https://doc.plus.daxpay.cn/plus/risk-control/policy.md)
- [支付安全与风控(运营端操作)](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)
- [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)
- [商户资料与门店(商户端风控只读视角)](https://doc.plus.daxpay.cn/operation-guide/merchant/mch-info.md)
---
# 风控策略与处置
**源**: https://doc.plus.daxpay.cn/plus/risk-control/policy.md
# 风控策略与处置
> 防线模型见[风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)。本页讲风控的日常操作面:策略在哪配、名单怎么管、命中与预警怎么看、命中之后会发生什么以及如何排查。
## 风控策略配置
运营端「支付安全 → 风控策略」是风控的核心配置页,左栏导航按防线维度分八个分区:
| 分区 | 配置内容 |
|---|---|
| 通用与处置 | 风控总开关、IPv6 地区匹配、命中阻断下单、事后补录命中 |
| 名单拦截 | 黑名单拦截开关、用户标识拦截级别(正常/增强) |
| 地域限制 | 海外 IP 拦截、地区拦截开关 |
| 门店围栏 | 地理围栏总闸、三档围栏策略 |
| 频率限制 | IP 日限与账号日限的开关和阈值 |
| 限额兜底 | 平台默认限额模板(见[商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)) |
| 指标检测 | IP 未支付笔数自动封禁、商户成功率预警 |
| 接口安全 | 开放接口 Nonce 防重放与时间窗口校验 |
关键开关说明:
- **风控总开关**:全部事前防线的总闸,关闭后只保留限额校验等非名单类约束;
- **用户标识拦截级别**:正常拦截仅对 JSAPI/小程序等原生支付方式生效;增强拦截对 H5/主扫等场景也强制通过 OAuth 获取用户标识后拦截,覆盖面更广但增加一次授权跳转;
- **命中阻断下单**:决定命中的最终动作是拦截还是仅记录(观察期可关);
- **事后补录命中**:支付成功后补一次校验留痕,不影响资金。
## 黑名单管理
「支付安全 → 黑名单管理」维护平台级名单,支持五种类型:
| 类型 | 名单值形态 | 备注 |
|---|---|---|
| IP | 客户端 IP | 可设过期时间(临时拉黑)与拉黑原因 |
| 支付宝用户 | 支付宝 userId | — |
| 微信 OpenId | 微信 openId | 需选择所属支付应用(OpenId 按应用隔离) |
| 省份 / 城市 | 行政区划选择器 | 即第二层「省市地区」防线的名单 |
名单的三个来源:**人工添加**(本页新增/编辑)、**命中记录转黑**(下文)、**自动产生**(账号日限超限转临时黑名单、指标检测封禁 IP)。过期时间到了名单自动失效,适合临时封禁场景。
## 风险命中记录
「支付安全 → 风险命中记录」是所有防线命中的流水台账:
- **命中阶段**分「事前拦截」与「事后命中」(补录产生);
- **命中类型**覆盖 IP、支付宝用户、微信 OpenId、海外 IP、省份、城市、地理围栏、支付频率超限等;
- 每条记录含交易单号、命中值、买家城市与门店城市(围栏命中时)等上下文;
- 行操作提供**转黑名单**:确认后把该命中值加入对应类型名单,后续交易直接拦截(地理围栏类命中不提供转黑,拦的是位置关系不是身份)。
## 风控预警
「支付安全 → 风控预警」汇集被动发现的异常信号,预警类型有三种:
| 类型 | 触发条件 | 默认处置 |
|---|---|---|
| IP 未支付封禁 | 指标检测发现窗口内未支付笔数超标的 IP | 自动封禁该 IP 一段时间 |
| 商户成功率预警 | 窗口内商户终态订单成功率低于阈值(达样本数门槛才评估) | 仅发预警站内信,不自动关商户 |
| 通道指标预警 | 通道维度指标异常 | 仅预警 |
预警带处理状态(未处理/已处理),供运营逐条确认闭环。运营端 APP 提供风控预警的只读查看,便于移动端跟进。
## 命中后会发生什么
以一笔被拦截的支付为例,完整链路是:
1. **拦截**:命中阻断下单开启时,请求被拒绝,商户收到风控拦截的错误响应;
2. **记录**:一条风险命中记录落库(命中类型、阶段、命中值、上下文);
3. **转黑**:视来源决定——人工在命中记录上转黑、账号日限超限自动转临时黑名单、指标检测自动封禁 IP;
4. **预警**:满足预警条件时生成风控预警,等待运营处理。
若「命中阻断下单」关闭,第 1 步变为放行,但记录照常产生——用于策略上线前的观察期。
## 排查思路
商户反馈「支付被拦截」时,按序排查:
1. 在**风险命中记录**按交易单号或商户筛选,看命中类型与阶段——这直接给出拦截原因;
2. 命中黑名单类,到**黑名单管理**核对名单值与过期时间,确认是误拉还是应拉;
3. 命中围栏类,核对门店行政区划地址与买家 IP 归属城市,确认围栏策略档位是否过严;
4. 命中频率类,核对 IP 日限/账号日限阈值,以及商户是否需要阈值覆盖;
5. 若无命中记录,转查[商户限额](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)或通道路由。
误拦截的纠正路径是移除/过期黑名单、调整策略档位或阈值,不要用关闭「命中阻断下单」来「解决」个案——那会让所有防线失效。
## 常见问题
**转黑名单后多久生效?**
名单实时生效,后续新请求即时拦截;已产生的订单不受影响。
**临时黑名单和普通黑名单的区别?**
临时黑名单带过期时间(自动封禁产生),到期自动失效;普通黑名单长期有效,需人工移除。
**商户能看到被拦截的记录吗?**
能。商户端「风控与限额」页提供本商户的拦截记录只读视图,命中值等敏感信息已脱敏。
## 相关链接
- [风控四层防线](https://doc.plus.daxpay.cn/plus/risk-control/overview.md)
- [支付安全与风控(运营端操作)](https://doc.plus.daxpay.cn/operation-guide/admin/risk-control.md)
- [风控与终端(运营端 APP)](https://doc.plus.daxpay.cn/operation-guide/app/admin/risk.md)
- [商户限额体系](https://doc.plus.daxpay.cn/plus/mch-limit/index.md)