本文档为开放平台对外接入指引,作为聚合支付方,对接各三方支付通道的进件能力。
接口路径前缀:商户接口/v1/paycfg/merchant、上传接口/v1/upload/paycfg、配置接口/v1/common/config。
入网及通道类接口为 异步 处理:提交后通过 回调通知 或查询接口获取处理结果(推荐配置notifyUrl接收异步回调)。回调通知:入网(4.1.2.3/4.1.2.5)、商户变更(4.1.2.4)、费率变更(4.1.2.6)接口均支持传入 notifyUrl,平台在通道状态变化时主动向调用方推送结果通知,无需轮询。详见「回调通知机制」章节。
| 接口编号 | 接口路径 | 方法名 | 说明 |
|---|---|---|---|
| 4.8.2.1 | POST /v1/common/config/mcc/tree | getMccTree | 获取MCC行业类目树 |
| 4.8.2.2 | POST /v1/common/config/area/list | getAreaList | 获取区域列表(三级联动) |
| 4.8.2.3 | POST /v1/common/config/bankParent/list | getBankParentList | 获取银行总行列表 |
| 4.8.2.4 | POST /v1/common/config/bank/list | getBankList | 获取银行支行列表 |
| 4.8.2.5 | POST /v1/common/config/mccYb/tree | getMccYbTree | 获取易宝MCC行业类目树 |
| 4.8.2.6 | POST /v1/common/config/mccEasypay/tree | getMccEasypayTree | 获取易生MCC行业类目树 |
| 4.8.2.7 | POST /v1/common/config/mccMappingEasypay/list | getMccMappingEasypayList | 获取易生MCC映射 |
| 4.8.2.8 | POST /v1/common/config/mccMappingPa/list | getMccMappingPaList | 获取平安银行MCC映射 |
pictureUrl)。| 接口编号 | 接口路径 | 方法名 | 说明 |
|---|---|---|---|
| 4.1.1.1 | POST /v1/upload/paycfg/merchantPicture | merchantPictureUpload | 公共文件上传(进件用) |
notifyUrl 参数。平台在通道状态发生变化时,会主动向调用方的 notifyUrl 发起 HTTP POST 通知,调用方无需轮询即可获取处理结果。| 业 务类型 | 触发接口 | 回调触发时机 |
|---|---|---|
| 商户入网 | 4.1.2.3(memberAdd)、4.1.2.5(channelAdd) | 三方通道审核结果返回时(成功/失败/审核中) |
| 商户变更 | 4.1.2.4(memberUpdate) | 三方通道变更审核结果返回时 |
| 费率变更 | 4.1.2.6(channelUpdate) | 三方通道费率变更结果返回时 |
推荐做法:调用方同时使用回调通知 + 定时查询,回调通知作为主要获取结果的方式,定时查询作为兑底补偿。
notifyUrl(需以 http:// 或 https:// 开头)。notifyUrl 发起 HTTP POST 请求,推送通道状态变化。success 表示接收成功。success,平台将按照重试策略自动重发通知。notifyUrl 发起的 HTTP POST 请求体为 JSON 格式,结构如下:{
"requestId": "平台请求ID",
"timestamp": "1700000000000",
"nonce": "随机字符串",
"sign": "RSA签名",
"reqBody": {
"channelId": 1,
"channelMchNo": "三方通道商户号",
"merchantNo": "E100001",
"status": 1,
"failMsg": null,
"agreementSignUrl": null
}
}| 字段 | 类型 | 说明 |
|---|---|---|
| requestId | String | 平台请求ID,与提交接口响应中的 requestId 一致 |
| timestamp | String | 毫秒级时间戳 |
| nonce | String | 随机字符串,用于防重放 |
| sign | String | RSA 签名,对整个请求体(排除sign字段)签名生成 |
| reqBody | Object | 业务参数对象 |
| 字段 | 类型 | 说明 |
|---|---|---|
| channelId | Integer | 通道 ID |
| channelMchNo | String | 三方通道商户号(入网成功时返回) |
| merchantNo | String | 商户编号 |
| status | Integer | 通道状态,与查询接口返回的状态枚举一致 |
| failMsg | String | 失败原因(审核失败时返回) |
| agreementSignUrl | String | 协议签约链接(部分通道需要签约时返回) |
| 值 | 说明 |
|---|---|
| 0 | 初始化 |
| 1 | 进件成功 |
| 2 | 初审中 |
| 3 | 初审失败 |
| 4 | 初审通过(待签约) |
| 5 | 复审中 |
| 6 | 审核失败 |
success(大小写不敏感)表示接收成功。success,平台停止重试。| 重试次数 | 重试间隔 | 说明 |
|---|---|---|
| 第 1 次 | 1 分钟 | 首次推送失败后 1 分钟重试 |
| 第 2 次 | 5 分钟 | |
| 第 3 次 | 30 分钟 | |
| 第 4 次 | 2 小时 | |
| 第 5 次 | 6 小时 | 最后一次重试,失败后任务进入终态 |
默认最多重试 5 次(不含 首次推送),共 6 次推送机会。重试策略可通过平台配置调整。
merchantNo(商户编号)。notifyUrl:回调通知地址(可选,推荐传入)注意:小微商户不支持线上经营
| 接口编号 | 接口路径 | 方法名 | 说明 |
|---|---|---|---|
| 4.1.2.1 | POST /v1/paycfg/merchant/add | add | 商户添加(简单信息录入) |
| 4.1.2.3 | POST /v1/paycfg/merchant/member/add | memberAdd | 信息补全并指定通道入网 |
| 4.1.2.5 | POST /v1/paycfg/merchant/channel/add | channelAdd | 独立指定通道入网(可选) |
| 4.1.2.7 | POST /v1/paycfg/merchant/detail | detail | 查询入网结果 |
merchantNo。notifyUrl:回调通知地址(可选,推荐传入)关键区别:企业/工商户需提供营业执照、开户许可证、非法人结算授权函等企业资质文件;部分通道和流程需额外签约确认。
| 接口编号 | 接口路径 | 方法名 | 说明 |
|---|---|---|---|
| 4.1.1.1 | POST /v1/upload/paycfg/merchantPicture | merchantPictureUpload | 公共文件上传 |
| 4.1.2.1 | POST /v1/paycfg/merchant/add | add | 商户添加(简单信息录入) |
| 4.1.2.3 | POST /v1/paycfg/merchant/member/add | memberAdd | 信息补全并指定通道入网 |
| 4.1.2.5 | POST /v1/paycfg/merchant/channel/add | channelAdd | 独立指定通道入网(可选) |
| 4.1.2.7 | POST /v1/paycfg/merchant/detail | detail | 查询入网结果 |
| 4.8.2.1~8 | 公共配置接口 | 各方法 | 获取MCC/区域/银行等 |
channelType:通道类型rateMap:费率信息(支付宝/微信/银联费率等)mccId:MCC 类目 IDnotifyUrl:回调通知地址(可选,推荐传入)| 接口编号 | 接口路径 | 方法名 | 说明 |
|---|---|---|---|
| 4.8.2.1~8 | 公共配置接口 | 各方法 | 获取MCC/区域/银行等 |
| 4.1.2.5 | POST /v1/paycfg/merchant/channel/add | channelAdd | 独立指定通道入网 |
| 4.1.2.7 | POST /v1/paycfg/merchant/detail | detail | 查询入网结果 |
notifyUrl:回调通知地址(可选,推荐传入)注意:查询入网成功后的更新结果统一使用 4.1.2.8 接口,而非 4.1.2.7。4.1.2.4 商户信息变更会涉及到同步三方通道,故与「费率变更流程」是互斥的。
| 接口编号 | 接口路径 | 方法名 | 说明 |
|---|---|---|---|
| 4.1.2.4 | POST /v1/paycfg/merchant/member/update | memberUpdate | 更新商户信息和通道信息 |
| 4.1.2.8 | POST /v1/paycfg/merchant/detail4Update | detail4Update | 查询更新结果 |
| 4.1.1.1 | POST /v1/upload/paycfg/merchantPicture | merchantPictureUpload | 文件上传(如需更新资质图片) |