alipay.acquire.overseas.spot.refund

2020-10-21 07:00

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

Parameter Description

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:

Parameters rejected by Alipay gateway:

Parameter Description

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.

Parameter Description

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:

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.
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:

Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
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:

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.