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

# 统一支付

## 统一响应参数

| 字段        | 是否必选 | 字段类型    | 字段说明 |
| --------- | ---- | ------- | ---- |
| `code`    | 是    | String  | 错误码  |
| `message` | 是    | String  | 错误信息 |
| `result`  | 是    | Boolean | 返回结果 |
| `data`    | 是    | String  | 业务参数 |

<Note>
  以下支付，查询，退款，撤销，关闭订单的响应参数为统一响应参数中的业务参数，封装在 data 中。
</Note>

## 支付接口

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/pay`

**请求参数**

| 字段              | 是否必选 | 字段类型   | 字段说明                       |
| --------------- | ---- | ------ | -------------------------- |
| `app_id`        | 是    | String | app\_id, 由系统统一分配           |
| `merchant_code` | 是    | String | 商户号                        |
| `store_code`    | 否    | String | 门店编号                       |
| `operator_id`   | 否    | String | 操作员id                      |
| `limit_pay`     | 否    | String | 00-全部 01-限定不能使用信用卡支付 默认值00 |
| `out_trade_no`  | 是    | String | 商户订单号                      |
| `channel`       | 否    | String | 支付渠道                       |
| `product`       | 否    | String | 支付产品，详细参考附录-支付产品属性值        |
| `client_ip`     | 是    | String | 客户端调用的 IP                  |
| `amount`        | 是    | int    | 支付金额，单位分                   |
| `subject`       | 是    | String | 订单标题                       |
| `body`          | 是    | String | 商品描述信息                     |
| `description`   | 是    | String | 订单附加说明                     |
| `extra`         | 否    | String | 特定支付产品发起交易时额外参数，json字符串    |
| `notify_url`    | 否    | String | 交易的通知地址                    |
| `callback_url`  | 否    | String | 收银台支付成功回跳地址                |
| `time_start`    | 否    | String | 订单生成时间，yyyyMMddHHmmss      |
| `time_expire`   | 否    | String | 订单失效时间，yyyyMMddHHmmss      |
| `memo`          | 否    | String | 附加备注                       |
| `goods_tag`     | 否    | String | 订单优惠标记                     |
| `detail`        | 否    | String | 微信单品营销用                    |
| `goods_detail`  | 否    | String | 支付宝商品明细列表                  |
| `sign_type`     | 是    | String | 签名类型                       |
| `sign`          | 是    | String | 签名值                        |

**响应参数**

| 字段                 | 是否必选 | 字段类型   | 字段说明              |
| ------------------ | ---- | ------ | ----------------- |
| `id`               | 是    | String | 通知支付平台流水号         |
| `out_trade_no`     | 是    | String | 商户订单号             |
| `state`            | 是    | String | 订单状态（参考附录-订单状态详情） |
| `credential`       | 是    | String | 调用支付的凭证           |
| `third_trade_no`   | 是    | String | 第三方流水号            |
| `channel_trade_no` | 否    | String | 微信支付宝订单号          |
| `failure_code`     | 是    | String | 业务参数 code         |
| `failure_msg`      | 是    | String | 业务结果描述            |
| `sign_type`        | 是    | String | 签名类型              |
| `sign`             | 是    | String | 签名值               |

### 支付凭证 credential 说明

**WECHAT\_LITE / WECHAT\_OFFICE\_ACCOUNT**

| 字段             | 字段类型   | 字段说明      |
| -------------- | ------ | --------- |
| `appId`        | String | 公众号 id    |
| `packageValue` | String | 订单详情扩展字符串 |
| `nonceStr`     | String | 随机字符串     |
| `timeStamp`    | String | 时间戳       |
| `paySign`      | String | 签名值       |
| `signType`     | String | 签名类型      |

**WECHAT\_H5 / ALIPAY\_H5 / BALANCE\_PAY**: `h5_url` (String) - 支付跳转链接

**WECHAT\_APP**: `prepay_id` (String) - 预支付交易会话标识

**ALIPAY\_FIXED\_QRCODE**: `trade_no` (String) - 支付宝返回的售易号

**CASHIERPAY**: `url`（收银台地址）, `form`（调起收银台form表单）

**WECHAT\_DYNAMIC\_SCAN\_CODE / ALIPAY\_DYNAMIC\_SCAN\_CODE**: `qr_code` (String) - 二维码码串

**ALIPAY\_APP**: `orderString` (String) - 预支付参数

**B2B\_PAY**: `form` (String) - form 表单

**APP\_TO\_WECHAT\_LITE**: `lite_username`, `lite_appid`, `path`

<Note>
  系统返回的应答或通知消息可能会由于升级增加参数，请验证通知签名或处理应答报文时注意允许这种情况。
</Note>

## 支付接口 V2

**请求地址**: `https://xlink.91xft.cn/transaction/v2/unify/charge/pay`

