合利宝商户进件接口对接指南

接口说明

合利宝商户进件接口用于帮助平台商完成子商户的入驻、信息管理、产品开通等操作，本技能覆盖全部进件相关场景：

| 业务模块 | 说明 | 核心接口 | |------|------|----------| | 商户进件 | 子商户信息提交、开户 | 4.1 商户进件接口 | | 进件查询 | 查询进件状态、商户信息 | 4.2 进件查询接口 | | 产品开通 | 开通扫码、快捷、POS 等产品 | 4.3.x 产品开通接口 | | 产品查询 | 查询已开通产品及费率 | 4.4.x 产品查询接口 | | 资质上传 | 上传商户证照、图片资质 | 4.6.4/4.6.7 资质上传接口 | | 信息变更 | 修改商户信息、结算卡变更 | 4.6.1/4.6.3 信息变更接口 | | 电子签章 | 商户电子协议签署 | 4.10 签章合同接口 | | 商户查询 | 查询商户详细信息 | 4.15 商户信息查询接口 | | 终端管理 | 终端信息采集、报备 | 4.31 终端采集接口 | | 投诉处理 | 微信/支付宝投诉单查询回复 | 4.42/4.43 投诉接口 |

文档获取方式

合利宝商户进件接口文档通过在线 API 动态获取：

# 获取完整接口文档
curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/15/ff2d6c0d"

编写代码前务必先获取最新文档，文档内包含完整的接口参数、代码示例和返回码说明。

快速决策树

用户咨询合利宝商户进件接入
        |
        +-- 新商户入驻？
        |       +-- 是 --> 4.1 商户进件 → 4.6.4 资质上传 → 4.3.1 开通产品
        |
        +-- 查询进件状态？
        |       +-- 是 --> 4.2 进件查询接口
        |
        +-- 修改商户信息？
        |       +-- 关键信息（结算卡/展示名/客服电话）--> 4.6.1/4.6.3 信息变更
        |       +-- 非关键信息 --> 4.9 信息补充接口
        |
        +-- 开通/修改产品费率？
        |       +-- 是 --> 4.3.x 产品开通接口（修改费率也用这个接口）
        |
        +-- 签署电子协议？
        |       +-- 是 --> 4.10 签章合同接口
        |
        +-- 查询商户信息？
        |       +-- 是 --> 4.15 商户信息查询接口
        |
        +-- 配置微信公众号/小程序支付授权？
                +-- 是 --> 微信公众号进件接口（单独文档）

接入路由表

| 场景 | 推荐方式 | 核心接口 | interfaceName 值 | 适用场景 | |------|----------|----------|---------------|----------| | 商户进件 | 商户进件接口 | 4.1 商户进件 | register | 新商户入驻提交资料 | | 进件查询 | 进件查询接口 | 4.2 进件查询 | registerQuery | 查询进件状态 | | 开通扫码产品 | 开通产品 - 扫码 | 4.3.1 开通产品 | openProduct | 开通微信/支付宝/银联扫码产品 | | 开通快捷产品 | 开通产品 - 快捷 | 4.3.3 开通产品 | openProduct | 开通快捷支付产品 | | 开通 POS 产品 | 开通产品-POS | 4.3.6 开通产品 | openProduct | 开通 POS 产品 | | 产品查询 | 产品查询接口 | 4.4.1 产品查询 | productQuery | 查询已开通产品及费率 | | 资质上传 | 资质上传接口 | 4.6.4 资质上传 | merchantCredential | 上传商户证照图片 | | 资质上传 URL | 资质 URL 上传 | 4.6.7 资质 URL 上传 | merchantCredentialUrl | 通过图片 URL 上传资质 | | 结算卡变更 | 结算卡变更 | 4.6.1 结算卡变更 | changeSettleCard | 修改结算银行卡信息 | | 信息变更 | 商户信息变更 | 4.6.3 商户信息变更 | merchantChange | 修改商户一般信息 | | 信息补充 | 商户信息补充 | 4.9 商户信息补充 | merchantSupplement | 补充/修改非关键信息 | | 电子签章 | 签章合同接口 | 4.10 签章合同 | signContract | 商户签署电子协议 | | 商户查询 | 商户信息查询 | 4.15 商户信息查询 | merchantQuery | 查询商户详细信息 | | 真实性审核 | 真实性审核查询 | 4.40 真实性审核查询 | authAuditQuery | 查询真实性审核结果 | | 终端采集 | 终端信息采集 | 4.31 终端信息采集 | terminalCollect | 采集终端设备信息 | | 投诉查询 | 投诉单查询 | 4.42 投诉单查询 | complaintQuery | 查询微信/支付宝投诉单 | | 投诉回复 | 投诉单回复 | 4.43 投诉单回复 | complaintReply | 回复投诉单 |

