alipay.intl.acquiring.common.refund_2.0.2

2021-02-26 07:48

The merchant and partner can use this interface to refund an existing payment. A refund can be partial and a transaction can have multiple refunds as long as the total refund amount is no greater than 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, use the same merchantRefundId.

Request

Service address

Environment	URL
Production	https://open-na.alipay.com/api/alipay/intl/acquiring/common/grefund.htm

Request head

Parameter	Name	Type	Length	Required	Description	Sample
version	API version	String	8	Y	The API version	2.0.2
function	API name	String	128	Y	The API name	alipay.intl.acquiring.common.refund
clientId	Client ID	String	32	Y	The unique ID assigned by Alipay to identify a client that makes API calls	211xxxxxxxxxxxxxxx044
reqTime	Request time	Date time	/	Y	Date time with timezone, see RFC 3339 Section 5.6 for details.	2001-07-04T12:08:56+05:30
reqMsgId	Request message ID	String	64	Y	The unique ID assigned by client to identify a request message	1234567asdfasdf1123fda
reserve	Reserved parameter	String	256	N	Key/Value formatted parameter for future use	{key/value}
signType	Sign type	String	64	N	The signature type	RSA2

Request body

Parameter	Name	Type	Length	Required	Description	Sample
partnerId	Partner ID	String	32	Y	The unique partner ID assigned by Alipay. This parameter identifies the settlement target that Alipay settles to.	211xxxxxxxxxxxxxxxx512
acquirementId	Alipay transaction ID	String	64	Y	The unique Alipay transaction ID.	2015xxxxxxxxxxxxxxxxxxxxx678
merchantRefundId	Merchant refund ID	String	64	Y	The unique refund ID assigned by the merchant.	Merchant_Refund_Id_93xxx
refundAmount	Refund amount	Money	/	Y	The refund amount in the pricing currency. The value can not be greater than the original order amount. `refundAmount` must 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). Note: This parameter is required when `resultInfo` or `reultCode` is `SUCCESS`. See Money for details.	{"value":"10000", "currency":"USD" }
refundReason	Refund reason	String	256	N	The refund reason that is shown in the buyer's transaction details. See Money for details.	Refund per customer request.
isSync	isSync	Boolean	5	N	This parameter specifies if the refund is synchronous. The value can be: `false` (by default): asynchronous `true`: synchronous	true

Response

Response head

Parameter	Name	Type	Length	Required	Description	Sample
version	API version	String	8	Y	The API version	2.0.2
function	API name	String	128	Y	The API name	alipay.intl.acquiring.common.refund
clientId	Client ID	String	32	Y	The unique ID assigned by Alipay to identify a client that makes API calls	211xxxxxxxxxxxxxxx044
respTime	Response time	Date time	/	Y	Date time with timezone, see RFC 3339 Section 5.6 for details.	2001-07-04T12:08:56+05:30
reqMsgId	Request message ID	String	64	Y	The unique ID assigned by client to identify a request message	1234567asdfasdf1123fda
reserve	Reserved parameter	String	256	N	Key/Value formatted parameter for future use	{key/value}

Response body

Parameter	Name	Type	Length	Required	Description	Sample
resultInfo	Result info	ResultInfo	/	Y	See resultInfo for details.	{ "resultStatus": "S", "resultCodeId": "00000000", "resultCode":"SUCCESS", "resultMsg": "result message" }
merchantRefundId	Merchant refund ID	String	64	C	The unique refund ID assigned by the merchant. Note: This parameter is required when `reultCode` is `SUCCESS`.	Merchant_Refund_Id_93xxx
acquirementId	Alipay transaction ID	String	64	C	The unique Alipay transaction ID. Note: This parameter is required when `reultCode` is `SUCCESS`.	2015xxxxxxxxxxxxxxxxxxxxx678
refundId	Refund ID	String	64	N	The unique refund ID assigned by Alipay.	2015xxxxxxxxxxxxxxxxxxxxx012
refundAmount	Refund amount	Money	/	C	The refund amount in the pricing currency. The value can not be greater than the original order amount. `refundAmount` must 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). Note: This parameter is required when `reultCode` is `SUCCESS`. See Money for details.	{"value":"10000", "currency":"USD" }
refundActualAmount	The actual refund amount that the buyer receives.	Money	/	C	This parameter can be in a different currency with `refundAmount`. Note: This parameter is required when `reultCode` is `SUCCESS`, or `refundActualCurrencyDifferentWithRefundCurrency` is `true`. See Money for details.	{"currency":"CNY", "value":"1481"}
conversionRate	Conversion rate	ExchangeRate	/	C	The exchage rate between orderAmount and payAmount. Note: This parameter is required when `reultCode` is `SUCCESS`, or `refundActualCurrencyDifferentWithRefundCurrency` is `true`. See conversionRate for details.	{ "baseCurrency":"USD", "exchangeCurrency":"CNY", "rate":"6.9123" }
refundTime	Refund time	Date time	/	C	Date time with timezone, see RFC 3339 Section 5.6 for details. Note: This parameter is required when `reultCode` is `SUCCESS`.	2001-07-04T12:08:56+05:30

