> ## 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={"system"}
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: 商户录入 merchant/add（引用 key，institutions 必填）
    O-->>P: 受理即建商户：merchant_code + apply_no + apply_status=AUDITING

    Note over P,C: 阶段三 · 平台审核与机构进件
    O->>C: 人工审核（资料完整性与合规性）
    alt 审核通过
        C-->>O: apply_status=PASSED
        O->>I: 按渠道商配置逐机构发起进件（institutions 指定）
        I-->>O: 机构进件结果（机构商户号/子商户号）
        O-->>O: institutions[].apply_status: SUBMITTED → VERIFYING → SIGNING → COMPLETED
    else 审核驳回
        C-->>O: apply_status=REJECTED（reject_reason）
    end

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

## 阶段一：上传资料图片

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

> [!NOTE]
>
> `key` 7 天内有效，过期需重新上传。上传时指定 `category`（附件类别编码），录入时只需上送 `category` + `key` 即可引用，无需按图片字段名逐张对应。

## 阶段二：录入商户

调用[商户录入](https://opendocs.xft.xin/open/payment/merchant/add.md)接口，提交商户主体、法人、联系人、经营地址、结算账户、图片与逐机构产品费率，`out_apply_no` 作为业务幂等键。

* **受理即建商户**：接口立即创建商户并返回 `merchant_code`、`apply_no` 与 `apply_status=AUDITING`，不等待审核与机构进件；
* **必须指定进件机构**：`institutions` 必填（至少 1 个），逐个指定支付机构及其产品费率，平台不做兜底分配；
* **重复提交幂等**：同一调用主体、同一 `out_apply_no` 重复提交返回原申请单当前状态，不报错、不重复建商户。

## 阶段三：平台审核与机构进件

平台审核人员对资料进行人工审核。此阶段可通过[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)轮询：

* **审核通过**：顶层 `apply_status=PASSED`。按渠道商配置决定是否自动发起进件：开启自动进件时，平台自动向 `institutions` 指定的每个机构发起进件；未开启时由平台运营手动发起。各机构进度独立，在 `institutions[]` 中逐机构返回：
  * `SUBMITTED`=已提交 → `VERIFYING`=核身中 → `SIGNING`=签约中 → `COMPLETED`=已完成；
  * 机构驳回 `REJECTED`、进件失败 `FAILED`；
  * 进件完成后返回 `institution_merchant_code`、`wechat_sub_merchant_code`、`alipay_sub_merchant_code`、`terminal_code` 等结果字段。
* **审核驳回**：顶层 `apply_status=REJECTED`，附 `reject_reason`。

> [!NOTE]
>
> 顶层状态反映商户审核结果，机构层状态反映单机构进件进度，两层独立；某一机构失败不影响其他机构进件，也不会把顶层状态改为驳回。完整取值见[状态机说明](https://opendocs.xft.xin/open/payment/appendix/status.md)。

## 阶段四：异步通知回调

平台在**终态**向 `back_url` 异步下发结果，见[审核异步通知](https://opendocs.xft.xin/open/payment/merchant/apply-notify.md)：

* **商户审核通过**：`event_type=MERCHANT_PASSED`，无机构维度；
* **商户审核驳回**：`event_type=MERCHANT_REJECTED`，无机构维度；
* **机构维度终态**：`event_type=INSTITUTION_COMPLETED`/`INSTITUTION_REJECTED`/`INSTITUTION_FAILED`，报文带 `institution_code`，逐机构各发一条；
* 通知请求带签名头（`Client-Id`/`Signature-Type`/`Timestamp`/`Nonce-Str`/`Signature`），签名算法与[开放平台请求签名](https://opendocs.xft.xin/open/payment/spec/signature.md)一致；
* 接收方须在 **10 秒内**返回 **HTTP 200**，且 body 为 `{"code":"SUCCESS","message":"成功"}`（`code` 必须为 `SUCCESS`）；其他状态码或业务码不符视为失败，平台按 `1s → 5s → 30s → 2min → 6min` 退避重试，最多 5 次；
* 通知按 `out_apply_no` + `institution_code` + `apply_status` 幂等，终态可能重复送达，请按该键去重。

> [!NOTE]
>
> 中间态（审核中、进件处理中）不下发通知，以[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)为准；通知最终失败落库，可联系平台补发。

## 前置条件

渠道商/品牌在星惠付管理后台完成入驻后，需具备：

* `app_key` / `app_secret`（签名凭据，见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md)）；
* **渠道商费率档**：渠道商须已在平台配置各「机构 × 产品」的代理费率，商户录入费率必须在该档位内（见[结算周期及手续费说明](https://opendocs.xft.xin/open/payment/guide/settlement.md#手续费费率)），否则整体拒绝。

## 驳回重提

审核驳回（`REJECTED`，附 `reject_reason`）后，渠道商按驳回原因修改资料，使用**新的 `out_apply_no`** 重新调用[商户录入](https://opendocs.xft.xin/open/payment/merchant/add.md)接口（图片已过期的重新上传）。原 `out_apply_no` 一经受理不再重开，重复提交只会返回原申请单状态。

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

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

> [!NOTE]
>
> 上表为通用资料要求；完整字段差异见[商户录入](https://opendocs.xft.xin/open/payment/merchant/add.md#不同主体必填差异)与[图片类型编码表](https://opendocs.xft.xin/open/payment/merchant/file-upload.md#图片类型编码表)。

## 状态流转

**顶层（商户入驻申请，`apply_status`）**

```
录入 ──► AUDITING ──► PASSED
            │
            ▼
         REJECTED ──(换新 out_apply_no 重新录入)──► AUDITING
```

**机构层（单机构进件申请，`institutions[].apply_status`）**

```
SUBMITTED ──► VERIFYING ──► SIGNING ──► COMPLETED
                 │              │
                 ├──► REJECTED  └──► FAILED
                 └──► FAILED
```

详见[状态机说明](https://opendocs.xft.xin/open/payment/appendix/status.md)。


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