Skip to main content

异步通知

简介

异步通知是指当收银台调用 预下单 请求 API 生成二维码展示给用户后，用户通过手机扫描二维码进行支付，支付宝会将该笔订单的变更信息，沿着商户调用预下单请求时所传入的异步通知地址 notify_url，通过 POST 请求的形式将支付结果作为参数通知到商户系统。该异步通知主要作用于配置应用网关，详情请参见 配置应用环境。

异步回调地址状态码(http 状态码) 为 200 时表示异步通知成功，返回码为 404 或 500 时则表示服务器内部错误，需要商户自行排查。

商户如果因为其他原因没有收到支付宝服务端返回的异步通知，可根据 异步通知问题 进行排查。


异步通知参数


参数

类型

必填

描述

notify_time

Date

是

通知时间。通知的发送时间。格式为yyyy-MM-dd HH:mm:ss。

示例值：2011-12-27 06:30:30

notify_type

String(64)

是

通知类型。

示例值：trade_status_sync

notify_id

String(128)

是

通知校验 ID。

示例值：ac05099524730693a8b330c5ecf72da9786

sign_type

String(10)

是

签名类型。商户生成签名字符串所使用的签名算法类型，目前支持 RSA2 和 RSA，推荐使用 RSA2（如果开发者手动验签，不使用 SDK 验签，可以不传此参数）。

示例值：RSA2

sign

String(256)

是

签名。请参考异步返回结果的验签（如果开发者手动验签，不使用 SDK 验签，可以不传此参数）。

示例值：601510b7970e52cc63db0f44997cf70e

trade_no

String(64)

是

支付宝交易号。支付宝交易凭证号。

示例值：2013112011001004330000121536

app_id

String(32)

是

开发者的 app_id。支付宝分配给开发者的应用 APPID。

示例值：2014072300007148

out_trade_no

String(64)

是

商户订单号。原支付请求的商户订单号。

示例值：6823789339978248

out_biz_no

String(64)

否

商户业务号。商户业务 ID，主要是退款通知中返回退款申请的流水号。

示例值：HZRF001

buyer_id

String(16)

否

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

示例值：2088102122524333

buyer_logon_id

String(100)

否

买家支付宝账号。

示例值：15901825620

seller_id

String(30)

否

卖家支付宝用户号。

示例值：2088101106499364

seller_email

String(100)

否

卖家支付宝账号。

示例值：zhuzhanghu@alitest.com

trade_status

String(32)

是

交易状态。交易目前所处的状态。

示例值：TRADE_CLOSED

total_amount

Number(9,2)

是

订单金额。本次交易支付的订单金额，单位为人民币（元）。

示例值：20

receipt_amount

Number(9,2)

否

实收金额。商户在交易中实际收到的款项，单位为人民币（元）。

示例值：15

invoice_amount

Number(9,2)

否

开票金额。用户在交易中支付的可开发票的金额。

示例值：10.00

buyer_pay_amount

Number(9,2)

否

付款金额。用户在交易中支付的金额。

示例值：13.88

point_amount

Number(9,2)

否

集分宝金额。使用集分宝支付的金额。

示例值：12.00

refund_fee

Number(9,2)

否

总退款金额。退款通知中，返回总退款金额，单位为元，支持两位小数。

示例值：2.58

send_back_fee

Number(9,2)

否

实际退款金额。商户实际退款给用户的金额，单位为元，支持两位小数。

示例值：2.08

subject

String(256)

否

订单标题。商品的标题/交易标题/订单标题/订单关键字等，是请求时对应的参数，原样通知回来。

示例值：当面付交易

body

String(400)

否

商品描述。该订单的备注、描述、明细等。对应请求时的 body 参数，原样通知回来。

示例值：当面付交易内容

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.S。

示例值：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折优惠”}]


交易状态说明


枚举名称

枚举说明

WAIT_BUYER_PAY

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

TRADE_CLOSED

未付款交易超时关闭，或支付完成后全额退款。

TRADE_SUCCESS

交易支付成功。

TRADE_FINISHED

交易结束，不可退款。



通知触发条件


触发条件名

触发条件描述

触发条件默认值

TRADE_FINISHED

交易完成

false（不触发通知）

TRADE_SUCCESS

支付成功

true（触发通知）

WAIT_BUYER_PAY

交易创建

false（不触发通知）

TRADE_CLOSED

交易关闭

false（不触发通知）



资金明细信息说明


参数

类型

必填

参数说明

fundChannel

String

否

支付渠道。详情请参见 支付渠道说明。

示例值：ALIPAYACCOUNT

amount

String

否

支付金额。使用指定支付渠道支付的金额，单位为元。

示例值：15.00



支付渠道说明


