微信支付API文档120(受理)

发布时间:2015-06-04 11:34:08   来源:文档文库   
字号:

1. 阅读对象

本文阅读对象:商户系统(在线购物平台、人工收银系统、自动化智能收银系统或其他)集成微信支付涉 及的技术架构师,研发工程师,测试工程师,系统运维工程师。

2. 术语

1. 支付模式

1) 被扫支付 “我/维码线

下面对面收银的场景。

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

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

3) 微信内网页支付

微信内网页支付是用户在微信中打开商户的 H5 页面,商户在 H5 页面通过调用微信支付提供的 JSAPI 口调起微信支付模块完成支付。应用场景有:

用户在微信公众账号内进入商家公众号,打开某个主页面,完成支付;

用户的好友在朋友圈、聊天窗口等分享商家页面连接,用户点击链接打开商家页面,完成支付

将商户页面转换成二维码,用户扫描二维码后在微信浏览器中打开页面后完成支付

4) APP 支付

APP APP SDK 模式。

5) 普通浏览器网页支付模式 正在建设中,敬请期待。

2. 名词解释

1) 微信公众平台 微信公众平台是微信公众账号申请入口和管理后台。商户可以在公众平台提交基本资料、业务资料、财务

资料申请开通微信支付功能。



平台入口:http://mp.weixin.qq.com

2) 微信开放平台

微信开放平台是商户 APP 接入微信支付开放接口的申请入口,通过此平台可申请微信 APP 支付。 平台入口:http://open.weixin.qq.com

3) 微信商户平台

微信商户平台是微信支付相关的商户功能集合,包括参数配置、支付数据查询与统计、在线退款、代金券 或立减优惠运营等功能。

平台入口:http://pay.weixin.qq.com

4) 微信支付系统

微信支付系统是指完成微信支付流程中涉及的 API 接口、后台业务处理系统、账务系统、回调通知等系统 的总称。

5) 商户收银系统

商户收银系统即商户的 POS 收银系统,是录入商品信息、生成订单、客户支付、打印小票等功能的系统。 POS POS 收银 软件系统。

6) 商户后台系统 商户后台系统是商户后台处理业务系统的总称,例如:商户网站、收银系统、进销存系统、发货系统、客

服系统等。

7) 扫码设备

一种输入设备,主要用于商户系统快速读取媒介上的图形编码信息。按读取码的类型不同,可分为条码扫 码设备和二维码扫码设备。按读取物理原理可分为红外扫码设备、激光扫码设备。

8) 商户证书

商户证书是微信提供的二进制文件,商户系统发起与微信支付后台服务器通信请求的时候,作为微信支付 后台识别商户真实身份的凭据。

9) 签名 商户后台和微信支付后台根据相同的密钥和算法生成一个结果,用于校验双方身份合法性。签名的算法由

微信支付制定并公开,常用的签名方式有:MD5SHA1SHA256HMAC 等。

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,后续会兼容 SHA1SHA256HMAC 等。

签名要求

请求和接收数据均需要校验签名,签名的详细方法请参考下文 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 举例:

假设传送的参数如下:

第一步:对参数按照 key=value 的格式,并按照参数名称 ASCII 字典序排序如下:

第二步:拼接 API 密钥:



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

微信提供相关接口在线签名验证工具:点击进入

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,为了

出:openssl pkcs12 -clcerts -nokeys

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

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

-in apiclient_cert.p12 -out

被他人复制

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.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 接口地址

https://api.mch.weixin.qq.com/pay/micropay

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)

C380BEC2BFD727A4B68 45133519F3AD6

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

商品描述

body

String(127)

Q 币购买订单支付

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

商品详情

detail

String(8192)

Ipad mini 16G 白色

传详细的商品列表

附加数据

attach

String(127)

自定义数据

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

API 和支付通知中原样返回

商户订单

out_trade_n

String(32)

121775250120140703323

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

o

3368018

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

节商户订单号

总金额

total_fee

Int

888

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

货币类型

fee_type

String(16)

CNY

符合 ISO 4217 标准的三位字母代 码,默认人民币: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)

120061098828009406

扫码支付授权码,设备读取用户微 信中的条码或者二维码信息

举例如下:

wx2421b1c4370ec43b

订单额外描述

120269300684844649

被扫支付测试

1000

注:参数值用 XML 转义即可,CDATA 标签用于说明数据不被 XML 解析器解析。

5 返回结果

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL



此字段是通信标识,非交易标识,交易是否成功 需要查看 result_code 来判断

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败 具体某个参数格式校验错误

return_code SUCCESS 的时候,还会包括以下字段:

字段名

变量名

类型

示例值

描述

公众账号

ID

appid

String(32)

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

返回提交的商户号

子商户公 众账号 ID

sub_appid

String(32)

oUpF8uJY5nl mGIikjDUkck vxtdoo

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

oUpF8uJY5nl mGIikjDUkck vxtdoo

子商户号

设备号

device_info

String(32)

01346700704

5764

返回提交的终端设备号,

随机字符

nonce_str

String(32)

Fsdfds1235df 231asdfg321 45gfdse

微信返回的随机字符串,不长于 32

签名

sign

String(32)

C380BEC2B FD727A4B68 45133519F3 AD6

返回数据的签名,验证签名算法详见第 4.3.1

业务结果 错误代码

错误描述

result_code err_code

err_code_de s

String(16) String(32)

String(128)

SUCCESS

SYSTEMER ROR

系统错误

SUCCESS/FAIL

详细参见 6 节错误列表

结果信息描述

return_code result_code 都为 SUCCESS 的时,还会包括以下字段:

字段名

变量名

类型

示例值

描述



用户标识

openid

String(128)

用户标识

用户子标识

sub_openid

String(128)

用户子标识

是否关注公

is_subscribe

String(1)

Y

用户是否关注公众账号仅在公众账号类型支付

众账号

有效,取值范围:Y N

Y-关注

N-未关注

是否关注子

sub_is_subsc

String(1)

Y

用户是否关注子公众账号仅在公众账号类型支

公众账号

ribe

付有效,取值范围:Y N

Y-关注

N-未关注

交易类型

trade_type

String(16)

MICROPAY

支付类型为 MICROPAY(即扫码支付)

付款银行

bank_type

String(16)

CMC

银行类型,采用字符串类型的银行标识

货币类型

fee_type

String(16)

CNY

符合 ISO 4217 标准的三位字母代码,默认人民 币:CNY,其他值列表详见 4.2 节货币类型

总金额

total_fee

Int

100

订单总金额,说明详见 4.2 节支付金额

现金支付货

cash_fee_typ

String(16)

CNY

符合 ISO 4217 标准的三位字母代码,默认人民

币类型

e

币:CNY,其他值列表详见 4.2 节货币类型

现金支付金

cash_fee

Int

订单现金支付金额说明详见 4.2 节支付金额

代金券或立 减优惠金额

微信支付订

coupon_fee

transaction_i

Int

String(32)

100

12177525012

“代券或减优金额<=订单总金额 单总金额-代金券或立减优惠”金额=现金支 付金额

微信支付订单号

单号

d

01407033233

368018

商户订单号

out_trade_no

String(32)

12177525012

01407033233

368018

商户系统的订单号,与请求一致。

商家数据包

attach

String(128)

123456

商家数据包,原样返回

支付完成时

time_end

String(14)

20141030133

订单生成时间格式为 yyyyMMddHHmmss

525

2009 12 25 9 10 10 秒表示为



20091225091010。其他详见 3.2 节时间规则

举例如下:

1

0

订单额外描述]]>

6 错误码

名称

描述

原因

解决方案

SYSTEMERROR

接口返回错误

系统超时

请立即调用被扫订单结果查询 API查询 当前订单状态并根据订单的状态决定下 一步的操作。

PARAM_ERROR

参数错误

请求参数未按指引

请根据接口返回的详细信息检查您的程

进行填写

.

ORDERPAID

订单已支付

订单号重复

请确认该订单号是否重复支付如果是新 单,请使用新订单号提交

NOAUTH

商户无权限

商户没有开通被扫

请开通商户号权限请联系产品或商务申

支付权限

AUTHCODEEXPIR

二维码已过期请用户在微

用户的条码已经过

请收银员提示用户请用户在微信上刷新

E

信上刷新后再试

条码,然后请收银员重新扫码。

直接将错误展示给收银员

NOTENOUGH

余额不足

用户的零钱余额不

请收银员提示用户更换当前支付的卡

后请收银员重新扫码。

建议:商户系统返回给收银台的提示为



“用户余额不足.提示用户换卡支付”

NOTSUPORTCARD

不支持卡类型

用户使用卡种不支

请用户重新选择卡种

持当前支付形式

建议:商户系统返回给收银台的提示为

“该卡不支持当前支付提示用户换卡支

付或绑新卡支付”

ORDERCLOSED

订单已关闭

该订单已关闭

商户订单号异常,请重新下单支付

BANKERROR

银行系统异常

银行端超时

请立即调用被扫订单结果查询 API查询 当前订单的不同状态,决定下一步的操 作。

USERPAYING

用户支付中需要输入密码

该笔交易因为业务

等待 5 秒,然后调用被扫订单结果查询

规则要求,需要用

