退款接口（条码支付）

2020-10-17 16:30

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

#网关URL

环境

HTTPS请求URL

生产环境

备用：https://intlmapi.alipay.com/gateway.do

测试环境

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

注意:

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

#请求参数

注意：

金额的小数位数精度（如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

同步处理：

#返回示例

同步返回示例

业务接收并正常处理：

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

注意：

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