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

# 进件流程指引

## 流程总览

商户进件分四个阶段：**渠道商上传图片 → 提交商户信息 → 平台审核 → 审核通过异步通知回调**。

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant P as 渠道商
    participant O as 开放平台
    participant C as 平台审核
    participant I as 支付机构

    Note over P,O: 阶段一 · 上传图片
    P->>O: 图片上传 file/upload
    O-->>P: 返回 key（7 天有效）
    loop 多张证件图片
        P->>O: 按 category 逐张上传
        O-->>P: key
    end

    Note over P,O: 阶段二 · 提交商户信息
    P->>O: 进件提交 apply（引用 key）
    O-->>P: 受理：apply_no + apply_status=AUDITING

    Note over P,C: 阶段三 · 平台审核
    O->>C: 人工审核（资料完整性与合规性）
    alt 审核通过
        C-->>O: 通过，商户进件成功（merchant_code）
        O->>I: 渠道进件（指定机构或平台分配）
        I-->>O: 微信/支付宝子商户号（sub_merchant_code）
        O-->>O: apply_status: PROCESSING → SUCCESS
    else 审核驳回
        C-->>O: 驳回（reject_reason）
        O-->>O: apply_status=REJECTED
    end

    Note over P,O: 阶段四 · 异步通知回调
    O-->>P: 通知 back_url（仅终态，验签）
    P-->>O: 应答 2xx 停止重试
    alt 通知失败
        O-->>P: 指数退避重试，最多 5 次
    end
```

## 阶段一：上传图片

进件所需证件图片（营业执照、法人身份证、门店照片等）先通过[图片上传](../merchant/file-upload)接口逐张上传，获得对象存储 `key`。

<Note>
  `key` 7 天内有效，过期需重新上传。上传时指定 `category`（附件类别编码），进件提交时只需上送 `category` + `key` 即可引用，无需按图片字段名逐张对应。
</Note>

## 阶段二：提交商户信息

调用[商户进件提交](../merchant/apply-create)接口，提交商户主体、法人、联系人、经营地址、结算账户、图片与产品信息（图片以 `key` 引用），`out_apply_no` 作为业务幂等键。

提交后平台异步受理，立即返回 `apply_no`（平台申请单号）与 `apply_status=AUDITING`，**不保证同步进件完成**。

## 阶段三：平台审核

平台审核人员对进件资料进行人工审核（校验素材完整性、合规性）。此阶段可通过[进件状态查询](../merchant/apply-query)轮询状态：

* 审核通过：平台完成商户进件（分配 `merchant_code`），随后向指定支付机构进件（未上送 `institution_codes` 时由平台分配）；商户进件完成、渠道进件进行中 `apply_status=PROCESSING`（`sub_merchant_code` 未就绪），渠道进件完成 `apply_status=SUCCESS`（`sub_merchant_code` 就绪）；机构侧返回的机构商户号以 `institution_merchant_code` 标识；
* 审核驳回：`apply_status=REJECTED`，附 `reject_reason`（标注平台驳回/渠道驳回）。

## 阶段四：审核通过异步通知回调

平台在\*\*终态（SUCCESS/REJECTED）\*\*时向 `back_url` 异步下发审核结果，见[审核异步通知](../merchant/apply-notify)：

* 通知报文需验签（`X-Signature` 等头信息，与开放平台签名算法一致）；
* 接收方须在 5 秒内应答 **HTTP 2xx**，否则平台按指数退避重试（最多 5 次）；
* 通知携带 `apply_no` 等字段，接收方按 `out_apply_no`/`apply_no` 幂等处理（终态可能重复送达）。

<Note>
  中间态（AUDITING/PROCESSING）不下发通知，以[进件状态查询](../merchant/apply-query)为准；通知最终失败落库，可联系平台补发。
</Note>

## 前置条件

渠道商在星富通管理后台完成入驻后，获得：

* `app_key` / `app_secret`（签名凭据，见[签名验签说明](../spec/signature)）；
* 渠道商产品模板与支付机构配置（进件时指定 `institution_codes`，不传由平台分配）。

## 驳回重提

审核驳回（REJECTED，附 `reject_reason`）后，渠道商按驳回原因修改资料，通过[商户进件提交](../merchant/apply-create)接口重新提交（同 `out_apply_no` + 完整资料，图片已过期的重新上传），平台以本次提交覆盖原申请单，重新进入待审核（AUDITING）。

## 不同商户主体的进件差异

| 维度                      | 企业（1）                  | 个体工商户（2）     | 事业单位/政府（3/4） | 小微（5）     |
| ----------------------- | ---------------------- | ------------ | ------------ | --------- |
| 营业执照编码 `license_no`     | 必填                     | 必填           | 必填           | 可不填       |
| 营业执照图片（category=1）      | 必传                     | 必传           | —            | —         |
| 统一社会信用代码证书（category=22） | —                      | —            | 必传           | 必传        |
| 单位证明函（category=17）      | —                      | —            | 必传           | —         |
| 法人证件照（category=2/3）     | 必传                     | 必传           | 必传           | 必传        |
| 商户名称规范                  | 执照名称                   | 无名称填「个体户XXX」 | 单位全称         | 「商户\_XXX」 |
| 结算图片                    | 按结算主体（对公→开户许可证，对私→银行卡） | 同左           | 同左           | 银行卡必传     |

完整必填差异见[商户进件提交](../merchant/apply-create#不同主体必填差异)与[图片类型编码表](../merchant/file-upload#图片类型编码表)。

## 状态流转

```
提交 ──► AUDITING ──► PROCESSING ──► SUCCESS
            │
            ▼
         REJECTED ──(修改重提)──► AUDITING
```

`CLOSED`（注销/终止）为二期状态，详见[状态机说明](../appendix/status)。