微信支付API文档120受理.docx

1、微信支付API文档120受理1. 阅读对象本文阅读对象：商户系统（在线购物平台、人工收银系统、自动化智能收银系统或其他）集成微信支付涉 及的技术架构师，研发工程师，测试工程师，系统运维工程师。2. 术语1. 支付模式1) 被扫支付 被扫支付是用户展示微信上“我的刷卡条码/二维码”给商户系统扫描后直接完成支付的模式。主要应用线下面对面收银的场景。2) 扫码支付 扫码支付是商户系统按微信支付协议生成支付二维码，用户再用微信“扫一扫”完成支付的模式。该模式适用于 PC 网站支付、实体店单品或订单支付、媒体广告支付等场景。3) 微信内网页支付微信内网页支付是用户在微信中打开商户的 H5 页面，商户在

2、H5 页面通过调用微信支付提供的 JSAPI 接 口调起微信支付模块完成支付。应用场景有： 用户在微信公众账号内进入商家公众号，打开某个主页面，完成支付； 用户的好友在朋友圈、聊天窗口等分享商家页面连接，用户点击链接打开商家页面，完成支付 将商户页面转换成二维码，用户扫描二维码后在微信浏览器中打开页面后完成支付4) APP 支付APP 支付又称移动端支付，是商户通过在移动端应用 APP 中集成开放 SDK 调起微信支付模块完成支付的 模式。5) 普通浏览器网页支付模式 正在建设中，敬请期待。2. 名词解释1) 微信公众平台 微信公众平台是微信公众账号申请入口和管理后台。商户可以在公众平台提交基

3、本资料、业务资料、财务资料申请开通微信支付功能。平台入口：。2) 微信开放平台微信开放平台是商户 APP 接入微信支付开放接口的申请入口，通过此平台可申请微信 APP 支付。 平台入口：。3) 微信商户平台微信商户平台是微信支付相关的商户功能集合，包括参数配置、支付数据查询与统计、在线退款、代金券 或立减优惠运营等功能。平台入口：。4) 微信支付系统微信支付系统是指完成微信支付流程中涉及的 API 接口、后台业务处理系统、账务系统、回调通知等系统 的总称。5) 商户收银系统商户收银系统即商户的 POS 收银系统，是录入商品信息、生成订单、客户支付、打印小票等功能的系统。 接入微信支付功能主要涉

4、及到 POS 软件系统的开发和测试，所以在下文中提到的商户收银系统特指 POS 收银 软件系统。6) 商户后台系统 商户后台系统是商户后台处理业务系统的总称，例如：商户网站、收银系统、进销存系统、发货系统、客服系统等。7) 扫码设备一种输入设备，主要用于商户系统快速读取媒介上的图形编码信息。按读取码的类型不同，可分为条码扫 码设备和二维码扫码设备。按读取物理原理可分为红外扫码设备、激光扫码设备。8) 商户证书商户证书是微信提供的二进制文件，商户系统发起与微信支付后台服务器通信请求的时候，作为微信支付 后台识别商户真实身份的凭据。9) 签名 商户后台和微信支付后台根据相同的密钥和算法生成一个结果

5、，用于校验双方身份合法性。签名的算法由微信支付制定并公开，常用的签名方式有：MD5、SHA1、SHA256、HMAC 等。10) JSAPI 网页支付 即前文说的微信内网页支付，可在微信公众号、朋友圈、聊天会话中点击页面链接，或者用微信“扫一扫”扫描页面地址二维码在微信中打开商户 HTML5 页面，在页面内下单完成支付。11) Native 原生支付Native 原生支付属于扫码支付，商户根据微信支付协议格式生成的二维码，用户通过微信“扫一扫”扫描 二维码后即进入付款确认界面，输入密码即完成支付。12) 支付密码支付密码是用户开通微信支付时单独设置的密码，用于确认支付完成交易授权。该密码与微信

