技术文档

Appearance

2026-01-25
1138
4.1m

文档规范 ​

这个问题已经非常明确地进入“支付机构级 OpenAPI 产品与能力建模”层面了，而不是单纯的技术设计。 我会站在“支付机构（PSP）+ 商户 / 代理 / 收单机构”视角，把资源层（Resource Layer）如何拆分模块、每个模块有哪些能力、为何这样拆，一次性给你一个**可以直接作为《开放平台能力地图》**的答案。

一、设计前的统一原则（非常关键） ​

在支付机构的开放接口中，资源层不是“接口列表”，而是“对外能力的系统化拆解”。

三个硬原则 ​

  1. 按资金与责任边界拆
  2. 按参与角色拆z
  3. 按交易生命周期拆

❗ 不按“内部系统结构”拆 ❗ 不按“代码服务”拆 ❗ 不按“历史模块”拆

二、支付机构 OpenAPI 资源层总体结构（一级模块） ​

text
OpenAPI 资源能力体系（支付机构）
│
├─ 1️⃣ 商户与主体资源（Merchant & Subject）
├─ 2️⃣ 交易与订单资源（Order & Transaction）
├─ 3️⃣ 支付执行资源（Payment Execution）
├─ 4️⃣ 资金与账户资源（Account & Balance）
├─ 5️⃣ 清结算与对账资源（Settlement & Reconciliation）
├─ 6️⃣ 退款与逆向资源（Refund & Reversal）
├─ 7️⃣ 风控与合规模块（Risk & Compliance）
├─ 8️⃣ 费率与计费资源（Pricing & Fee）
├─ 9️⃣ 通知与回调资源（Notify & Webhook）
├─ 🔟 代理 / 渠道资源（Agent & Acquirer）
├─ ⓫ 平台运维与查询资源（Operation & Query）

这套拆法天然支持：

  • 商户直连
  • 代理接入
  • 收单机构接入
  • 多角色共存

三、一级模块逐个讲清楚（重点） ​

1️⃣ 商户与主体资源（Merchant & Subject） ​

设计目的 ​

解决“谁在用你平台”

典型资源 ​

text
Merchant
├─ 商户创建 / 查询
├─ 商户状态（启用 / 冻结）
├─ 商户资质信息
├─ 商户绑定代理

接入角色 ​

角色权限
商户查自己
代理管辖商户
收单查通道商户

2️⃣ 交易与订单资源（Order & Transaction） ​

设计目的 ​

统一所有交易行为的起点

核心资源 ​

text
Order
├─ 支付订单创建
├─ 订单查询
├─ 订单状态

设计关键点 ​

  • 所有支付动作必须有订单
  • 订单与资金动作解耦
  • 订单是审计主线

3️⃣ 支付执行资源（Payment Execution） ​

设计目的 ​

真正触发资金流动

子资源 ​

text
Payment
├─ 发起支付
├─ 支付确认
├─ 支付结果查询
├─ 支付关闭

说明 ​

  • 可能对应多个通道
  • 与订单一对多
  • 可异步

4️⃣ 资金与账户资源（Account & Balance） ​

设计目的 ​

钱在哪？能不能用？

资源拆分 ​

text
Account
├─ 账户信息
├─ 可用余额
├─ 冻结余额
text
Ledger
├─ 资金流水查询
├─ 分录记录

非常重要 ​

❗ 不允许直接“改余额” ❗ 余额只由交易结果驱动

5️⃣ 清结算与对账资源（Settlement & Reconciliation） ​

设计目的 ​

交易完成后的资金归集与核对

子模块 ​

text
Settlement
├─ 清算结果
├─ 结算批次
├─ 出账记录
text
Reconciliation
├─ 对账单下载
├─ 差错查询

6️⃣ 退款与逆向资源（Refund & Reversal） ​

设计目的 ​

交易逆向能力

资源 ​

text
Refund
├─ 退款申请
├─ 退款查询

特别说明 ​

  • 必须关联原订单
  • 走独立风控
  • 独立权限

7️⃣ 风控与合规资源（Risk & Compliance） ​

设计目的 ​

平台安全生命线

资源示例 ​

text
Risk
├─ 风控校验结果查询
├─ 风险拦截原因
text
Compliance
├─ KYC 状态
├─ 限额查询

8️⃣ 费率与计费资源（Pricing & Fee） ​

设计目的 ​

钱怎么收？怎么分？

资源 ​

text
Fee
├─ 费率配置查询
├─ 交易手续费明细

9️⃣ 通知与回调资源（Notify & Webhook） ​

设计目的 ​

异步状态同步

资源 ​

text
Webhook
├─ 回调地址配置
├─ 回调日志
├─ 重试记录

🔟 代理 / 渠道资源（Agent & Acquirer） ​

设计目的 ​

多级角色管理

资源 ​

text
Agent
├─ 代理信息
├─ 下级商户
├─ 分润信息
text
Acquirer
├─ 通道能力
├─ 通道状态

⓫ 平台运维与查询资源（Operation & Query） ​

设计目的 ​

只读 + 运维

资源 ​

text
Query
├─ 交易查询
├─ 统计汇总

四、资源与角色的映射关系（很重要） ​

text
资源模块         商户   代理   收单
---------------------------------
商户主体           ✔     ✔     ✔
订单 / 交易        ✔     ✔     ✔
支付执行           ✔     ✔     ✔
账户 / 余额        ✔     ✔     ✖
清结算             ✔     ✔     ✔
退款               ✔     ✔     ✔
风控               部分  部分  ✔
费率               ✔     ✔     ✔
通知               ✔     ✔     ✖
代理管理           ✖     ✔     ✖

五、这套拆分方式的“长期价值” ​

1️⃣ 权限天然清晰 ​

text
角色 → 资源模块 → 接口

2️⃣ 非常利于产品文档输出 ​

  • 一级模块 = 能力目录
  • 二级模块 = 功能说明
  • 接口 = 实现

3️⃣ 便于监管解释 ​

“我们对外开放的只是交易能力接口， 不开放核心账务写接口。”