alipay.acquire.overseas.spot.refund

Call this interface to issue a full or partial refund for a transaction. The refund request cannot be cancelled.

#Request

#Service address

Environment

HTTPS request URL

Production environment

Priority: https://globalmapi.alipay.com/gateway.do

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

Test environment

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

Note:

If you use POST method, please specify _input_charset in the request URL.

For example: https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

#Request parameters

ParameterDescription
Basic parameter

service

String Required

Interface name 

Example:alipay.acquire.overseas.spot.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

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) Required

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

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

Business parameter

partner_trans_id

String(64) Required

The original partner transaction ID given in the payment request, which is:

  • the value of out_trade_no in the alipay.acquire.precreate interface.
  • the value of partner_trans_id in the alipay.acquire.overseas.spot.pay interface.

Example:2010121000000002

alipay_trans_id

String(64)

The Alipay transaction ID

Example:201311221703338463

partner_refund_id

String(64) Required

The refund order ID in the partner system. The value of partner_refund_id cannot be the same as that of partner_transaction_id. The partner_refund_id field plus the partner field identifies a refund transaction.

Example:301012133000002

refund_amount

Number(9,2) Required

Refund amount, which must be less than or equal to the original transaction amount or the left transaction amount if ever refunded.

Example:39.25

currency

String(10) Required

The refund currency. Use upper case. For more information about supported currencies, see Supported Currencies.

Example:USD

refund_reason

String(128)

Reason for the refund 

Example:Refund the good

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 notification 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:Y


Note:

The decimal place accuracy of amounts, such as the values of refund_amount, depend 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.

#Response

#Synchronous response parameters

#Parameters accepted by Alipay gateway:

ParameterDescription

is_success

String(1) Required

Indicate whether the request succeeds or not, with a value of T for success and F for failure.

Note: a successful request does not mean the business is accepted and processed successfully. 

Example:T

sign_type

String Required

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

Example:MD5

sign

String(32) Required

Sign value 

Example:59c7275cf3c82f038b7c0076f9888926

result_code

String(32) Required

Processing result of the request. Possible values are:

  • SUCCESS: when the refund is synchronous, this field indicates that the refund is successful, the value of is_sync is Y. When the refund is asynchronous, this field indicates that the processing is accepted successfully, which does not mean the refund is processed successfully.
  • FAILED: indicates that the process is failed.

Example:SUCCESS

error

String(48)

Error code that is returned when the request is not successful, to describe the request failure reason. This field is not returned when the result_code is SUCCESS. For more information, see the Error Code section in this document.

Example:TRANS_NOT_FOUND

partner_trans_id

String(64) Required

The original partner transaction ID given in the payment request. This parameter is transmitted by the corresponding request and needs to be returned with its original value.

Example:201311221000000002

alipay_trans_id

String(64)

The transaction ID assigned by Alipay for the partner's payment request, which follows a mapping relation with the partner field plus the partner_trans_id field.

Example:201311221703338463

partner_refund_id

String(64) Required

The refund order ID in the partner system. The partner_refund_id field plus the partner field identifies a refund transaction. 

Example:301012133000002

refund_amount

Number(9,2) Required

Refund amount, which must be less than or equal to the original transaction amount or the left transaction amount if ever refunded. 

Example:39.25

currency

String(10) Required

The refund currency 

Example:USD

exchange_rate

Number(8,6)

The exchange rate between the currency given in the request to CNY. The exchange occurs when the Alipay trade order is created. 

Example:6.0939

refund_amount_cny

Number(9,2)

Refund amount in CNY. It is the exact amount that Alipay refunded. 

Example:239.19

#Parameters rejected by Alipay gateway:

ParameterDescription

is_success

String(1) Required

Indicates whether the request is accepted by the Alipay gateway.

T: accepted

F: rejected

Example:F

sign_type

String Required

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

Example:MD5

sign

String(32) Required

Sign value

Example:59c7275cf3c82f038b7c0076f9888926

error

String(48)

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

Example:TRANS_NOT_FOUND

#Asynchronous notification parameters

Alipay notifies the merchant website of the result data processed through an initiative notification from the server after completing the processing of request data of merchant. These result data are asynchronous notification parameters from the server.

ParameterDescription
Basic parameter

