AlipayHKAlipayHKDOCS

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

https://api-sea-global.alipayplus.com/gateway.do

Request parameters

Parameter

Description

Basic parameter

service

String Required

Interface name 

Example:alipay.acquire.overseas.spot.refund

sign

String Required

Sign value

Example:c8il4epm90wyn768fijgqhy8tay37gqa

sign_type
String Required

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

Example:RSA2

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 or 2160. 

Example:2160*********662

_input_charset

String

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

Example:UTF-8

Operation parameter

partner_trans_id

String(64)

Required

The original partner transaction ID given in the payment request

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. Only HKD is supported.

Example:HKD

refund_reson

String(128)

The reason of refund 

Example:Refund the good

is_sync

String(1)

Required

Indicates that the refund request is processed synchronously with a value of Y.

Example:Y

Note:

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

Response

Synchronous response parameters

Parameters accepted by Alipay gateway:

Parameter

Description

is_success

String(1) Required

Indicates 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 and RSA2 are supported. Use uppercase. 

Example:RSA2

sign

String(32) Required

Sign value

Example:59c7275cf3c82f038b7c0076f9888926

result_code

String(32) Required

Processing result of the request, with a value of SUCCESS to indicate the process is successful, FAIL to indicate the process is failed, or UNKNOWN to indicate an unknown result. 

Example:SUCCESS

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

partner_trans_id

String(64) Required

Equal to the partner_trans_id field given in the request

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. Only HKD is supported.. 

Example:HKD

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 and RSA2 are supported. Use uppercase. 

Example:RSA2

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

Error codes

Error code

Description

SYSTEM_ERROR

Alipay system is not available. Try again later.

ILLEGAL_SIGN

Illegal signature. Use the legal signature and try again.

INVALID_PARAMETER

Parameter value error. Check each request parameter according to the API specification.

ILLEGAL_ARGUMENT

Parameter name error. Check each request parameter according to the API specification. Contact Alipay technical support if this error persists.

ILLEGAL_PARTNER

Incorrect partner ID. 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. Ensure that the service parameter 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. Contact Alipay technical support.

ILLEGAL_SIGN_TYPE

Illegal sign type. 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.  Contact Alipay technical support.

REASON_TRADE_BEEN_FREEZEN

Corresponding trade has been frozen due to security issues. Contact Alipay technical support.

TRADE_NOT_EXIST

Cannot find the corresponding trade according to the value of partner_trans_id.

Action:

  1. Ensure that 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. Make sure 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 the total refund amount is more than the original trade amount, which cannot be processed by Alipay. The merchant needs to check if the returned amount is correct.

REQUEST_AMOUNT_EXCEED

The same with the REFUND_AMT_RESTRICTION error code.

The merchant needs to check if the return amount is correct.

RETURN_AMOUNT_EXCEED

The same with the REFUND_AMT_RESTRICTION error code. The merchant needs to check if the returned amount is correct.

REFUND_CHARGE_ERROR

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

Samples

Request

Synchronous refund request:

https://intlmapi.alipay.com/gateway.do?_input_charset=UTF-8&service=alipay.acquire.overseas.spot.refund&sign_type=RSA2&partner=2160xxxxxxxx5500&currency=HKD&partner_trans_id=partner_trans_id_2019010_000036&partner_refund_id=partner_trans_id_2019010_003252&refund_amount=0.01&refund_reson=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E9%80%80%E6%AC%BE&is_sync=Y&sign=15c29ae88de4cbaa7b90d219cf3467b3

Response

Synchronous response

Request succeeds, and the business processing succeeds:

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner_trans_id">partner_trans_id_2019010_000035</param>
        <param name="partner">2160021966645500</param>
        <param name="service">alipay.acquire.overseas.spot.refund</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">3798890cf14f36bceb764eb3a3a44ab7</param>
        <param name="refund_amount">0.01</param>
        <param name="currency">HKD</param>
        <param name="notify_url">https://www.mikascoffee.com/notify</param>
        <param name="is_sync">Y</param>
        <param name="sign_type">RSA2</param>
        <param name="partner_refund_id">partner_refund_id_20190904_160211</param>
    </request>
    <response>
        <alipay>
            <alipay_trans_id>2019091022001414270571637760</alipay_trans_id>
            <currency>HKD</currency>
            <partner_refund_id>partner_refund_id_20190904_160211</partner_refund_id>
            <partner_trans_id>partner_trans_id_2019010_000035</partner_trans_id>
            <refund_amount>0.01</refund_amount>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    <sign>acaa2e792c7473b9a20639b515c374e9</sign>
    <sign_type>RSA2</sign_type>
</alipay>

Request is failed:

copy
<?xml version="1.0" encoding="UTF-8"?> 
 <alipay> 
   <is_success>F</is_success> 
   <error>ILLEGAL_SIGN</error> 
   <sign>02f6b289c46b8d0c1ea62b4f78637c1a</sign> 
   <sign_type>RSA2</sign_type> 
 </alipay>