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

      alipay.acquire.refund

      Auto-debit Acquiring refund Interface-- alipay.acquire.refundThis interface can be used by merchant to refund the transaction.


      #Request

      #Service address

      Environment

      HTTPS request URL

      Production environment

      https://intlmapi.alipay.com/gateway.do

      Test environment

      https://mapi.alipaydev.com/gateway.do

      #Request parameters

      ParameterType(length)DescriptionRequiredExample
      Basic parameters
      serviceStringService Name

      Y

      		alipay.acquire.refund
      partnerString(16)Partner ID that is composed of 16 digits beginning with 2088.

      Y

      		2088101125328850
      _input_charsetStringThe charset with which the request data is encoded. UTF-8 is supported.

      Y

      		utf-8
      sign_typeStringSign type. DSA, RSA, and MD5 are supported. Use uppercase.

      Y

      		MD5
      signStringSign value

      Y

      		363a752668ee2b3b8f1 24c623bd028ad
      alipay_ ca_req uestString

      Signature type.

      1: Certificate signature

      2: Other key signatures

      If this is null, the default value shall be 2.

      N

      		2
      notify_urlString(190)The URL for receiving asynchronous notifications after the payment is completed.

      N

      		http://api.test.alipay.net/atinterface/receive_notify.htm
      Business parameters
      out_trade_noString(64)Unique order No. in Alipay’s merchant’s website

      Y

      		HZ0120131127001
      refund_amountnumber(9,2)The amount refunded shall not be greater than order amount. Full refund shall be consistent with order amount.

      Y

      		200.00
      trans_currencyString(8)The currency used for refund pricing. It should be either CNY or the trans_currency used for purchasing. Default value is CNY

      N

      		CNY
      trade_noString(64)The trade serial number of the trade in Alipay system.16 bits at least and 64 bits at most. If out_trade_no and  trade_no are transmitted at the same time, trade_no shall govern.

      N

      		2013112611001004680073956707
      sync_flagString(1)The refund request is processed synchronously or asynchronously. Value: Y or N. Default value is N, which is processed asynchronously.

      N

      		N
      out_request_noString(64)Merchant’s refund request No. is used to identify the refund request in this trade.If this parameter is not transmitted, out_trade_no shall be filled out as  the value of this parameter and at the same time it is deemed that this request is full refund request. The refund amount shall be the same as the payment amount.

      N

      		HZ01RF001
      operator_typeString(1)Operator type:0: operator of Alipay1: operator of merchantIf other value or no value is transmitted, it shall be deemed to be 1.

      N

      		1
      operator_idString(28)Seller’s operator ID

      N

      		OP001
      refund_reasonString(128)Refund reason explanation

      N

      		Normal refund
      ref_idsString(256)Business reference ID set is used for placing merchant’s refund order No., refund serial No., etc. It shall be in json format. Please refer to

      ref_ids for details.

      N

      		 [{"id_type":"orig_out_req uest_no","id":"HZ0001"},{"id_type":"orig_out_order_no","id":"HZ0001"}]
      extend_paramsString(128)Be used for transferring refund business information. Only when merchant and Alipay prescribed for passing this parameter and the parameter meaning, this parameter is valid.

      N

      		{"STORE_ID":"BJ_ZZ_001","STORE_TYPE":"0"}


      #ref_ids

      ParameterType(length)DescriptionRequiredExample
      id_typeString

      Extended ID type:

      orig_out_order_no: merchant’s original refund order No.

      orig_out_request_no: merchant’s original refund request serial No.

      Y

      		orig_out_order_no
      idStringExtended ID value

      Y

      		HZ0001


      #extend_params

      ParameterType(length)DescriptionRequiredExample
      STORE_TYPEPString

      Store type.

      0: Alipay store

      1: merchant store

      N

      		0
      STORE_IDStringStore id, need to combine with STORE_TYPE. Merchant need to confirm that the store id is exit under the relevant store type.

      N

      		BJ_ZZ_001
      TERMINAL_IDString

      The terminal device that used for submit request.

      This parameter is indispensable if use promotions.

      N

      		A80001


      #Response

      ParameterType(length)DescriptionRequiredExample
      Basic parameter
      is_successString

      Request succeeds or not. Successful request does not mean the business is accepted and processed successfully.

      T means success

      F means failure

      Y

      		T
      sign_typeStringSign type. DSA, RSA, and MD5 are supported. Use uppercase.

      N

      		MD5
      signStringSign value

      N

      		fc209d86b57b2adb23254a897ebaa7d9
      errorString

      This parameter does not exist if request succeeds;

      This parameter will be error code if request fails.

      N

      		ILLEGAL_SIGN
      result_codeString(32)

      Response code of refund processing result.

      SUCCESS: successful refund

      INPROCESS: the request is accepted; refund in process.

      FAIL: unsuccessful refund

      UNKNOWN: unknown result

      Y

      		SUCCESS
      trade_noString(64)Trade number of the trade in Alipay system16 bits at least and 64 bits at most

      N

      		2013112011001004330000121536
      out_trade_noString(64)Unique order ID in order system in corresponding merchant’s website other than Alipay trade number.Uniqueness of this parameter in merchant’s website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.

      N

      		6823789339978248
      buyer_user_idString(24)Unique Alipay user ID corresponding to Buyer’s Alipay logon ID.16 numbers beginning with 2088

      N

      		2088102122524333
      buyer_logon_idString(100)Buyer’s Alipay logon ID, may be email or phone number.

      N

      		159****5620
      fund_changeString(1)

      In respect of refund request of the same merchant, if the refund has been conducted, the result of last refund will be returned directly. At the same time, identification of whether capital change happens or not will be returned.

      Y: capital change happened in this refund request;

      N: capital change does not happen in this refund request

      N

      		Y
      refund_feeNumberThe actual refund amount, the unit is RMB.

      N

      		1.00
      trans_currencyString(8)The currency used for refund pricing. It should be either CNY or the trans_currency used for purchasing.

      N

      		CNY
      gmt_refund_payDateRefund date, the format as below:yyyy-MM-dd HH:mm:ss

      N

      		2013-11-27 15:45:57
      refund_detail_item_listList

      Refund amount of return channel, the XML format, and can return multiple refund channel child node <TradeFundBil>, the parameter of the node contains , please refer to refund_detail_item_list.

      N

      		Refer to “5.3 Refund Channel List”
      detail_error_codeString(48)Give cause description to the response code returned. If the response code of result_code is SUCCESS, this parameter shall not be returned.

      N

      		TRADE_STATUS_ER ROR
      detail_error_desString(64)

      Give literal statement as to the detailed error code. If the response code of result_code is SUCCESS, this parameter shall not be returned.

      N

      		Trade status is illegal.

      #refund_detail_item_list

      ParameterType(length)DescriptionRequiredExample
      fund_channelStringRefund channel, refer to  refund channel

      N

      		ALIPAYACCOUNT
      amountStringThe amount that Using the specified channels refund, the unit is RMB.

      N

      		70.00

      #Error codes

      #Business errors

      Error codeDescription
      INVALID_PARAMETERParameter is invalid.
      TRADE_ROLE_ERRORThere is no right to refund or withdraw this trade.
      DISCORDANT_REPEAT_REQUESTThe refund amount or the amount specified in withdrawal order of the same trade is inconsistent.
      TRADE_HAS_CLOSEThe trade has been closed.
      REASON_TRADE_BEEN_FREEZENThe trade has been frozen.
      BUYER_ERRORThe buyer does not exist.
      SELLER_ERRORThe seller does not exist.
      TRADE_NOT_EXISTThe trade does not exist.
      TRADE_STATUS_ERRORThe trade status is illegal.
      TRADE_HAS_FINISHEDThe trade has been finished.
      REFUND_AMT_NOT_EQUAL_TOTALWithdrawal or refund amount is inconsistent with the amount in order.
      SELLER_BALANCE_NOT_ENOUGHThe balance of seller is not enough.
      ACCOUNT_BALANCE_NOT_AVALIABLE_TEMPORILYThe balance of the user’s account is temporally not available.
      ACCOUNT_NOT_EXISTSThe account is not exist.
      FOREX_REFUND_CURENCY_NOT_EQUAL_TRADE_CURENCYThe refund pricing currency is different from the transaction pricing currency.
      FOREX_REFUND_NOT_SET_CURENCY Refund to foreign currency transaction needs to set refund currency.
      FOREX_REFUND_RATE_NOT_FOUND The transaction fx rate cannot be retrieved when refunding.
      FORIGEN_CURRENCY_DECIMAL_NUM_NOT_EXISTSCannot retrieve the currency decimal count for foreign currency transaction
      FORIGEN_CURRENCY_TOTAL_FEE_NOT_MATCH_DECIMAL_NUM The input foreign currency amount is not matching the supported format (decimal digit not match)
      FORIGEN_CURRENCY_TOTAL_FEE_NOT_NULLThe foreign currency amount is not correct
      MERCHANT_BALANCE_NOT_ENOUGHMerchant balance is not enough for refund
      NOT_THIS_PARTNERS_TRADEThe trade is not belonged to the partner
      REASON_REFUND_AMOUNT_LESS_THAN_COUPON_FEEAlipay coupon cannot be partially refunded.
      REASON_TRADE_REFUND_FEE_ERRRefund fee amount error
      REFUND_AMOUNT_NOT_VALID The refund amount is not valid
      SELLER_ACCOUNT_HAD_FREEZEThe seller account is freeze
      SELLER_BALANCE_NOT_ENOUGHThe seller account balance is not enough
      TRADE_PRODUCT_NOT_ALLOW_REFUNDThe product is not allow refund
      TRADE_STATUS_NOT_ALLOW_REFUNDRefund is not allowed for the trade status.
      UNFOREX_TREADE_NOT_ALLOW_FOREX_FOUNDDomestic transaction cannot accept forex refund
      BUYER_ENABLE_STATUS_FORBIDBuyer account status prohibits the refund


      #Access errors

      Error codeDescription
      ILLEGAL_SIGNIllegal signature.
      ILLEGAL_DYN_MD5_KEYDynamic key information is incorrect.
      ILLEGAL_ENCRYPTEncryption is incorrect.
      ILLEGAL_ARGUMENTParameter is incorrect.
      ILLEGAL_SERVICEService parameter is incorrect.
      ILLEGAL_USERUser ID is incorrect.
      ILLEGAL_PARTNERPartner ID is incorrect.
      ILLEGAL_EXTERFACEInterface configuration is incorrect.
      ILLEGAL_PARTNER_EXTERFACEPartner’s interface information is incorrect.
      ILLEGAL_SECURITY_PROFILEMatching private key configuration has not been found.
      ILLEGAL_AGENTAgency ID is incorrect.
      ILLEGAL_SIGN_TYPEThe signature type is incorrect.
      ILLEGAL_CHARSETThe character set is illegal.
      HAS_NO_PRIVILEGEHas no right to visit.
      INVALID_CHARACTER_SETThe character set is invalid.


      #System errors

      Error codeDescription
      SYSTEM_ERRORAlipay system error
      SESSION_TIMEOUTSession timeout
      ILLEGAL_TARGET_SERVICEWrong  target_service
      ILLEGAL_ACCESS_SWITCH_SYSTEMMerchant is not allowed to visit system of this type.
      EXTERFACE_IS_CLOSEDThe interface has been closed.


      #Refund funding channel

      CodePayment channel
      ALIPAYACCOUNTAlipay Balance
      COUPONAlipay Red Envelop
      POINTAlipay Points
      BANKCARDBank card
      DISCOUNTAlipay Discount
      FINANCEACCOUNTSpecial Alipay account for financial management
      TMALLFUNDTmall Fund
      PCARDPrepaid card
      MCARDMerchant’s card
      MDISCOUNTMerchant’s discount coupon
      MCOUPONMerchant’s Red Envelope


      #Samples

      #Request sample

      https://mapi.alipay.com/gateway.do?operator_id=OP001&sign_type=RSA&out_trade_no=HZ0120131127001&operator_type=1&sign=363a752668ee2b3b8f124c623bd028ad&_input_charset=UTF-8&service=alipay.acquire.refund&out_request_no=HZ01RF001&partner=2088101125328850&refund_reason=%E6%AD%A3%E5%B8%B8%E9%80%80%E6%AC%BE&refund_amount=200&alipay_ca_request=2


      #Response sample

      Business is accepted and processed normally, and refund is conducted successfully:

      copy
      <?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="sign">8c066dc2cb92a9c2c8070d935917fa73</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">RSA</param>