API,查询当前订单的不同状态,决定下

户输入支付密码。

一步的操作。

AUTH_CODE_ERR OR

授权码参数错误

请求参数未按指引 进行填写

每个二维码仅限使用一次,请刷新再试

AUTH_CODE_INVA LID

授权码检验错误

收银员扫描的不是 微信支付的条码

请扫描微信支付被扫条码/二维码

XML_FORMAT_ER ROR

XML 格式错误

XML 格式错误

请检查 XML 参数格式是否正确

ORDERREVERSED

订单已撤销

当前订单已经被撤

当前订单状态为“订单已撤销”,请提示

用户重新支付

REQUIRE_POST_ METHOD

请使用 post 方法

未使用 post 传递参

请检查请求参数是否通过 post 方法提交

SIGNERROR

签名错误

参数签名结果不正

请检查签名参数和方法是否都符合签名

算法要求

LACK_PARAMS

缺少参数

缺少必要的请求参

请检查参数是否齐全

NOT_UTF8

编码格式错误

未使用指定编码格

请使用 NOT_UTF8 编码格式

BUYER_MISMATC H

支付帐号错误

暂不支持同一笔订 单更换支付方

请确认支付方是否相同

APPID_NOT_EXIST

APPID 不存在

参数中缺少 APPID

请检查 APPID 是否正确

MCHID_NOT_EXIS T

MCHID 不存在

参数中缺少 MCHID

请检查 MCHID 是否正确



OUT_TRADE_NO_ USED

商户订单号重复

同一笔交易不能多 次提交

请核实商户订单号是否重复提交

APPID_MCHID_NO T_MATCH

appid mch_id 不匹配

appid mch_id 匹配

请确认 appid mch_id 是否匹配

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://api.mch.weixin.qq.com/secapi/pay/reverse

3 是否需要证书

请求需要双向证书。 详见 4.3.3 节使用证书

4 请求参数

字段名

变量名

类型

示例值

描述



公众账号 ID

appid

String(32)

wx88888888 88888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

微信订单号

transaction_id

String(32)

12177525012

01407033233

368018

微信的订单号,优先使用

商户订单号

out_trade_no

String(32)

12177525012

01407033233

368018

商户系统内部的订单号,

transaction_idout_trade_no 二选一,如果同时存在优 先级:transaction_id> out_trade_no

随机字符串

nonce_str

String(32)

5K8264ILTK CH16CQ250 2SI8ZNMTM

67VS

随机字符串,不长于 32 位。推荐生成算法详见第 4.3.2

签名

sign

String(32)

C380BEC2B FD727A4B68 45133519F3 AD6

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

提交参数举例如下:

wx2421b1c4370ec43b

10000100

b7ffb16a7150cf08639db472c5f5bdae

1415717424

ign>9B2EA16C05A5CEF8E53B14D53932D012</sign>

返回结果

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL



返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

必填

类型

示例值

描述

公众账号 ID

appid

String(32)

wx888888 88888888

88

微信分配的公众账号 ID

商户号

mch_id

String(32)

19000001

09

微信支付分配的商户号

子商户公众账 ID

sub_appid

String(32)

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

ID

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

随机字符串

nonce_str

String(32)

5K8264ILT KCH16CQ 2502SI8Z NMTM67V S

微信返回的随机字符串,不长于 32

签名

sign

String(32)

C380BEC 2BFD727A

4B684513

3519F3AD

6

签名,验证签名算法详见第 4.3.1

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

SUCCESS 表示撤销成功此笔订单不能再 发起支付;若已支付完成,则会发起退款;

FAIL 其它表示撤销接口异常,根据 recall

判断是否可再次发起撤销操作;

是否重调

recall

String(1)

Y

是否需要继续调用撤销,Y-需要,N-不需要



错误代码

err_code

String(32)

SYSTEME RROR

详细参见 6 节错误列表

错误描述

err_code_de s

String(128

)

系统错误

结果信息描述

返回参数举例如下

5 错误码 I

名称

描述

原因

解决方案

SYSTEMERROR

接口返回错误

系统超时

请尝试再次调用查询 API

INVALID_TRANSAC TIONID

无效 transaction_id

请求参数未按指引进行填

参数错误,请重新检查

PARAM_ERROR

参数错误

请求参数未按指引进行填

参数错误,请重新检查

REQUIRE_POST_M ETHOD

请使用 post 方法

未使用 post 传递参数

请检查请求参数是否通过 post 方法提交

SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签名算 法要求

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(用户标识)回调商户后台系统,商户后 台系统根据 productid 生成支付交易,最后微信支付系统发起用户支付流程。

模式二:商户后台系统调用微信支付【统一下单 API】生成预付交易,将接口返回的链接生成二维码,用 户扫码后输入密码完成支付交易。注意:该模式的预付单有效期为 2 小时,过期后无法支付。

4. 模式一

模式一开发前,商户必须在公众平台后台设置支付回调 URLURL 实现的功能:接收用户扫码后微信支 付系统回调的 productid openidURL 设置详见本章第 6.3.1



1 业务流程时序图

6.8:原生支付接口模式一时序图 业务流程说明:

1) 商户后台系统根据微信支付规定格式生成二维码(规则见本章第 6.4.2 ),展示给用户扫码。

2) 用户打开微信“扫一扫”扫描二维码,微信客户端将扫码内容发送到微信支付系统。



3) 微信支付系统收到客户端请求,发起对商户后台系统支付回调 URL 的调用。调用请求将带 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 生成二维码所需参数列表

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888888888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

时间戳

time_stamp

String(10)

1414488825

系统当前时间定义规则见 4.2 节时间



随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

随机字符串,不长于 32 位。推荐生成算 法详见第 4.3.2

商品 ID

product_id

String(32)

88888

商户定义的商品 id 或者订单号

签名

sign

String(32)

C380BEC2BFD727A4 B6845133519F3AD6

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

举例:

3 回调商户支付 URL

商户提供的支付回调 URL(设置请见 6.3.1 )需要实现以下功能:接收用户扫码后微信支付系统发送的 数据,根据接收的数据生成支付订单,调用【统一下单 API】提交支付交易。

1. 输入参数

6.2 输入参数说明

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888888888888

微信分配的公众账号 ID

用户标识

openid

String(128)

o8GeHuLAsgefS_80exEr 1cTqekUs

用户在商户 appid 下的唯一标识

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

是否关注公众

is_subscribe

String(1)

Y

用户是否关注公众账号,Y-关注,N-未关

随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ25

02SI8ZNMTM67VS

随机字符串不长于 32 推荐生成算法 详见第 4.3.2

商品 ID

product_id

String(32)

88888

商户定义的商品 id 或订单号

签名

sign

String(32)

C380BEC2BFD727A4B6 845133519F3AD6

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

2. 输出参数

6.3 输出参数说明

字段名

变量名

必填

类型

示例值

说明



返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

公众账号 ID

appid

String(32)

wx8888888888888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

微信返回的随机字符串,不长于 32

预支付 ID

prepay_id

String(64)

wx2014102720093955 22657a690389285100

调用统一下单接口生成的预支付 ID

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

错误描述

err_code_des

String(128)

result_code FAIL 商户展示 给用户的错误提示。

签名

sign

String(32)

签名,验证签名算法详见第 4.3.1

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. 二维码相关知识 二维码背景知识介绍:

http://www.thonky.com/qr-code-tutorial/

http://coolshell.cn/articles/10590.html

7. 微信内网页支付

1. 场景介绍

商户已有 H5 商城网站,用户通过消息或扫描二维码在微信内打开网页时,可以调用微信支付完成下单购 买的流程。



步骤(1):如图 7.1,商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页。 步骤(2):如图 7.2,进入商户网页,用户选择购买,完成选购流程。

7.1 商户自定义消息界面 7.2 商户网页下单 步骤(3):如图 7.3,调起微信支付控件,用户开始输入支付密码。 步骤(4):如图 7.4,密码验证通过,支付成功。商户后台得到支付成功的通知。

7.3 用户确认支付,输入密码 7.4 用户支付成功提示 步骤(5):如图 7.5,返回商户页面,显示购买成功。该页面由商户自定义。 步骤(6):如图 7.6,公众号下发消息,提示发货成功。该步骤可选。



7.5 返回商户页面提示 7.6 用户收到发货微信通知 注意:商户也可以把商品网页的链接生成二维码,用户扫一扫打开后即可完成购买支付。 交互细节:

以下是支付场景的交互细节,请认真阅读,设计商户页面的逻辑:

1 JavaScript getBrandWCPayRequest 发起微信支付请求,用户进入支付流程。

2)用户成功支付点击完成按钮后,商户的前端会收到 JavaScript 的返回值。商户可直接跳转到支付成 功的静态页面进行展示。

3)商户后台收到来自微信开放平台的支付成功回调通知,标志该笔订单支付成功。 注:

2)和(3)的触发不保证遵循严格的时序。JS API 返回值作为触发商户网页跳转的标志,但商户后台应 该只在收到微信后台的支付成功回调通知后,才做真正的支付成功的处理。

2. 案例介绍 目前已上线支付案例,商户可进行实际体验。 线下:新版友宝售卖机等。 线上:京东、易迅公众号内下单支付等



3. 微信内网页支付开发步骤

