rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7b2f3d77caa937cf2b6e23419ddc858d2fefa183
rui-docs/backend/design/支付模块接口设计.md
T
vifo 7b2f3d77ca docs: 支付模块开发文档 + git 域名更新 
- 新增 backend/design/支付模块架构概览.md
- 新增 backend/design/支付模块数据库设计.md (21张表 DDL)
- 新增 backend/design/支付模块接口设计.md
- git.dev.vifo.cc → git.vifo.cc 全局替换
2026-06-09 01:54:29 +08:00

7.3 KiB
Raw Blame History

支付模块接口设计

来源: ~/rui/支付模块架构设计.md v1.0 创建日期: 2026-06-08 模块: rui-payment

一、接口分层

层级 路径前缀 认证 说明
对外接口 /payment/open/** 需认证 商户/业务系统调用
对外入口 /payment/entry/** 免认证 收银台、扫码支付
第三方回调 /payment/notify/** 免认证 支付/退款异步通知
内部接口 /payment/inner/** @Inner 微服务间调用

二、对外接口（需认证）

2.1 支付交易 /payment/open/trade

统一下单 POST /payment/open/trade/pay

// 请求
{
    "channel": "alipay",               // PayChannel 枚举
    "payType": "app",                   // PayType 枚举
    "merchantOrderNo": "BIZ2026060801", // 业务订单号
    "subject": "商品标题",
    "body": "商品描述",
    "amount": 100.00,                   // BigDecimal，元
    "currency": "CNY",
    "notifyUrl": "https://xxx/notify",
    "returnUrl": "https://xxx/return",
    "clientIp": "127.0.0.1",
    "userId": "oXXXXXXXX"               // 微信 JSAPI 需要 openid
}

// 响应
{
    "code": 200,
    "data": {
        "success": true,
        "channelOrderNo": null,
        "payParams": {                   // 支付宝 APP
            "orderInfo": "alipay_sdk=..."
        },
        // 或 "payUrl": "<form>...</form>",   // 支付宝 H5/PC
        // 或 "payQrCode": "weixin://...",     // 微信 Native
        // 或 "payParams": {"prepayId": "..."} // 微信 JSAPI
    }
}

统一执行入口 POST /payment/open/trade/execute

支持所有渠道和动作的通用入口。

// 请求
{
    "channel": "alipay",
    "action": "query",
    "merchantOrderNo": "PAY20260608001"
}

// 响应 — 查询示例
{
    "code": 200,
    "data": {
        "success": true,
        "channelOrderNo": "20260608...",
        "payParams": {
            "tradeStatus": "TRADE_SUCCESS",
            "totalAmount": "100.00"
        }
    }
}

详细的 PayRequest/PayResponse 字段说明和每个 Action 的请求/返回示例见 rui-payment-provider/API.md。

2.2 退款 /payment/open/refund

接口 方法 说明
/payment/open/refund/apply POST 申请退款
/payment/open/refund/{refundNo} GET 查询退款单

申请退款 POST /payment/open/refund/apply

// 请求 PayRefundApplyRequest
{
    "orderNo": "PAY20260608001",
    "refundAmount": 50.00,
    "refundReason": "用户申请退款",
    "notifyUrl": "https://xxx/refund_notify"
}

// 响应 PayRefundVO
{
    "code": 200,
    "data": {
        "refundNo": "REF20260608001",
        "orderNo": "PAY20260608001",
        "refundAmount": 50.00,
        "refundStatus": 0,                // 0:退款中 1:退款成功 2:退款失败
        "channelRefundNo": null
    }
}

2.3 分账 /payment/open/split

接口 方法 说明
/payment/open/split/create POST 创建分账订单
/payment/open/split/{splitNo} GET 查询分账订单
/payment/open/split/execute/{splitNo} POST 执行分账（手动触发）
/payment/open/split/return/{splitNo} POST 回退分账

创建分账订单 POST /payment/open/split/create

// 请求 SplitOrderCreateRequest
{
    "orderNo": "PAY20260608001",
    "splitReceivers": [
        {
            "receiverId": 1,
            "receiverType": 1,
            "receiverName": "商户A",
            "amount": 30.00,
            "rate": 0.30
        }
    ]
}

2.4 商户进件 /payment/open/merchant

接口 方法 说明
/payment/open/merchant/apply POST 提交商户入驻申请
/payment/open/merchant/{merchantNo} GET 查询商户信息
/payment/open/merchant/{merchantNo} PUT 更新商户信息
/payment/open/merchant/qualification/upload POST 提交资质材料
/payment/open/merchant/qualification/{merchantNo} GET 查询资质列表
/payment/open/merchant/audit/{merchantNo} GET 查询审核记录
/payment/open/merchant/channel/{merchantNo} GET 查询渠道配置
/payment/open/merchant/channel/apply POST 申请渠道开通
/payment/open/merchant/settle/{merchantNo} GET 查询结算配置
/payment/open/merchant/settle/{merchantNo} PUT 更新结算配置

三、对外入口（免认证）

/payment/entry

接口 方法 说明
/payment/entry/cashier/{orderNo} GET 收银台页面（H5）
/payment/entry/scan POST 扫码支付

四、第三方回调（免认证）

/payment/notify

接口 方法 说明
/payment/notify/alipay POST 支付宝支付回调
/payment/notify/wechat_pay POST 微信支付回调（JSON body）
/payment/notify/unionpay POST 银联支付回调
/payment/notify/alipay/refund POST 支付宝退款回调
/payment/notify/wechat_pay/refund POST 微信退款回调（JSON body）

支付宝回调

POST /payment/notify/alipay
Content-Type: application/x-www-form-urlencoded

out_trade_no=PAY20260608001&trade_no=20260608...&trade_status=TRADE_SUCCESS&total_amount=100.00&...
  • 返回纯文本 "success" 表示成功，"fail" 表示失败

微信回调

POST /payment/notify/wechat_pay
Content-Type: application/json

{"id":"xxx","create_time":"...","resource_type":"encrypt-resource","event_type":"TRANSACTION.SUCCESS","resource":{...}}
  • 请求头携带 Wechatpay-Serial, Wechatpay-Nonce, Wechatpay-Signature, Wechatpay-Timestamp
  • 返回 JSON {"code":"SUCCESS","message":"成功"}

五、内部接口（@Inner）

/payment/inner

接口 方法 说明
/payment/inner/order/status/{orderNo} GET 查询支付状态
/payment/inner/order/biz/{bizOrderNo} GET 根据业务订单号查询
/payment/inner/order/create POST 创建支付订单（内部调用）

六、管理后台接口

6.1 支付渠道管理 /payment/admin/channel

接口 方法 说明
/payment/admin/channel/list GET 渠道列表
/payment/admin/channel/{id} GET 渠道详情
/payment/admin/channel POST 新增渠道
/payment/admin/channel/{id} PUT 修改渠道
/payment/admin/channel/{id}/enable PUT 启用渠道
/payment/admin/channel/{id}/disable PUT 停用渠道

6.2 代理商管理 /payment/admin/agent

接口 方法 说明
/payment/admin/agent/list GET 代理商列表
/payment/admin/agent/{id} GET 代理商详情
/payment/admin/agent POST 新增代理商
/payment/admin/agent/{id} PUT 修改代理商
/payment/admin/agent/{id}/commission GET 佣金记录
/payment/admin/agent/{id}/settlement GET 结算记录

6.3 结算管理 /payment/admin/settle

接口 方法 说明
/payment/admin/settle/list GET 结算单列表
/payment/admin/settle/{id} GET 结算单详情
/payment/admin/settle/generate POST 生成结算单
/payment/admin/settle/{id}/confirm POST 确认结算
Reference in New Issue View Git Blame Copy Permalink