文档中心 > 手机网站支付

即时到账有密退款接口

更新时间:2017/07/26 访问次数:85904

请求参数说明

请求参数是商户在与支付宝进行数据交互时,提供给支付宝的请求数据,以便支付宝根据这些数据进一步处理。

参数

参数名称

类型(长度范围)

参数说明

是否可为空

样例

基本参数

service

接口名称

String

接口名称。

不可空

refund_fastpay_by_p

latform_pwd

partner

合作者身份ID

String(16)

签约的支付宝账号对应的支付宝唯一用户号。

以2088开头的16位纯数字组成。

不可空

2088101008267254

_input_charset

参数编码字符集

String

商户网站使用的编码格式,如UTF-8、GBK、GB2312等。

不可空

GBK

sign_type

签名方式

String

DSA、RSA、MD5三个值可选,必须大写。

不可空

MD5

sign

签名

String

请参见本文档“附录:签名与验签”。

不可空

tphoyf4aoio5e6zxoaydjevem2c1s1zo

notify_url

服务器异步通知页面路径

String(200)

支付宝服务器主动通知商户网站里指定的页面http路径。

可空

http://api.test.alipay.net/atinterface/receive_notify.htm

业务参数

seller_email

卖家支付宝账号

String

  • seller_user_id是以2088开头的纯16位数字。
  • seller_email是支付宝登录账号,格式一般是邮箱或手机号。

登录时,seller_email和seller_user_id两者必填一个。如果两者都填,以seller_user_id为准。

不可空

Jier1105@alitest.com

seller_user_id

卖家用户ID

String

2088101008267254

refund_date

退款请求时间

String

退款请求的当前时间。

格式为:yyyy-MM-dd HH:mm:ss。

不可空

2011-01-12 11:21:00

batch_no

退款批次号

String

每进行一次即时到账批量退款,都需要提供一个批次号,通过该批次号可以查询这一批次的退款交易记录,对于每一个合作伙伴,传递的每一个批次号都必须保证唯一性。

格式为:退款日期(8位)+流水号(3~24位)。

不可重复,且退款日期必须是当天日期。流水号可以接受数字或英文字符,建议使用数字,但不可接受“000”。

不可空

201101120001

batch_num

总笔数

String

即参数detail_data的值中,“#”字符出现的数量加1,最大支持1000笔(即“#”字符出现的最大数量为999个)。

不可空

1

detail_data

单笔数据集

String

退款请求的明细数据。

格式详情参见下面的“单笔数据集参数说明”。

不可空

2014040311001004370000361525^5.00^协商退款

单笔数据集参数说明

  • 单笔数据集格式为:第一笔交易退款数据集#第二笔交易退款数据集#第三笔交易退款数据集…#第N笔交易退款数据集;
  • 交易退款数据集的格式为:原付款支付宝交易号^退款总金额^退款理由;
  • 不支持退分润功能。

单笔数据集(detail_data)注意事项

  • detail_data中的退款笔数总和要等于参数batch_num的值;
  • “退款理由”长度不能大于256字节,“退款理由”中不能有“^”、“|”、“$”、“#”等影响detail_data格式的特殊字符;
  • detail_data中退款总金额不能大于交易总金额;
  • 一笔交易可以多次退款,退款次数最多不能超过99次,需要遵守多次退款的总金额不超过该笔交易付款金额的原则。
https://mapi.alipay.com/gateway.do?seller_email=Jier1105%40alitest.com&batch_num=1&refund_date=2011-01-12+11%3A21%3A00&notify_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_notify.htm&sign=9b3426cac65d36f64bffbfbc6ce50549&service=refund_fastpay_by_platform_pwd&partner=2088101008267254&detail_data=2014040311001004370000361525%5E5.00%5E%D0%AD%C9%CC%CD%CB%BF%EE&sign_type=MD5&batch_no=201101120001

说明:

本样例仅供参考,支付宝网关为https://mapi.alipay.com/gateway.do

服务器异步通知参数说明

支付宝对商户的请求数据处理完成后,会将处理的结果数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。

参数

参数名称

类型(长度范围)

参数说明

是否可为空

样例

基本参数

notify_time

通知时间

Date

通知发送的时间。

格式为:yyyy-MM-dd HH:mm:ss。

不可空

2009-08-12 11:08:32

notify_type

通知类型

String

通知的类型。

不可空

batch_refund_notify

notify_id