6、登录密码不同。13) Openid用户在公众号内的身份标识，不同公众号拥有不同的 openid。商户后台系统通过登录授权、支付通知、查 询订单等 API 可获取到用户的 openid。主要用途是判断同一个用户，对用户发送客服消息、模版消息等。3. 支付账户商户在微信公众平台(申请扫码原生支付、微信内网页支付)或开放平台(申请 APP 支付)按照相应提示，申 请相应微信支付模式。微信支付工作人员审核资料无误后开通相应的微信支付权限。微信支付申请审核通过后， 商户在申请资料填写的邮箱中收取到由微信支付小助手发送的邮件，此邮件包含开发时需要使用的支付账户信 息，见图 3.1 所示。图 3.1 微信审

7、核通过邮件模板邮件中的账户参数与接口 API 参数对应关系见表格 3.1： 表 3.1：账户参数说明邮件中参数API 参数名 称详细说明APPIDappidappid 是微信公众账号或开放平台 APP 的唯一标识，在公众平台申请公众账号或 者在开放平台申请 APP 账号后，微信会自动分配对应的 appid，用于标识该应用。 商户的微信支付审核通过邮件中也会包含该字段值。微信支付商户号mch_id商户申请微信支付后，由微信支付分配的商户收款账号。API 密钥key交易过程生成签名的密钥，仅保留在商户系统和微信支付后台，不会在网络中传 播。商户妥善保管该 Key，切勿在网络中传输，不能在其他客户端

8、中存储，保证 key 不会被泄漏。商户可根据邮件提示登录微信商户平台进行设置。AppsecretsecretAppSecret 是 APPID 对应的接口密码，用于获取接口调用凭证 access_token 时 使用。在微信支付中，先通过 OAuth2.0 接口获取用户 openid，此 openid 用于微 信内网页支付模式下单接口使用。在开发模式中获取 AppSecret（成为开发者且 帐号没有异常状态）。4. 接口规则1. 协议规则商户接入微信支付，调用 API 必须遵循以下规则： 表 4.1：接口规则传输方式为保证交易安全性，采用 HTTPS 传输提交方式采用 POST 方法提交数据格

9、式提交和返回数据都为 XML 格式，根节点名为 xml字符编码统一采用 UTF-8 字符编码签名算法MD5，后续会兼容 SHA1、SHA256、HMAC 等。签名要求请求和接收数据均需要校验签名，签名的详细方法请参考下文第 4.3.1 节证书要求调用申请退款、撤销订单接口需要商户证书判断逻辑先判断协议字段返回，再判断业务返回，最后判断交易状态2. 参数规定1) 交易金额交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。对账单中的交易金 额单位为【元】。外币交易的支付金额精确到币种的最小单位，参数值不能带小数点。2) 货币类型货币类型的取值列表： CNY：人民币 GBP

10、：英镑 HKD：港币 USD：美元JPY：日元 CAD：加拿大元 AUD：澳大利亚元 EUR：欧元注：退款币种与支付币种必须一致3) 时间 标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时4) 时间戳标准北京时间，时区为东八区，自 1970 年 1 月 1 日 0 点 0 分 0 秒以来的秒数。注意：部分系统取到的值 为毫秒级，需要转换成秒(10 位数字)。5) 商户订单号 商户支付的订单号由商户自定义生成，微信支付要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过或已调用关

11、单、撤销（请见后文的 API 列表）的订单号不能重新发起支付。6) 交易类型JSAPI：即微信网页内支付 NATIVE：即扫码支付 APP：即 APP 支付MICROPAY：即被扫支付 WAP：非微信手机浏览器支付3. 安全规范1 签名算法 签名生成的通用步骤如下：第一步，设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名称的 ASCII码从小到大排序（字典序），使用 URL 键值对的格式（即 key1=value1&key2=value2）拼接成字符串 stringA。 特别注意以下重要规则： 参数名称 ASCII 码从小到大排序（字典序）； 如果参数的值为空不参

12、与签名； 参数名称区分大小写； 验证调用返回或微信主动通知签名时，传送的 sign 参数不参与签名，将生成的签名与该 sign 值 作校验。 微信接口可能增加字段，验证签名时必须支持增加的扩展字段第二步，在 stringA 最后拼接上 key=(API 密钥的值)得到 stringSignTemp 字符串，并对 stringSignTemp进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign 值 signValue。 举例：假设传送的参数如下：appid： wxd930ea5d5a258f4fdevice_info： 1000body： testnonce_str： ibua

