alipay.intl.acquiring.common.refund_2.0.2
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): asynchronoustrue: 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
#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"
}