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

退款接口（条码支付）

调用此接口发起全额退款或部分退款请求。退款请求无法撤销。

网关URL

注意:

如果使用POST方法，请在请求URL中传入_input_charset。例如： https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

请求参数

参数描述
基本参数

service

String 不可空

接口名称

Example:alipay.acquire.overseas.spot.refund

partner

String(16) 不可空

支付宝分配的用于标识支付宝帐户的合作伙伴ID。合作伙伴ID是2088开头的16位数字。

示例：2088*********662

_input_charset

String

请求数据的编码集，支持UTF-8。

示例：UTF-8

sign_type

String 不可空

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

示例：RSA

sign

String 不可空

签名值

示例：e5815a4556db338ed237f7d3fd222184

notify_url

URL(200)

交易支付完成之后的接收通知的URL。

示例：https://www.test.com/alipay/notify_url.php

业务参数

partner_trans_id

String(64) 不可空

原支付请求中合作伙伴的交易号

示例：2010121000000002

alipay_trans_id

String(64)

支付宝交易号

示例：201311221703338463

partner_refund_id

String(64) 不可空

合作伙伴系统中的退款订单号。此字段的值不能与partner_transaction_id字段的值相同。同一个合作伙伴ID下的一个partner_refund_id，系统将识别为一笔退款。

示例：301012133000002

refund_amount

Number(9,2) 不可空

退款金额。退款金额不能大于原始交易金额和未退款金额。

示例：39.25

currency

String(10) 不可空

退款币种，使用大写形式。关于币种的更多信息，具体请参见支持币种。

示例：USD

refund_reason

String(128)

退款原因

示例：Refund the good

is_sync

String(1)

用来表明退款请求是同步或异步处理，值为Y或N。默认值为N，表示异步处理，支付宝发送异步通知到商户在请求参数中传入的notify_url。如果值为Y，表示同步处理，支付宝仅返回同步通知。

示例：Y

注意：

金额的小数位数精度（如refund_amount的值）取决于货币值。如果currency的值为JPY或KRW，则金额必须为整数，如100 JPY。其他货币金额精确到小数点后两位，如100.00 USD。其他格式将导致报错，如100.999 USD。

返回参数

同步返回参数

支付宝网关接受的参数

参数描述

is_success

String(1) 不可空

用于展示请求是否成功，值为T表示成功，值为F表示失败。

注意：成功的请求并不意味着业务被接受并成功完成处理。

示例：T

sign_type

String 不可空

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

示例：MD5

sign

String(32) 不可空

签名值

示例：59c7275cf3c82f038b7c0076f9888926

result_code

String(32) 不可空

请求处理结果

SUCCESS：处理成功

FAILED：处理失败

示例：SUCCESS

error

String(48)

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

示例：TRANS_NOT_FOUND

partner_trans_id

String(64) 不可空

原支付请求中合作伙伴的交易号。返回值与请求传入值相同。

示例：201311221000000002

alipay_trans_id

String(64)

支付宝为商户请求分配的交易号。该字段与partner和partner_trans_id形成映射关系。

Example:201311221703338463

partner_refund_id

String(64) 不可空

合作伙伴系统中的退款订单号，同一个合作伙伴ID下的一个partner_refund_id，系统将识别为一笔退款。

Example:301012133000002

refund_amount

Number(9,2) 不可空

退款金额。退款金额不能大于原始交易金额和未退款金额。

示例：39.25

currency

String(10) 不可空

退款币种

示例：USD

exchange_rate

Number(8,6)

支付请求中的外币与人民币之间的汇率。汇率换算在支付宝交易订单创建时发生。

示例：6.0939

refund_amount_cny

Number(9,2)

人民币退款金额，即支付宝实际退款金额。

示例：239.19

支付宝网关拒绝的参数

参数描述

is_success

String(1) 不可空

用于展示支付宝网关是否接收请求

T：接受

F：拒绝

示例：F

sign_type

String 不可空

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

示例：MD5

sign

String(32) 不可空

签名值

示例：59c7275cf3c82f038b7c0076f9888926

error

String(48)

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

示例：TRANS_NOT_FOUND

异步返回参数

在处理完商户的请求数据后，支付宝通过服务器主动通知商户网站数据处理的结果。下表为异步通知中的参数：

参数描述
基本参数

notify_time