13、iVcKdpRxkhJA第一步：对参数按照 key=value 的格式，并按照参数名称 ASCII 字典序排序如下：stringA=appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ib第二步：拼接 API 密钥：stringSignTemp=stringA&key=192006250b4c09247ec02edce69f6a2dsign=MD5(stringSignTemp).toUpperCase()=9A0A8659F005D6984697E2CA0A9CF3B7最终得到最终发送的数

14、据：微信提供相关接口在线签名验证工具：点击进入。2 生成随机数算法微信支付 API 接口协议中包含字段 nonce_str，主要保证签名不可预测。我们推荐生成随机数算法如下： 调用随机数函数生成，将得到的值转换为字符串。3 商户证书1) 获取商户证书 微信支付接口中，涉及资金回滚的接口会使用到商户证书，包括退款、撤销接口。商家在申请微信支付成功后，收到的相应邮件通知中，附件会包含接口需要用到的证书文件，有四个证书文件，分别说明如下。 表 4.2：证书文件说明证书附件描述使用场景备注pkcs12 格式包含了私钥信息的证书文撤销、退款申请 API 中调用windows 上可以直接双击导入系统，(a

15、piclient_cert.p12)件，为 p12(pfx)格式，由微导入过程中会提示输入证书密码，证信支付签发给您用来标识和书密码默认为您的商户 ID（如：界定您的身份10010000）证书 pem 格式从 apiclient_cert.p12 中导出PHP 等不能直接使用 p12 文您也可以使用 openssl 命令来自己导（apiclient_cert.pem）证书部分的文件，为 pem 格件，而需要使用 pem，为了出：openssl pkcs12 -clcerts -nokeys式，请妥善保管不要泄漏和方便您使用，已为您直接提-in apiclient_cert.p12 -out被他

16、人复制供apiclient_cert.pem证书密钥 pem 格式从 apiclient_cert.p12 中导出PHP 等不能直接使用 p12 文您也可以使用 openssl 命令来自己导（apiclient_key.pem）密钥部分的文件，为 pem 格件，而需要使用 pem，为了出：openssl pkcs12 -nocerts -in式方便您使用，已为您直接提apiclient_cert.p12 -out供apiclient_key.pemCA 证书微信支付 api 服务器上也部该文件为签署微信支付证书部分工具已经内置了若干权威机构的（rootca.pem）署了证明微信支付身份的服的权

17、威机构的根证书，可以根证书，无需引用该证书也可以正常务器证书，您在使用 api 进用来验证微信支付服务器证进行验证，这里提供给您在未内置所行调用时也需要验证所调用书的真实性必须根证书的环境中载入使用服务器及域名的真实性2) 使用商户证书。 apiclient_cert.p12 是商户证书文件，除 PHP 外的开发均使用此证书文件。 商户如果使用.NET 环境开发，请确认 Framework 版本大于 2.0，必须在操作系统上双击安装证书 apiclient_cert.p12 后才能被正常调用。 商户证书调用或安装都需要使用到密码，该密码的值为微信商户号（mch_id） PHP 开发环境请使用商

18、户证书文件 apiclient_cert.pem 和 apiclient_key.pem ，rootca.pem 是 CA 证 书。各版本的调用实例请参考微信支付提供的 Demo。3) 商户证书安全证书文件不能放在 web 服务器虚拟目录，应放在有访问权限控制的目录中，防止被他人下载。商户服务器 要做好病毒和木马防护工作，不被非法侵入者窃取证书文件。4 商户回调 API 安全在普通的网络环境下，HTTP 请求存在 DNS 劫持、运营商插入广告、数据被窃取，正常数据被修改等安 全风险。商户回调接口使用 HTTPS 协议可以保证数据传输的安全性。所以微信支付建议商户提供给微信支付 的各种回调采用

