余额分账业务接入指引

本文档为开放平台余额分账模块的业务接入指引，涵盖 B2B 转账、提现、余额查询等功能。
接口路径前缀：/v1/openpay/account。
转账和提现接口为异步处理：提交后通过查询接口获取处理结果，也可配置异步回调通知。

一、功能概览

余额分账模块提供以下核心能力：

功能	说明	接口编号
B2B 转账	商户钱包余额之间的转账	4.4.1.1
转账查询	查询转账订单状态和结果	4.4.1.2
余额查询	查询商户钱包账户余额	4.4.2.1
提现	商户钱包余额提现至银行卡	4.4.3.1
提现查询	查询提现订单状态和结果	4.4.3.2
查询提现银行卡	查询已绑定的提现银行卡列表	4.4.3.3

前置条件：使用余额分账功能前，商户需已完成入网并开通余额分账功能（分账模式 splitMode=2）。

二、公共说明

2.1 请求格式

所有接口统一使用 OpenApiRequest<T> 包装：

{
  "reqBody": {
    // 业务请求参数
  }
}

2.2 响应格式

所有接口统一使用 OpenApiResponse<T> 包装：

{
  "code": "SUCCESS",
  "msg": "成功",
  "data": {
    // 业务响应数据
  }
}

2.3 认证与商户号（merchantNo）规则

所有接口需携带 API Key 进行认证（@SaCheckApiKey）。

merchantNo 处理规则：

当前商户类型	merchantNo 是否必填	说明
普通商户（NORMAL）	否	系统从登录上下文自动获取，调用方无需传入
品牌商户（BRAND）	是	传入目标下属商户号，系统校验归属关系
服务商商户（PROXY）	是	传入目标下属商户号，系统校验归属关系

归属关系校验：目标商户的 merchantPno 必须等于当前登录商户号，否则拒绝请求。
即：品牌/服务商商户只能代操作其下属商户的业务。

2.4 金额单位

所有金额字段统一使用分为单位。

2.5 幂等控制

转账和提现接口使用 bizFlowNo（商户请求流水号）进行幂等控制：

同一商户号下 2 天内 不允许重复

重复提交将直接拒绝，返回"bizFlowNo已存在"

三、B2B 转账

3.1 流程说明

B2B 转账用于实现商户钱包余额之间的资金划转：

调用方发起转账请求（接口编号 4.4.1.1），指定付款方、收款方和转账金额。

系统同步调用通道完成转账，返回提交结果。

转账成功后系统自动生成转出方（OUT）和转入方（IN）两条流水记录。

如配置了 notifyUrl，订单状态变更时系统会异步回调通知。

通过转账查询接口（接口编号 4.4.1.2）查询最终结果。

注意：本接口为同步接口，应答中 status 为 SUCCESS 表示转账已成功，FAIL 表示失败。

3.2 接口列表

接口编号	接口路径	方法名	说明
4.4.1.1	`POST /v1/openpay/account/transfer`	transfer	B2B 转账
4.4.1.2	`POST /v1/openpay/account/transfer/query`	transferQuery	转账查询

3.3 转账请求参数（4.4.1.1）

字段	类型	必填	说明
merchantNo	String	条件必填	商户号。普通商户无需传入；品牌/服务商商户必填（目标下属商户号）
bizFlowNo	String	是	商户请求流水号，2天内唯一
fromMerchantNo	String	是	付款方商户号
toMerchantNo	String	是	收款方商户号
orderAmount	Long	是	转账金额（分），必须大于 0
usage	String	否	转账用途
notifyUrl	String	否	异步通知地址，订单状态变更时回调

3.4 转账响应参数

字段	类型	说明
bizFlowNo	String	商户请求流水号
orderNo	String	收呗订单号
status	String	平台状态，见枚举表
orderAmount	Long	转账金额（分），仅成功时返回
fee	Long	手续费（分）
trxTime	String	交易时间，格式 yyyy-MM-dd HH:mm:ss
accountTime	String	入账时间，格式 yyyy-MM-dd HH:mm:ss
failReason	String	失败原因，仅 status=FAIL 时返回

