Refund

2023-05-08 06:42

After a payment is completed, you can issue a refund via 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.
Minimum refundable amount: The minimum refundable amount 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 to issue a refund

You can use the refund API to achieve a seamless refund process.

Step 1: Call the refund API

The following requirements about 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 needs to 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. The refund is allowed only when the value of the paymentStatus parameter is `SUCCESS`.	ORDER_STATUS_INVALID
Refund period	The refund is allowed only when the refund is issued within the refund window of the corresponding payment method.	REFUND_WINDOW_EXCEED
To-be-settled balance of the merchant's account	Alipay deducts funds from the to-be-settled balance of the merchant's account for a refund. The refund fails if the balance is insufficient. If the contract specifies that the commission fee is not returned, the full refund of the first payment fails. Therefore, it is recommended that you keep a sufficient balance in your account before you test in a production environment.	MERCHANT_BALANCE_NOT_ENOUGH

Table 1. Requirements about a refund request

Step 2: Obtain the refund result

Regardless of the payment method used for a payment, you can use either of the following two ways to obtain the refund result:

Call the inquiryRefund API to inquire about the refund status.
View the refund result through an asynchronous notification sent by Alipay.

For Alipay+ payment methods used for a payment, you can obtain the refund result through the response returned by using the refund API.

Alipay+ payment methods

After you call the refund API, Alipay synchronously returns the refund result:

If the value of result.resultStatus in the response is S, the refund is successful.
If the response is not received due to network issues or the value of result.resultStatus is U, you can resend the API request with the same value of refundRequestId. refundRequestId is the unique identifier of a refund, so resending the request by using the same value of the parameter doesn't trigger multiple refunds.
If the value of result.resultStatus is F, the refund failed. See Error codes of the refund API for troubleshooting.

Other payment methods

After you call the refund API, Alipay returns the error code REFUND_IN_PROCESS, and the refund status changes to PROCESSING. After the payment method provider processes the refund, the refund status changes to SUCCESS or FAIL. Then, Alipay sends an asynchronous notification to you through the notifyRefund notification.

Note: For card, online banking, bank transfer, and mobile banking app payment methods, after you call the refund API, the value REFUND_IN_PROCESS of result.resultCode and the value U of result.resultStatus indicate that the request is being processed. However, the refund result is not to be returned synchronously. You must integrate the inquiryRefund API and the notifyRefund notification to obtain the refund result.

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 shows the possible values of the refundStatus parameter:

refundStatus	Description
SUCCESS	The refund is successful.
PROCESSING	The refund is being processed (which also occurs when the error code is `MERCHANT_BALANCE_NOT_ENOUGH`).
FAIL	The refund fails.

Table 2. Explanation of refundStatus

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, follow Notification to proceed with the refund process.

The refundStatus parameter in the notification indicates the refund status. The value of SUCCESS indicates a successful refund and the value of FAIL indicates a failed refund.

(Optional) Step 3: 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

Alipay Merchant Portal provides an easy way for you to issue a refund.

Step 1: Issue a refund

Log in to Alipay Merchant Portal.
Go to the Transaction Statement page by clicking Transaction Statement in the navigation bar.
On the Transaction Statement page, find the transaction to have a refund issued, and click Details under the operations column to go to the Transaction Statement Detail page.
On the Transaction Statement Detail page, click the Refund button to issue a refund after you confirm the refund information.

Note: Click Change password to set your payment password the first time you issue a refund on the portal.

Figure 1. Issue a refund

Step 2: Obtain the refund result

On the Transaction Statement page, find the target refund whose Transaction Type is displayed as REFUND. The refund is successful if its Status is displayed as SUCCESS.

Note: You can only view the successful refunds on the portal. Failed and processing refunds are not shown on the portal.

Figure 2. Obtain the refund result

(Optional) Step 3: Inquire about the refund records

On the Transaction Statement page, find the target transaction whose Transaction Type is displayed as PAYMENT, and click Details to go to the Transaction Statement Detail page.
On the Transaction Statement Detail page, the Related Transaction section shows the refund records of the transaction.

Figure 3. inquire about the refund records