一、基础说明

 

本文档将涵盖API调用场景及注意事项，天猫与淘宝的退货退款API将统一为一大套API接口对外开放。

适用于接入退款退货管理功能的第三方开发者（下文简称：isv）或自主开发的商家。

 

注意：消费者发起退款后，为了避免出现资损和投诉，建议除了系统对接退款退货流程外，还需要售后客服与消费者沟通确认，再最终往下推进退款流程。

 

1）订单付款未发货前，消费者发起退款，卖家可以同意退款，资金原路退回；卖家也可以进行发货，订单进入发货状态。

2）已发货订单的退款，消费者可以发起<退款退货>或者<退款不退货> , 不同的退款类型和原因，卖家侧也有响应时效限制，如果不处理会自动同意退款。

 

 

获取退款单API

 

taobao.refunds.receive.get 查询卖家收到的退款列表

taobao.refund.get 获取单笔退款详情

 

二、退款退货调用流程

 

 

1. taobao.rp.refund.review( 审核退款单 ) 审核退款单，标志是否可用于批量退款，目前仅支持天猫订单，仅支持主账号操作。

 

2. 天猫订单退款必须先调用审核接口，再调用同意退款接口 taobao.rp.refunds.agree( 同意退款 )。

1）同意退款接口仅支持许子账号授权调用，当前调用 API所用的子账号必须在卖家中心→子账号管理 授权退款操作的权限，并设定具体的操作限额，详情点击参考子账号授权流程介绍。

注意：需要保证该子账号拥有客户服务-售中售后管理-同意退款（集市需要交易管理-子账号售中退款-同意子账号退款）的权限点。

 

2）该接口分两个阶段，第一次不带Code参数，系统会发送验证码到当前授权所代表的子账号用户注册的手机上，第二次带Code参数（参数内容为验证码），执行同意退款打款操作，调用成功，则直接通过支付宝打款给买家。

注意：目前不支持同意退款接口只调用一次即完成退款操作，由于接口调用会直接打款至支付宝，基于安全必须通过获取短信的方式完成退款。

 

3）并且集市支持批量(20笔以内，总金额6000以内)，天猫支持30笔以内，总金额10000以内。

4）入参refund_infos说明：

① 对于集市，包含信息如下：RefundId（退款单ID）、Fee（退款金额）、Version（通过taobao.refund.get接口获取refund_version）；

② 对于天猫，包含的数据有退款ID|其对应的金额|对应版本号列表|退款阶段（onsale\aftersale），其中金额以分为单位，ID与金额以“|”符号分隔，多笔订单以“,”分隔。

格式：RefundId1|Fee1|Version1|Refund_phase,RefundId2|Fee2|Version2|Refund_phase ...

示例：192242532288979|6000|12312|onsale,192242532298979|6000|32112|onsale

 

4）判断是否退款成功

success 为 true 时，【不一定】全部成功，ISV需要取到results后逐个判断是否成功。

 

三、退款状态变化

 

退款单的状态可以在Refund数据结构中的Status获取，会根据退款操作的变化而变化。

关于退款单状态的变化情况请参考上文天猫退款退货流程，以下列表仅做描述，现有的退款单状态：

 

API	描述	说明
WAIT_SELLER_AGREE	买家已经申请退款，等待卖家同意	买家提交退款申请时的状态
WAIT_BUYER_RETURN_GOODS	卖家已经同意退款，等待买家退货	退款申请包含退货时，卖家同意退货（后台或者taobao.rp.returngoods.agree）后的状态
WAIT_SELLER_CONFIRM_GOODS	买家已经退货，等待卖家确认收货	退款申请包含退货，买家上传退货物流信息后的状态
SELLER_REFUSE_BUYER	卖家拒绝退款	卖家拒绝退货或者拒绝退款时
SUCCESS	退款成功	卖家批量同意退款操作后的状态
CLOSED	退款关闭	退款申请超时或者未发货的订单申请退款时卖家强制发货后的状态

 

四、退款/退货/换货卖家响应时效

 

不适用“立即退款”（以下简称“秒退”）规则的特殊类目及场景有哪些？

1）本地生活/点券、航旅、虚拟、天猫卡券及定制相关类目（明细类目点此查看）；

2）根据天猫《滥用会员权利的规则及实施细则》，会员滥用会员权利产生的订单；

3）特殊交易流程或新型业务场景下产生的订单，包括新零售居然之家城市站、淘宝特价版APP/“阿里鱼-造点新货”频道等特殊渠道、涉及资金出入境的业务场景、天猫大闸蟹商品等虚拟商品/服务交易场景等。

 