3.5 转账查询请求参数（4.4.1.2）

字段	类型	必填	说明
merchantNo	String	条件必填	商户号。普通商户无需传入；品牌/服务商商户必填（目标下属商户号）
bizFlowNo	String	二选一	商户请求流水号
orderNo	String	二选一	收呗订单号

3.6 转账查询响应参数

字段	类型	说明
bizFlowNo	String	商户请求流水号
orderNo	String	收呗订单号
status	String	平台状态，见枚举表
orderAmount	Long	订单金额（分）
fee	Long	手续费（分）
trxTime	String	交易时间
accountTime	String	入账时间
fromMerchantNo	String	付款方商户号
toMerchantNo	String	收款方商户号
failReason	String	失败原因，仅失败时返回

3.7 时序图

四、余额查询

4.1 流程说明

余额查询用于获取商户钱包账户的可用余额信息：

调用余额查询接口（接口编号 4.4.2.1），查询当前商户的账户余额。

返回余额（分）和账户状态。

4.2 接口列表

接口编号	接口路径	方法名	说明
4.4.2.1	`POST /v1/openpay/account/balance/query`	queryBalance	余额查询

4.3 请求参数

无需传入业务参数，merchantNo 由系统自动获取。

4.4 响应参数

字段	类型	说明
balance	Long	余额（分）
accountStatus	String	账户状态，见账户状态枚举表

4.5 时序图

五、提现

5.1 流程说明

提现用于将商户钱包余额提现至绑定的银行卡账户：

调用方发起提现请求（接口编号 4.4.3.1），指定提现金额和结算银行卡。

未指定结算卡号时，默认使用商户结算账户卡号。

系统调用通道完成提现，返回提交结果。

如配置了 notifyUrl，订单状态变更时系统会异步回调通知。

通过提现查询接口（接口编号 4.4.3.2）查询最终结果。

注意：本接口为异步接口，应答仅代表提现请求已提交至通道，最终结果请通过查询接口确认。

5.2 接口列表

接口编号	接口路径	方法名	说明
4.4.3.1	`POST /v1/openpay/account/withdraw`	withdraw	提现
4.4.3.2	`POST /v1/openpay/account/withdraw/query`	withdrawQuery	提现查询
4.4.3.3	`POST /v1/openpay/account/withdraw/cards`	withdrawCards	查询提现银行卡

5.3 提现请求参数（4.4.3.1）

字段	类型	必填	说明
merchantNo	String	条件必填	商户号。普通商户无需传入；品牌/服务商商户必填（目标下属商户号）
bizFlowNo	String	是	商户请求流水号，2天内唯一
orderAmount	Long	是	提现金额（分），必须大于 0
bankAccountNo	String	否	提现银行卡号，未传时取商户结算账户卡号
remark	String	否	备注
notifyUrl	String	否	异步通知地址，订单状态变更时回调

5.4 提现响应参数

字段	类型	说明
bizFlowNo	String	商户请求流水号
orderNo	String	收呗订单号
status	String	平台状态，见枚举表
trxTime	String	交易时间，格式 yyyy-MM-dd HH:mm:ss
accountTime	String	入账时间，格式 yyyy-MM-dd HH:mm:ss
failReason	String	失败原因，仅 status=FAIL 时返回

5.5 提现查询请求参数（4.4.3.2）

字段	类型	必填	说明
merchantNo	String	条件必填	商户号。普通商户无需传入；品牌/服务商商户必填（目标下属商户号）
bizFlowNo	String	二选一	商户请求流水号
orderNo	String	二选一	收呗订单号

5.6 提现查询响应参数

字段	类型	说明
bizFlowNo	String	商户请求流水号
orderNo	String	收呗订单号
status	String	平台状态，见枚举表
orderAmount	Long	订单金额（分）
fee	Long	手续费（分）
trxTime	String	交易时间
accountTime	String	入账时间
isReversed	Boolean	是否有退返标记
failReason	String	失败原因，仅失败时返回

