即时到账

支付宝网页即时到账功能，可让用户在线向开发者的支付宝账号支付资金，交易资金即时到账，帮助开发者快速回笼资金。 

交易步骤少，简单、方便。 

交易资金三个月内可退款，提升买家购物保障。

本产品签约后，默认开通以下接口功能：

  • 即时到账交易接口(create_direct_pay_by_user)（DEMO下载）
  • 即时到账批量退款有密接口(refund_fastpay_by_platform_pwd)（DEMO下载）

 

签约方式

申请地址（即时到账收款）：https://b.alipay.com/order/productDetail.htm?productId=2015110218012942

提交申请后，会有一个审核阶段，审核通过才能使用该接口。

登录b.alipay.com->我的商家服务，可在“签约管理”中查看审核进度。

 

 

即时到账交易接口

请求参数说明

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

参数

参数名称

类型（字节长度）

参数说明

为空

样例

基本参数

service

接口名称

String

接口名称。

不可空

create_direct_pay_by_user

partner

合作者身份ID

String(16)

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

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

不可空

2088101011913539

_input_charset

参数编码字符集

String

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

不可空

GBK

sign_type

签名方式

String

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

不可空

MD5

sign

签名

String

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

不可空

7d314d22efba4f336fb187697793b9d2

notify_url

服务器异步通知页面路径

String(190)

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

可空

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

return_url

页面跳转同步通知页面路径

String(200)

支付宝处理完请求后，当前页面自动跳转到商户网站里指定页面的http路径。

可空

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

业务参数

out_trade_no

商户网站唯一订单号

String(64)

支付宝合作商户网站唯一订单号。

不可空

6843192280647118

subject

商品名称

String(256)

商品的标题/交易标题/订单标题/订单关键字等。

该参数最长为128个汉字。

不可空

贝尔金护腕式

payment_type

支付类型

String(4)

只支持取值为1（商品购买）。

不可空

1

total_fee

交易金额

Number

该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。

不可空

100

seller_id

卖家支付宝用户号

String(16)

  • seller_id是以2088开头的纯16位数字。
  • seller_email是支付宝登录账号，格式一般是邮箱或手机号。
  • seller_account_name是卖家支付宝账号别名。

三个参数至少必须传递一个。

当签约账号就是收款账号时，请务必使用参数seller_id，即seller_id的值与partner的值相同。

三个参数的优先级别是：seller_id>seller_account_name>seller_email。

不可空

2088002007018966

seller_email

卖家支付宝账号

String(100)

alipay-test01@alipay.com

seller_account_name

卖家支付宝账号别名

String(100)

tstable02@alipay.com

buyer_id

买家支付宝用户号

String(16)

  • buyer_id是以2088开头的纯16位数字。
  • buyer_email是支付宝登录账号，格式一般是邮箱或手机号。
  • buyer_account_name是买家支付宝账号别名。

三个参数的优先级别是：buyer_id>buyer_account_name>buyer_email。

可空

2088002007018955

buyer_email

买家支付宝账号

String(100)

tstable01@alipay.com

buyer_account_name

买家支付宝账号别名

String(100)

tstable03@alipay.com

price

商品单价

Number

单位为：RMB Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。此参数为单价

规则：price、quantity能代替total_fee。即存在total_fee，就不能存在price和quantity；存在price、quantity，就不能存在total_fee。

可空

10.00

quantity

购买数量

Number

price、quantity能代替total_fee。即存在total_fee，就不能存在price和quantity；存在price、quantity，就不能存在total_fee。

可空

1

body

商品描述

String(1000)

对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。

可空

美国专业护腕鼠标垫，舒缓式凝胶软垫模拟手腕的自然曲线和运动，创造和缓的GelFlex舒适地带！

show_url

商品展示网址

String(400)

收银台页面上，商品展示的超链接。

可空

http://www.360buy.com/product/113714.html

paymethod

默认支付方式

String

取值范围：

  • creditPay（信用支付）
  • directPay（余额支付）

如果不设置，默认识别为余额支付。

说明：

必须注意区分大小写。

可空

directPay

enable_paymethod

