目录

Applying for PIN-Free Withholding

Function

Performs PIN-free payment.

Scenario

After signing a contract with Payment Kit, you can call this API to directly perform PIN-free payment.

Restrictions

If the order is replaced and retried, it is considered as a new service order. You need to associate the new service order with the original service order. The API re-entry rules are described as follows (for reference).

Re-entry Determination Field Original Order Re-entry Scenario Recommended Order Replacement and Retry Scenario

Merchant order number

(mercOrderNo)

1. The withholding request API fails. After the fault is rectified based on the error code, the original merchant order number can be retried.

2. The withholding request API is successful. The original merchant order number is re-entered, and the API returns an idempotent response. The order status is subject to the asynchronous result notification or synchronous query API.

 If the withholding request is successful and the withholding status in the withholding order query or callback notification is TRX_FAILED, the order enters the final failure state. If the fee needs to be deducted again, you need to replace the order for retry.

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 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.
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.
contractId Yes String ID of the withholding contract. The value is returned in the callback API after the contract is signed. The value contains a maximum of 64 characters.
payer No PayerIn Payer information.

Request Example

POST /api/v1/aggr/transactions/withhold HTTP/1.1
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120***","traceId":"202305151026422776499","time":1684117602555,"authId":"120291744647139***","headerSign":"u+H1Oe3fXV9mGCES89XA7tSjp8+TELYgG*******************4WvEpfjLzpzKE2/+KYaq1jDH/+VmefC29ZXpK54c5DwKJH7rMv6SBj/z0UcN9Qr*******************AFfwjEWJu5JyvY5KunSeE6DiKs=","bodySign":"yWDtXOBqDoItPgHmF57L6U5G7F/L*******************Du6E6KxPAHE0TIkTxHMcUWx7N6405QrcBimTcTN7pBpFA7pvFe*******************vta6J5UxIUmAp+wGdV/juGEvQ="}
Accept: application/json
{
  "appId": "5765880207853***",
  "contractId": "2024070914615843071097***",
  "mercNo": "10132120***",
  "mercOrderNo": "czl00120240705***",
  "allocationType": "DELAY_ORDER_ALLOCATION",
  "callbackUrl": "https://www.xxxxxx.com/hw/pay/callback",
  "currency": "CNY",
  "totalAmount": 2,
  "tradeSummary": "xx service - magazines and newspapers"
}

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.
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.
sysTransOrderNo Yes String Transaction order number in the Huawei Pay system.

Response Example

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

Result Codes

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

Return Code Result Code Description Solution
400000 CUST_NOT_EXIST The user does not exist or has been deregistered. Replace the signing number and try again.
400000 INVALID_ARGUMENTS Invalid parameter. Check whether the parameter is correct.
400000 INVALID_MERC_NO Invalid merchant number. Use a valid merchant number.
400000 UNKNOW_ERROR Service temporarily unavailable. Try again later. Try again later.
400000 CHECK_TRANSACTION_ORDER_STATUS Transaction order status error. Check whether the order is correct or replace the order for retry.
400000 CHECK_MERC_STATUS Merchant status error. Check whether the merchant status is normal.
400000 MERC_NOT_SUPPORT_ALLOCATION The merchant does not support allocation. Change the value of the allocationType input parameter.
400000 CHECK_ACCOUNT_STATUS User status error. Check whether the user status is normal.
400000 INVALID_PAYMENT_TYPE The user does not have a valid payment method. Check the payment method of the user.
400000 WITHHOLD_OVER_TIMES The number of withholding times exceeds the threshold. Try again four hours later.
400000 INVALID_APPID The app ID does not match. Check whether the app ID is correct and has been bound to a merchant number.