易支付SaaS接口 - 支持子商户自动进件与结算

一、核心能力定位

易支付 SaaS 接口通过 “自动化进件接口 + 灵活结算配置 + 实时状态同步”，解决 SaaS 平台子商户 “入驻慢、审核繁、结算乱” 痛点，实现：

• 子商户无需单独注册易支付账号，通过 SaaS 平台一键提交资料完成进件；

• 进件审核最快 1 分钟完成（自动校验场景），支持异步通知结果；

• 结算规则可按需配置（分账比例、结算周期、手续费承担方），资金自动清算至子商户账户。

二、子商户自动进件：接口化对接，零人工干预

（一）进件接口分类与适配场景

易支付提供 3 类标准化进件接口，覆盖不同类型子商户，SaaS 平台可根据子商户类型选择调用：

（二）自动进件全流程（以企业子商户为例）

1. 前置准备：SaaS 平台授权配置

• SaaS 平台需先完成易支付服务商资质认证，获取parentMerchantNo（代理商编号）、x-yop-appkey（应用标识）、API 签名密钥；

• 在易支付后台配置 “子商户进件回调地址”（notifyUrl），用于接收进件状态异步通知。

2. 核心接口调用：特约商户入网接口（V2.0）

（1）请求参数规范（必填项 + 可选项）

{
"requestNo": "YBRWQQH202511280001", // 入网请求号（SaaS自定义，唯一标识）
"parentMerchantNo": "10080011235",  // SaaS平台服务商编号（易支付分配）
"businessRole": "ORDINARY_MERCHANT", // 商户角色（默认普通商户）
"merchantSubjectInfo": {
"licenceUrl": "https://saas-platform.com/upload/licence.jpg", // 营业执照图片地址（需先调用文件上传接口）
"signName": "XX科技有限公司", // 商户签约名（与营业执照一致）
"signType": "ENTERPRISE", // 签约类型：ENTERPRISE(企业)/INDIVIDUAL(个体)
"licenceNo": "91440101MA9X7XXXX", // 统一社会信用代码
"shortName": "XX科技" // 商户简称（支付页面展示）
},
"merLegalInfo": { // 法人信息
"legalName": "张三",
"legalIdCard": "4401051990XXXX1234",
"merLegalPhone": "13800138000", // 法人手机号（用于短信授权）
"merLegalEmail": "zhangsan@xx.com"
},
"settlementInfo": { // 结算账户信息
"cardNo": "62220810010XXXX1234", // 对公账户/法人个人账户
"headBankCode": "102100099996", // 开户总行编码（参考易支付银行编码表）
"bankCity": "440100" // 开户城市编码（省市区编码需符合易支付规范）
},
"notifyUrl": "https://saas-platform.com/notify/merchant/onboarding", // 进件结果回调地址
"merLevel1No": "01", // 一级行业分类编码（参考易支付行业编码表）
"merLevel2No": "0101" // 二级行业分类编码
}

（2）接口调用关键注意事项

1. 图片资料（营业执照、身份证）需先调用易支付 “文件上传接口” 获取合法 URL，再传入进件接口，支持 JPG/PNG 格式（单张≤5MB）；

2. requestNo为唯一标识，申请状态非 “驳回” 时不可重复使用；若驳回，可复用该编号重新提交（子商户编号不变）；

3. 个人商户需额外指定merAuthorizeType（授权类型）：SMS_AUTHORIZE（短信授权，法人需回复验证码）或WEB_AUTHORIZE（页面授权，无需短信）。

（3）返回结果与状态说明

接口调用后即时返回初步校验结果，包含核心字段：

{
"requestNo": "YBRWQQH202511280001",
"applicationNo": "TYSHRW20251128999999", // 易支付进件申请单编号
"applicationStatus": "REVIEWING", // 申请状态：REVIEWING(审核中)/AUTHENTICITY_VERIFYING(真实性验证中)
"merchantNo": "100800112350001", // 易支付子商户编号（生成后永久不变）
"message": "参数校验通过，进入自动审核流程"
}

（三）进件状态同步：主动查询 + 异步通知

1. 主动查询接口：SaaS 平台可通过商户状态查询接口实时获取进件进度，接口地址：GET https://openapi.yeepay.com/yop-center/rest/v1.0/sys/merchant/queryCustApply，参数为requestNo或merchantNo；

2. 异步通知回调：进件状态变更（审核通过 / 驳回 / 待签约）时，易支付会向配置的notifyUrl推送通知，示例回调参数：

{
"requestNo": "YBRWQQH202511280001",
"applicationNo": "TYSHRW20251128999999",
"applicationStatus": "COMPLETED", // 最终状态：COMPLETED(成功)/REVIEW_BACK(驳回)
"merchantNo": "100800112350001",
"auditOpinion": "审核通过", // 驳回时返回具体原因（如“营业执照过期”）
"agreementUrl": "https://openapi.yeepay.com/agreement/sign/xxx" // 待签约时返回签约地址
}

3. 异常处理：若子商户未收到签约短信，可调用签约短信重发接口重新推送，接口地址：POST https://openapi.yeepay.com/yop-center/rest/v1.0/sys/merchant/resendSms。

（四）进件资质校验规则（降低驳回率）

• 自动校验项：身份证号真实性（对接公安接口）、银行卡四要素校验（姓名 + 卡号 + 开户行 + 预留手机号）、营业执照编码有效性；

• 格式要求：图片需清晰无遮挡（像素≥800×600），企业名称与营业执照完全一致，银行编码需使用易支付标准编码（可通过接口下载编码表）；

