目录

Requesting Refunds

Function

Requests a refund for a transaction order. The refund rules are as follows:

  1. Concurrent refunds are not supported for the same transaction order.

    • If multiple refunds are required for an order, the interval between two refund requests must be longer than 1 minute.
    • If refunds are required for multiple sub-orders, the interval between two refund requests must be longer than 1 minute.

  2. Only orders in the last 180 days can be refunded.

  3. A successful refund request only indicates that the request has been accepted for processing. The refund is processed asynchronously. The refund is successful only when the asynchronous callback notification indicating that the refund is successful is received.

  4. To request a refund on behalf of a special merchant, the service provider can handle it through applying for API refund authorization on Huawei Pay Merchant Platform.

Scenario

After integrating the one-off payment capability of the Payment Kit and having successful transactions, you can use this API to request a refund for an order. After the refund is successful, Huawei Pay uses a callback to return the refund result to the merchant server.

Restrictions

If a refund is requested again with a different refund order, you need to associate the new refund order with the original transaction 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
mercRefundOrderNo If the refund request fails to be initiated, you are advised to rectify the fault based on the error code and try again with the same refund order. If the error code is 400000 RETRY_TOO_MANY, you need to request the refund with a new order.

1. If the error code is 400000 RETRY_TOO_MANY, you need to request the refund with a new order.

2. For multiple partial refunds, each refund needs to be requested with a new order.

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
mercOrderNo No String Merchant order number, which is generated by the merchant and must be unique. The value contains 1 to 46 characters. Either sysTransOrderNo or this parameter must be specified.
sysTransOrderNo No String Transaction order number in the Huawei Pay system. Either mercOrderNo or this parameter must be specified. If both parameters are specified, sysTransOrderNo is used.
mercRefundOrderNo Yes String

Merchant refund order number. The value must be unique. The value contains a maximum of 64 characters.

When a refund request fails or an exception occurs, ensure that the value of this parameter remains unchanged during retry to prevent repeated refund. If multiple refunds are requested under the same refund order number, only one refund is made.
reason No String Refund reason, which is displayed in the bill details. The value contains a maximum of 256 characters.
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.
refundAmount No Long

Total refund amount. Refund amount for an order, in cents. The value cannot be greater than the order amount.

Note: If promotion coupons are used in a forward transaction, the refund amount includes the coupon amount. Huawei Pay determines the refund proportions of the coupon amount and the amount paid by the buyer based on the business rules. Refund is made according to the proportion by default. If this parameter is left empty, the full amount is refunded by default.
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.

Request Example

POST /api/v1/partner/aggr/transactions/refunds HTTP/1.1
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120***","traceId":"202305151442062977847","time":1684132926969,"authId":"120291744647139***","headerSign":"BpOBa8o+gJnKG+vHVI7u********************mVuKDV8iPqNJ+Y8b4XDpSi3FHgjozsWH+uLoTSIg=","bodySign":"lHjrX3dv44zyfu+PO1G+oa9tJi2********************EatA8QTjLPsSPKfM="}
Accept: application/json
{
  "mercOrderNo": "czl00120240705***",
  "mercRefundOrderNo": "czl0012024070914***",
  "reason": "123456",
  "callbackUrl": "https://www.xxxxxx.com/hw/pay/callback",
  "refundAmount": 2,
  "payload": "example-payload"
}

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. The value 000000 indicates success, and other values indicate failure.
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.
mercRefundOrderNo Yes String Merchant refund order number. The value contains a maximum of 64 characters.
sysRefundOrderNo Yes String Refund order number in the Huawei Pay system.
sysTransOrderNo Yes String Transaction order number in the Huawei Pay system.
mercOrderNo Yes String Merchant order number, which is generated by the merchant and must be unique. The value contains 1 to 46 characters.
refundAmount Yes Long

Total refund amount. Refund amount for an order, in cents. The value cannot be greater than the order amount.

Note: If promotion coupons are used in a forward transaction, the refund amount includes the coupon amount. Huawei Pay determines the refund proportions of the coupon amount and the amount paid by the buyer based on the business rules. Refund is made according to the proportion by default. If this parameter is not specified, the value of payerRefundAmount is used by default.
payerRefundAmount No Long Amount refunded to the payer, in cents.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resultCode": "000000",
  "resultDesc": "Success.",
  "sign": "MEUCIEhVD6FuZ5iIh41A********************diWp/WVE8SoZOSXWMI0JGRXrj0=",
  "mercRefundOrderNo": "czl0012024070914***",
  "sysRefundOrderNo": "12407030900270084914518***",
  "sysTransOrderNo": "12407030857530004914518***",
  "mercOrderNo": "czl00120240705***",
  "refundAmount": 2,
  "payerRefundAmount": 2
}

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 CHECK_ACCOUNT_STATUS Payment account error. Check the payment account status.
400000 CHECK_MERC_STATUS Merchant status error. Check whether the merchant status is normal.
400000 MERC_NOT_SUPPORT_REFUND The merchant does not support refund. Check whether the merchant has the refund permission.
400000 CHECK_AMOUNT_INVALID Amount verification failed. Check whether the transferred amount is valid.
400000 CHECK_ACCOUNT_BALANCE Insufficient account balance. Check the merchant account balance.
400000 RETRY_TOO_MANY Too many retries. Submit another request with a different order. Submit another request using a new order number.
400000 ORDER_CONCURRENT_ERROR Concurrent refund error for an order.

1. If multiple refunds are required for an order, the interval between two refund requests must be longer than 1 minute.

2. If refunds are required for multiple sub-orders, the interval between two refund requests must be longer than 1 minute.
400000 OPERATION_NOT_AUTHORIZED Unauthorized operation. Check whether you have completed the API refund authorization request.
400000 CUST_NOT_EXIST The user does not exist or has been deregistered. Check the user to be refunded.
400000 NOT_IN_VALIDITY_PERIOD Not within the validity period. Check whether the refund order has expired.
400000 NOT_SUPPORTED_OPERATION Unsupported operation. Check whether the operation is allowed. If it cannot be confirmed, submit a ticket online.
400000 RESTRICTED_USER_ACCOUNT Restricted user account. Check whether the user account status is normal.
400000 RESTRICTED_USER_TRANSACTION Restricted user transactions. Check whether the user status is normal.
400000 RESTRICTED_MERCHANT_TRANSACTION Restricted merchant transactions. Check whether the merchant payment account status is normal.