1 设置测试目录

在微信公众平台设置,栏目见图 7.7。支付测试状态下,设置测试目录,测试人的微信号添加到白名单, 发起支付的页面目录必须与设置的精确匹配。并将支付链接发到对应的公众号会话窗口中才能正常发起支付测 试。注意正式目录一定不能与测试目录设置成一样,否则支付会出错。

7.7 微信内网页支付设置栏目入口

2 设置正式支付目录

JSAPI 是发起支付的页面的精确目录,子目录下无法正常调用支付。具体界面如图 7.8 所示:



7.8 微信网页内支付接口授权目录设置



4. 业务流程时序图

7.9 微信内网页支付时序图 商户系统和微信支付系统主要交互:

1. 商户 server 调用统一下单接口请求订单,api 参见公共 api统一下单 2. 商户 server 接收支付通知,api 参见公共 api通用通知 api

3. 商户 server 查询支付结果,api 参见公共 api查询订单 api



5. 获取微信版本号

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 HTTP 5.0

6. 显示微信安全支付标题 对于商户具有支付权限且需要调用微信支付的页面,为了让用户增加购买信心,确认交易环境安全,微信

强烈建议商户使用“微信安全支付”标题。安全支付标题的如下图。

7.10 微信安全支付标题 显示支付安全标题,需将原始链接添加上"showwxpaytitle=1"的尾串。通过这种方式,商户的页面将出现

微信安全支付的标识。例如,原始 URL 为:http://weixin.qq.com,显示安全支付标题的 URL 为:

http://weixin.qq.com?showwxpaytitle=1

当用户在微信里打开 http://weixin.qq.com 不会直接出现微信安全支付的标题,而打开

http://weixin.qq.com?showwxpaytitle=1 后将出现微信安全支付标题。

7. H5 网页端调起支付 API

在微信浏览器里面打开 H5 网页中执行 JS 调起支付。接口输入输出数据格式为 JSON 注意:WeixinJSBridge 内置对象在其他浏览器中无效;列表中参数名称区分大小。 getBrandWCPayRequest 参数以及返回值定义见图 7.1,返回列表值说明见图 7.2

7.1 网页端接口参数列表

字段名

变量名

类型

示例值

描述

公众号 id

appId

String(16)

wx88888888888 88888

商户注册具有支付权限的公众号成功后即 可获得

时间戳

timeStamp

String(32)

1414561699

当前的时间规则详见其他详见 4.2 节时



间戳规则

随机字符串

nonceStr

String(32)

5K8264ILTKCH

16CQ2502SI8Z NMTM67VS

随机字符串,不长于 32 位。推荐生成算法 详见第 4.3.2

订单详情扩展字 符串

package

String(128)

prepay_id=1234 56789

统一下单接口返回的 prepay_id 参数值 交格式如:prepay_id=***

签名方式

signType

String(32)

MD5

签名算法,暂支持 MD5

签名

paySign

String(64)

C380BEC2BFD 727A4B6845133

519F3AD6

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

7.2 网页内支付接口返回结果值说明

字段名

返回值

描述

err_msg

get_brand_wcpay_request:ok

支付成功

get_brand_wcpay_request:cancel

支付过程中用户取消

get_brand_wcpay_request:fail

支付失败

JS API get_brand_wcpay_request:ok

get_brand_wcpay_request:cancel 或者 get_brand_wcpay_request:fail 可以统一处理为用户遇到错误或者主动 放弃,不必细化区分。

示例代码如下:

document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);

}else if (document.attachEvent){

document.attachEvent('WeixinJSBridgeReady', onBridgeReady); document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);

}



8. 统一下单 API 注意交易类型(trade_type)填写:JSAPI 详见【公共 API 9.1 节统一下单

9. 查询订单 API

详见【公共 API 9.2 查询订单

10. 关闭订单 API

详见【公共 API 9.3 节关闭订单

11. 申请退款 API

详见【公共 API 9.4 申请退款

12. 查询退款 API

详见【公共 API 9.5 节查询退款

13. 下载对账单 API

详见【公共 API 9.6 节下载对账单

8. APP 支付模式

1. 场景介绍

适用于商户在移动端 APP 中集成微信支付功能。

商户 APP 调用微信提供的 SDK 调用微信支付模块,商户 APP 会跳转到微信中完成支付,支付完后跳回 到商户 APP 内,最后展示支付结果。

目前微信支付支持手机系统有:IOS(苹果)、Android(安卓)和 WPWindows Phone)。 交互细节如下:



1 APP 名后将数据传输到 APP 端。以微信提供的 DEMO 为例,见图 8.1

步骤 2:用户点击后发起支付操作,进入到微信界面,调起微信支付,出现确认支付界面,见图 8.2

步骤 3:用户确认收款方和金额,点击立即支付后出现输入密码界面,可选择零钱或银行卡支付见图 8.3

8.1 商户 APP 界面实例 8.2 跳转到微信支付 8.3 用户确认支付 第四步:输入正确密码后,支付完成,用户端微信出现支付详情页面。见图 8.4 第五步:回跳到商户 APP 中,商户 APP 根据支付结果个性化展示订单处理结果。见图 8.5

8.4 支付成功提示页面 8.5 返回到商户 APP 提示

2. 案例介绍 目前已上线支付案例,如京东、易迅手机 APP 等。



3. 业务流程

以下是交互时序图,统一下单 API、接受支付通知和查询 API 等都涉及签名过程,调用都必须在商户服务 器端完成。如图 8.6 所示。

8.6 APP 支付时序图

商户系统和微信支付系统主要交互说明:



步骤 1:用户在商户 APP 中选择商品,提交订单,选择微信支付。

步骤 2:商户后台系统收到用户支付单,调用微信支付统一下单接口。参见公共 api统一下单 API】。 步骤 3:统一下单接口返回正常的 prepay_id,再按签名规范重新生成签名后,将数据传输给 APP。参与

签名的字段名为 appIdpartnerIdprepayIdnonceStrtimeStamppackage。注意:package 的值格式为 prepay_id=wx20141009175351724b348a500087751557

步骤 4:商户 APP 调起微信支付。api 参见本章节【app 端开发说明

步骤 5:商户 server 接收支付通知。api 参见公共 api通用通知 api 步骤 6:商户 server 查询支付结果。,api 参见公共 api查询订单 api

4. API 详细说明

1.请详细参考开放平台 API 手册:

IOS:

https://open.weixin.qq.com/zh_CN/htmledition/res/dev/document/sdk/ios/index.html

安卓:

https://open.weixin.qq.com/zh_CN/htmledition/res/dev/document/sdk/android/index.html

WP:

待提供

2.APP 端调起支付接口

APP 端调起支付参数列表字段,具体调用根据提供的 SDK 说明。

字段名

变量名

必填

类型

示例值

描述

公众账号 ID

appId

String(32)

wx8888888888888888

微信分配的公众账号 ID

商户号

partnerId

String(32)

1900000109

微信支付分配的商户号

交易会话标

prepayId

String(64)

wx2014100917535172

调用微信支付统一下单会返回的交易会话

4b348a500087751557

标识

随机字符串

nonceStr

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

随机字符串,不长于 32 位。推荐生成算法 详见第 4.3.2

订单扩展字

package

String(256)

prepay_id=wx2014100

填写订单详情字段

9175351724b348a5000

87751557

商品描述

timeStam p

String(12)

1419908648

时间戳



5. APP 端开发步骤说明

1 IOS 开发要点说明

以下项目开发环境以 Xcode10.0,运行环境为 IOS7.0 为例,说明其开发中需要的操作。

1) 项目设置 APPID

商户在微信开放平台申请开发 APP 应用后,微信开放平台会生成 APP 的唯一标识 APPID。在 Xcode 打开项目,设置项目属性中的 URL Schemes 为您的 APPID。如图 8.7 标红位置所示。

8.7

2) 注册 APPID

商户 APP 工程中引入微信 lib 库和头文件,调用 API 前,需要先向微信注册您的 APPID,代码如下:

3) 调起支付

API( 9.1 )付单 prepay_id 次签名传输给 APP 发起支付。以下是调起微信支付的关键代码:



4) 支付结果回调

照微信 SDK Samplenet.sourceforge.simcpux.wxapi 包路径中实现 WXPayEntryActivity (包名或类名 不一致会造成无法回调),类中实现 onResp 函数,支付完成后,微信 APP 会返回到商户 APP 并回调 onResp 函数,开发者需要在该函数中接收通知,判断返回错误码,如果支付成功则去后台查询支付结果再展示用户实 际支付结果。注意一定不能以客户端返回作为用户支付的结果,应以服务器端的接收的支付通知或查询 API 回的结果为准。代码示例如下:

回调中 errCode 值列表:

名称

描述

解决方案

0

成功

展示成功页面

-1

错误

可能的原因:签名错误、未注册 APPID、项目设置 APPID 不正确、注册的 APPID 与设置 的不匹配、其他异常等。

-2

用户取消

无需处理。发生场景:用户不支付了,点击取消,返回 APP

2 Android 开发要点说明

1) 后台设置