Timestamp 不可空

通知发送时间，格式为yyyy-MM-dd HH:mm:ss。

Example:2013-11-27 15:45:58

notify_type

String 不可空

通知类型

Example:refund_status_sync

notify_id

String 不可空

通知ID，合作伙伴可使用通知ID验证通知的合法性。

Example:ac05099524730693a8b 330c5ecf72da978

sign_type

String 不可空

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

Example:MD5

sign

String 不可空

签名值

Example:601510b7970e52cc63d b0f44997cf70e

业务参数

out_trade_no

String(64)

商户网站订单系统中的订单号，非支付宝交易号，需确保在商户系统中订单号的唯一性。该字段的值与请求中传入的值保持一致。

Example:990xxxxxxx8989

out_return_no

String(64) 不可空

合作伙伴系统中的退款订单号。如果商户在支付宝网站发起退款请求，该字段的值由支付宝自动生成。

Example:301012133000002

refund_status

String(64) 不可空

退款状态

REFUND_SUCCESS：退款成功

REFUND_FAIL：退款失败

Example:REFUND_SUCCESS

currency

String(8)

退款币种

Example:USD

return_amount

Number(9,2)

退款金额

Example:1.00

trans_refund_fee

Number(9,2)

以交易币种表示的预计退款金额，仅供参考。

Example:1.00

error_code

String

退款失败时返回的错误代码，用于描述退款失败的原因。当退款成功时，该字段为空。

Example:ILLEGAL_SIGN

错误码

错误码

描述

SYSTEM_ERROR

支付宝系统错误

解决方案：输入正确的参数，并且重新发送请求。具体请参见案例 2。

ILLEGAL_SIGN

签名不正确

解决方案：使用正确的签名重试。

INVALID_PARAMETER

参数不正确

解决方案根据接口说明检查每个请求参数的标准。

ILLEGAL_ARGUMENT

参数不正确

解决方案根据接口说明检查每个请求参数的标准。如果此错误仍然存在，联系支付宝技术支持。

ILLEGAL_PARTNER

商户ID不正确

解决方案：确保partner值与支付宝分配的值一致。如果此错误仍然存在，请联系支付宝技术支持。

ILLEGAL_EXTERFACE

接口配置不正确

解决方案：确保service参数的值同接口说明中的值一致。如果此错误仍然存在，联系支付宝技术支持。

ILLEGAL_PARTNER_EXTERFACE

商户无权使用该接口

解决方案：确保您与支付宝的协议已签订。如果需要，请联系支付宝技术支持。

ILLEGAL_SIGN_TYPE

签名类型不正确

解决方案：确保sign_type值为 MD5、RSA 或 RSA2。如果此错误仍然存在，请联系支付宝技术支持。

HAS_NO_PRIVILEGE

无权访问

解决方案：联系支付宝技术支持。

REASON_TRADE_BEEN_FREEZEN

由于安全问题，交易被冻结。

解决方案：联系支付宝技术支持。

TRADE_NOT_EXIST

根据partner_trans_id值无法找到对应交易

解决方案：确保partner_trans_id参数值正确。如果此错误仍然存在，请联系支付宝技术支持。

TRADE_STATUS_ERROR

相应交易的状态不允许当前操作

解决方案：确保交易状态正确。如果此错误仍然存在，请联系支付宝技术支持。

REFUND_AMT_RESTRICTION

退款金额超过原始交易金额，或者总退款金额超过原始交易金额，支付宝无法处理。

解决方案：商户检查退款金额是否正确。

REQUEST_AMOUNT_EXCEED

与错误码REFUND_AMT_RESTRICTION的原因相同。

解决方案：商户检查退款金额是否正确。

TRADE_HAS_CLOSE

交易关闭，无法操作退款

解决方案：检查交易状态和退款时间范围设置。

MERCHANT_BALANCE_NOT_ENOUGH

商户余额不足以处理此笔退款。可能的原因是之前交易金额已结算至商家账户。

解决方案：新的交易发生并且商户余额充足时，重试退款。

INVALID_ROUNDED_AMOUNT

退款金额违反人民币金额和外币金额必须同时全额或部分退款的规则。以金额为0.07 CNY（0.01 USD）的交易为例，退款金额为0.06 CNY时，无法受理，因为剩余未退款金额为0.01 CNY（0 USD）。

