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 are encoded. UTF-8 is supported 

      Example:UTF-8

      sign_type

      String Required

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

      Example:RSA

      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

      String(64) Required

      The unique refund ID for the refund request

      Example:205485121225

      out_trade_no

      String(64) Required

      The transaction ID of the original payment

      Example:990xxxxxxx8989

      return_amount

      Number(9,2)

      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. The return_amount and return_rmb_amount fields cannot be empty at the same time, therefore, one of them must be specified.

      Example:100.30

      return_rmb_amount

      Number(9,2)

      The refund amount in CNY. The value is in the range of 0.01 - 1000000.00, with at most 2 digits after the decimal point. Either the return_amount or return_rmb_amount field can be specified.

      Example:10.20

      currency

      String(10) Required

      The currency for the refund. The value of this field is not CNY, even when the return_rmb_amount parameter is not null. Use upper case. For more information about supported currencies, see Supported Currencies.

      Example:USD

      gmt_return

      String(14) 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

      String(100)

      Reason for the refund 

      Example:Out of supply

      product_code

      String(32) Required

      Product code of the Alipay product that you use, which is NEW_OVERSEAS_SELLER for website payment refund, and NEW_WAP_OVERSEAS_SELLER for WAP or APP payment refund.

      Example:NEW_OVERSEAS_SELLER

      is_sync

      String(1)

      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

      split_fund_info

      String(1600)

      Split fund information, which is in the JSON format. For more details, see Refund Split Detail Info. 

      Example:[{"transOut":"2088101137935255","amount":"0.10","currency":"USD","desc":"test1"},{"transOut":"2088101126707869","amount":"0.10","currency":"USD","desc":"test2"}]

      Note:

      The decimal place accuracy of amounts, such as the values of return_amount, depends on the value of currency. If the value of currency isJPY, then the amount must be an integer. For example, 100 JPY. For other currencies, the amount is of two decimal place accuracy. For example, 100.00 USD. Amounts in other formats will cause error, for example, 100.999 USD. The values of parameters such as return_rmb_amount are also of two decimal places because the currency is CNY. is_sync YNTF

      #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 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:REPEATED_REFUNDMENT_REQUEST

      #Asynchronous response

      ParameterDescription
      Basic parameter

      notify_type

      String

      Notification type

      Example:refund_status_sync

      notify_time

      Timestamp

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

      Example:2009-08-12 11:08:32

      notify_id

      String

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

      Example:70fec0c2730b27528665af4517c27b95

      sign_type

      String

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

      Example:MD5

      sign

      String

      Sign value

      Example:656578b72f40e52326dba4a41d6da62b

      Business parameter

      out_trade_no

      String(64)

      The unique transaction ID that is assigned by the merchant for the refund

      Example:990xxxxxxx8989

      out_return_no

      String(64)

      Refund ID of the partner

      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

      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(8)

      The currency for the refund

      Example:CNY

      return_amount

      Number(9,2)

      Refund amount

      Example:100.00

      #Error codes

      #Business errors

      Returned result

      Description

      REFUNDMENT_VALID_DATE_EXCEED

      The refund cannot be performed after the specified refund time period.

      SYSTEM_EXCEPTION

      System exception

      ILLEGAL_ARGUMENT

      Illegal argument

      REPEATED_REFUNDMENT_REQUEST

      Duplicated refund request

      RETURN_AMOUNT_EXCEED

      Refund amount is over the payment amount.

      CURRENCY_NOT_SAME

      Different currency from the payment currency

      PURCHASE_TRADE_NOT_EXIST

      The payment transaction does not exist.

      BUYER_NOT_EXIST

      The buyer does not exist.

      REFUND_CHARGE_ERROR

      The refund failed because the payment is in progress. Please try again later.

      MORE_THAN_ALLOW_REFUND_FOREX_FEE

      The refund amount is more than the refundable amount.

      #Access errors

      Returned result

      Description

      ILLEGAL_SIGN

      Illegal signature

      ILLEGAL_SERVICE

      Service parameter is incorrect.

      ILLEGAL_PARTNER

      Incorrect partner ID

      ILLEGAL_SIGN_TYPE

      Signature is of wrong type.

      ILLEGAL_PARTNER_EXTERFACE

      Service is not activated for this account.

      ILLEGAL_DYN_MD5_KEY

      Dynamic key information is incorrect.

      ILLEGAL_ENCRYPT

      Encryption is incorrect.

      ILLEGAL_USER

      User ID is incorrect.

      ILLEGAL_EXTERFACE

      Interface configuration is incorrect.

      ILLEGAL_AGENT

      Agency ID is incorrect.

      HAS_NO_PRIVILEGE

      No right to visit

      INVALID_CHARACTER_SET

      The character set is invalid.

      #System errors

      Returned result

      Description

      SYSTEM_ERROR

      Alipay system error

      SESSION_TIMEOUT

      Session timeout

      ILLEGAL_TARGET_SERVICE

      Wrong target service

      ILLEGAL_ACCESS_SWITCH_SYSTEM

      Merchant is not allowed to visit system of this type.

      EXTERFACE_IS_CLOSED

      The interface has been closed.

      #Samples

      #Request

      Request sample with the return_amount field specified

      https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&product_code=NEW_OVERSEAS_SELLER&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190830_204330&return_amount=0.01&gmt_return=20190904142347&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=8080dd500a1ecb05a393e168d57090d2


      Request sample with the return_rmb_amount field specified

      https://intlmapi.alipay.com/gateway.do?service=forex_refund&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&product_code=NEW_OVERSEAS_SELLER&out_return_no=out_return_no_20190904_142347&out_trade_no=out_trade_no_20190830_204330&return_rmb_amount=0.07&gmt_return=20190904142347&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=4c13c00a832ebbd2a08379dd3d8e2ec6

      #Response

      Synchronous response sample

      Success response

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

      Error response

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

      Asynchronous response sample

      copy
      https://www.mikascoffee.com/notify
      notify_type=refund_status_sync
      return_amount=0.01
      notify_time=2019-09-04 18:07:27
      out_trade_no=out_trade_no_20190826_204553
      refund_status=REFUND_SUCCESS
      sign=$$
      out_return_no=out_return_no_20190904_142349
      currency=USD
      sign_type=MD5
      notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxxx9467