目录

Refund Result Callback Notification

Function

Sends key refund event notifications to your server from the Payment Kit server upon successful completion of a user refund.

  1. To ensure the reliability of callback requests, the system implements a retry mechanism. Therefore, the same notification may be resent.

  2. To ensure information validity, you need to perform SM2-based signature verification on the returned payment information. Pay attention to the following during signature verification:

    • Use the complete content of the notification for signature verification.
    • Before signature verification, sort and combine the returned data. The sign field indicates the signature value. The content to be verified must exclude the sign field.
    • Use Huawei Pay certificate as the public key for signature verification.

  3. The refund status is determined by the refundOrderStatus field.

Scenario

After a refund is successful, the Payment Kit server calls the callback API (specified by callbackUrl) passed by your app or atomic service in the refund request API to send the refund order details to you.

Prototype

Request Parameters

Request Body

Parameter Mandatory Type Description
callbackId Yes String Unique ID of a callback notification.
callbackTime Yes String Time when a callback notification is sent. The format is yyyy-MM-dd HH:mm:ss.
dataType Yes String

Data encryption type.

- encrypt: encryption

- plain: plaintext
sign Yes String

Signature of the callback notification result. All fields except the sign field are involved in signing.

You can perform signature verification on the callback packet by referring to Signature Verification Rules.
signType Yes String Signature type. Algorithm used to generate the signature string. Currently, the SM2 algorithm is used.
certNo No String Certificate number used for signing.
mercRefundNo Yes String Merchant refund order number.
sysRefundNo Yes String Refund order number in the Huawei Pay system.
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 left empty, the full amount is refunded by default.
payerRefundAmount Yes Long Amount refunded to the payer, in cents.
promotionRefundAmount Yes Long Marketing refund amount, in cents.
currency Yes String

Transaction currency. The value can contain a maximum of 3 characters.

The default value is CNY. Currently, only this currency is supported.
mercNo No String Merchant number.
finishTime No String Refund completion time, in UTC format (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
refundOrderStatus Yes String

Refund status.

- REFUND_CHL_PROC: processing

- REFUND_SUCCESS: successful

- REFUND_FAILED: failed
payload No String Reserved information. If this parameter is passed in a merchant request, it will be returned as-is.

Request Example

POST /hw/pay/callback HTTP/1.1
Content-Type: application/json;charset=UTF-8
{
  "callbackId": "124070308575300049145189***",
  "callbackTime": "2023-03-29 09:52:37",
  "currency": "CNY",
  "dataType": "plain",
  "finishTime": "2023-02-23T10:05:17.000+0800",
  "mercNo": "10132120***",
  "mercRefundNo": "czl00120240705***",
  "payerRefundAmount": 100,
  "payload": "example-payload",
  "promotionRefundAmount": 10,
  "refundAmount": 100,
  "refundOrderStatus": "REFUND_SUCCESS",
  "sign": "MEYCIQD8RlHJ9tGmc2*******************GYpU7nDIJCYHcZpBY1ffr21wgjQ2l",
  "signType": "SM2",
  "certNo": "120291744647139***",
  "sysRefundNo": "1230223100511858780002***"
}

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. Huawei Pay parses the response of the application/json type. The value 000000 indicates success, and other values indicate failure. If the return value format is invalid or the return value is not 000000, the callback fails.
resultDesc Yes String Result description.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resultCode": "000000",
  "resultDesc": "Success."
}