以上“退款/退货/换货卖家响应时效”信息根据淘宝网的平台规则内容整理，可能存在主站规则变更，开放平台信息同步不及时问题，以主站平台规则为准，可以查看：淘宝网超时说明，天猫交易时效规定

 

五、未发货2H秒退订单

退款类型			变更前超时时限	变更后超时时限
退款（无需退货）	货物状态：未发货	不想要了	2日	除特殊类目及场景外，付款2小时内且订单金额≤200元的订单买家申请退款时享受“秒退”，除上述情形外的超时时效为24小时
		拍错了/订单信息错误
		商家缺货	3日
		商家未按约定时间发货
	货物状态：已发货(消费者未收到货)	设置了“支持售中自动退款”的电子凭证商品的所有退款原因	1日	24小时
		除上述情形外	3日	48小时
退货退款/换货	已发货需要退货/换货/我要换货-“转退货”	1、退款原因为“试了不合适”的商品； 2、退款原因为“7天无理由退换货”的部分商品，详情请点此查看	立即	立即
		“售后无忧”服务的订单	1日	24小时
		除上述情形外	3日	48小时
	已退货待退款	快递	10日	240小时
		平邮	30日	336小时
等待买家修改协议		未退货	7日	120小时
		已退货	15日

 

要点一：商家需要在新规要求时间内响应买家的退款申请（同意或者拒绝），逾期系统将默认同意买家的退款/退货/换货申请；

要点二：针对未发货状态下付款后2小时内，且订单金额≤200元的中秒退的订单，商家需及时关注异常情况，有需要第一时间联系快递/买家协商处理。

符合平台“未发货2H秒退”订单查看路径：“商家中心→退款售后管理，进入退款管理页面，在“业务类型”筛选框下选择“未发货2小时零秒退”则可符合规则订单明细

 

1）Q：店铺ERP如何通过 API接口 识别该笔订单是不是未发货2H秒退订单？
A：目前未发货秒退的识别方式为接口taobao.refund.get( 获取单笔退款详情 ) 请求参数 fileds中加上 attribute，响应返回列表中“attribute” 字段中含有 “newAutoRefund” 即为未发货秒退订单。

 

2）Q：商家后台如何查询该笔订单是属于平台“未发货2H秒退”的订单？

A：您可以在店铺后台店铺管理页面查询该笔订单是否符合“未发货2H秒退”，具体查询路径为“商家中心-退款管理-业务类型（选择未发货2H秒退）

商家端后台查询页面展示如下图：

 

 

3）Q：在属于平台“未发货2H秒退”的订单中，若商品实际已发货，应该怎么办？

A：：若商品您已发货，建议您第一时间联系快递拦截退回，且同时对买家端做好拒签的提醒，若前面过程都无法拦截，建议及时联系买家协商，未协商一致的情况下可以联系天猫客服协助。

同时，建议您及时调整商品发货等操作流程哦，若订单状态已发货，就不属于“未发货2H秒退”订单范围。

 

4）Q：如果在商家响应退款前，消费者突然修改了退款协议，退款的超时时间怎么计算？

A：订单超时会根据退款状态调整，按照最新退款状态的显示计算，比如：消费者修改为 退款（无需退货），则会按照 退款（无需退货）的超时时间开始计算。

 

5）Q：商家响应退款的时间要求缩短了，有什么工具可以帮助我更快速的处理吗？

A：亲，有以下两个工具可以帮助您批量自动化处理退款：

① 您可使用平台为商家推出的AG产品，设置自动化退款，详细操作【点此查看】；若您对AG产品有其他问题，也可【点此查看】提交工单流程，处理人会在1个工作内在提交工单链接中答复；

② 您可在商家中心-退款管理页面，使用【托管设置】工具，进行自动化退款，详细操作【点此查看】。

 

6）0秒退快递拦截场景

为了提升消费者在逆向环节的购物体验，针对符合平台自动退款规则的订单，且订单状态在“已发货”后“待派件”前，消费者申请退款时将执行0秒退。同时，平台也会向快递公司发起快递拦截指令。为了更好地帮助商家服务消费者，服务商系统需要识别0秒退的订单及快递拦截状态。

对接方案如下：
taobao.refunds.receive.get和taobao.refund.get在attribute新增以下返回值：