通知校验ID

String

通知校验ID。

不可空

70fec0c2730b27528665af4517c27b95

sign_type

签名方式

String

DSA、RSA、MD5三个值可选,必须大写。

不可空

MD5

sign

签名

String

请参见本文档“附录:签名与验签”。

不可空

b7baf9af3c91b37bef4261849aa76281

业务参数

batch_no

退款批次号

String

原请求退款批次号。

不可空

20060702001

success_num

退款成功总数

String

退交易成功的笔数。

0<= success_num<= 总退款笔数。

不可空

2

result_details

退款结果明细

String

退款结果明细。

  • 退手续费结果返回格式:交易号^退款金额^处理结果$退费账号^退费账户ID^退费金额^处理结果;
  • 不退手续费结果返回格式:交易号^退款金额^处理结果。

若退款申请提交成功,处理结果会返回“SUCCESS”。

若提交失败,退款的处理结果中会有报错码,参见业务错误码

不可空

2014040311001004370000361525^80^SUCCESS$jax_chuanhang@alipay.com^2088101003147483^0.01^SUCCESS

http://商户自定义地址/alipay/notify_url.php?notify_time=2009-08-12+11%3A08%3A32&notify_type=batch_refund_notify&notify_id=70fec0c2730b27528665af4517c27b95&sign_type=MD5&sign=_p_w_l_h_j0b_gd_aejia7n_ko4_m%252Fu_w_jd3_nx_s_k_mxus9_hoxg_y_r_lunli_pmma29_t_q%3D%3D&batch_no=20060702001&success_num=2&result_details=2014040311001004370000361525%5E80%5ESUCCESS

说明:

本样例仅供参考,实际网关为商户域名。

通知触发条件

触发条件名

触发条件描述

触发条件默认值

退款处理结束

退款处理结束。

true(触发通知)

服务器异步通知页面特性

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

业务错误码

错误代码(error_code)

含义

ILLEGAL_USER

用户ID不正确

BATCH_NUM_EXCEED_LIMIT

总比数大于1000

REFUND_DATE_ERROR

错误的退款时间

BATCH_NUM_ERROR

传入的总笔数格式错误

BATCH_NUM_NOT_EQUAL_TOTAL

传入的退款条数不等于数据集解析出的退款条数

SINGLE_DETAIL_DATA_EXCEED_LIMIT

单笔退款明细超出限制

NOT_THIS_SELLER_TRADE

不是当前卖家的交易

DUBL_TRADE_NO_IN_SAME_BATCH

同一批退款中存在两条相同的退款记录

DUPLICATE_BATCH_NO

重复的批次号

TRADE_STATUS_ERROR

交易状态不允许退款

BATCH_NO_FORMAT_ERROR

批次号格式错误

SELLER_INFO_NOT_EXIST

卖家信息不存在

PARTNER_NOT_SIGN_PROTOCOL

平台商未签署协议

NOT_THIS_PARTNERS_TRADE

退款明细非本合作伙伴的交易

DETAIL_DATA_FORMAT_ERROR

数据集参数格式错误

PWD_REFUND_NOT_ALLOW_ROYALTY

有密接口不允许退分润

NANHANG_REFUND_CHARGE_AMOUNT_ERROR

退票面价金额不合法

REFUND_AMOUNT_NOT_VALID

退款金额不合法

TRADE_PRODUCT_TYPE_NOT_ALLOW_REFUND

交易类型不允许退交易

RESULT_FACE_AMOUNT_NOT_VALID

退款票面价不能大于支付票面价

REFUND_CHARGE_FEE_ERROR

退收费金额不合法

REASON_REFUND_CHARGE_ERR

退收费失败

RESULT_AMOUNT_NOT_VALID

退收费金额错误

RESULT_ACCOUNT_NO_NOT_VALID

账号无效

REASON_TRADE_REFUND_FEE_ERR

退款金额错误

REASON_HAS_REFUND_FEE_NOT_MATCH

已退款金额错误

TXN_RESULT_ACCOUNT_STATUS_NOT_VALID

账户状态无效

TXN_RESULT_ACCOUNT_BALANCE_NOT_ENOUGH

账户余额不足

REASON_REFUND_AMOUNT_LESS_THAN_COUPON_FEE

红包无法部分退款

BUYER_ERROR

因买家支付宝账户问题不允许退款

FAQ

关于此文档暂时还没有FAQ
返回
顶部