> ## 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://go-test.xft.xin` | `/openapi` |
| 生产环境 | `https://gw.xft.xin` | `/openapi` |

接口完整地址 = 请求域名 + 请求路径；各接口文档的「请求路径」已包含 `/openapi` 前缀，文档中的完整 URL 示例使用生产域名。

> [!NOTE]
>
> 测试与生产使用不同域名，凭据（app\_key/app\_secret）按环境分别签发，请勿混用；具体以平台开通为准。

## 联调参数

联调测试使用的参数由平台开通渠道商/品牌时分配，请向对接支持人员索取。示例值（仅演示，不可用于线上）：

| 参数 | 示例值 |
| - | - |
| app\_key | `a1b2c3d4e5f67890a1b2c3d4e5f67890` |
| app\_secret | `f6e5d4c3b2a19087f6e5d4c3b2a19087` |

## 公共请求头

| Header | 必填 | 说明 |
| - | - | - |
| `Content-Type` | 是 | `application/json`（图片上传为 `multipart/form-data`） |
| `Client-Id` | 是 | app\_key，32 位十六进制 |
| `Signature-Type` | 是 | 固定 `HmacSHA256` |
| `Timestamp` | 是 | 秒级时间戳，与平台时间差 ≤ 5 分钟 |
| `Nonce-Str` | 是 | 随机串（建议 32 位十六进制），5 分钟内不可重复 |
| `Signature` | 是 | 请求签名，构造方法见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md) |

## 通用响应

| 项 | 说明 |
| - | - |
| 成功 | HTTP 200，业务数据平铺在 body，无业务码包装 |
| 失败 | HTTP 4xx/5xx + 统一错误体（`code`/`reason`/`message`/`metadata`），见[返回码说明](https://opendocs.xft.xin/open/payment/appendix/return-code.md) |
| `Signature` | 响应头恒带平台签名，**包括错误响应**；验签方式见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md#响应验签平台--渠道商可选但推荐) |

> [!NOTE]
>
> 错误体中的 `code` 是错误码数值，业务错误时与 HTTP 状态码一致；网关验签/鉴权类拒绝除外（如验签失败 HTTP 401、body `code`=403 `NO_AUTH`）。判断错误以 `reason` 为准。

## 业务字段约定

| 约定 | 说明 |
| - | - |
| 时间 | 业务字段（`timestamp` 等）一律字符串 `yyyy-MM-dd HH:mm:ss`（北京时间）；纯日期字段格式 `yyyy-MM-dd`；签名头 `Timestamp` 为秒级时间戳 |
| 金额 | 一律为字符串，单位为分；费率 `val` 为十万分比（0.6% → `"600"`） |
| 枚举 | 状态/类型类字段一律英文语义值，取值见[枚举值说明](https://opendocs.xft.xin/open/payment/appendix/enums.md) |
| 空值 | 空值字段省略，不返回也不上送 |
| 附件 | 图片先通过[图片上传](https://opendocs.xft.xin/open/payment/merchant/file-upload.md)获取 `key`（7 天有效），录入时以 `key` 引用 |


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