返回值	说明
autoInterceptAgree	= 1 ，代表淘天平台自动拦截
interceptInvestor	代表快递拦截费用的出资方，枚举值有： 1）taobao，代表平台为该笔拦截费用出资； 2）seller，代表商家为该笔拦截费用出资；
LogisticInterceptEnum	商品截单状态，具体值如下： 1）INTERCEPT_APPLY(1, "物流截单申请中") 2） INTERCEPT_SUCCESS(2, "物流截单成功") 3）INTERCEPT_FAILED(3, "物流截单失败") 4）INTERCEPT_SELLER_CONFIRM_SIGN(5, "拦截卖家确认签收")
interceptFailCode	截单失败原因

六、FAQ

 

1. Q：如何知道是否有退货？

A：通过 taobao.refund.get( 获取单笔退款详情 )Refund. has_good_return“买家是否需要退货”判断，true为退款退货，false退款（无需退货）。

 

2. Q：如何获取退款单的refund_phase和refund_version？

A：可以通过refund_id 查询接口 taobao.refund.get( 获取单笔退款详情 )获取 refund_phase“退款阶段，onsale/aftersale”和 refund_version“退款版本号”，以时间戳格式返回。

 

3. Q：买家修改退款申请后卖家操作退款单有什么影响？

A：买家修改退款申请后，退款版本号 refund_version 会变化，退款操作时会校验 refund_version，在操作中可以通过taobao.refund.get( 获取单笔退款详情 ) 接口查询具体退款单的Refund信息。

 

4. Q：子账号操作 taobao.rp.refunds.agree（同意退款）报错"操作失败"，"msg_code":"40001"

A：报该错误一般有以下几种情况，

1) 淘宝退款一次退款超过20笔了，总金额超过6000元了。

2) 天猫退款一次退款超过30笔了，总金额超过10000元了。

3) 子账号单笔可操作退款的金额超出限制；

建议商家用主账号在商家后台处理 或 给子账号调整单笔可操作退款金额上限大于实际退款金额。

示例：主账号给子账号设置的单笔可操作的退款金额上限是 800元，退款单实际退款的金额是：900元，这时子账号操作同意退款就会报错。

4) 一笔订单多个子订单，如A子订单TRADE_FINISHED(交易成功)，B子订单还在交易中。买家申请A子订单退款，这时A子订单卖家同意退款报“操作失败”；这种场景需要所以其余子订单交易完结，卖家才可操作同意退款。

 

5. Q：权益金、购物金退款金额获取？

A：

交易订单退款，包含购物金支付部分的退款信息，可通过：taobao.refund.get( 获取单笔退款详情 )

字段 attribute“退款扩展属性”获取进行解析。

（权益金退款具体金额是 卖家同意退款完成之后，卖家才可以获取。）

使用了权益金且退款完成【"refund_status":"SUCCESS(退款成功)"】的订单，退款接口才会返回权益金相应字段。

资金退款组成售中退款：pmtRD；

资金退款组成售后退款：pmtARD；

权益金：TMALL_MCARD_PZ_SP 单位：分。

本金：TMALL_MERCHANTCARD_SP 单位：分。

 

注意：

1）权益金退款，是退款完成之后，商家才可以得知具体金额的。退款完成之前，不会返回权益金，退款单也不会包含权益金退款金额。请核实订单状态是否"refund_status":"SUCCESS(退款成功)"

2）如果退款没有完成，退款单状态是以下这些情况的订单，"refund_status": "WAIT_SELLER_AGREE"(等待卖家同意) /WAIT_SELLER_AGREE(买家已经申请退款，等待卖家同意) /WAIT_BUYER_RETURN_GOODS(卖家已经同意退款，等待买家退货) /WAIT_SELLER_CONFIRM_GOODS(买家已经退货，等待卖家确认收货) /SELLER_REFUSE_BUYER(卖家拒绝退款) /CLOSED(退款关闭) ，都是不会返回权益金退款的相关字段的。

 

6. 同意退款接口 taobao.rp.refunds.agree（同意退款）返回的error_code列表有：

 

