alipay.acquire.refund.query

2025-01-06 01:16

Call this interface to query the refund status.

Request

Request parameters

Parameter Description

Basic parameter

service

String Required

Interface name

Example:alipay.acquire.refund.query

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********364

_input_charset

String Required

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

Example:UTF-8

sign_type

String Required

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

Example:MD5

sign

String Required

The signature value

Example:b7baf9af3c91b37bef4261849aa76281

Business parameter

out_trade_no

String(64) Required

The unique ID that is assigned by the merchant to identify a transaction

Example:1234567890

out_return_no

String(128) Required

The unique ID of the refund that is sent in the original refund request

Example:0987654321

Response

Synchronous response

Parameter Description

Basic parameter

is_success

String Required

This parameter indicates whether the request succeeds, with a value of T for success and F for failure. A successful request does not mean the business is accepted and processed successfully.

Example:T

sign_type

String Required

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

Example:MD5

sign

String Required

The signature value

Example:59c7275cf3c82f038b7c0076f9888926

error

String

Error code that is returned when the request is failed. This describes the request failure reason. This parameter is not returned if the request succeeds. For more information, see the Access errors section in this document.

Example:ILLEGAL_SIGN

Business parameter

response_code

String(64) Required

The result of the inquiry request. Possible values are:

SUCCESS: The request is successful.
ACCESS_FORBIDDEN: You are not permitted to use this service.
NOT_FOUND: No refund is found.
QUERY_FAILED: The inquiry is failed.
TRADE_NOT_EXIST: The transaction does not exist.

Example:SUCCESS

refund_result_code

String(64)

The refund status. Possible values are:

SUCCESS: The refund is successful.
FAILED: The refund is failed.
CANCELED: The refund is canceled.
PROCESSING: The refund is being processed in Alipay system.

Example:SUCCESS

refund_error_code

String(64)

Error code returned for the refund. Only returned when the refund status is FAILED or PROCESSING. For more information, see the Business errors section in this document.

Example:MERCHANT_BALANCE_NOT_ENOUGH

out_return_no

String(128)

The unique ID of the refund that is sent in the original refund request

Example:0123456789

out_trade_no

String(64)

The unique ID that is assigned by the merchant to identify a transaction

Example:123123123

trade_no

String(64)

The serial number assigned by Alipay to identify a trade in the Alipay system, with a length in the range 16 - 64 bits.

Example:2020030322001272141426888888

gmt_create

Date

The time when the refund request is accepted. Format: yyyy-MM-dd HH24:mm:ss. Use GMT+8.

Example:2020-12-25 15:45:57

gmt_finished

Date

The time when the refund succeeds. Format: yyyy-MM-dd HH24:mm:ss. Use GMT+8.

Example:2020-12-25 15:45:58

refund_rmb_amount

Money

The refund amount in CNY. The value is in the range of 0.01 - 1000000.00, with at most 2 digits after the decimal point.

Example:12.56

refund_foreign_amount

Money

The amount to refund in the settlement currency. The value is in the range of 0.01 – 1000000.00, with at most 2 digits after the decimal point.

Example:123.34

currency

String

The settlement currency. The three-character ISO-4217 currency code. For more information, see Supported Currencies.

Example:USD

forex_rate

String

The exchange rate that is used for the refund, which is the same with the rate used for the original payment. Can have up to eight digits after the decimal point.

Example:7.09610000

refund_royaltys

String(6000)

Detailed list of the split refunds. Use JSON format. See refund_royaltys for details.

Example:[{"amount":"0.20","transOut":"2088102149952810"}]

refund_royaltys

Parameter Description

amount

Money Required

Amount of a split refund. Unit: CNY.

The value is in the range of 0.01 – 1000000.00, with at most 2 digits after the decimal point.

Example:0.34

transOut

String(32) Required

The merchant's domestic account in Alipay system where the funds are transferred out.

Example:2088002007018777

Error codes

Access errors

Returned result	Description
ILLEGAL_SIGN	Illegal signature
ILLEGAL_DYN_MD5_KEY	Dynamic key information is incorrect.
ILLEGAL_ENCRYPT	Encryption is incorrect.
ILLEGAL_ARGUMENT	Parameter is incorrect.
ILLEGAL_SERVICE	Service parameter is incorrect.
ILLEGAL_USER	User ID is incorrect.
ILLEGAL_PARTNER	Partner ID is incorrect.
ILLEGAL_EXTERFACE	Interface configuration is incorrect.
ILLEGAL_PARTNER_EXTERFACE	Partner's interface information is incorrect.
ILLEGAL_SECURITY_PROFILE	No matching private key configuration is found.
ILLEGAL_AGENT	Agency ID is incorrect.
ILLEGAL_SIGN_TYPE	The signature type is incorrect.
ILLEGAL_CHARSET	The character set is illegal.
HAS_NO_PRIVILEGE	No right to visit.
INVALID_CHARACTER_SET	The character set is invalid.

Business errors

Error codes returned when the value of refund_result_code is PROCESSING:

Returned result	Description
SYSTEM_ERROR	Alipay system error. Please try again later.
MERCHANT_BALANCE_NOT_ENOUGH	Merchant balance is not enough for the refund.
REFUND_CHARGE_ERROR	Errors exist in the refund fee.
REFUND_FAIL	The refund fails.
SERVICE_REFUSE	The refund is not available during service downtime.
SELLER_BALANCE_NOT_ENOUGH	The balance of seller is not enough.

Error codes returned when the value of refund_result_code is FAILED:

