基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(免确认模式)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
微信支付分(公共API)
支付即服务
行业方案
智慧商圈
微信支付分停车服务
营销工具
代金券
商家券
委托营销
消费卡
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
付款
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传

支付通知API

最新更新时间:2020.05.26 版本说明


微信支付通过支付通知接口将用户支付成功消息通知给商户

注意:

• 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。

• 如果在所有通知频率(4小时)后没有收到微信侧回调,商户应调用查询订单接口确认订单状态。


特别提醒:商户系统对于开启结果通知的内容一定要做签名验证,并校验通知的信息是否与商户侧的信息一致,防止数据泄漏导致出现“假通知”,造成资金损失。

接口说明

适用对象: 服务商

回调URL:该链接是通过统一下单接口中的请求参数“notify_url”来设置的,要求必须为https地址。请确保回调URL是外部可正常访问的,且不能携带后缀参数,否则可能导致商户无法接收到微信的回调通知信息。回调URL示例: “https://pay.weixin.qq.com/wxpay/pay.action”

通知规则

用户支付完成后,微信会把相关支付结果和用户信息发送给商户,商户需要接收处理该消息,并返回应答。

对后台通知交互时,如果微信收到商户的应答不符合规范或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)

通知报文

支付结果通知是以POST 方法访问商户设置的通知url,通知的数据以JSON 格式通过请求主体(BODY)传输。通知的数据包括了加密的支付结果详情。


下面详细描述对通知数据进行解密的流程:

  1. 1、用商户平台上设置的APIv3密钥【微信商户平台—>账户设置—>API安全—>设置APIv3密钥】,记为key;
  2. 2、针对resource.algorithm中描述的算法(目前为AEAD_AES_256_GCM),取得对应的参数nonce和associated_data;
  3. 3、使用key、nonce和associated_data,对数据密文resource.ciphertext进行解密,得到JSON形式的资源对象;

注: AEAD_AES_256_GCM算法的接口细节,请参考rfc5116。微信支付使用的密钥key长度为32个字节,随机串nonce长度12个字节,associated_data长度小于16个字节并可能为空。

通知参数

参数名 变量 类型[长度限制] 必填 描述
通知ID id string[1,32] 通知的唯一ID
示例值:EV-2018022511223320873
通知创建时间 create_time string[1,16] 通知创建的时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示北京时间2015年05月20日13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
通知类型 event_type string[1,32] 通知的类型,支付成功通知的类型为TRANSACTION.SUCCESS
示例值:TRANSACTION.SUCCESS
通知数据类型 resource_type string[1,32] 通知的资源数据类型,支付成功通知为encrypt-resource
示例值:encrypt-resource
+通知数据 resource object 通知资源数据
json格式,见示例
参数名 变量 类型[长度限制] 必填 描述
加密算法类型 algorithm string[1,32] 对开启结果数据进行加密的加密算法,目前只支持AEAD_AES_256_GCM
示例值:AEAD_AES_256_GCM
数据密文 ciphertext string[1,1048576] Base64编码后的开启/停用结果数据密文
示例值:sadsadsadsad
附加数据 associated_data string[1,16] 附加数据
示例值:fdasfwqewlkja484w
原始类型 original_type string[1,16] 原始回调类型,为transaction
示例值:transaction
随机串 nonce string[1,16] 加密使用的随机串
示例值:fdasflkja484w
回调摘要 summary string[1,64] 回调摘要
示例值:支付成功

通知签名

加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名,并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名,以确认请求来自微信,而不是其他的第三方。签名验证的算法请参考微信支付APIv3签名方案

回调示例

支付成功结果通知


{
    "id":"EV-2018022511223320873",
    "create_time":"2015-05-20T13:29:35+08:00",
    "resource_type":"encrypt-resource",
    "event_type":"TRANSACTION.SUCCESS",
    "resource":{
        "algorithm":"AEAD_AES_256_GCM",
        "ciphertext":"...",
        "nonce":"...",
        "original_type":"transaction",
        "associated_data":""
    },
    "summary":"支付成功"
}

商户对resource对象进行解密后,得到的资源对象示例


{
    "transaction_id":"1217752501201407033233368018",
    "amount":{
        "payer_total":100,
        "total":100,
        "currency":"CNY",
        "payer_currency":"CNY"
    },
    "mchid":"1230000109",
    "trade_state":"SUCCESS",
    "bank_type":"CMC",
    "promotion_detail":[
        {
            "amount":100,
            "wechatpay_contribute":0,
            "coupon_id":"109519",
            "scope":"GLOBALSINGLE",
            "merchant_contribute":0,
            "name":"单品惠-6",
            "other_contribute":0,
            "currency":"CNY",
            "type":"CASHNOCASH",
            "stock_id":"931386",
            "goods_detail":[
                {
                    "goods_remark":"商品备注信息",
                    "quantity":1,
                    "discount_amount":1,
                    "goods_id":"M1006",
                    "unit_price":100
                },
                {
                    "goods_remark":"商品备注信息",
                    "quantity":1,
                    "discount_amount":1,
                    "goods_id":"M1006",
                    "unit_price":100
                }
            ]
        },
        {
            "amount":100,
            "wechatpay_contribute":0,
            "coupon_id":"109519",
            "scope":"GLOBALSINGLE",
            "merchant_contribute":0,
            "name":"单品惠-6",
            "other_contribute":0,
            "currency":"CNY",
            "type":"CASHNOCASH",
            "stock_id":"931386",
            "goods_detail":[
                {
                    "goods_remark":"商品备注信息",
                    "quantity":1,
                    "discount_amount":1,
                    "goods_id":"M1006",
                    "unit_price":100
                },
                {
                    "goods_remark":"商品备注信息",
                    "quantity":1,
                    "discount_amount":1,
                    "goods_id":"M1006",
                    "unit_price":100
                }
            ]
        }
    ],
    "success_time":"2018-06-08T10:34:56+08:00",
    "payer":{
        "openid":"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
    },
    "out_trade_no":"1217752501201407033233368018",
    "appid":"wxd678efh567hg6787",
    "trade_state_desc":"支付失败,请重新下单支付",
    "trade_type":"MICROPAY",
    "attach":"自定义数据",
    "scene_info":{
        "device_id":"013467007045764"
    }
}

