Pre-ordering

Function

Obtains a prepayment ID (prepayId).

Scenario

When integrating the one-time payment 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

Protocol: HTTPS POST
Direction: Your server -> Payment Kit server
URL: https://petalpay-developer.cloud.huawei.com.cn/api/v2/aggr/preorder/create/app

Note: Use https://petalpay-developer.cloud.huawei.com.cn/api/v2/aggr/preorder/create/fa as the pre-order API of the atomic service.
Data format:

Request: Content-Type: application/json; charset=UTF-8

Response: Content-Type: application/json; charset=UTF-8

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 a maximum of 46 characters.
mercNo	Yes	String	Merchant number. The value contains a maximum of 12 characters.
tradeSummary	Yes	String	Trade 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>	List of goods 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.
payer	No	PayerIn	Payer information.
selectPromotions	No	SelectPromotions	Platform coupon information.

Request Example

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 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"
}

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 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 ID is valid for 10 minutes.
mercOrderNo	No	String	Merchant order number, which is generated by the merchant and must be unique. The value contains a maximum of 46 characters.

Response Example

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***"
}

Result Codes

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 does not match.	Check whether the app ID is correct and has been bound to a merchant number.

目录