支付渠道

String

用于控制收银台支付渠道显示，该值的取值范围请参见支付渠道。

可支持多种支付渠道显示，以“^”分隔。

可空

directPay^bankPay^cartoon^cash

anti_phishing_key

防钓鱼时间戳

String

通过时间戳查询接口获取的加密支付宝系统时间戳。

如果已申请开通防钓鱼时间戳验证，则此字段必填。

可空

587FE3D2858E6B01E30104656E7805E2

exter_invoke_ip

客户端IP

String(15)

用户在创建交易时，该用户当前所使用机器的IP。

如果商户申请后台开通防钓鱼IP地址检查选项，此字段必填，校验用。

可空

128.214.222.111

extra_common_param

公用回传参数

String(100)

如果用户请求时传递了该参数，则返回给商户时会回传该参数。

可空

你好，这是测试商户的广告。

it_b_pay

超时时间

String

设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭。

取值范围：1m～15d。

m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。

该参数数值不接受小数点，如1.5h，可转换为90m。

可空

1h

token

快捷登录授权令牌

String(40)

如果开通了快捷登录产品，则需要填写；如果没有开通，则为空。

可空

201103290c9f9f2c03db4267a4c8e1bfe3adfd52

qr_pay_mode

扫码支付方式

String(1)

扫码支付的方式，支持前置模式和跳转模式。

前置模式是将二维码前置到商户的订单确认页的模式。需要商户在自己的页面中以iframe方式请求支付宝页面。具体分为以下4种：

  • 0：订单码-简约前置模式，对应iframe宽度不能小于600px，高度不能小于300px；
  • 1：订单码-前置模式，对应iframe宽度不能小于300px，高度不能小于600px；
  • 3：订单码-迷你前置模式，对应iframe宽度不能小于75px，高度不能小于75px。
  • 4：订单码-可定义宽度的嵌入式二维码，商户可根据需要设定二维码的大小。

跳转模式下，用户的扫码界面是由支付宝生成的，不在商户的域名下。

  • 2：订单码-跳转模式

可空

1

qrcode_width

商户自定二维码宽度

Integer

商户自定义的二维码宽度。

当qr_pay_mode=4时，该参数生效。

可空 200

need_buyer_realnamed

是否需要买家实名认证

String(2)

是否需要买家实名认证。

  • T表示需要买家实名认证；
  • 不传或者传其它值表示不需要买家实名认证。
可空  T

hb_fq_param

花呗分期参数

String

参数格式：hb_fq_seller_percent ^卖家承担付费比例|hb_fq_num ^期数。

  • hb_fq_num：花呗分期数，比如分3期支付；
  • hb_fq_seller_percent：卖家承担收费比例，比如100代表卖家承担100%。

两个参数必须一起传入。

两个参数用“|”间隔。Key和value之间用“^”间隔。

具体花呗分期期数和卖家承担收费比例可传入的数值请咨询支付宝。

可空 hb_fq_seller_percent^100|hb_fq_num^3

goods_type

商品类型

String(2)

商品类型：

  • 1表示实物类商品
  • 0表示虚拟类商品

如果不传，默认为实物类商品。

可空 1

https://mapi.alipay.com/gateway.do?body=%C3%C0%B9%FA%D7%A8%D2%B5%BB%A4%CD%F3%CA%F3%B1%EA%B5%E6%2C%CA%E6%BB%BA%CA%BD%C4%FD%BD%BA%C8%ED%B5%E6%C4%A3%C4%E2%CA%D6%CD%F3%B5%C4%D7%D4%C8%BB%C7%FA%CF%DF%BA%CD%D4%CB%B6%AF%A3%AC%B4%B4%D4%EC%BA%CD%BB%BA%B5%C4GelFlex%CA%E6%CA%CA%B5%D8%B4%F8%21&subject=%B1%B4%B6%FB%BD%F0%BB%A4%CD%F3%CA%BD&sign_type=MD5&notify_url=http%3A%2F%2Fapi.test.alipay.net&out_trade_no=6741334835157966&return_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_return.htm&sign=dc3d42f405d7e738ab35344449e2d9f7&buyer_id=2088002007018955&total_fee=100&service=create_direct_pay_by_user&partner=2088101568338364&seller_id=2088002007018966&payment_type=1&qr_pay_mode=1&_input_charset=gbk

 

