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

      alipay.intl.acquiring.common.refund

      Use this interface to refund an existing payment. A refund can be partial and a transaction can have multiple refunds as long as the total refund amount is no greater than the original transaction amount. There is a refund window for each transaction. A refund request will be declined if it happens outside of the refund window.


      To retry a refund in case of timeout or the returned resultStatus is U, use the same merchantRefundId.


      #Request

      #Service address


      #Request head

      ParameterDescription

      version

      String(8) Required

      API version 

      Example:2.0.4

      function

      String(128) Required

      API name

      Example:alipay.intl.acquiring.common.refund

      clientId

      String(32) Required

      A unique ID assigned by Alipay to identify a client that makes API calls

      Example:385xxxxxxxxx0001

      reqTime

      Date time(/) Required

      Request time. The date time with timezone, see RFC 3339 Section 5.6 for details. 

      Example:2001-07-04T12:08:56+05:30

      reqMsgId

      String(64) Required

      Request message ID. A unique ID assigned by the client to identify a request message. This ID identifies a unique system request rather than business request.

      Example:123xxxxxxxxxxxxxx3fda

      reserve

      String(256) Conditional

      Reserved parameter. Key-value formatted parameter for future use. This parameter is required for system integrator. If you are a system integrator, you must provide the isvAccesstoken value. 

      Example:{"isvAccesstoken":123123123sdfsddsf}

      signType

      String(64)

      Sign type

      Example:RSA2


      #Request body

      ParameterDescription

      merchantId

      String(64) Required

      The unique merchant ID assigned by Alipay. This parameter identifies the settlement target that Alipay settles to.

      Example:211xxxxxxxxxxxxxx2999

      acquirementId

      String(64) Required

      The unique Alipay transaction ID that identifies the transaction to be refunded 

      Example:201xxxxxxxxxxxxxxxxxxxxx5678

      merchantRefundId

      String(64) Required

      The unique refund ID assigned by the merchant

      Example:Merchant_Refund_Id_93xxx

      refundAmount

      Money(/) Required

      The refund amount in the pricing currency. The value can not be greater than the original order amount. refundAmount must be provided in the smallest common currency unit. For example, to create a refund for $1.00, you set refundAmount value=100 (100 cents).

      See Money for details. 

      Example:{"value":"10000", "currency":"USD" }

      refundReason

      String(256)

      The refund reason that is shown in the buyer's transaction details. 

      Example:Refund per customer request

      extendInfo

      String(2048)

      The key-value formatted parameter reserved for future use

      Example:{Key/Value}

      isSync

      Boolean(5)

      This parameter specifies whether the refund is processed synchronously. Valid values are:

      • true. The refund is processed synchronously.
      • false. The refund is processed asynchronously.

      The default value is true.

      Example:true


      #Response

      #Response head

      ParameterDescription

      version

      String(8) Required

      API version

      Example:2.0.4

      function

      String(128) Required

      API name

      Example:alipay.intl.acquiring.common.refund

      clientId

      String(32) Required

      Client ID. The unique ID assigned by Alipay to identify a client that makes API calls

      Example:385xxxxxxxxx0001

      respTime

      Date time(/) Required

      Response time. The date time with timezone, see RFC 3339 Section 5.6 for details. 

      Example:2001-07-04T12:08:56+05:30

      reqMsgId

      String(64) Required

      Request message ID. The unique ID assigned by client to identify a request message

      Example:123xxxxxxxxxxxxxxx3fda

      reserve

      String(256)

      Reserved parameter. The key-value formatted parameter reserved for future use 

      Example:{key/value}

      signType

      String(8)

      Sign type

      Example:RSA2


      #Response body

      ParameterDescription

      resultInfo

      ResultInfo(/) Required

      See resultInfo for details. 

      Example:{ "resultStatus": "S", "resultCodeId": "00000000", "resultCode":"SUCCESS", "resultMsg": "result message" }

      merchantRefundId

      String(64) Conditional

      The unique ID assigned by the merchant to identify a refund. Only when the refund succeeds, this field is returned.

      Example:Refund_Request_Id_93xxx

      acquirementId

      String(64) Conditional

      The unique transaction ID assigned by Alipay when the transaction succeeds. 

      Example:201xxxxxxxxxxxxxxxxxxxxx5678

      refundId

      String(64) Conditional

      The unique refund ID assigned by Alipay. Only when the refund succeeds, this field is returned.

      Example:201xxxxxxxxxxxxxxxxxxxxx9012

      refundAmount

      Money(/) Conditional

      The refund amount in the pricing currency. The value can not be greater than the original order amount. refundAmount must be provided in the smallest common currency unit. For example, to create a refund for $1.00, you would set refundAmount value=100 (100 cents). Note: This parameter is required when resultInfo.resultCode is SUCCESS.See Money for details.

      Example:{"value":"10000", "currency":"USD" }

      refundTime

      Date time(/) Conditional

      Date time with timezone, see RFC 3339 Section 5.6 for details. Note: This parameter is required when resultInfo.resultCode is SUCCESS. 

      Example:2001-07-04T12:08:56+05:30

      extendInfo

      String(2048)

      Extended information. The key-value formatted parameter reserved for future use.

      Example:{}


      #Sub-parameters

      #resultInfo

      ParameterDescription

      resultStatus

      String(2) Required

      The request status can be:S: successF: failureU: unknown

      Example:S

      resultCodeId

      String(8) Required

      An 8-digit code that is used to identify a result. When resultStatus is S, the value must be 00000000. When resultStatus is F or U, the value can be other result ID specified by the interface. 

      Example:00000000

      resultCode

      String(64) Required

      The result code

      Example:SUCCESS

      resultMsg

      String(256)

      When resultCode is S, this value can be empty. When resultCodeis F or U, the error description is required.

      Example:success


      #Money

      ParameterDescription

      currency

      String(3) Required

      The 3-letter currency code. See Supported currencies for details. 

      Example:USD

      value

      Number(16) Required

      The amount. This value must be provided in the smallest common currency unit. For example, to create a charge for $1.00, you set orderAmount value=100 (100 cents). 

      Example:239


      #Result code

      #Functional logic result code

      resultCodeId

      resultCode

      resultStatus

      Remarks

      00000025

      REPEAT_REQ_INCONSISTENT

      F

      Repeated or inconsistent requests

      12002005

      USER_NOT_EXIST

      F

      The user does not exist.

      12002006

      USER_STATUS_ABNORMAL

      F

      Abnormal user status

      12005001

      CURRENCY_NOT_SUPPORT

      F

      The transaction currency is not supported. See Supported currencies for details.

      12005004

      ORDER_NOT_EXIST

      F

      The transaction does not exist.

      23005302

      REFUND_AMOUNT_EXCEED

      F

      The refund amount exceeds the limit.

      12005014

      REFUND_TIME_EXCEED_LIMIT

      F

      The refund time exceeds the limit.

      12005003

      ORDER_STATUS_INVALID

      F

      The transaction status is invalid.

      12005134

      SIGN_TYPE_INVALID

      F

      The signature type is invalid.

      12006009

      MERCHANT_BALANCE_NOT_ENOUGH

      F

      The merchant balance is not enough.


      #Basic result code

      resultCodeId

      resultCode

      resultStatus

      Remarks

      00000000

      SUCCESS

      S

      Success

      00000019

      PROCESS_FAIL

      F

      General business failure

      00000901

      UNKNOWN_EXCEPTION

      U

      API failed because of unknown reasons

      00000004

      PARAM_ILLEGAL

      F

      The parameter is incorrect.

      00000007

      INVALID_SIGNATURE

      F

      The signature is invalid.

      00000008

      KEY_NO_FOUND

      F

      The key is not found.

      00000013

      NO_INTERFACE_DEF

      F

      The API is undefined.

      00000014

      API_IS_INVALID

      F

      The API is invalid or nonactivated.

      00000021

      ACCESS_DENIED

      F

      Access denied

      12014155

      UNKNOWN_CLIENT

      F

      Unknown client

      12014156

      INVALID_CLIENT_STATUS

      F

      Invalid client status

      00000024

      REQUEST_TRAFFIC_EXCEED_LIMIT

      F

      The request traffic exceeds the limit.

      12003001

      MERCHANT_NOT_EXIST

      F

      The merchant doesn't exist.


      #Sample

      #Sample request

      copy
      {
          "request":{
              "head":{
                  "version":"2.0.4",
                  "function":"alipay.intl.acquiring.common.refund",
                  "clientId":"385xxxxxxxxx0001",
                  "reqTime":"2001-07-04T12:08:56+05:30",
                  "reqMsgId":"123xxxxxxxxxxxxxxx3fda",
                  "signType":"RSA2"
              },
              "body":{
                  "merchantId":"211xxxxxxxxxxxxxx2999",
                  "acquirementId":"201xxxxxxxxxxxxxxxxxxxxx5678",
                  "merchantRefundId":"Merchant_Refund_Id_93045",
                  "refundAmount":{
                      "currency":"USD",
                      "value":"239"
                  },
                  "refundReason":"refund per customer request",
                  "extendInfo":"{}",
                  "isSync":true
              }
          },
          "signature":"signature string"
      }


      #Sample response

      copy
      {
          "response":{
              "head":{
                  "version":"2.0.4",
                  "function":"alipay.intl.acquiring.common.refund",
                  "clientId":"385xxxxxxxxx0001",
                  "respTime":"2001-07-04T12:08:56+05:30",
                  "reqMsgId":"123xxxxxxxxxxxxxxx3fda",
                  "reserve":"{}",
                  "signType":"RSA2"
              },
              "body":{
                  "resultInfo":{
                      "resultStatus":"S",
                      "resultCodeId":"00000000",
                      "resultCode":"SUCCESS",
                      "resultMsg":"success"
                  },
                  "merchantRefundId":"Merchant_Refund_Id_93045",
                  "acquirementId":"201xxxxxxxxxxxxxxxxxxxxx5678",
                  "refundId":"201xxxxxxxxxxxxxxxxxxxxx9012",
                  "refundAmount":{
                      "currency":"USD",
                      "value":"239"
                  },
                  "refundTime":"2001-07-04T12:08:56+05:30",
                  "extendInfo":"{}"
              }
          },
          "signature":"signature string"
      }