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

退款查询接口

调用此接口以查询退款状态。

请求参数

参数

描述

基本参数

service

String 不可空

接口名称

示例：alipay.acquire.refund.query

partner

String(16) 不可空

支付宝分配的用于标识支付宝帐户的合作伙伴ID。

合作伙伴ID是以2088开头的16位纯数字组成。

示例：2088*********364

_input_charset

String 不可空

请求数据的编码集，如GBK、GB2312、UTF-8等。

示例：UTF-8

sign_type

String 不可空

签名类型，支持RSA、RSA2、MD5，请使用大写形式。

示例：MD5

sign

String 不可空

签名值

示例：b7baf9af3c91b37bef4261849aa76281

业务参数

out_trade_no

String(64) 不可空

商户订单号

示例：1234567890

out_return_no

String(128) 不可空

退款流水号

示例：0987654321

返回参数

同步返回参数

参数

描述

基本参数

is_success

String 不可空

表示该次请求是否成功。T表示查询请求成功，F表示查询请求失败。请求成功并不代表退款已被成功接受和处理。

示例：T

sign_type

String 不可空

签名类型，支持RSA、RSA2、MD5，请使用大写形式。

示例：MD5

sign

String 不可空

签名值

示例：59c7275cf3c82f038b7c0076f9888926

error

String

请求失败时返回错误码，用于描述请求失败的原因。具体请参见网关错误码。

示例：ILLEGAL_SIGN

业务参数

response_code

String(64) 不可空

查询请求结果

  • SUCCESS：查询成功
  • ACCESS_FORBIDDEN：无查询权限
  • NOT_FOUND：退款不存在
  • QUERY_FAILED：查询失败
  • TRADE_NOT_EXIST：交易不存在

示例：SUCCESS

refund_result_code

String(64)

退款处理结果

  • SUCCESS：退款成功
  • FAILED：退款失败
  • CANCELED：退款取消
  • PROCESSING：退款待处理

示例：SUCCESS

refund_error_code

String(64)

退款失败时返回的错误码，只有FAILED和PROCESSING状态的退款才会返回，其他状态不返回。具体请参见业务错误码。

示例：MERCHANT_BALANCE_NOT_ENOUGH

out_return_no

String(128)

退款流水号

示例：0123456789

out_trade_no

String(64)

外部订单号

示例：123123123

trade_no

String(64)

支付宝分配的用于识别支付宝交易的序列号，长度在16-64位之间。

示例：2020030322001272141426888888

gmt_create

Date

退款受理时间，格式为yyyy-MM-dd HH24:mm:ss，使用北京时间。

示例：2020-12-25 15:45:57

gmt_finished

Date

退款成功时间，格式为yyyy-MM-dd HH24:mm:ss，使用北京时间。

示例：2020-12-25 15:45:58

refund_rmb_amount

Money

人民币退款金额，此字段的值在0.01-1000000.00的范围内，小数点后最多可保留两位数字。

示例：12.56

refund_foreign_amount

Money

外币退款金额，此字段的值在0.01-1000000.00的范围内，小数点后最多保留两位数。

示例：123.34

currency

String

退款币种，使用三个字母的ISO-4217货币代码来表示。关于币种的更多信息，具体请参见支持币种。

示例：USD

forex_rate

String

用于退款的外币与人民币之间的汇率，与付款时的汇率相同。小数点后最多可保留八位数字。

示例：7.09610000

refund_royaltys

String(6000)

多个退分账明细信息，格式为JSON，具体请参见refund_royaltys参数。

示例：[{"amount":"0.20","transOut":"2088102149952810"}]

refund_royaltys参数

参数

描述

amount

Money 不可空

退分账金额，单位：元。

此字段的值在0.01-1000000.00的范围内，小数点后最多可保留两位数字。

示例：0.34

transOut

String(32) 不可空

支付宝商户的国内账号，资金在此转出。

示例：2088002007018777

错误码

网关错误码

结果码

描述

ILLEGAL_SIGN

签名不正确

ILLEGAL_DYN_MD5_KEY

动态密钥信息不正确

ILLEGAL_ENCRYPT

加密不正确

ILLEGAL_ARGUMENT

参数不正确

ILLEGAL_SERVICE

服务器参数不正确

ILLEGAL_USER

用户ID不正确

ILLEGAL_PARTNER

商户ID不正确

ILLEGAL_EXTERFACE

接口配置不正确

ILLEGAL_PARTNER_EXTERFACE

商户无权使用该接口

ILLEGAL_SECURITY_PROFILE

未找到匹配的私钥配置

ILLEGAL_AGENT

机构ID不正确

ILLEGAL_SIGN_TYPE

签名类型不正确

ILLEGAL_CHARSET

非法字符集

HAS_NO_PRIVILEGE

无访问权限

INVALID_CHARACTER_SET

无效字符集

业务错误码

当refund_result_code的值是PROCESSING时返回的错误码：

结果码

描述

SYSTEM_ERROR

支付宝系统错误，请重新发起请求

MERCHANT_BALANCE_NOT_ENOUGH

商户账户余额不足

REFUND_CHARGE_ERROR

退收费异常

REFUND_FAIL

退款失败

SERVICE_REFUSE

该时间段内不接受退款业务

SELLER_BALANCE_NOT_ENOUGH

卖家账户余额不足

当refund_result_code的值是FAILED时返回的错误码：

结果码

描述

SYSTEM_ERROR

支付宝系统错误，请重新发起请求

MERCHANT_BALANCE_NOT_ENOUGH

商户账户余额不足

TXN_RESULT_ACCOUNT_BALANCE_NOT_ENOUGH

最后一次退款执行失败，因为商户账户余额不足

REFUND_CHARGE_ERROR

退收费异常

TRADE_SETTLE_ERROR

结算异常

REFUND_FAIL

退款失败

TRADE_STATUS_ERROR

交易状态不合法

TRADE_HAS_CLOSE

交易已关闭，不允许退款

SERVICE_REFUSE

该时间段内不接受退款业务

SELLER_BALANCE_NOT_ENOUGH

卖家账户余额不足

CURRENCY_NOT_MATCH

退款币种和结算币种不匹配

INVALID_ROUNDED_AMOUNT

此金额的退款可能违反了人民币和外币的计算金额必须同时是全额退款或非全额退款的规则。

以一笔0.07元人民币(0.01美元)的交易为例。未接收0.06元人民币的退款请求，是因为本次交易还剩0.01人民币 (0美元)。

示例

请求示例

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

返回示例

请求失败：

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

请求成功但未收到退款结果：

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>

退款失败：

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>

退款成功：

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>

退款成功（存在退分账）：

copy
<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>