场景关键词匹配

| 关键词 | 路由方式 | |--------|----------| | 进件、开户、子商户进件、商户进件、新商户入驻 | 4.1 商户进件接口 | | 进件查询、进件状态、进件结果 | 4.2 进件查询接口 | | 开通产品、开通扫码、开通微信、开通支付宝、开通 POS | 4.3.x 产品开通接口 | | 费率设置、费率修改、修改费率、调整费率 | 4.3.1 开通产品接口（修改费率也用这个） | | 资质上传、证照上传、图片上传、门头照、内景照 | 4.6.4/4.6.7 资质上传接口 | | 修改结算卡、结算卡变更、换银行卡 | 4.6.1 结算卡变更接口 | | 修改商户信息、信息变更、商户变更 | 4.6.3 商户信息变更接口 | | 信息补充、补充资料、修改非关键信息 | 4.9 商户信息补充接口 | | 电子签章、签章、电子协议、签署合同 | 4.10 签章合同接口 | | 商户查询、查询商户信息、商户详情 | 4.15 商户信息查询接口 | | 真实性审核、实名审核、OCR 识别 | 4.40 真实性审核查询接口 | | 终端采集、终端报备、POS 机报备、设备采集 | 4.31 终端信息采集接口 | | 投诉查询、投诉单、微信投诉、支付宝投诉 | 4.42/4.43 投诉接口 |

以下关键词不触发本技能：

| 关键词 | 应使用技能 | |--------|------------| | 快捷支付、绑卡支付、一键绑卡 | helipay-quickpay-integration | | 扫码支付、收款、主扫、被扫、公众号支付 | helipay-scanpay-integration | | 分账、延时分账 | helipay-delayed-split | | 结算、提现 | helipay-merchant-settlement | | 余额查询、对账单、电子回单 | helipay-public-products |

接口地址

| 环境 | 地址 | |------|------| | 测试环境 | http://test.trx.helipay.com/trx/merchantEntry/interface.action | | 生产环境 | http://entry.trx.helipay.com/trx/merchantEntry/interface.action |

所有接口使用同一个请求地址，通过 interfaceName 字段值区分具体接口。

统一请求响应格式

所有接口统一使用以下方式：

| 项目 | 说明 | |------|------| | 请求方法 | POST | | 请求格式 | application/x-www-form-urlencoded（form 表单），文件上传用 multipart/form-data | | 字符编码 | UTF-8 | | 接口识别 | 通过 interfaceName 字段值判定是哪个接口 |

统一请求参数：

| 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 接口名称 | interfaceName | 是 | 各接口的名称标识，如 register、registerQuery 等 | | 请求参数主体 | body | 是 | 加密后的明文数据（JSON 串） | | 签名 | sign | 是 | MD5 或 SM3WITHSM2 签名结果 | | 商户号 | merchantNo | 是 | 平台商商户号 | | 签名类型 | signType | 否 | MD5 或 SM3WITHSM2，不传默认 MD5 | | 加密密钥 | encryptionKey | 否 | 国密算法时必填 |

统一返回响应参数：

| 字段名 | 变量名 | 必填 | 类型 | 说明 | |--------|--------|------|------|------| | 成功标志 | success | 是 | Boolean | true/false | | 返回码 | code | 否 | String | 0000 表示成功 | | 响应错误消息 | message | 是 | String | 返回的响应消息 | | 业务数据 | data | 否 | String | 解密后的明文数据（JSON 串） | | Data 数据签名串 | sign | 否 | String | 用于校验 data 串的完整性 | | 处理主机别名 | hostname | 是 | String | 如 Trx06 | | 签名类型 | signType | 否 | String | MD5 或 SM3WITHSM2 | | 加密密钥 | encryptionKey | 否 | String | 国密算法时返回 |

验签规则：

当且仅当 success=true 并且 code=0000 时，商户需要对 data 域进行验签
若 success=false 或 code≠0000，商户不需要进行验签操作

核心接口详解

4.1 商户进件接口

流程：

4.1 商户进件接口
    ↓ 返回进件状态
