Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

refund

Use the refund API to initiate a synchronous or asynchronous refund for a successful payment. 

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see： 


Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

  • If the data type of a field is Integer and its value is 20, set it as "20". 
  • If the data type of a field is Boolean and its value is true, set it as "true". 

Request parameters

refundRequestId StringRequired

The unique ID assigned by the merchant to identify a refund request.

More information about this field:

  • This field is an API idempotency field. Merchant uses the refundRequestId field for idempotency control. For payment requests that are initiated with the same value of refundRequestId and reach a final status (S or F), the same result is to be returned for the request.
  • Maximum length: 64 characters
paymentId StringRequired

The unique ID assigned by Alipay for the original payment to be refunded.

More information about this field:

  • Maximum length: 64 characters
referenceRefundId StringOptional

The unique ID to identify a refund, which is assigned by the merchant that directly provides services or goods to the customer.

More information about this field:

  • Maximum length: 64 characters
refundAmount AmountRequired

The refund amount that is initiated by the merchant.

currency StringRequired

The 3-letter currency code that follows the ISO 4217 standard.

More information about this field:

  • Maximum length: 3 characters
value IntegerRequired

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.

More information about this field:

  • Value range: 0 - unlimited
refundReason StringOptional

The refund reasons

More information about this field:

  • Maximum length: 256 characters

Response parameters

result ResultRequired

The request result contains information such as status and error codes.

resultCode StringRequired

Result code

More information about this field:

  • Maximum length: 64 characters
resultStatus StringRequired

Result status. Valid values are:

  • S: Indicates that the result status is successful. 
  • F: Indicates that the result status failed.
  • U: Indicates that the result status is unknown.
resultMessage StringOptional

Result message

More information about this field:

  • Maximum length: 256 characters
refundRequestId StringOptional

The unique ID that is assigned by the merchant to identify a refund request.

More information about this field:

  • Maximum length: 64 characters
refundId StringOptional

The unique ID that is assigned by Alipay to identify a refund. A one-to-one correspondence between refundId and refundRequestId exists. 

More information about this field:

  • Maximum length: 64 characters
paymentId StringOptional

The unique ID assigned by Alipay for the original payment to be refunded.

More information about this field:

  • Maximum length: 64 characters
refundAmount AmountOptional

The refund amount collected by the payment executor for this refund.

currency StringRequired

The 3-letter currency code that follows the ISO 4217 standard.

More information about this field:

  • Maximum length: 3 characters
value IntegerRequired

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.

More information about this field:

  • Value range: 0 - unlimited
refundTime DatetimeOptional

The date and time when the refund reaches a final state of success or failure.

More information about this field:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
grossSettlementAmount AmountOptional

The total settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote.

Note: This field is empty when the settlement currency is the same as the transaction currency.

currency StringRequired

The 3-letter currency code that follows the ISO 4217 standard.

More information about this field:

  • Maximum length: 3 characters
value IntegerRequired

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.

More information about this field:

  • Value range: 0 - unlimited
settlementQuote QuoteOptional

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.

quoteId StringOptional

The unique ID to identify an exchange rate.

More information about this field:

  • Maximum length: 64 characters
quoteCurrencyPair StringRequired

Pair of currency exchange rate

More information about this field:

  • Maximum length: 16 characters
quotePrice DecimalRequired

The exchange rate used when a currency conversion occurs.

More information about this field:

  • Value range: 0 - unlimited
quoteStartTime DatetimeOptional

Effective time of the exchange rate. 

More information about this field:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
quoteExpiryTime DatetimeOptional

Expiration time of the exchange rate. 

More information about this field:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
guaranteed Boolean Optional

Guaranteed exchange rate available for payment

More information 

This section gives additional information about the key parameter. See the following list for details:

  • refundRequestId:
    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.

Error codes

Error codes are usually classified into the following categories:

  • Common error codes: common for all online and in-store payment APIs.
  • API-specific error codes: listed in the following table.  

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The refund is successful, no further action is needed.

REFUND_WINDOW_EXCEEDFThe refund date exceeds the refundable period that is agreed in the contract.

Confirm whether the refund date exceeds the refundable period.

REFUND_AMOUNT_EXCEEDFThe total refund amount exceeds the payment amount.

Confirm whether the total refund amount exceeds the payment amount.

ORDER_NOT_EXISTFThe order does not exist.

Check whether paymentId is correct.

ORDER_STATUS_INVALIDFThe order status is invalid.

Check the order status.

MERCHANT_BALANCE_NOT_ENOUGHFThe merchant balance is not enough.

Call the interface again after the merchant has sufficient balance. The refundRequestId field needs to be changed when you try again.

CURRENCY_NOT_SUPPORT FThe currency is not supported.

Use the currency that is agreed in the contract.

REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.

Use a unique refundRequestId to initiate the payment again.

CLIENT_INVALIDFThe client is invalid.

Check whether the clientId is correct.

METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

Check whether the HTTP method is correct.

MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

Check whether the media type is correct.

MULTIPLE_REFUNDS_NOT_SUPPORTEDFMultiple refunds are not supported.

Check whether multiple refunds exist.

Request/Response Code

Request

Method

POST

Endpoint

/v1/payments/refund

Header

Accept: application/json

URL

Domain name

Request Body
Request parameters
Response Body
Body content