# 预下单

#### 功能介绍

开发者可以调用该接口获取预支付ID（prepayId）。  

#### 场景描述

在接入Payment Kit的单次支付功能前，开发者需要调用该接口获取到预支付ID（prepayId），用prepayId构建[orderStr](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#orderstr)参数返回给客户端调用支付接口拉起华为支付收银台。  

#### 接口原型

* 承载协议： HTTPS POST

* 接口方向： 开发者服务器 -\> 华为支付服务器

* 接口URL： https://petalpay-developer.cloud.huawei.com.cn/api/v2/aggr/preorder/create/app

  说明：元服务预下单接口请使用<https://petalpay-developer.cloud.huawei.com.cn/api/v2/aggr/preorder/create/fa>
* 数据格式：

  请求消息：Content-Type: application/json; charset=UTF-8

响应消息：Content-Type: application/json; charset=UTF-8  

#### 请求参数

Request Header  

|参数|是否必选|参数类型|描述|
|:-----------|:---|:-----|:---------------------------------------------------------------------------------------------------------------------|
|Content-Type|是|String|取值为：application/json; charset=UTF-8|
|PayMercAuth|是|String|取值为：[PayMercAuth](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#paymercauth)的JSON字符串|

Request Body  

|参数|是否必选|类型|说明|
|:---------------|:---|:-------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|appId|是|String|应用ID。获取方式请参见[AppID管理及关联](https://developer.huawei.com/consumer/cn/doc/pay-docs/hwzf-appidguanli-0000001757041165)。|
|mercOrderNo|是|String|商户订单号，由商户自己生成，商户需保证订单信息唯一性。最大长度46。|
|mercNo|是|String|商户号。最大长度12。|
|tradeSummary|是|String|交易的摘要。格式建议："商户应用名称-商品描述"。最大长度128。|
|totalAmount|是|Long|订单金额，必须为大于0的整数值，单位：分。|
|currency|否|String|交易币种单位，最大长度为3。 CNY （默认，当前仅支持该币种单位）|
|goodsDetail|否|List\<[GoodDetail](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#gooddetail)\>|订单详细信息列表。|
|allocationType|否|String|分账类型。 - NO_ALLOCATION：不分账（默认） - DELAY_ORDER_ALLOCATION：延时分账 说明： 使用该字段需联系开发者的商户对接人协助申请开通分账能力。分账相关操作参见[分账交易管理](https://developer.huawei.com/consumer/cn/doc/pay-docs/hwzf-dongjiefenzhang-0000001200646822)。|
|callbackUrl|是|String|回调通知地址，通知URL必须为外网环境可直接访问的URL，要求为https地址。具体要求参考[通知回调接口说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-rest-overview#通知回调接口说明)。最大长度为512。|
|payload|否|String|商户预留信息，在查询和回调通知时会原样返回。最大长度255。|
|expireTime|否|String|交易过期时间。此时间必须为准确的UTC时间。 格式要求："yyyy-MM-dd'T'HH:mm:ss.SSSZ" 。 说明： - 下单过期时间，不传默认2个小时，如果传递则最小值无限制，最大180天，超过180天系统会报错。 - 传已过时间可能会导致订单因过期、超时等原因异常关闭。 - 开发者可以参考[获取对应的UTC过期时间示例](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-appendix#获取对应的utc过期时间示例)来获取对应的UTC过期时间。|
|payer|否|[PayerIn](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#payerin)|支付者信息。|
|selectPromotions|否|[SelectPromotions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-model#selectpromotions)|平台券信息。|

#### 请求示例

```
POST /api/v2/aggr/preorder/create/app HTTP/1.1
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120***","traceId":"202305151026422776499","time":1684117602555,"authId":"120291744647139***","headerSign":"u+H1Oe3fXV9mGCES89XA7tSjp8+********************lOG7eAFfwjEWJu5JyvY5KunSeE6DiKs=","bodySign":"yWDtXOBqDoItPgHmF57L6U5G7F/*******************asPj10iUIFeaszpiRT2aQDaqLGaxvta6J5UxIUmAp+wGdV/juGEvQ="}
Accept: application/json
{
  "appId": "5765880207853***",
  "mercOrderNo": "czl00120240705***",
  "mercNo": "10132120***",
  "tradeSummary": "xx商城-手机",
  "totalAmount": 2,
  "currency": "CNY",
  "callbackUrl": "https://www.xxxxxx.com/hw/pay/callback",
  "payload": "example-payload",
  "expireTime": "2023-03-28T17:50:12.000+0800"
}
```

#### 响应参数

Response Header  

|参数|是否必选|参数类型|描述|
|:-----------|:---|:-----|:----------------------------------|
|Content-Type|是|String|取值为：application/json; charset=UTF-8|

Response Body  

|参数|是否必选|参数类型|描述|
|:----------|:---|:-----|:-----------------------------------------------------------------------------------------------------------------------------------|
|resultCode|是|String|返回码，"000000"表示成功，其他表示异常，请参见[错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-error-code-rest#公共错误码说明)。|
|resultDesc|是|String|结果描述。|
|subCode|否|String|业务错误码。|
|subDesc|否|String|业务错误描述信息。|
|sign|是|String|签名值。用于开发者对响应报文进行防篡改验证。|
|prepayId|是|String|预支付ID。有效期10分钟。|
|mercOrderNo|否|String|商户订单号，由商户自己生成，商户需保证订单信息唯一性。最大长度46。|

#### 响应示例

```
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resultCode": "000000",
  "resultDesc": "Success.",
  "sign": "MEQCIEIWzdpziRyTi8vhwWHFu********************0YAMabeCgTDG77e+2XJItvq/ZkIcCN5/B20pQ==",
  "prepayId": "12407091401520894056950***",
  "mercOrderNo": "czl00120240705***"
}
```

#### 错误码

resultCode非400000的错误码请查看[公共错误码说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-error-code-rest#公共错误码说明)。  

|返回码|错误码|错误描述|解决方案|
|:-----|:------------------------|:-----------|:-----------------------------------------------------------------------------|
|400000|UNKNOW_ERROR|服务暂不可用，请稍后重试|稍后重试。|
|400000|INVALID_ARGUMENTS|参数不合法|检查请求参数。|
|400000|INVALID_MERCNO|无效商户号|检查入参商户号是否正确。|
|400000|REJECTED_BY_RISK_CONTROL|风控拒绝|咨询华为支付团队，[在线提单](https://developer.huawei.com/consumer/cn/support/feedback/#/)。|
|400000|NO_MATCH_MATCHING_PRODUCT|未匹配到商户产品|检查商户产品是否配置正确。|
|400000|CHECK_ORDER_STATUS|订单状态异常|请检查是否使用相同订单重复下单。|
|400000|BANK_CARD_NOT_SUPPORT|银行卡不支持|更换其他银行卡重试。|
|400000|INVALID_APPID|appId不匹配|检查appId是否正确且已经绑定商户号。|