refund
Use the refund API 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.
The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).
Notes: For more information about the smallest currency unit, see Currency codes for details.
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 amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).
Notes: For more information about the smallest currency unit, see Currency codes for details.
The date and time when the refund reaches a final state of success or failure, which follows the ISO 8601 standard.
Total settlement amount, which equals to transaction amount multiplied by the value of settlementQuote.
Note: This field is empty when the settlement currency is the same as the transaction currency.
The 3-letter currency code that follows the ISO 4217 standard.
The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).
Notes: For more information about the smallest currency unit, see Currency codes for details.
The exchange rate between the settlement currency and transaction currency at the time of transaction, which is provided only in the locked-in rate case.
Note: This field is empty when the settlement currency is the same as the transaction currency.
Effective time of the exchange rate, which follows the ISO 8601 standard
Expiration time of the exchange rate, 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.
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 inquiryPayment 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= FREFUND_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 does not 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. Do not 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