主题
商户入网
接口描述
- 接入方通过该接口进行商户入网，入网结果异步返回，或者调用商户查询接口进行查询。
- 商户入网失败的情况下，调用该接口进行重新入网，outMerchantNo传值保持不变。
请求URL
/merchant/apply
请求方式
- POST
公共请求参数
| 参数名 | 必选 | 类型 | 最大长度 | 说明 | 示例 |
|---|---|---|---|---|---|
| appId | 是 | string | appId | 202415629590370906 | |
| signature | 是 | string | 签名 | ||
| transNonce | 是 | string | 32 | 请求流水号 | 43e2c287-24b1-4cd1-b3d2-e40e7840cc40 |
| transDate | 是 | string | 13 | 请求时间，13位时间戳 | 1731406784607 |
请求参数
| 参数名 | 必选 | 类型 | 最大长度 | 说明 | 示例 |
|---|---|---|---|---|---|
| outMerchantNo | 是 | string | 32 | 接入方商户编号 | ZD240820000054 |
| merchantCategory | 是 | string | 商户类别： T-小微商户，P-个体工商户，E-企业商户; | T | |
| legalPhoneNo | 是 | string | 64 | 法人手机号(需要AES加密) | |
| legalName | 是 | string | 64 | 法人姓名(需要AES加密) | |
| legalCertType | 是 | string | 法人证件类型： ID_CARD-身份证；PASSPORT-护照；HK_MACAO_PERMIT-港澳通行证；TW_PERMIT-台胞证；FOREIGN_PERMANENT-外国人永久居住证； | ID_CARD | |
| legalCertNo | 是 | string | 64 | 法人身份证(需要AES加密) | |
| legalCertFrontUrl | 是 | string | 64 | 法人证件人脸照片 | |
| legalCertBackUrl | 是 | string | 64 | 法人证件国徽面照片 | |
| legalHandCertUrl | 否 | string | 64 | 法人手持身份证照片 | |
| legalCertAddress | 是 | string | 128 | 证件地址信息(需要AES加密) | |
| legalCertStartTime | 是 | string | 10 | 证件有效起始日期(yyyy-MM-dd) | 2024-01-01 |
| legalCertEndTime | 是 | string | 10 | 证件有效截止日期(yyyy-MM-dd)，如果是长期则传“长期” | 2050-01-01 |
| legalProvinceCode | 是 | string | 6 | 法人证件省份编码 | 310000 |
| legalCityCode | 是 | string | 6 | 法人证件城市编码 | 310100 |
| legalDistrictCode | 是 | string | 6 | 法人证件区县编码 | 310114 |
| legalEmail | 是 | string | 64 | 法人邮箱(需要AES加密) | |
| controllerCertType | 否 | string | 实控人证件类型： ID_CARD-身份证；PASSPORT-护照；HK_MACAO_PERMIT-港澳通行证；TW_PERMIT-台胞证；FOREIGN_PERMANENT-外国人永久居住证；实控人是法人的可不传 | ||
| controllerName | 否 | string | 64 | 实控人姓名(需要AES加密)，实控人是法人的可不传 | |
| controllerCertNo | 否 | string | 64 | 实控人证件号(需要AES加密)，实控人是法人的可不传 | |
| controllerPhoneNo | 否 | string | 64 | 实控人手机号(需要AES加密)，实控人是法人的可不传 | |
| controllerCertStarTime | 否 | string | 10 | 实控人证件有效起始时间，格式：yyyy-MM-dd，实控人是法人的可不传 | |
| controllerCertEndTime | 否 | string | 10 | 实控人证件有效截止时间，格式：yyyy-MM-dd,如果为长期则传“长期”，实控人是法人的可不传 | |
| controllerCertAddress | 否 | string | 128 | 实控人证件地址(需要AES加密)，实控人是法人的可不传 | |
| controllerCertFrontUrl | 否 | string | 64 | 实控人证件正面地址，实控人是法人的可不传 | |
| controllerCertBackUrl | 否 | string | 64 | 实控人证件反面地址，实控人证件类型为身份证时必传，实控人是法人的可不传 | |
| bankAccountNo | 是 | string | 64 | 结算账户(需要AES加密)，对私结算为结算卡卡号，对公结算为对公账号 | |
| bankPhoneNo | 否 | string | 64 | 银行预留手机号(需要AES加密)，对私结算必填 | |
| bankAccountType | 是 | string | 2 | 银行账户类型，小微商户仅支持对私，企业商户仅支持对公： BC-对公,BU-对私 | BU |
| bankAccountName | 是 | string | 32 | 银行账户名称(需要AES加密)，对公结算银行账户名称必须和企业营业执照名称一致 | xxx公司 |
| bankNo | 是 | string | 32 | 总行联行号 | 102100099996 |
| bankName | 是 | string | 32 | 总行名称 | 中国工商银行 |
| bankBranchNo | 是 | string | 32 | 支行联行号 | 102290017292 |
| bankBranchName | 是 | string | 32 | 支行名称 | 中国工商银行上海市徐家汇支行 |
| bankProvinceCode | 是 | string | 6 | 结算银行所在省编码 | 310000 |
| bankCityCode | 是 | string | 6 | 结算银行所在市编码 | 310100 |
| bankDistrictCode | 否 | string | 6 | 结算银行所在区编码 | 310104 |
| bankAccountImageUrl | 是 | string | 64 | 结算账户照片，对私为银行卡照片，对公为开户许可证照片 | |
| settleMode | 是 | string | 2 | 商户结算模式： D0-当日结算，D1-下一自然日结算，T1-下一工作日结算 | D0 |
| mccCode | 是 | string | 32 | mcc编码 | 7999 |
| industryCode | 是 | string | 32 | 行业类别编码 | 详见行业类别说明 |
| merchantName | 是 | string | 64 | 商户名称 | xxx小卖部,小微商户名称固定格式：商户_+法人名称，如：商户_张三 |
| merchantBriefName | 是 | string | 64 | 商户简称 | 小卖部 |
| busiLicNo | 否 | string | 32 | 统一社会信用代码，企业与个体工商户必填 | 102290017292 |
| busiLicName | 否 | string | 32 | 营业执照名称，企业与个体工商户必填 | xxx公司 |
| busiLicAddress | 否 | string | 32 | 商户地址，企业与个体工商户必填 | xxx路xx号xxx室 |
| busiLicStartTime | 否 | string | 10 | 营业执照有效期开始时间 | 2020-01-01 |
| busiLicEndTime | 否 | string | 10 | 营业执照有效期（结束时间），如果是长期或者无有效期则传“长期” | 2050-01-01 |
| busiLicPicUrl | 否 | string | 64 | 营业执照照片 | |
| busiProvinceCode | 否 | string | 6 | 营业执照地址所在省编码，企业与个体工商户必填 | 310000 |
| busiCityCode | 否 | string | 6 | 营业执照地址所在市编码，企业与个体工商户必填 | 310100 |
| busiDistrictCode | 否 | string | 6 | 营业执照地址所在区编码，企业与个体工商户必填 | 310104 |
| compFrontPicUrl | 否 | string | 64 | 企业前台照片，企业与个体工商户必填 | |
| compScenePicUrl | 否 | string | 32 | 企业场景照片，企业与个体工商户必填 | |
| busiPermitName | 否 | string | 32 | 经营许可证名称 | |
| busiPermitNo | 否 | string | 32 | 经营许可证编号 | |
| busiPermitStartTime | 否 | string | 10 | 经营许可证有效期开始时间，格式：yyyy-MM-dd | |
| busiPermitEndTime | 否 | string | 10 | 经营许可证有效期结束时间，格式：yyyy-MM-dd,如果为长期则传“长期” | |
| busiPermitPicUrl | 否 | string | 10 | 经营许可证照片 | |
| supplementMaterials | 否 | string | 512 | 补充材料，多个补充材料用半角逗号隔开（最多10个），补充材料应先通过文件上传接口上传后获取文件名称 | fileName1,fileName2,fileName3 |
| beneficiaryInfo | 否 | string | 64 | 受益人信息列表的json数组字符串(需要AES加密) | |
| - beneficiaryName | 是 | string | 64 | 受益所有人姓名 | |
| - benefitType | 是 | string | 32 | 受益人类型： OWNERSHIP_25_PERCENT:直接或间接拥有25%(含)以上股权或合伙权益 CONTROL_LEGAL_ENTITY:单独或者联合对法人组织进行实际控制 BENEFICIAL_25_PERCENT_SHARE:直接或者间接享有25%（含）以上收益权 SENIOR_MANAGEMENT:高级管理人员 | |
| - beneficiaryCertType | 是 | string | 32 | 受益所有人证件类型： ID_CARD-身份证；PASSPORT-护照；HK_MACAO_PERMIT-港澳通行证；TW_PERMIT-台胞证；FOREIGN_PERMANENT-外国人永久居住证；USCC-统一社会信用代码； | |
| - beneficiaryCertNo | 是 | string | 64 | 受益所有人证件号 | |
| - beneficiaryCertStartTime | 是 | string | 64 | 受益所有人证件有效期开始时间(yyyy-MM-dd) | 2020-01-01 |
| - beneficiaryCertEndTime | 是 | string | 64 | 受益所有人证件有效期结束时间(yyyy-MM-dd),如果长期则传“长期” | 2025-01-01 |
| - beneficiaryCertAddress | 是 | string | 64 | 受益所有人证件地址 | |
| - beneficiaryPhoneNo | 是 | string | 64 | 受益所有人手机号 | |
| - beneficiaryCertFrontUrl | 是 | string | 64 | 受益所有人证件正面照 | |
| - beneficiaryCertBackUrl | 是 | string | 64 | 受益所有人证件反面照 | |
| contactName | 是 | string | 64 | 联系人姓名(需要AES加密) | |
| contactPhoneNo | 是 | string | 64 | 联系人手机号(需要AES加密) | 联系人手机号不能重复使用 |
| contactEmail | 是 | string | 64 | 联系人邮箱(需要AES加密) | |
| storeAddress | 是 | string | 255 | 店铺详细地址 | |
| storeCategory | 是 | string | 2 | 店铺类型，小微商户必填： 01-流动摊位，02-固定门店，03-线上店铺 | 01 |
| storeLongitude | 否 | string | 店铺地址经度，小微商户必填 | ||
| storeLatitude | 否 | string | 店铺地址纬度，小微商户必填 | ||
| storeCashierPicUrl | 否 | string | 64 | 收银台照片 | |
| storeHeadPicUrl | 否 | string | 64 | 门头照片 | |
| storeIndoorPicUrl | 否 | string | 64 | 店内照片 | |
| storeGoodsPicUrl | 否 | string | 64 | 商品照片 | |
| storeProvinceCode | 是 | string | 6 | 店铺所在省编码 | 310000 |
| storeCityCode | 是 | string | 6 | 店铺所在市编码 | 310100 |
| storeDistrictCode | 是 | string | 6 | 店铺所在区编码 | 310101 |
| appImageUrl | 否 | string | 64 | APP首页截图照片 | |
| companyDomain | 否 | string | 128 | 企业官网 | |
| icp | 否 | string | 32 | icp备案号 | |
| videoUrl | 否 | string | 32 | 人脸认证视频链接 | |
| notifyUrl | 是 | string | 128 | 商户入网通知回调地址 | |
| feeInfo | 是 | string | 费率信息，费用产品列表的json字符串 | [{"endDate":"2099-12-31","feeCode":"ALIPAY","feeFixed":0,"feeRate":"0.6","startDate":"2024-11-13","feePayType":"1"},{"endDate":"2099-12-31","feeCode":"WXPAY","feeFixed":0,"feeRate":"0.6","startDate":"2024-11-13","feePayType":"1"}] | |
| - feeCode | 是 | string | 费用产品代码： 参考商户费用产品说明，间联商户入网必须服务商先开通对应费用产品商户才能开通 | ALIPAY | |
| - feeType | 是 | string | 计费类型： RATE-费率；FIXED-定额；MIX-混合(费率+单笔定额)，参考商户费用产品说明 | RATE | |
| - feeRate | 是 | string | 8 | 费用产品费率(%)，只能设置数字，0.0~0.999999，必须上送且不小于0，最大值以产品为准 | 0.60 |
| - feeFixed | 是 | number | 8 | 费用产品固定费(单位分)，0~99999999，必须上送且不小于0，最大值以产品为准 | 1 |
| - feePayType | 是 | string | 1 | 手续费收取方式;1-内扣;2-外扣;3-他扣 | 1 |
| - feePayRoleNo | 否 | string | 32 | 手续费支付角色编号(feePayType为3时，必传)，传商户编号或服务商编号 | 1 |
| - feePayRoleType | 否 | string | 10 | 手续费支付角色类型(feePayType为3时，必传)，传商户或服务商角色,MERCHANT-商户;AGENT-服务商 | 1 |
| - topFee | 否 | number | 8 | 费用产品手续费封顶值(单位分)，0~99999999，没有约定封顶费用的不传 | 2000 |
| - startDate | 是 | string | 10 | 费用产品开始日期(yyyy-MM-dd) | 2024-01-01 |
| - endDate | 是 | string | 10 | 费用产品结束日期(yyyy-MM-dd) | 2024-12-31 |
请求报文示例
json
{
"appId": "202408554212370909",
"bankAccountImageUrl": "PRIf7784ece29b7497aac3bb21df63829a6.png",
"bankAccountName": "JRK97dTOVaSwU3smFZ2uUQ==",
"bankAccountNo": "c9pR1sdwHDXoY9XW8T/V3D6OvGyx1STeM8qir+6Xeak=",
"bankAccountType": "BU",
"bankBranchName": "招商银行股份有限公司武汉东西湖支行",
"bankBranchNo": "308521015284",
"bankName": "招商银行",
"bankNo": "308584000013",
"bankPhoneNo": "h6f9rFZAgtWiNqWzBIAZKw==",
"contactEmail": "NFAud9j8HegfXnT2uZCVB3ehIXTJM1H4YRJRHuJzM9s=",
"contactName": "JRK97dTOVaSwU3smFZ2uUQ==",
"contactPhoneNo": "h6f9rFZAgtWiNqWzBIAZKw==",
"feeInfo": "[{\"endDate\":\"2099-12-31\",\"feeType\":\"RATE\",\"feeCode\":\"YOYIPAY\",\"feeFixed\":0,\"feeRate\":\"0.6\",\"startDate\":\"2024-11-13\"},{\"endDate\":\"2099-12-31\",\"feeType\":\"RATE\",\"feeCode\":\"ALIPAY\",\"feeFixed\":0,\"feeRate\":\"0.6\",\"startDate\":\"2024-11-13\",\"feePayType\":\"1\"}]",
"legalCertAddress": "bdkjGizwp6ZO+P3GmbCLGHF6NTd22QgxKFYLwHfsQopp2NpyWbXY2mBlj7hkblovoBkYtE77dsMKfIka84YH/SgyDQOjoGmYEAHcHiY2jyQ=",
"legalCertBackUrl": "PRI140d37bea52c4189b1685781a8b49653.png",
"legalCertEndTime": "2038-05-02",
"legalCertFrontUrl": "PRI2c7e3fe477a54e01a7efb7290cd9dc42.png",
"legalCertNo": "Lw178IM6/4jaQEpkDCbzHZqBUbML1LtR4Ew+YmcAQLo=",
"legalCertStartTime": "2018-05-02",
"legalCertType": "ID_CARD",
"legalCityCode": "330700",
"legalDistrictCode": "330703",
"legalEmail": "NFAud9j8HegfXnT2uZCVB3ehIXTJM1H4YRJRHuJzM9s=",
"legalName": "JRK97dTOVaSwU3smFZ2uUQ==",
"legalPhoneNo": "h6f9rFZAgtWiNqWzBIAZKw==",
"legalProvinceCode": "330000",
"mccCode": "5441",
"industryCode":"0009999999",
"merchantBriefName": "得动",
"merchantCategory": "T",
"merchantName": "商户_张三",
"notifyUrl": "https://aaa.bbb.ccc/notify",
"outMerchantNo": "ZD000000000013",
"settleMode": "D0",
"signature": "exCsFUiaSptDPtolFklsDx0yHrDGi5u1E9ujvoT/4mMPFW3Vq2criGow0fCh7ZyLRFe4CtYPrE/QH8RypiZtroofmlPytqbZKUX3cBCgOPkac/2Fhx1ffJdYrAhUeBSxtTNVC16kUSLjBn0wlcQr2AvFIj72nAj92MHUHeiQO3INuCYaA3cj8tWw5W5WoCBUWjYpdaxcIbOrJrHGu4yo+JcHoe/u/rxUN8crWXQvnSKdiMIPjigJeZ6S648Heui58ffhLrK7zuUOKwu4JdVBLOq+ta9Q1MUp3KkK6iR1ovqUuK0/lTk/F3QMZiBNdFq4yqMy8GRNSWAA7P99nC85qg==",
"storeAddress": "xx省xx市xx区xxx号",
"storeCashierPicUrl": "PRI77c3e4cb8a1749edbf7cdb56f71a0340.png",
"storeCategory": "02",
"storeCityCode": "330700",
"storeDistrictCode": "330703",
"storeGoodsPicUrl": "PRIee4714c0fa1e4b08972b185277ce7d0b.png",
"storeHeadPicUrl": "PRI2e54031ce5a74966a836753619169de9.png",
"storeIndoorPicUrl": "PRI7fe8f2161001466695a3f9966441e261.png",
"storeLatitude": "31.177287",
"storeLongitude": "121.414683",
"storeProvinceCode": "330000",
"transDate": "1731486017900",
"transNonce": "879df171f3de481d825e1e185638ee22",
"videoUrl": "PRIefc2789caea54cc7bb3560e7e459d29c.png"
}注意：
- 受益人信息加密时需要对beneficiaryInfo字符串信息整体加密，无需对内部敏感信息加密，签名时对加密前的字符串信息签名
- 小微商户店铺信息传：店铺类型，详细地址及店铺所在省市区，经纬度信息。固定门店需上传门头照片，店铺内景照片；流动摊贩需上传收银台照片，店铺商品照片， 企业或个体商户店铺信息传：店铺类型，详细地址及店铺所在省市区，其他信息按实际情况上送。
- 企业商户入网时，商户名称，营业执照名称，对公结算账户名称必须一致。
- 费率信息中： 计费类型传RATE时，feeFixed传0，即使传其他值也不会参与算费； 计费类型传FIXED时，feeRate传0，即使传其他值也不会参与算费； 计费类型传MIX时，feeRate和feeFixed都会参与算费； 费用封顶没有特殊约定的不要传；
- 请求信息中，值为空字符串的字段不要传。
- 接口请求信息中照片信息需调用图片上传接口，取返回报文中的fileUrl字段；
- 接口请求信息中省市区及银行信息上送请参考“开发&联调工具”中的省市区及银行附件；
- 测试环境的商户电子签约也需要真实企业或个人手机号信息，认证流程与正式环境相同；
- 小微商户电子签约时使用法人手机号进行短信验证；
- 间联商户签约链接有效期1天，过期需通过接口重新获取签约链接，成功获取新签约链接后原签约链接失效；
公共响应参数
| 参数名 | 必选 | 类型 | 最大长度 | 说明 | 示例 |
|---|---|---|---|---|---|
| code | 是 | string | 响应编码 | 00000000 | |
| message | 是 | string | 响应信息 | 成功 | |
| signature | 是 | string | 签名 | ||
| transNonce | 是 | string | 32 | 请求流水号(同入参) | 123456 |
| transDate | 是 | string | 13 | 请求时间，13位时间戳 | 1731406784607 |
响应参数
| 参数名 | 必选 | 类型 | 最大长度 | 说明 | 示例 |
|---|---|---|---|---|---|
| merchantNo | 是 | string | 32 | 商户编号 | XS241113000204 |
| merchantStatus | 是 | string | 商户状态： INIT-初始，PROCESSING-处理中，SUCCESS-入网成功，FAIL-入网失败 | PROCESSING | |
| auditStatus | 是 | string | 审核状态 WAIT-待审核，REFUSE-审核拒绝，PASS-审核通过 | PASS | |
| esignStatus | 否 | string | 签约状态 ESIGN_PROCESS-待签约，ESIGN_PROCESSING-签约中，ESIGN_SUCCESS-签约成功，ESIGN_FAIL-签约失败 | ESIGN_PROCESS |
响应示例
json
{
"auditStatus": "PASS",
"code": "00000000",
"merchantNo": "XS241113000204",
"merchantStatus": "PROCESSING",
"message": "成功",
"transDate": "1731486017900",
"transNonce": "879df171f3de481d825e1e185638ee22",
"signature": "exCsFUiaSptDPtolFklsDx0yHrDGi5u1E9ujvoT/4mMPFW3Vq2criGow0fCh7ZyLRFe4CtYPrE/QH8RypiZtroofmlPytqbZKUX3cBCgOPkac/2Fhx1ffJdYrAhUeBSxtTNVC16kUSLjBn0wlcQr2AvFIj72nAj92MHUHeiQO3INuCYaA3cj8tWw5W5WoCBUWjYpdaxcIbOrJrHGu4yo+JcHoe/u/rxUN8crWXQvnSKdiMIPjigJeZ6S648Heui58ffhLrK7zuUOKwu4JdVBLOq+ta9Q1MUp3KkK6iR1ovqUuK0/lTk/F3QMZiBNdFq4yqMy8GRNSWAA7P99nC85qg=="
}商户入网流程
商户电子签约流程
备注
- 更多返回错误代码请看首页的错误代码描述