alipay.intl.acquiring.common.refund

2022-01-21 09:18

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	Money	/	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	ResultInfo	/	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	Money	/	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