商户在微信开放平台申请开发应用后,微信开放平台会生成 APP 的唯一标识 APPID。由于需要保证支付 安全,需要在开放平台绑定商户应用包名和应用签名,设置好后才能正常发起支付。设置界面在【开放平台】 中的栏目【管理中心 / 修改应用 / 修改开发信息】里面,如图 8.8 红框内所示。



8.8

应用包名:是在 APP 项目配置文件 AndroidManifest.xml 中声明的 package 值,例如 DEMO 中的

package="net.sourceforge.simcpux"

应用签名:根据项目的应用包名和编译使用的 keystore,可由签名工具生成一个 32 位的 md5 串,在调试 的手机上安装签名工具后,运行可生成应用签名串,如图 8.9 所示,绿色串即应用签名。签名工具下载地址: https://open.weixin.qq.com/zh_CN/htmledition/res/dev/download/sdk/Gen_Signature_Android.apk



8.9

2) 注册 APPID

商户 APP 工程中引入微信 JAR 包,调用 API 前,需要先向微信注册您的 APPID,代码如下: API 调用前,需要先向微信注册您的 APP,代码如下:

// 将该 app 注册到微信

3) 调起支付

商户服务器生成支付订单,先调用统一下单 API(详见第 7 )生成预付单,获取到 prepay_id 后将参数再 次签名传输给 APP 发起支付。以下是调起微信支付的关键代码:

IWXAPI api;

PayReq request = new PayReq();

request. appId = "wxd930ea5d5a258f4f";

request. partnerId = "1900000109";

request.prepayId= "1101000000140415649af9fc314aa427",;

request. packageValue = "Sign=WXPay";

request.nonceStr= "1101000000140429eb40476f8896f4c9";

request.timeStamp= "1398746574";

request.sign= "7ffecb600d7157c5aa49810d2d8f28bc2811827b";

api.sendReq(req);

4) 支付结果回调

参照微信 SDK Sample,在 WXPayEntryActivity 类中实现 onResp 函数,支付完成后,微信 APP 会返回 到商户 APP 并回调 onResp 函数,开发者需要在该函数中接收通知,判断返回错误码,如果支付成功则去后 台查询支付结果再展示用户实际支付结果。注意一定不能以客户端返回作为用户支付的结果,应以服务器端的 接收的支付通知或查询 API 返回的结果为准。代码示例如下:



回调中 errCode 值列表:

名称

描述

解决方案

0

成功

展示成功页面

-1

错误

可能的原因:签名错误、未注册 APPID、项目设置 APPID 不正确、注册的

APPID 与设置的不匹配、其他异常等。

-2

用户取消

无需处理。发生场景:用户不支付了,点击取消,返回 APP

6. 统一下单 API

注意交易类型(trade_type)填写:APP 详见【公共 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 节下载对账单

9. 公共 API

公共 API 主要包括统一下单、通用通知、查询订单、关闭订单、退款申请、退款查询、对账单对账、短链 接转换。以下对接口使用进行详细说明。

1. 统一下单

1 应用场景 除被扫支付场景以外,商户系统先调用该接口在微信支付服务后台生成预支付交易单,返回正确的预支付

交易回话标识后再按扫码、JSAPIAPP 等不同场景生成交易串调起支付。

2 接口链接

URL 地址:https://api.mch.weixin.qq.com/pay/unifiedorder

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)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

随机字符串,不长于 32 位。推荐生成算法 详见第 4.3.2

签名

sign

String(32)

C380BEC2BFD727A4B

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



6845133519F3AD6

商品描述

body

String(32)

Ipad mini 16G 白色

商品或支付单简要描述

商品详情

detail

String(8192)

Ipad mini 16G 白色

商品名称明细列表

附加数据

attach

String(127)

说明

附加数据,在查询 API 和支付通知中原样 返回,该字段主要用于商户携带订单的自 定义数据

商户订单号

out_trade_n

String(32)

1217752501201407033

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

o

233368018

含字母, 其他说明见 4.2 节商户订单号

货币类型

fee_type

String(16)

CNY

符合 ISO 4217 标准的三位字母代码默认 人民币:CNY,其他值列表详见 4.2 货币类型

总金额

total_fee

Int

888

订单总金额,只能为整数,详见 4.2 支付金额

终端 IP

spbill_create

_ip

String(16)

8.8.8.8

APP 和网页支付提交用户端 ipNative 付填调用微信支付 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)

WXG

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

通知地址

notify_url

String(256)

http://www.baidu.com/

接收微信支付异步通知回调地址

交易类型

trade_type

String(16)

JSAPI

取值如下:JSAPINATIVEAPP,详细 说明见 4.2 节参数规定

商品 ID

product_id

String(32)

1223541321407035645

8058

trade_type=NATIVE,此参数必传。此 id

为二维码中包含的商品 ID商户自行定义。

用户标

openid

String(1

28)

oUpF8uMuAJO_M 2pxb1Q9zNjWeS6o

trade_type=JSAPI,此参数必传,用 户在商户 appid 下的唯一标识下单前需要 调用【网页授权获取用户信息】接口获取



到用户的 Openid

用户子标识

sub_openid

String(128)

oUpF8uMuAJO_M2pxb 1Q9zNjWeS6o

trade_type =JSAPI 时,此参数必 传,用户在商户 sub_appid 下的唯一标识。 下单前需要调用【网页授权获取用户信息 接口获取到用户的 Openid

举例如下:

wx2421b1c4370ec43b

支付测试

JSAPI 支付测试

10000100

注:参数值用 XML 转义即可,CDATA 标签用于说明数据不被 XML 解析器解析。

5 返回结果

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识,非交易标识,交易是否成 功需要查看 result_code 来判断

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888888 888888

调用接口提交的公众账号 ID



商户号

mch_id

String(32)

1900000109

调用接口提交的商户号

子商户公众账号

ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

设备号

device_info

String(32)

013467007045

764

调用接口提交的终端设备号,

随机字符串

nonce_str

String(32)

5K8264ILTKC H16CQ2502SI 8ZNMTM67VS

微信返回的随机字符串

签名

sign

String(32)

C380BEC2BF D727A4B6845 133519F3AD6

微信返回的签名,验证签名算法详见第 4.3.1

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

错误代码

err_code

String(32)

SYSTEMERR OR

详细参见 6 节错误列表

错误代码描述

err_code_de s

String(128)

系统错误

错误返回的信息描述

以下字段在 return_code result_code 都为 SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述

交易类型

trade_type

String(16)

JSAPI

调用接口提交的交易类型取值如下JSAPI NATIVEAPP,详细说明见 4.2 节参数规

预支付交易会话 标识

prepay_id

String(64)

wx2014102720 09395522657a

690389285100

微信生成的预支付回话标识用于后续接口调 用中使用,该值有效期为 2 小时

二维码链接

code_url

String(64)

URl

weixin://wxpay/ s/An4baqw

trade_type NATIVE 是有返回可将该参数 值生成二维码展示出来进行扫码支付

举例如下:



6 错误码

名称

描述

原因

解决方案

NOAUTH

商户无此接口权限

商户未开通此接口权限

请商户前往申请此接口权限

NOTENOUGH

余额不足

用户帐号余额不足

用户帐号余额不足,请用户充值或更换支付 卡后再支付

ORDERPAID

商户订单已支付

商户订单已支付,无需重复 操作

商户订单已支付,无需更多操作

ORDERCLOSED

订单已关闭

当前订单已关闭,无法支付

当前订单已关闭,请重新下单

SYSTEMERROR

系统错误

系统超时

系统异常,请用相同参数重新调用

APPID_NOT_EXI ST

APPID 不存在

参数中缺少 APPID

请检查 APPID 是否正确

MCHID_NOT_EX IST

MCHID 不存在

参数中缺少 MCHID

请检查 MCHID 是否正确

APPID_MCHID_ NOT_MATCH

appid mch_id 匹配

appid mch_id 不匹配

请确认 appid mch_id 是否匹配

LACK_PARAMS

缺少参数

缺少必要的请求参数

请检查参数是否齐全

OUT_TRADE_N O_USED

商户订单号重复

同一笔交易不能多次提交

请核实商户订单号是否重复提交

SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签名算法 要求

XML_FORMAT_E RROR

XML 格式错误

XML 格式错误

请检查 XML 参数格式是否正确

REQUIRE_POST

_METHOD

请使用 post 方法

未使用 post 传递参数

请检查请求参数是否通过 post 方法提交



POST_DATA_EM PTY

post 数据为空

post 数据不能为空

请检查 post 数据是否为空

NOT_UTF8

编码格式错误

未使用指定编码格式

请使用 NOT_UTF8 编码格式

7 API 工具

2. 查询订单

1 应用场景 该接口提供所有微信支付订单的查询,商户可以通过该接口主动查询订单状态,完成下一步的业务逻辑。 需要调用查询接口的情况:

1. 当商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知;

2. 调用支付接口后,返回系统错误或未知交易状态情况;

3. 调用被扫支付 API,返回 USERPAYING 的状态;

4. 调用关单或撤销接口 API 之前,需确认支付状态;

2 接口链接

https://api.mch.weixin.qq.com/pay/orderquery

3 是否需要证书

不需要

4 请求参数

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx88888888 88888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众账 ID

sub_appid

String(32)

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

子商户公众账号 ID



子商户号

sub_mch_id

