Refund
Use this interface to initiate a synchronous or asynchronous refund for a successful payment.
Request parameters
The refund amount that is initiated by the merchant.
The 3-letter currency code that follows the ISO 4217 standard.
Response parameters
The request result, which contains information related to the request result, such as status and error codes.
Result status. Possible values are:
- S: Indicates that the result status is successful.
- F:Indicates that the result status is failed.
- U: Indicates that the result status is unknown.
The refund amount collected by the payment executor for this refund.
The 3-letter currency code that follows the ISO 4217 standard.
The date and time when the refund reaches a final state of success or failure, which follows the ISO 8601 standard.
More information
This section gives additional information about certain parameters. See the following list for details:
- refundRequestId:
- Alipay uses the refundRequestId parameter for idempotency control. For example, if the refund request with the refundRequestId of 201811291907410200070000001111 has been successfully processed by Alipay, when the merchant uses the same refundRequestId to refund, Alipay returns a result of refund success.
- The refund can be full or partial. A transaction can have multiple refunds as long as the total refund amount is less than or equal to the original transaction amount. If being out of the refund window, the refund request will be declined. Use the same refundRequestId to retry a refund in case of timeout or when the returned resultStatus is U.
- refundId
The parameter can be used for the refund inquiry.
Responses for different cases
This section provides responses for different cases of failed refunds.
1. The refund currency is inconsistent with the transaction currency.
The refund currency needs to be consistent with the transaction currency, otherwise an error is returned. The following example is a sample code of this case.
2. The refund currency exceeds the refund limit.
For example, the refund amount exceeds the transaction amount or is less than the minimum refund amount. The following example is a sample code of this case.
3. The refundRequestId
is repeated.
The refundRequestId is same with the previous request. The following example is a sample code of this case.
4. The transaction status is invalid.
If initiates a refund in non-SUCCESS status, an error is reported. The following example is a sample code of this case.
Result process logic
For different request results, different actions are to be performed. See the following list for details:
- If the value of result.resultStatus is S, for synchronous refund, the refund succeeds. For an asynchronous refund the refund request is processed successfully, and merchant can call Refund Result Inquiry interface to query the refund result.
- If the value of result.resultStatus is F, the refund fails. Usually, the failure is caused by a refund initiated outside the refund window (result. resultCode= REFUND_WINDOW_EXCEED). If the refund is still needed to be processed, manual intervention is needed.
- If the value of result.resultStatus is U, the result is unknown. Processing failure might occur due to system or network issues. Merchant can retry with the same refundRequestId.
Result/Error codes
Code | Value | Message |
---|---|---|
SUCCESS | S | Success |
REFUND_WINDOW_EXCEED | F | The refund date exceeds the refundable period that is agreed in the contract. |
REFUND_AMOUNT_EXCEED | F | The total refund amount exceeds the payment amount. |
ORDER_NOT_EXIST | F | The order doesn't exist. |
ORDER_STATUS_INVALID | F | The order status is invalid. |
MERCHANT_BALANCE_NOT_ENOUGH | F | The merchant balance is not enough. |
CURRENCY_NOT_SUPPORT | F | The currency is not supported. |
PROCESS_FAIL | F | A general business failure occurred. Don't retry. |
PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. |
REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. |
KEY_NOT_FOUND | F | The key is not found. |
ACCESS_DENIED | F | Access denied |
REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
API_INVALID | F | API is invalid or not active. |
CLIENT_INVALID | F | The client is invalid. |
SIGNATURE_INVALID | F | The signature is invalid. |
METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. |
MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
UNKNOWN_EXCEPTION | U | An API calling is failed, which is caused by unknown reasons. |
Request
Method
POST
Endpoint
v1/payments/refund
Header
Accept: application/json