• 驳回重提：子商户资料驳回后，SaaS 平台可通过原requestNo重新调用进件接口提交修正资料，无需重新生成商户编号。

三、子商户结算体系：灵活配置，自动清算

（一）结算规则配置接口

SaaS 平台可通过易支付 “结算规则配置接口”，为单个或批量子商户设置结算参数，接口地址：POST https://openapi.yeepay.com/yop-center/rest/v1.0/sys/settlement/rule/set，核心配置项：

（二）结算流程与接口联动

1. 交易分账实时触发：子商户完成交易后，易支付自动按配置的分账规则拆分资金：

• 子商户应收金额 = 交易金额 - 易支付渠道费率 - SaaS 平台抽成；

• 资金实时计入子商户 “待结算金额”，SaaS 平台抽成计入 “平台收益账户”。

2. 自动结算执行：

• 结算日（如 T+1 的次日）易支付系统自动筛选 “待结算金额≥门槛” 的子商户；

• 生成结算单（含交易总金额、手续费、分账金额、实际到账金额）；

• 资金自动转账至子商户绑定的银行账户（对公 / 个人），并推送结算通知（短信 + SaaS 平台回调）。

3. 结算查询与对账：

• 子商户可通过 SaaS 平台查询结算明细，易支付提供 “子商户结算单下载接口”：GET https://openapi.yeepay.com/yop-center/rest/v1.0/sys/settlement/bill/download；

• SaaS 平台可调用 “对账接口” 获取全量子商户结算数据，接口地址：GET https://openapi.yeepay.com/yop-center/rest/v1.0/sys/settlement/reconciliation/download，支持按日期范围查询。

（三）异常场景处理

• 结算失败：银行账户信息错误导致打款失败时，易支付会触发 3 次重试（间隔 24 小时），仍失败则暂停结算并推送 “结算失败通知”，SaaS 平台需引导子商户更新银行卡信息；

• 大额结算审核：子商户单日结算金额≥5 万元时，易支付触发人工审核，审核通过后再打款，确保资金安全；

• 分账调整：如需调整分账比例，SaaS 平台可重新调用 “结算规则配置接口”，新规则自下一笔交易起生效。

四、关键接口调用示例（Java SDK）

（一）企业子商户进件示例（V2.0 接口）

import com.yeepay.yop.sdk.service.mer.MerClient;
import com.yeepay.yop.sdk.service.mer.MerClientBuilder;
import com.yeepay.yop.sdk.service.mer.request.RegisterSaasMerchantV2Request;
import com.yeepay.yop.sdk.service.mer.response.RegisterSaasMerchantV2Response;
public class SubMerchantOnboardingDemo {
// 初始化Client（单例模式）
private static final MerClient merClient = MerClientBuilder.builder().build();
public static void main(String[] args) {
// 构建请求参数
RegisterSaasMerchantV2Request request = new RegisterSaasMerchantV2Request();
request.setRequestNo("YBRWQQH202511280001");
request.setParentMerchantNo("10080011235");
request.setBusinessRole("ORDINARY_MERCHANT");
// 商户主体信息（JSON字符串）
String merchantSubjectInfo = "{"licenceUrl":"https://saas-platform.com/upload/licence.jpg","signName":"XX科技有限公司","signType":"ENTERPRISE","licenceNo":"91440101MA9X7XXXX","shortName":"XX科技"}";
request.setMerchantSubjectInfo(merchantSubjectInfo);
request.setNotifyUrl("https://saas-platform.com/notify/merchant/onboarding");
try {
// 调用接口
RegisterSaasMerchantV2Response response = merClient.registerSaasMerchantV2(request);
// 处理响应结果
System.out.println("申请单编号：" + response.getResult().getApplicationNo());
System.out.println("子商户编号：" + response.getResult().getMerchantNo());
System.out.println("进件状态：" + response.getResult().getApplicationStatus());
} catch (Exception e) {
e.printStackTrace();
// 异常处理（如参数错误、签名失败）
}
}
}

五、技术保障与合规要求

（一）接口安全机制

• 签名验签：所有接口调用需通过Authorization鉴权串 +x-yop-request-id唯一标识，支持 HMAC-SHA256 签名算法；

• 数据加密：敏感信息（身份证号、银行卡号）需通过易支付提供的加密工具加密后传输，避免明文泄露；

• 访问控制：API 调用频率限制为 100 次 / 秒，超出会触发限流，需合理控制并发。

（二）合规要求

1. SaaS 平台需确保子商户资料真实性，易支付会定期抽查，若发现虚假资料，将冻结子商户账户；

2. 特殊行业子商户（如金融、游戏）需提前向易支付报备，获取行业准入资质；

3. 子商户进件成功后，需在 SaaS 平台公示支付服务协议、费率标准、退款规则，确保用户知情权。

六、落地建议

1. 优先对接 “个人入网接口” 试点：个人商户资料简单、审核快，适合快速验证进件流程，再逐步拓展企业商户；

2. 接入沙箱测试环境：先在易支付沙箱环境（https://open.yeepay.com/sandbox）测试进件、结算流程，模拟审核通过 / 驳回、结算失败等场景；

3. 优化回调处理逻辑：SaaS 平台需确保回调地址高可用，接收易支付通知后及时返回 “success”，避免重复通知；

4. 监控关键指标：搭建数据看板，监控子商户进件通过率、结算成功率、驳回原因分布，针对性优化资料校验逻辑。