String(32)

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

子商户号

微信订单号

transaction_i d

String(32)

01346700704

5764

微信的订单号,优先使用

商户订单号

out_trade_no

String(32)

12177525012

01407033233

368018

商户系统内部的订单号,当没提供 transaction_id 需要传这个。

随机字符串

nonce_str

String(32)

C380BEC2B FD727A4B68 45133519F3 AD6

随机字符串,不长于 32 位。推荐生成算法详见第 4.3.2

签名

sign

String(32)

5K8264ILTK CH16CQ250 2SI8ZNMTM

67VS

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

举例如下:

wx2421b1c4370ec43b

10000100

ec2316275641faa3aacf3cc599e8730f

1008450740201411110005820873

FDD167FAA73459FD921B144BAF4F4CA2

5 返回结果

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识,非交易标识,交易是否成功需要 查看 trade_state 来判断

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述



公众账号 ID

appid

String(32)

wx88888888 88888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众账 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

随机字符串

nonce_str

String(32)

5K8264ILTK CH16CQ250 2SI8ZNMTM

67VS

随机字符串,不长于 32

签名

sign

String(32)

C380BEC2B FD727A4B68 45133519F3 AD6

签名,验证签名算法详见第 4.3.1

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

错误代码

err_code

String(32)

SYSTEMER ROR

详细参见 6 节错误列表

错误代码描述

err_code_de s

String(128)

系统错误

结果信息描述

以下字段在 return_code result_code 都为 SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述

设备号

device_info

String(32)

01346700704

5764

微信支付分配的终端设备号,

用户标识

openid

String(128)

oUpF8uJY5nlm GIikjDUkckvx tdoo

用户标识

用户子标识

sub_openid

String(128)

oUpF8uJY5nl mGIikjDUkckv xtdoo

用户子标识



是否关注公 众账号

is_subscribe

String(1)

Y

用户是否关注公众账号,仅在公众账号类型支付有 效,取值范围:Y N

Y-关注

N-未关注

是否关注子

sub_is_subscri

String(1)

Y

用户是否关注子公众账号,仅在公众账号类型支付

公众账号

be

有效,取值范围:Y N

Y-关注

N-未关注

交易类型

trade_type

String(16)

JSAPI

调用接口提交的交易类型,取值如下:JSAPI NATIVEAPPMICROPAY,详细说明见 4.2 节参数规定

交易状态

trade_state

String(32)

SUCCESS

SUCCESS—支付成功 REFUND—转入退款 NOTPAY—未支付 CLOSED—已关闭 REVOKED—已撤销 USERPAYING--用户支付中

NOPAY--未支付(输入密码或确认支付超时) PAYERROR--支付失败(其他原因,如银行返回失败)

付款银行

bank_type

String(16)

CMC

银行类型,采用字符串类型的银行标识

总金额

total_fee

Int

100

订单总金额,单位为分

货币种类

fee_type

String(8)

CNY

货币类型,符合 ISO 4217 标准的三位字母代码, 默认人民币:CNY,其他值列表详见 4.2 节货币 类型

现金支付金

cash_fee

Int

100

现金支付金额订单现金支付金额,详见 4.2 节支

付金额

现金支付货

cash_fee_type

String(16)

CNY

货币类型,符合 ISO 4217 标准的三位字母代码,

币类型

默认人民币:CNY,其他值列表详见 4.2 节货币

类型

代金券或

coupon_fee

Int

代金券或立减优惠”金额<=订单总金额,订单

立减优惠

总金额-代金券或立减优惠”金额=现金支付金

金额

额,详见 4.2 节支付金额



代金券或 立减优惠 使用数量

coupon_count

Int

1

代金券或立减优惠使用数量

代金券或

coupon_batch_i

String(20)

100

代金券或立减优惠批次 ID ,$n 为下标,从 1 开始

立减优惠

d_$n

编号

批次 ID

代金券或 立减优惠

ID

coupon_id_$n

String(20)

10000

代金券或立减优惠 ID, $n 为下标,从 1 开始编号

单个代金

coupon_fee_$n

Int

100

单个券或减优惠支付金额, $n 为下标 1

券或立减

开始编号

优惠支付

金额

微信支付订

transaction_id

String(32)

12177525012

微信支付订单号

单号

01407033233

368018

商户订单号

out_trade_no

String(32)

12177525012

01407033233

368018

商户系统的订单号,与请求一致。

商家数据包

attach

String(128)

123456

商家数据包,原样返回

支付完成时

time_end

String(14)

20141030133

订单支付时间,格式为 yyyyMMddHHmmss,如

525

2009 12 25 9 10 10 秒表示为

20091225091010。其他详见 4.2 节时间规则

举例如下:

订单额外描述]]>



6 错误码

名称

描述

原因

解决方案

ORDERNOTEXIST

此交易订单号 不存在

查询系统中不存在此交易订 单号

API 只能查提交支付交易返回成功 的订单请商户检查需要查询的订单号 是否正确

SYSTEMERROR

系统错误

后台系统返回错误

系统异常,请再调用发起查询

3. 关闭订单

1 应用场景 以下情况需要调用关单接口:商户订单支付失败需要生成新单号重新发起支付,要对原订单号调用关单,

避免重复支付;系统下单后,用户支付超时,系统退出不再受理,避免用户继续,请调用关单接口。

2 接口链接

https://api.mch.weixin.qq.com/pay/closeorder

3 是否需要证书 不需要。

4 请求参数

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888 888888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

190000010

9

微信支付分配的商户号

子商户公众账号

ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

微信支付分 配的子商户 受理模式

子商户号



下必填

商户订单号

out_trade_n o

String(32)

121775250

120140703

323336801

8

商户系统内部的订单号

随机字符串

nonce_str

String(32)

5K8264ILT KCH16CQ2 502SI8ZNM TM67VS

商户系统内部的订单号,32 个字符内、可包含 字母, 其他说明见 4.2 节商户订单号

签名

sign

String(32)

C380BEC2 BFD727A4 B68451335 19F3AD6

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

示例代码:

wx2421b1c4370ec43b

10000100

4ca93f17ddf3443ceabf72f26d64fe0e

1415983244

ign>59FF1DF214B2D279A0EA7077C54DD95D</sign>

5 返回结果

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888 888888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

190000010

微信支付分配的商户号



9

子商户公众账号

ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_i d

String(32)

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

子商户号

随机字符串

nonce_str

String(32)

5K8264ILT KCH16CQ2 502SI8ZNM TM67VS

随机字符串,不长于 32

签名

sign

String(32)

C380BEC2 BFD727A4 B68451335 19F3AD6

签名,验证签名算法详见第 4.3.1

错误代码

err_code

String(32)

SYSTEME RROR

详细参见第 6 节错误列表

错误代码描述

err_code_d es

String(128)

系统错误

结果信息描述

示例代码

6 错误码

名称

描述

原因

解决方案

ORDERPAID

订单已支付

订单已支付,不能发起关单

订单已支付不能发起关单请当作已 支付的正常交易

SYSTEMERROR

系统错误

系统错误

系统异常,请重新调用该 API

ORDERNOTEXIST

订单不存在

订单系统不存在此订单

不需要关单当作未提交的支付的订单

ORDERCLOSED

订单已关闭

订单已关闭,无法重复关闭

订单已关闭,无需继续调用



SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签 名算法要求

REQUIRE_POST_MET HOD

请使用 post

未使用 post 传递参数

请检查请求参数是否通过 post 方法提

XML_FORMAT_ERROR

XML 格式错误

XML 格式错误

请检查 XML 参数格式是否正确

4. 申请退款

1 应用场景 当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还

给买家,微信支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。 注意:

1.交易时间超过半年的订单无法提交退款;

2.微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款 单号。一笔退款失败后重新提交,要采用原来的退款单号。总退款金额不能超过用户实际支付金额。

接口提交成功后,还需要在微信商户后台由商户管理员审核退款,如下图所示栏目:

2 接口地址 接口链接:https://api.mch.weixin.qq.com/secapi/pay/refund



3 是否需要证书 请求需要双向证书。

4 请求参数

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx888888888 8888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_i d

String(32)

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

子商户号

设备号

device_info

String(32)

01346700704

5764

微信支付分配的终端设备号,与下单一致

随机字符串

nonce_str

String(32)

5K8264ILTKC H16CQ2502S I8ZNMTM67V S

随机字符串,不长于 32 位。推荐生成算法详见第 4.3.2

签名

sign

String(32)

C380BEC2BF D727A4B684 5133519F3AD

6

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

微信订单号

transaction

_id

String(28)

12177525012

01407033233

368018

微信订单号

商户订单号

out_trade_ no

String(32)

12177525012

01407033233

368018

商户系统内部的订单号,

transaction_idout_trade_no 二选一,如果同时存在优 先级:transaction_id> out_trade_no

商户退款单

out_refund

_no

String(32)

12177525012

01407033233

368018

商户系统内部的退款单号,商户系统内部唯一,同一退 款单号多次请求只退一笔



总金额

total_fee

Int

100

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

退款金额

refund_fee

Int

100

退款总金额,订单总金额,单位为分,只能为整数,详 4.2 节支付金额

货币种类

fee_type

String(8)

CNY

