退款接口

商户可以使用这个单笔退款接口来操作退款.


使用同一个PID(partner)发起多个退款交易时,退款请求间隔至少3秒。


#网关URL

环境HTTPS请求URL
生产环境https://intlmapi.alipay.com/gateway.do
测试环境https://mapi.alipaydev.com/gateway.do

#请求参数

参数类型 (长度是字节)描述可选示例
基本参数
serviceString接口名称不可空forex_refund
partnerString(16)境外商户在支付宝的用户ID. 2088开头的16位数字不可空2088001159940003
_input_charsetString请求数据的编码集,支持UTF-8。不可空UTF-8
sign_typeString签名算法 DSA, RSA, and MD5.不可空RSA
signString签名值不可空e5815a4556db338ed237f7d3fd222184

notify_url

String(200)

针对该交易支付成功之后的通知接收URL。

可空

http://www.test.com/alipay/notify_url.php

业务参数
out_return_noString(64)外部退款请求的ID不可空 

205485121225

out_trade_noString(64)境外商户交易号(确保在境外商户系统中唯一)不可空

205485121223

return_amountNumber(8,2)外币退款金额可空100.30
return_rmb_amountNumber(15)人民币退款金额可空

 10.20

currencyString(10)外币币种不可空USD
gmt_returnString(14)

yyyyMMddHHmmss

北京时间(+8)
不可空 
reasonString(100)退款原因可空test
product_codeString(32)网站支付: NEW_OVERSEAS_SELLER 手机浏览器或支付宝钱包支付: NEW_WAP_OVERSEAS_SELLER不可空NEW_OVERSEAS_SELLER
split_fund_infoString(1 600)分账信息,json 格式,具体请参见“分账明细说明可空

[{"transOut":"2088101137935255","amount":"0.10","currency":"USD","desc":"test1"},{"transOut":"2088101126707869","amount":"0.10","currency":"USD","desc":"test2"}]

is_syncString(1)退款请求同步或异步处理。取值:Y或N。默认值:N,异步处理。如果该值为Y,notify_url将无意义可空Y

 Note:

  1. 退款总金额不能超过原始的支付金额。
  2. 退款必须在一定的时间范围内申请(合同里面确定,默认是3个月)
  3. 外币金额和人民币金额的值(如return_amountreturn_rmb_amount的值)必须精确到小数点后两位。如100.00 USD。 其它格式将导致报错,如100.999 USD. 但当外币金额单位是JPY时,金额必须是整数,如100 JPY。

#同步返回

同步返回是xml格式的。

参数类型 (长度是字节)描述可选示例
is_successString返回状态, ‘T’ or ‘F’不可空T
errorString错误消息可空REPEATED_REFUNDMENT_REQUEST

#示例

#请求示例

https://intlmapi.alipay.com/gateway.do?reason=refund+test&return_amount=0.1&sign_type=MD5&gmt_return=20130812094000&out_trade_no=iamdjc456&currency=HKD&sign=8e9004797d3c7112b907bd184d775662&_input_charset=UTF-8&out_return_no=test005&service=forex_refund&partner=2088701998606387

#同步返回示例

#成功返回
copy
<?xml version="1.0" encoding="GBK"?>
<alipay>
    <is_success>T</is_success>    
</alipay>
#错误返回:
copy
<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

#

#异步通知

除了通过网页重定向的API响应,API响应也可以以异步POST方法发送给合作伙伴,如果商家在请求中设置了参数notify_url并且目标URL会处理异步通知。这种支付解决方案必须处理异步通知。

支付宝会在25小时内自动重复多次发送异步通知直到商家服务器回复“success”消息在响应中。 在处理同步返回和异步通知的时候,需要考虑下面几个方面:

  • 异步通知可能比同步返回先到达
  • 重复的异步通知消息

#异步通知返回参数

参数名类型(长度字节)描述示例
基本参数
notify_typeString通知类型值trade_status_sync
notify_timeDate通知时间(支付宝时间),格式:yyyy-MM-dd HH:mm:ss2009-08-12 11:08:32
notify_idString支付宝通知流水号,境外商户可以用这个流水号询问支付宝该条通知的合法性70fec0c2730b275286 65af4517c27b95
sign_typeString签名方式 DSA, RSA, MD5.MD5
signString签名656578b72f40e52 326dba4a41d6da62b
业务参数
out_trade_noString(64)境外商户交易号(确保在境外商户系统中唯一)3824701800653976
out_return_noString(64)机构的退款ID
refund_statusString(32)退款状态。
若退款成功,退款状态为 REFUND_SUCCESS。
若退款失败,退款状态为REFUND_FAIL。
REFUND_SUCCESS
error_codeString(64)退款失败错误码,本字段仅出现在退款失败时。RETURN_AMOUNT_EXCEED
currencyString(8)退款币种CNY
return_amountNumber(8,2)退款金额100.00

#异步通知示例

