异步通知说明

使用说明

异步通知是指一笔订单支付完成后，支付宝会将该笔订单的变更信息，沿着商家调用支付请求时传入的异步通知地址 notify_url，通过 POST 请求将支付结果作为参数通知到商家系统。

异步回调地址状态码（HTTP 状态码）为 200 时表示异步通知成功；返回码为 404 或 500 时表示服务器内部错误，需要商家自行排查。

注意事项

异步通知参数

参数	类型	是否必选	最大长度	描述	注意事项/枚举值	示例值
notify_time	Date	必选	-	通知发送时间，格式为 yyyy-MM-dd HH:mm:ss。	-	2020-12-27 06:20
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	商家业务号，主要是退款通知中返回退款申请的流水号。	-	HZRF001
buyer_id / buyer_open_id	String	可选	128	买家支付宝用户号或买家支付宝 open_id。	新商户建议使用 buyer_open_id 替代 buyer_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
gmt_payment	Date	可选	-	交易付款时间，格式为 yyyy-MM-dd HH:mm:ss。	-	2015-04-27 15:45
gmt_refund	Date	可选	-	交易退款时间，格式为 yyyy-MM-dd HH:mm:ss.SS。	-	2015-04-28 15:45 .320
gmt_close	Date	可选	-	交易结束时间，格式为 yyyy-MM-dd HH:mm:ss。	-	2015-04-29 15:45
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折优惠"}]

交易状态说明

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

通知触发条件

触发条件名	触发条件描述	触发条件默认值
TRADE_FINISHED	交易完成	true（触发通知）
TRADE_SUCCESS	支付成功	true（触发通知）
TRADE_CLOSED	交易关闭	true（触发通知）
WAIT_BUYER_PAY	交易创建	false（不触发通知）

资金明细信息说明

参数	类型	是否必选	最大长度	描述	注意事项/枚举值	示例值
fundChannel	String	可选	-	支付渠道。	详情可查看支付渠道说明。	ALIPAYACCOUNT
amount	String	可选	11	支付金额，使用指定支付渠道支付的金额，单位为元。	-	15.00

优惠券信息说明

参数	类型	是否必选	最大长度	描述	注意事项/枚举值	示例值
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[]	可选	-	优惠券的其他出资方明细。	子字段见下方 otherContributeDetail[]。	-
otherContributeDetail[].contributeType	String	可选	32	出资方类型。	如品牌商出资、支付宝平台出资等。	PLATFORM
otherContributeDetail[].contributeAmount	Number	可选	8	出资方金额。	-	0.18
memo	String	可选	256	优惠券备注信息。	-	学生专用优惠

异步通知特性

1. 在进行异步通知交互时，如果支付宝收到的应答不是 success，支付宝会认为通知失败，并通过一定策略定期重新发起通知。通知间隔频率为：4m、10m、10m、1h、2h、6h、15h。
2. 商家设置的异步通知地址 notify_url 需保证无任何多余字符，如空格、HTML 标签，且不能重定向。若发生重定向，支付宝会收不到 success 字符，可能判定页面程序运行异常并重新发送通知。
3. 支付宝使用 POST 方式发送通知信息，商户可通过 request.Form("out_trade_no")、$_POST['out_trade_no'] 等方式获取参数。
4. 支付宝针对同一条异步通知重试时，异步通知参数中的 notify_id 不变。

异步返回结果验签

某商家设置的通知地址为 https://api.xx.com/receive_notify.htm，对应接收到通知的示例如下。

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

https://api.xx.com/receive_notify.htm?gmt_payment=2015-06-11 22:33:59&notify_id=42af7baacd1d3746cf7b56752b91edcj34&seller_email=testyufabu07@alipay.com&notify_type=trade_status_sync&sign=kPbQIjX+xQc8F0/A6/AocELIjhhZnGbcBN6G4MM/HmfWL4ZiHM6fWl5NQhzXJusaklZ1LFuMo+lHQUELAYeugH8LYFvxnNajOvZhuxNFbN2LhF0l/KL8ANtj8oyPM4NN7Qft2kWJTDJUpQOzCzNnV9hDxh5AaT9FPqRS6ZKxnzM=&trade_no=2015061121001004400068549373&out_trade_no=21repl2ac2eOutTradeNo322&gmt_create=2015-06-11 22:33:46&seller_id=2088211521646673&notify_time=2015-06-11 22:34:03&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_status=TRADE_SUCCESS&sign_type=RSA2