说明：

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

 

注意：

  • 此接口只支持https请求；
  • 参数body（商品描述）、subject（商品名称）、extra_common_param（公用回传参数）不能包含特殊字符（如：#、%、&、+）、敏感词汇，也不能使用外国文字（旺旺不支持的外文，如：韩文、泰语、藏文、蒙古文、阿拉伯语）；
  • 请按照本文档“附录：签名与验签”中的签名方法对输入参数进行签名，该接口请求才能够被支付宝系统接收；
  • 此接口支持重复调用，前提是交易基本信息（买家、卖家、交易金额、超时时间等）在多次调用中保持一致，且交易尚未完成支付；
  • 配置qr_pay_mode为0或1或3或4的情况下，同步通知地址return_url需要传入商户中间跳转页面，即该页面需要实现让父页面自行跳转的功能，中间页面javascript代码：<script>window.parent.location.href='父页面调整的URL';</script>

 

页面跳转同步参数说明

支付宝对商户的请求数据处理完成后，会将处理的结果数据通过系统程序控制客户端页面自动跳转的方式通知给商户网站。这些处理结果数据就是页面跳转同步通知参数。

参数

参数名称

类型（字节长度）

参数说明

是否可为空

样例

is_success 成功标识 String(1) 表示接口调用是否成功，并不表明业务处理结果。 不可空 T
sign_type 签名方式 String DSA、RSA、MD5三个值可选，必须大写。 不可空 MD5
sign 签名 String(32) 请参见本文档“附录：签名与验签”。 不可空 b1af584504b8e845ebe40b8e0e733729
out_trade_no 商户网站唯一订单号 String(64) 对应商户网站的订单系统中的唯一订单号，非支付宝交易号。需保证在商户网站中的唯一性。是请求时对应的参数，原样返回。 可空 6402757654153618
subject 商品名称 String(256) 商品的标题/交易标题/订单标题/订单关键字等。 可空 手套
payment_type 支付类型 String(4) 只支持取值为1（商品购买）。 可空 1
exterface 接口名称 String 标志调用哪个接口返回的链接。 可空 create_direct_pay_by_user
trade_no 支付宝交易号 String(64) 该交易在支付宝系统中的交易流水号，最长64位，一般28位 可空 2014040311001004370000361525
trade_status 交易状态 String

交易目前所处的状态。成功状态的值只有两个：

  • TRADE_FINISHED（普通即时到账的交易成功状态）；
  • TRADE_SUCCESS（开通了高级即时到账或机票分销产品后的交易成功状态）
可空 TRADE_FINISHED
notify_id 通知校验ID String 支付宝通知校验ID，商户可以用这个流水号询问支付宝该条通知的合法性。 可空 RqPnCoPT3K9%2Fvwbh3I%2BODmZS9o4qChHwPWbaS7UMBJpUnBJlzg42y9A8gQlzU6m3fOhG
notify_time 通知时间 Date 通知时间（支付宝时间）。格式为yyyy-MM-dd HH:mm:ss。 可空 2008-10-23 13:17:39
notify_type 通知类型 String 返回通知类型。 可空 trade_status_sync
seller_email 卖家支付宝账号 String(100) 卖家支付宝账号，可以是Email或手机号码。 可空 chao.chenc1@alipay.com
buyer_email 买家支付宝账号 String(100) 买家支付宝账号，可以是Email或手机号码。 可空 tstable01@alipay.com
seller_id 卖家支付宝账户号 String(30) 卖家支付宝账号对应的支付宝唯一用户号。以2088开头的纯16位数字。 可空 2088002007018916
buyer_id 买家支付宝账户号 String(30) 买家支付宝账号对应的支付宝唯一用户号。以2088开头的纯16位数字。 可空 2088101000082594
total_fee 交易金额 Number 该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01,100000000.00]，精确到小数点后两位。 可空 10.00
body 商品描述 String(1000) 对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。 可空 Hello
extra_common_param 公用回传参数 String 用于商户回传参数，该值不能包含“=”、“&”等特殊字符。如果用户请求时传递了该参数，则返回给商户时会回传该参数。 可空 你好，这是测试商户的广告。