货币类型,须与支付货币类型一致。符合 ISO 4217 标准 的三位字母代码,默认人民币:CNY,其他值列表详见 4.2 节货币类型

操作员

op_user_id

String(32)

1900000109

操作员帐号, 默认为商户号

举例如下:

5 返回结果

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述

业务结果

result_cod e

String(16)

SUCCESS

SUCCESS/FAIL

SUCCESS 退款申请接收成功,结果通过退款 查询接口查询

FAIL 提交业务失败

错误代码

err_code

String(32)

SYSTEMERROR

列表详见第 6



错误代码描

err_code_d es

String(128)

系统超时

结果信息描述

公众账号 ID

appid

String(32)

wx8888888888888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_i d

String(32)

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

子商户号

设备号

device_info

String(32)

013467007045764

微信支付分配的终端设备号,与下单一致

随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ25

02SI8ZNMTM67VS

随机字符串,不长于 32

签名

sign

String(32)

5K8264ILTKCH16CQ25

02SI8ZNMTM67VS

签名,验证签名算法详见第 4.3.1

微信订单号

transaction

_id

String(28)

12177525012014070332

33368018

微信订单号

商户订单号

out_trade_ no

String(32)

12177525012014070332

33368018

商户系统内部的订单号

商户退款单

out_refund

_no

String(32)

12177525012014070332

33368018

商户退款单号

微信退款单

refund_id

String(28)

12177525012014070332

33368018

微信退款单号

退款金额

refund_fee

Int

100

退款总金额,单位为分,可以做部分退款

订单总金额

total_fee

Int

100

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

订单金额货 币种类

fee_type

String(8)

CNY

订单金额货币类型,符合 ISO 4217 标准的三 位字母代码,默认人民币:CNY,其他值列表 详见 4.2 节货币类型

现金支付金

cash_fee

Int

100

现金支付金额,单位为分,只能为整数,详见 4.2 节支付金额

货币种类

cash_fee_t ype

String(8)

CNY

货币类型,符合 ISO 4217 标准的三位字母代 默认人民币CNY其他值列表详见 4.2 节货币类型

现金退款金

cash_refun

Int

100

现金退款金额,单位为分,只能为整数,详见



d_fee

4.2 节支付金额

代金券或立 减优惠退款 金额

coupon_ref und_fee

Int

100

代金券或立减优惠”退款金额=订单金额- 现金退款金额注意优惠金额不会退回

代金券或立 减优惠使用 数量

coupon_co unt

Int

1

代金券或立减优惠使用数量

代金券或立 减优惠批次

ID

coupon_ba tch_id_$n

String(20)

100

批次 ID ,$n 为下标,从 1 开始编号

代金券或立 减优惠 ID

coupon_id

_$n

String(20)

10000

代金券或立减优惠 ID, $n 为下标,从 1 开始 编号

单个代金券 或立减优惠 支付金额

coupon_fe e_$n

Int

100

单个代金券或立减优惠支付金额, $n 为下 标,从 1 开始编号

举例如下:

6 错误码

名称

描述

原因

解决方案

SYSTEMERROR

接口返回错误

系统超时

请用相同参数再次调用 API

INVALID_TRANSAC TIONID

无效 transaction_id

请求参数未按指引进行填

请求参数错误检查原交易号是否存在或 发起支付交易接口返回失败

PARAM_ERROR

参数错误

请求参数未按指引进行填

请求参数错误请重新检查再调用退款申



APPID_NOT_EXIST

APPID 不存在

参数中缺少 APPID

请检查 APPID 是否正确

MCHID_NOT_EXIST

MCHID 不存在

参数中缺少 MCHID

请检查 MCHID 是否正确

APPID_MCHID_NO T_MATCH

appid mch_id 匹配

appid mch_id 不匹配

请确认 appid mch_id 是否匹配

REQUIRE_POST_M ETHOD

请使用 post 方法

未使用 post 传递参数

请检查请求参数是否通过 post 方法提交

SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签名 算法要求

XML_FORMAT_ER ROR

XML 格式错误

XML 格式错误

请检查 XML 参数格式是否正确

5. 查询退款

1 应用场景

提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,用零钱支付的退款 20 分钟内到账, 银行卡支付的退款 3 个工作日后重新查询退款状态。

2 接口地址 接口链接:https://api.mch.weixin.qq.com/pay/refundquery

3 是否需要证书 不需要。

4 请求参数

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx88888888 88888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众账 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

微信支付分配

子商户号



的子商户号,

受理模式下必

设备号

device_info

String(32)

01346700704

5764

微信支付分配的终端设备号

随机字符串

nonce_str

String(32)

5K8264ILTK CH16CQ250 2SI8ZNMTM

67VS

随机字符串,不长于 32 位。推荐生成算法详见 4.3.2

签名

sign

String(32)

C380BEC2B FD727A4B68 45133519F3 AD6

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

微信订单号

transaction_id

String(28)

12177525012

01407033233

368018

微信订单号

商户订单号

out_trade_no

String(32)

12177525012

01407033233

368018

商户系统内部的订单号

商户退款单号

out_refund_no

String(32)

12177525012

01407033233

368018

商户退款单号

微信退款单号

refund_id

String(28)

12177525012

微信退款单号

01407033233

368018

refund_idout_refund_noout_trade_no

transaction_id 四个参数必填一个,如果同事存

在优先级为:

refund_id>out_refund_no>transaction_id>out_t

rade_no

举例如下:



5 返回数据

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

SUCCESS 退款申请接收成功结果通过退款查询接 口查询

FAIL

错误码

err_code

String(32)

SYSTEMER ROR

错误码详见 9.6

错误描述

err_code_des

String(32)

系统错误

结果信息描述

公众账号 ID

appid

String(32)

wx88888888 88888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众账 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

设备号

device_info

String(32)

01346700704

5764

微信支付分配的终端设备号,与下单一致

随机字符串

nonce_str

String(28)

5K8264ILTK CH16CQ250

2SI8ZNMTM

随机字符串,不长于 32



67VS

签名

sign

String(32)

C380BEC2B FD727A4B68 45133519F3 AD6

签名,验证签名算法详见第 4.3.1

微信订单号

transaction_id

String(32)

12177525012

01407033233

368018

微信订单号

商户订单号

out_trade_no

String(32)

12177525012

01407033233

368018

商户系统内部的订单号

订单总金额

total_fee

Int

100

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

订单金额货币 种类

fee_type

String(8)

CNY

订单金额货币类型,符合 ISO 4217 标准的三位字母 代码,默认人民币:CNY,其他值列表详见 4.2 货币类型

现金支付金额

cash_fee

Int

100

现金支付金额,单位为分,只能为整数,详见 4.2 节支付金额

货币种类

cash_fee_typ e

String(8)

CNY

货币类型,符合 ISO 4217 标准的三位字母代码,默 认人民币CNY其他值列表详见 4.2 节货币类型

退款金额

refund_fee

Int

100

退款总金额,单位为分,可以做部分退款,货币类型跟 订单总金额保持一致

代金券或立 减优惠退款金

coupon_refun d_fee

Int

100

代金券或立减优惠退款金额=订单金额-现金退款 金额,注意:满立减金额不会退回

退款笔数

refund_count

Int

1

退款记录数

商户退款单号

out_refund_n o_$n

String(32)

12177525012

01407033233

368018

商户退款单号

微信退款单号

refund_id_$n

String(28)

12177525012

01407033233

368018

微信退款单号

退款渠道

refund_chann el_$n

String(16)

ORIGINAL

ORIGINAL—原路退款 BALANCE—退回到余额



退款金额

refund_fee_$ n

Int

100

退款总金额,单位为分,可以做部分退款

代金券或立 减优惠退款金

coupon_refun d_fee_$n

Int

100

券或减优惠退款金额<=退款金额退款金额

-代金券或立减优惠退款金额为现金,说明详见 10

节代金券或立减优惠

代金券或立

coupon_refun

Int

1

代金券或立减优惠使用数量 ,$n 为下标, 1 开始

减优惠使用数

d_count_$n

编号

代金券或立 减优惠批次

ID

coupon_refun d_batch_id_$ n_$m

String(20)

100

批次 ID ,$n 为下标,$m 为下标,从 1 开始编号

代金券或立 减优惠 ID

coupon_refun d_id_$n_$m

String(20)

10000

代金券或立减优惠 ID, $n 为下标,$m 为下标,从

1 开始编号

单个代金券

coupon_refun

Int

100

单个代金券或立减优惠支付金额, $n 为下标,$m

或立减优惠

d_fee_$n_$m

为下标,从 1 开始编号

支付金额

退款状态

refund_status

_$n

String(16)

SUCCES

退款状态: SUCCES—退款成功 FAIL—退款失败 PROCESSING—退款处理中

NOTSURE—未确定需要商户原退款单号重新发起

CHANGE—转入代发,退款到银行发现用户的卡作 废或者冻结了导致原路退款银行卡失败资金回流 到商户的现金帐号需要商户人工干预通过线下或 者财付通转账的方式进行退款。

举例如下:



6 错误码

名称

描述

原因

解决方案

SYSTEMERROR

接口返回错误

系统超时

请尝试再次掉调用 API

INVALID_TRANSAC TIONID