http://www.merchant.com/alipay/notify_url.php?sign=327fed8c8d07be26e2790e 216266f5a8&notify_time=2015-06-16 19:27:27&out_return_no=YNTK20150616 008&return_amount=10.00&sign_type=MD5&refund_status=REFUND_SUCCE SS&notify_type=refund_status_sync&notify_id=179ed48796486c67af63836465f 7733m6a&out_trade_no=2332688563037664&currency=USD

 Note:

  • 必须保证服务器异步通知页面(notify_url)上无任何字符,如空格、HTML标签、开发系统自带抛出的异常提示信息等。
  • 您可以使用GET方式获取该页面中的参数,如: request.Form("out_trade_no"), $_POST['out_trade_no'].
  • 支付宝主动发起通知,该方式才会被启用。
  • 只有在支付宝的交易管理中存在该笔交易,且发生了交易状态的改变,支付宝才会通过该方式发起服务器通知(即时到账中交易状态为“等待买家付款”的状态默认是不会发送通知的)。
  • 服务器间的交互,不像页面跳转同步通知可以在页面上显示出来,这种交互方式是不可见的。
  • 第一次交易状态改变(即时到账中此时交易状态是交易完成)时,不仅页面跳转同步通知页面会启用,而且服务器异步通知页面也会收到支付宝发来的处理结果通知。
  • 程序执行完后必须打印输出“success”(不包含引号)。如果商户反馈给支付宝的字符不是success这7个字符,支付宝服务器会不断重发通知,直到超过24小时22分钟。 一般情况下,25小时以内完成8次通知(通知的间隔频率一般是:2m,10m,10m,1h,2h,6h,15h)。
  • 程序执行完成后,该页面不能执行页面跳转。如果执行页面跳转,支付宝会收不到success字符,会被支付宝服务器判定为该页面程序运行出现异常,而重发处理结果通知。
  • cookies、session等在此页面会失效,即无法获取这些数据。
  • 该方式的调试与运行必须在服务器上,即互联网上能访问;
  • 该方式的作用主要防止订单丢失,即页面跳转同步通知没有处理订单更新,它则去处理;
  • 当商户收到服务器异步通知并打印出success时,服务器异步通知参数notify_id才会失效。也就是说在支付宝发送同一条异步通知时(包含商户并未成功打印出success导致支付宝重发数次通知),服务器异步通知参数notify_id是不变的。
  • 商户与支付宝约定后,异步通知可能会返回更多的参数信息。随着业务的发展,异步通知也可能有新的参数信息返回,商户在收到异步通知后,需要对支付宝所有的返回参数(除了sign_typesign)都参与验签,而不是只对上表中的参数参与验签。

#异步通知校验

为了系统的健康,支付宝建议校验异步通知。商家只能校验过去1分钟之内的异步通知消息,并且在商家服务器返回‘success’消息之前。 例如:

https://intlmapi.alipay.com/gateway.do? service=notify_verify&partner=2088101122136241&notify_id=+4465b04e84cb6bacc2bd1b52232c0b8gjg&sign=ciSBXc7gjCfXW8KMBxFiFH2cbMZtFelfTOGKqY2NF7q98RnH3E%2BiF5Cj%2Fu%2Bl8py1D%2FOsE%2FAva1ls8A6Tw1MzhG6ideJSgh4FxWmAjEnlczdfLj%2FqzA6qGzxdKGEXaSDFmTGglOembXUqK8g8ajICD%2BBH7xoxBRY7vtfylEXtojs%3D&sign_type=RSA


#错误代码

基本上API接口的调用的检查是在支付宝的2个级别进行的 


第一个级别是在支付宝网关。在这里会进行一些基础的校验,如签名,商家ID是否有效或者是否有权限使用某个接口等。如果校验失败,就会返回相应的错误码,归类在下面的网关错误中。 


一旦网关校验通过了,接口请求就会被转发到内部系统进行进一步的处理。 这里会进行业务逻辑的校验。如果校验失败,就会返回相应的错误码,归类在业务错误代码中。

#业务错误

错误代码含义
REFUNDMENT_VALID_DATE_EXCEED超过退款周期 不能退款
SYSTEM_EXCEPTION系统异常
ILLEGAL_ARGUMENT参数错误
REPEATED_REFUNDMENT_REQUEST重复退款请求
RETURN_AMOUNT_EXCEED退款金额超过支付金额
CURRENCY_NOT_SAME退款币种与支付币种不一致
PURCHASE_TRADE_NOT_EXIST交易不存在

BUYER_NOT_EXIST

买家不存在

REFUND_CHARGE_ERROR

支付进行中,退款失败。请稍后重试。

MORE_THAN_ALLOW_REFUND_FOREX_FEE

超过可退付汇金额

#网关错误

如果请求参数里面有错误,支付宝网关会报错。整个流程还是在支付宝这端而不会返回到商户端。

错误代码含义
ILLEGAL_SIGN签名错误
ILLEGAL_SERVICE接口参数不正确
ILLEGAL_PARTNER商户PID不对
ILLEGAL_SIGN_TYPE签名方法错误
ILLEGAL_PARTNER_EXTERFACE商家无权使用该接口
ILLEGAL_DYN_MD5_KEY动态密钥信息错误
ILLEGAL_ENCRYPT加密不正确
ILLEGAL_USER用户ID不正确
ILLEGAL_EXTERFACE接口配置错误
ILLEGAL_AGENT代理商不正确
HAS_NO_PRIVILEGE无权访问
INVALID_CHARACTER_SET字符集不正确

#系统错误

当出现系统错误提示时,请联系支付宝技术支持协助处理

错误代码含义
SYSTEM_ERROR支付宝系统错误
SESSION_TIMEOUTSession 超时
ILLEGAL_TARGET_SERVICE错误的target_service
ILLEGAL_ACCESS_SWITCH_SYSTEMpartner不允许访问该类型的系统
EXTERFACE_IS_CLOSED接口已关闭