http://商户自定义地址/return_url.php?is_success=T&sign=b1af584504b8e845ebe40b8e0e733729&sign_type=MD5&body=Hello&buyer_email=xinjie_xj%40163.com&buyer_id=2088101000082594&exterface=create_direct_pay_by_user&out_trade_no=6402757654153618&payment_type=1&seller_email=chao.chenc1%40alipay.com&seller_id=2088002007018916&subject=%E5%A4%96%E9%83%A8FP&total_fee=10.00&trade_no=2014040311001004370000361525&trade_status=TRADE_FINISHED&notify_id=RqPnCoPT3K9%252Fvwbh3I%252BODmZS9o4qChHwPWbaS7UMBJpUnBJlzg42y9A8gQlzU6m3fOhG&notify_time=2008-10-23+13%3A17%3A39&notify_type=trade_status_sync&extra_common_param=%E4%BD%A0%E5%A5%BD%EF%BC%8C%E8%BF%99%E6%98%AF%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7%E7%9A%84%E5%B9%BF%E5%91%8A%E3%80%82

说明：

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

 

页面跳转同步通知页面特性

1. 用户在登录成功后会看到一个支付宝提示登录的页面，该页面会停留几秒，然后会自动跳转回商户指定的同步通知页面（参数return_url）。

2. 该页面中获得参数的方式，需要使用GET方式获取，如request.QueryString(“out_trade_no”)、$_GET[‘out_trade_no’]。后续商户可根据获取的信息作处理，譬如，可以把获取到的token放入session中，以便于后续需要使用到token访问支付宝相应服务时，可以便捷地重用。

3. 该方式仅仅在用户登录完成以后进行自动跳转，因此只会进行一次。

4. 该方式不是支付宝主动去调用商户页面，而是支付宝的程序利用页面自动跳转的函数，使用户的当前页面自动跳转。

5. 该方式可在本机而不是只能在服务器上进行调试。

6. 返回URL只有一分钟的有效期，超过一分钟该链接地址会失效，验证则会失败。

7. 设置页面跳转同步通知页面（return_url）的路径时，不要在页面文件的后面再加上自定义参数。例如：

错误的写法：http://www.alipay.com/alipay/return_url.php?xx=11

正确的写法：http://www.alipay.com/alipay/return_url.php

8. 由于支付宝会对页面跳转同步通知页面（return_url）的域名进行合法有效性校验，因此设置页面跳转同步通知页面（return_url）的路径时，不要设置成本机域名，也不能带有特殊字符（如“!”），如：

错误的写法：

http://localhost/alipay/return_url.php
http://localhost:80/alipay/return_url.php
http://商户自定义地址/alipay/return!url.do

正确的写法：

能够正常访问的域名地址：http://商户自定义地址/alipay/return_url.php

能够正常访问的IP地址：http://121.1.1.255/alipay/return_url.php

 

服务器异步通知参数说明

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

参数

参数名称

类型（字节长度）

参数说明

是否可为空

样例

基本参数

notify_time

通知时间

Date

通知的发送时间。

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

不可空

2009-08-12 11:08:32

notify_type

通知类型

String

通知的类型。

不可空

trade_status_sync

notify_id

通知校验ID

String

通知校验ID。

不可空

70fec0c2730b27528665af4517c27b95

sign_type

签名方式

String

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

不可空

DSA

sign

签名

String

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

不可空

_p_w_l_h_j0b_gd_aejia7n_ko4_m%2Fu_w_jd3_nx_s_k_mxus9_hoxg_y_r_lunli_pmma29_t_q%3D%

3D

业务参数

out_trade_no

商户网站唯一订单号

String(64)

对应商户网站的订单系统中的唯一订单号，非支付宝交易号。

需保证在商户网站中的唯一性。是请求时对应的参数，原样返回。

可空

3618810634349901