无效 transaction_id

请求参数未按指引进行填

请求参数错误,检查原交易号是否存在或 发起支付交易接口返回失败

PARAM_ERROR

参数错误

请求参数未按指引进行填

请求参数错误,请检查参数再调用退款申

APPID_NOT_EXIST

APPID 不存在

参数中缺少 APPID

请检查 APPID 是否正确

MCHID_NOT_EXIST

MCHID 不存在

参数中缺少 MCHID

请检查 MCHID 是否正确

APPID_MCHID_NOT

_MATCH

appid mch_id 匹配

appid mch_id 不匹配

请确认 appid mch_id 是否匹配

REQUIRE_POST_M ETHOD

请使用 post 方法

未使用 post 传递参数

请检查请求参数是否通过 post 方法提交

SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签名算 法要求

XML_FORMAT_ERR OR

XML 格式错误

XML 格式错误

请检查 XML 参数格式是否正确

6. 下载对账单

1 应用场景 商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致,通过对

账单核对后可校正支付状态。 注意:

1.微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中,跟原支付单 订单号一致,bill_type REVOKED

2.微信在次日 9 点启动生成前一天的对账单,建议商户 10 点后再获取;

3.对账单中涉及金额的字段单位为“元”。



2 接口链接 https://api.mch.weixin.qq.com/pay/downloadbill

3 是否需要证书 不需要。

4 请求参数

字段名

变量名

类型

示例值

描述

公众账号 ID

appid

String(32)

wx88888888 88888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_i d

String(32)

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

子商户号

设备号

device_inf o

String(32)

0134670070

45764

微信支付分配的终端设备号,填写此字段,只下载该设备号 的对账单

随机字符串

nonce_str

String(32)

5K8264ILTK CH16CQ250 2SI8ZNMTM

67VS

随机字符串,不长于 32 位。推荐生成算法详见第 4.3.2

签名

sign

String(32)

C380BEC2B FD727A4B6 845133519F

3AD6

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

对账单日起

bill_date

String(8)

20140603

下载对账单的日期,格式:20140603

账单类型

bill_type

String(8)

ALL

ALL,返回当日所有订单信息,默认值 SUCCESS,返回当日成功支付的订单 REFUND,返回当日退款订单 REVOKED,已撤销的订单



wx2421b1c4370ec43b

20141110

ALL

10000100

21df7dc9cd8616b56919f20d9f679233

332F17B766FC787203EBE9D6E40457A1

5 返回结果 失败时,返回以下字段

字段名

变量名

必填

类型

示例值

说明

返回状态码

return_code

String(16)

FAIL

FAIL

返回信息

return_msg

String(128)

签名失败

返回信息如非空, 为错误原因

签名失败 参数格式校验错误 该日期订单未生成

成功时,数据以文本表格的方式返回,第一行为表头,后面各行为对应的字段内容,字段内容跟查询订单 或退款结果一致,具体字段说明可查阅相应接口。

第一行为表头,根据请求下载的对账单类型不同而不同( bill_type 决定), 目前有: 当日所有订单

交易时间,公众账号 ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款 银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额, 代金券或立减优惠退款金 额,退款类型,退款状态,商品名称,商户数据包,手续费,费率

当日成功支付的订单

交易时间,公众账号 ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款 银行,货币种类,总金额, 代金券或立减优惠金额,商品名称,商户数据包,手续费,费率

当日退款的订单

交易时间,公众账号 ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款 银行,货币种类,总金额, 代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款 金额, 代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率