进件状态=INIT（待审核）或 AUDITED（审核通过）
    ↓ 审核通过后
4.6.4 资质上传 → 4.3.1 开通产品 → 4.10 电子签章

适用场景：

新商户入驻提交资料
子商户开户

关键参数（body 域）：

firstClassMerchantNo: 平台商商编
orderNo: 商户订单号（唯一）
signName: 子商户签约名
showName: 展示名（收银台展示）
merchantType: 子商户类型（企业商户/个人商户/个体工商户）
legalPerson: 法人名字
legalPersonID: 法人身份证号
businessLicense: 营业执照号
regionCode: 区县编码
accountNo: 结算账号
bankCode: 结算卡联行号
merchantCategory: 经营类别

返回结果：

orderNo: 进件时的订单号
entryStatus: 进件状态（INIT/ OVERRULE/ AUDITED）
merchantNo: 子商户商编（审核通过时返回）
sysAccountNo: 系统账户号（审核通过时返回）

4.2 进件查询接口

流程：

4.2 进件查询接口
    ↓ 返回进件状态和商户信息
判断进件状态：
- INIT: 待审核
- OVERRULE: 申请驳回
- AUDITED: 审核通过

适用场景：

查询进件审核状态
获取商户详细信息

关键参数（body 域）：

orderNo: 进件下单时的订单号
firstClassMerchantNo: 平台商商编

4.3.1 开通产品 - 扫码（修改费率也是这个接口）

流程：

4.3.1 开通产品 - 扫码
    ↓ 返回开通结果
设置产品费率（可多次调用开通不同产品）
    ↓ 自动报备（除微信公众号外）

适用场景：

开通微信扫码支付
开通支付宝扫码支付
开通银联云闪付
修改产品费率（用同一接口）

关键参数（body 域）：

productType: 产品类型（APPPAY 扫码产品）
firstClassMerchantNo: 平台商商编
merchantNo: 子商户商编
appPayType: 客户端类型（WXPAY/ALIPAY/UNIONPAY）
value: 费率（%）
appFeeMode: 费率模式（RANGE 普通费率 / 分段费率）

注意：

进件完成后需先调用资质上传接口
子商户费率要大于或等于平台商费率
修改费率也用这个接口

4.6.4 子商户资质上传接口

流程：

4.6.4 子商户资质上传接口（multipart/form-data）
    ↓ 返回上传结果
上传门头照、内景照、营业执照等

适用场景：

上传商户证照图片
上传门头照、内景照（个人商户必传）
上传特殊行业资质

请求格式：multipart/form-data

关键参数：

merchantNo: 子商户商编
credentialType: 资质类型（见附录）
file: 图片文件（不超过 2MB）

4.10 签章合同接口

流程：

4.10 签章合同接口
    ↓ 返回签约链接
商户前端打开链接完成电子签章
    ↓ 签章成功异步通知

适用场景：

商户签署电子协议
完成合规签约

关键参数（body 域）：

merchantNo: 子商户商编
contractType: 合同类型
successCallBackUrl: 成功回跳地址（可选）

通用规则

签名规则

固定不参与签名的字段：

sign - 签名结果本身
signType - 签名类型标识

签名原始串组装方式：

待签名串 = body 加密串&商户号
MD5 签名：待签名串 + & + 签名秘钥 → MD5 计算
SM3WITHSM2 签名：待签名串 → SM3WITHSM2 签名（使用商户私钥），不追加秘钥

MD5 签名示例：

待签名字符串：body 加密串&商户号
拼接后的原文串：C0HdQBfH3pJ2iBH6zEM9udEvoPW7k8AqLIvdOqpskQ+jomvhpC1pf7uy1kk/+B5sF9GbM8yDjuANrqu+er5GXmHskmvi4arr2WxWhWQAiQ/HTjufLU8Qb5Z9ZkHOnR2u&E1800001025
拼接签名秘钥：C0HdQBfH3pJ2iBH6zEM9udEvoPW7k8AqLIvdOqpskQ+jomvhpC1pf7uy1kk/+B5sF9GbM8yDjuANrqu+er5GXmHskmvi4arr2WxWhWQAiQ/HTjufLU8Qb5Z9ZkHOnR2u&E1800001025&YC4QSNWEls84sJzwhPKqPtz7fm0BPA07
进行 MD5 计算：sign = 23584952fcaea446a3992bcc019c8f18

使用 helipay-sm2 技能：将拼接好的签名原文传给 helipay-sm2 技能，获取 SM3withSM2 签名结果。

