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

      refund

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

      Request parameters

      refundRequestIdString(64)Required
      The unique ID assigned by the merchant to identify a refund request.
      paymentIdString(64)Required
      The unique ID assigned by Alipay for the original payment to be refunded
      referenceRefundIdString(64)Optional
      The unique ID to identify a refund, which is assigned by the merchant that directly provides services or goods to the customer
      refundAmountAmountRequired

      The refund amount that is initiated by the merchant.

      currencyString(3)Required

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

      valueString(16)Required

      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.

      refundReasonString(256)Optional
      The refund reasons

      Response parameters

      resultResultRequired

      The request result, which contains information related to the request result, such as status and error codes.

      resultCodeString(16)Required
      Result code
      resultStatusEnumRequired

      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.
      resultMessageString(64)Optional
      Result message
      refundRequestIdString(64)Optional
      The unique ID that is assigned by the merchant to identify a refund request
      refundIdString(64)Optional
      The unique ID that is assigned by Alipay to identify a refund. A one-to-one correspondence between refundId and refundRequestId exists.
      paymentIdString(64)Optional
      The unique ID assigned by Alipay for the original payment to be refunded
      refundAmountAmountOptional

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

      currencyString(3)Required

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

      valueString(16)Required

      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.

      refundTimeDatetimeOptional

      The date and time when the refund reaches a final state of success or failure, which follows the ISO 8601 standard.

      grossSettlementAmountAmountOptional

      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.

      currencyString(3)Required

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

      valueString(16)Required

      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.

      settlementQuoteQuoteOptional

      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.

      quoteIdString(64)Optional
      The unique ID to identify a quote.
      quoteCurrencyPairString(16)Required
      Pair of currency exchange rate
      quotePriceDecimal(20)Required
      Rate quotation, decimal point that follows market quotation
      quoteStartTimeDatetimeOptional

      Effective time of the exchange rate, which follows the ISO 8601 standard

      quoteExpiryTimeDatetimeOptional

      Expiration time of the exchange rate, which follows the ISO 8601 standard

      guaranteedBoolean Optional
      Guaranteed exchange rate is available for payment

      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

      CodeValueMessage
      SUCCESSSSuccess
      REFUND_WINDOW_EXCEEDFThe refund date exceeds the refundable period that is agreed in the contract.
      REFUND_AMOUNT_EXCEEDFThe total refund amount exceeds the payment amount.
      ORDER_NOT_EXISTFThe order does not exist.
      ORDER_STATUS_INVALIDFThe order status is invalid.
      MERCHANT_BALANCE_NOT_ENOUGHFThe merchant balance is not enough.
      CURRENCY_NOT_SUPPORT FThe currency is not supported.
      PROCESS_FAILFA general business failure occurred. Do not retry.
      PARAM_ILLEGALFIllegal parameters exist. For example, a non-numeric input, or an invalid date.
      REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.
      KEY_NOT_FOUNDFThe key is not found.
      ACCESS_DENIEDFAccess denied
      REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
      API_INVALIDFAPI is invalid or not active.
      CLIENT_INVALIDFThe client is invalid.
      SIGNATURE_INVALIDFThe signature is invalid.
      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.
      MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
      UNKNOWN_EXCEPTIONUAn API calling is failed, which is caused by unknown reasons.
      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