支付渠道代码

支付渠道

COUPON

支付宝红包

ALIPAYACCOUNT

支付宝余额

POINT

集分宝

DISCOUNT

折扣券

PCARD

预付卡

FINANCEACCOUNT

余额宝

MCARD

商户储值卡

MDISCOUNT

商户优惠券

MCOUPON

商户红包

PCREDIT

蚂蚁花呗


优惠券信息说明

参数类型必填描述
nameString(64)是

券名称。

示例值：5 元代金券、5 折折扣券

typeString(32)是

优惠类型。当前支持以下几种主要类型：

  • ALIPAY_BIZ_VOUCHER：商家全场券。

  • ALIPAY_COMMON_ITEM_VOUCHER：商家单品券。

  • ALIPAY_CASH_VOUCHER：平台优惠券，支付宝或第三方出资。

  • ALICREDIT_INTFREE_VOUCHER：花呗分期券，该券仅做订单外的花呗分期费用减免，并不抵扣订单内支付金额。

注意：不排除未来新增其他类型的可能，商家接入时请注意兼容性，避免硬编码。


示例值：ALIPAY_BIZ_VOUCHER

amountNumber(9,2)是

优惠金额。优惠券在本次交易中抵扣的金额。

示例值：10.00

merchant_contributeNumber(9,2)否

商家出资金额。优惠金额中，由商家出资的金额。

示例值：9.00

other_contributeNumber(9,2)否

其他出资方出资金额。可能是支付宝，可能是品牌商，或者其他方，也可能是他们的共同出资。

示例值：1.00

memoString(256)否

优惠券备注信息。

示例值：学生专用优惠


异步返回结果示例

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







注意：第三方代商户调用支付接口得到的异步通知有所不同，会带上 auth_app_id，即第三方应用的 APPID；第三方代调用场景下，系统服务商收到的异步通知示例如下：


异步返回结果验签


  1. 在通知返回参数列表中，除去 sign、sign_type 两个参数外，凡是通知返回回来的参数皆是待验签的参数；

  2. 将剩下参数进行 url_decode, 然后进行字典排序，组成字符串，得到待签名字符串：

    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


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

  2. 使用 RSA/RSA2 的验签方法，通过签名字符串、签名参数（经过 base64 解码）及支付宝公钥验证签名；

  3. 需要严格按照如下描述校验通知数据的正确性：

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

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

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

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


注意：

  • 状态 TRADE_SUCCESS 的通知触发条件是商户签约的产品支持退款功能的前提下，买家付款成功。

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



服务器异步通知页面特性


  • 商户设置的异步地址必须是外网能够顺利访问到的地址，且不能是重定向的网址，并且保证服务器异步通知页面（notify_url）上无任何字符，如空格、HTML 标签、开发系统自带抛出的异常提示信息等。

  • 支付宝是用 POST 方式发送通知信息，因此该页面中获取参数的方式，如：request.Form("out_trade_no")、$_POST['out_trade_no']。

  • 支付宝主动发起通知，该方式才会被启用。

  • 只有在支付宝的交易管理中存在该笔交易，且发生了交易状态的改变，支付宝才会通过该方式发起服务器通知（即时到账中交易状态为“等待买家付款”的状态默认是不会发送通知的）。

  • 服务器间的交互，不像页面跳转同步通知可以在页面上显示出来，这种交互方式是不可见的。

  • 第一次交易状态改变（即时到账中此时交易状态是交易完成）时，不仅会返回同步处理结果，而且服务器异步通知页面也会收到支付宝发来的处理结果通知。

  • 程序执行完后必须通过 PrintWriter 类打印输出"success"（不包含引号）。如果商户反馈给支付宝的字符不是 success 这 7 个字符，支付宝服务器会不断重发通知，直到超过 24 小时 22 分钟。一般情况下，25 小时以内完成 8 次通知（通知的间隔频率一般是：4m,10m,10m,1h,2h,6h,15h）。

  • 程序执行完成后，该页面不能执行页面跳转。如果执行页面跳转，支付宝会收不到 success 字符，会被支付宝服务器判定为该页面程序运行出现异常，而重发处理结果通知。

  • cookies、session 等在此页面会失效，即无法获取这些数据。

  • 该方式的调试与运行必须在服务器上，即互联网上能访问。

  • 该方式的作用主要防止订单丢失，即页面跳转同步通知没有处理订单更新，它则去处理。

  • 当商户收到服务器异步通知并打印出 success 时，服务器异步通知参数 notify_id 才会失效。也就是说在支付宝发送同一条异步通知时（包含商户并未成功打印出 success 导致支付宝重发数次通知），服务器异步通知参数 notify_id 是不变的。

Back to top