> ## Documentation Index
> Fetch the complete documentation index at: https://opendocs.xft.xin/llms.txt
> Use this file to discover all available pages before exploring further.

# 商户录入

## 接口说明

渠道商/品牌将商户信息录入平台，一次性提交商户主体、法人、联系人、经营地址、结算账户、图片与产品费率，并指定支付机构。平台审核通过后按渠道商配置发起机构进件。

* **异步受理**：接口立即受理并创建商户，返回受理结果与申请状态；审核结果通过[审核异步通知](https://opendocs.xft.xin/open/payment/merchant/apply-notify.md)下发；
* **幂等**：`out_apply_no` 为业务幂等键，同一调用主体（app\_key 对应的渠道商/品牌）下唯一；重复提交（含驳回后）一律返回原申请单当前状态，不报错、不重复建商户；驳回后需使用**新的 `out_apply_no`** 重新录入；
* **不同商户主体必填字段不同**：小微（`MICRO`）可免营业执照，差异见[不同主体必填差异](#不同主体必填差异)。

**支持商户**：全部已开通进件权限的渠道商（及其旗下品牌）

**请求方式**：`POST`

**请求路径**：`/openapi/v1/merchant/add`

## 请求参数

请求体由下列 8 个分组组成（申请单信息、基础信息、营业执照信息、法人信息、联系人信息、结算信息、附件信息、进件机构与产品信息），点击展开查看字段说明：

> 契约口径：状态/类型类字段一律使用英文语义值（如 `merchant_type=ENTERPRISE`、`settlement_cycle=D1`、`fee_type=FLAT`），不使用数字裸值。

> **① 申请单信息**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `out_apply_no` | 是 | String(≤64) | 申请单号，业务幂等键。1、同一调用主体下唯一，重复提交不报错，返回原申请单当前状态；2、驳回后需换新单号重新录入，原单号一经受理不再重开 |
> | `back_url` | 是 | String(≤256) | 结果异步通知地址。1、必须 HTTPS；2、仅终态下发（`event_type`：`MERCHANT_PASSED`/`MERCHANT_REJECTED`/`INSTITUTION_COMPLETED`/`INSTITUTION_REJECTED`/`INSTITUTION_FAILED`，报文见[审核异步通知](https://opendocs.xft.xin/open/payment/merchant/apply-notify.md)）；3、通知失败按 1s/5s/30s/2min/6min 退避重试最多 5 次，需长期可达 |
> | `institutions` | 是 | Array | 进件机构列表（必填，至少 1 个），元素见 ⑧。渠道商指定进件到哪些支付机构、各机构下哪些产品费率，平台不做兜底分配。支付机构编码由平台分配，详见[支付机构列表](https://opendocs.xft.xin/open/payment/appendix/institutions.md) |
> | `remark` | 否 | String(≤50) | 备注，供渠道商内部记录 |

> **② 基础信息 basic\_info**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `merchant_type` | 是 | String | 商户主体类型：`ENTERPRISE`=企业/`INDIVIDUAL`=个体工商户/`PUBLIC_INSTITUTION`=事业单位/`GOVERNMENT`=政府/`MICRO`=小微/`OTHER`=其他。不同主体必填字段不同，见[不同主体必填差异](#不同主体必填差异) |
> | `name` | 是 | String(≤42) | 商户名称。1、企业填营业执照名称；2、个体工商户无名称时填「个体户XXX」；3、小微填「商户\_XXX」 |
> | `short_name` | 是 | String(≤64) | 商户简称，收银台与账单展示，建议 20 字以内 |
> | `industry` | 否 | String(≤64) | 经营类目，四位数 MCC 编码，如 5999=其他零售、5812=餐饮。建议上送且与实际经营一致，与费率、风控相关 |
> | `service_phone` | 否 | String(≤32) | 客服电话，用户账单与售后展示 |
> | `province_code` | 是 | String | 省份编码，国标行政区划代码（如 430000=湖南省） |
> | `city_code` | 是 | String | 城市编码（如 430100=长沙市） |
> | `district_code` | 是 | String | 区/县编码（如 430104=岳麓区） |

> **③ 营业执照信息 license\_info**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `license_no` | 条件 | String(≤64) | 营业执照编码（统一社会信用代码），18 位。小微（`MICRO`）可不填，但需传统一社会信用代码证书（category=22） |
> | `license_type` | 否 | String(≤64) | 营业执照类型，如「企业法人营业执照」 |
> | `registered_capital` | 否 | String(≤64) | 注册资本 |
> | `established_date` | 否 | String | 成立日期，格式 `yyyy-MM-dd` |
> | `business_term_start` | 否 | String | 营业期限起始，格式 `yyyy-MM-dd` |
> | `business_term_end` | 条件 | String | 营业期限截止，格式 `yyyy-MM-dd`；长期（无期限）留空，需与执照图片显示一致 |
> | `business_scope` | 否 | String(≤2000) | 经营范围，需与营业执照一致 |
> | `registered_address` | 是 | String(≤256) | 注册地址，需与营业执照一致 |
> | `registration_authority` | 否 | String(≤128) | 登记机关 |

> **④ 法人信息 legal\_person**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `legal_person_id_name` | 是 | String(≤64) | 法人/经营者姓名 |
> | `legal_person_id_no` | 是 | String(≤32) | 法人/经营者证件号码；身份证 18 位，需与证件图片（category=2/3）一致 |
> | `legal_person_id_start` | 是 | String | 证件有效期起始，格式 `yyyy-MM-dd` |
> | `legal_person_id_end` | 否 | String | 证件有效期截止，格式 `yyyy-MM-dd`；长期（无期限）留空 |
> | `legal_phone` | 否 | String(≤32) | 法人手机号，审核回访与风控联系使用 |
> | `legal_id_address` | 否 | String(≤256) | 法人/经营者住址；与注册地址一致时可留空 |

> **⑤ 联系人信息 contact\_info**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `reuse_legal_person` | 否 | Boolean | 联系人是否复用法人信息。1、`true` 时联系人姓名、证件号码、联系人证件照（category=4/5）可不填，自动取法人信息；2、`false`（默认）需填写联系人资料 |
> | `name` | 条件 | String(≤64) | 联系人姓名；不复用法人时必填 |
> | `identity_number` | 条件 | String(≤32) | 联系人证件号码；不复用法人时必填 |
> | `phone` | 是 | String(≤32) | 联系人手机号，商户后台登录账号，须与商户实际经办人一致 |
> | `email` | 是 | String(≤128) | 联系人邮箱，接收协议与通知 |

> **⑥ 结算信息 settlement\_info**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `settlement_subject` | 是 | String | 结算主体：`CORPORATE`=对公/`LEGAL_PERSON`=法人对私/`NON_LEGAL_PERSON`=非法人对私。不同结算主体必传图片不同：对公→开户许可证（category=11），对私→银行卡（category=8） |
> | `settlement_cycle` | 是 | String | 结算周期，目前仅支持 `D1`（次日自然日结算），其余周期暂不开放。由渠道商按商户协商结果上送，平台校验 |
> | `bank_account_name` | 是 | String(≤128) | 开户名称。1、对公结算填商户名称；2、对私结算填结算人姓名，须与银行卡持卡人一致 |
> | `bank_account_no` | 是 | String(≤64) | 银行账号：对公填企业基本户/一般户账号，对私填银行卡号 |
> | `bank_name` | 否 | String(≤128) | 开户银行名称，无需上送；平台按 `bank_cnaps_code` 从银行字典匹配并回填标准名称 |
> | `bank_cnaps_code` | 是 | String(≤32) | 开户银行**总行**联行号（12 位数字），平台据此回填开户银行名称 |
> | `bank_branch` | 否 | String(≤128) | 开户支行名称，无需上送；平台按 `bank_branch_cnaps_code` 从银行字典匹配并回填标准名称 |
> | `bank_branch_cnaps_code` | 是 | String(≤32) | 开户**支行**联行号（12 位数字），平台据此回填支行名称 |
> | `bank_province_code` | 是 | String(≤16) | 开户地区省份编码，国标行政区划代码（如 430000=湖南省） |
> | `bank_city_code` | 是 | String(≤16) | 开户地区城市编码（如 430100=长沙市） |
> | `bank_district_code` | 是 | String(≤16) | 开户地区区/县编码（如 430104=岳麓区） |
> | `bank_account_phone` | 条件 | String(≤32) | 收款人手机号；对私结算（settlement\_subject=LEGAL\_PERSON/NON\_LEGAL\_PERSON）必填，须与结算人一致 |
> | `account_id_no` | 条件 | String(≤64) | 收款人身份证号码；对私结算（settlement\_subject=LEGAL\_PERSON/NON\_LEGAL\_PERSON）必填，须与结算人一致 |
> | `un_incorporate_card_begin` | 条件 | String | 非法人身份证有效期起始，格式 `yyyy-MM-dd`；非法人对私结算（settlement\_subject=NON\_LEGAL\_PERSON）必填 |
> | `un_incorporate_card_end` | 条件 | String | 非法人身份证有效期截止，格式 `yyyy-MM-dd`；非法人对私结算（settlement\_subject=NON\_LEGAL\_PERSON）必填，长期（无期限）留空 |

> **⑦ 附件信息 pictures**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `pictures` | 是 | Array | 附件列表，元素见下方子字段；必传图片随商户主体、结算主体变化，见[不同主体必填差异](#不同主体必填差异) |
> | `pictures[].category` | 是 | String | 附件类别编码，完整编码表见[图片类型编码表](https://opendocs.xft.xin/open/payment/merchant/file-upload.md#图片类型编码表) |
> | `pictures[].key` | 是 | String | 对象存储 Key，来自[图片上传](https://opendocs.xft.xin/open/payment/merchant/file-upload.md)，7 天内有效，过期需重新上传 |

> **⑧ 进件机构与产品信息 institutions**
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `institutions[].institution_code` | 是 | String(≤64) | 支付机构编码，见[支付机构列表](https://opendocs.xft.xin/open/payment/appendix/institutions.md) |
> | `institutions[].products` | 是 | Array | 该机构下产品列表（至少 1 条），元素见下方子字段 |
> | `products[].product_code` | 是 | String | 产品码，见[产品清单](https://opendocs.xft.xin/open/payment/appendix/products.md) |
> | `products[].fee_items` | 是 | Array | 费率配置项列表（至少 1 条），见下方子字段 |
>
> `products[].fee_items[]` 子字段：
>
> | 字段 | 是否必填 | 类型 | 字段说明 |
> | - | - | - | - |
> | `fee_type` | 是 | String | 费率类型：`FLAT`=固定费率/`FLAT_CAPPED`=固定费率+封顶/`TIERED_CAPPED`=阶梯费率+封顶 |
> | `val` | 是 | String | 费率值（十万分比，例：0.6% → 600） |
> | `dc_flag` | 是 | String | 借贷标志：`OD`=借记卡/`DC`=贷记卡 |
> | `min_amt` | 条件 | String | 阶梯最低金额（分）；阶梯费率（fee\_type=TIERED\_CAPPED）逐档上送时使用 |
> | `max_amt` | 条件 | String | 阶梯最高金额（分）；阶梯费率（fee\_type=TIERED\_CAPPED）逐档上送时使用 |
> | `min_fee` | 否 | String | 最低手续费（分） |
> | `max_fee` | 否 | String | 最高手续费（分）；封顶（fee\_type=FLAT\_CAPPED/TIERED\_CAPPED）时使用 |
>
> > [!NOTE]
> >
> > 产品与费率由渠道商按商户协商结果上送，平台逐机构逐产品校验，任一不满足**整单拒绝**：
> >
> > 1. 同一产品必须\*\*同时提交借记卡（`OD`）与贷记卡（`DC`）\*\*两条费率，缺一不可；
> > 2. 商户费率（及封顶时的最低/最高手续费）**不得低于渠道商代理费率**；
> > 3. 每条费率须与渠道商费率档**逐项匹配**（机构 + 产品 + 借贷标志 + 费率类型 + 金额区间），渠道商未配置对应档位的机构/产品不接受录入。

## 请求示例

```json theme={"system"}
{
  "out_apply_no": "TST-20261018-CH-0012",
  "back_url": "https://merchant.example.com/notify",
  "remark": "商户接入申请",
  "institutions": [
    {
      "institution_code": "EASYPAY",
      "products": [
        {
          "product_code": "WECHAT_MICRO_PAY",
          "fee_items": [
            { "fee_type": "FLAT", "val": "320", "dc_flag": "OD", "min_amt": "0", "max_amt": "0", "min_fee": "0", "max_fee": "0" },
            { "fee_type": "FLAT", "val": "320", "dc_flag": "DC", "min_amt": "0", "max_amt": "0", "min_fee": "0", "max_fee": "0" }
          ]
        },
        {
          "product_code": "ALIPAY_MICRO_PAY",
          "fee_items": [
            { "fee_type": "FLAT", "val": "320", "dc_flag": "OD", "min_amt": "0", "max_amt": "0", "min_fee": "0", "max_fee": "0" },
            { "fee_type": "FLAT", "val": "320", "dc_flag": "DC", "min_amt": "0", "max_amt": "0", "min_fee": "0", "max_fee": "0" }
          ]
        },
        {
          "product_code": "UNIONPAY_MICRO_PAY",
          "fee_items": [
            { "fee_type": "FLAT", "val": "320", "dc_flag": "OD", "min_amt": "0", "max_amt": "0", "min_fee": "0", "max_fee": "0" },
            { "fee_type": "FLAT", "val": "320", "dc_flag": "DC", "min_amt": "0", "max_amt": "0", "min_fee": "0", "max_fee": "0" }
          ]
        }
      ]
    }
  ],
  "basic_info": {
    "merchant_type": "ENTERPRISE",
    "name": "杭州西湖云帆智慧零售有限公司",
    "short_name": "云帆数据",
    "industry": "08003",
    "service_phone": "0571-88990044",
    "province_code": "330000",
    "city_code": "330100",
    "district_code": "330106"
  },
  "license_info": {
    "license_no": "91330106MA2K9YX23F",
    "license_type": "营业执照",
    "registered_capital": "800",
    "established_date": "2021-11-08",
    "business_term_start": "2021-11-08",
    "business_term_end": "2041-11-07",
    "business_scope": "数据处理服务；大数据服务；信息系统集成服务；软件开发；信息技术咨询服务",
    "registered_address": "浙江省杭州市西湖区文三路478号华星科技大厦9楼",
    "registration_authority": "杭州市西湖区市场监督管理局"
  },
  "legal_person": {
    "legal_person_id_name": "陆文昊",
    "legal_person_id_no": "330114198809213456",
    "legal_person_id_start": "2006-09-01",
    "legal_person_id_end": "",
    "legal_phone": "13800139011",
    "legal_id_address": "浙江省杭州市西湖区文三路478号"
  },
  "contact_info": {
    "reuse_legal_person": false,
    "name": "沈佳怡",
    "identity_number": "330114199512084567",
    "phone": "13900139012",
    "email": "jy.shen@yunfan-data.tech"
  },
  "settlement_info": {
    "settlement_subject": "CORPORATE",
    "settlement_cycle": "D1",
    "bank_account_name": "杭州西湖云帆智慧零售有限公司",
    "bank_account_no": "33050101110778889900",
    "bank_name": "上海浦东发展银行",
    "bank_cnaps_code": "313491099996",
    "bank_branch": "上海浦东发展银行股份有限公司长沙五一路支行",
    "bank_branch_cnaps_code": "310551000065",
    "bank_province_code": "430000",
    "bank_city_code": "430100",
    "bank_district_code": "430102"
  },
  "pictures": [
    { "category": "1", "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb" },
    { "category": "2", "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb" },
    { "category": "3", "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb" },
    { "category": "6", "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb" },
    { "category": "7", "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb" },
    { "category": "11", "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb" }
  ]
}
```

## 不同主体必填差异

| 维度 | 企业 `ENTERPRISE` | 个体 `INDIVIDUAL` | 事业/政府 `PUBLIC_INSTITUTION`/`GOVERNMENT` | 小微 `MICRO` | 其他 `OTHER` |
| - | - | - | - | - | - |
| 营业执照编码 `license_no` | 必填 | 必填 | 必填 | 可不填 | 必填 |
| 营业期限截止 `business_term_end` | 必填 | 必填 | 必填 | 可不填 | 必填 |
| 营业执照图片（category=1） | 必传 | 必传 | — | — | — |
| 统一社会信用代码证书（category=22） | — | — | 必传 | 必传 | 必传 |
| 单位证明函（category=17） | — | — | 必传 | — | — |
| 法人证件照（category=2/3） | 必传 | 必传 | 必传 | 必传 | 必传 |
| 联系人证件照（category=4/5） | 联系人不复用法人时必传 | 同左 | — | 可复用法人 | 同左 |
| 门头照（category=7）/ 门店内景照（category=6） | 必传 | 必传 | 必传 | 必传 | 必传 |
| 开户许可证（category=11） | 对公结算必传 | 对公结算必传 | 对公结算必传 | — | — |
| 银行卡正面（category=8） | 对私结算必传 | 对私结算必传 | — | 对私结算必传 | — |
| 非法人结算授权书（category=13） | 非法人结算必传 | — | — | — | — |

## 响应参数

| 字段 | 是否必填 | 类型 | 字段说明 |
| - | - | - | - |
| `out_apply_no` | 是 | String | 申请单号，原样返回 |
| `apply_no` | 是 | String | 平台申请单号，报障时使用 |
| `merchant_code` | 是 | String | 商户编码。受理即建商户，可用于[进件进度查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)与[商户查询](https://opendocs.xft.xin/open/payment/merchant/merchant-query.md)，报障时使用 |
| `apply_status` | 是 | String | 申请状态，受理后为 `AUDITING` |
| `timestamp` | 是 | String | 受理时间，格式 `yyyy-MM-dd HH:mm:ss`（北京时间） |

## 响应示例

**受理成功**

```json theme={"system"}
{
  "out_apply_no": "P20260815001",
  "apply_no": "APL2608151000230001",
  "merchant_code": "801260815123456",
  "apply_status": "AUDITING",
  "timestamp": "2026-08-15 10:00:23"
}
```

**重复提交（幂等，返回原申请单当前状态）**

```json theme={"system"}
{
  "out_apply_no": "P20260815001",
  "apply_no": "APL2608151000230001",
  "merchant_code": "801260815123456",
  "apply_status": "REJECTED",
  "timestamp": "2026-08-16 09:30:00"
}
```

**失败（参数错误）**

```json theme={"system"}
{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[out_apply_no]",
  "metadata": {}
}
```

> [!NOTE]
>
> 受理不代表进件成功：`AUDITING` 后平台人工审核，终态结果通过[审核异步通知](https://opendocs.xft.xin/open/payment/merchant/apply-notify.md)下发；审核驳回后修改资料，使用**新的 `out_apply_no`** 重新调用本接口（原单号重复提交只会返回原状态）。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.