5.7 查询提现银行卡（4.4.3.3）

通过本接口可查询商户已绑定的提现银行卡列表，供提现时选择结算账户。

请求参数：无需传入业务参数。

响应：返回银行卡列表（包含卡号、银行名称等信息）。

5.8 时序图

六、异步回调通知

6.1 通知机制

当订单状态发生变更时，系统会向调用方传入的 notifyUrl 发起 POST 回调通知。回调采用统一请求体（OpenApiRequest）+ RSA 签名格式，与开放平台 API 请求格式一致。

6.2 通知触发时机

场景	触发条件
同步返回	提交接口同步返回终态（SUCCESS/FAIL）时立即推送
主动查询	查询接口检测到状态从非终态 → 终态时推送
异步回调	通道异步回调到达时推送

6.3 重试策略

推送失败后自动重试，采用指数退避：1分钟 → 5分钟 → 30分钟 → 2小时 → 6小时，最多重试 5 次。对接方返回 success 视为推送成功。

6.4 通知报文格式

回调报文采用统一请求体包装，业务字段位于 reqBody 中：

{
  "requestId": "请求ID（用于问题追踪）",
  "timestamp": "时间戳（毫秒）",
  "nonce": "随机字符串（16-36位）",
  "sign": "RSA签名值",
  "reqBody": { ... }
}

转账回调 reqBody：

字段	类型	必返回	说明
bizFlowNo	String	是	商户请求流水号
channelOrderNo	String	是	通道订单号
bizOrderNo	String	是	业务订单号
merchantNo	String	是	商户号
orderAmount	Long	是	转账金额（分）
fee	Long	是	手续费（分）
orderStatus	Integer	是	状态码：0=处理中，1=成功，2=失败
status	String	是	PROCESSING / SUCCESS / FAIL
bizType	String	是	固定值 `transfer`
payerMerchantNo	String	否	付款方商户号
payerMerchantName	String	否	付款方商户名称
payeeMerchantNo	String	否	收款方商户号
payeeMerchantName	String	否	收款方商户名称
trxTime	String	否	交易时间，仅成功时返回
accountTime	String	否	入账时间，仅成功时返回
failReason	String	否	失败原因，仅失败时返回

提现回调 reqBody：

字段	类型	必返回	说明
bizFlowNo	String	是	商户请求流水号
channelOrderNo	String	是	通道订单号
bizOrderNo	String	是	业务订单号
merchantNo	String	是	商户号
orderAmount	Long	是	提现金额（分）
fee	Long	是	手续费（分）
orderStatus	Integer	是	状态码：0=处理中，1=成功，2=失败
status	String	是	PROCESSING / SUCCESS / FAIL
bizType	String	是	固定值 `withdraw`
trxTime	String	否	交易时间，仅成功时返回
accountTime	String	否	入账时间，仅成功时返回
failReason	String	否	失败原因，仅失败时返回

报文示例（转账成功）：

{
  "requestId": "cb-20260820-001",
  "timestamp": "1755676200000",
  "nonce": "a1b2c3d4e5f6g7h8",
  "sign": "MIIEvgIBADANBgkqhkiG9w0BAQEFA...",
  "reqBody": {
    "bizFlowNo": "TF20260820001",
    "channelOrderNo": "YE20260820123456789",
    "bizOrderNo": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "merchantNo": "M100001",
    "orderAmount": 100000,
    "fee": 10,
    "orderStatus": 1,
    "status": "SUCCESS",
    "bizType": "transfer",
    "payerMerchantNo": "M100001",
    "payerMerchantName": "付款方公司",
    "payeeMerchantNo": "M100002",
    "payeeMerchantName": "收款方公司",
    "trxTime": "2026-08-20 14:30:00",
    "accountTime": "2026-08-20 14:30:05"
  }
}

6.5 验签

对接方需使用平台 RSA 公钥对回调通知进行验签，确保通知来源可信。验签步骤：

提取外层 JSON 中的 sign 字段