参数及响应与支付接口一致，响应额外返回 `payer_id` 付款人标识。

## 定额聚合支付

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/qrPrePay`

**请求参数**

| 字段              | 是否必选 | 字段类型   | 字段说明                                   |
| --------------- | ---- | ------ | -------------------------------------- |
| `app_id`        | 是    | String | app\_id                                |
| `merchant_code` | 是    | String | 统一平台分配的商户号                             |
| `store_code`    | 否    | String | 门店编号                                   |
| `operator_id`   | 否    | String | 收银员id                                  |
| `out_trade_no`  | 是    | String | 商户系统内部订单号                              |
| `amount`        | 是    | String | 交易金额，单位分                               |
| `callback_url`  | 否    | String | 支付成功前端回调地址                             |
| `notify_url`    | 否    | String | 支付成功异步通知地址                             |
| `attach`        | 否    | String | 订单备注                                   |
| `body`          | 否    | String | 商品描述信息                                 |
| `subject`       | 否    | String | 订单标题                                   |
| `extra`         | 否    | String | `{"qr_code_to_img":"Y"}` Y 表示接口返回二维码图片 |
| `sign_type`     | 是    | String | 签名类型                                   |
| `sign`          | 是    | String | 签名值                                    |

**credential**：`qr_code` (String) 二维码码串，`qr_code_img_url` (String) 图片 url。

## 订单查询

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/query`

支付订单和退款订单都用该接口查询。

**请求参数**：`app_id`, `merchant_code`, `out_trade_no`(与 third\_trade\_no 任一必传), `third_trade_no`, `client_ip`, `extra`, `sign_type`, `sign`。

**响应参数**

| 字段                 | 是否必选 | 字段类型   | 字段说明                  |
| ------------------ | ---- | ------ | --------------------- |
| `id`               | 是    | String | 平台流水号                 |
| `out_trade_no`     | 是    | String | 商户订单号                 |
| `amount`           | 是    | int    | 订单金额（分）               |
| `state`            | 是    | String | 交易状态                  |
| `payer_id`         | 否    | String | 付款人标识                 |
| `subject`          | 是    | String | 订单标题                  |
| `body`             | 是    | String | 商品描述信息                |
| `description`      | 是    | String | 订单附加说明                |
| `channel`          | 是    | String | 支付渠道                  |
| `product`          | 是    | String | 支付产品                  |
| `store_code`       | 是    | String | 门店编号                  |
| `operator_id`      | 是    | String | 操作员 id                |
| `third_trade_no`   | 否    | String | 第三方流水号                |
| `channel_trade_no` | 否    | String | 微信支付宝订单号              |
| `failure_code`     | 是    | String | 业务参数 code             |
| `failure_msg`      | 是    | String | 业务结果描述                |
| `sign_type`        | 是    | String | 签名类型                  |
| `sign`             | 是    | String | 签名值                   |
| `update_time`      | 否    | String | 订单完成时间 yyyyMMddHHmmss |

## 申请退款

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/refund`

**请求参数**

| 字段               | 是否必选 | 字段类型   | 字段说明     |
| ---------------- | ---- | ------ | -------- |
| `app_id`         | 是    | String | app\_id  |
| `merchant_code`  | 是    | String | 商户       |
| `out_trade_no`   | 是    | String | 原交易订单号   |
| `third_trade_no` | 否    | String | 第三方支付流水号 |
| `out_refund_no`  | 是    | String | 退款订单号    |
| `total_amount`   | 是    | int    | 交易金额（分）  |
| `refund_amount`  | 是    | int    | 退款金额（分）  |
| `subject`        | 是    | String | 商品标题     |
| `body`           | 是    | String | 商品描述     |
| `description`    | 是    | String | 附加说明     |
| `extra`          | 否    | String | 预留字段     |
| `notify_url`     | 否    | String | 通知地址     |
| `sign_type`      | 是    | String | 签名类型     |
| `sign`           | 是    | String | 签名值      |

## 撤销交易

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/cancel`

请求参数: `app_id`, `merchant_code`, `out_trade_no`, `third_trade_no`(否), `out_cancel_no`, `subject`, `body`, `description`, `extra`, `sign_type`, `sign`。

