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

      Refund

      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.


      #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.resultCoderesultStatusresultMessage

      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.