Antom, leading provider of tailored payment solutions

alipay.intl.acquiring.common.refund

You can use this interface to initiate a full or partial refund for an existing payment based on the actual business requirements, and updating the corresponding reconciling processes
Note:
  • The refund can be partial and a transaction can have multiple refunds as long as the total refund amount is less than or equal to the original transaction amount.
  • There is a refund window for each transaction. A refund request will be declined if it happens outside of the refund window.
  • AlipayHK only supports synchronous refund: AlipayHK makes the refund in real-time, and returns the result immediately.
  • To retry a refund in case of timeout or the returned 'resultStatus' is 'U', the same 'merchantRefundId' should be used. 

Request parameter

No
Name
Description
Type
Length
Required
Remarks
Sample
1
version
API version
string
8
Y
As per the respective API reference
2.0.0
2
function
API interface
string
128
Y
According to specifications defined by each business domain
alipay.intl.function
3
clientId
Client ID
string
32
Y
Provided by AlipayHK, used to identify partner and application system
4Q5XPV504B0A5302
4
reqTime
Request time
datetime
/
Y
DateTime with timezone, which follows the ISO-8601 standard.
Refer to: RFC 3339 Section 5.6
2001-07-04T12:08:56+05:30
5
reqMsgId
Request message ID
string
64
Y
Each request will be assigned with a unique id (uuid).
The reqMsgId identify an unique system request, it is not used to identity an unique business request.
1234567asdfasdf1123fda
6
reserve
Reserved for future implementation
string
256
N
Key/Value
{}
 

Body

No
Name
Description
Type
Length
Required
Remarks
Sample
1
merchantId
The merchant id, which identifies the settlement target that AlipayHK would settle to.
string 
64
Y
2160400000002012
2
acquirementId
Unique AlipayHK transaction id.
string
64
Y
The AlipayHK transaction id, identifying the transaction to be refunded.
20181211194010800100160960000444183
3
merchantRefundId
Unique merchant refund id.
string
64
Y
Merchant_Refund_Id_121201
4
refundAmount
Refund amount
/
Y
The amount to be refunded. It should not be greater than original order amount.
The refundAmount should be provided in the smallest common currency unit.For example, to create a refund for $1.00, you would set refundAmount.value=100 (100 cents).
{                “currency”:”HKD”,
                “value”:”2000”
}
5
refundReason
The refund reason. Would be shown in the buyer's transaction details.
string
512
N
refund per customer request
6
extendInfo
Reserved for extended info
string
2048
N
Key/Value
{}

Request Sample

{
    “request”:{
       “head”:{
           “version”:”2.0.0”,
           “function”:”alipay.intl.acquiring.common.refund”,
           “clientId”:”4Q5XPV504B0A5302”,
           “reqTime”:”2001-07-04T12:08:56+05:30”,
           “reqMsgId”:”1234567asdfasdf1123fda”,
           “reserve”:”{}”
       },
       “body”:{
           “merchantId”:”2160400000002012”,
           “acquirementId”:”20181211194010800100160960000444183”,
           “merchantRefundId”:”Merchant_Refund_Id_121201”,
           “refundAmount”:{
                “currency”:”HKD”,
                “value”:”2000”
           },
           “refundReason”:”refund per customer request”,
           “extendInfo”:”{}”
       }
   },
    “signature”:”testing_signature”
}

Response parameters

Header

No
Name
Description
Type
Length
Required
Remarks
Sample
1
version
API version
string
8
Y
As per the respective API reference
2.0.0
2
function
API interface
string
128
Y
According to specifications defined by each business domain
alipay.intl.function
3
clientId
Client ID
string
32
Y
Provided by AlipayHK, used to identify partner and application system
4Q5XPV504B0A5302
4
respTime
Response time
datetime
/
Y
DateTime with timezone, which follows the ISO-8601 standard.  
Refer to: RFC 3339 Section 5.6
2018-12-11T21:01:49-08:00
5
reqMsgId
Request message ID
string
64
Y
Each request will be assigned with a unique id (uuid).
1234567asdfasdf1123fda
6
reserve
Reserved for future implementation
string
256
N
Key/Value
{}

Body


No
Name
Description
Type
Length
Required
Remarks
Sample
1
resultInfo
Result info
/
Y
{
                "resultCode": "SUCCESS",
                "resultCodeId": "00000000",
                "resultMsg": "Success",
                "resultStatus": "S"
}
2
merchantRefundId
Unique merchant refund id.
Note:
This parameter is required when resultInfo.resultCode = SUCCESS
string
64
N
The merchant refund Id generated by the caller, copied from the request.
Merchant_Refund_Id_121201
3
acquirementId
Unique AlipayHK transaction id.
Note:
This parameter is required when resultInfo.resultCode = SUCCESS
string
64
N
The AlipayHK transaction id,  copied from the request.
20181211194010800100160960000444183
4
refundId
Unique AlipayHK refund id.
string
64
N
20181211194010801300160960000032979
5
refundAmount
Refund amount.
Note:
This parameter is required when resultInfo.resultCode = SUCCESS
/
N
The refund amount should be exactly same as 'refundAmount'   
passed in the request
{
                "currency": "HKD",
                "value": "2000"
}
6
refundTime
Refund time.
Note:
This parameter is required when resultInfo.resultCode = SUCCESS
datetime
/
N
DateTime with timezone, which follows the ISO-8601 standard.  
Refer to: RFC 3339 Section 5.6
2018-12-11T21:01:47-08:00
7
extendInfo
Reserved for extended info
string
2048
N
{}

Response Sample

{
    "response": {
        "body": {
            "acquirementId": "20181211194010800100160960000444183",
            "refundAmount": {
                "currency": "HKD",
                "value": "2000"
            },
            "refundId": "20181211194010801300160960000032979",
            "refundTime": "2018-12-11T21:01:47-08:00",
            "requestId": "Merchant_Refund_Id_121201",
            "resultInfo": {
                "resultCode": "SUCCESS",
                "resultCodeId": "00000000",
                "resultMsg": "Success",
                "resultStatus": "S"
            }
        },
        "head": {
            "clientId": "4Q5XPV504B0A5302",
            "function": "alipay.intl.acquiring.common.refund",
            "reqMsgId": "1234567asdfasdf1123fda",
            "reserve": "{}",
            "respTime": "2018-12-11T21:01:49-08:00",
            "version": "2.0.0"
        }
    },
    "signature": "test signature"
}

Business Error code

Functional Logic Result Code
No
ResultCodeId
ResultCode
ResultStatus
Remarks
15
00000025
REPEAT_REQ_INCONSISTENT
F
Repeated submit, and requests are inconsistent.
17
12005001
CURRENCY_NOT_SUPPORT
F
Transaction currency is invalid
18
12005004
ORDER_NOT_EXIST
F
Order does not exist
26
23005302
REFUND_AMOUNT_EXCEED
F
Refund amount exceeds
27
12005014
REFUND_TIME_EXCEED_LIMIT
F
Refund time exceed limit