19、HTTPS 协议。请参考：HTTPS 搭建指南。5. 被扫支付模式开发指引1. 场景介绍步骤 1：用户选择被扫支付付款并打开微信，进入“我”-“钱包”-“刷卡”条码界面（如图 5.1 所示）； 步骤 2：收银员在商户系统操作生成支付订单，用户确认支付金额；步骤 3：商户收银员用扫码设备扫描用户的条码/二维码，商户收银系统提交支付；步骤 4：微信支付后台系统收到支付请求，根据验证密码规则判断是否验证用户的支付密码，不需要验证 密码的交易直接发起扣款，需要验证密码的交易会弹出密码输入框（如图 5.2 所示）。支付成功后微信端会弹出成功页面（如图 5.3 所示），支付失败会弹出错误提示。 图 5.1

20、 我的钱包刷卡界面 图 5.2 输入密码，确认支付 图 5.3 支付成功后页面提示2. 支付验证密码规则 支付金额300 元的交易需要验证用户支付密码； 用户账号每天最多有 10 笔交易可以免密，超过后需要验证密码； 微信支付后台判断用户支付行为有异常情况，符合免密规则的交易也会要求验证密码；3. 案例介绍 目前已上线被扫支付案例，商户可自行前往店里实际体验。 便利店：711 便利店、国大 36524、好邻居等 连锁药店：老百姓大药房、国大药房、海王星辰等 超市：天虹等4. 商户侧流程 根据商户具体的情况，被扫支付接入模式可分为：商户后台接入和门店接入；根据用户是否需要输入支付密码可分为：免密

21、模式和验密模式。1 接入模式-商户后台接入 该模式适合具备统一后台系统的商户。门店收银台与商户后台通信，商户后台系统负责与微信支付系统发送交易请求和接收返回结果。图 5.4 商户后台接入被扫支付2 接入模式-门店接入 该模式适合门店收银台通过公网直接与微信后台通信的商户。门店收银台直接发起交易请求和处理返回结果。商户可以根据实际需要，处理门店和商户后台系统之间的其它业务流程。图 5.5 门店接入被扫支付3 免密支付流程 本节以商户后台接入模式说明支付流程，请参看以下时序图：图 5.6 被扫支付免密流程时序图 流程详细说明：1) 收银员在商户收银台生成支付订单，向用户展示支付金额；2) 用户打开

22、微信客户端，点击“我的钱包”，选择“刷卡”，进入条码界面；3) 使用扫码设备读取用户手机屏幕上的条码；4) 扫码设备将读取的信息上传给门店收银台；5) 门店收银台得到支付信息后，向商户收银后台发起支付请求。6) 商户后台对门店收银台的支付请求进行处理，生成签名后调用【提交被扫支付 API】向微信支付系统 发起支付请求。7) 微信支付系统得到商户侧的支付请求之后会对请求进行验证，验证通过之后会对请求数据进行处理， 最后将处理后的支付结果返回给商户收银后台。如果支付成功，微信支付系统会将支付结果返回给商 户，同时把支付结果通知给用户（以短信、微信消息的形式通知）。8) 商户收银后台对得到的支付结果

23、进行签名验证和处理，再将支付结果返回给门店收银台。9) 收银员看到门店收银台的支付结果后给用户发货。4 验密支付流程场景交互与免密模式相同，不同的是在商户调用【提交被扫支付 API】发起支付请求之后，微信支付后台 提示用户输入密码确认支付，接口同步返回 USERPAYING 状态，商户系统再轮询调用查询订单接口来确认当 前用户是否已经支付成功。以下时序图说明验密支付流程：图 5.7 被扫支付验证密码流程时序图由于在商户收银后台向微信支付系统发起支付请求之前的流程是完全一样的，所以这里只介绍商户发起支 付请求之后的逻辑。1) 商户门店生成订单后，收银台向后台系统发起支付请求。2) 后台调用微信支