Returned result	Description
SYSTEM_ERROR	Alipay system error. Please try again later.
MERCHANT_BALANCE_NOT_ENOUGH	Merchant balance is not enough for the refund.
TXN_RESULT_ACCOUNT_BALANCE_NOT_ENOUGH	The last refund failed because the merchant balance is not enough.
REFUND_CHARGE_ERROR	Errors exist in the refund fee.
TRADE_SETTLE_ERROR	Settlement error
REFUND_FAIL	The refund fails.
TRADE_STATUS_ERROR	The trade status is illegal.
TRADE_HAS_CLOSE	The trade is closed and cannot be refunded.
SERVICE_REFUSE	The refund is not available during service downtime.
SELLER_BALANCE_NOT_ENOUGH	The balance of seller is not enough.
CURRENCY_NOT_MATCH	The refund currency and the settlement currency do not match.
INVALID_ROUNDED_AMOUNT	The refund with this amount might have violated the rule that the calculated amount of both CNY and foreign currency must be fully or not fully refunded at the same time. Take a transaction with 0.07 CNY (0.01 USD) as an example. A refund with 0.06 CNY is not to be accepted because 0.01 CNY (0 USD) is left for this transaction.

Samples

Request

https://mapi.alipay.com/gateway.do?out_trade_no=00220170124b4df6c6&partner=2088xxxxxxxx6931&service=alipay.acquire.refund.query&_input_charset=UTF-8&out_return_no=00220170124b4df6c6r&sign=51f9207497c4d2fc59c5912e7982d2d2&sign_type=MD5

Response

The request fails:

copy
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_PARTNER_EXTERFACE</error>
</alipay>

The request succeeds but no refund result is found:

copy
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="out_trade_no">202005148394958330292_02</param>
        <param name="partner">2088xxxxxx6931</param>
        <param name="service">alipay.acquire.refund.query</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">c97372146992e9099401c36223d88054</param>
        <param name="out_return_no">2020051484990500595995_1</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <response_code>NOT_FOUND</response_code>
        </alipay>
    </response>
    <sign>b77f097d603ef6c8ae041e159c16086d</sign>
    <sign_type>MD5</sign_type>
</alipay>

The refund fails:

copy
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="out_trade_no">00220170124b4df6c6</param>
        <param name="partner">2088xxxxxxxx6931</param>
        <param name="service">alipay.acquire.refund.query</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">a4c9ffdefbfd93dd7a3bd057755c05f9</param>
        <param name="out_return_no">00220170124b4df6c6r</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <gmt_create>2017-02-05 01:25:48</gmt_create>
            <out_return_no>00220170124b4df6c6r</out_return_no>
            <out_trade_no>00220170124b4df6c6</out_trade_no>
            <refund_error_code>SYSTEM_ERROR</refund_error_code>
            <refund_foreign_amount>0.01</refund_foreign_amount>
            <refund_result_code>FAILED</refund_result_code>
            <refund_rmb_amount>0.01</refund_rmb_amount>
            <response_code>SUCCESS</response_code>
            <trade_no>2017012421001003270252363402</trade_no>
        </alipay>
    </response>
    <sign>b46585009f4098a86b289fe48a88be84</sign>
    <sign_type>MD5</sign_type>
</alipay>

The refund succeeds:

copy
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="out_trade_no">3941721012815833</param>
        <param name="partner">2088xxxxxxxx6931</param>
        <param name="service">alipay.acquire.refund.query</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">df9f58640736d49f7993e7eb6eaae5f6</param>
        <param name="out_return_no">YNTK20150624002</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <currency>USD</currency>
            <forex_rate>6.22945000</forex_rate>
            <gmt_create>2015-06-24 21:43:56</gmt_create>
            <gmt_finished>2015-06-24 21:43:57</gmt_finished>
            <out_return_no>YNTK20150624002</out_return_no>
            <out_trade_no>3941721012815833</out_trade_no>
            <refund_foreign_amount>0.10</refund_foreign_amount>
            <refund_result_code>SUCCESS</refund_result_code>
            <refund_rmb_amount>0.62</refund_rmb_amount>
            <response_code>SUCCESS</response_code>
            <trade_no>2015062421001003430021738264</trade_no>
        </alipay>
    </response>
    <sign>d4ca93db8660180a61b828b3e0604d2c</sign>
    <sign_type>MD5</sign_type>
</alipay>

The refund succeeds (spilt refunds exist):

copy
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="out_trade_no">202005148394958330292_02</param>
        <param name="partner">2088xxxxxxxx6931</param>
        <param name="service">alipay.acquire.refund.query</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">4d3671ab713adb24c0ae81e5970c5474</param>
        <param name="out_return_no">2020051484990500595995</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <currency>USD</currency>
            <forex_rate>7.14389000</forex_rate>
            <gmt_create>2020-05-14 13:25:08</gmt_create>
            <gmt_finished>2020-05-14 13:25:10</gmt_finished>
            <out_return_no>2020051484990500595995</out_return_no>
            <out_trade_no>202005148394958330292_02</out_trade_no>
            <refund_foreign_amount>4.20</refund_foreign_amount>
            <refund_result_code>SUCCESS</refund_result_code>
            <refund_rmb_amount>30.00</refund_rmb_amount>
            <refund_royaltys>[{"amount":"20.00","transOut":"2088801766902304"}]</refund_royaltys>
            <response_code>SUCCESS</response_code>
            <trade_no>2020051422001395451410092226</trade_no>
        </alipay>
    </response>
    <sign>b5b94e230ee244d031baeb225a749871</sign>
    <sign_type>MD5</sign_type>
</alipay>