<param name="service">alipay.acquire.refund</param>
<param name="out_request_no">daiqing121</param>
<param name="partner">2088101125936190</param>
<param name="refund_reason">refund on behalf of qing</param>
<param name="refund_amount">1.00</param>
<param name="out_trade_no">6823789339978248</param>
</request>
<response>
<alipay>
<result_code>SUCCESS</result_code>
<buyer_logon_id>159****5620</buyer_logon_id>
<buyer_user_id>2088102122524333</buyer_user_id>
<fund_change>Y</fund_change>
<out_trade_no>6823789339978248</out_trade_no>
<trade_no>2013112011001004330000121536</trade_no>
</alipay>
</response>
<sign>fc209d86b57b2adb23254a897ebaa7d9</sign>
<sign_type>RSA</sign_type>
</alipay>


      Request succeeds, business processing fails:

      copy
      <?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="sign">8c066dc2cb92a9c2c8070d935917fa73</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">RSA</param>
<param name="service">alipay.acquire.refund</param>
<param name="out_request_no">daiqing121</param>
<param name="partner">2088101125936190</param>
<param name="refund_reason">refund on behalf of Qing</param>
<param name="refund_amount">1.00</param>
<param name="out_trade_no">6823789339978248</param>
</request>
<response>
<alipay>
<result_code>FAIL</result_code>
<detail_error_code>TRADE_STATUS_ERROR</detail_error_code>
<detail_error_des>illegal trade status</detail_error_des>
</alipay>
</response>
<sign>fc209d86b57b2adb23254a897ebaa7d9</sign>
<sign_type>RSA</sign_type>
</alipay>


      Output when Request fails or the data accessed is wrong:

      copy
      <?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>