支付成功通知参数

参数名 变量 类型[长度限制] 必填 描述
服务商应用ID sp_appid string[1,32] 服务商申请的公众号或移动应用appid。
示例值:wx8888888888888888
服务商户号 sp_mchid string[1,32] 服务商户号,由微信支付生成并下发
示例值:1230000109
子商户应用ID sub_appid string[1,32] 子商户申请的公众号或移动应用appid。
示例值:wxd678efh567hg6999
子商户号 sub_mchid string[1,32] 子商户的商户号,有微信支付生成并下发。
示例值:1900000109
商户订单号 out_trade_no string[1,32] 商户系统内部订单号,只能是数字、大小写字母_-*且在同一个商户号下唯一。
特殊规则:最小字符长度为6
示例值:1217752501201407033233368018
微信支付订单号 transaction_id string[1,32] 微信支付系统生成的订单号。
示例值:1217752501201407033233368018
交易类型 trade_type string[1,16] 交易类型,枚举值:
JSAPI:公众号支付
NATIVE:扫码支付
APP:APP支付
MICROPAY:付款码支付
MWEB:H5支付
FACEPAY:刷脸支付
示例值:MICROPAY
交易状态 trade_state string[1,32] 交易状态,枚举值:
SUCCESS:支付成功
REFUND:转入退款
NOTPAY:未支付
CLOSED:已关闭
REVOKED:已撤销(付款码支付)
USERPAYING:用户支付中(付款码支付)
PAYERROR:支付失败(其他原因,如银行返回失败)
示例值:SUCCESS
交易状态描述 trade_state_desc string[1,256] 交易状态描述
示例值:支付失败,请重新下单支付
付款银行 bank_type string[1,16] 银行类型,采用字符串类型的银行标识。银行标识请参考《银行类型对照表
示例值:CMC
附加数据 attach string[1,128] 附加数据,在查询API和支付通知中原样返回,可作为自定义参数使用
示例值:自定义数据  
支付完成时间 success_time string[1,64] 支付完成时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2018-06-08T10:34:56+08:00
+支付者 payer object 支付者信息
参数名 变量 类型[长度限制] 必填 描述
用户服务标识 sp_openid string[1,128] 用户在服务商appid下的唯一标识。
示例值:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
用户子标识 sub_openid string[1,128] 用户在子商户appid下的唯一标识。
示例值:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
+订单金额 amount object 订单金额信息
参数名 变量 类型[长度限制] 必填 描述
总金额 total int 订单总金额,单位为分。
示例值:100
用户支付金额 payer_total int 用户支付金额,单位为分。
示例值:100
货币类型 currency string[1,16] CNY:人民币,境内商户号仅支持人民币。
示例值:CNY
用户支付币种 payer_currency string[1,16] 用户支付币种
示例值:CNY
+场景信息 scene_info object 支付场景信息描述
参数名 变量 类型[长度限制] 必填 描述
商户端设备号 device_id string[1,16] 终端设备号(门店号或收银设备ID)。
特殊规则:长度最小7个字节
示例值:POS1:1
+优惠功能 promotion_detail array 优惠功能,享受优惠时返回该字段。
参数名 变量 类型[长度限制] 必填 描述
券ID coupon_id string[1,32] 券ID
示例值:109519
优惠名称 name string[1,64] 优惠名称
示例值:单品惠-6
优惠范围 scope string[1,32] GLOBAL:全场代金券
SINGLE:单品优惠
示例值:GLOBAL
优惠类型 type string[1,32] CASH:充值
NOCASH:预充值
示例值:CASH
优惠券面额 amount int 优惠券面额
示例值:100
活动ID stock_id string[1,32] 活动ID
示例值:931386
微信出资 wechatpay_contribute int 微信出资,单位为分
示例值:0
商户出资 merchant_contribute int 商户出资,单位为分
示例值:0
其他出资 other_contribute int 其他出资,单位为分
示例值:0
优惠币种 currency string[1,16] CNY:人民币,境内商户号仅支持人民币。
示例值:CNY
+单品列表 goods_detail array 单品列表信息
参数名 变量 类型[长度限制] 必填 描述
商品编码 goods_id

string[1,32]

商品编码
示例值:M1006
商品数量 quantity int 用户购买的数量
示例值:1
商品单价 unit_price int 商品单价,单位为分
示例值:100
商品优惠金额 discount_amount int 商品优惠金额
示例值:0  
商品备注 goods_remark string[1,128] 商品备注信息
示例值:商品备注信息

通知应答

支付通知http应答码为200或204才会当作正常接收,当回调处理异常时,应答的HTTP状态码应为500,或者4xx。

参数名 变量 类型[长度限制] 必填 描述
返回状态码 code string[1,32] 错误码,SUCCESS为清算机构接收成功,其他错误码为失败。
示例值:SUCCESS
返回信息 message string[1,64] 返回信息,如非空,为错误原因。
示例值:系统错误

注意:当商户后台应答失败时,微信支付将记录下应答的报文,建议商户按照以下格式返回。



{   
    "code": "ERROR_NAME",
    "message": "ERROR_DESCRIPTION",
}


版本说明

关闭
V1.0
2020.05.26
1. 支付结果回调通知上线

技术咨询

文档反馈