微信公众号支付接口文档结算中心受理机构v00.docx
《微信公众号支付接口文档结算中心受理机构v00.docx》由会员分享，可在线阅读，更多相关《微信公众号支付接口文档结算中心受理机构v00.docx（56页珍藏版）》请在冰豆网上搜索。
微信公众号支付接口文档结算中心受理机构v00
微信公众号支付接口文档
（结算中心-受理机构）
讨论
目录
修改日志4
1.微信支付简介5
1.1.功能简介5
1.2.支付账户5
1.3.支付方式6
2.支付场景介绍6
2.1.网页内支付场景---JSAPI（网页内）支付接口6
2.1.1.交互细节8
2.1.2.JSAPI支付时序图9
2.1.4.显示微信安全支付标题9
2.2.线下扫码购买场景---Native（原生）支付接口10
2.2.1使用场景10
2.2.2.Native（原生）支付URL定义11
3.接口说明13
3.1.接口调用规则13
3.2.微信Sign签名生成方法14
3.2.1受理商签名Sign生成方法14
3.3结算中心签名生成方法15
3.4调用流程16
4.API说明17
4.1.统一支付接口17
4.2.通用通知接口20
4.3.订单查询接口22
4.7关闭订单接口24
4.8.退款申请接口26
4.9.退款查询接口28
4.10.对账单接口30
4.12.接口调用上报接口30
5.企业红包使用说明32
5.1创建批次企业红包32
5.2提交支付使用企业红包32
5.3查询使用企业红包金额33
5.4企业红包对账单33
6.返回状态码列表33
7.错误码列表33
8.常见问题和注意事项34
8.1.常见基本概念疑惑34
8.2.常见错误现象及解决方法34
8.3.常见注意事项35
修改日志
日期
修改人
操作
修改内容
2014-12-26
陈恒
创建
新增修改日志
2014-12-26
陈恒
修改
修改“4.8退款申请接口”参数名“Sign_szfs”为“sign_szfs”
2014-12-26
陈恒
修改
修改“3.3结算中心签名方式”
2014-12-26
陈恒
修改
修改“6返回状态码列表”，新增状态码“FAIL_STATUS”、“FAIL_SIGN”、“FAIL_SZFS”
2015-01-05
陈恒
修改
修改“4.7关闭订单接口”参数“商户订单号（out_trade_no）”为必填
1.微信支付简介
1.1.功能简介
微信支付，是基于微信客户端提供的支付服务功能。
同时向商户提供销售经营分析、账户和资金管理的功能支持。
用户通过扫描二维码、微信内打开商品页面购买等多种方式调起微信支付模块完成支付。
微信支持公众号内支付，即基于公众号向用户收款，公众号相当于收款的商户。
其中支付方式，可以分为JSAPI（网页内）支付、Native（原生）支付。
商户可以结合业务场景，自主选择支付方式。
本文将全面介绍微信支付的技术方案。
1.2.支付账户
商户向微信提交企业以及银行账户资料，商户功能审核通过后，可以获得以下帐户（包含财付通的商户账户），用于公众号支付。
帐号
作用
appId
微信公众号身份的唯一标识。
审核通过后，在微信发送的邮件中查看。
Mchid
商户ID，身份标识，在微信发送的邮件中查看。
SubMchId
子商户ID，受理模式下子商户与受理商有绑定关系，没有不提交该参数
Key
商户支付密钥Key。
登录微信商户后台，进入栏目【账户设置】【密码安全】【API安全】【API密钥】
Appsecret
JSAPI接口中获取openid，审核后在公众平台开启开发模式后可查看。
注意：
支付密钥Key是验证商户唯一性的安全标识，请妥善保管，仅保留在第三方后
台和微信后台，不会在网络中传播。
1.3.支付方式
JSAPI（网页内）支付：
是指用户打开图文消息或者扫描二维码，在微信内置浏览器打开网页进行的支付。
商户网页前端通过使用微信提供的JSAPI，调用微信支付模块。
这种方式，适合需要在商户网页进行选购下单的购买流程。
Native（原生）支付：
是指商户组成符合Native（原生）支付规则的URL链接，用户可通过在会话中点击链接或者扫描对应的二维码直接进入微信支付模块（客户端界面），即可进行支付。
这种方式，适合无需选购直接支付的购买流程。
跟JSAPI最大的区别是不经过网页调起支付。
2.支付场景介绍
2.1.网页内支付场景---JSAPI（网页内）支付接口
商户已有H5商城网站，在微信内打开网页时，可以调用微信支付完成下单购买的流程。
步骤
（1）：
左图，商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页。
步骤
（2）：
右图，进入商家网页，用户选择购买，完成选购流程。
步骤（3）：
左图，调起微信支付控件，用户开始输入支付密码。
步骤（4）：
右图，密码验证通过，支付成功。
商户后台得到支付成功的通知。
步骤（5）：
左图，返回商户页面，显示购买成功。
该页面由商户自定义。
步骤（6）：
右图，公众号下发消息，提示发货成功。
该步骤可选。
注意：
商户也可以把商品网页的链接生成二维码，用户扫一扫打开后即可完成购买支付。
2.1.1.交互细节
以下是支付场景的交互细节，请认真阅读，并设计商户页面的逻辑：
（1）用户打开商户网页选购商品，发起支付，在网页通过JavaScript调用getBrandWCPayRequest接口，发起微信支付请求，用户进入支付流程。
（2）用户成功支付点击完成按钮后，商户的前端会收到JavaScript的返回值。
商户可直接跳转到支付成功的静态页面进行展示。
（3）商户后台收到来自微信开放平台的支付成功回调通知，标志该笔订单支付成功。
注：
（2）和（3）的触发不保证遵循严格的时序。
JSAPI返回值作为触发商户网页跳转的标志，但商户后台应该只在收到微信后台的支付成功回调通知后，才做真正的支付成功的处理。
JSAPI返回值目前只在支付成功时返回，后续版本将扩展返回值，以便商户做更多个性化的展示。
2.1.2.JSAPI支付时序图
2.1.3.获取当前微信版本号
由于微信5.0版本后才加入微信支付模块，低版本用户调用微信支付功能将无效。
因此，建议商户通过useragent来确定用户当前的版本号后再调用支付接口。
以iPhone版本为例，可以通过useragent可获取如下微信版本示例信息：
"Mozilla/5.0（iphone;CPUiphoneOS5_1_1likeMacOSX）AppleWebKit/534.46（KHTML,likeGeocko）Mobile/9B206MicroMessenger/5.0"
其中5.0为用户安装的微信版本号，商户可以判定版本号是否高于或者等于5.0。
2.1.4.显示微信安全支付标题
对于商户具有支付权限且需要调用微信支付的页面，为了让用户增加购买信心，确认交易环境安全，微信强烈建议商户使用“微信安全支付”标题。
安全支付标题的如下图。
显示支付安全标题，需将原始链接添加上"showwxpaytitle=1"的尾串。
通过这种方式，
商户的页面将出现微信安全支付的标识。
例如，原始URL为：
htp:
//,显示安全支付标题的URL为：
htp:
//?
showwxpaytitle=1。
当用户在微信里打开不会直接出现微信安全支付的标题，而打开
htp:
//?
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.接口调用规则
◆认证方式：
HTTP认证，退款和撤销接口调用需要商户证书（证书由结算中心下发）
◆请求采用POST方式
◆提交和返回结果采用XML格式
◆字符集默认使用UTF-8，请勿使用其它字符集
◆商户与微信之间的交互（特别是Native回调和支付通知回调），都需要验证签名
◆处理返回时先判断协议返回错误码，再判断业务返回错误码，最后判断交易状态
3.2.微信Sign签名生成方法
假设微信支付分配的参数为：
（1）第三方商户的商户参数：
商户参数名
参数值
说明
appid
wxd00000000000000f
第三方商户公众号标识
mch_id
10000001
第三方商户商户号标识
Key
8934e7d15453e97507ef7
94cf7b0519d
第三方商户密钥
3.2.1受理商签名Sign生成方法
由于数据中携带了生成订单的详细信息，因此在微信将对数据里面的内容进行鉴权，确定携带的信息是真实、有效、合理的。
因此，这里将定义生成sign字符串的方法。
a.对所有传入参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1，注意：
值为空的参数不参与签名；
b.在string1最后拼接上key=受理商商户Key得到stringSignTemp字符串，并对stringSignTemp进行md5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。
下面定义了一段生成sign字符串的示范过程：
假设以下为传入参数：
appid=wxd00000000000000fmch_id=10000001auth_code=123456
body=testdevice_info=123
nonce_str=960f228109051b9969f76c82bde183acout_trade_no=1400755861spbill_create_ip=127.0.0.1
total_fee=1
i：
经过a过程URL键值对字典序排序后的字符串string1为：
appid=wxd00000000000000f&auth_code=123456&body=test&device_info=123&mch_id=10000001&nonce_str=960f228109051b9969f76c82bde183ac&out_trade_no=1400755861&spbill_create_ip=127.0.0.1&total_fee=1
ii：
经过b过程后得到sign为：
sign
=md5（string1&key=8934e7d15453e97507ef794cf7b0519d）.toUpperCase
=md5（appid=wxd00000000000000f&auth_code=123456&body=test&device_info=123&mch_id=10000001&nonce_str=960f228109051b9969f76c82bde183ac&out_trade_no=1400755861&spbill_create_ip=127.0.0.1&total_fee=1&key=8934e7d15453e97507ef794cf7b0519d）.toUpperCase（）
="0b28fe46b0e12e4692ca950d67cecde5".toUpperCase（）
="0B28FE46B0E12E4692CA950D67CECDE5"
3.3结算中心签名生成方法
受理机构在发起撤销和退款申请时，需要对相应接口的“提交参数”进行签名。
除“结算中心签名（sign_szfs）”和值为空的参数外，所有“提交参数”都需参与签名。
生成的签名填充参数“结算中心签名”。
结算中心收到一笔撤销和退款申请时必须用“提交参数”中的“结算中心签名”来验证报文的有效性。
签名所需的私钥文件由结算中心统一提供，各受理机构需要更换私钥文件时可以向结算中心申请。
验签所需的公钥文件由结算中心决定是否更换。
以下给出签名的生成方式：
（1）除“结算中心签名”和值为空的参数外，所有“提交参数”都需参与签名。
（2）对所有传入参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1，string1即为签名要素。
注意：
此时string1应包括sign=signValue。
（3）使用自身的数字证书（私钥）对签名要素串签名，签名的校验算法使用SHA1WithRSA算法。
（4）将签名值使用BASE64转码后得到参数“结算中心签名”的值。
3.4调用流程
（1）商户发起请求处理流程：
（2）商户调用返回或微信主动通知处理流程：
4.API说明
4.1.统一支付接口
URL地址：
待定
统一支付接口，可接受JSAPI/NATIVE/APP下预支付订单，返回预支付订单号。
NATIVE支付返回二维码code_url。
注意：
JSAPI下单前需要调用登录授权接口（详细调用说明请点击打开链接）获取到用户的Openid。
请求参数：
字段名
变量名
必填
类型
说明
公众账号ID
appid
是
String（32）
微信分配的公众账号ID
商户号
mch_id
是
String（32）
微信支付分配的商户号
子商户号
sub_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个字符内、可包含字母,确保在商户系统唯一,详细说明见8.3节第四项
总金额
total_fee
是
Int
订单总金额，单位为分，不
能带小数点
终端IP
spbill_create_ip
是
String（16）
订单生成的机器IP
交易起始时间
time_start
否
String（14）
订单生成时间，格式为
yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。
时区
为GMT+8beijing。
该时间取
自商户服务器
交易结束时间
time_expire
否
String（14）
订单失效时间，格式为
yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。
时区
为GMT+8beijing。
该时间取自商户服务器
商品标记
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）
此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
详见第6节
返回信息
return_msg
否
String（128）
返回信息，如非空，为错误
原因
签名失败
参数格式校验错误
微信侧超时
以下字段在return_code为SUCCESS的时候有返回
公众账号ID
appid
是
String（32）
微信分配的公众账号ID
商户号
mch_id
是
String（32）
微信支付分配的商户号
子商户号
sub_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）
列表第7节
错误代码描述
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是有
返回，此参数可直接生成二维码展示出来进行扫码支付
请求示例：
wxd00000000000000f
NATIVE
[CDATA[test]]>
123
10000001
960f228109051b9969f76c82bde183ac
1400755861
127.0.0.1
1
100
0B28FE46B0E12E4692CA950D67CECDE5
wxd88888888888888f
10000002
78078498E19F1E74A489AB6428A521AD
返回示例：
SUCCESS
OK
wx2421b1c4370ec43b
10000100
1000
LM1Bbp0WoDV5jqpP
1DE267795ECCC5BFB90DDCA91DBBF107
SUCCESS
wx20140718112216156db45f6d0493886204
NATIVE
wxd88888888888888f
10000002
C380BEC2BFD727A4B6845133519F3AD6
4.2.通用通知接口
通知URL是4.1节中提交的参数notify_url，支付完成后，结算中心会把相关支付和用户信息发送到该URL，第三方受理机构需接收该通知并验签，验签通过才可做下一步操作。
对后台通知交互时，如果结算中心收到第三方受理机构的应答不是成功或超时，结算中心认为通知失败，中心会通过一定的策略（如30分钟共8次）定期重新发起通知，尽可能提高通知的成功率，但中心不保证通知最终能成功。
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。
商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。
在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
通知参数：
字段名
变量名
升级会员 