目录

Pre-order

Function

Obtains a prepayment ID (prepayId).

Scenario

When integrating the payment and contract signing function of Payment Kit, you need to call this API to obtain the prepayment ID (prepayId) and use it to construct the orderStr parameter. Then, this parameter is returned to the client to call the payment API and initiate the Huawei Pay checkout service.

Prototype

Request Parameters

Request Header

Parameter Mandatory Type Description
Content-Type Yes String The value is application/json; charset=UTF-8.
PayMercAuth Yes String The value is a JSON string of PayMercAuth.

Request Body

Parameter Mandatory Type Description
appId Yes String App ID.
mercOrderNo Yes String Merchant order number, which is generated by the merchant and must be unique. The value contains 1 to 46 characters.
mercNo Yes String Merchant number. The value contains a maximum of 12 characters.
tradeSummary Yes String Transaction summary. Recommended format: Merchant app name-Product description. The value contains a maximum of 128 characters.
totalAmount Yes Long Total order amount, in cents. The value must be an integer greater than 0.
currency No String

Transaction currency. The value contains a maximum of 3 characters.

The default value is CNY. Currently, only this currency is supported.
goodsDetail No List<GoodDetail> Order details.
allocationType No String

Allocation type.

- NO_ALLOCATION: no allocation (default)

- DELAY_ORDER_ALLOCATION: delayed allocation

Note: To use this field, contact your merchant contact person to apply for the allocation capability.
callbackUrl Yes String Callback notification URL. It must be an HTTPS URL that can be directly accessed from the external network. For details, see Notification Callback API Description. The value contains a maximum of 512 characters.
payload No String Information reserved by the merchant, which will be returned as-is in the query response and callback notification. The value contains a maximum of 255 characters.
expireTime No String

Time when a transaction expires. The time must be an accurate UTC time.

Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ

NOTE

- If this parameter is not specified, the default value is 2 hours from the current time. If this parameter is specified, the expiration time cannot be later than 180 days from the current time. Otherwise, the system reports an error.

- If the passed time is earlier than the current time, the order may be closed abnormally due to expiration or timeout.

- You can obtain the corresponding UTC expiration time by referring to Example of Obtaining the UTC Expiration Time.
contractInfo Yes ContractInfo Contract information.
payer No PayerIn Payer information.

Request Example

POST /api/v1/aggr/pay-and-sign/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 Mall-Mobile Phone",
  "totalAmount": 2,
  "currency": "CNY",
  "callbackUrl": "https://www.xxxxxx.com/hw/pay/callback",
  "payload": "example-payload",
  "expireTime": "2023-03-28T17:50:12.000+0800",
  "contractInfo": {
     "planId": "1***",
     "mercContractCode": "2024020316555432***",
     "callbackUrl": "https://www.xxxxxx.com/hw/sign/callback"
   }
}

Response Parameters

Response Header

Parameter Mandatory Type Description
Content-Type Yes String The value is application/json; charset=UTF-8.

Response Body

Parameter Mandatory Type Description
resultCode Yes String Result code. 000000 indicates success, and other values indicate exceptions. For details, see Common Result Codes.
resultDesc Yes String Result description.
subCode No String Service result code.
subDesc No String Service result description.
sign Yes String Signature, which is used to perform anti-tamper verification on response packets.
prepayId Yes String Prepayment ID. The number is valid for 10 minutes.
mercOrderNo No String Merchant order number, which is generated by the merchant and must be unique. The value contains 1 to 46 characters.

Response Example

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

Result Code

For error codes of resultCode other than 400000, see Common Result Codes.

Return Code Result Code Description Solution
400000 UNKNOW_ERROR Service temporarily unavailable. Try again later. Try again later.
400000 INVALID_ARGUMENTS Invalid parameter. Check the request parameters.
400000 INVALID_MERCNO Invalid merchant number. Check whether the input merchant number is correct.
400000 REJECTED_BY_RISK_CONTROL Rejected by the risk control system. Consult the Huawei Pay team or submit a ticket online.
400000 NO_MATCH_MATCHING_PRODUCT No matching merchant product. Check whether the merchant product is correctly configured.
400000 CHECK_ORDER_STATUS Order status error. Check whether this is a duplicate order submission.
400000 BANK_CARD_NOT_SUPPORT Bank card not supported. Use another bank card and try again.
400000 INVALID_APPID The app ID is not matched. Check whether the app ID is correct and has been bound to a merchant number.