特殊接口说明

以下三个接口不使用 body 加密模式，需特别注意：

1. 资质上传（文件上传）`merchantCredential`

请求格式为 multipart/form-data
不传 body（不加密），直接传文件 + 基础参数
请求参数：interfaceName、merchantNo、sign、credentialType、file
签名规则：sign = MD5(credentialType&merchantNo&签名秘钥) 或 SM3WITHSM2 签名
响应：直接返回 JSON，不是加密的 data 域

2. 资质上传（URL）`merchantCredentialUrl`

请求格式为 application/x-www-form-urlencoded（普通 form 表单）
不传 body（不加密），直接传参数
请求参数：interfaceName、merchantNo、sign、credentialType、credentialUrl
签名规则：sign = MD5(credentialType&credentialUrl&merchantNo&签名秘钥) 或 SM3WITHSM2 签名
响应：直接返回 JSON，不是加密的 data 域

3. 签章合同 `signContract`

请求格式为 application/x-www-form-urlencoded（普通 form 表单）
不传 body（不加密），直接传参数
请求参数：interfaceName、merchantNo、sign、contractType、successCallBackUrl（可选）
签名规则：sign = MD5(contractType&merchantNo&签名秘钥) 或 SM3WITHSM2 签名
响应：返回签约链接 URL

以上三个特殊接口均不使用 body 加密模式，签名规则也不同于正常接口。其余接口（进件、查询、产品开通等）均使用 body 加密 + 签名的标准模式。

SM4 加密

| 场景 | 加密内容 | |------|---------| | body 域 | 整个 body JSON 串使用 SM4 加密 | | encryptionKey | SM4 key 使用平台公钥进行 SM2 加密后填充 |

使用方式：

请求时：商户随机生成 SM4 key，使用平台公钥加密后通过 encryptionKey 字段上送
响应时：平台随机生成 SM4 key，使用商户公钥加密后通过 encryptionKey 字段返回

回调处理

进件审核异步通知

通知机制：

人工审核成功或失败会异步通知
自动审核通过不会通知
采用 POST 方法提交（application/json）
响应类型：纯文本 success

回调参数（data 域）：

orderNo: 进件时的订单号
entryStatus: 进件状态
merchantNo: 子商户商编（审核通过时返回）
parentMerchantNo: 平台商编
sysAccountNo: 系统账户号

返回码说明

| 返回码 | 描述 | 处理建议 | |--------|------|----------| | 0000 | 成功 | - | | 0001 | 处理中 | 等待异步结果或调用查询接口 | | 8000 | 失败 | 根据返回信息排查 | | 8999 | 系统异常 | 联系合利宝客服 |

进件状态码： | 状态码 | 描述 | |--------|------| | INIT | 待审核 | | OVERRULE | 申请驳回 | | AUDITED | 审核通过 |

注意事项

商户进件与资质上传需分别调用：建议前端同时收集，进件审核通过后再上传资质
关键信息变更需人工审核：结算卡、展示名、客服电话等关键信息变更需提交相关文件证明
非关键信息可直接修改：通过 4.9 信息补充接口直接修改
电子协议必须签署：电子签章是必要的，不可免除
微信公众号进件需单独调用：开通扫码产品时，除微信公众号外会自动报备，微信公众号需单独调用进件接口（有单独文档）
费率设置：子商户费率要大于或等于平台商费率
body 加密模式 vs 特殊接口：大部分进件接口使用 body 加密模式，但资质上传（文件/URL）和签章合同是特殊接口，不使用 body 加密，签名规则也不同
敏感信息保护：不要在日志中明文记录身份证、卡号、手机号等敏感信息
各接口具体的 body 域参数、返回参数、返回码以最新文档为准，请用上方 curl 命令获取

Demo 和资料下载

通过文档 API 获取下载地址：

curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/15/ff2d6c0d"

文档内提供：

Java/PHP/C# demo 源码下载
进件流程图
MCC 码表
行业编码及地区编码表
资质类型枚举

常见对接问题

| 问题 | 解决方案 | |------|----------| | 签名失败 | 检查参数拼接顺序、签名秘钥是否正确、排除签名参数是否已排除 | | 进件审核驳回 | 根据 msg 返回的驳回原因补充资料后重新提交 | | 费率设置失败 | 确认子商户费率是否大于等于平台商费率 | | 资质上传失败 | 检查图片大小（不超过 2MB）、格式、资质类型是否正确 | | 查不到商户信息 | 确认商户是否已审核通过获得商编 |

