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

# 常见问题

## 接入相关

### 如何获得 app\_key 和 app\_secret？

渠道商在星惠付管理后台完成入驻后，由平台分配 `app_key` 与 `app_secret`。请妥善保管 `app_secret`，**不要以明文形式**出现在代码仓库、日志或聊天记录中。

### 接口域名是什么？

* 测试环境：`https://go-test.xft.xin`
* 生产环境：`https://gw.xft.xin`

所有接口路径以 `/openapi` 开头，完整地址示例：`https://gw.xft.xin/openapi/v1/merchant/add`，各接口路径见接口文档的「请求路径」。

### 签名总是失败，常见原因有哪些？

* 时间戳与平台时间差超过 5 分钟（请校准服务器时间）；
* 签名原文中的 URL 不是完整地址（应包含实际调用的域名，如 `https://go-test.xft.xin` 或 `https://gw.xft.xin`，与路径）；
* 请求体与签名时的 body 不一致（请对发送的原始字节签名）；
* `app_secret` 配错或带有多余空格/换行。

详见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md)。

## 进件相关

### 小微商户进件要传什么材料？

小微商户（`merchant_type=MICRO`）无需营业执照：`license_no` 可不填，不传营业执照图片（category=1），改传统一社会信用代码证书（category=22）；商户名称按「商户\_XXX」规范填写。结算账户图片（银行卡等）按结算主体要求上传。

### reuse\_legal\_person 怎么用？

联系人复用法人信息时，将 `reuse_legal_person` 置为 `true`，联系人姓名、证件号码及联系人证件照（category=4/5）可不填，平台自动取法人信息。

### 图片类型传错了怎么办？

图片上传后 `key` 7 天有效，进件提交前可重新上传正确类型的图片，进件提交时引用正确的 `key` 即可。若进件已提交且被驳回，可重新上传图片后使用**新的 `out_apply_no`** 通过[商户录入](https://opendocs.xft.xin/open/payment/merchant/add.md)重新提交。

### 提交后如何知道审核结果？

平台仅对终态发送[审核异步通知](https://opendocs.xft.xin/open/payment/merchant/apply-notify.md)到 `back_url`，报文 `event_type` 显式标识事件：`MERCHANT_PASSED`/`MERCHANT_REJECTED`（商户审核，无机构维度）、`INSTITUTION_COMPLETED`/`INSTITUTION_REJECTED`/`INSTITUTION_FAILED`（单机构进件，逐机构通知）；中间态（顶层 `AUDITING`、机构层处理中）可通过[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)主动查询。

### 通知没收到怎么办？

平台按 1s/5s/30s/2min/6min 指数退避重试最多 5 次（单次通知超时 10 秒，应答 HTTP 200/204 视为成功）。若仍未收到，请通过[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)确认终态，并以查询结果为准；多次重试失败的通知会落库，可联系平台人工补发。

### 重复提交进件会怎么样？

同一调用主体、同一 `out_apply_no` 重复提交不会创建新申请单，接口返回 HTTP 200 与已受理申请单的当前状态（幂等语义），不报错、不重复建商户。

### 进件被驳回后如何重新提交？

使用**新的 `out_apply_no`** 重新调用[商户录入](https://opendocs.xft.xin/open/payment/merchant/add.md)接口，提交完整资料（含修改后的字段）。原 `out_apply_no` 一经受理不再重开，重复提交只会返回原申请单状态。

## 认证相关

### 认证申请后多久有结果？

认证申请提交后，平台返回申请单号（付临门为机构自动认证，无需扫码）。认证二维码不随申请响应返回，需调用[认证结果查询](https://opendocs.xft.xin/open/payment/auth/apply-query.md)获取 `qr_code`，由商户扫码完成微信/支付宝侧授权；申请进度与最终授权状态均以该接口的 `apply_status` / `auth_status` 为准。


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