将剩余字段按 key ASCII 升序排列，拼接为 key1=value1&key2=value2&...（空值不参与签名，嵌套对象需平铺）

对拼接字符串做 MD5 摘要

使用平台公钥对 sign 进行 RSA 验签

对接方可复用已有的 API 签名验签工具（OpenApiSignKit.verify）。

6.6 通知确认

调用方收到通知后需返回字符串 success（不区分大小写），系统将标记推送成功。若未返回 success，系统将按重试策略继续推送。对接方需根据 reqBody.bizFlowNo + reqBody.status 做幂等处理。

详细的回调接口文档请参见《转账提现回调通知接口文档》。

七、核心枚举速查

7.1 转账状态（SbTransferStatusEnum）

状态码	说明
PROCESSING	处理中
CHANNEL_ACCEPTED	通道已受理
SUCCESS	转账成功
FAIL	转账失败

7.2 提现状态（SbWithdrawStatusEnum）

状态码	说明
PROCESSING	处理中
CHANNEL_ACCEPTED	通道已受理
SUCCESS	提现成功
FAIL	提现失败
REFUNDED	已退返

7.3 账户状态（AccountStatusEnum）

状态码	说明
INIT	未激活
NORMAL	正常
FROZEN	冻结
CANCELLED	已注销

附录：接口总览

Open API 余额分账接口索引

接口编号	模块	接口路径	说明
4.4.1.1	转账	`/v1/openpay/account/transfer`	B2B 转账
4.4.1.2	转账	`/v1/openpay/account/transfer/query`	转账查询
4.4.2.1	余额	`/v1/openpay/account/balance/query`	余额查询
4.4.3.1	提现	`/v1/openpay/account/withdraw`	提现
4.4.3.2	提现	`/v1/openpay/account/withdraw/query`	提现查询
4.4.3.3	提现	`/v1/openpay/account/withdraw/cards`	查询提现银行卡

注意事项

merchantNo 规则：普通商户无需传入，系统自动获取；品牌/服务商商户必须传入目标下属商户号，系统校验归属关系（详见 2.3 节）。

bizFlowNo 唯一性：同一商户号下 2 天内不允许重复，建议调用方使用带业务含义的唯一流水号（如 业务前缀_日期_自增序号）。

手续费：转账和提现可能产生手续费，具体金额以查询接口返回为准。

提现退返：提现可能因银行原因退返，查询接口通过 isReversed 字段标识，状态为 REFUNDED。

异步通知可靠性：建议调用方同时使用主动查询接口作为兗底，不应完全依赖异步通知。

3.2 余额分账业务接入指引

余额分账业务接入指引#

一、功能概览#

二、公共说明#

2.1 请求格式#

2.2 响应格式#

2.3 认证与商户号（merchantNo）规则#

2.4 金额单位#

2.5 幂等控制#

三、B2B 转账#

3.1 流程说明#

3.2 接口列表#

3.3 转账请求参数（4.4.1.1）#

3.4 转账响应参数#

3.5 转账查询请求参数（4.4.1.2）#

3.6 转账查询响应参数#

3.7 时序图#

四、余额查询#

4.1 流程说明#

4.2 接口列表#

4.3 请求参数#

4.4 响应参数#

4.5 时序图#

五、提现#

5.1 流程说明#

5.2 接口列表#

5.3 提现请求参数（4.4.3.1）#

5.4 提现响应参数#

5.5 提现查询请求参数（4.4.3.2）#

5.6 提现查询响应参数#

5.7 查询提现银行卡（4.4.3.3）#

5.8 时序图#

六、异步回调通知#

6.1 通知机制#

6.2 通知触发时机#

6.3 重试策略#

6.4 通知报文格式#

6.5 验签#

6.6 通知确认#

七、核心枚举速查#

7.1 转账状态（SbTransferStatusEnum）#

7.2 提现状态（SbWithdrawStatusEnum）#

7.3 账户状态（AccountStatusEnum）#

附录：接口总览#

Open API 余额分账接口索引#

注意事项#