alipay.intl.acquiring.common.refund

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


#Request head

ParameterDescription

version

String(8) Required

API version 

Example:2.0.4

function

String(128) Required

API name

Example:alipay.intl.acquiring.common.refund

clientId

String(32) Required

A unique ID assigned by Alipay to identify a client that makes API calls

Example:385xxxxxxxxx0001

reqTime

Date time(/) Required

Request time. The date time with timezone, see RFC 3339 Section 5.6 for details. 

Example:2001-07-04T12:08:56+05:30

reqMsgId

String(64) Required

Request message ID. A unique ID assigned by the client to identify a request message. This ID identifies a unique system request rather than business request.

Example:123xxxxxxxxxxxxxx3fda

reserve

String(256) Conditional

Reserved parameter. Key-value formatted parameter for future use. This parameter is required for system integrator. If you are a system integrator, you must provide the isvAccesstoken value. 

Example:{"isvAccesstoken":123123123sdfsddsf}

signType

String(64)

Sign type

Example:RSA2


#Request body

ParameterDescription

merchantId

String(64) Required

The unique merchant ID assigned by Alipay. This parameter identifies the settlement target that Alipay settles to.

Example:211xxxxxxxxxxxxxx2999

acquirementId

String(64) Required

The unique Alipay transaction ID that identifies the transaction to be refunded 

Example:201xxxxxxxxxxxxxxxxxxxxx5678

merchantRefundId

String(64) Required

The unique refund ID assigned by the merchant

Example:Merchant_Refund_Id_93xxx

refundAmount

Money(/) Required

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 set refundAmount value=100 (100 cents).

See Money for details. 

Example:{"value":"10000", "currency":"USD" }

refundReason

String(256)

The refund reason that is shown in the buyer's transaction details. 

Example:Refund per customer request

extendInfo

String(2048)

The key-value formatted parameter reserved for future use

Example:{Key/Value}

isSync

Boolean(5)

This parameter specifies whether the refund is processed synchronously. Valid values are:

  • true. The refund is processed synchronously.
  • false. The refund is processed asynchronously.

The default value is true.

Example:true


#Response

#Response head

ParameterDescription

version

String(8) Required

API version

Example:2.0.4

function

String(128) Required

API name

Example:alipay.intl.acquiring.common.refund

clientId

String(32) Required

Client ID. The unique ID assigned by Alipay to identify a client that makes API calls

Example:385xxxxxxxxx0001

respTime

Date time(/) Required

Response time. The date time with timezone, see RFC 3339 Section 5.6 for details. 

Example:2001-07-04T12:08:56+05:30

reqMsgId

String(64) Required

Request message ID. The unique ID assigned by client to identify a request message

Example:123xxxxxxxxxxxxxxx3fda

reserve

String(256)

Reserved parameter. The key-value formatted parameter reserved for future use 

Example:{key/value}

signType

String(8)

Sign type

Example:RSA2


#Response body

ParameterDescription

resultInfo

ResultInfo(/) Required

See resultInfo for details. 

Example:{ "resultStatus": "S", "resultCodeId": "00000000", "resultCode":"SUCCESS", "resultMsg": "result message" }

merchantRefundId

String(64) Conditional

The unique ID assigned by the merchant to identify a refund. Only when the refund succeeds, this field is returned.

Example:Refund_Request_Id_93xxx

acquirementId

String(64) Conditional

The unique transaction ID assigned by Alipay when the transaction succeeds. 

Example:201xxxxxxxxxxxxxxxxxxxxx5678

refundId

String(64) Conditional

The unique refund ID assigned by Alipay. Only when the refund succeeds, this field is returned.

Example:201xxxxxxxxxxxxxxxxxxxxx9012

refundAmount

Money(/) Conditional

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.resultCode is SUCCESS.See Money for details.

Example:{"value":"10000", "currency":"USD" }

refundTime

Date time(/) Conditional

Date time with timezone, see RFC 3339 Section 5.6 for details. Note: This parameter is required when resultInfo.resultCode is SUCCESS. 

Example:2001-07-04T12:08:56+05:30

extendInfo

String(2048)

Extended information. The key-value formatted parameter reserved for future use.

Example:{}


#Sub-parameters

#resultInfo

ParameterDescription

resultStatus

String(2) Required

The request status can be:S: successF: failureU: unknown

Example:S

resultCodeId

String(8) Required

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. 

Example:00000000

resultCode

String(64) Required

The result code

Example:SUCCESS

resultMsg

String(256)

When resultCode is S, this value can be empty. When resultCodeis F or U, the error description is required.

Example:success


#Money

ParameterDescription

currency

String(3) Required

The 3-letter currency code. See Supported currencies for details. 

Example:USD

value

Number(16) Required

The amount. This value must be provided in the smallest common currency unit. For example, to create a charge for $1.00, you set orderAmount value=100 (100 cents). 

Example:239


#Result code

#Functional logic result code

resultCodeId

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.

12006009

MERCHANT_BALANCE_NOT_ENOUGH

F

The merchant balance is not enough.


#Basic result code

resultCodeId

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.

00000021

ACCESS_DENIED

F

Access denied

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.

12003001

MERCHANT_NOT_EXIST

F

The merchant doesn't exist.


#Sample

#Sample request

copy
{
    "request":{
        "head":{
            "version":"2.0.4",
            "function":"alipay.intl.acquiring.common.refund",
            "clientId":"385xxxxxxxxx0001",
            "reqTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"123xxxxxxxxxxxxxxx3fda",
            "signType":"RSA2"
        },
        "body":{
            "merchantId":"211xxxxxxxxxxxxxx2999",
            "acquirementId":"201xxxxxxxxxxxxxxxxxxxxx5678",
            "merchantRefundId":"Merchant_Refund_Id_93045",
            "refundAmount":{
                "currency":"USD",
                "value":"239"
            },
            "refundReason":"refund per customer request",
            "extendInfo":"{}",
            "isSync":true
        }
    },
    "signature":"signature string"
}


#Sample response

copy
{
    "response":{
        "head":{
            "version":"2.0.4",
            "function":"alipay.intl.acquiring.common.refund",
            "clientId":"385xxxxxxxxx0001",
            "respTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"123xxxxxxxxxxxxxxx3fda",
            "reserve":"{}",
            "signType":"RSA2"
        },
        "body":{
            "resultInfo":{
                "resultStatus":"S",
                "resultCodeId":"00000000",
                "resultCode":"SUCCESS",
                "resultMsg":"success"
            },
            "merchantRefundId":"Merchant_Refund_Id_93045",
            "acquirementId":"201xxxxxxxxxxxxxxxxxxxxx5678",
            "refundId":"201xxxxxxxxxxxxxxxxxxxxx9012",
            "refundAmount":{
                "currency":"USD",
                "value":"239"
            },
            "refundTime":"2001-07-04T12:08:56+05:30",
            "extendInfo":"{}"
        }
    },
    "signature":"signature string"
}