subject

商品名称

String(256)

商品的标题/交易标题/订单标题/订单关键字等。

它在支付宝的交易明细中排在第一列，对于财务对账尤为重要。是请求时对应的参数，原样通知回来。

可空

phone手机

payment_type

支付类型

String(4)

只支持取值为1（商品购买）。

可空

1

trade_no

支付宝交易号

String(64)

该交易在支付宝系统中的交易流水号。最长64位。

可空

2014040311001004370000361525

trade_status

交易状态

String

取值范围请参见交易状态。

可空

TRADE_FINISHED

gmt_create

交易创建时间

Date

该笔交易创建的时间。

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

可空

2008-10-22 20:49:31

gmt_payment

交易付款时间

Date

该笔交易的买家付款时间。

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

可空

2008-10-22 20:49:50

gmt_close

交易关闭时间

Date

交易关闭时间。

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

可空

2008-10-22 20:49:46

refund_status

退款状态

String

取值范围请参见退款状态。

可空

REFUND_SUCCESS

gmt_refund

退款时间

Date

卖家退款的时间，退款通知时会发送。

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

可空

2008-10-29 19:38:25

seller_email

卖家支付宝账号

String(100)

卖家支付宝账号，可以是email和手机号码。

可空

chao.chenc1@alipay.com

buyer_email

买家支付宝账号

String(100)

买家支付宝账号，可以是Email或手机号码。

可空

13758698870

seller_id

卖家支付宝账户号

String(30)

卖家支付宝账号对应的支付宝唯一用户号。

以2088开头的纯16位数字。

可空

2088002007018916

buyer_id

买家支付宝账户号

String(30)

买家支付宝账号对应的支付宝唯一用户号。

以2088开头的纯16位数字。

可空

2088002007013600

price

商品单价

Number

如果请求时使用的是total_fee，那么price等于total_fee；如果请求时使用的是price，那么对应请求时的price参数，原样通知回来。

可空

10.00

total_fee

交易金额

Number

该笔订单的总金额。

请求时对应的参数，原样通知回来。

可空

10.00

quantity

购买数量

Number

如果请求时使用的是total_fee，那么quantity等于1；如果请求时使用的是quantity，那么对应请求时的quantity参数，原样通知回来。

可空

1

body

商品描述

String(1000)

该笔订单的备注、描述、明细等。

对应请求时的body参数，原样通知回来。

可空

Hello

discount

折扣

Number

支付宝系统会把discount的值加到交易金额上，如果需要折扣，本参数为负数。

可空

-5

is_total_fee_adjust

是否调整总价

String(1)

该交易是否调整过价格。

可空

N

use_coupon

是否使用红包买家

String(1)

是否在交易过程中使用了红包。

可空

N

extra_common_param

公用回传参数

String

用于商户回传参数，该值不能包含“=”、“&”等特殊字符。

如果用户请求时传递了该参数，则返回给商户时会回传该参数。

可空

你好，这是测试商户的广告。

business_scene

是否扫码支付

String

回传给商户此标识为qrpay时，表示对应交易为扫码支付。

目前只有qrpay一种回传值。

非扫码支付方式下，目前不会返回该参数。

可空

qrpay

http://商户自定义地址/notify_url.php?trade_no=2014040311001004370000361525&out_trade_no=3618810634349901&discount=-5&payment_type=1&subject=iphone%E6%89%8B%E6%9C%BA&body=Hello&price=10.00&quantity=1&total_fee=10.00&trade_status=TRADE_FINISHED&refund_status=REFUND_SUCCESS&seller_email=chao.chenc1%40alipay.com&seller_id=2088002007018916&buyer_id=2088002007013600&buyer_email=13758698870&gmt_create=2008-10-22+20%3A49%3A31&is_total_fee_adjust=N&gmt_payment=2008-10-22+20%3A49%3A50&gmt_close=2008-10-22+20%3A49%3A46&gmt_refund=2008-10-29+19%3A38%3A25&use_coupon=N&notify_time=2009-08-12+11%3A08%3A32&notify_type=trade_status_sync&notify_id=70fec0c2730b27528665af4517c27b95&sign_type=DSA&sign=_p_w_l_h_j0b_gd_aejia7n_ko4_m%252Fu_w_jd3_nx_s_k_mxus9_hoxg_y_r_lunli_pmma29_t_q%253D%253D&extra_common_param=%E4%BD%A0%E5%A5%BD%EF%BC%8C%E8%BF%99%E6%98%AF%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B7%E7%9A%84%E5%B9%BF%E5%91%8A%E3%80%82