24、付【提交被扫支付 API】生成支付交易。3) 微信支付系统对商户请求进行验证，验证通过后判断当前用户需要输入密码。4) 微信支付系统返回 USERPAYING 状态，商户后台系统将应答结果返回给商户门店收银台。5) 微信支付系统通知用户微信客户端输入密码。6) 用户得到输入密码提示后，确认支付并输入密码。7) 完成密码输入，提交微信支付。8) 微信客户端在用户完成支付后提示微信支付后台系统返回的支付结果，而且微信支付系统会通过短 信、微信消息给用户发送支付结果提醒。9) 商户收银台得到 USERPAYING 状态后，经过商户后台系统调用【查询订单 API】（详见公共 API） 查询实际支付结果

25、。10) 如果支付结果仍为 USERPAYING，则每隔 5 秒循环调用【查询订单 API】判断实际支付结果，如果 用户取消支付或累计 30 秒用户都未支付，商户收银台退出查询流程后继续调用【撤销订单 API】撤 销支付交易。5 异常处理 用户遇到支付异常，请按如下说明处理1) 用户微信端弹出系统错误提示框，用户可在交易列表查看交易情况，如果未找到订单，需要商户重新 发起支付交易；如果订单显示成功支付，商户收银系统再次调用【查询订单 API】查询实际支付结果；2) 用户微信端弹出支付失败提示，例如：余额不足，信用卡失效。需要重新发起支付；3) 当交易超时或支付交易失败，商户收银系统必须调用【撤

26、销支付 API】（详见公共 API），撤销此交 易。4) 由于银行系统异常、用户余额不足、不支持用户卡种等原因使当前支付交易失败，商户收银系统应该 把错误提示明确展示给收银员。5) 根据返回的错误码，判断是否需要撤销交易，具体详见 API 返回错误码列表5. 提交被扫支付 API1 应用场景 收银员使用扫码设备读取微信用户刷卡授权码以后，二维码或条码信息传送至商户收银台，由商户收银台或者商户后台调用该接口发起支付。2 接口地址3 是否需要证书 不需要。4 输入参数名称变量名类型必 填示例值描述公众账号IDappidString(32)是wx8888888888888888微信分配的公众账号 I

27、D商户号mch_idString(32)是1900000109微信支付分配的商户号子商户公 众账号 IDsub_appidString(32)否微信分配的子商户公众账 号 ID子商户公众账号 ID子商户号sub_mch_idString(32)是微信支付分配的子商户号， 受理模式下必填子商户号设备号device_infoString(32)否013467007045764终端设备号(商户自定义，如门店编 号)随机字符nonce_strString(32)是5K8264ILTKCH16CQ250随机字符串，不长于 32 位。推荐生串2SI8ZNMTM67VS成算法详见第 4.3.2 节签名sig

28、nString(32)是C380BEC2BFD727A4B68 45133519F3AD6签名，详见 4.3.1 节签名生成算法商品描述bodyString(127)是Q 币购买订单支付商品或支付单描述，展示给用户商品详情detailString(8192)否Ipad mini 16G 白色传详细的商品列表附加数据attachString(127)否自定义数据商户扩展字段，提交支付后在查询API 和支付通知中原样返回商户订单out_trade_nString(32)是121775*703323商户系统内部的订单号,32 个字符号o3368018内、可包含字母, 其他说明见第 4.2节商户订单号

29、总金额total_feeInt是888订单总金额，单位为分，只能为整 数，详见第 4.2 节支付金额货币类型fee_typeString(16)否CNY符合 ISO 4217 标准的三位字母代 码，默认人民币：CNY，其他值列表详见第 4.2 节货币类型终端 IPspbill_create_ipString(16)是8.8.8.8调用微信支付 API 的机器 IP交易起始time_startString(14)否20091225091010订单生成时间，格式为时间yyyyMMddHHmmss，如 2009 年12 月 25 日 9 点 10 分 10 秒表示为20091225091010。其他详见第 4.2节时间规则交易失效time_expireString(14)否20091227091010订单失效时间，格式为时间yyyyMMddHHmmss，如 2009 年12 月 27 日 9 点 10 分 10 秒表示为20091227091010。其他详见第 4.2节时间规则商品标记goods_tagString(32)否商品标记，代金券或立减优惠功 能的参数，说明详见第 10 节代金 券或立减优惠授权码auth_codeString(128)是12