从第二行起,为数据记录,各参数以逗号分隔,参数前增加`符号,为标准键盘 1 左边键的字符,字段顺序 与表头一致。



倒数第二行为订单统计标题,最后一行为统计数据 总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额 举例如下:

6 错误码

名称

描述

原因

解决方案

SYSTEMERROR

接口返回错误

系统超时

请尝试再次查询。

INVALID_TRANSACTIONI D

无效 transaction_id

请求参数未按指引进行填写

参数错误,请重新检查

PARAM_ERROR

参数错误

请求参数未按指引进行填写

参数错误,请重新检查

7. 支付结果通用通知

1 应用场景

支付完成后,微信会把相关支付结果和用户信息发送给商户,商户需要接收处理,并返回应答。 对后台通知交互时,如果微信收到商户的应答不是成功或超时,微信认为通知失败,微信会通过一定的策

略(如 30 分钟共 8 次)定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。

由于存在重新发送后台通知的情况,因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确 处理重复的通知。

推荐的做法是,当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如 果没有处理过再进行处理,如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数 据锁进行并发控制,以避免函数重入造成的数据混乱。

技术人员可登进微信商户后台扫描加入接口报警群。



2 接口链接

下单 API notify_url 访微信 通知。

3 是否需要证书 不需要。

4 通知参数

字段名

变量名

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识,非交易标识,交易是 否成功需要查看 result_code 来判断

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因



以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

必填

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888888888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_i d

String(32)

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

子商户号

设备号

device_info

String(32)

013467007045764

微信支付分配的终端设备号,

随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

随机字符串,不长于 32

签名

sign

String(32)

C380BEC2BFD727A4 B6845133519F3AD6

签名,验证签名算法详见第 4.3.1

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

错误代码

err_code

String(32)

SYSTEMERROR

详细参见 6 节错误列表

错误代码描

err_code_d es

String(128)

系统错误

错误返回的信息描述

用户标识

openid

String(128)

oUpF8uJY5nlmGIikjDU kckvxtdoo

用户在商户 appid 下的唯一标识

是否关注公

is_subscrib

String(1)

Y

用户是否关注公众账号,Y-关注,N-未关注,

众账号

e

仅在公众账号类型支付有效

用户子标识

sub_openid

String(128)

oUpF8uJY5nlmGIikjDU kckvxtdoo

用户子标识

是否关注子

sub_is_sub

String(1)

Y

用户是否关注子公众账号仅在公众账号类型支

公众账号

scribe

付有效,取值范围:Y N

Y-关注

N-未关注

交易类型

trade_type

String(16)

JSAPI

JSAPINATIVEAPP



付款银行

bank_type

String(16)

CMC

银行类型采用字符串类型的银行标识银行类 型见附表

总金额

total_fee

Int

100

订单总金额,单位为分

货币种类

fee_type

String(8)

CNY

货币类型符合 ISO 4217 标准的三位字母代码, 默认人民币CNY其他值列表详见 4.2 节货 币类型

现金支付金

cash_fee

Int

100

现金支付金额订单现金支付金额详见 4.2

支付金额

现金支付货

cash_fee_t

String(16)

CNY

货币类型符合 ISO 4217 标准的三位字母代码,

币类型

ype

默认人民币CNY其他值列表详见 4.2 节货

币类型

代金券或立

coupon_fee

Int

代金券或立减优惠金额<=订单总金额,订单总

减优惠金额

金额-代金券或立减优惠金额=现金支付金额

4.2 节支付金额

代金券或立 减优惠使用 数量

coupon_co unt

Int

1

代金券或立减优惠使用数量

代金券或立

coupon_bat

String(20)

100

代金券或立减优惠批次 ID ,$n 为下标,从 1

减优惠批次

ch_id_$n

始编号

ID

代金券或立 减优惠 ID

coupon_id_

$n

String(20)

10000

代金券或立减优惠 ID, $n 为下标,从 1 开始编

单个代金券

coupon_fee

Int

100

单个代金券或立减优惠支付金额, $n 为下标

或立减优惠

_$n

1 开始编号

支付金额

微信支付订

transaction

String(32)

121775250120140703

微信支付订单号

单号

_id

3233368018

商户订单号

out_trade_n o

String(32)

121232121120140703

3568112322

商户系统的订单号,与请求一致。

商家数据包

attach

String(128)

123456

商家数据包,原样返回

支付完成时

time_end

String(14)

20141030133525

支付完成时间,格式为 yyyyMMddHHmmss

2009 12 25 9 10 10 秒表示为

20091225091010其他详见 3.2 节时间规则

举例如下:



ppid>

支付测试]]>

5 返回参数 商户处理后同步返回给微信参数:

字段名

变量名

必填

类型

示例值

描述

返回状态码

return_cod e

String(16)

SUCCESS

SUCCESS/FAIL

SUCCESS 表示商户接收通知成功并校验成功

返回信息

return_msg

String(128)

OK

返回信息,如非空,为错误原因: 签名失败

参数格式校验错误

举例如下:

8. 测速上报

1 应用场景 商户在调用微信支付提供的相关接口时,会得到微信支付返回的相关信息以及获得整个接口的响应时间。

为提高整体的服务水平,协助商户一起提高服务质量,微信支付提供了相关接口调用耗时和返回信息的主动上 报接口,微信支付可以根据商户侧上报的数据进一步优化网络部署,完善服务监控,和商户更好的协作为用户 提供更好的业务体验。



2 接口地址

https://api.mch.weixin.qq.com/payitil/report

3 是否需要证书

4 输入参数

字段名

变量名

必填

类型

示例值

描述

公众账号 ID

appid

String(32)

wx8888888888 888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

设备号

device_info

String(32)

013467007045

764

微信支付分配的终端设备号,商户自定义

随机字符串

nonce_str

String(32)

5K8264ILTKCH

16CQ2502SI8Z NMTM67VS

随机字符串,不长于 32 位。推荐生成算法详见第 4.3.2

签名

sign

String(32)

C380BEC2BFD 727A4B684513

3519F3AD6

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

接口 URL

interface_url

String(127)

https://api.mch. weixin.qq.com/ pay/unifiedorde r

上报对应的接口的完整 URL,类似: https://api.mch.weixin.qq.com/pay/unifiedorder

对于被扫支付为更好的和商户共同分析一次业务行为的 整体耗时情况对于 2 种接入模式请都在门店侧对一次 被扫行为进行一次单独的整体上报,上报 URL 指定为:

https://api.mch.weixin.qq.com/pay/micropay/total

关于 2 中接入模式具体可参考本文档章节被扫支付商户 接入模式

其它接口调用仍然按照调用一次,上报一次来进行。



接口耗时

execute_tim e_

Int

1000

接口耗时情况,单位为毫秒

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识非交易标识交易是否成功需要查看

trade_state 来判断

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

错误代码

err_code

String(32)

SYSTEMERRO R

ORDERNOTEXIST—订单不存在 SYSTEMERROR—系统错误

错误代码描

err_code_d es

String(128)

系统错误

结果信息描述

商户订单号

out_trade_n

String(32)

121775250120

商户系统内部的订单号,商户可以在上报时提供相关商户

o

140703323336

订单号方便微信支付更好的提高服务质量。

8018

访问接口 IP

user_ip

String(16)

8.8.8.8

发起接口调用时的机器 IP

商户上报时

time

String(14)

200912270910

系统时间,格式为 yyyyMMddHHmmss,如 2009 12

10

27 9 10 10 秒表示为 20091227091010其他

详见 4.2 节时间规则

5 返回结果

字段名

变量名

必填

类型

示例值

描述

返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识,非交易标识,交易是否成功需要查 result_code 来判断

返回信息

return_msg

String(128)

签名失败

返回信息,如非空,为错误原因 签名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

类型

示例值

描述



业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

6 错误码

9. 转换短链接

1 应用场景 (weixin://wxpay/s/XXXXXX)

数据量,提升扫描速度和精确度。 2 接口地址

https://api.mch.weixin.qq.com/tools/shorturl 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)

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

子商户号

URL 链接

long_url

String(512)

weixin://wxpay/bizpayur l?sign=XXXXX&appid=XXXX X&mch_id=XXXXX&product_ id=XXXXXX&time_stamp=XX XXXX&nonce_str=XXXXX

需要转换的 URL 签名用原串传输需

URL encode

随机字符串

nonce_str

String(32)

5K8264ILTKCH16CQ2502SI8 ZNMTM67VS

随机字符串不长于 32 位。推荐生成算 法详见第 4.3.2

签名

sign

String(32)

C380BEC2BFD727A4B684513 3519F3AD6

签名,详见 4.3.1 签名生成算法

5 返回结果

字段名

变量名

必填

类型

示例值

描述



返回状态码

return_code

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识,非交易标识, 交易是否成功需要查看 result_code 来判断

返回信息

return_msg

String(128)

签名失败

返回信息如非空为错误原因签 名失败

参数格式校验错误

以下字段在 return_code SUCCESS 的时候有返回

字段名

变量名

必填

类型

示例值

描述

公众账号 ID

appid

String(32)

wx888888888 8888888

微信分配的公众账号 ID

商户号

mch_id

String(32)

1900000109

微信支付分配的商户号

子商户公众 账号 ID

sub_appid

String(32)

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

子商户公众账号 ID

子商户号

sub_mch_id

String(32)

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

子商户号

随机字符串

nonce_str

String(32)

5K8264ILTKC H16CQ2502SI 8ZNMTM67VS

随机字符串,不长于 32 位。推荐 生成算法详见第 4.3.2

签名

sign

String(32)

C380BEC2BFD 727A4B68451

33519F3AD6

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

业务结果

result_code

String(16)

SUCCESS

SUCCESS/FAIL

错误代码

err_code

String(32)

SYSTEMERROR

SYSTEMERROR—系统错误 URLFORMATERRORURL 格式错误

URL 链接

short_url

String(64)

weixin://wx pay/s/XXXXX X

转换后的 URL

6 错误码

名称

描述

原因

解决方案

SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否 都符合签名算法要求



REQUIRE_POST_METHO D

请使用 post 方法

未使用 post 传递参数

请检查请求参数是否通过

post 方法提交

APPID_NOT_EXIST

APPID 不存在

参数中缺少 APPID

请检查 APPID 是否正确

MCHID_NOT_EXIST

MCHID 不存在

参数中缺少 MCHID

请检查 MCHID 是否正确

APPID_MCHID_NOT_MA TCH

appid mch_id 不匹配

appid mch_id 不匹配

请确认 appid mch_id 否匹配

LACK_PARAMS

缺少参数

缺少必要的请求参数

请检查参数是否齐全

XML_FORMAT_ERROR

XML 格式错误

XML 格式错误

请检查 XML 参数格式是否 正确

POST_DATA_EMPTY

post 数据为空

post 数据不能为空

请检查 post 数据是否为空

10. 代金券或立减优惠

使 API 调用 下面详细介绍怎样配置代金券或立减优惠。

1. 创建批次代金券或立减优惠 商户需要使用该功能,请先登录商户系统(地址:https://pay.weixin.qq.com)建新批次。



2. 确保可用余额充足

发放代金券或立减优惠将使用商户的可用余额,需确保可用余额充足。查看可用余额、充值、提现可在商 户平台“资金管理”进行操作

3. 发放代金券或立减优惠 商户可在创建好的批次详情中查看发放方式。目前主要提供了 3 种发放方式

1) 每个批次都有唯一的二维码可供用户扫码领取

2) 可在商户平台配置营销规则,如满额送即微信支付成功后立即发放红包给用 户。

3) openAPI 提供发放和查询代金券或立减优惠相关接口。

4. 用户使用代金券或立减优惠 已领取代金券或立减优惠的用户,在可使用的商户微信支付时使用可减价。红包对应的金额会和用户支付

的金额一并同时支付给商户。



5. 灵活定制代金券或立减优惠商品标识

代金券或立减优惠为商户提供了灵活定制使用商品范围的能力。在单品优惠、类目优惠、限时优惠等场景 下灵活控制商品是否可使用代金券或立减优惠。

1 实现方法 第一步:创建批次时设置该批次可使用的商品标识。

在“使用方式”的选填项目中,可设置商品标识。

注意:【商品标识】字段对应支付接口中的参数 goods_tag,该值配置为空时,提交支付接口不需要传 goods_tag 字段;



第二步:提交支付,在 API 参数对特定商品传入 goods_tag

提交 goods_tag 参数值为批次中配置的【商品标识】,微信后台会判断,如果存在有效代金券即交易符合 代金券扣减规则,用户实际支付金额=总扣款-有效代金券或立减优惠金额。

2 应用场景举例

场景举例:指定单品优惠,如 iPhone5s 直降 100

第一步:创建单品优惠批次,设置面额 100 元,商品标识为”iPhone5s”。确保可用余额充足。将代 金券或立减优惠发放给用户。

第二步:商户提交支付时判断商品为 iPhone5S,则设置 goods_tag 参数为“iPhone5s”,则领用了代 金券或立减优惠的用户,支付该商户 iPhone5s 的订单时,可使用红包减价 100 元。支付成功后商户收到的金 额为用户支付金额+代金券或立减优惠金额。

6. 查询支付的代金券或立减优惠金额 支付成功或查询接口会返回用户使用代金券或立减优惠金额。接口返回字段 coupon_fee 为使用代金券或

total_fee =total_fee-coupon_fee给用 户,发票额与用户实际支付金额相等。

7. 代金券或立减优惠对账单 对账单中有代金券或立减优惠金额字段和订单总金额,用于对账。

11. SDK 下载

请去网页上下载,点击打开

12. 常见问题和注意事项

1. 服务器 SSL 版本说明

由于低版本的 SSL 存在高危漏洞,需要确认您系统所使用的 SSL 版本是否需要升级,详细说明请见公众平 SSL 安全策略说明:

https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=1414562353&version=11&lang

=zh_CN

Java 开发可以参考 Oracle 网站的说明:[Oracle Java disable SSL3](http://www.oracle.com/technetwork/java/javase/documentation/cve-2014-3566-2342133.html)

2. IPV6 相关



如果您的服务器开启了 IPv6 支持,由于当前互联网对 IPv6 支持不完整,导致在 DNS 解析时通常会碰到超 时问题;

建议在调用支付 API 时,显示指定使用 IPv4 解析. PHP 程序使用 curl 调用参考代码如下:

if(defined('CURLOPT_IPRESOLVE') && defined('CURL_IPRESOLVE_V4')){

curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);

}

13. 联系我们

1. 添加公众号“微信支付商户通”,发微信消息可以联系到我们;

2. 发邮件到 weixinpay@tencent.com

本文来源:https://www.2haoxitong.net/k/doc/a1e1edcfe45c3b3566ec8b16.html

《微信支付API文档120(受理).doc》
将本文的Word文档下载到电脑,方便收藏和打印
推荐度:
点击下载文档

文档为doc格式