说明

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

 

服务器异步通知页面特性

  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是不变的。

 

通知触发条件

触发条件名

触发条件描述

触发条件默认值

TRADE_FINISHED

交易完成

true（触发通知）

TRADE_SUCCESS

支付成功

true（触发通知）

WAIT_BUYER_PAY

交易创建

false（不触发通知）

TRADE_CLOSED

交易关闭

false（不触发通知）

说明：商户可以向支付宝申请配置，是否触发各交易状态下的异步通知。

 

支付渠道

枚举名称

枚举说明

directPay

支付宝账户余额

cartoon

卡通

bankPay

网银

cash

现金

creditCardExpress

信用卡快捷

debitCardExpress

借记卡快捷

coupon

红包

point

积分

voucher

购物券

 

交易状态

枚举名称

枚举说明

WAIT_BUYER_PAY

交易创建，等待买家付款。

TRADE_CLOSED

在指定时间段内未支付时关闭的交易；

在交易完成全额退款成功时关闭的交易。

TRADE_SUCCESS

交易成功，且可对该交易做操作，如：多级分润、退款等。

TRADE_PENDING

等待卖家收款（买家付款后，如果卖家账号被冻结）。

TRADE_FINISHED

交易成功且结束，即不可再做任何操作

 

退款状态

枚举名称

枚举说明

REFUND_SUCCESS

退款成功：

全额退款情况：trade_status= TRADE_CLOSED，而refund_status=REFUND_SUCCESS

非全额退款情况：trade_status= TRADE_SUCCESS，而refund_status=REFUND_SUCCESS

REFUND_CLOSED

退款关闭

 

业务错误码

错误代码（error_code）

含义

SELLER_NOT_IN_SPECIFIED_SELLERS

抱歉，该收款账户不是指定的收款账户，请确认参数是否正确或咨询您的客户经理。

TRADE_SELLER_NOT_MATCH

抱歉，该笔交易的卖家已不存在，请联系正确的卖家重新创建交易进行付款。

TRADE_BUYER_NOT_MATCH

抱歉，您本次支付使用的账户与原先的不一致，请使用原来的账户，或重新创建交易付款。

ILLEGAL_FEE_PARAM

抱歉，金额传递错误，请确认参数是否正确或咨询您的客户经理。

SUBJECT_MUST_NOT_BE_NULL

商品名不能为空。

TRADE_PRICE_NOT_MATCH

抱歉，该商品的交易单价与原先的不一致，请重新创建交易付款。

TRADE_QUANTITY_NOT_MATCH

抱歉，该商品的购买数量与原先的不一致，请重新创建交易付款。

TRADE_TOTALFEE_NOT_MATCH

抱歉，该商品的交易金额与原先的不一致，请重新创建交易付款。

TRADE_NOT_ALLOWED_PAY

抱歉，您不能进行本次支付，请查看该交易是否已超时或已被关闭等。

DIRECT_PAY_WITHOUT_CERT_CLOSE

未开通非证书余额支付，无法完成支付。

FAIL_CREATE_CASHIER_PAY_ORDER

抱歉，系统异常，无法创建本次收银台支付订单，请稍后再试。

ILLEGAL_EXTRA_COMMON_PARAM

抱歉，接口通用回传参数格式不正确，请联系您的商户。

ILLEGAL_PAYMENT_TYPE

抱歉，接口传递的Payment_type参数错误，请联系您的商户。

NOT_SUPPORT_GATEWAY

抱歉，商户网关配置出错，请联系您的商户。

BUYER_SELLER_EQUAL

抱歉，买家和卖家不能是同一个账户。

SELLER_NOT_EXIST

抱歉，卖家账户经验证不存在，请联系您的商户。

ILLEGAL_ARGUMENT

抱歉，商户传递的接口参数错误，请联系您的商户。

TRADE_NOT_FOUND

根据交易号无法找到交易。

TRADE_GOOD_INFO_NOT_FOUND

根据交易号无法找到交易详情。

BUYER_EMAIL_ID_MUST_NULL

抱歉，该笔交易的买家账户必须为空，请联系您的商户。

PRODUCT_NOT_ALLOWED

您未开通此产品，暂时无法使用本服务。

ROYALTY_RECEIVER_NOT_IN_SPECIFIED_ACCOUNTS

抱歉，分润账号不是指定的分润账户，请确保该分润账户已签署分润协议。

ROYALTY_LENGTH_ERROR

抱歉，分润信息过长，不能超过1000个字符，请检查后重新集成。

DEFAULT_BANK_INVALID

您传递的默认网银参数不在规定的范围内。

DIS_NOT_SIGN_PROTOCOL

抱歉，您的分销商没有与支付宝签约，请联系您的商户。

SELF_TIMEOUT_NOT_SUPPORT

抱歉，商户没有开通自定义超时权限，请联系您的商户。

ILLEGAL_OUTTIME_ARGUMENT

抱歉，自定义超时时间设置错误，请联系您的商户。

EBANK_CERDIT_GW_RULE_NOT_OPEN

信用卡未签约（签约到期）或者接口参数未指定开通信用卡支付。

DIRECTIONAL_PAY_FORBIDDEN

付款受限，请确保收款方有权进行收款。

SELLER_ENABLE_STATUS_FORBID

卖家状态不正常。

ROYALTY_SELLER_ENABLE_STATUS_FORBID

抱歉，卖家暂时无法进行收款操作，请联系您的商户。

ROYALTY_SELLER_NOT_CERTIFY

抱歉，卖家尚未通过认证，不能进行收款，请联系您的商户。

ROYALTY_FORAMT_ERROR

抱歉，接口传递的分润参数格式错误，请检查后重新集成。

ROYALTY_TYPE_ERROR

抱歉，接口传递的分润类型错误，请检查后重新集成。

ROYALTY_RECEIVE_EMAIL_NOT_EXIST

抱歉，分润账户经验证不存在，请联系您的商户。

ROYALTY_RECEIVE_EMAIL_NOT_CERTIFY

抱歉，分润账户经验证未通过人行验证，请联系您的商户。

ROYALTY_PAY_EMAIL_NOT_EXIST

抱歉，分润付款账户经验证不存在，请联系您的商户。

TAOBAO_ANTI_PHISHING_CHECK_FAIL

抱歉，无法付款! 该笔交易可能存在风险，如果您确定本次交易没有问题，请1个小时后再付款。

SUBJECT_HAS_FORBIDDENWORD

抱歉，无法付款! 请联系商户修改商品名称，再重新购买。

PAY_CHECK_FAIL

抱歉，付款失败! 该笔交易可能存在风险。

BODY_HAS_FORBIDDENWORD

抱歉，无法付款! 请联系商户修改商品描述，再重新购买。

NEED_CTU_CHECK_PARAMETER_ERROR

抱歉，您传递的商户可信任参数权限参数错误。

NEED_CTU_CHECK_NOT_ALLOWED

抱歉，商户没有可信任参数校验的权限。

BUYER_NOT_EXIST

抱歉，买家账户经验证不存在。

HAS_NO_PRIVILEGE

你的当前访问记录丢失，请返回商户网站重新发起付款。

 

 

即时到账有密退款接口

请求参数说明

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

参数

参数名称

类型（长度范围）

参数说明

是否可为空

样例

基本参数

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次（第一次退1/10，第二次退1/5，第三次退1/2），需要遵守多次退款的总金额不超过该笔交易付款金额的原则。

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

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

 

 

参考推荐：

支付宝即时到账 （官网）

支付宝技术集成服务

支付宝接口付款/退款详细逻辑流程

支付宝、财付通、网银、快钱接口的收费费率 （推荐）