16 KiB
16 KiB
001 - 汇元企业入网申请 API
接口名称： customer.enter.enterprise.apply
更新时间： 2025-11-28
状态： 已实现
调用地址
| 环境 | 地址 |
|---|---|
| 生产 | https://openapi.heepay.com/v1/customer/gateway |
| 沙箱 | http://openapi.heepaydev.com/v1/customer/gateway |
注意：进件网关地址与支付网关不同，对应
config.yaml中的channels.heepay.merchant_url。
接口说明
企业商户入网申请。所有 *_img 字段均需先调用文件上传接口（接口 002）获取 file_id 后传入。
请求业务参数（biz_content）
顶层字段
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
base_info |
基础信息 | 是 | Object | 见下方 |
settlement_info |
结算信息 | 是 | Object | 见下方 |
addition_info |
补充信息 | 否 | Object | 见下方 |
subject_info |
主体信息 | 是 | Object | 见下方 |
identity_info |
法人信息 | 是 | Object | 见下方 |
contact_info |
业务联系人信息 | 是 | Object | 见下方 |
ubo_infos |
受益所有人信息 | 条件必填 | Object[] | 受益人非法人时必传 |
business_info |
业务信息 | 是 | Object | 见下方 |
base_info 基础信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
request_no |
商户入网申请流水号 | 是 | String(64) | 商户自定义，全局唯一 |
alias_name |
商户简称 | 是 | String(20) | 支付宝/微信支付页显示该名称 |
mcc |
经营类目编码 | 是 | String(4) | 参照【经营类目编码】列表 |
service_phone |
客服电话 | 是 | String | 客服电话 |
email |
商户邮箱 | 是 | String(128) | 首次入网默认作为登录账号和联系人邮箱 |
notify_url |
通知地址 | 否 | String(256) | 汇元主动通知的 http/https 回调地址 |
settlement_info 结算信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
settle_type |
结算类型 | 是 | String | ACCOUNT=结算到汇付宝账户，BANK_CARD=结算到银行卡 |
account_type |
账户类型 | 是 | String | PUBLIC=对公，PRIVATE=对私；公司只支持对公，小微只支持对私 |
account_no |
银行卡号 | 是 | String(35) | 银行卡号 |
account_name |
开户名称 | 是 | String(32) | 开户名称 |
account_branch_no |
开户支行联行号 | 是 | String(64) | 开户支行联行号 |
open_account_img |
银行开户许可照 | 条件必填 | String(64) | 对公账号必传，传 file_id |
bank_name |
银行名称 | 是 | String | 参照【银行列表】 |
region_code |
银行卡省市区县编码 | 是 | String(6) | 参照省市编码列表 |
addition_info 补充信息（选填）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
open_merch_video |
开户意愿视频 | 否 | String | 传 file_id |
sharing_protocol_img |
分账协议 | 否 | String | 传 file_id |
business_developer |
业务开发者（拓展商户的业务员） | 否 | String(20) | 业务员姓名 |
subject_info 主体信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
name |
商户名称 | 是 | String(50) | 须与营业执照名称一致 |
cert_no |
营业执照号 | 是 | String(32) | 营业执照号 |
region_code |
营业执照区划编码 | 是 | String(32) | 传区县编码（通过行政区划查询接口获取） |
address |
营业执照注册地址 | 是 | String(250) | 营业执照注册地址 |
cert_img |
营业执照图片 | 是 | String | 传 file_id |
cert_expire |
营业执照有效期 | 是 | String | 格式：yyyy-MM-dd/yyyy-MM-dd，长期有效传 yyyy-MM-dd/forever |
identity_info 法人信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
name |
姓名 | 是 | String(18) | 法人姓名 |
mobile |
手机号 | 是 | String(11) | 法人手机号 |
cert_type |
证件类型 | 是 | String | ID_CARD=大陆身份证，HK_CARD=港通行证，MC_CARD=澳通行证，TW_CARD=台通行证，PASSPORT=外籍护照 |
cert_no |
证件号 | 是 | String(32) | 证件号码 |
nation |
国籍类型 | 是 | Int | 参照【国家编码】列表 |
cert_front_img |
证件正面照（人像面） | 是 | String | 传 file_id |
cert_back_img |
证件反面照（非人像面） | 是 | String | 传 file_id |
cert_expire |
证件有效期 | 是 | String | 格式：yyyy-MM-dd/yyyy-MM-dd，长期有效传 yyyy-MM-dd/forever |
belong_ubo |
受益人是否是法人 | 是 | Bool | true=是，false=否；为 false 时 ubo_infos 必传 |
contact_info 业务联系人信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
name |
姓名 | 是 | String(32) | 业务联系人姓名 |
mobile |
手机号 | 是 | String(11) | 业务联系人手机号 |
cert_type |
证件类型 | 是 | String | 同 identity_info.cert_type 枚举值 |
cert_no |
证件号 | 是 | String(18) | 证件号码 |
nation |
国籍类型 | 是 | Int | 参照【国家编码】列表 |
cert_expire |
证件有效期 | 是 | String | 格式：yyyy-MM-dd/yyyy-MM-dd，长期有效传 yyyy-MM-dd/forever |
cert_front_img |
证件正面照（人像面） | 是 | String(255) | 传 file_id |
cert_back_img |
证件反面照（非人像面） | 是 | String(255) | 传 file_id |
ubo_infos 受益所有人信息（受益人非法人时必传，数组）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
name |
证件姓名 | 是 | String(64) | 受益所有人证件姓名 |
cert_type |
证件类型 | 是 | String | 同 identity_info.cert_type 枚举值 |
cert_no |
证件号码 | 是 | String(32) | 证件号码 |
nation |
国籍类型 | 是 | Int | 参照【国家编码】列表 |
cert_expire |
证件有效期 | 是 | String | 格式：yyyy-MM-dd/yyyy-MM-dd，长期有效传 yyyy-MM-dd/forever |
cert_address |
证件地址 | 是 | String(255) | 受益所有人证件地址 |
rate |
持股比例 | 是 | String | 以 % 为单位，传 1-100 的数字，如 10 表示占股 10% |
business_info 业务信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
business_open_info |
业务开通详情 | 是 | Object | 见下方 |
business_open_info
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
business_platform |
业务平台 | 是 | String | HEEPAY=汇付宝，HEELIFE=汇生活 |
heepay_info |
汇付宝信息 | 条件必填 | Object | business_platform=HEEPAY 时传入 |
heelife_info |
汇生活信息 | 条件必填 | Object | business_platform=HEELIFE 时传入 |
heepay_info 汇付宝信息
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
operate_type |
操作类型 | 是 | String | OPEN_ORDINARY_MERCH=开通普通户收单账户，OPEN_BALANCE=开通子户余额账户，OPEN_MERCH=开通子户收单账户，APPEND_OPEN_PRODUCT=补充开通产品；小微商户不支持 OPEN_ORDINARY_MERCH |
scene_info |
场景信息 | 条件必填 | Object | 收单账户必传 |
heepay_ordinary |
普通商户必须信息 | 条件必填 | Object | operate_type=OPEN_ORDINARY_MERCH 时必传 |
product_info |
产品费率信息 | 条件必填 | Object | operate_type=OPEN_MERCH 或 APPEND_OPEN_PRODUCT 时必传 |
wechat_config |
微信配置 | 否 | Object | 见下方 |
wechat_enter |
微信进件参数 | 否 | Object | 需要指定微信进件参数时传入 |
alipay_enter |
支付宝进件参数 | 否 | Object | 需要指定支付宝进件参数时传入 |
scene_info 场景信息（收单账户必传）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
shop_brand_img |
商户品牌标识图片 | 是 | String | 企业传公司大楼照，个体/小微传门头照，传 file_id |
customer_service_img |
客户服务照 | 是 | String | 企业传公司前台照，个体/小微传收银台照，传 file_id |
work_env_img |
商户经营照 | 是 | String | 企业传内部办公场所照，个体/小微传店铺经营照，传 file_id |
heepay_ordinary 普通商户必须信息（operate_type=OPEN_ORDINARY_MERCH 时必传）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
app_type |
应用类型 | 是 | String | PC，APP，WAP，WECHAT_MINI=微信小程序，ALIPAY_MINI=支付宝小程序，WECHAT_PUBLIC_PLATFORM=微信公众号，QUICK_PASS=云闪付，OTHER=其他线上场景 |
app_name |
应用名称 | 是 | String | 应用名称 |
app_url |
应用网址 | 条件必填 | String | app_type 为 PC/APP/WAP/WECHAT_MINI 时必填 |
app_download_url |
应用下载地址 | 条件必填 | String | app_type 为 PC/APP/WAP/WECHAT_MINI 时必填 |
mini_app_id |
小程序 APPID | 条件必填 | String | app_type 为 WECHAT_MINI/ALIPAY_MINI 时必填 |
app_status |
应用状态 | 是 | String | OFFLINE=未上线，ONLINE=已上线公开，ONLINE_SPECIAL=已上线特定IP/用户开放 |
icp_url |
ICP 备案网址 | 条件必填 | String | app_type 为 PC/WAP 时必填 |
business_types |
业务种类 | 是 | Object[] | 支持多个，见下方 business_types 结构 |
business_note |
业务场景说明 | 是 | String | 业务场景说明 |
business_types 单条结构：
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
business_type |
业务种类 | 是 | String | 见下方枚举值 |
business_type 枚举值：
| 枚举值 | 说明 |
|---|---|
PURCHASE_VIRTUAL_GOODS |
虚拟商品购买 |
PREPAID_ACCOUNT_CHARGE |
预付费类账户充值 |
MATERIAL_CONSUMPTION |
实物消费 |
AVIATION_BUSINESS_TRAVEL_EXPENSES |
航空商旅消费 |
L_C_CONSUMPTION |
生活及商业消费服务 |
OTHER_MERCH_CONSUMPTION |
其他商户消费 |
PAYMENT_PUBLIC_UTILITIES |
公共事业缴费 |
E_MEDICAL_PAYMENT |
教育医疗缴费 |
GOVERNMENT_PAYMENT |
政府服务缴费 |
PUBLIC_WELFARE_DONATION |
公益捐款 |
OTHER_PUBLIC_SERVICES |
其他公共服务 |
OTHER_FINANCIAL_PAYMENTS |
其他金融付款 |
FUND_PURCHASE |
基金购买 |
INSURANCE_PURCHASE |
保险选购 |
WEALTH_MANAGE |
投资理财 |
CREDIT_REPAYMENT |
信贷偿还 |
CREDIT_CARD_REPAYMENTS |
信用卡还款转出 |
RECHARGE_PAYMENT_ACCOUNT |
支付账户充值 |
BANK_ACCOUNT_TRANSFER_OUT |
银行账户转账转出 |
OTHER_ACCOUNT_CHARGE |
其他账户充值 |
SERVICE_TYPE |
服务类 |
SYSTEM_TYPE |
系统类 |
MANAGE_TYPE |
管理类 |
BID_BOND_PAYMENT |
招投标保证金支付 |
OVERSEAS_SHOPPING |
境外商品购买 |
business_img |
经营服务图片 |
ext_a_img ~ ext_e_img |
附件 1-5 |
product_info 产品费率信息（operate_type=OPEN_MERCH 或 APPEND_OPEN_PRODUCT 时必传）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
reference_merch_id |
标杆商户编码 | 条件必填 | Long | 与 rate_infos 二选一 |
rate_infos |
费率列表 | 条件必填 | Object[] | 与 reference_merch_id 二选一 |
rate_infos 单条结构：
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
rate_code |
支付场景编码 | 是 | String | 参照【支付场景】列表 |
rate_type |
费率类型 | 是 | String(32) | SINGLE_PERCENT=单笔百分比，SINGLE_FIXED=单笔固定值 |
rate |
费率值 | 是 | String(5) | 费率值 |
wechat_config 微信配置（选填）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
app_ids |
appId 列表 | 否 | Object[] | appId 列表 |
pay_urls |
支付授权目录列表 | 否 | Object[] | 支付授权目录列表 |
wechat_enter 微信进件参数（选填）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
channel_code |
进件渠道号 | 是 | String | 进件渠道号 |
alipay_enter 支付宝进件参数（选填）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
channel_code |
进件渠道号 | 是 | String | 进件渠道号 |
heelife_info 汇生活信息（business_platform=HEELIFE 时传入）
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
operate_type |
操作类型 | 是 | String | 指明业务类型（具体枚举值待补充） |
响应业务参数
| 字段 | 名称 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
request_no |
商户申请流水号 | 是 | String | 后续查询（接口 003）和修改（接口 004）时使用 |
业务错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
invalid_parameter_email_existed |
汇元已存在此邮箱 | 更换邮箱 |
invalid_parameter_email_except |
邮箱校验异常 | 检查参数 |
invalid_parameter_enterprise_type_ex |
企业用户只支持对公账户 | 检查 account_type |
invalid_parameter_micro_type_ex |
小微用户只支持对私账户 | 检查 account_type |
invalid_parameter_ubo_must_not_empty |
受益人不能为空 | 传入 ubo_infos |
invalid_parameter_rate_must_not_empty |
开通收单账户费率信息不能为空 | 检查 product_info |
invalid_parameter_common_must_not_empty |
开通普通户必须信息不能为空 | 检查 heepay_ordinary |
invalid_parameter_mark_merch_not_existed |
标杆商户未配置 | 联系汇元配置 |
business_fail_customer_has_passed |
商户已入驻完毕 | 确认 request_no 是否已用过 |
business_fail_customer_waiting |
入驻申请处理中 | 等待审核结果 |
business_fail_save_his_work_record_fail |
迁移创建历史入驻工单失败 | 重试 |
business_fail_delete_his_work_record_fail |
迁移删除历史入驻工单失败 | 重试 |
business_fail_save_work_record_fail |
保存入驻记录失败 | 重试 |
unknown_exception |
系统未知问题 | 参考返回描述 |
unknown_error_gateway |
网关系统不可用 | 稍后重试 |
invalid_auth |
授权权限不足 | 检查签名/权限 |
missing_parameter |
缺少参数 | 补充必填参数 |
invalid_parameter |
无效参数 | 检查参数格式 |
invalid_request |
无效请求 | 参考返回详细信息 |
biz_failure |
业务错误 | 参照具体错误提示 |
service_not_exists |
服务不存在 | 确认服务是否开通 |
service_time_out |
系统繁忙 | 稍后重试 |
channel_error |
通道系统异常 | 用相同参数重新调用 |
实现要点
- 网关地址：使用
channels.heepay.merchant_url（进件网关），而非支付网关 - 图片先传后用：所有
*_img字段均为file_id，依赖接口 002（文件上传） - 受益人条件必填：
identity_info.belong_ubo=false时，ubo_infos数组必传 - operate_type 决定必填子结构：
OPEN_MERCH/APPEND_OPEN_PRODUCT→product_info必传OPEN_ORDINARY_MERCH→heepay_ordinary必传- 收单账户 →
scene_info必传
- 费率二选一：
product_info中reference_merch_id和rate_infos二选一 - 返回 request_no：作为查询（接口 003）和修改（接口 004）的入参，需持久化存储
待补充
heelife_info.operate_type枚举值（暂不支持汇生活，低优先级）wechat_config.app_ids和pay_urls单条结构字段- 省市区县编码（建议用行政区划查询接口在线获取，无需维护静态列表）
附录文档
- MCC 经营类目编码 →
appendix-mcc-codes.md - 银行列表 →
appendix-bank-codes.md - 国家编码 →
appendix-nation-codes.md - 支付场景编码 →
appendix-payment-scene-codes.md