Appearance
API 文档
API Overview
面向客户接入的开放接口文档
本目录按商富通当前开放接口整理，覆盖支付、退款、转账、分账、提现、钱包边界、发票边界、扫码 POS、用户标识获取和常见联调问题。支付网关
覆盖统一下单、查单、关单、渠道用户标识获取、条码换取 openId、支付通知等客户最常用能力。
分账模式
自动分账和手动分账分开说明，下单字段、触发时机和后续查询流程都能直接查到。
字段已校对
支付、用户标识、分账请求字段和状态值均按当前系统控制器、请求模型、响应模型整理，减少联调时字段口径不一致。
WARNING
普通支付网关当前对外 API 域名为 https://pay.yefupay.cn。
扫码 POS 当前按现网部署走商户域名 https://mch.yefupay.cn。
除特别说明外，普通开放接口完整请求地址 = https://pay.yefupay.cn + 接口路径；扫码 POS 接口完整请求地址 = https://mch.yefupay.cn + 接口路径。
交易接口接入顺序
普通收款业务建议按下面顺序接入，先把主链路跑通，再补充退款、分账、转账等资金能力：
| 步骤 | 要做什么 | 关键页面 | 验收标准 |
|---|---|---|---|
| 1 | 获取商户号、应用 ID、应用密钥 | 签名规则 | 本地能生成和平台一致的签名 |
| 2 | 选择支付方式并准备用户标识 | 支付方式总表、支付接口 | 明确 wayCode 和 channelExtra 怎么传 |
| 3 | 调统一下单创建支付单 | 支付接口 | 能拿到 payOrderId 和前端拉起支付参数 |
| 4 | 接收支付通知并查单兜底 | 回调通知 | 后端验签、核对金额、幂等入账 |
| 5 | 接入售后退款 | 退款接口 | 能按退款单号查询最终退款状态 |
| 6 | 按业务需要接分账、提现或转账 | 分账接口、提现接口、转账接口 | 每个资金动作都有状态查询和幂等处理 |
WARNING
前端页面提示、跳转结果、按钮状态都不能作为资金最终结果。支付、退款、转账、分账都以后端通知和主动查询为准。
文档补充内容
- 新增 支付方式总表，覆盖系统内主要
wayCode、所需用户标识字段和典型场景。 - 支付接口补充了当前系统仍保留的兼容下单接口：
/api/pay/aliBarOrder、/api/pay/aliJsapiOrder、/api/pay/ysfBarOrder、/api/pay/ysfJsapiOrder，并明确建议新项目统一走/api/pay/unifiedOrder。 - 分账能力拆成 分账接口 与 分账模式说明，明确自动分账和手动分账怎么接。
- 补充 钱包接口 与 发票接口 说明，先明确当前能力边界，避免客户误把内部钱包、通道余额、会员余额和发票业务混成支付接口。
- 支付文档单独补充了微信
openid、支付宝buyerUserId、银联/云闪付userId的差异，以及“商户自有应用”和“平台/服务商应用”两种接入方式。 - 常见问题页补充了
openid与appId匹配、订单分账与余额处理区别、回调与查单优先级等高频问题。 - 扫码 POS 文档已按当前源码修正为商户域名
https://mch.yefupay.cn，并移除了源码中不存在的独立/api/device/params开放接口描述。
公共请求字段
除跳转授权类接口外，大多数开放接口都需要传以下字段：
| 字段 | 是否必填 | 说明 |
|---|---|---|
version | 是 | 接口版本号，建议固定为 1.0 |
mchNo | 是 | 商户号 |
appId | 是 | 商户应用 ID |
reqTime | 是 | 请求时间戳，建议使用 13 位毫秒值 |
signType | 是 | 签名类型，当前系统支持 MD5、RSA2 |
sign | 是 | 请求签名值 |
WARNING
如果你们客户当前只使用 MD5，也可以继续按 MD5 对接；但文档仍按系统现状保留 RSA2 说明，避免后续升级时字段解释不一致。
公共返回结构
json
{
"code": 0,
"msg": "SUCCESS",
"data": {},
"encryptData": null,
"sign": "RESPONSE_SIGN"
}返回码说明
code | 含义 |
|---|---|
0 | 接口调用成功 |
10 | 系统异常 |
11 | 参数有误 |
12 | 数据库异常 |
9999 | 业务异常，以 msg 为准 |
DANGER
code = 0 只代表“接口调用成功”，不代表“支付成功”或“分账成功”。最终结果必须再看业务状态字段，例如支付单看 state/orderState，退款单看 state，分账看 state。
能力矩阵
| 模块 | 入口页面 | 核心接口 | 适用场景 |
|---|---|---|---|
| 支付网关 | 支付接口 | /api/pay/unifiedOrder | 小程序、公众号、H5、扫码、条码、收银台 |
| 支付方式总表 | 支付方式总表 | wayCode 目录 | 客户选型、前后端字段对齐、联调排查 |
| 退款 | 退款接口 | /api/refund/refundOrder | 全额退款、部分退款、售后 |
| 转账 | 转账接口 | /api/transferOrder | 企业付款、银行卡代付、余额查询 |
| 分账接口 | 分账接口 | /api/division/exec | 自动分账、手动分账、接收方绑定、查询和提现 |
| 提现接口 | 提现接口 | /api/division/receiver/channelBalanceCashout | 分账接收方渠道余额查询与提现 |
| 钱包接口 | 钱包接口 | 能力边界说明 | 内部钱包、通道余额、会员余额的区别 |
| 发票接口 | 发票接口 | 能力边界说明 | 后续开票、查票、红冲、下载的接口规划 |
| 分账模式说明 | 分账模式说明 | divisionMode | 说明 divisionMode=1/2 的选择和流程差异 |
| 扫码 POS | 扫码POS接口 | https://mch.yefupay.cn/api/pos/pay/{version} | 扫码设备、POS、门店终端 |
推荐阅读顺序
说明
- 本站文档以商富通当前开放接口为准。
- 如果客户只接普通支付网关，建议先完成下单、查单、通知和退款，再接分账或转账。