REASON_TRADE_REFUND_FEE_ERR

退款金额无效

解决方案：检查请求中的退款金额。

REFUND_CHARGE_ERROR

支付进行中，退款失败。

解决方案：请稍后重试。

BUYER_NOT_EXIST

买家不存在

解决方案：联系支付宝技术支持。

结果处理

案例 1：当接口调用因网络问题或请求超时而失败，并且支付宝无响应时，执行以下操作：

1. 检查您的网络是否连接支付宝网关。使用正确的参数重新发送请求，直到收到支付宝响应。重试规则为每三秒钟一次，最多五次。

2. 如果仍未收到支付宝响应，请联系支付宝国际技术支持。

案例 2：如果收到支付宝响应，且以下结果之一被返回：

  • is_success=F，error=SYSTEM_ERROR
  • is_success=T，result_code=FAILED，detail_error_code=SYSTEM_ERROR

执行以下操作：

1. 使用正确的参数重新发送请求，直到收到支付宝响应。重试规则为每三秒钟一次，最多五次。

2. 如果仍未收到支付宝响应，请联系支付宝国际技术支持。

案例 3：如果您收到支付宝响应为is_success=T ，result_code=SUCCESS，则退款请求已成功受理，但不代表退款操作已成功处理。

案例4：如果收到以下任何一种响应，表明退款失败：

  • is_success=F，error=!SYSTEM_ERROR
  • is_success=T，result_code=FAILED，detail_error_code!=SYSTEM_ERROR

参考具体错误码以了解更多信息。

伪代码

copy
try{
  if(isCase3){ //CASE 3
    doSuccessProcess();
  }
  else if(isCase4){ //CASE 4
    doFailureProcess();
  }
  else{ //CASE 2
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }

}catch (Exception ex){ //CASE 1

    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }
}

示例

请求示例

异步处理：

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.spot.refund&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&partner_trans_id=out_trade_no_20190904_160450&partner_refund_id=partner_refund_id_20190904_160211&refund_amount=0.01&refund_reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&sign=b0d81ca4ecc6f14d149626233c727ef2

同步处理：

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.spot.refund&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&partner_trans_id=out_trade_no_20190904_160450&partner_refund_id=partner_refund_id_20190904_160211&refund_amount=0.01&refund_reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&is_sync=Y&sign=45f7af56d72cae12f1c74868873c47b8

返回示例

同步返回示例

业务接收并正常处理：

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner_trans_id">out_trade_no_20190904_160450</param>
        <param name="partner">208xxxxxxxxx8155</param>
        <param name="service">alipay.acquire.overseas.spot.refund</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">b0d81ca4ecc6f14d149626233c727ef2</param>
        <param name="refund_amount">0.01</param>
        <param name="currency">USD</param>
        <param name="refund_reason">The buyer wants to initiate a refund.</param>
        <param name="notify_url">https://www.mikascoffee.com/notify</param>
        <param name="sign_type">MD5</param>
        <param name="partner_refund_id">partner_refund_id_20190904_160211</param>
    </request>
    <response>
    <alipay>
        <alipay_trans_id>201xxxxxxxxxxxxxxxxxxxxx3346</alipay_trans_id>
        <currency>USD</currency>
        <exchange_rate>7.18041000</exchange_rate>
        <partner_refund_id>partner_refund_id_20190904_160211</partner_refund_id>
        <partner_trans_id>out_trade_no_20190904_160450</partner_trans_id>
        <refund_amount>0.01</refund_amount>
        <refund_amount_cny>0.07</refund_amount_cny>
        <result_code>SUCCESS</result_code>
    </alipay>
    </response>
    <sign>fde68b2f3b82a599fd33eb84e250a220</sign>
    <sign_type>MD5</sign_type>
</alipay>

请求失败或者数据错误：

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

异步通知示例

copy
https://www.mikascoffee.com/notify
trans_refund_fee=0.01
notify_type=refund_status_sync
return_amount=0.01
notify_time=2019-09-11 19:24:30
out_trade_no=out_trade_no_20190904_163949
refund_status=REFUND_SUCCESS
sign=$$$
out_return_no=partner_refund_id_20190904_160211
currency=USD
sign_type=MD5
notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx3785

注意：

关于异步通知，同步通知和数字签名的更多信息，参见接口说明。