验签步骤如下：

1. 在通知返回参数列表中，除去 sign、sign_type 两个参数外，通知返回的参数均为待验签参数。
2. 将剩余参数进行 URLDecode，然后按字典排序组成字符串，得到待签名字符串：

gmt_create=2015-06-11 22:33:46&gmt_payment=2015-06-11 22:33:59&notify_id=42af7baacd1d3746cf7b56752b91edcj34&notify_time=2015-06-11 22:34:03&notify_type=trade_status_sync&out_trade_no=21repl2ac2eOutTradeNo322&seller_email=testyufabu07@alipay.com&seller_id=2088211521646673&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_no=2015061121001004400068549373&trade_status=TRADE_SUCCESS

3. 将签名参数 sign 使用 base64 解码为字节码串。
4. 使用 RSA 验签方法，通过签名字符串、签名参数（经过 base64 解码）及支付宝公钥验证签名。
5. 在步骤四验证签名正确后，必须再严格校验通知数据的正确性：

校验项	校验说明
out_trade_no	校验通知数据中的 out_trade_no 是否为商家系统中创建的订单号。
total_amount	判断 total_amount 是否确实为该订单的实际金额，即商家订单创建时的金额。
seller_id / seller_email	校验通知中的 seller_id 或 seller_email 是否为 out_trade_no 这笔单据的对应操作方。
app_id	验证 app_id 是否为该商家本身。

上述任一校验项不通过，则表明本次通知是异常通知，务必忽略。

上述校验通过后，商家必须根据支付宝不同类型的业务通知进行业务处理，并过滤重复通知结果数据。在支付宝的业务通知中，只有交易通知状态为 TRADE_SUCCESS 或 TRADE_FINISHED 时，支付宝才会认定为买家付款成功。

SDK 接收以及验签示例代码如下。此处以 Java 语言为例，按照服务端 SDK 中提供的工具类，注意区分公钥和公钥证书验签代码。

// 获取支付宝 POST 过来反馈信息，将异步通知中收到的待验证所有参数都存放到 map 中。
Map<String, String> params = new HashMap<String, String>();
Map requestParams = request.getParameterMap();
for (Iterator iter = requestParams.keySet().iterator(); iter.hasNext();) {
    String name = (String) iter.next();
    String[] values = (String[]) requestParams.get(name);
    String valueStr = "";
    for (int i = 0; i < values.length; i++) {
        valueStr = (i == values.length - 1) ? valueStr + values[i] : valueStr + values[i] + ",";
    }
    // 乱码解决，这段代码在出现乱码时使用。
    // valueStr = new String(valueStr.getBytes("ISO-8859-1"), "utf-8");
    params.put(name, valueStr);
}

// 调用 SDK 验证签名。
// 公钥验签示例代码：
boolean signVerified = AlipaySignature.rsaCheckV1(params, ALIPAY_PUBLIC_KEY, CHARSET, sign_type);

// 公钥证书验签示例代码：
// boolean flag = AlipaySignature.rsaCertCheckV1(params, alipayPublicCertPath, "UTF-8", "RSA2");

if (signVerified) {
    // TODO 验签成功后，按照支付结果异步通知中的描述，对支付结果中的业务内容进行 1/2/3/4 二次校验。
    // 校验成功后在 response 中返回 success。
} else {
    // TODO 验签失败则记录异常日志，并在 response 中返回 fail。
}

注意：

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

响应值

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

异步通知触发时机和通知参数说明

注意：如果签约不支持退款，或者定制了异步通知的触发条件和通知字段，则本节说明不适用。

在交易支付成功、交易关单、交易退款、交易分账等场景下都可能触发异步通知。各场景的关键通知参数区分如下：

场景	通知参数特征
用户支付成功通知	trade_status=TRADE_SUCCESS，且不包含 out_biz_no 字段。
退款成功通知	通知参数包含 gmt_refund、refund_fee、out_biz_no 字段，其中 out_biz_no 为退款请求号。
交易未支付超时关单通知	通知参数包含 gmt_close、refund_fee 字段，其中 refund_fee=0、trade_status=TRADE_CLOSED。如果用户在收银台没有点击过提交支付，则不会真正创建交易，该场景下不会有未支付超时关单通知。
交易分账成功通知	通知参数包含 out_biz_no 字段，其中 out_biz_no 为分账请求号。