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

      forex_refund

      Call this interface to refund a transaction.


      To initiate multiple refund transactions by using a same partner ID (partner), send the refund requests with an interval of at least 3 seconds.


      #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

      ParameterDescription
      Basic parameter

      service

      String Required

      Interface name 

      Example:forex_refund

      partner

      String(16) Required

      The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088. 

      Example:2088*********662

      _input_charset

      String Required

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

      Example:UTF-8

      sign_type

      String Required

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase. 

      Example:RSA2

      sign

      String Required

      Sign value 

      Example:e5815a4556db338ed237f7d3fd222184

      notify_url

      URL(200)

      The URL for receiving asynchronous notifications after the payment is completed.

      Example:http://www.test.com/alipay/notify_url.php

      Business parameter

      out_return_no

      Required

      The unique refund ID for the refund request 

      Example:205485121225

      out_trade_no

      Required

      The payment ID for the original payment transaction 

      Example:990xxxxxxx8989

      return_amount
      Required

      The amount to refund in the settlement currency. The value is in the range of 0.01 – 1000000.00, with at most 2 digits after the decimal point.

      Example:100.30

      currency

      Required

      The currency for the refund. Only HKD is supported. 

      Example:HKD

      gmt_return

      Required

      Refund transaction time, with a format of yyyy-MM-dd HH:mm:ss. Use GMT+8.

      Example:2013-11-27 15:45:57

      reason

      Required

      Reason for the refund 

      Example:product defect

      is_sync

      Required

      Indicates that the refund request is processed synchronously or asynchronously with a value of Y or N.The default value is N, which means an asynchronous response from Alipay is returned to the merchant if the merchant has set the value of the notify_url field when sending the refund request. If the value is set as Y, it means only a synchronous response is returned to the merchant. 

      Example:N

      Note:

      Do not use the halfwidth quotation mark (") in parameter values.

      #Response

      #Synchronous response

      ParameterDescription

      is_success

      String Required

      If the value of is_sync is Y, this parameter indicates whether the refund succeeds, with a value of T for success and F for failure.

      If the value of is_sync is empty or N, this parameter indicates whether the request succeeds, with a value of T for success and F for failure. A successful request does not mean the business is accepted and processed successfully.

      Example:T

      error

      String

      Error message

      Example:REPEATED_REFUNDMENT_REQUEST

      #Asynchronous response

      ParameterDescription
      Basic parameter

      sign_type

      String

      Sign type. RSA, RSA2 and MD5 are supported. Use uppercase. 

      Example:RSA

      sign

      String

      Sign value 

      Example:e5815a4556db338ed237f7d3fd222184

      Business parameter

      notify_type

      String

      Notification type, with a value of refund_status_sync 

      Example:refund_status_sync

      notify_id

      String(34)

      Notification ID, used by the partner system to verify the notification

      Example:92c60707dc43a5b2d648b7b4d3c2e1592g

      notify_time

      Timestamp

      The time in GMT+8 when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss.

      Example:2015-06-30 09:56:02

      refund_status

      String(32)

      The refund status. The value can be REFUND_SUCCESS for a successful refund or REFUND_FAIL for a failed refund.

      Example:REFUND_SUCCESS

      out_trade_no

      String(64)

      The unique transaction ID that is assigned by the partner. This parameter is transmitted by the corresponding request and needs to be returned with the original value.

      Example:990xxxxxxx8989

      out_return_no

      String(64)

      Refund ID of the partner

      error_code

      String(64)

      Error code that is returned when the request is failed, to describe the request failure reason. For more information, see the Error Code section in this document.

      Example:RETURN_AMOUNT_EXCEED

      currency

      String(3)

      The refund currency 

      Example:HKD

      return_amount

      Number(9,2)

      Refund amount

      Example:100.00

      #Error codes

      #Business errors

      Returned resultDescription
      REFUNDMENT_VALID_DATE_EXCEEDCannot refund after the specified refund time.
      SYSTEM_EXCEPTIONSystem exception
      ILLEGAL_ARGUMENTIllegal argument
      REPEATED_REFUNDMENT_REQUESTDuplicated refund request
      RETURN_AMOUNT_EXCEEDRefund amount is over the payment amount
      CURRENCY_NOT_SAMEDifferent currency from the payment currency
      PURCHASE_TRADE_NOT_EXISTThe payment transaction does not exist
      REFUND_CHARGE_ERRORThe refund is failed because the payment is in progress. Please try again later.

      #Access errors

      Returned resultDescription
      SYSTEM_EXCEPTIONAlipay system error
      ILLEGAL_ARGUMENTIncorrect parameter
      ILLEGAL_SIGNIllegal signature
      ILLEGAL_SERVICEThe service parameter is incorrect
      ILLEGAL_PARTNERIncorrect partner ID
      ILLEGAL_SIGN_TYPESignature is of wrong type.
      ILLEGAL_PARTNER_EXTERFACEService is not activated for this account
      ILLEGAL_DYN_MD5_KEYDynamic key information is incorrect
      ILLEGAL_ENCRYPTEncryption is incorrect.
      ILLEGAL_USERUser ID is incorrect.
      ILLEGAL_EXTERFACEInterface configuration is incorrect.
      ILLEGAL_AGENTAgency ID is incorrect.
      HAS_NO_PRIVILEGENo right to visit
      INVALID_CHARACTER_SETThe character set is invalid.

      #System errors

      Returned resultDescription
      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.

      #Samples

      #Request

      Asynchronous refund request:

      https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=HKD&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190910_140255&return_amount=0.01&gmt_return=20190910140255&reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&sign=e1b27f1dedde149830e22da63091da7c


      Synchronous refund request:

      https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=HKD&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190910_140255&return_amount=0.01&gmt_return=20190910140255&reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&is_sync=Y&sign=83079e3e6540bf8efef87b1e76f4dbbf


      #Response

      Synchronous response

      copy
      <?xml version="1.0" encoding="GBK"?>
      <alipay>
          <is_success>T</is_success> 
      </alipay>


      Asynchronous response

      copy
      https://www.mikascoffee.com/notify
      notify_type=refund_status_sync
      return_amount=0.01
      notify_time=2019-09-10 14:52:46
      out_trade_no=out_trade_no_20190910_140255
      refund_status=REFUND_SUCCESS
      sign=$$
      out_return_no=out_return_no_20190904_142347
      currency=HKD
      sign_type=MD5
      notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx1673