【微信支付】微信公众号支付接口文档V3.3.7
微信公众号支付接口文档
(V3.3.7)
目录
微信公众号支付接口文档 (1)
1.微信支付简介 (4)
1.1.功能简介 (4)
1.2.支付账户 (4)
1.3.支付方式 (5)
2.支付场景介绍 (5)
2.1.网页内支付场景---JS API（网页内）支付接口 (5)
2.1.1.交互细节 (7)
2.1.2.JSAPI支付时序图 (8)
2.1.3.获取当前微信版本号 (8)
2.1.4.显示微信安全支付标题 (8)
2.2.线下扫码购买场景---Native（原生）支付接口 (9)
2.2.1使用场景 (9)
2.2.2.Native（原生）支付URL定义 (10)
3.接口说明 (12)
3.1.接口调用规则 (12)
3.2.Sign签名生成方法 (13)
3.3.代码实例 (14)
4.API说明 (15)
4.1.统一支付接口 (15)
4.2.通用通知接口 (17)
4.3.订单查询接口 (19)
4.4.JSAPI支付——H5网页端调起支付接口 (21)
4.5.Native支付——二维码链接 (22)
4.6.Native支付——请求商家获取商品信息接口 (23)
4.7关闭订单接口 (24)
4.8.退款申请接口 (25)
4.9.退款查询接口 (26)
4.10.对账单接口 (28)
4.11.短链接转换接口 (30)
4.12.接口调用上报接口 (31)
5.企业红包使用说明 (32)
5.1创建批次企业红包 (32)
5.2提交支付使用企业红包 (33)
5.3查询使用企业红包金额 (33)
5.4企业红包对账单 (33)
6.错误码列表 (33)
7.常见问题和注意事项 (34)
7.1.常见基本概念疑惑 (34)
7.2.常见错误现象及解决方法 (34)
7.3.常见注意事项 (35)
7.4.联系我们 (36)
1.微信支付简介
1.1.功能简介
微信支付，是基于微信客户端提供的支付服务功能。同时向商户提供销售经营分析、账户和资金管理的功能支持。用户通过扫描二维码、微信内打开商品页面购买等多种方式调起微信支付模块完成支付。
微信支持公众号内支付，即基于公众号向用户收款，公众号相当于收款的商户。其中支付方式，可以分为JS API（网页内）支付、Native（原生）支付。商户可以结合业务场景，自主选择支付方式。
本文将全面介绍微信支付的技术方案。
1.2.支付账户
商户向微信提交企业以及银行账户资料，商户功能审核通过后，可以获得以下帐户（包含财付通的商户账户），用于公众号支付。
帐号作用
appId
微信公众号身份的唯一标识。审核通过后，在微信发送的邮件中查看。
Mchid
商户ID，身份标识，在微信发送的邮件中查看。
Key
商户支付密钥Key。登录微信商户后台，进入栏目【账户设置】【密码安全】
【API安全】【API密钥】，进入设置API密钥。
Appsecret
JSAPI接口中获取openid，审核后在公众平台开启开发模式后可查看。
注意：支付密钥Key是验证商户唯一性的安全标识，请妥善保管，仅保留在第三方后台和微信后台，不会在网络中传播。
1.3.支付方式
JS API（网页内）支付：是指用户打开图文消息或者扫描二维码，在微信内置浏览器打开网页进行的支付。商户网页前端通过使用微信提供的JS API，调用微信支付模块。这种方式，适合需要在商户网页进行选购下单的购买流程。
Native（原生）支付：是指商户组成符合Native（原生）支付规则的URL链接，用户可通过在会话中点击链接或者扫描对应的二维码直接进入微信支付模块（客户端界面），即可进行支付。这种方式，适合无需选购直接支付的购买流程。跟JSAPI最大的区别是不经过网页调起支付。
2.支付场景介绍
2.1.网页内支付场景---JS API（网页内）支付接口
商户已有H5商城网站，在微信内打开网页时，可以调用微信支付完成下单购买的流程。
步骤（1）：左图，商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页。
步骤（2）：右图，进入家网页，用户选择购买，完成选购流程。
步骤（3）：左图，调起微信支付控件，用户开始输入支付密码。
步骤（4）：右图，密码验证通过，支付成功。商户后台得到支付成功的通知。
步骤（5）：左图，返回商户页面，显示购买成功。该页面由商户自定义。 步骤（6）：右图，公众号下发消息，提示发货成功。该步骤可选。
注意：商户也可以把商品网页的链接生成二维码，用户扫一扫打开后即可完成购买支付。
2.1.1.交互细节
以下是支付场景的交互细节，请认真阅读，并设计商户页面的逻辑：
（1）用户打开商户网页选购商品，发起支付，在网页通过JavaScript 调用getBrandWCPayRequest 接口，发起微信支付请求，用户进入支付流程。
（2）用户成功支付点击完成按钮后，商户的前端会收到JavaScript 的返回值。商户可直接跳转到支付成功的静态页面进行展示。
（3）商户后台收到来自微信开放平台的支付成功回调通知，标志该笔订单支付成功。 注：
（2）和（3）的触发不保证遵循严格的时序。JS API 返回值作为触发商户网页跳转的标志，但商户后台应该只在收到微信后台的支付成功回调通知后，才做真正的支付成功的处理。
JS API 返回值目前只在支付成功时返回，后续版本将扩展返回值，以便商户做更多个
性化的展示。
2.1.2.JSAPI支付时序图
2.1.
3.获取当前微信版本号
由于微信5.0版本后才加入微信支付模块，低版本用户调用微信支付功能将无效。因此，建议商户通过user agent来确定用户当前的版本号后再调用支付接口。以iPhone版本为例，可以通过user agent可获取如下微信版本示例信息：
"Mozilla/5.0(iphone;CPU iphone OS 5_1_1 like Mac OS X) AppleWebKit/534.46(KHTML,like Geocko) Mobile/9B206 MicroMessenger/5.0"
其中5.0为用户安装的微信版本号，商户可以判定版本号是否高于或者等于5.0。
2.1.4.显示微信安全支付标题
对于商户具有支付权限且需要调用微信支付的页面，为了让用户增加购买信心，确认交易环境安全，微信强烈建议商户使用“微信安全支付”标题。安全支付标题的如下图。
显示支付安全标题，需将原始链接添加上"showwxpaytitle=1"的尾串。通过这种方式，商户的页面将出现微信安全支付的标识。例如，原始URL 为：htp://https://www.docsj.com/doc/005084846.html,,显示安全支付标题的URL 为：htp://https://www.docsj.com/doc/005084846.html,?showwxpaytitle=1。
当用户在微信里打开https://www.docsj.com/doc/005084846.html, 不会直接出现微信安全支付的标题，而打开htp://https://www.docsj.com/doc/005084846.html,?showwxpaytitle=1后将出现微信安全支付标题。
2.2.线下扫码购买场景---Native （原生）支付接口
2.2.1使用场景
与网页内支付场景不同，部分商户不需要经过网页选购，可以直接下单购买。 步骤（1）：左图，商户根据微信支付的规则，为不同商品生成不同的二维码，张贴在各种场景，便于用户扫描购买。
步骤（2）：右图，用户使用微信扫描二维码后，获取商品信息，同时到商户后台下单。
步骤（3）：左图，用户开始支付，输入支付密码。
步骤（4）：右图，支付成功，商户后台得到通知，进行发货处理。
2.2.2.Native（原生）支付URL定义
模式一：商户按固定格式生成链接二维码，用户扫码后调微信会将productid和用户openid发送到商户设置的链接上，商户收到请求生成订单，调用统一支付接口下单提交到微信，微信会返回给商户prepayid，时序图如下：
对应链接：
weixin://wxpay/bizpayurl?sign=XXXXX&appid=XXXXX&mch_id=XXXXX&product_id= XXXXXX &time_stamp=XXXXXX&nonce_str=XXXXX
模式二：商户生成订单，先调用统一支付接口获取到code_url，此URL直接生成二维码，用户扫码后调起支付。时序图如下：
code_url对应链接：
weixin://wxpay/bizpayurl?sr=XXXXX
3.接口说明
3.1.接口调用规则
◆认证方式：HTTPS认证，退款和冲正接口调用需要商户证书(证书在审核邮件附件
中)
◆请求采用POST方式
◆提交和返回结果采用XML格式
◆字符集默认使用UTF-8，请勿使用其它字符集
◆商户与微信之间的交互(特别是Native回调和支付通知回调)，都需要验证签名
处理返回时先判断协议返回错误码，再判断业务返回错误码，最后判断交易状态3.2.Sign签名生成方法
微信支付中将对数据里面的内容进行鉴权，确定携带的信息是真实、有效、合理的。因此，这里将定义生成sign字符串的方法。
a.对所有传入参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1，注意：值为空的参数不参与签名；
b.在string1最后拼接上key=Key(商户支付密钥)得到stringSignTemp字符串，并对stringSignTemp进行md5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。
下面定义了一段生成sign字符串的示范过程：
假设以下为package传入参数：
appid=wxd930ea5d5a258f4f
auth_code=123456
body=test
device_info=123
mch_id=1900000109
nonce_str=960f228109051b9969f76c82bde183ac
out_trade_no=1400755861
spbill_create_ip=127.0.0.1
total_fee=1
key=8934e7d15453e97507ef794cf7b0519d
i：经过a过程URL键值对字典序排序后的字符串string1为：
appid=wxd930ea5d5a258f4f&auth_code=123456&body=test&device_info=123&mch_id=1 900000109&nonce_str=960f228109051b9969f76c82bde183ac&out_trade_no=1400755861&spbil l_create_ip=127.0.0.1&total_fee=1
ii：经过b过程后得到sign为：
sign
=md5(string1&key=8934e7d15453e97507ef794cf7b0519d).toUpperCase
=md5(appid=wxd930ea5d5a258f4f&auth_code=123456&body=test&device_info=123&mch
_id=1900000109&nonce_str=960f228109051b9969f76c82bde183ac&out_trade_no=1400755861 &spbill_create_ip=127.0.0.1&total_fee=1&key=8934e7d15453e97507ef794cf7b0519d).toUpper Case()
="c380bec2bfd727a4b6845133519f3ad6".toUpperCase()
="C380BEC2BFD727A4B6845133519F3AD6"
3.3.代码实例
接口调用实例，以开发为例说明数据提交和返回的具体格式：
提交数据：
协议级错误返回：
正确返回数据：
业务级错误返回：
4.API说明
4.1.统一支付接口
URL地址：https://https://www.docsj.com/doc/005084846.html,/pay/unifiedorder
统一支付接口，可接受JSAPI/NATIVE/APP下预支付订单，返回预支付订单号。
NA TIVE支付返回二维码code_url。
注意：JSAPI下单前需要调用登录授权接口(详细调用说明请点击打开链接)获取到用户的Openid。
请求参数：
字段名变量名必填类型说明
公众账号ID appid 是String(32) 微信分配的公众账号ID
商户号mch_id 是String(32) 微信支付分配的商户号
设备号device_info 否String(32) 微信支付分配的终端设备号随机字符串nonce_str 是String(32) 随机字符串，不长于32位签名sign 是String(32) 签名,详细签名方法见3.2节商品描述body 是String(127) 商品描述
附加数据attach 否String(127) 附加数据，原样返回
商户订单号out_trade_no 是String(32) 商户系统内部的订单号,32
个字符内、可包含字母,确保
在商户系统唯一,详细说明
见7.3节第四项
总金额total_fee 是Int 订单总金额，单位为分，不
能带小数点
终端IP spbill_create_ip 是String(16) 订单生成的机器IP
交易起始时间time_start 否String(14) 订单生成时间，格式为
yyyyMMddHHmmss，如2009年
12月25日9点10分10秒表
示为20091225091010。时区
为GMT+8 beijing。该时间取
自商户服务器
交易结束时间time_expire 否String(14) 订单失效时间，格式为
yyyyMMddHHmmss，如2009年
12月27日9点10分10秒表
示为20091227091010。时区
为GMT+8 beijing。该时间取
自商户服务器
商品标记goods_tag 否String(32) 商品标记，该字段不能随便
填，不使用请填空，使用说
明详见第5节
通知地址notify_url 是String(256) 接收微信支付成功通知
交易类型trade_type 是String(16) JSAPI、NATIVE、APP
用户标识openid否String(128)用户在商户appid下的唯一
标识，trade_type为JSAPI
时，此参数必传，获取方式
见表头说明。
商品ID product_id 否String(32) 只在trade_type为NATIVE 时需要填写。此id为二维码中包含的商品ID，商户自行维护。
返回参数：
字段名变量名必填类型说明
返回状态码return_code 是String(16) SUCCESS/FAIL
此字段是通信标识，非交易
标识，交易是否成功需要查
看result_code来判断
返回信息return_msg 否String(128) 返回信息，如非空，为错误
原因
签名失败
参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
公众账号ID appid 是String(32) 微信分配的公众账号ID
商户号mch_id 是String(32) 微信支付分配的商户号
设备号device_info 否String(32) 微信支付分配的终端设备
号，
随机字符串nonce_str 是String(32) 随机字符串，不长于32位签名sign 是String(32) 签名,详细签名方法见3.2节业务结果result_code 是String(16) SUCCESS/FAIL
错误代码err_code 否String(32) 列表第6节
错误代码描述err_code_des 否String(128) 结果信息描述
以下字段在return_code 和result_code都为SUCCESS的时候有返回
交易类型trade_type 是String(16) JSAPI、NATIVE、APP
预支付ID prepay_id 是String(64) 微信生成的预支付ID，用于
后续接口调用中使用
二维码链接code_url 否String(64) trade_type为NATIVE是有
返回，此参数可直接生成二
维码展示出来进行扫码支付
4.2.通用通知接口
通知URL是4.1节中提交的参数notify_url，支付完成后，微信会把相关支付和用户信息发送到该URL，商户需要接收处理信息。
对后台通知交互时，如果微信收到商户的应答不是成功或超时，微信认为通知失败，微信会通过一定的策略（如30分钟共8次）定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
通知参数：
字段名变量名必填类型说明
返回状态码return_code 是String(16) SUCCESS/FAIL
此字段是通信标识，非交易
标识，交易是否成功需要查
看result_code来判断
返回信息return_msg 否String(128) 返回信息，如非空，为错误
原因
签名失败
参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
公众账号ID appid 是String(32) 微信分配的公众账号ID
商户号mch_id 是String(32) 微信支付分配的商户号
设备号device_info 否String(32) 微信支付分配的终端设备
号，
随机字符串nonce_str 是String(32) 随机字符串，不长于32位签名sign 是String(32) 签名,详细签名方法见3.2节业务结果result_code 是String(16) SUCCESS/FAIL
错误代码err_code 否String(32) 错误码见第6节
错误代码描述err_code_des 否String(128) 结果信息描述
以下字段在return_code 和result_code都为SUCCESS的时候有返回
用户标识openid 是String(128) 用户在商户appid下的唯一
标识
是否关注公众账号is_subscribe 是String(1) 用户是否关注公众账号，Y-
关注，N-未关注，仅在公众
账号类型支付有效
交易类型trade_type 是String(16) JSAPI、NATIVE、MICROPAY、
APP
付款银行bank_type 是String(16) 银行类型，采用字符串类型
的银行标识
总金额total_fee 是Int 订单总金额，单位为分
现金券金额coupon_fee 否Int 现金券支付金额<=订单总金
额，订单总金额-现金券金额
为现金支付金额
货币种类fee_type 否String(8) 货币类型，符合ISO 4217标
准的三位字母代码，默认人
民币：CNY
微信支付订单号transaction_id 是String(32) 微信支付订单号
商户订单号out_trade_no 是String(32) 商户系统的订单号，与请求
一致。
商家数据包attach 否String(128) 商家数据包，原样返回
支付完成时间time_end 是String(14) 支付完成时间，格式为
yyyyMMddhhmmss，如2009年
12月27日9点10分10秒表
示为20091227091010。时区
为GMT+8 beijing。该时间取
自微信支付服务器商户处理后同步返回给微信参数：
字段名变量名必填类型说明
返回状态码return_code 是S tring(16)SUCCESS/FAIL
SUCCESS表示商户接收通知
成功并校验成功
返回信息r et urn_msg 否String(128)返回信息，如非空，为错误
原因
签名失败
参数格式校验错误
4.3.订单查询接口
接口链接：https://https://www.docsj.com/doc/005084846.html,/pay/orderquery
该接口提供所有微信支付订单的查询，当支付通知处理异常或丢失的情况，商户可以通过该接口查询订单支付状态。
请求参数：
字段名变量名必填类型说明
公众账号ID appid 是String(32) 微信分配的公众账号ID
商户号mch_id 是String(32) 微信支付分配的商户号
微信订单号transaction_id 否String(32)微信的订单号，优先使用
商户订单号out_trade_no 是String(32)商户系统内部的订单号,
transaction_id、out_trade_no二
选一，如果同时存在优先级：
transaction_id> out_trade_no
随机字符串nonce_str 是String(32) 随机字符串，不长于32位
签名sign 是String(32) 签名,详细签名方法见3.2节同步返回结果：
字段名变量名必填类型说明
返回状态码return_code 是String(16) SUCCESS/FAIL
此字段是通信标识，非交易
标识，交易是否成功需要查
看trade_state来判断
返回信息return_msg 否String(128) 返回信息，如非空，为错误
原因
签名失败
参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
公众账号ID appid 是String(32) 微信分配的公众账号ID
商户号mch_id 是String(32) 微信支付分配的商户号
随机字符串nonce_str 是String(32) 随机字符串，不长于32位签名sign 是String(32) 签名,详细签名方法见3.2节业务结果result_code 是String(16) SUCCESS/FAIL
错误代码err_code 否String(32) 错误码见第6节
错误代码描述err_code_des 否String(128) 结果信息描述
以下字段在return_code 和result_code都为SUCCESS的时候有返回
交易状态trade_state是S tring(32)SUCCESS—支付成功
REFUND—转入退款
NOTPAY—未支付
CLOSED—已关闭
REVOKED—已撤销
USERPAYING--用户支付中
NOPAY--未支付(输入密码或
确认支付超时)
PAYERROR--支付失败(其他
原因，如银行返回失败)
以下字段在return_code 和result_code都为SUCCESS的时候有返回
设备号device_info 否String(32) 微信支付分配的终端设备
号，
用户标识openid 是String(128) 用户在商户appid下的唯一
标识
是否关注公众账号is_subscribe 是String(1) 用户是否关注公众账号，Y-
关注，N-未关注，仅在公众
账号类型支付有效
交易类型trade_type 是String(16) JSAPI、NATIVE、MICROPAY、
APP
付款银行bank_type 是String(16) 银行类型，采用字符串类型
的银行标识
总金额total_fee 是Int 订单总金额，单位为分
现金券金额coupon_fee 否Int 现金券支付金额<=订单总金
额，订单总金额-现金券金额
为现金支付金额
货币种类fee_type 否String(8) 货币类型，符合ISO 4217标
准的三位字母代码，默认人
民币：CNY
微信支付订单号transaction_id 否String(32) 微信支付订单号
商户订单号out_trade_no 否String(32) 商户系统的订单号，与请求
一致。
商家数据包attach 否String(128) 商家数据包，原样返回
支付完成时间time_end 是String(14) 支付完成时间，格式为
yyyyMMddhhmmss，如2009年
12月27日9点10分10秒表
示为20091227091010。时区