对接步骤清单

人工准备（对接前完成）

[ ] 登录合利宝商户后台，获取平台商商户号
[ ] 获取签名秘钥、加密秘钥
[ ] 下载并阅读完整接口文档（使用文档 API）

技术对接

[ ] 实现签名（使用 helipay-sm2 技能）
[ ] 实现 SM4 字段加密（使用 helipay-sm2 技能）
[ ] 调通 4.1 商户进件接口
[ ] 调通 4.2 进件查询接口
[ ] 调通 4.6.4 资质上传接口
[ ] 调通 4.3.1 产品开通接口
[ ] 调通 4.10 电子签章接口
[ ] 实现回调处理
[ ] 小金额测试验证

完整进件流程

1. 4.1 商户进件接口 → 提交商户资料
         ↓
2. 等待审核（INIT → AUDITED）
         ↓
3. 4.2 进件查询接口 → 获取子商户商编
         ↓
4. 4.6.4 资质上传接口 → 上传证照图片
         ↓
5. 4.3.1 开通产品 - 扫码 → 开通支付产品并设置费率
         ↓
6. 4.10 签章合同接口 → 商户签署电子协议
         ↓
7. 完成！商户拥有交易权限

生成时的说明要求

最终回答需要包含：

接口请求方式：明确告知接口是 POST form 表单格式（application/x-www-form-urlencoded），文件上传用 multipart/form-data；接口通过 interfaceName 字段值来判定是哪个接口。
统一请求参数说明：列出 interfaceName、body、sign、merchantNo、signType、encryptionKey 等公共参数的作用。
统一返回响应参数说明：列出 success、code、data、sign、hostname 等返回参数的作用及验签规则（仅 success=true 且 code=0000 时需验签）。
特殊接口说明：明确告知资质上传（文件/URL）和签章合同不使用 body 加密模式，直接传参数，签名规则也不同。
接口字段说明：列出具体接口的请求参数（body 域 JSON）、返回参数的完整说明（以最新文档为准），明确哪些字段需要 SM4 加密、哪些字段参与签名。
签名源串拼接规则：正常接口按 body&merchantNo 顺序拼接，MD5 签名需加上 & 和签名秘钥，SM3WITHSM2 不追加。sign、signType 不参与签名。特殊接口见上方说明。
SM4 加密字段清单：body 域 JSON 串需要调用 helipay-sm2 技能进行 SM4 加密，SM4 key 需要调用 helipay-sm2 技能使用平台公钥进行 SM2 加密。
代码示例：提供完整的请求参数组装、签名、调用示例（Java/Python/php 等，根据用户要求）。
配合 helipay-sm2 技能使用：
- 签名：将拼接好的签名源串传给 helipay-sm2 技能，获取 SM3withSM2 签名结果。
- SM4 加密：将 body 域 JSON 明文串传给 helipay-sm2 技能进行 SM4 加密；SM4 key 用 SM2 公钥加密后填入 encryptionKey。
- SM4 解密（响应处理）：将加密的 data 和加密的 SM4 key 传给 helipay-sm2 技能进行解密。
JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）。
明确说明：本技能只处理合利宝商户进件接口字段组装、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
提醒：签名源串的字段顺序、排除字段、证书格式必须与合利宝官方文档一致；不同接口的 interfaceName 值不同，请严格按对应接口文档组装。

合利宝接口对接_商户进件产品V001

合利宝商户进件接口对接指南

接口说明

文档获取方式

快速决策树

接入路由表

场景关键词匹配

接口地址

统一请求响应格式

核心接口详解

4.1 商户进件接口

4.2 进件查询接口

4.3.1 开通产品 - 扫码（修改费率也是这个接口）

4.6.4 子商户资质上传接口

4.10 签章合同接口

通用规则

签名规则

特殊接口说明

1. 资质上传（文件上传）merchantCredential

2. 资质上传（URL）merchantCredentialUrl

3. 签章合同 signContract

SM4 加密

回调处理

进件审核异步通知

返回码说明

注意事项

Demo 和资料下载

常见对接问题

对接步骤清单

人工准备（对接前完成）

技术对接

完整进件流程

生成时的说明要求

1. 资质上传（文件上传）`merchantCredential`

2. 资质上传（URL）`merchantCredentialUrl`

3. 签章合同 `signContract`