> ## 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.

# 商户进件提交

## 接口说明

渠道商将发展的商户进件至平台，一次性提交商户主体、法人、联系人、经营地址、结算账户、图片与产品信息。

* **异步受理**：接口立即返回受理结果与申请单状态，最终结果通过[审核异步通知](../merchant/apply-notify)下发；
* **幂等**：`out_apply_no` 为业务幂等键，同一渠道商下唯一；审核中重复提交返回原申请单当前状态，不报错；驳回后重新提交（同 `out_apply_no`）覆盖重提；
* **不同商户主体必填字段不同**：小微（5）可免营业执照，差异见[不同主体必填差异](#不同主体必填差异)。

**支持商户**：全部已开通进件权限的渠道商

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

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

**请求域名**：

| 域名                           | 说明                    |
| ---------------------------- | --------------------- |
| `https://gw.xft.xin/openapi` | 接口域名，路径前缀为 `/openapi` |

## 请求参数

请求体由 8 个分组组成，与新增商户的资料结构一致（基础信息、营业执照信息、法人信息、联系人信息、结算信息、附件信息），点击展开查看字段说明：

<AccordionGroup>
  <Accordion title="① 申请单信息">
    | 字段                  | 是否必选 | 类型           | 字段说明                                                                                           |
    | ------------------- | ---- | ------------ | ---------------------------------------------------------------------------------------------- |
    | `out_apply_no`      | 是    | String(≤64)  | 申请单号，业务幂等键。1、同一渠道商下唯一，审核中重复提交不报错，返回原申请单当前状态；2、仅限字母、数字、`-`、`_`；3、驳回后覆盖重提时须与已提交申请单一致             |
    | `back_url`          | 是    | String(≤256) | 审核结果异步通知地址。1、必须 HTTPS；2、仅终态（SUCCESS/REJECTED）下发通知；3、通知失败按指数退避重试最多 5 次，需长期可达                    |
    | `institution_codes` | 否    | Array        | 支付机构编码列表。1、指定后商户进件到指定支付机构，可传多个；2、不传时由平台分配进件机构。支付机构编码由平台分配，详见[支付机构列表](../appendix/institutions) |
    | `remark`            | 否    | String(≤50)  | 备注，供渠道商内部记录                                                                                    |
  </Accordion>

  <Accordion title="② 基础信息 basic_info">
    | 字段              | 是否必选 | 类型          | 字段说明                                                                        |
    | --------------- | ---- | ----------- | --------------------------------------------------------------------------- |
    | `type`          | 是    | String      | 商户主体类型：1=企业/2=个体工商户/3=事业单位/4=政府/5=小微/6=其他。不同主体必填字段不同，见[不同主体必填差异](#不同主体必填差异) |
    | `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      | 省份编码，国标行政区划代码（如 330000=浙江省）                                                 |
    | `city_code`     | 是    | String      | 城市编码（如 330100=杭州市）                                                          |
    | `district_code` | 是    | String      | 区/县编码（如 330106=西湖区）                                                         |
  </Accordion>

  <Accordion title="③ 营业执照信息 license_info">
    | 字段                       | 是否必选 | 类型            | 字段说明                                                      |
    | ------------------------ | ---- | ------------- | --------------------------------------------------------- |
    | `license_no`             | 条件   | String(≤64)   | 营业执照编码（统一社会信用代码），18 位。小微（5）可不填，但需传统一社会信用代码证书（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)  | 登记机关                                                      |
  </Accordion>

  <Accordion title="④ 法人信息 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) | 法人/经营者住址；与注册地址一致时可留空                       |
  </Accordion>

  <Accordion title="⑤ 联系人信息 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) | 联系人邮箱，接收协议与通知                                                                          |
  </Accordion>

  <Accordion title="⑥ 结算信息 settlement_info">
    | 字段                          | 是否必选 | 类型           | 字段说明                                                                           |
    | --------------------------- | ---- | ------------ | ------------------------------------------------------------------------------ |
    | `settlement_subject`        | 是    | String       | 结算主体：1=对公/2=法人对私/3=非法人对私。不同结算主体必传图片不同：对公→开户许可证（category=11），对私→银行卡（category=8） |
    | `settlement_cycle`          | 是    | String       | 结算周期，目前仅支持 D1（编码 5，次日自然日结算），其余周期暂不开放。由渠道商按商户协商结果上送，平台校验                        |
    | `bank_account_name`         | 是    | String(≤128) | 开户名称。1、对公结算填商户名称；2、对私结算填结算人姓名，须与银行卡持卡人一致                                       |
    | `bank_account_no`           | 是    | String(≤64)  | 银行账号：对公填企业基本户/一般户账号，对私填银行卡号                                                    |
    | `bank_name`                 | 是    | String(≤128) | 开户行名称，如「中国建设银行」                                                                |
    | `bank_code`                 | 是    | String       | 联行号（12 位数字）。1、与 `bank_name` 同时上送，用于精确匹配开户行；2、填错会导致结算打款失败                       |
    | `bank_branch`               | 否    | String(≤128) | 开户支行名称，如「中国建设银行杭州西湖支行」；对公结算建议填写，精确到支行                                          |
    | `account_type`              | 否    | String       | 账户类型：1=对公账户/2=个人账户，默认 1；应与 `settlement_subject` 对应（对公→1，对私→2）                  |
    | `bank_account_phone`        | 条件   | String(≤32)  | 收款人手机号；对私结算（settlement\_subject=2/3）必填，须与结算人一致                                 |
    | `account_id_no`             | 条件   | String(≤64)  | 收款人身份证号码；对私结算（settlement\_subject=2/3）必填，须与结算人一致                               |
    | `un_incorporate_card_begin` | 条件   | String       | 非法人身份证有效期起始，格式 `yyyy-MM-dd`；非法人对私结算（settlement\_subject=3）必填                   |
    | `un_incorporate_card_end`   | 条件   | String       | 非法人身份证有效期截止，格式 `yyyy-MM-dd`；非法人对私结算（settlement\_subject=3）必填，长期（无期限）留空         |
  </Accordion>

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

  <Accordion title="⑧ 产品信息 products">
    | 字段                        | 是否必选 | 类型     | 字段说明                                             |
    | ------------------------- | ---- | ------ | ------------------------------------------------ |
    | `products`                | 是    | Array  | 产品列表，元素见下方子字段                                    |
    | `products[].product_code` | 是    | String | 产品码，见[产品清单](../appendix/products)；同一产品码重复上送以一次为准 |
    | `products[].fee_items`    | 是    | Array  | 费率配置项列表（至少 1 条），见下方子字段                           |

    `products[].fee_items[]` 子字段（对应商户产品费率配置）：

    | 字段               | 是否必选 | 类型     | 字段说明                                   |
    | ---------------- | ---- | ------ | -------------------------------------- |
    | `types`          | 是    | String | 费率类型：1=固定费率/2=阶梯费率/3=固定费率+封顶/4=阶梯费率+封顶 |
    | `val`            | 是    | String | 费率值（十万分比，例：0.6% → 600）                 |
    | `dc_flag`        | 否    | String | 借贷标志：`OD`=借记卡/`DC`=贷记卡                 |
    | `min_amt`        | 条件   | String | 阶梯最低金额（分）；阶梯费率（types=2/4）逐档上送时使用       |
    | `max_amt`        | 条件   | String | 阶梯最高金额（分）；阶梯费率（types=2/4）逐档上送时使用       |
    | `min_fee`        | 否    | String | 最低手续费（分）                               |
    | `max_fee`        | 否    | String | 最高手续费（分）；封顶（types=3/4）时使用              |
    | `fee_bearer`     | 否    | String | 手续费承担方：1=品牌商户/2=当前商户                   |
    | `deduction_rule` | 否    | String | 扣费规则：1=内扣/2=外扣                         |

    <Note>
      产品与费率由渠道商按商户协商结果上送，平台校验合法性；审核通过后按此开通产品。支付机构若指定（`institution_codes`），产品须在指定机构已开通。
    </Note>
  </Accordion>
</AccordionGroup>

## 请求示例

```json theme={null}
{
  "out_apply_no": "P20260815001",
  "back_url": "https://merchant.example.com/notify",
  "institution_codes": ["INS001"],
  "basic_info": {
    "type": "1",
    "name": "杭州星富通科技有限公司",
    "short_name": "星富通",
    "industry": "5999",
    "service_phone": "0571-88888888",
    "province_code": "330000",
    "city_code": "330100",
    "district_code": "330106"
  },
  "license_info": {
    "license_no": "91330100MA27XXXXX0",
    "license_type": "企业法人营业执照",
    "registered_capital": "500万",
    "established_date": "2018-06-01",
    "business_term_start": "2018-06-01",
    "business_term_end": "",
    "business_scope": "技术服务、软件开发；批发、零售",
    "registered_address": "浙江省杭州市西湖区XX路XX号",
    "registration_authority": "杭州市市场监督管理局"
  },
  "legal_person": {
    "legal_person_id_name": "张三",
    "legal_person_id_no": "330100199001010011",
    "legal_person_id_start": "2020-01-01",
    "legal_person_id_end": "",
    "legal_phone": "13800000000",
    "legal_id_address": "浙江省杭州市西湖区XX路XX号"
  },
  "contact_info": {
    "reuse_legal_person": true,
    "phone": "13800000000",
    "email": "contact@example.com"
  },
  "settlement_info": {
    "settlement_subject": "1",
    "settlement_cycle": "1",
    "bank_account_name": "杭州星富通科技有限公司",
    "bank_account_no": "330016016000000000000",
    "bank_name": "中国建设银行",
    "bank_code": "105331080158",
    "bank_branch": "中国建设银行杭州西湖支行",
    "account_type": "1"
  },
  "pictures": [
    { "category": "1", "key": "f_20260815A1B2C3" },
    { "category": "2", "key": "f_20260815D4E5F6" },
    { "category": "3", "key": "f_20260815G7H8I9" },
    { "category": "6", "key": "f_20260815J0K1L2" },
    { "category": "7", "key": "f_20260815M3N4O5" },
    { "category": "11", "key": "f_20260815P6Q7R8" }
  ],
  "products": [
    {
      "product_code": "WECHAT_JSAPI",
      "fee_items": [
        {
          "types": "1",
          "val": "600",
          "dc_flag": "DC",
          "min_fee": "100",
          "max_fee": "5000",
          "fee_bearer": "2",
          "deduction_rule": "1"
        }
      ]
    },
    {
      "product_code": "ALIPAY_F2F",
      "fee_items": [
        { "types": "1", "val": "380", "dc_flag": "DC" }
      ]
    }
  ]
}
```

## 不同主体必填差异

| 维度                                 | 企业（1）       | 个体（2）  | 事业/政府（3/4） | 小微（5）  | 其他（6） |
| ---------------------------------- | ----------- | ------ | ---------- | ------ | ----- |
| 营业执照编码 `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 | 平台申请单号，报障时使用         |
| `apply_status` | 是    | String | 申请状态，受理后为 `AUDITING` |
| `timestamp`    | 是    | int64  | 受理时间，秒级时间戳           |

## 响应示例

**受理成功**

```json theme={null}
{
  "out_apply_no": "P20260815001",
  "apply_no": "AP2026081500001",
  "apply_status": "AUDITING",
  "timestamp": 1755234000
}
```

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

```json theme={null}
{
  "out_apply_no": "P20260815001",
  "apply_no": "AP2026081500001",
  "apply_status": "REJECTED",
  "timestamp": 1755234600
}
```

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

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

<Note>
  受理不代表进件成功：`AUDITING` 后平台人工审核，终态结果通过[审核异步通知](../merchant/apply-notify)下发；审核驳回后修改资料，重新调用本接口（同 `out_apply_no`）覆盖重提。
</Note>