We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
API versionAll
DeviceAll
Atomic service APIsNot filter by this
ReferencesApplication ServicesPayment KitREST APIDirect MerchantBasic PaymentRefund Result Callback Notification

Refund Result Callback Notification

Last updated: 2026-09-08 08:15
Content overview
Expand

Function

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

NOTE

  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

  • Protocol: HTTPS POST

  • Direction: Payment Kit server -> Your server

  • URL: Callback URL passed in the refund request API.

  • Data format:

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

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

Request Parameters

Request Body

Expand
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

Collapse
Word wrap
Dark theme
Copy code
  1. POST /hw/pay/callback HTTP/1.1
  2. Content-Type: application/json;charset=UTF-8
  3. {
  4.   "callbackId": "124070308575300049145189***",
  5.   "callbackTime": "2023-03-29 09:52:37",
  6.   "currency": "CNY",
  7.   "dataType": "plain",
  8.   "finishTime": "2023-02-23T10:05:17.000+0800",
  9.   "mercNo": "10132120***",
  10.   "mercRefundNo": "czl00120240705***",
  11.   "payerRefundAmount": 100,
  12.   "payload": "example-payload",
  13.   "promotionRefundAmount": 10,
  14.   "refundAmount": 100,
  15.   "refundOrderStatus": "REFUND_SUCCESS",
  16.   "sign": "MEYCIQD8RlHJ9tGmc2*******************GYpU7nDIJCYHcZpBY1ffr21wgjQ2l",
  17.   "signType": "SM2",
  18.   "certNo": "120291744647139***",
  19.   "sysRefundNo": "1230223100511858780002***"
  20. }

Response Parameters

Response Header

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

Response Body

Expand
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

Collapse
Word wrap
Dark theme
Copy code
  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4.   "resultCode": "000000",
  5.   "resultDesc": "Success."
  6. }
Applying for Refunds
Refund Query
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice