异步通知说明 -凯发app官方网站

参数	类型	是否必填	最大长度	描述	示例值
notify_time	date	是	-	通知时间。通知的发送时间。格式为 yyyy-mm-dd hh:mm:ss。	2020-12-27 06:20:30
notify_type	string	是	64	通知类型。枚举值：trade_status_sync。	trade_status_sync
notify_id	string	是	128	通知校验 id。	ac05099524730693a8b330c5ecf72da9786
sign_type	string	是	10	签名类型。商家生成签名字符串所使用的签名算法类型，目前支持 rsa2 和 rsa，推荐使用 rsa2（如果开发者手动验签，不使用 sdk 验签，可以不传此参数）。	rsa2
sign	string	是	344	签名。可查看异步返回结果的验签（如果开发者手动验签，不使用 sdk 验签，可以不传此参数）。	601510b7970e52cc63db0f44997cf70e
trade_no	string	是	64	支付宝交易号。支付宝交易凭证号。	20213112011001004330000121536
app_id	string	是	32	开发者的 app_id。支付宝分配给开发者的应用 appid。	2014072300007148
auth_app_id	string	是	32	开发者的 app_id，在服务商调用的场景下为授权方的 app_id。	2014072300007148
out_trade_no	string	是	64	商户订单号。	6823789339978248
out_biz_no	string	否	64	商家业务号。商家业务 id，主要是退款通知中返回退款申请的流水号。	hzrf001
buyer_id（buyer_open_id）	string	否	128	买家支付宝用户号。买家支付宝账号对应的支付宝唯一用户号。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认应用-开发配置-openid配置管理已启用。无该配置项，可查看。	-
buyer_logon_id	string	否	100	买家支付宝账号。	180****0062
seller_id	string	否	30	卖家支付宝用户号。	2088101106499364
seller_email	string	否	100	卖家支付宝账号。	zhuzhanghu@alitest.com
trade_status	string	是	32	交易状态。咨询目前所处的状态。	trade_closed
total_amount	number	是	11	订单金额。本次交易支付的订单金额，单位为人民币（元）。支持小数点后两位。	20
receipt_amount	number	是	11	实收金额。商家在交易中实际收到的款项，单位为人民币（元）。支持小数点后两位。	15
invoice_amount	number	否	11	开票金额。用户在交易中支付的可开发票的金额。支持小数点后两位。	10.00
buyer_pay_amount	number	否	11	付款金额。用户在交易中支付的金额。支持小数点后两位。	13.88
point_amount	number	否	11	集分宝金额。使用集分宝支付的金额。支持小数点后两位。	12.00
refund_fee	number	否	11	总退款金额。退款通知中，返回总退款金额，单位为元，支持小数点后两位。	2.58
send_back_fee	number	否	11	实际退款金额。商家实际退款给用户的金额，单位为元，支持小数点后两位。	2.08
subject	string	否	256	订单标题。商品的标题/交易标题/订单标题/订单关键字等，是请求时对应的参数，原样通知回来。	xxx交易
body	string	否	400	商品描述。该订单的备注、描述、明细等。对应请求时的 body 参数，原样通知回来。	xxx交易内容
passback_params	string	否	512	公共回传参数，如果请求时传递了该参数，则返回给商家时会在异步通知时将该参数原样返回。本参数必须进行 urlencode 之后才可以发送给支付宝。	-
gmt_create	date	否	-	交易创建时间。该笔交易创建的时间。格式为 yyyy-mm-dd hh:mm:ss。	2015-04-27 15:45:57
gmt_payment	date	否	-	交易付款时间。该笔交易的买家付款时间。格式为 yyyy-mm-dd hh:mm:ss。	2015-04-27 15:45:57
gmt_refund	date	否	-	交易退款时间。该笔交易的退款时间。格式为 yyyy-mm-dd hh:mm:ss.ss。	2015-04-28 15:45:57.320
gmt_close	date	否	-	交易结束时间。该笔交易结束时间。格式为 yyyy-mm-dd hh:mm:ss。	2015-04-29 15:45:57
fund_bill_list	string	否	512	支付金额信息。支付成功的各个渠道金额信息，详请可查看下表资金明细信息说明。	[{"amount":"15.00", "fundchannel":"alipayaccount" }]
voucher_detail_list	string	否	-	优惠券信息。本交易支付时所使用的所有优惠券信息，详请可查看下表优惠券信息说明。	[{"amount":"0.20", "merchantcontribute":"0.00", "name":"一键创建券模板的券名称"， "othercontribute":"0.20", "type":"alipay_biz_voucher", "memo":"学生8折优惠" }]

3 交易状态说明

枚举名称	枚举说明
wait_buyer_pay	交易创建，等待买家付款。
trade_closed	未付款交易超时关闭，或支付完成后全额退款。
trade_success	交易支付成功。
trade_finished	交易结束，不可退款。

4 通知触发条件

触发条件名	触发条件描述	触发条件默认值
trade_finished	交易完成	true（触发通知）
trade_success	支付成功	true（触发通知）
trade_closed	交易关闭	true（触发通知）
wait_buyer_pay	交易创建	false（不触发通知）

5 资金明细信息说明

参数	类型	是否必填	最大长度	描述	示例值
fundchannel	string	否	-	支付渠道。详情可查看支付渠道说明。	alipayaccount
amount	string	否	11	支付金额。使用指定支付渠道支付的金额，单位为元。	15.00

6 优惠券信息说明

参数	类型	是否必填	最大长度	描述	示例值
voucherid	string	是	32	券 id	2015102600073002039000002d5o
templateid	string	否	64	券模板 id	20171030000730015359000emzp0
name	string	是	64	券名称	5 元代金券
type	string	是	32	优惠类型。当前支持以下几种主要类型： ●alipay_biz_voucher：商家全场券。 ●alipay_common_item_voucher：商家单品券。 ●alipay_cash_voucher：平台优惠券，支付宝或第三方出资。 ●alicredit_intfree_voucher：花呗分期券，该券仅做订单外的花呗分期费用减免，并不抵扣订单内支付金额。注意：不排除未来新增其它类型的可能，商家接入时请注意兼容性，避免硬编码。	alipay_biz_voucher
amount	number	是	11	优惠金额。优惠金额中，由商家出资的金额。	10.00
merchantcontribute	number	否	11	商家出资金额。优惠金额中，由商家出资的金额。	9.00
othercontribute	number	否	11	其他出资方出资金额。可能是支付宝，可能是品牌商，或者其他方，也可能是他们的共同出资。	1.00
othercontributedetail	contributedetail[]	否	-	优惠券的其他出资方明细	-
l contributetype	string	否	32	出资方类型，如品牌商出资、支付宝平台出资等。	platform
l contributeamount	number	否	8	出资方金额	0.18
memo	string	否	256	优惠券备注信息。	学生专用优惠

7 异步通知特性

在进行异步通知交互时，如果支付宝收到的应答不是

success

，支付宝会认为通知失败，会通过一定的策略定期重新发起通知。

通知的间隔频率为：4m、10m、10m、1h、2h、6h、15h

。

商家设置的异步地址（notify_url）需保证无任何字符，如空格、html 标签，且不能重定向。（如果重定向，

支付宝会收不到 success 字符，会被支付宝服务器判定为该页面程序运行出现异常，而重发处理结果通知

）

支付宝是用 post 方式发送通知信息，商户获取参数的方式如下：

request.form("out_trade_no")

、

$_post['out_trade_no']

。

支付宝针对同一条异步通知重试时，异步通知参数中的 notify_id 是不变的。

8 异步返回结果验签

某商家设置的通知地址为

https://api.xx.com/receive_notify.htm

，对应接收到通知的示例如下：

注意：

以下示例报文仅供参考，实际返回的详细报文请以实际返回为准。

第一步：

在通知返回参数列表中，除去

sign

、

sign_type

两个参数外，通知返回的参数均为待验签的参数。

第二步：

将剩下参数进行

urldecode

，然后进行字典排序，组成字符串，得到待签名字符串：

第三步：

将签名参数（sign）使用 base64 解码为字节码串。

第四步：

使用 rsa 的验签方法，通过签名字符串、签名参数（经过 base64 解码）及支付宝公钥验证签名。

第五步：在步骤四验证签名正确后，必须再严格按照如下描述校验通知数据的正确性。

商家需要验证该通知数据中的 out_trade_no 是否为商家系统中创建的订单号。

判断 total_amount 是否确实为该订单的实际金额（即商家订单创建时的金额）。

校验通知中的 seller_id（或者 seller_email ) 是否为 out_trade_no 这笔单据的对应的操作方（有的时候，一个商家可能有多个seller_id/seller_email）。

验证 app_id 是否为该商家本身。

上述 1、2、3、4 有任何一个验证不通过，则表明本次通知是异常通知，务必忽略。在上述验证通过后商家必须根据支付宝不同类型的业务通知，正确的进行不同的业务处理，并且过滤重复的通知结果数据。在支付宝的业务通知中，只有交易通知状态为 trade_success 或 trade_finished 时，支付宝才会认定为买家付款成功。

sdk接收以及验签示例代码（此处以 java 语言为例，按照服务端 sdk 中提供的工具类，注意区分公钥和公钥证书验签代码）：

注意：

●

状态

trade_success

的通知触发条件是商家开通的产品支持退款功能的前提下，买家付款成功。

●

交易状态

trade_finished

的通知触发条件是商家开通的产品不支持退款功能的前提下，买家付款成功或商家开通的产品支持退款功能的前提下，交易已经成功并且已经超过可退款期限。

●

响应值

响应值	描述	异步是否重试发送
fail	消息获取失败	重试
success	消息获取成功	不重试

相关问题