Refund

2020-10-16 10:11

URL: /v1/payments/refund

Use this interface to initiate a synchronous or asynchronous refund for a successful payment.

#Sample

The following example shows the use of Refund interface to refund, which consists of the following steps:

1. Merchant submits a refund request to Alipay.

copy
{
 "paymentId":"201811291907410100070000001111",
 "refundRequestId":"201811291907410200070000001111",
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 }
}

2. Alipay returns the refund result to merchant.

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 },
 "refundTime": "2020-10-10T12:01:01+08:30",
 "paymentId":"201811291907410100070000001111",
 "refundRequestId":"201811291907410200070000001111",
 "refundId":"401811291907410200070000001111"
}

#Structure

#Request parameters

No.	Field	Description
1	refundRequestId	MANDATORY String (64) The unique ID assigned by the merchant to identify a refund request.
2	paymentId	MANDATORY String (64) The unique ID assigned by Alipay for the original payment to be refunded
3	referenceRefundId	OPTIONAL String (64) The unique ID to identify a refund, which is assigned by the merchant that directly provides services or goods to the customer
4	refundAmount	MANDATORY Amount The refund amount that is initiated by the merchant.
5	refundReason	OPTIONAL String (256) The refund reasons
6	isAsyncRefund	OPTIONAL Boolean If the value of this parameter is true, the refund is processed asynchronously. Otherwise, the refund is processed synchronously.

#Response parameters

No.	Field	Description
1	result	MANDATORY Result The request result, which contains information related to the request result, such as status and error codes.
2	refundRequestId	OPTIONAL String (64) The unique ID that is assigned by the merchant to identify a refund request
3	refundId	OPTIONAL String (64) The unique ID that is assigned by Alipay to identify a refund. A one-to-one correspondence between refundId and refundRequestId exists.
4	paymentId	OPTIONAL String (64) The unique ID assigned by Alipay for the original payment to be refunded
5	refundAmount	OPTIONAL Amount The refund amount collected by the payment executor for this refund.
6	refundTime	OPTIONAL Datetime The date and time when the refund reaches a final state of success or failure, which follows the ISO 8601 standard.
7	grossSettlementAmount	OPTIONAL Amount 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.
8	settlementQuote	OPTIONAL Quote 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.

#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

#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 code

This section helps you identify and resolve problems. See the following table for details:

No.	resultCode	resultStatus	resultMessage
1	SUCCESS	S	Success
2	REFUND_WINDOW_EXCEED	F	The refund date exceeds the refundable period that is agreed in the contract.
3	REFUND_AMOUNT_EXCEED	F	The total refund amount exceeds the payment amount.
4	ORDER_NOT_EXIST	F	The order doesn't exist.
5	ORDER_STATUS_INVALID	F	The order status is invalid.
6	MERCHANT_BALANCE_NOT_ENOUGH	F	The merchant balance is not enough.
7	CURRENCY_NOT_SUPPORT	F	The currency is not supported.
8	PROCESS_FAIL	F	A general business failure occurred. Don't retry.
9	PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
10	REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.
11	KEY_NOT_FOUND	F	The key is not found.
12	ACCESS_DENIED	F	Access denied
13	REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.
14	API_INVALID	F	API is invalid or not active.
15	CLIENT_INVALID	F	The client is invalid.
16	SIGNATURE_INVALID	F	The signature is invalid.
17	METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.
18	MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.
19	UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.