微信支付API文档120(受理)
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
1. 阅读对象
本文阅读对象：商户系统（在线购物平台、人工收银系统、自动化智能收银系统或其他）集成微信支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。
2. 术语
1. 支付模式
1) 被扫支付被扫支付是用户展示微信上“我的刷卡条码/二维码”给商户系统扫描后直接完成支付的模式。
主要应用线
下面对面收银的场景。
2) 扫码支付扫码支付是商户系统按微信支付协议生成支付二维码，用户再用微信“扫一扫”完成支付的模
式。
该模式
适用于P C 网站支付、实体店单品或订单支付、媒体广告支付等场景。
3) 微信内网页支付
微信内网页支付是用户在微信中打开商户的H5 页面，商户在H5 页面通过调用微信支付提供的JSAPI 接口调起微信支付模块完成支付。
应用场景有：
•用户在微信公众账号内进入商家公众号，打开某个主页面，完成支付；
•用户的好友在朋友圈、聊天窗口等分享商家页面连接，用户点击链接打开商家页面，完成支付•将商户页面转换成二维码，用户扫描二维码后在微信浏览器中打开页面后完成支付
4) APP 支付
APP 支付又称移动端支付，是商户通过在移动端应用APP 中集成开放SDK 调起微信支付模块完成支付的模式。
5) 普通浏览器网页支付模式
正在建设中，敬请期待。
2. 名词解释
1) 微信公众平台微信公众平台是微信公众账号申请入口和管理后台。
商户可以在公众平台提交基本资料、业务
资料、财务
资料申请开通微信支付功能。
平台入口：。
2) 微信开放平台
微信开放平台是商户APP 接入微信支付开放接口的申请入口，通过此平台可申请微信APP 支付。
平台入口：。
3) 微信商户平台
微信商户平台是微信支付相关的商户功能集合，包括参数配置、支付数据查询与统计、在线退款、代金券或立减优惠运营等功能。
平台入口：。
4) 微信支付系统
微信支付系统是指完成微信支付流程中涉及的API 接口、后台业务处理系统、账务系统、回调通知等系统的总称。
5) 商户收银系统
商户收银系统即商户的POS 收银系统，是录入商品信息、生成订单、客户支付、打印小票等功能的系统。
接入微信支付功能主要涉及到POS 软件系统的开发和测试，所以在下文中提到的商户收银系统特指POS 收银软件系统。
6) 商户后台系统商户后台系统是商户后台处理业务系统的总称，例如：商户网站、收银系统、进销存系统、发
货系统、客
服系统等。
7) 扫码设备
一种输入设备，主要用于商户系统快速读取媒介上的图形编码信息。
按读取码的类型不同，可分为条码扫码设备和二维码扫码设备。
按读取物理原理可分为红外扫码设备、激光扫码设备。
8) 商户证书
商户证书是微信提供的二进制文件，商户系统发起与微信支付后台服务器通信请求的时候，作为微信支付后台识别商户真实身份的凭据。
9) 签名商户后台和微信支付后台根据相同的密钥和算法生成一个结果，用于校验双方身份合法性。
签名的算法
由
微信支付制定并公开，常用的签名方式有：MD5、SHA1、SHA256、HMAC 等。
10) JSAPI 网页支付即前文说的微信内网页支付，可在微信公众号、朋友圈、聊天会话中点击页面链接，或者用
微信“扫一扫”
扫描页面地址二维码在微信中打开商户HTML5 页面，在页面内下单完成支付。
11) Native 原生支付
Native 原生支付属于扫码支付，商户根据微信支付协议格式生成的二维码，用户通过微信“扫一扫”扫描二维码后即进入付款确认界面，输入密码即完成支付。
12) 支付密码
支付密码是用户开通微信支付时单独设置的密码，用于确认支付完成交易授权。
该密码与微信登录密码不同。
13) Openid
用户在公众号内的身份标识，不同公众号拥有不同的openid。
商户后台系统通过登录授权、支付通知、查询订单等A PI 可获取到用户的o penid。
主要用途是判断同一个用户，对用户发送客服消息、模版消息等。
3. 支付账户
商户在微信公众平台(申请扫码原生支付、微信内网页支付)或开放平台(申请APP 支付)按照相应提示，申请相应微信支付模式。
微信支付工作人员审核资料无误后开通相应的微信支付权限。
微信支付申请审核通过后，商户在申请资料填写的邮箱中收取到由微信支付小助手发送的邮件，此邮件包含开发时需要使用的支付账户信息，见图3.1 所示。
图3.1 微信审核通过邮件模板
邮件中的账户参数与接口API 参数对应关系见表格3.1：表3.1：账户参数说明
4. 接口规则
1. 协议规则
商户接入微信支付，调用API 必须遵循以下规则：
表4.1：接口规则
2. 参数规定
1) 交易金额
交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。
对账单中的交易金额单位为【元】。
外币交易的支付金额精确到币种的最小单位，参数值不能带小数点。
2) 货币类型
货币类型的取值列表：
CNY：人民币GBP：
英镑HKD：港币
USD：美元
JPY：日元CAD：加
拿大元AUD：澳大利
亚元EUR：欧元
注：退款币种与支付币种必须一致
3) 时间标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。
参数值必须根据商户系统所在
时
区先换算成标准北京时间，例如商户所在地为0 时区的伦敦，当地时间为2014 年11 月11 日0 时0 分0 秒，换算成北京时间为2014 年11 月11 日8 时0 分0 秒。
4) 时间戳
标准北京时间，时区为东八区，自1970 年1 月1 日0 点0 分0 秒以来的秒数。
注意：部分系统取到的值为毫秒级，需要转换成秒(10 位数字)。
5) 商户订单号商户支付的订单号由商户自定义生成，微信支付要求商户订单号保持唯一性（建议根据当前系统
时间加随
机序列来生成订单号）。
重新发起一笔支付要使用原订单号，避免重复支付；已支付过或已调用关单、撤销（请见后文的API 列表）的订单号不能重新发起支付。
6) 交易类型
JSAPI：即微信网页内支付
NATIVE：即扫码支付APP：
即APP 支付
MICROPAY：即被扫支付
WAP：非微信手机浏览器支付
3. 安全规范
1 签名算法签名生成的通用
步骤如下：
第一步，设所有发送或者接收到的数据为集合M，将集合M 内非空参数值的参数按照参数名称的ASCII 码从小到大排序（字典序），使用URL 键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。
特别注意以下重要规则：
》参数名称ASCII 码从小到大排序（字典序）；
》如果参数的值为空不参与签名；
》参数名称区分大小写；
》验证调用返回或微信主动通知签名时，传送的sign 参数不参与签名，将生成的签名与该sign 值作校验。
》微信接口可能增加字段，验证签名时必须支持增加的扩展字段
第二步，在stringA 最后拼接上key=(API 密钥的值)得到stringSignTemp 字符串，并对stringSignTemp 进行MD5 运算，再将得到的字符串所有字符转换为大写，得到sign 值signValue。
举例
：
假设传送的参数如下：
appid：wxd930ea5d5a258f4f
device_info：1000
body：test
nonce_str：ibuaiVcKdpRxkhJA
第一步：对参数按照key=value 的格式，并按照参数名称ASCII 字典序排序如下：
第二步：拼接API 密钥：
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
最终得到最终发送的数据：
<xml>
<appid>wxd930ea5d5a258f4f</appid>
<mch_id>10000100</mch_id>
<device_info>1000<device_info>
<body>test</body>
<nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
<sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
<xml>
微信提供相关接口在线签名验证工具：点击进入。
2 生成随机数算法
微信支付A PI 接口协议中包含字段n once_str，主要保证签名不可预测。
我们推荐生成随机数算法如下：调用随机数函数生成，将得到的值转换为字符串。
3 商户证书
1) 获取商户证书微信支付接口中，涉及资金回滚的接口会使用到商户证书，包括退款、撤销接口。
商家在申请
微信支付成
功后，收到的相应邮件通知中，附件会包含接口需要用到的证书文件，有四个证书文件，分别说明如下。
表4.2：证书文件说明
2)。
apiclient_cert.p12 是商户证书文件，除PHP 外的开发均使用此证书文件。
商户如果使用.NET 环境开发，请确认Framework 版本大于2.0，必须在操作系统上双击安装证书apiclient_cert.p12 后才能被正常调用。
商户证书调用或安装都需要使用到密码，该密码的值为微信商户号（mch_id）
◆PHP 开发环境请使用商户证书文件apiclient_cert.pem 和apiclient_key.pem ，rootca.pem 是CA 证
书。
各版本的调用实例请参考微信支付提供的Demo。
3) 商户证书安全
证书文件不能放在web 服务器虚拟目录，应放在有访问权限控制的目录中，防止被他人下载。
商户服务器要做好病毒和木马防护工作，不被非法侵入者窃取证书文件。
4 商户回调API 安全
在普通的网络环境下，HTTP 请求存在DNS 劫持、运营商插入广告、数据被窃取，正常数据被修改等安全风险。
商户回调接口使用HTTPS 协议可以保证数据传输的安全性。
所以微信支付建议商户提供给微信支付的各种回调采用HTTPS 协议。
请参考：HTTPS 搭建指南。
5. 被扫支付模式开发指引
1. 场景介绍
步骤1：用户选择被扫支付付款并打开微信，进入“我”->“钱包”->“刷卡”条码界面（如图5.1 所示）；
步骤2：收银员在商户系统操作生成支付订单，用户确认支付金额；
步骤3：商户收银员用扫码设备扫描用户的条码/二维码，商户收银系统提交支付；
步骤4：微信支付后台系统收到支付请求，根据验证密码规则判断是否验证用户的支付密码，不需要验证密码的交易直接发起扣款，需要验证密码的交易会弹出密码输入框（如图 5.2 所示）。
支付成功后微信端会弹出成功页面（如图5.3 所示），支付失败会弹出错误提示。
图 5.1 我的钱包刷卡界面 图 5.2 输入密码，确认支付
图 5.3 支付成功后页面提示
2.
支付验证密码规则
• 支付金额>300 元的交易需要验证用户支付密码；
• 用户账号每天最多有 10 笔交易可以免密，超过后需要验证密码；
•
微信支付后台判断用户支付行为有异常情况，符合免密规则的交易也会要求验证密码；
3. 案例介绍 目前已上线被扫支付案例，商户可自行前往店
里实际体验。
便利店：711 便利店、国大 36524、好邻居等 连锁药店：老百姓大药房、国大药房、海王星辰等 超市：天虹等
4. 商户侧流程 根据商户具体的情况，被扫支付接入模式可分为：商户后台接入和门店接入；根据用户是否
需要输入支付
密码可分为：免密模式和验密模式。
1
接入模式-商户后台接入 该模式适合具备统一后台系统的商户。
门店收银台与商户后台通信，商户后台系统
负责与微信支付系统发 送交易请求和接收返回结果。
图5.4 商户后台接入被扫支付
2 接入模式-门店接入该模式适合门店收银台通过公网直接与微信后台通信的商户。
门店收银台直接发起交易
请求和处理返回结
果。
商户可以根据实际需要，处理门店和商户后台系统之间的其它业务流程。
图5.5 门店接入被扫支付
3 免密支付流程本节以商户后台接入模式说明支付流程，请参
看以下时序图：
图5.6 被扫支付免密流程时序图
流程详细说明：
1) 收银员在商户收银台生成支付订单，向用户展示支付金额；
2) 用户打开微信客户端，点击“我的钱包”，选择“刷卡”，进入条码界面；
3) 使用扫码设备读取用户手机屏幕上的条码；
4) 扫码设备将读取的信息上传给门店收银台；
5) 门店收银台得到支付信息后，向商户收银后台发起支付请求。
6) 商户后台对门店收银台的支付请求进行处理，生成签名后调用【提交被扫支付API】向微信支付系统
发起支付请求。
7) 微信支付系统得到商户侧的支付请求之后会对请求进行验证，验证通过之后会对请求数据进行处理，
最后将处理后的支付结果返回给商户收银后台。
如果支付成功，微信支付系统会将支付结果返回给商户
，同时把支付结果通知给用户（以短信、微信消息的形式通知）。
8) 商户收银后台对得到的支付结果进行签名验证和处理，再将支付结果返回给门店收银台。
9) 收银员看到门店收银台的支付结果后给用户发货。
4 验密支付流程
场景交互与免密模式相同，不同的是在商户调用【提交被扫支付API】发起支付请求之后，微信支付后台提示用户输入密码确认支付，接口同步返回USERPAYING 状态，商户系统再轮询调用查询订单接口来确认当前用户是否已经支付成功。
以下时序图说明验密支付流程：
图5.7 被扫支付验证密码流程时序图
由于在商户收银后台向微信支付系统发起支付请求之前的流程是完全一样的，所以这里只介绍商户发起支付请求之后的逻辑。
1) 商户门店生成订单后，收银台向后台系统发起支付请求。
2) 后台调用微信支付【提交被扫支付API】生成支付交易。
3) 微信支付系统对商户请求进行验证，验证通过后判断当前用户需要输入密码。
4) 微信支付系统返回USERPAYING 状态，商户后台系统将应答结果返回给商户门店收银台。
5) 微信支付系统通知用户微信客户端输入密码。
6) 用户得到输入密码提示后，确认支付并输入密码。
7) 完成密码输入，提交微信支付。
8) 微信客户端在用户完成支付后提示微信支付后台系统返回的支付结果，而且微信支付系统会通过短信
、微信消息给用户发送支付结果提醒。
9) 商户收银台得到USERPAYING 状态后，经过商户后台系统调用【查询订单API】（详见公共API）
查询实际支付结果。
10) 如果支付结果仍为USERPAYING，则每隔5 秒循环调用【查询订单API】判断实际支付结果，如果
用户取消支付或累计30 秒用户都未支付，商户收银台退出查询流程后继续调用【撤销订单API】撤销支付交易。
5 异常处理用户遇到支付异常，请按如
下说明处理
1) 用户微信端弹出系统错误提示框，用户可在交易列表查看交易情况，如果未找到订单，需要商户重新
发起支付交易；如果订单显示成功支付，商户收银系统再次调用【查询订单API】查询实际支付结果；
2) 用户微信端弹出支付失败提示，例如：余额不足，信用卡失效。
需要重新发起支付；
3) 当交易超时或支付交易失败，商户收银系统必须调用【撤销支付API】（详见公共API），撤销此交
易。
4) 由于银行系统异常、用户余额不足、不支持用户卡种等原因使当前支付交易失败，商户收银系统应该把
错误提示明确展示给收银员。
5) 根据返回的错误码，判断是否需要撤销交易，具体详见A PI 返回错误码列表
5. 提交被扫支付API
1 应用场景收银员使用扫码设备读取微信用户刷卡授权码以后，二维码或条码信息传送至商户收银台，由商户
收银台
或者商户后台调用该接口发起支付。
2 接口地址
https:///pay/micropay 3 是否需要证书
不需要。
4 输入参数
5 返回结果
举例如下：
6 错误码
7 API 工具
6. 查询订单API
详见【公共API 第9.2 节查询订单】
7. 申请退款API
详见【公共API 第9.4 节申请退款】
8. 查询退款API
详见【公共API 第9.5 节查询退款】
9. 撤销支付API
1 应用场景支付交易返回失败或支付系统超时，调用该接口撤销交易。
如果此订单用户支付失败，微信支付系
统会将
此订单关闭；如果用户支付成功，微信支付系统会将此订单资金退还给用户。
注意：7 天以内的交易单可调用撤销，其他正常支付的单如需实现相同功能请调用申请退款API。
提交支付交易后调用【查询订单API】，没有明确的支付结果再调用【撤销订单API】。
2 接口链接
https:///secapi/pay/reverse
3 是否需要证书
请求需要双向证书。
详见第4.3.3 节使用证书
4 请求参数
返回结果
5 错误码
10. 下载对账单API
详见【公共API 第9.6 节下载对账单】
11. 上报测速
为提高支付服务质量，建议商户系统将支付接口时延情况通过上报测速API 发给微信支付后台。
详见【公共API 上报测速API】。
6. 扫码原生支付模式开发指引
1. 场景介绍用户扫描商户展示在各种场景的二维
码进行支付。
步骤1：商户根据微信支付的规则，为不同商品生成不同的二维码（如图 6.1），展示在各种场景，用于用户扫描购买。
步骤2：用户使用微信“扫一扫”（如图 6.2）扫描二维码后，获取商品支付信息，引导用户完成支付（如图6.3）。
图6.1 支付二维码图6.2 打开微信扫一扫二维码图6.3 确认支付页面
步骤（3）：用户确认支付，输入支付密码（如图 6.4）。
步骤（4）：支付完成后会提示用户支付成功（如
图 6.5），商户后台得到支付成功的通知，然后进行发货
处理。
图 6.4 用户确认支付，输入密码
图 6.5 支付成功提示
2. 案例介绍 目前已上线支付案例，商户可进
行实际体验。
线下：上品折扣线下店。
线上：京东、携程等
3.
扫码原生支付开发步骤
1 开通支付权限
在微信公众平台设置支付权限，进入栏目微信支付-》开发配置-》修改，如图 6.6 所示。
图 6.6 原生支付参数设置栏目入口
进入修改页面后，找到公众号支付-》Native 原生支付，勾选Native 原生支付开通该权限，在支付回调URL 上填写商户支付后台系统的网页地址。
图6.7 原生支付设置权限及支付回调地址
2 根据应用场景选择实现模式扫码支付可分为两种模式，商户
根据支付场景选择相应模式。
模式一：商户后台系统根据微信支付规则链接生成二维码，链接中带固定参数productid（可定义为产品标识或订单号）。
用户扫码后，微信支付系统将productid 和用户openid(用户标识)回调商户后台系统，商户后台系统根据p roductid 生成支付交易，最后微信支付系统发起用户支付流程。
模式二：商户后台系统调用微信支付【统一下单API】生成预付交易，将接口返回的链接生成二维码，用户扫码后输入密码完成支付交易。
注意：该模式的预付单有效期为 2 小时，过期后无法支付。
4. 模式一
模式一开发前，商户必须在公众平台后台设置支付回调URL。
URL 实现的功能：接收用户扫码后微信支付系统回调的productid 和openid；URL 设置详见本章第6.3.1 节。
1 业务流程时序图
图6.8：原生支付接口模式一时序图
业务流程说明：
1) 商户后台系统根据微信支付规定格式生成二维码（规则见本章第 6.4.2 节），展示给用户扫码。
2) 用户打开微信“扫一扫”扫描二维码，微信客户端将扫码内容发送到微信支付系统。
3) 微信支付系统收到客户端请求，发起对商户后台系统支付回调U RL 的调用。
调用请求将带productid
和用户的openid 等参数，并要求商户系统调返回prepay_id（【统一下单API】返回的交易会话标识，有效期2 小时）才能发起用户支付。
4) 商户后台系统收到微信支付系统的回调请求，根据productid 生成商户系统的订单。
5) 商户系统调用微信支付【统一下单API】请求生成交易会话标识。
6) 微信支付系统根据商户系统的请求生成预支付交易，返回交易会话标识prepay_id。
7) 商户后台系统得到交易会话标识prepay_id。
8) 商户后台系统将prepay_id 返回给微信支付系统。
9) 微信支付系统根据交易会话标识，发起用户端授权支付流程。
10) 用户在微信客户端输入密码，确认支付后，微信客户端提交支付授权。
11) 微信支付系统验证后扣款，完成支付交易。
12) 微信支付系统完成支付交易后给微信客户端返回交易结果，并将交易结果通过短信、微信消息提示用
户。
微信客户端展示支付交易结果页面。
13) 微信支付系统通过发送异步消息通知商户后台系统支付结果。
商户后台系统需回复接收情况，通知微
信后台系统不再发送该单的支付通知。
14) 未收到支付通知的情况，商户后台系统调用【查询订单API】。
15) 商户确认订单已支付后给用户发货。
2 生成二维码规则二维码中的内容
为链接，形式为：
weixin://wxpay/bizpayurl?sign=XXXXX&appid=XXXXX&mch_id=XXXXX&product_id=XXXXXX&time _stamp=XXXXXX&nonce_str=XXXXX
其中XXXXX 为商户需要填写的内容，商户将该链接生成二维码，如需要打印发布二维码，需要采用此格式。
商户可调用第三方库生成二维码图片。
参数说明如下：
表6.1 生成二维码所需参数列表
举例：
weixin://wxpay/bizpayurl?appid=wx2421b1c4370ec43b&mch_id=10000100&nonce_str=f6808210402125e30663234f94c87a8c&product_id=1&time _stamp=1415949957&sign=512F68131DD251DA4A45DA79CC7EFE9D
3 回调商户支付URL
商户提供的支付回调U RL（设置请见6.3.1 节）需要实现以下功能：接收用户扫码后微信支付系统发送的数据，根据接收的数据生成支付订单，调用【统一下单API】提交支付交易。
1. 输入参数
表6.2 输入参数说明
2. 输出参数
表6.3 输出参数说明
5. 模式二
模式二与模式一相比，流程更为简单，不依赖设置的回调支付URL。
商户后台系统先调用微信支付的统一下单接口，微信后台系统返回链接参数code_url，商户后台系统将code_url 值生成二维码图片，用户使用微信客户端扫码后发起支付。
注意：code_url 有效期为2 小时，过期后扫码不能再发起支付。
1 业务流程时序图
图6.9 原生支付模式二时序图
业务流程说明：
1) 商户后台系统根据用户选购的商品生成订单。
2) 用户确认支付后调用微信支付【统一下单API】生成预支付交易；
3) 微信支付系统收到请求后生成预支付交易单，并返回交易会话的二维码链接code_url。
4) 商户后台系统根据返回的code_url 生成二维码。
5) 用户打开微信“扫一扫”扫描二维码，微信客户端将扫码内容发送到微信支付系统。
6) 微信支付系统收到客户端请求，验证链接有效性后发起用户支付，要求用户授权。
7) 用户在微信客户端输入密码，确认支付后，微信客户端提交授权。
8) 微信支付系统根据用户授权完成支付交易。
9) 微信支付系统完成支付交易后给微信客户端返回交易结果，并将交易结果通过短信、微信消息提示用户。
微信客户端展示支付交易结果页面。
10) 微信支付系统通过发送异步消息通知商户后台系统支付结果。
商户后台系统需回复接收情况，通知微
信后台系统不再发送该单的支付通知。
11) 未收到支付通知的情况，商户后台系统调用【查询订单API】。
12) 商户确认订单已支付后给用户发货。
2 生成二维码规则
对应链接格式：weixin://wxpay/bizpayurl?sr=XXXXX。
请商户调用第三方库将code_url 生成二维码图片。
该模式链接较短，生成的二维码打印到结账小票上的识别率较高。
例如，将weixin://wxpay/s/An4baqw 生成二维码见图6.10。
图6.10 原生支付“模式二”二维码示例
6. 统一下单API注意交易类型（trade_type）
填写：NATIVE。
详见【公共API 第9.1 节统
一下单】
7. 查询订单API
详见【公共API 第9.2 节查询订单】
8. 关闭订单API
详见【公共API 第9.3 节关闭订单】
9. 申请退款API
详见【公共API 第9.4 节申请退款】
10. 查询退款API
详见【公共API 第9.5 节查询退款】
11. 下载对账单API
详见【公共API 第9.6 节下载对账单】
12. 上报测速
为提高支付服务质量，建议商户系统将支付接口时延情况通过上报测速API 发给微信支付后台。
详见【公共API 上报测速API】。
13. 二维码相关知识二维码背
景知识介绍：
/qr-code-tutorial/
/articles/10590.html
7. 微信内网页支付
1. 场景介绍
商户已有H5 商城网站，用户通过消息或扫描二维码在微信内打开网页时，可以调用微信支付完成下单购买的流程。