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

# 聚合支付统一下单

## 功能说明

除付款码支付场景外，商户系统都可先通过调用该接口生成预支付交易单，返回正确的预支付交易标识后商户再按小程序支付、JSAPI、APP 等不同场景生成的交易串调起支付，支付完成后，异步通知商户支付结果。

## 请求地址

`POST /v1/aggregate/payment/prepare/pay`

## 请求参数

| 字段                  | 类型     | 必填 | 说明                                               |
| ------------------- | ------ | -- | ------------------------------------------------ |
| `out_trade_no`      | string | 是  | 商户请求流水号，每次必须唯一                                   |
| `business_trade_no` | string | 否  | 业务流水号                                            |
| `merchant_code`     | string | 是  | 商户编码                                             |
| `amount`            | object | 是  | 订单金额，单位：分，详见下方 Amount 说明                         |
| `attach`            | string | 否  | 商户数据包（附加数据）                                      |
| `subject`           | string | 是  | 订单标题                                             |
| `body`              | string | 否  | 商品描述                                             |
| `notify_url`        | string | 否  | 支付结果异步通知地址                                       |
| `payer`             | object | 否  | 预支付参数，详见下方 Payer 说明                              |
| `scene_info`        | object | 否  | 场景信息，详见下方 SceneInfo 说明                           |
| `expired_at`        | string | 否  | 交易有效期，请求格式：`yyyyMMddHHmmss`；示例值：`20220912111230` |
| `product_code`      | string | 是  | 支付产品编码，详见 [ProductCode 枚举](#productcode)         |

**Amount 对象**

| 字段               | 类型     | 必填 | 说明                                 |
| ---------------- | ------ | -- | ---------------------------------- |
| `total`          | int    | 是  | 订单总金额，单位：分                         |
| `payer_total`    | int    | 否  | 用户支付金额，单位：分（使用优惠券的情况下，等于总金额减优惠券金额） |
| `currency`       | string | 否  | 订单金额货币类型；`CNY`：人民币，境内商户号仅支持人民币     |
| `payer_currency` | string | 否  | 用户支付货币类型                           |

**Payer 对象**

| 字段            | 类型     | 必填 | 说明         |
| ------------- | ------ | -- | ---------- |
| `sub_open_id` | string | 否  | 子商户 openid |
| `sub_app_id`  | string | 是  | 子商户 appid  |

**SceneInfo 对象**

| 字段           | 类型     | 必填 | 说明                       |
| ------------ | ------ | -- | ------------------------ |
| `device_id`  | string | 否  | 商户端设备号（门店号或收银设备 ID）      |
| `device_ip`  | string | 是  | 商户端设备 IP                 |
| `store_info` | object | 否  | 商户门店信息，详见下方 StoreInfo 说明 |

**StoreInfo 对象**

| 字段       | 类型     | 必填 | 说明                                        |
| -------- | ------ | -- | ----------------------------------------- |
| `id`     | string | 否  | 门店编号（微信支付线下场所 ID，格式为纯数字）；与 `out_id` 二选一必填 |
| `out_id` | string | 否  | 商家自定义编码（商户系统的门店编码）；与 `id` 二选一必填           |

<span id="productcode" />**ProductCode 枚举**

| 编码                | 说明        |
| ----------------- | --------- |
| `WECHAT_JSAPI`    | 微信公众号     |
| `WECHAT_MINIAPP`  | 微信小程序     |
| `WECHAT_NATIVE`   | 微信正扫      |
| `WECHAT_H5`       | 微信 H5 支付  |
| `WECHAT_APP`      | 微信 APP 支付 |
| `ALIPAY_JSAPI`    | 支付宝 JS 支付 |
| `ALIPAY_NATIVE`   | 支付宝正扫     |
| `ALIPAY_MINIAPP`  | 支付宝小程序    |
| `UNIONPAY_NATIVE` | 银联正扫      |
| `UNIONPAY_JSAPI`  | 银联 JS 支付  |

## 请求示例

```json theme={null}
{
  "out_trade_no": "ea51203e1a0146d7954b39ac88aecaf7",
  "business_trade_no": "B20231025152300001",
  "merchant_code": "226801000000865319122",
  "amount": {
    "total": 100,
    "currency": "CNY"
  },
  "subject": "示例商品",
  "body": "线下订单服务费",
  "notify_url": "https://example.com/notify",
  "payer": {
    "sub_open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
    "sub_app_id": "wx1234567890abcdef"
  },
  "expired_at": "20220912111230",
  "product_code": "WECHAT_MINIAPP",
}
```

## 响应参数

| 字段                  | 类型     | 说明                                                                                |
| ------------------- | ------ | --------------------------------------------------------------------------------- |
| `trade_state`       | string | 支付状态，详见 [TradeState 枚举](/open/xianghe/aggregate-payment-v1/get-charge#tradestate) |
| `trade_state_desc`  | string | 支付状态描述                                                                            |
| `trade_channel`     | string | 支付渠道                                                                              |
| `trade_no`          | string | 微信、支付宝等第三方交易号                                                                     |
| `failure_code`      | string | 失败码                                                                               |
| `failure_msg`       | string | 失败信息                                                                              |
| `platform_trade_no` | string | 平台流水号                                                                             |
| `out_trade_no`      | string | 商户流水号                                                                             |
| `business_trade_no` | string | 商户业务订单号                                                                           |
| `wechat_pay_params` | object | 微信 JSAPI、小程序 支付参数，详见下方说明                                                          |
| `alipay_params`     | object | 支付宝 JS支付、小程序支付参数，详见下方说明                                                           |
| `unionpay_params`   | object | 云闪付JS支付参数，详见下方说明                                                                  |

**WechatPayParams 对象（微信 JSAPI 支付所需参数）**

| 字段          | 类型     | 说明        |
| ----------- | ------ | --------- |
| `app_id`    | string | 微信 appid  |
| `timestamp` | string | 时间戳       |
| `nonce_str` | string | 随机字符串     |
| `package`   | string | 订单详情扩展字符串 |
| `sign_type` | string | 签名方式      |
| `pay_sign`  | string | 签名        |

**AlipayParams 对象（支付宝小程序支付所需参数）**

| 字段         | 类型     | 说明                              |
| ---------- | ------ | ------------------------------- |
| `trade_no` | string | 支付宝 tradeNO，用于 `my.tradePay` 调起 |

**UnionPayParams 对象（云闪付JS支付所需参数）**

| 字段   | 类型     | 说明                              |
| ---- | ------ | ------------------------------- |
| `tn` | string | 云闪付 TN（交易流水号），用于 `upomp.pay` 调起 |

## 响应示例

以下示例以微信小程序支付为例：

```json theme={null}
{
  "trade_state": "09",
  "trade_state_desc": "待支付",
  "trade_channel": "WECHAT",
  "trade_no": "4200001234202310251234567890",
  "failure_code": "",
  "failure_msg": "",
  "platform_trade_no": "20231025152300000001",
  "out_trade_no": "ea51203e1a0146d7954b39ac88aecaf7",
  "business_trade_no": "B20231025152300001",
  "wechat_pay_params": {
    "app_id": "wx1234567890abcdef",
    "timestamp": "1698218580",
    "nonce_str": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
    "package": "prepay_id=wx20231025152300abcdef1234567890",
    "sign_type": "RSA",
    "pay_sign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ1xNnN..."
  },
  "alipay_params": null,
  "unionpay_params": null
}
```