Refund

2023-06-01 03:03

After a payment is completed, you can issue a refund by using the refund API or Alipay Global Merchant Portal if your buyer demands a refund.

Before issuing a refund, you must be familiar with the following information:

Commission fee: Whether the commission fee is returned is subject to the contract.
Refund exchange rate: For cross-currency settlement which applies when the transaction currency differs from the settlement currency, the Alipay exchange rate on the day after the refund is issued is applied.
Partial refund: Whether a partial refund is allowed depends on the payment method that the buyer used for a payment. For details, see Refund capabilities of payment methods.
Refund period: The refund period depends on the payment method that the buyer used for a payment. For details, see Refund capabilities of payment methods.

Use the refund API

Issue a refund

The following requirements for a refund request must be satisfied when you use the refund API. Otherwise, the corresponding error codes are to be returned by Alipay:

Item	Requirement	Error code
Refund currency	The value of the parameter refundAmount.currency in the refund request needs to be consistent with the value of the parameter paymentAmount.currency used for initiating a payment.	CURRENCY_NOT_SUPPORT
Refund amount	The value of the parameter refundAmount.value in the refund request must be no less than the minimum refund amount (which is usually the same as the minimum payment amount) and no greater than the refundable amount of a payment.	REFUND_AMOUNT_EXCEED
Payment status	For card payment methods: Only captured payments can be refunded. For a payment where a chargeback occurs and the liability is not judged, a refund is not allowed. For other payment methods, the refund is allowed only when the value of the paymentStatus parameter of the original payment is `SUCCESS`.	ORDER_STATUS_INVALID
Refund period	The refund is allowed only when the refund is issued within the refund period of the corresponding payment method.	REFUND_WINDOW_EXCEED

Table 1. Requirements for a refund request

The key parameters contained in refund requests are listed as follows (For details, see the refund API):

Parameter	Description
refundRequestId	The unique identifier that you assign to a payment.
paymentId	The unique identifier that Alipay assigns to the original payment to be refunded.
refundAmount	The refund amount must be no less than the minimum refund amount (which is usually the same as the minimum payment amount) and no greater than the refundable amount of a payment.
refundNotifyUrl	The URL for receiving asynchronous refund notifications.

Table 2. Key parameters of refund requests

Obtain the refund result

After you initiate a refund request, you can use either of the following three ways to obtain the refund result:

Obtain the refund result by checking the response returned through the refund API.
Call the inquiryRefund API to inquire about the refund status.
View the refund result through asynchronous notifications sent by Alipay.

Check the refund status through the refund API

After you call the refund API, Alipay synchronously returns the refund result. The resultStatus parameter in the API response indicates the refund status of this payment. The values of resultStatus are explained as follows:

resultStatus	Explanation
S	The refund is successful.
U	The refund is being processed. When the value of resultCode is `REFUND_IN_PROCESS`, you can obtain the final refund result through the inquiryRefund API or the notifyRefund notification.
F	The refund failed. See error codes of the refund API for troubleshooting.

Table 3. Values of resultStatus

Inquire about the refund status

Regardless of the payment method used for a payment, you can call the inquiryRefund API to inquire about the refund status. The refund status is indicated by the refundStatus parameter in the response. The following table explains the possible values of the refundStatus parameter:

refundStatus	Explanation
SUCCESS	The refund is successful.
PROCESSING	The refund is being processed.
FAIL	The refund failed.

Table 4. Values of refundStatus in the inquiryRefund API

Receive an asynchronous notification of the refund status

Before you can receive an asynchronous notification of the refund status, you must set a notification address. You can configure the address in Alipay Developer Center or by specifying the refundNotifyUrl parameter in the refund API. After you receive the notification, check the refund status through the refundStatus parameter in the notification. The values of refundStatus are explained as follows:

refundStatus	Explanation
SUCCESS	The refund is successful.
FAIL	The refund failed.

Table 5. Values of refundStatus in the notifyRefund API

Inquire about the refund records

You can view the refund records of a transaction by using the inquiryRefund API. If a transaction has been refunded, the parameter transactions shows the refund records of the transaction.

Issue a refund on Alipay Merchant Portal

You can issue a refund on Alipay Merchant Portal. For more information about how to issue a refund and view the refund result, see Issue a refund on Alipay Merchant Portal.