Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

alipay.trade.refund

Call the alipay.trade.refund interface to issue a full or partial refund.

Request

Service address

Environment

HTTPS request URL

production environment

https://globalopenapi.alipay.com/gateway.do

Test environment

https://openapi.alipaydev.com/gateway.do

Request parameters

Parameter

Description

Basic parameter

app_id

String (32) Required

The unique ID that is assigned by Alipay to identify an application.

Example: 2014072300007148

method

String (128) Required

Interface name

Example: alipay.fund.auth.order.freeze

format

String (40)

Only JSON is supported.

Example: JSON

charset

String (10) Required

The charset with which the request data is encoded. GBK and UTF-8 are supported.

Example: UTF-8

sign_type

String (10) Required

Signature type. RSA and RSA2 are supported. Use uppercase.

Example: RSA2

sign

String (344) Required

Signature value

timestamp

String (19) Required

The time when the merchant server sends the request. The format is yyyy-mm-dd hh:mm:ss.

Example: 2020-07-24 03:07:50

version

String (3) Required

The API version. The value is fixed as 1.0.

Example: 1.0

notify_url

String (256)

The URL for receiving asynchronous notifications after the pre-auth is completed.

Example: http://api.test.alipay.net/atinterface/receive_notify.htm

app_auth_token

String (40)

To query authorization information. 

Example: 201510BBaabdb44d8fd04607abf8d5931ec75D84

Note: After a merchant authorizes an ISV to use certain APIs, Alipay will assign an app_auth_token to the ISV. The ISV can use this interface to query the authorization information such as the authorizer and authorized APIs corresponding to the app_auth_token. For more details, see Overview of the app authorization (in Mandarin).

biz_content

String Required

Collection of request parameters. The maximum length is not limited. Except for common parameters, all other request parameters must be passed in to this parameter.

Business parameter

out_trade_no

String (64) Required

The unique transaction ID that is assigned by the merchant.

Example: 8077735255938023

trade_no

String (64) Required

The serial number assigned by Alipay to identify a trade in Alipay system. This parameter is required when out_trade_no is not provided.

Example: 2018080121001004589756745

out_request_no

String (64) Required

The unique refund request ID that is assigned by the merchant. This parameter is also required for partial refunds.

Example: ABC123AS

refund_amount

Price (11) Required

Refund amount

Example: 150.00

refund_reason

String (64)

Reason for refund

refund_currency

String (8) Required

The refund currency. The currency is the transaction currency used for the payment.

Example: USD

operator_id

String (32)

The operator ID of the merchant.

store_id

String (32)

The store ID of the merchant.

terminal_id

String (32)

The terminal ID of the merchant.

Response

Synchronous response

Parameter

Description

Basic parameter

code

String (16) Required

The gateway return code, which indicates whether the request is accepted by Alipay gateway.

Example:  10000

msg

String (32) Required

Description of the gateway return code

Example: Business Failed

sub_code

String (16)

Processing result of the request

Example: isv.invalid-signature

sub_msg

String (64)

Description of the processing result of the request

sign

String (344) Required

The sign value. See Signature for details.

Business parameter

out_trade_no

String (64) Required

The unique transaction ID that is assigned by the merchant.

Example: 8077735255938023

trade_no

String (64) Required

The serial number assigned by Alipay to identify a trade in the Alipay system. This parameter is required when out_trade_no is not provided.

Example: 2018080121001004589756745

buyer_logon_id

String (100) Required

Buyer's Alipay user login ID

Example: 138****1234

fund_change

String (10) Required

Indicates if the refund leads to any change in the funds. Possible values include:

  • Y: Yes
  • N: No

Example: N

refund_fee

Price (11) Required

Refund amount

Example: 100

gmt_refund_pay

Date (32) Required

The time when the refund is paid.

Example: 2018-01-12 21:10:10

store_name

String (64)

The store name where the payment is made.

Example: Test store

buyer_user_id

String (32) Required

Buyer's Alipay user ID

Example: 2088102000275885

refund_currency

String (8)

Refund currency

Example: USD

Error codes

 Error Code

Description

ACQ.SYSTEM_ERROR

System error

ACQ.INVALID_PARAMETER

Incorrect parameter

ACQ.SELLER_BALANCE_NOT_ENOUGH

The seller's account balance was insufficient and the refund failed.

ACQ.REFUND_AMT_NOT_EQUAL_TOTAL

The refund amount exceeds the total amount.

ACQ.REASON_TRADE_BEEN_FREEZEN

The transaction is frozen for the refund transaction.

ACQ.TRADE_NOT_EXIST

The transaction does not exist.

ACQ.TRADE_HAS_FINISHED

The transaction is completed.

ACQ.TRADE_STATUS_ERROR

The trade status is illegal.

ACQ.DISCORDANT_REPEAT_REQUEST

Inconsistent request

ACQ.REASON_TRADE_REFUND_FEE_ERR

The refund amount is incorrect.

ACQ.TRADE_NOT_ALLOW_REFUND

The refund is not allowed.

ACQ.REFUND_FEE_ERROR

Errors exist in the refund fee.