## 关闭订单

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/close`

请求参数: `app_id`, `out_trade_no`, `merchant_code`, `subject`, `body`, `description`, `extra`, `sign_type`, `sign`。

## 订单通知

支付完成后，统一平台系统会把支付结果发送给商户，商户需要接收处理，并返回应答。通知频率为 15/15/30/180/1800/1800/1800/1800/3600，单位：秒。

<Warning>
  商户系统对于支付结果通知的内容一定要做签名验证，并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄漏导致出现“假通知”，造成资金损失。
</Warning>

<Note>
  通知参数不需要加入统一响应参数 data 中。
</Note>

| 字段                 | 是否必选 | 字段类型   | 字段说明                  |
| ------------------ | ---- | ------ | --------------------- |
| `out_trade_no`     | 是    | String | 商户订单号                 |
| `created`          | 是    | String | 订单生成时间 yyyyMMddHHmmss |
| `third_trade_no`   | 是    | String | 第三方流水号                |
| `channel_trade_no` | 否    | String | 微信支付宝订单号              |
| `state`            | 是    | String | 订单状态                  |
| `merchant_code`    | 是    | String | 商户编号                  |
| `update_time`      | 是    | String | 订单支付时间                |
| `amount`           | 是    | int    | 订单金额（分）               |
| `store_code`       | 是    | String | 门店编号                  |
| `operator_id`      | 是    | String | 操作员 id                |
| `product`          | 是    | String | 支付产品                  |
| `client_ip`        | 是    | String | 客户端调用的 IP             |
| `subject`          | 是    | String | 订单标题                  |
| `body`             | 是    | String | 商品描述                  |
| `description`      | 是    | String | 订单附加说明                |
| `payer_id`         | 否    | String | 付款人标识                 |
| `sign_type`        | 是    | String | 签名类型                  |
| `sign`             | 是    | String | 签名值                   |

**返回**：处理成功返回 SUCCESS，不分大小写。

## 退款订单通知

暂只支持 channel 为 WECHAT / SXF / IPSPAY，其他支付渠道为同步退款或可通过查询接口查询。

| 字段                | 是否必选 | 字段类型   | 字段说明     |
| ----------------- | ---- | ------ | -------- |
| `out_trade_no`    | 是    | String | 商户订单号（原） |
| `out_refund_no`   | 是    | String | 退款订单号    |
| `refund_amount`   | 是    | int    | 退款金额（分）  |
| `amount`          | 是    | int    | 原订单金额（分） |
| `third_refund_no` | 是    | String | 第三方退款订单号 |
| `state`           | 是    | String | 订单状态     |
| `merchant_code`   | 是    | String | 商户编号     |
| `store_code`      | 是    | String | 门店编号     |
| `refund_time`     | 是    | String | 退款完成时间   |
| `product`         | 是    | String | 支付产品     |
| `subject`         | 是    | String | 订单标题     |
| `body`            | 是    | String | 商品描述     |
| `description`     | 是    | String | 订单附加说明   |
| `sign_type`       | 是    | String | 签名类型     |
| `sign`            | 是    | String | 签名值      |

## 下载对账

**请求地址**: `https://xlink.91xft.cn/settle/bill/download/query`

请求参数: `app_id`, `merchant_code`, `sign`, `sign_type`, `bill_date`(yyyyMMdd), `bill_type`(1-对账单)。响应返回 `bill_download_url`。

## 下载渠道对账

**请求地址**: `https://xlink.91xft.cn/settle/bill/agent/download/query`

请求参数: `app_id`, `agent_code`, `sign`, `sign_type`, `bill_date`, `bill_type`(1-对账单, 3-结算文件)。响应返回 `bill_download_url`。

## 下载结算文件

**请求地址**: `https://xlink.91xft.cn/settle/bill/download`

请求参数: `app_id`, `merchant_code`, `sign`, `sign_type`, `bill_date`。响应返回 `bill_download_url`。

## 收款设备获取商户支付信息

**请求地址**: `https://xlink.91xft.cn/transaction/device/query/pay/info`

请求参数: `app_id`, `device_sn`, `sign`。响应参数包括 `md5_key`, `device_sn`, `merchant_code`, `store_code`, `operator_id`, `sign`, `app_id`。

## 支付验证码

**请求地址**: `https://xlink.91xft.cn/transaction/unify/charge/sms`

请求参数: `app_id`, `sign_type`, `sign`, `merchant_code`, `wc_user_id`。响应 `check_code` 有效期900秒。

## 当日订单流水

**请求地址**: `https://xlink.91xft.cn/settle/transaction/out/pos/list`

请求参数: `app_id`, `sign_type`, `sign`, `merchant_code`, `store_code`(否), `operator_id`(否), `limit`, `offset`。

响应字段包括：`id`, `createTime`, `outTradeNo`, `platTradeNo`, `thirdTradeNo`, `merchantFullName`, `merchantCode`, `storeFullName`, `storeCode`, `operatorId`, `operatorName`, `institutionName`, `productCodeDesc`, `stateDesc`, `amount`, `discountAmount`, `totalAmount`, `preRateAmount`, `channelTradeNo`, `productCode`, `institutionCode`, `refundAmount`, `state`, `successTime`, `tradeDate`。