> ## 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/appendix/return-code.md)中同步维护。
* 接口路径一经发布保持稳定，新增能力通过新增接口或字段提供，不影响既有对接。

## 版本记录

### v1.1.0（2026-10-18）

**新增能力**

* 新增[签约信息查询](https://opendocs.xft.xin/open/payment/merchant/sign-info.md)接口：按机构进件申请单号（`institutions[].apply_no`）查询签约状态、签约链接与合同号；
* [进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)响应补齐 `institutions[]` 机构明细：`apply_no`、机构进件状态、状态更新时间、机构商户号、银联/微信/支付宝子商户号、终端号、渠道返回码；
* [商户状态查询](https://opendocs.xft.xin/open/payment/merchant/merchant-query.md)补充 `audit_status` 审核状态，与商户业务状态 `merchant_status` 相互独立；
* [商户录入](https://opendocs.xft.xin/open/payment/merchant/add.md)结算信息补充开户地区（`bank_province_code`/`bank_city_code`/`bank_district_code`）与开户支行联行号（`bank_branch_cnaps_code`）等必填字段说明；费率校验口径明确为「借记/贷记成对 + 不得低于渠道商代理费率 + 与渠道商费率档逐项匹配」；补充资料图片要求说明。

**契约调整**

* 「商户进件提交」口径调整为**商户录入**：受理即建商户，审核通过后由平台按渠道商配置发起机构进件；
* 进件状态改为两层：[顶层](https://opendocs.xft.xin/open/payment/appendix/status.md) `apply_status`（AUDITING/PASSED/REJECTED）为商户审核结果，`institutions[].apply_status`（SUBMITTED/VERIFYING/SIGNING/COMPLETED/REJECTED/FAILED）为单机构进件状态；
* [审核异步通知](https://opendocs.xft.xin/open/payment/merchant/apply-notify.md)改为终态事件：报文新增 `event_type` 显式标识事件类型（`MERCHANT_PASSED`/`MERCHANT_REJECTED`/`INSTITUTION_COMPLETED`/`INSTITUTION_REJECTED`/`INSTITUTION_FAILED`），商户审核通过/驳回落 `PASSED`/`REJECTED`（均无机构维度），机构维度 `COMPLETED`/`REJECTED`/`FAILED`（带 `institution_code`），幂等键 `out_apply_no + institution_code + event_type`；
* 所有接口响应 `timestamp` 统一为字符串格式 `yyyy-MM-dd HH:mm:ss`（北京时间）；
* 认证域接口按实际实现修正路径与字段：认证申请改为 `/v1/merchant/auth/{wechat,alipay}/apply`，认证结果查询改为 `/auth/{wechat,alipay}/query`，子商户信息查询改为 `/auth/{wechat,alipay}/info`，新增[撤销认证](https://opendocs.xft.xin/open/payment/auth/cancel.md)、[银联报备查询](https://opendocs.xft.xin/open/payment/auth/unionpay-query.md)、[机构信息查询](https://opendocs.xft.xin/open/payment/auth/institution-info.md)；
* 商户变更类接口（商户信息变更、变更状态查询）与微信 APPID / 授权目录配置接口**暂未开放**，相关文档标注为规划稿。

### v1.0.0（一期，2026-08-15）

**开放范围**

* 商户进件类接口 4 个：图片上传、商户进件提交、进件状态查询、商户状态查询；
* 商户变更类接口 2 个：商户信息变更、变更状态查询（变更经平台审核，通过后生效）；
* 微信支付宝认证配置接口 3 个：认证申请、认证状态查询、子商户信息查询；
* 微信商户配置接口 2 个：微信商户新增APPID、微信商户新增授权目录（经平台审核，通过后同步至微信商户平台）；
* 审核异步通知（进件终态结果回调 `back_url`）。

**协议**

* 采用 app\_key 对称签名机制（HMAC-SHA256），详见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md)。

**已知约定**

* 进件重复提交（同 `out_apply_no`）幂等返回原申请单当前状态，不报错；
* 通知仅终态下发，中间态（AUDITING/PROCESSING）以[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)为准（v1.1.0 起状态机调整为两层，见上文）；
* 接口域名 `https://gw.xft.xin`，接口路径统一以 `/openapi` 开头。

> [!NOTE]
>
> 一期为人工审核模式：进件提交后由平台审核人员审核，审核结果通过异步通知 + 查询接口获取。


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