notify_time

Timestamp Required

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

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

notify_type

String Required

Notification type 

Example:refund_status_sync

notify_id

String Required

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

Example:ac05099524730693a8b 330c5ecf72da978

sign_type

String Required

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

Example:MD5

sign

String Required

Sign value

Example:601510b7970e52cc63d b0f44997cf70e

Business parameter

out_trade_no

String(64)

Unique order ID in the order system in corresponding merchant’s website, other than Alipay trade number. Uniqueness of this parameter in merchant’s website need to be guaranteed. This is a parameter transmitted upon corresponding request, which need to be returned in its orginal shape.

Example:990xxxxxxx8989

out_return_no

String(64) Required

The refund order ID in the partner system. If the merchant initiates the refund request on the Alipay website, this parameter is to be filled with an automatically generated number by Alipay. 

Example:301012133000002

refund_status

String(64) Required

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

Example:REFUND_SUCCESS

currency

String(8)

The refund currency

Example:USD

return_amount

Number(9,2)

The refund amount in the refund currency

Example:1.00

trans_refund_fee

Number(9,2)

The estimated refund amount in the original transaction currency, for reference only.

Example:1.00

error_code

String

The reason for a refund with status of REFUND_FAIL. This field is nulll when the refund_status is REFUND_SUCCESS.

Example:ILLEGAL_SIGN

#Error codes

Error code

Description

SYSTEM_ERROR

Alipay system is not available.

Action: Retry this request with the exact parameters. Refer to Case 2 for detailed instruction.

ILLEGAL_SIGN

Illegal signature.

Action: Use a legal signature and try again.

INVALID_PARAMETER

Parameter error.

Action: Check the standard of each request parameter according to the API specification

ILLEGAL_ARGUMENT

Parameter error.

Action: Check each request parameter according to the API specification, contact Alipay technical support if this error persists

ILLEGAL_PARTNER

Incorrect partner ID.

Action: Ensure that the value of the partner parameter matches the partner value provided by Alipay. Contact Alipay technical support if this error persists.

ILLEGAL_EXTERFACE

Interface configure error.

Action: Ensure that the service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists

ILLEGAL_PARTNER_EXTERFACE

The partner ID does not have access privilege.

Action: Ensure your agreement with Alipay has been finalized. Contact Alipay technical support if needed.

ILLEGAL_SIGN_TYPE

Illegal sign type.

Action: Ensure that the value of sign_type is among MD5,RSA and RSA2. Contact Alipay technical support if this error persists.

HAS_NO_PRIVILEGE

Has no privilege.

Action: Contact Alipay technical support.

REASON_TRADE_BEEN_FREEZEN

Corresponding trade has been frozen due to security issues.

Action: Contact Alipay technical support.

TRADE_NOT_EXIST

Cannot find corresponding trade according to the value of partner_trans_id.

Action: 1. Ensure that the value of partner_trans_id is correct. 2. If the issue persists, contact Alipay Technical Support.

TRADE_STATUS_ERROR

Corresponding trade status is not allowed for the current operation.

Action: 1. Ensure that the trade status is correct. 2. If the issue persists, contact Alipay technical support.

REFUND_AMT_RESTRICTION

The value of refund_amount is more than the original trade amount, or total refund amount is more than the original trade amount, which cannot be processed by Alipay.

Action: Merchant needs to check if the returned amount is correct.

REQUEST_AMOUNT_EXCEED

Same as the REFUND_AMT_RESTRICTION error code.

Action: Merchant needs to check if the returned amount is correct.

TRADE_HAS_CLOSE

The transaction is closed and refunds are not allowed anymore.

Action: Check the status of this transaction and the refund time window setting.

MERCHANT_BALANCE_NOT_ENOUGH

Insufficient balance of the merchant to process this refund request. The previous transactions might have been settled to the merchant bank account.

Action: Retry the refund after new transactions occur and the merchant's balance is sufficient.

INVALID_ROUNDED_AMOUNT

The refund with this amount might have violated the rule that the calculated amount of both CNY and foreign currency must be fully or not fully refunded at the same time.

Take a transaction with 0.07 CNY (0.01 USD) as an example. A refund with 0.06 CNY is not to be accepted because 0.01 CNY (0 USD) is left for this transaction.

