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

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

《微信支付API文档120受理.docx》由会员分享，可在线阅读，更多相关《微信支付API文档120受理.docx（143页珍藏版）》请在冰点文库上搜索。

微信支付API文档120受理

1.阅读对象

本文阅读对象：

商户系统（在线购物平台、人工收银系统、自动化智能收银系统或其他）集成微信支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。

2.术语

1.支付模式

1）被扫支付被扫支付是用户展示微信上“我的刷卡条码/二维码”给商户系统扫描后直接完成支付的模式。

主要应用线

下面对面收银的场景。

2）扫码支付扫码支付是商户系统按微信支付协议生成支付二维码，用户再用微信“扫一扫”完成支付的模式。

该模式

适用于PC网站支付、实体店单品或订单支付、媒体广告支付等场景。

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。

商户后台系统通过登录授权、支付通知、查询订单等API可获取到用户的openid。

主要用途是判断同一个用户，对用户发送客服消息、模版消息等。

3.支付账户

商户在微信公众平台（申请扫码原生支付、微信内网页支付）或开放平台（申请APP支付）按照相应提示，申请相应微信支付模式。

微信支付工作人员审核资料无误后开通相应的微信支付权限。

微信支付申请审核通过后，商户在申请资料填写的邮箱中收取到由微信支付小助手发送的邮件，此邮件包含开发时需要使用的支付账户信息，见图3.1所示。

图3.1微信审核通过邮件模板

邮件中的账户参数与接口API参数对应关系见表格3.1：

表3.1：

账户参数说明

邮件中参数

API参数名称

详细说明

APPID

appid

appid是微信公众账号或开放平台APP的唯一标识，在公众平台申请公众账号或者在开放平台申请APP账号后，微信会自动分配对应的appid，用于标识该应用。

商户的微信支付审核通过邮件中也会包含该字段值。

微信支付商户号

mch_id

商户申请微信支付后，由微信支付分配的商户收款账号。

API密钥

key

交易过程生成签名的密钥，仅保留在商户系统和微信支付后台，不会在网络中传播。

商户妥善保管该Key，切勿在网络中传输，不能在其他客户端中存储，保证key不会被泄漏。

商户可根据邮件提示登录微信商户平台进行设置。

Appsecret

secret

AppSecret是APPID对应的接口密码，用于获取接口调用凭证access_token时使用。

在微信支付中，先通过OAuth2.0接口获取用户openid，此openid用于微信内网页支付模式下单接口使用。

在开发模式中获取AppSecret（成为开发者且帐号没有异常状态）。

4.接口规则

1.协议规则

商户接入微信支付，调用API必须遵循以下规则：

表4.1：

接口规则

传输方式

为保证交易安全性，采用HTTPS传输

提交方式

采用POST方法提交

数据格式

提交和返回数据都为XML格式，根节点名为xml

字符编码

统一采用UTF-8字符编码

签名算法

MD5，后续会兼容SHA1、SHA256、HMAC等。

签名要求

请求和接收数据均需要校验签名，签名的详细方法请参考下文第4.3.1节

证书要求

调用申请退款、撤销订单接口需要商户证书

判断逻辑

先判断协议字段返回，再判断业务返回，最后判断交易状态

2.参数规定

1）交易金额

交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。

对账单中的交易金额单位为【元】。

外币交易的支付金额精确到币种的最小单位，参数值不能带小数点。

2）货币类型

货币类型的取值列表：

CNY：

人民币GBP：

英镑HKD：

港币USD：

美元

JPY：

日元CAD：

加拿大元AUD：

澳大利亚元EUR：

欧元

注：

退款币种与支付币种必须一致

3）时间标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。

参数值必须根据商户系统所在时

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字典序排序如下：

stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ib

第二步：

拼接API密钥：

stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"

sign=MD5（stringSignTemp）.toUpperCase（）="9A0A8659F005D6984697E2CA0A9CF3B7"

最终得到最终发送的数据：

微信提供相关接口在线签名验证工具：

点击进入。

2生成随机数算法

微信支付API接口协议中包含字段nonce_str，主要保证签名不可预测。

我们推荐生成随机数算法如下：

调用随机数函数生成，将得到的值转换为字符串。

3商户证书

1）获取商户证书微信支付接口中，涉及资金回滚的接口会使用到商户证书，包括退款、撤销接口。

商家在申请微信支付成

功后，收到的相应邮件通知中，附件会包含接口需要用到的证书文件，有四个证书文件，分别说明如下。

表4.2：