前台错误信息（message字段）	错误信息解析说明
系统繁忙，请稍候再试	这种情况是平台内部计算逻辑异常报错，遇到此信息请稍后半小时重试，如果重试还是存在异常请通过开放平台工单反馈处理
子账号校验金额权限不足	退款的金额超过了商家给这个子账号设置的同意退款金额上限，需要更换子账号操作或者在子账号管理后台调整同意退款金额上限
资金正在处理中，请稍后查看处理结果	这类提示是因为订单应该是通过其它非支付宝渠道做退款处理的，这个需要等待下游渠道返回实际出账成功，这个可以稍后刷新看状态是否同步处理成功。
资金正在处理中，请在成交24小时后再次尝试	团长代付订单，支付成功后需要T+1才到商家账户，需要在24小时后同意退款
您店铺主体的支付宝账号代扣协议签署已过期，请重新签署。如您的店铺曾经过户，需要新主体的支付宝账号签署代扣协议，才能操作过户前的退款申请	商家执行过店铺过户，新主体操作老主体的退款会校验店铺过户协议，需要新主体签署店铺过户协议
退款失败，卖家支付宝账户异常，请联系支付宝确认	此类问题是因为执行退款的时候，卖家的支付宝账户出现了异常导致无法正常打款，此类问题需要卖家确认下自己的支付宝账户是否是正常可用状态，如果账号确实异常请反馈支付宝官方客服确认异常原因和处理
退款失败，卖家支付宝账户司法冻结，请联系支付宝确认
退款失败，卖家支付宝账户异常，请联系支付宝确认
退款失败，卖家支付宝账户异常，请联系支付宝确认
您需要重新签署子账号协议，然后再用子账号操作退款，或者让商家用主账号操作退款	子账号免密退款协议未签署
支付宝可用余额或者保证金不足, 请充值后再尝试操作	余额不足
客官别急，稍等再试试~	通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理
同一主订单下多笔子订单退款存在冲突，请稍后重试	多出现在一主多子的订单，同时操作同意退款，在支付宝并发导致，一般重试即可
系统异常	通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理
由于其余子订单尚未完结，售后退款失败。待买家将其余子订单确认收货后，即可操作售后退款。	主子订单状态不一致，需要主订单推进到售后，才能操作退款
您需要联系支付宝客服解锁该笔交易，然后再重试退款操作	支付宝交易被锁定

 

七、错误码信息获取与业务解析

 

taobao.rp.refunds.agree，接口处理错误信息的反馈，目前接口针对每笔退款失败的退款单都透出了错误信息文案，赋给message字段。

 

前台错误信息（message字段）	错误信息解析说明
系统繁忙，请稍候再试	这种情况是平台内部计算逻辑异常报错，遇到此信息请稍后半小时重试，如果重试还是存在异常请通过开放平台工单反馈处理
子账号校验金额权限不足	退款的金额超过了商家给这个子账号设置的同意退款金额上限，需要更换子账号操作或者在子账号管理后台调整同意退款金额上限
资金正在处理中，请稍后查看处理结果	这类提示是因为订单应该是通过其它非支付宝渠道做退款处理的，这个需要等待下游渠道返回实际出账成功，这个可以稍后刷新看状态是否同步处理成功。
资金正在处理中，请在成交24小时后再次尝试	团长代付订单，支付成功后需要T+1才到商家账户，需要在24小时后同意退款
您店铺主体的支付宝账号代扣协议签署已过期，请重新签署。如您的店铺曾经过户，需要新主体的支付宝账号签署代扣协议，才能操作过户前的退款申请。	商家执行过店铺过户，新主体操作老主体的退款会校验店铺过户协议，需要新主体签署店铺过户协议
退款失败，卖家支付宝账户异常，请联系支付宝确认	此类问题是因为执行退款的时候，卖家的支付宝账户出现了异常导致无法正常打款，此类问题需要卖家确认下自己的支付宝账户是否是正常可用状态，如果账号确实异常请反馈支付宝官方客服确认异常原因和处理
退款失败，卖家支付宝账户司法冻结，请联系支付宝确认
退款失败，卖家支付宝账户异常，请联系支付宝确认
退款失败，卖家支付宝账户异常，请联系支付宝确认
您需要重新签署子账号协议，然后再用子账号操作退款，或者让商家用主账号操作退款	子账号免密退款协议未签署
支付宝可用余额或者保证金不足, 请充值后再尝试操作	余额不足
客官别急，稍等再试试~	通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理
同一主订单下多笔子订单退款存在冲突，请稍后重试	多出现在一主多子的订单，同时操作同意退款，在支付宝并发导致，一般重试即可
系统异常	通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理
由于其余子订单尚未完结，售后退款失败。待买家将其余子订单确认收货后，即可操作售后退款。	主子订单状态不一致，需要主订单推进到售后，才能操作退款
您需要联系支付宝客服解锁该笔交易，然后再重试退款操作	支付宝交易被锁定

八、涉及API

 

API	功能描述
taobao.user.seller.get	查询商家信息
taobao.refunds.receive.get	查询退款列表
taobao.refund.get	查询单笔退款
taobao.rp.returngoods.refuse	拒绝退货
taobao.rp.returngoods.agree	同意退货
taobao.rp.returngoods.refill	天猫商家回填退款物流单号
taobao.rp.refund.review	退款单标记
taobao.rp.refund.review	审核退款单
taobao.refund.refuse	拒绝退款
taobao.rp.refunds.agree	同意退款