Action: Contact Alipay technical support.

REASON_TRADE_REFUND_FEE_ERR

Invalid refund amount.

Action: Check the request refund amount.

REFUND_CHARGE_ERROR

The refund is failed because the payment is in progress.

Action: Try again later.

BUYER_NOT_EXIST

The buyer does not exist.

Action: Contact Alipay technical support.

#Handling result

Case 1. When the invocation is failed due to network issue or request timeout, no response is returned from Alipay. Take the following actions:

  1. Check your network connectivity to Alipay gateway. Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
  2. If you still cannot get any response from Alipay, contact Alipay technical support for help.

Case 2. If you received the response from Alipay, but one of the following results is returned:

  • is_success=F and error=SYSTEM_ERROR
  • is_success=T, result_code=FAILED, and detail_error_code=SYSTEM_ERROR

Take the following actions:

  1. Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
  2. If you still cannot get any response from Alipay, contact Alipay technical support for help.

Case 3. If you received the response from Alipay, and is_success=T and result_code=SUCCESS, the merchant refund request is accepted successfully, but it does not necessarily mean that the refund is executed successfully.

Case 4. If you received the response from Alipay, and one of the following results is returned:

  • is_success=F and error=!SYSTEM_ERROR
  • is_success=T and result_code=FAILED and detail_error_code!=SYSTEM_ERROR.

The merchant failed to refund the order. Refer to specific error code for instruction.

#Pseudo code

copy
try{
  if(isCase3){ //CASE 3
    doSuccessProcess();
  }
  else if(isCase4){ //CASE 4
    doFailureProcess();
  }
  else{ //CASE 2
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }

}catch (Exception ex){ //CASE 1

    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }
}

#Samples

#Request

Asynchronous refund process:

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.spot.refund&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&partner_trans_id=out_trade_no_20190904_160450&partner_refund_id=partner_refund_id_20190904_160211&refund_amount=0.01&refund_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=b0d81ca4ecc6f14d149626233c727ef2


Synchronous refund process:

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.spot.refund&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&partner_trans_id=out_trade_no_20190904_160450&partner_refund_id=partner_refund_id_20190904_160211&refund_amount=0.01&refund_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=45f7af56d72cae12f1c74868873c47b8


#Response

Synchronous sample

Business is accepted and processed normally:

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner_trans_id">out_trade_no_20190904_160450</param>
        <param name="partner">208xxxxxxxxx8155</param>
        <param name="service">alipay.acquire.overseas.spot.refund</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">b0d81ca4ecc6f14d149626233c727ef2</param>
        <param name="refund_amount">0.01</param>
        <param name="currency">USD</param>
        <param name="refund_reason">The buyer wants to initiate a refund.</param>
        <param name="notify_url">https://www.mikascoffee.com/notify</param>
        <param name="sign_type">MD5</param>
        <param name="partner_refund_id">partner_refund_id_20190904_160211</param>
    </request>
    <response>
    <alipay>
        <alipay_trans_id>201xxxxxxxxxxxxxxxxxxxxx3346</alipay_trans_id>
        <currency>USD</currency>
        <exchange_rate>7.18041000</exchange_rate>
        <partner_refund_id>partner_refund_id_20190904_160211</partner_refund_id>
        <partner_trans_id>out_trade_no_20190904_160450</partner_trans_id>
        <refund_amount>0.01</refund_amount>
        <refund_amount_cny>0.07</refund_amount_cny>
        <result_code>SUCCESS</result_code>
    </alipay>
    </response>
    <sign>fde68b2f3b82a599fd33eb84e250a220</sign>
    <sign_type>MD5</sign_type>
</alipay>


Request fails or the data accessed are wrong:

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


Asynchronous sample

copy
https://www.mikascoffee.com/notify
trans_refund_fee=0.01
notify_type=refund_status_sync
return_amount=0.01
notify_time=2019-09-11 19:24:30
out_trade_no=out_trade_no_20190904_163949
refund_status=REFUND_SUCCESS
sign=$$
out_return_no=partner_refund_id_20190904_160211
currency=USD
sign_type=MD5
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx3785


Note:

For more information about asynchronous notification, synchronous notification, and digital signature, see API specification.