交易撤销接口(条码支付)

2023-12-27 07:01

调用此接口以取消一笔交易。若交易未被支付，则交易将被关闭；若交易已被支付，交易将被退款。

网关URL

环境

HTTPS请求地址

生产环境

备份：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

请求参数

参数描述

基本参数

service

String 不可空

接口名

示例：alipay.acquire.cancel

partner

String(16) 不可空

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

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

_input_charset

String 不可空

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

示例：UTF-8

sign_type

String 不可空

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

示例：MD5

sign

String 不可空

签名值

示例：363a752668ee2b3b8f124c623bd028ad

timestamp

String 不可空

商户服务器发送请求的时间。精确到毫秒。

示例：1456507704121

terminal_timestamp

String

终端发送请求的时间。精确到毫秒。

示例：1456507704102

业务参数

out_trade_no

String(64) 不可空

商户系统中唯一交易号

示例：990xxxxxxx8989

trade_no

String(64)

支付宝系统中唯一交易号。长度16-64字节。如果trade_no和out_trade_no同时出现，优先使用trade_no。

示例：2013112611001004680073956707

同步返回参数

参数描述

基本参数

is_success

String 不可空

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

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

示例：T

sign_type

String

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

示例：MD5

sign

String

签名值

示例：fc209d86b57b2adb23254a897ebaa7d9

error

String

请求失败时返回的错误代码，用于描述请求失败的原因。有关详细信息，参见本文档中的错误码。

示例：ILLEGAL_SIGN

业务参数

result_code

String(32) 不可空

交易撤销结果。SUCCESS代表撤销成功， FAIL代表撤销失败。

示例：SUCCESS

trade_no

String(64)

支付宝系统中唯一交易号。长度16-64字节。

示例：2013112011001004330000121536

out_trade_no

String(64)

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

示例：990xxxxxxx8989

retry_flag

String(1)

表明失败的请求是否可以重试。Y表示可以重试，N表示不可重试。

示例：Y

action

String(10)

表明如何撤销交易。可能的返回值如下：

close: 关闭交易
refund: 进行交易退款

示例：close

detail_error_code

String(48)

详细错误码，描述响应码的返回原因。当返回的result_code为SUCCESS时，该字段不会被返回。具体参见错误码。

示例：TRADE_STATUS_ERROR

detail_error_des

String(64)

详细错误码的描述。当返回的result_code为SUCCESS时，该字段不会被返回。

示例：Trade status is illegal.

错误码

错误码	描述
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	相应交易的状态不允许当前操作解决方案：确保交易状态正确。如果此错误仍然存在，请联系支付宝技术支持。
BUYER_ERROR	买家不存在。解决方案：联系支付宝技术支持。
BUYER_ENABLE_STATUS_FORBID	买家账户状态禁止退款。解决方案：联系支付宝技术支持。
SELLER_ERROR	卖家不存在。解决方案：联系支付宝技术支持。
MERCHANT_BALANCE_NOT_ENOUGH	商户余额不足，无法退款。解决方案：新的交易发生并且商户余额充足时，重试退款。
TRADE_CANCEL_TIME_OUT	不在撤销服务可用的时间内。解决方案：使用退款接口重试。
SELLER_BALANCE_NOT_ENOUGH	卖家余额不足。解决方案：新的交易发生并且卖家余额充足时，重试退款。
REASON_TRADE_REFUND_FEE_ERR	退款金额无效。解决方案：联系支付宝技术支持。
TRADE_HAS_FINISHED	交易已完成。解决方案：使用退款接口重试。
REFUND_CHARGE_ERROR	支付正在进行中，退款失败。解决方案：请稍后重试。
FREQUENCY_LIMITED	请求频率达到系统限制。解决方案：请稍后重试。

结果处理

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

检查您的网络是否连接支付宝网关，并使用正确的参数重试撤销请求。请进行多次重试。重试时，推荐使用递增间隔，如2秒，4秒，8秒，16秒，32秒。具体重试次数和间隔视产品和网络状态而定。详情可联系技术支持。
若问题未被解决，请联系支付宝技术支持。

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

is_success=F，error=SYSTEM_ERROR
is_success=T，result_code=FAIL，detail_error_code=SYSTEM_ERROR

执行以下操作：

请进行多次重试。重试时，推荐使用递增间隔，如2秒，4秒，8秒，16秒，32秒。具体重试次数和间隔视产品和网络状态而定。详情可联系技术支持。
若问题未被解决，请联系支付宝技术支持。

案例3：如果收到支付宝响应，且is_success=T，result_code=SUCCESS，交易撤销成功。

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

is_success=F，error=SYSTEM_ERROR
is_success=T，result_code=FAIL，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.
    }
  }
}

示例

请求示例

指定out_trade_no字段的请求示例

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.cancel&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&out_trade_no=out_trade_no_20190904_151404&sign=fa57cabdbc0fc5bd583a66afdf2df62c

指定trade_no字段的请求示例

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.cancel&partner=2088021966388155&_input_charset=UTF-8&sign_type=MD5&trade_no=2019090422001436530558497325&sign=7288cd48af8091b31c3c4cdc768ef5bd

响应示例

请求成功，且撤销业务成功：

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner">208xxxxxxxxx8155</param>
        <param name="service">alipay.acquire.cancel</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">7288cd48af8091b31c3c4cdc768ef5bd</param>
        <param name="trade_no">201xxxxxxxxxxxxxxxxxxxxx7325</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <action>refund</action>
            <out_trade_no>out_trade_no_20190904_151744</out_trade_no>
            <result_code>SUCCESS</result_code>
            <retry_flag>N</retry_flag>
            <trade_no>201xxxxxxxxxxxxxxxxxxxxx7325</trade_no>
        </alipay>
    </response>
    <sign>69ac0fcec5f9b0b2e64c7dec82249feb</sign>
    <sign_type>MD5</sign_type>
</alipay>

请求成功，但撤销业务失败：

copy
<?xml version="1.0" encoding="utf-8"?> 
 <alipay> 
   <is_success>T</is_success> 
   <request> 
     <param name="sign">66b3a14ec95846f01d42564e6953c81b</param> 
     <param name="_input_charset">UTF-8</param> 
     <param name="sign_type">MD5</param> 
     <param name="service">alipay.acquire.cancel</param> 
     <param name="partner">2088101126765726</param> 
     <param name="out_trade_no">99003911198989</param> 
     <param name="timestamp">1456507705033</param> 
   </request> 
   <response> 
     <alipay> 
      <result_code>FAIL</result_code> 
      <detail_error_code>TRADE_STATUS_ERROR</detail_error_code> 
      <detail_error_des>illegal trade status</detail_error_des> 
     </alipay> 
    </response> 
    <sign>fc209d86b57b2adb23254a897ebaa7d9</sign> 
    <sign_type>RSA</sign_type> 
 </alipay>

请求失败：

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