Sub-parameters

resultInfo

			Parameter	Name	Type	Length	Required	Description	Sample
resultStatus	Result status	String	2	Y	The request status can be:	`S`: success	`F`: failure	`U`: unknown	S
resultCodeId	Result ID	String	8	Y	An 8-digit code that is used to identify a result. When `resultStatus` is `S`, the value must be 00000000. When `resultStatus` is `F` or `U`, the value can be other result ID specified by the interface.	00000000
resultCode	Result code	String	64	Y	The result code	SUCCESS
resultMsg	Result message	String	256	N	When `resultCode` is `S`, this value can be empty. When `resultCode` is `F` or `U`, the error description is required.	success

conversionRate

Parameter	Name	Type	Length	Required	Description	Sample
baseCurrency	Base currency	String	3	Y	The base currency	USD
exchangeCurrency	Exchange currency	String	3	Y	The exchange currency	CNY
rate	Rate	String	16	Y	The exchange rate of `baseCurrency` against `exchangeCurrency`	6.9123

Money

Parameter	Name	Type	Length	Required	Description	Sample
currency	Currency	String	3	Y	The 3-letter currency code. See supported currencies for details.	USD
value	value	Number	16	Y	The amount. This value must be provided in the smallest common currency unit. For example, to create a charge for $1.00, you would set `orderAmount` value=100 (100 cents).	239

Result code

Functional logic result code

ResultID	ResultCode	ResultStatus	Remarks
00000025	REPEAT_REQ_INCONSISTENT	F	Repeated or inconsistent requests
12002005	USER_NOT_EXIST	F	The user does not exist.
12002006	USER_STATUS_ABNORMAL	F	Abnormal user status
12005001	CURRENCY_NOT_SUPPORT	F	The transaction currency is not supported. See supported currencies for details.
12005004	ORDER_NOT_EXIST	F	The transaction does not exist.
23005302	REFUND_AMOUNT_EXCEED	F	The refund amount exceeds the limit.
12005014	REFUND_TIME_EXCEED_LIMIT	F	The refund time exceeds the limit.
12005003	ORDER_STATUS_INVALID	F	The transaction status is invalid.
12005134	SIGN_TYPE_INVALID	F	The signature type is invalid.
12005135	SIGN_TYPE_NOT_SUPPORT	F	The signature type is not supported.

Basic result code

ResultID	ResultCode	ResultStatus	Remarks
00000000	SUCCESS	S	Success
00000019	PROCESS_FAIL	F	General business failure
00000901	UNKNOWN_EXCEPTION	U	API failed because of unknown reasons
00000004	PARAM_ILLEGAL	F	The parameter is incorrect.
00000007	INVALID_SIGNATURE	F	The signature is invalid.
00000008	KEY_NO_FOUND	F	The key is not found.
00000013	NO_INTERFACE_DEF	F	The API is undefined.
00000014	API_IS_INVALID	F	The API is invalid or nonactivated.
00000016	OAUTH_FAILED	F	The oAuth authentication failed.
00000021	ACCESS_DENIED	F	Access denied
12014152	CLIENT_FORBIDDEN_ACCESS_API	F	The Client is not authorized to use this API.
12014155	UNKNOWN_CLIENT	F	Unknown client
12014156	INVALID_CLIENT_STATUS	F	Invalid client status
00000024	REQUEST_TRAFFIC_EXCEED_LIMIT	F	The request traffic exceeds the limit.

Sample

Sample request

copy

{ 
    "request":{ 
        "head":{ 
            "version":"2.0.2", 
            "function":"alipay.intl.acquiring.common.refund", 
            "clientId":"211xxxxxxxxxxxxxxx044", 
            "reqTime":"2001-07-04T12:08:56+05:30", 
            "reqMsgId":"1234567asdfasdf1123fda", 
            "reserve":"{}",
            "signType":"RSA2"
        }, 
        "body":{ 
            "partnerId":"218820000000000000023", 
            "acquirementId":"2015xxxxxxxxxxxxxxxxxxxxx678", 
            "merchantRefundId":"Merchant_Refund_Id_93xxx", 
            "refundAmount":{ 
                "currency":"USD", 
                "value":"239" 
            }, 
            "refundReason":"refund per customer request", 
            "isSync":“true”
        } 
    }, 
    "signature":"signature string" 
}

Sample response

copy

{ 
    "response":{ 
        "head":{ 
            "version":"2.0.2", 
            "function":"alipay.intl.acquiring.common.refund", 
            "clientId":"211xxxxxxxxxxxxxxx044", 
            "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_93xxx", 
            "acquirementId":"2015xxxxxxxxxxxxxxxxxxxxx678", 
            "refundId":"2015xxxxxxxxxxxxxxxxxxxxx012", 
            "refundAmount":{ 
                "currency":"USD", 
                "value":"239" 
            }, 
            "refundTime":"2001-07-04T12:08:56+05:30" 
        } 
    }, 
    "signature":"signature string" 
}