证书文件说明

证书附件

描述

使用场景

备注

pkcs12格式

包含了私钥信息的证书文

撤销、退款申请API中调用

windows上可以直接双击导入系统，

（apiclient_cert.p12）

件，为p12（pfx）格式，由微

导入过程中会提示输入证书密码，证

信支付签发给您用来标识和

书密码默认为您的商户ID（如：

界定您的身份

10010000）

证书pem格式

从apiclient_cert.p12中导出

PHP等不能直接使用p12文

您也可以使用openssl命令来自己导

（apiclient_cert.pem）

证书部分的文件，为pem格

件，而需要使用pem，为了

出：

opensslpkcs12-clcerts-nokeys

式，请妥善保管不要泄漏和

方便您使用，已为您直接提

-inapiclient_cert.p12-out

被他人复制

供

apiclient_cert.pem

证书密钥pem格式

从apiclient_cert.p12中导出

PHP等不能直接使用p12文

您也可以使用openssl命令来自己导

（apiclient_key.pem）

密钥部分的文件，为pem格

件，而需要使用pem，为了

出：

opensslpkcs12-nocerts-in

式

方便您使用，已为您直接提

apiclient_cert.p12-out

供

apiclient_key.pem

CA证书

微信支付api服务器上也部

该文件为签署微信支付证书

部分工具已经内置了若干权威机构的

（rootca.pem）

署了证明微信支付身份的服

的权威机构的根证书，可以

根证书，无需引用该证书也可以正常

务器证书，您在使用api进

用来验证微信支付服务器证

进行验证，这里提供给您在未内置所

行调用时也需要验证所调用

书的真实性

必须根证书的环境中载入使用

服务器及域名的真实性

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）根据返回的错误码，判断是否需要撤销交易，具体详见API返回错误码列表

5.提交被扫支付API

1应用场景收银员使用扫码设备读取微信用户刷卡授权码以后，二维码或条码信息传送至商户收银台，由商户收银台

或者商户后台调用该接口发起支付。

2接口地址

3是否需要证书不需要。

4输入参数

名称

变量名

类型

必填

示例值

描述

公众账号

ID

appid

String（32）

是

wx8888888888888888

微信分配的公众账号ID

商户号

mch_id

String（32）

是

1900000109

微信支付分配的商户号

子商户公众账号ID

sub_appid

String（32）

否

微信分配的子商户公众账号ID

子商户公众账号ID

子商户号

sub_mch_id

String（32）

是

微信支付分配的子商户号，受理模式下必填

子商户号

设备号

device_info

String（32）

否

013467007045764

终端设备号（商户自定义，如门店编号）

随机字符

nonce_str

String（32）

是

5K8264ILTKCH16CQ250

随机字符串，不长于32位。

推荐生

串

2SI8ZNMTM67VS

成算法详见第4.3.2节

签名

sign

String（32）

是

C380BEC2BFD727A4B6845133519F3AD6

签名，详见4.3.1节签名生成算法

商品描述

body

String（127）

是

Q币购买订单支付

商品或支付单描述，展示给用户

商品详情

detail

String（8192）

否

Ipadmini16G白色

传详细的商品列表

附加数据

attach

String（127）

否

自定义数据

商户扩展字段，提交支付后在查询

API和支付通知中原样返回

商户订单

out_trade_n

String（32）

是

121775*********703323

商户系统内部的订单号,32个字符

号

o

3368018

内、可包含字母,其他说明见第4.2

节商户订单号

总金额

total_fee

Int

是

888

订单总金额，单位为分，只能为整数，详见第4.2节支付金额

货币类型

fee_type

String（16）

否

CNY

符合ISO4217标准的三位字母代码，默认人民币：

CNY，其他值列

表详见第4.2节货币类型

终端IP

spbill_create

_ip

String（16）

是

8.8.8.8

调用微信支付API的机器IP

交易起始

time_start

String（14）

否

20091225091010

订单生成时间，格式为

时间

yyyyMMddHHmmss，如2009年

12月25日9点10分10秒表示为

20091225091010。

其他详见第4.2

节时间规则

交易失效

time_expire

String（14）

否

20091227091010

订单失效时间，格式为

时间

yyyyMMddHHmmss，如2009年

12月27日9点10分10秒表示为

20091227091010。

其他详见第4.2

节时间规则

商品标记

goods_tag

String（32）

否

商品标记，代金券或立减优惠功能的参数，说明详见第10节代金券或立减优惠

授权码

auth_code

String（128）

是

12