alipay.intl.acquiring.common.refund

2022-01-21 09:17

The merchant uses this interface to refund an existing payment.

The partner uses this interface to refund an existing payment. 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.

To retry a refund, in case of timeout or the returned resultStatus is U, the same merchantRefundId should be used.

Request

Request Parameter

Header

No	Name	Description	Type	Length	Required	Remarks	Sample
1	version	API version	string	8	ME	As per the respective API reference.	2.0.0
2	function	API interface	string	128	ME	According to specifications defined by each business domain.	alipay.intl.function
3	clientId	Client ID	string	32	ME	Provided by Alipay, used to identify partner and application system.	211020000000000000044
4	reqTime	Request time	datetime	/	M	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	ME	Each request will be assigned with a unique ID (uuid). The reqMsgId identifies a unique system request, it is not used to identify a unique business request.	1234567asdfasdf1123fda
6	reserve	Reserved for future implementation	string	256	O	Key/Value	{}

Body

No	Name	Description	Type	Length	Required	Remarks	Sample
1	merchantId	Merchant ID, which identifies the settlement target that Alipay would settle to.	string	64	M		218820000000000000023
2	acquirementId	Unique Alipay transaction ID	string	64	ME	Alipay transaction ID, identifying the transaction to be refunded.	2015032412007101547201355678
3	merchantRefundId	Unique merchant refund ID	string	64	ME		Merchant_Refund_Id_93045
4	refundAmount	Refund amount	Money	/	M	The amount to be refunded. It should not be greater than the 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 as100 (100 cents).	{"value":"10000", "currency":"USD" }
5	refundReason	The refund reason, which is shown in the buyer's transaction details.	string	512	O		refund per customer request
6	extendInfo	Reserved for extended information	string	2048	O	Key/Value	{}

Request Sample

copy
{
    "request":{
        "head":{
            "version":"2.0.0",
            "function":"alipay.intl.acquiring.common.refund",
            "clientId":"211020000000000000044",
            "reqTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"1234567asdfasdf1123fda",
            "reserve":"{}"
        },
        "body":{
            "merchantId":"218820000000000000023",
            "acquirementId":"2015032412007101547201355678",
            "merchantRefundId":"Merchant_Refund_Id_93045",
            "refundAmount":{
                "currency":"USD",
                "value":"239"
            },
            "refundReason":"refund per customer request",
            "extendInfo":"{}"
        }
    },
    "signature":"signature string"
}

Response

Response Parameter

Header

No	Name	Description	Type	Length	Required	Remarks	Sample
1	version	API version	string	8	ME	As per the respective API reference.	2.0.0
2	function	API interface	string	128	ME	According to specifications defined by each business domain.	alipay.intl.function
3	clientId	Client ID	string	32	ME	Provided by Alipay, used to identify partner and application system.	211020000000000000044
4	respTime	Response time	datetime	/	M	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	ME	Each request will be assigned with a unique ID (uuid).	1234567asdfasdf1123fda
6	reserve	Reserved for future implementation	string	256	O	Key/Value	{}

Body

No	Name	Description	Type	Length	Required	Remarks	Sample
1	resultInfo	Result information	ResultInfo	/	M		{ "resultStatus": "S", "resultCodeId": "00000000", "resultCode":"SUCCESS", "resultMsg": "result message" }
2	merchantRefundId	Unique merchant refund ID. Note: This field is required when resultInfo.resultCode is `SUCCESS`.	string	64	CE	Merchant refund ID, which is generated by the caller, copied from the request.	Refund_Request_Id_93045
3	acquirementId	Unique Alipay transaction ID. Note: This field is required when resultInfo.resultCode is `SUCCESS`.	string	64	CE	Alipay transaction ID, copied from the request.	2015032412007101547201355678
4	refundId	Unique Alipay refund ID	string	64	O		2015032412007101547201359012
5	refundAmount	Refund amount. Note: This field is required when resultInfo.resultCode is `SUCCESS`.	Money	/	C	The refund amount should be exactly same as refundAmount passed in the request.	{"value":"10000", "currency":"USD" }
6	refundTime	Refund time. Note: This field is required when resultInfo.resultCode is `SUCCESS`.	datetime	/	C	DateTime with timezone, which follows the ISO-8601 standard. Refer to: RFC 3339 Section 5.6	2001-07-04T12:08:56+05:30
7	extendInfo	Reserved for extended information	string	2048	O		{}

Response Sample

copy
{
    "response":{
        "head":{
            "version":"2.0.0",
            "function":"alipay.intl.acquiring.common.refund",
            "clientId":"211020000000000000044",
            "respTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"1234567asdfasdf1123fda",
            "reserve":"{}"
        },
        "body":{
            "resultInfo":{
                "resultStatus":"S",
                "resultCodeId":"00000000",
                "resultCode":"SUCCESS",
                "resultMsg":"success"
            },
            "merchantRefundId":"Merchant_Refund_Id_93045",
            "acquirementId":"2015032412007101547201355678",
            "refundId":"2015032412007101547201359012",
            "refundAmount":{
                "currency":"USD",
                "value":"239"
            },
            "refundTime":"2001-07-04T12:08:56+05:30",
            "extendInfo":"{}"
        }
    },
    "signature":"signature string"
}

Result codes

Functional Logic result codes

No	ResultCodeId	ResultCode	ResultStatus	Remarks
1	00000025	REPEAT_REQ_INCONSISTENT	F	Repeated submit, and requests are inconsistent.
2	12002005	USER_NOT_EXIST	F	The user does not exist.
3	12002006	USER_STATUS_ABNORMAL	F	The user status is not normal.
4	12005001	CURRENCY_NOT_SUPPORT	F	Transaction currency is invalid.
5	12005004	ORDER_NOT_EXIST	F	The order does not exist.
6	23005302	REFUND_AMOUNT_EXCEED	F	The refund amount exceeds the limit.
7	12005014	REFUND_TIME_EXCEED_LIMIT	F	Refund time exceeds the limit.
8	12005003	ORDER_STATUS_INVALID	F	Order status is invalid.

Basic result codes

The following global result codes might be returned for all APIs.

No	ResultCodeId	ResultCode	ResultStatus	Remarks
1	00000000	SUCCESS	S	Success
2	00000019	PROCESS_FAIL	F	General business failure. No retry.
3	00000901	UNKNOWN_EXCEPTION	U	API failed due to unknown reasons.
4	00000004	PARAM_ILLEGAL	F	Illegal parameters. For example, non-numeric input, invalid date.
5	00000007	INVALID_SIGNATURE	F	The signature is invalid.
6	00000008	KEY_NO_FOUND	F	The key is not found.
7	00000013	NO_INTERFACE_DEF	F	API is not defined.
8	00000014	API_IS_INVALID	F	API is invalid or not active.
9	00000016	OAUTH_FAILED	F	oAuth authentication failed.
10	00000021	ACCESS_DENIED	F	Access denied.
11	12014152	CLIENT_FORBIDDEN_ACCESS_API	F	The client is not authorized to use this API.
12	12014155	UNKNOWN_CLIENT	F	Unknown client
13	12014156	INVALID_CLIENT_STATUS	F	Invalid client status
14	00000024	REQUEST_TRAFFIC_EXCEED_LIMIT	F	Request traffic exceeds the limit.