微信公众号支付接口文档（结算中心-受理机构）v0.0 - 图文

微信公众号支付接口文档

（结算中心-受理机构）

讨论

微信被扫支付接口文档（结算中心-受理机构）V0.0

1

目录

修改日志............................................................................................................................................. 4 1.微信支付简介.................................................................................................................................. 5

1.1.功能简介 ............................................................................................................................... 5 1.2.支付账户 ............................................................................................................................... 5 1.3.支付方式 ............................................................................................................................... 6 2.支付场景介绍.................................................................................................................................. 6

2.1.网页内支付场景---JS API（网页内）支付接口 ................................................................. 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

微信被扫支付接口文档（结算中心-受理机构）V0.0

2

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.常见注意事项 ..................................................................................................................... 36

微信被扫支付接口文档（结算中心-受理机构）V0.0

3

修改日志

日期 修改人 创建 修改 修改 修改 修改 操作 修改内容 新增修改日志 修改“4.8 退款申请接口”参数名“Sign_szfs”为“sign_szfs” 修改“3.3 结算中心签名方式” 修改“6 返回状态码列表”，新增状态码“FAIL_STATUS”、“FAIL_SIGN”、“FAIL_SZFS” 修改“4.7 关闭订单接口”参数“商户订单号（out_trade_no）”为必填 2014-12-26 陈恒 2014-12-26 陈恒 2014-12-26 陈恒 2014-12-26 陈恒 2015-01-05 陈恒 微信被扫支付接口文档（结算中心-受理机构）V0.0

4

1.微信支付简介

1.1.功能简介

微信支付，是基于微信客户端提供的支付服务功能。同时向商户提供销售经营分析、账户和资金管理的功能支持。用户通过扫描二维码、微信内打开商品页面购买等多种方式调起 微信支付模块完成支付。

微信支持公众号内支付，即基于公众号向用户收款，公众号相当于收款的商户。其中支付方式，可以分为 JS API（网页内）支付、Native（原生）支付。商户可以结合业务场景， 自主选择支付方式。

本文将全面介绍微信支付的技术方案。

1.2.支付账户

商户向微信提交企业以及银行账户资料，商户功能审核通过后，可以获得以下帐户（包含财付通的商户账户），用于公众号支付。 帐号 appId Mchid SubMchId Key 作用 微信公众号身份的唯一标识。审核通过后，在微信发送的邮件中查看。 商户 ID，身份标识，在微信发送的邮件中查看。 子商户ID，受理模式下子商户与受理商有绑定关系，没有不提交该参数 商户支付密钥Key。登录微信商户后台，进入栏目【账户设置】【密码安全】【API 安全】【API 密钥】 JSAPI 接口中获取 openid，审核后在公众平台开启开发模式后可查看。 Appsecret 微信被扫支付接口文档（结算中心-受理机构）V0.0

5

注意： 支付密钥 Key 是验证商户唯一性的安全标识，请妥善保管，仅保留在第三方后 台和微信后台，不会在网络中传播。

1.3.支付方式

JS API（网页内）支付：是指用户打开图文消息或者扫描二维码，在微信内置浏览器

打开网页进行的支付。商户网页前端通过使用微信提供的 JS API，调用微信支付模块。这种方 式，适合需要在商户网页进行选购下单的购买流程。

Native（原生）支付：是指商户组成符合 Native（原生）支付规则的 URL 链接，

用户 可通过在会话中点击链接或者扫描对应的二维码直接进入微信支付模块（客户端界面），即可进行支付。这种方式，适合无需选购直接支付的购买流程。跟 JSAPI 最大的区别是不经过网页调起支付。

2.支付场景介绍

2.1.网页内支付场景---JS API（网页内）支付接口

商户已有 H5 商城网站，在微信内打开网页时，可以调用微信支付完成下单购买的流程。

步骤（1）：左图，商户下发图文消息或者通过自定义菜单吸引用户点击进入商户网页。

步骤（2）：右图，进入商家网页，用户选择购买，完成选购流程。

微信被扫支付接口文档（结算中心-受理机构）V0.0

6

步骤（3）：左图，调起微信支付控件，用户开始输入支付密码。

步骤（4）：右图，密码验证通过，支付成功。商户后台得到支付成功的通知。

步骤（5）：左图，返回商户页面，显示购买成功。该页面由商户自定义。 步骤（6）：右图，公众号下发消息，提示发货成功。该步骤可选。

微信被扫支付接口文档（结算中心-受理机构）V0.0

7

微信公众号支付接口文档 V3.3

注意：商户也可以把商品网页的链接生成二维码，用户扫一扫打开后即可完成购买支付。

2.1.1.交互细节

以下是支付场景的交互细节，请认真阅读，并设计商户页面的逻辑： （ 1 ） 用 户 打 开 商 户 网 页 选 购 商 品 ， 发 起 支 付 ， 在 网 页 通 过 JavaScript 调用getBrandWCPayRequest 接口，发起微信支付请求，用户进入支付流程。

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

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

注：

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

JS API 返回值目前只在支付成功时返回，后续版本将扩展返回值，以便商户做更多

个性化的展示。

微信被扫支付接口文档（结算中心-受理机构）V0.0

8

微信公众号支付接口文档 V3.3

2.1.2.JSAPI 支付时序图

2.1.3.获取当前微信版本号

由于微信 5.0 版本后才加入微信支付模块，低版本用户调用微信支付功能将无效。因此， 建议商户通过 user agent 来确定用户当前的版本号后再调用支付接口。以 iPhone 版本为例， 可以通过 user agent 可获取如下微信版本示例信息：

\ Geocko) Mobile/9B206 MicroMessenger/5.0\

其中 5.0 为用户安装的微信版本号，商户可以判定版本号是否高于或者等于 5.0。

2.1.4.显示微信安全支付标题

对于商户具有支付权限且需要调用微信支付的页面，为了让用户增加购买信心，确认交易环境安全，微信强烈建议商户使用“微信安全支付”标题。安全支付标题的如下图。

微信被扫支付接口文档（结算中心-受理机构）V0.0

9

微信公众号支付接口文档 V3.3

显示支付安全标题，需将原始链接添加上\的尾串。通过这种方式， 商户的页面将出现微信安全支付的标识。例如，原始 URL 为：htp://weixin.qq.com,显示安全 支付标题的 URL 为：htp://weixin.qq.com?showwxpaytitle=1。

当用户在微信里打开 http://weixin.qq.com不会直接出现微信安全支付的标题，而打开 htp://weixin.qq.com?showwxpaytitle=1后将出现微信安全支付标题。

2.2.线下扫码购买场景---Native（原生）支付接口

2.2.1 使用场景

与网页内支付场景不同，部分商户不需要经过网页选购，可以直接下单购买。 步骤（1）：左图，商户根据微信支付的规则，为不同商品生成不同的二维码，张贴在各种场景，便于用户扫描购买。

步骤（2）：右图，用户使用微信扫描二维码后，获取商品信息，同时到商户后台下单。

步骤（3）：左图，用户开始支付，输入支付密码。

微信被扫支付接口文档（结算中心-受理机构）V0.0

10

微信公众号支付接口文档 V3.3

步骤（4）：右图，支付成功，商户后台得到通知，进行发货处理。

2.2.2.Native（原生）支付 URL 定义

模式一：商户按固定格式生成链接二维码，用户扫码后调微信会将 productid 和用户 openid 发送到商户设置的链接上，商户收到请求生成订单，调用统一支付接口下单提交

到微信，微信会返回给商户prepayid，时序图如下：

微信被扫支付接口文档（结算中心-受理机构）V0.0

11

微信公众号支付接口文档 V3.3

对应链接：

weixin://wxpay/bizpayurl?sign=XXXXX&appid=XXXXX&mch_id=XXXXX&product_id= XXXXXX &time_stamp=XXXXXX&nonce_str=XXXXX

模式二：商户生成订单，先调用统一支付接口获取到 code_url，此 URL 直接生成二

维 码，用户扫码后调起支付。时序图如下：

微信被扫支付接口文档（结算中心-受理机构）V0.0

12

微信公众号支付接口文档（结算中心-受理机构） V0.0

code_url 对应链接：

weixin://wxpay/bizpayurl?sr=XXXXX

3.接口说明

3.1.接口调用规则

? 认证方式：HTTP 认证，退款和撤销接口调用需要商户证书（证书由结算中

心下发）

? 请求采用 POST 方式

? 提交和返回结果采用 XML 格式

? 字符集默认使用UTF-8，请勿使用其它字符集

? 商户与微信之间的交互(特别是 Native 回调和支付通知回调)，都需要验证签名

微信被扫支付接口文档（结算中心-受理机构）V0.0

13

微信公众号支付接口文档（结算中心-受理机构） V0.0

? 处理返回时先判断协议返回错误码，再判断业务返回错误码，最后判断交易状态

3.2.微信Sign 签名生成方法

假设微信支付分配的参数为： (1)第三方商户的商户参数： 商户参数名 appid mch_id Key 参数值 wxd00000000000000f 10000001 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 字符串的示范过程：

微信被扫支付接口文档（结算中心-受理机构）V0.0

14

微信公众号支付接口文档（结算中心-受理机构） V0.0

假设以下为传入参数： appid=wxd00000000000000f mch_id=10000001 auth_code=123456 body=test device_info=123 nonce_str=960f228109051b9969f76c82bde183ac out_trade_no=1400755861 spbill_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=1 0000001&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&mc h_id=10000001&nonce_str=960f228109051b9969f76c82bde183ac&out_trade_no=1400755861& spbill_create_ip=127.0.0.1&total_fee=1&key=8934e7d15453e97507ef794cf7b0519d).toUpperCa se() =\=\ 3.3 结算中心签名生成方法

受理机构在发起撤销和退款申请时，需要对相应接口的“提交参数”进行签名。除“结算中心签名(sign_szfs)”和值为空的参数外，所有“提交参数”都需参与签名。生成的签名填充参数“结算中心签名”。

结算中心收到一笔撤销和退款申请时必须用“提交参数”中的“结算中心签名”来验证报文的有效性。

签名所需的私钥文件由结算中心统一提供，各受理机构需要更换私钥文件时可以向结算中心申请。验签所需的公钥文件由结算中心决定是否更换。

以下给出签名的生成方式：

（1）除“结算中心签名”和值为空的参数外，所有“提交参数”都需参与签名。 （2）对所有传入参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1，string1即为签名要素。注意：此时string1应包括sign=signValue。

（3）使用自身的数字证书（私钥）对签名要素串签名，签名的校验算法使用SHA1WithRSA算法。

微信被扫支付接口文档（结算中心-受理机构）V0.0 （4）将签名值使用BASE64转码后得到参数“结算中心签名”的值。

15

微信公众号支付接口文档（结算中心-受理机构） V0.0

3.4 调用流程

(1)商户发起请求处理流程：

(2)商户调用返回或微信主动通知处理流程：

微信被扫支付接口文档（结算中心-受理机构）V0.0

16

微信公众号支付接口文档（结算中心-受理机构） V0.0

4.API 说明

4.1.统一支付接口

URL 地址：待定

统一支付接口，可接受 JSAPI/NATIVE/APP 下预支付订单，返回预支付订单号。NATIVE 支付返回二维码 code_url。

注意：JSAPI 下单前需要调用登录授权接口(详细调用说明请点击打开链接)获取到用

户的 Openid。

请求参数：

字段名 公众账号 ID 商户号 子商户号 设备号 随机字符串 签名 商品描述 附加数据 商户订单号 变量名 appid mch_id sub_mch_id device_info nonce_str sign body attach out_trade_no 必填 是 是 否 否 是 是 是 否 是 类型 String(32) String(32) String(32) String(32) String(32) String(32) String(127) String(127) String(32) 说明 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 微信支付分配的终端设备号 随机字符串，不长于 32 位 签名,详细签名方法见 3.2 节 商品描述 附加数据，原样返回 商 户 系统 内 部 的 订单 号 ,32个字符内、可包含字母,确保 在商户系 统唯一,详细说明 见 8.3节第四项 订单总金额，单位为分，不 能带小数点 订单生成的机器 IP 订 单 生 成 时 间 ， 格 式 为 yyyyMMddHHmmss，如 2009 年 12 月 25 日 9 点 10 分 10 秒表 示为 20091225091010。时区 总金额 终端 IP 交易起始时间 total_fee spbill_create_ip time_start 是 是 否 Int String(16) String(14) 微信被扫支付接口文档（结算中心-受理机构）V0.0

17

交易结束时间 time_expire 微信公众号支付接口文档（结算中心-受理机构） V0.0

String(14) 否 为 GMT+8 beijing。该时间取 自商户服务器订 单 失 效 时 间 ， 格 式 为 yyyyMMddHHmmss，如 2009 年 12 月 27 日 9 点 10 分 10 秒表 示为 20091227091010。时区 为 GMT+8 beijing。该时间取 自商户服务器 商品标记 goods_tag 否 String(32) 商品标记，该字段不能随便 填，不使用请填空，使用说 明详见第 5 节 接收微信支付成功通知 JSAPI、NATIVE、APP 用户在商户 appid 下的唯一 标识，trade_type 为 JSAPI 时，此参数必传，获取方式 见表头说明。 只 在 trade_type 为 NATIVE 时需要填写。此 id 为二维码 中包含的商品 ID，商户自行 维护。 通知地址 交易类型 用户标识 notify_url trade_type openid 是 是 否 String(256) String(16) String(128) 商品 ID

product_id 否 String(32) 返回参数： 字段名 返回状态码 变量名 return_code 必填 是 类型 String(16) 说明 此字段是通信标识，非交易标 识 ， 交 易 是 否 成 功 需 要 查 看 result_code 来判断 详见 第 6 节 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误 微信侧超时 返回信息 return_msg 否 String(128) 以下字段在 return_code 为 SUCCESS 的时候有返回 公众账号 ID appid 是 String(32) 微信分配的公众账号 ID 微信被扫支付接口文档（结算中心-受理机构）V0.0

18

商户号 子商户号 设备号 随机字符串 签名 业务结果 错误代码 错误代码描述 交易类型 预支付 ID 二维码链接 mch_id sub_mch_id device_info nonce_str sign result_code err_code err_code_des trade_type prepay_id code_url 微信公众号支付接口文档（结算中心-受理机构） V0.0

是 否 否 是 是 是 否 否 是 是 否 String(32) String(32) String(32) String(32) String(32) String(16) String(32) String(128) String(16) String(64) String(64) 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 微 信 支 付 分 配 的 终 端 设 备 号， 随机字符串，不长于32 位 签名,详细签名方法见 3.2 节 SUCCESS/FAIL 列表第7 节 结果信息描述 JSAPI、NATIVE、APP 微信生成的预支付 ID，用于 后续接口调用中使用 trade_type 为 NATIVE 是 有 返回，此参数可直接生成二 维码展示出来进行扫码支付 以下字段在 return_code 和 result_code 都为 SUCCESS 的时候有返回 请求示例：

wxd00000000000000f NATIVE 123 10000001

960f228109051b9969f76c82bde183ac 1400755861

127.0.0.1 1 100

0B28FE46B0E12E4692CA950D67CECDE5 wxd88888888888888f 10000002

78078498E19F1E74A489AB6428A521AD

返回示例：

SUCCESS OK

wx2421b1c4370ec43b 10000100

1000

LM1Bbp0WoDV5jqpP

微信被扫支付接口文档（结算中心-受理机构）V0.0

19

微信公众号支付接口文档（结算中心-受理机构） V0.0

1DE267795ECCC5BFB90DDCA91DBBF107 SUCCESS

wx20140718112216156db45f6d0493886204 NATIVE

wxd88888888888888f 10000002

C380BEC2BFD727A4B6845133519F3AD6

4.2.通用通知接口

通知 URL 是 4.1 节中提交的参数 notify_url，支付完成后，结算中心会把相关支付和用户信息发送到该 URL，第三方受理机构需接收该通知并验签，验签通过才可做下一步操作。

对后台通知交互时，如果结算中心收到第三方受理机构的应答不是成功或超时，结算中心认为通知失败，中心会通过一定的策略（如 30 分钟共 8 次）定期重新发起通知，尽可能提高通知的成功率， 但中心不保证通知最终能成功。

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

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

通知参数：

字段名 返回状态码 变量名 return_code 必填 是 类型 说明 返回信息 return_msg 否 String(16) 此字段是通信标识，非交易标 识 ， 交 易 是 否 成 功 需 要 查 看 result_code 来判断 详见 第 6 节 String(128) 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误 以下字段在 return_code 为 SUCCESS 的时候有返回 公众账号 ID appid 是 String(32) 微信分配的公众账号 ID 微信被扫支付接口文档（结算中心-受理机构）V0.0

20

微信公众号支付接口文档（结算中心-受理机构） V0.0

商户号 子商户号 设备号 随机字符串 签名 业务结果 错误代码 错误代码描述 mch_id sub_mch_id device_info nonce_str sign result_code err_code err_code_des 是 否 否 是 是 是 否 否 String(32) String(32) String(32) String(32) String(32) String(16) String(32) 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 微 信 支 付 分 配 的 终 端 设 备 号， 随机字符串，不长于 32 位 签名,详细签名方法见 3.2 节 SUCCESS/FAIL 错误码见第 7 节 String(128) 结果信息描述 以下字段在 return_code 和 result_code 都为 SUCCESS 的时候有返回 用户标识 openid 是 String(128) 用户在商户 appid 下的唯一 标识 是否关注公众账 is_subscribe 号 交易类型 付款银行 总金额 trade_type bank_type total_fee 是 String(1) 用户是否关注公众账号，Y- 关注，N-未关注，仅在公众 账号类型支付有效 JSAPI、NATIVE、MICROPAY、 APP 银行类型，采用字符串类型 的银行标识 订单总金额，单位为分 现金券支付金额<=订单总金 额，订单总金额-现金券金额 为现金支付金额 货币类型，符合 ISO 4217 标准的三位字母代码，默认人 民币：CNY 微信支付订单号 商户系统的订单号，与请求 一致。 支 付 完 成 时 间 ， 格 式 为 yyyyMMddhhmmss，如 2009 年 12 月 27 日 9 点 10 分 10 秒表 示为 20091227091010。时区 为 GMT+8 beijing。该时间取 自微信支付服务器 是 是 是 否 String(16) String(16) Int Int 现金券金额 货币种类 coupon_fee fee_type 否 String(8) 微信支付订单号 transaction_id 商户订单号 商家数据包 支付完成时间 out_trade_no attach time_end 是 是 否 是 String(32) String(32) String(128) 商家数据包，原样返回 String(14) 微信被扫支付接口文档（结算中心-受理机构）V0.0

21

微信公众号支付接口文档（结算中心-受理机构） V0.0

商户处理后同步返回给中心参数：

字段名 返回状态码 变量名 return_code 必填 是 类型 String(16) 说明 SUCCESS/FAIL SUCCESS 表示商户接收通知 成功并校验成功 返回信息 return_msg 否 String(128) 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误

4.3.订单查询接口

接口链接：待定

该接口提供所有微信支付订单的查询，当支付通知处理异常或丢失的情况，商户可以通

过该接口查询订单支付状

态。 请求参数： 字段名 公众账号 ID 商户号 子商户号 微信订单号 商户订单号 变量名 appid mch_id sub_mch_id transaction_id 必填 是 是 否 否 是 类型 String(32) String(32) String(32) String(32) String(32) 说明 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号，受理模式下必填 微信的订单号，优先使用 商户系统内部的订单号, transaction_id、out_trade_no 二 选一，如果同时存在优先级： transaction_id> out_trade_no 随机字符串，不长于 32 位 签名,详细签名方法见 3.2节 out_trade_no 随机字符串 签名

nonce_str sign 是 是 String(32) String(32) 同步返回结果：

字段名 变量名 必填 类型 说明 微信被扫支付接口文档（结算中心-受理机构）V0.0

22

微信公众号支付接口文档（结算中心-受理机构） V0.0

返回状态码 return_code 是 返回信息 return_msg 否 String(16) 此字段是通信标识，非交易标 识 ， 交 易 是 否 成 功 需 要 查 看 result_code 来判断 详见 第 6 节 String(128) 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误 微信侧超时 以下字段在 return_code 为 SUCCESS 的时候有返回 公众账号 ID 商户号 子商户号 随机字符串 签名 业务结果 错误代码 错误代码描述 交易状态 appid mch_id sub_mch_id nonce_str sign result_code err_code err_code_des trade_state 是 是 否 是 是 是 否 否 是 String(32) String(32) String(32) String(32) String(32) String(16) String(32) 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 随机字符串，不长于 32 位 签名,详细签名方法见 3.2 节 SUCCESS/FAIL 错误码见第 7 节 String(128) 结果信息描述 String(32) SUCCESS—支付成功 REFUND—转入退款 NOTPAY—未支付 CLOSED—已关闭 REVOKED—已撤销 USERPAYING--用户支付中 NOPAY--未支付(输入密码或 确认支付超时) PAYERROR-- 支 付 失 败 ( 其 他 原因，如银行返回失败) 以下字段在 return_code 和 result_code 都为 SUCCESS 的时候有返回 以下字段在 return_code 和 result_code 都为 SUCCESS 的时候有返回 设备号 device_info 否 String(32) 微 信 支 付 分 配 的 终 端 设 备 号， 用户标识 openid 是 是 String(128) 用户在商户 appid 下的唯一 标识 String(1) 用户是否关注公众账号，Y- 关注，N-未关注，仅在公众 账号类型支付有效 是否关注公众账 is_subscribe 号 微信被扫支付接口文档（结算中心-受理机构）V0.0

23

微信公众号支付接口文档 （结算中心-受理机构）V0.0

交易类型 付款银行 总金额 trade_type bank_type total_fee 是 是 是 否 String(16) String(16) Int Int JSAPI、NATIVE、MICROPAY、 APP 银行类型，采用字符串类型 的银行标识 订单总金额，单位为分 现金券支付金额<=订单总金 额，订单总金额-现金券金额 为现金支付金额 货币类型，符合 ISO 4217 标 准的三位字母代码，默认人 民币：CNY 微信支付订单号 商户系统的订单号，与请求 一致。 支 付 完 成 时 间 ， 格 式 为 yyyyMMddhhmmss，如 2009 年 12 月 27 日 9 点 10 分 10 秒表 示为 20091227091010。时区 为 GMT+8 beijing。该时间取 自微信支付服务器 现金券金额 货币种类 coupon_fee fee_type 否 String(8) 微信支付订单号 transaction_id 商户订单号 商家数据包 支付完成时间 out_trade_no attach time_end 否 否 否 是 String(32) String(32) String(128) 商家数据包，原样返回 String(14)

4.7 关闭订单接口

接口链接：待定

当订单支付失败，调用关单接口后用新订单号重新发起支付，如果关单失败，返回已完

成支付请按正常支付处理。如果出现银行掉单，调用关单成功后，微信后台会主动发起退

款。 请求参数：

字段名 公众账号 ID 商户号 子商户号 商户订单号 随机字符串 签名

变量名 appid mch_id sub_mch_id out_trade_no nonce_str sign 必填 是 是 否 是 是 是 类型 String(32) String(32) String(32) String(32) String(32) String(32) 说明 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号，受 理模式下必填 商户系统内部的订单号 随机字符串，不长于 32 位 签名,详细签名方法见 3.2节 24 微信被扫支付接口文档（结算中心-受理机构）V0.0 同步返回结果：

微信公众号支付接口文档 （结算中心-受理机构）V0.0 字段名 返回状态码 变量名 return_code 必填 是 类型 说明 String(16) 此字段是通信标识，非交易标 识 ， 交 易 是 否 成 功 需 要 查 看 result_code 来判断 详见 第 6 节 返回信息 String(128) 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误 微信侧超时 以下字段在 return_code 为 SUCCESS 的时候有返回 公众账号 ID appid 是 String(32) 微信分配的公众账号 ID 商户号 子商户号 随机字符串 签名 业务结果 mch_id sub_mch_id nonce_str sign result_code 是 否 是 是 是 String(32) String(32) String(32) String(32) String(16) 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 随机字符串，不长于 32 位 签名,详细签名方法见 3.2 节 SUCCESS/FAIL SUCCESS 表示关单成功，此笔 订单不能再发起支付； FAIL 其 它 表 示 关 单 接 口 异 常，可再次发起关单操作 return_msg 否 错误代码 错误代码描述 err_code err_code_des 否 否 String(32) 错误列表详见 第7 节 String(128) 结果信息描述 微信被扫支付接口文档（结算中心-受理机构）V0.0

25

微信公众号支付接口文档 （结算中心-受理机构）V0.0

4.8.退款申请接口

接口链接：待定

注意：

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

2.支持部分退款，部分退需要设置相同的订单号和不同的out_refund_no。一笔退款失败后重新提交，要采用原来的out_refund_no。总退款金额不能超过用户实际支付金额。

请求参数：

字段名 公众账号 ID 商户号 子商户号 设备号 随机字符串 签名 微信订单号 变量名 appid mch_id sub_mch_id device_info nonce_str sign transaction_id 必填 类型 是 是 否 否 是 是 否 是 String(32) String(32) String(32) String(32) String(32) String(32) String(28) String(32) 说明 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号，受 理模式下必填 微信支付分配的终端设备号， 与下单一致 随机字符串，不长于 32 位 签名,详细签名方法见 3.2节 微信订单号 商户系统内部的订单号, transaction_id 、 out_trade_no 二选一，如果同 时 存 在 优 先 级 ： transaction_id> out_trade_no 商户系统内部的退款单号，商 户系统内部唯一，同一退款单号多次请求只退一笔 订单总金额，单位为分 退款总金额，单位为分,可以做 部分退款 操作员帐号, 默认为商户号 商户订单号 out_trade_no 商户退款单号 总金额 out_refund_no total_fee 是 String(32) 是 是 是 是 Int Int String(32) 退款金额 操作员 结算中心签名 refund_fee op_user_id sign_szfs String(512) 详细签名方法见3.3节 微信被扫支付接口文档（结算中心-受理机构）V0.0

26

微信公众号支付接口文档 （结算中心-受理机构）V0.0

退款返回结果：

字段名 返回状态码 变量名 return_code 必填 是 类型 说明 String(16) 此字段是通信标识，非交易标 识 ， 交 易 是 否 成 功 需 要 查 看 result_code 来判断 详见 第 6 节 String(128) 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误 微信侧超时 原订单不存在 头寸不足 SUCCESS/FAIL SUCCESS 退款申请接收成功， 结果通过退款查询接口查询 FAIL 错误码详见第 7节 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 微 信 支 付 分 配 的 终 端 设 备 号，与下单一致 随机字符串，不长于 32 位 签名,详细签名方法见 3.2 节 微信订单号 商户系统内部的订单号 商户退款单号 微信退款单号 ORIGINAL—原路退款，默认 BALANCE—退回到余额 退款总金额,单位为分,可以 做部分退款 现 金 券 退 款 金 额 <= 退 款 金 额，退款金额-现金券退款金 额为现金 返回信息 return_msg 否 以下字段在 return_code 为 SUCCESS 的时候有返回 业务结果 result_code 是 String(16) 错误代码 错误代码描述 公众账号 ID 商户号 子商户号 设备号 随机字符串 签名 微信订单号 商户订单号 商户退款单号 微信退款单号 err_code err_code_des appid mch_id sub_mch_id device_info nonce_str sign transaction_id out_trade_no out_refund_no refund_id refund_channel refund_fee 否 否 是 是 否 否 是 是 是 是 是 是 否 是 否 String(32) String(32) String(32) String(32) String(32) String(32) String(32) String(28) String(32) String(32) String(28) String(16) Int Int String(128) 结果信息描述 退款渠道 退款金额 coupon_refund_fe 现金券退款金额 e 微信被扫支付接口文档（结算中心-受理机构）V0.0

27

微信公众号支付接口文档 （结算中心-受理机构）V0.0

4.9.退款查询接口

接口链接：待定

提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，用零钱支付的退款

20 分钟内到账，银行卡支付的退款 3 个工作日后重新查询退款状态。 请求参数： 字段名 公众账号 ID 商户号 子商户号 设备号 随机字符串 签名 微信订单号 商户订单号 变量名 appid mch_id sub_mch_id device_info nonce_str sign transaction_id out_trade_no 必填 类型 是 是 否 否 是 是 否 否 String(32) String(32) String(32) String(32) String(32) String(32) String(28) String(32) 说明 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号，受 理模式下必填 微信支付分配的终端设备号 随机字符串，不长于 32 位 签名,详细签名方法见 3.2节 微信订单号 商户系统内部的订单号 商户退款单号 out_refund_no 否 String(32) 商户退款单号 否 String(28) 微信退款单号 refund_id 微信退款单号 refund_id、out_refund_no、 out_trade_no 、 transaction_id 四 个 参 数 必 填一个，如果同事存在优先级 为： refund_id>out_refund_no>t ransaction_id>out_trade_n o

微信被扫支付接口文档（结算中心-受理机构）V0.0

28

退款查询同步返回结果

字段名 返回状态码 变量名 return_code 是 微信公众号支付接口文档 （结算中心-受理机构）V0.0

必填 类型 说明 String(16) 此字段是通信标识，非交易标 识 ， 交 易 是 否 成 功 需 要 查 看 result_code 来判断 详见 第 6 节 String(128) 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 微信侧超时 SUCCESS/FAIL SUCCESS 退款申请接收成功， 结果通过退款查询接口查询 FAIL 返回信息 return_msg 否

以下字段在 return_code 为 SUCCESS 的时候有返回 业务结果 result_code 是 String(16) 错误代码 错误代码描述 公众账号 ID 商户号 子商户号 设备号 随机字符串 签名 微信订单号 商户订单号 退款笔数 商户退款单号 微信退款单号 err_code err_code_des appid mch_id sub_mch_id device_info nonce_str sign transaction_id out_trade_no refund_count out_refund_no_$n refund_id_$n refund_channel_$n refund_fee_$n 否 否 是 是 否 否 是 是 是 是 是 是 是 否 是 否 String(32) 错误码详见第7 节 String(128) 结果信息描述 String(32) String(32) String(32) String(32) String(32) String(32) String(28) String(32) Int String(32) String(28) String(16) Int Int 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 微 信 支 付 分 配 的 终 端 设 备 号，与下单一致 随机字符串，不长于 32 位 签名 微信订单号 商户系统内部的订单号 退款记录数 商户退款单号 微信退款单号 ORIGINAL—原路退款 BALANCE—退回到余额 退款总金额,单位为分,可以 做部分退款 现 金 券 退 款 金 额 <= 退 款 金 额，退款金额-现金券退款金 额为现金 退款状态： SUCCES—退款成功 FAIL—退款失败 PROCESSING—退款处理中 NOTSURE—未确定，需要商户 原退款单号重新发起 CHANGE—转入代发，退款到 29

退款渠道 退款金额 coupon_refund_fe 现金券退款金额 e_$n 是 String(16) 退款状态 refund_status_$n 微信被扫支付接口文档（结算中心-受理机构）V0.0

微信公众号支付接口文档 （结算中心-受理机构）V0.0

银行发现用户的卡作废或者 冻结了，导致原路退款银行 卡失败，资金回流到商户的 现金帐号，需要商户人工干 预，通过线下或者财付通转 账的方式进行退款。 $n 表示记录的序号，取值为 0~($ refund_count -1)，例如 refund_count 指示返回的退款记 录有 2 条。第一条序号为“0”，第二条序号为“1”。

4.10.对账单接口

微信公众号支付和被扫支付业务按照受理机构合并为一个对账文件，对账单接口参考《微信被扫支付接口文档（结算中心-受理机构）v0.0》2.6节对账单接口。

4.12.接口调用上报接口

URL 地址：待定

支付接口调用监控上报接口，主要完成商户系统调用微信支付接口返回错误和延时等信息反馈给微信后台。该接口可由第三方商户直接向微信支付后台发起，也可以由转清机构发起。

请求参数：

字段名 公众账号 ID 商户号 子商户号 设备号 随机字符串 签名 接口 URL 变量名 appid mch_id sub_mch_id device_info nonce_str sign interface_url 必填 否 是 否 否 是 是 是 类型 String(32) String(32) String(32) String(32) String(32) String(32) 说明 微信分配的公众账号 ID 微信支付分配的商户号 微信支付分配的子商户号， 受理模式下必填 微信支付分配的终端设备号 随机字符串，不长于 32 位 签名,详细签名方法见 3.2 节 String(127) 上报对应的接口的完整 URL， 类似： https://api.mch.weixin.q q.com/pay/unifiedorder Int String(16) 接口耗时情况，单位为毫秒 SUCCESS/FAIL 此字段是通信标识。 接口耗时 返回状态码 返回信息 业务结果 错误代码 错误代码描述 execute_time_ return_code return_msg result_code err_code err_code_des 是 是 否 是 否 否 String(128) 返回信息，如非空，为错误 原因 String(16) String(32) String(128) 结果信息描述 30

SUCCESS/FAIL 此字段是业务返回结果。 微信被扫支付接口文档（结算中心-受理机构）V0.0

微信公众号支付接口文档 （结算中心-受理机构）V0.0 商户订单号 out_trade_no 否 String(32) 商户系统 内部的订单号 ,商 户可以在上报时提供相关商 户订单号方便微信支付更好 的提高服务质量。 发起接口调用时的机器 IP 商户调用该接口时商户自己 系 统 的 时 间 ， 格 式 为 访问接口 IP 商户上报时间 user_ip time 是 否 String(16) String(14) 微信被扫支付接口文档（结算中心-受理机构）V0.0

31

微信公众号支付接口文档 （结算中心-受理机构）V0.0

yyyyMMddHHmmss，如 2009 年 12 月 27 日 9 点 10 分 10 秒表 示为 20091227091010。时区 为 GMT+8 beijing。该时间取 自商户服务器

返回参数：

字段名 返回状态码 变量名 return_code 必填 是 类型 String(16) 说明 SUCCESS/FAIL 此字段是通信标识，非交易 标识，交易是否成功需要查 看 result_code 来判断 返回信息 return_msg 否 String(128) 返回信息，如非空，为错误 原因 签名失败 参数格式校验错误 以下字段在 return_code 为 SUCCESS 的时候有返回 业务结果 result_code 是 String(16) 错误代码 错误代码描述

SUCCESS/FAIL err_code err_code_des 否 否 String(32) String(128) 结果信息描述

5.企业红包使用说明

5.1 创建批次企业红包

商户需要使用该功能，请先登录商户系统(地址：https://mch.weixin.qq.com)建新批次。 注意：【商品标识】字段对应被扫支付接口中的参数 goods_tag，该值配置为空时，提交支付 接口不需要传 goods_tag 字段；多个批次使用相同的商品标识，则扣款时会使用有效的批次 企业红包(使用企业红包金额小于订单金额)。

5.2 提交支付使用企业红包

被扫支付 API 中提交 goods_tag 参数值为 5.1 节中配置的【商品标识】，微信后台会判断， 如果存在有效代金券即交易符合代金券扣减规则，用户实际支付金额=总扣款-有效企业红包 金额。

微信被扫支付接口文档（结算中心-受理机构）V0.0

32

5.3 查询使用企业红包金额

微信公众号支付接口文档 （结算中心-受理机构）V0.0

被扫支付扣款成功或查询接口会返回用户使用企业红包金额。接口返回字段 coupon_fee 为使用企业红包金额，total_fee 为订单总金额，用户实际支付金额=total_fee-coupon_fee，商户如需提供发票给用户，发票额与用户实际支付金额相等。

5.4 企业红包对账单

对账单中有企业红包金额字段和订单总金额，用于对账。后续会提供查询某个用户订单 使用对应的批次的对账单。

6. 返回状态码列表

返回状态码 (return_code)

返回状态码 SUCCESS FAIL TIMEOUT FAIL_NOT_ENOUGH FAIL_NOT_EXIST FAIL_STATUS FAIL_SIGN FAIL_SZFS 返回状态码描述 签名失败、参数格式校验错误 超时 头寸不足 原订单不存在 受理机构状态异常 结算中心验签失败 失败 支付 Y Y Y Y Y 查单 Y Y Y Y Y 关单 Y Y Y Y Y Y 退款 Y Y Y Y Y Y Y Y 退款 查询 Y Y Y Y Y

超时：结算中心转发给微信支付后，超时未收到响应。

头寸不足：受理机构的正交易不足以支持退款或撤销。 原订单不支持撤销：微信主扫支付不支持撤销。

结算中心验签失败：受理机构向结算中心发起撤销或退款时，“结算中心签名”验证失败。 失败：结算中心处理请求失败。

7.错误码列表

错误代码(err_code)

错误码 SYSTEMERROR INVALID_TRANSACTIONID PARAM_ERROR ORDERPAID OUT_TRADE_NO_USED NOAUTH 错误描述 接口后台错误 无效 transaction_id 提交参数错误 订单已支付 商户订单号重复 商户无权限 支付 Y Y Y Y Y Y 查单 Y Y Y 关单 Y Y Y Y 退款 Y Y Y 退款 查询 Y Y Y 33

微信被扫支付接口文档（结算中心-受理机构）V0.0

NOTENOUGH NOTSUPORTCARD ORDERCLOSED BANKERROR REFUND_FEE_INVALID ORDERNOTEXIST

余额不足 不支持卡类型 订单已关闭 银行系统异常 微信公众号支付接口文档 （结算中心-受理机构）V0.0 Y Y Y Y 退款金额大于支付金额 订单不存在 Y Y Y Y Y

8.常见问题和注意事项

8.1.常见基本概念疑惑

（1） 还没拿到正式号，如何调试测试？

答：只有在“商户功能”审核通过以后，收到了微信和财付通的相关邮件，才可以进行开发。

（2） 支付授权目录如何使用？ 答：支付授权目录是支付功能正式上线后，商户后台发起支付请求的页面所在的目录。这个目录在注册填写时，需要精确到最细一级的目录，且在使用时，目录名称后直接加文件名，不可再增加 or 删减目录。

举例：发起请求的页面 url 为 http://pay.weixin.com/weixin/pay/payment.php?XXXXX，则 填写的目录应该为 http://pay.weixin.com/weixin/pay/。 （3） 支付测试目录和支付授权目录？

答：支付授权目录将会在产品上线审核时，以及上线后长期使用的正式目录。支付测试目录是提供给开发者，在开发测试期间使用的临时目录。这两个目录都是发起支付请求的页面文件所在的位置。

8.2.常见错误现象及解决方法

（1） 点击支付按钮，调用 JS API 没反应？

答：尝试发起支付的页面 url，不在支付授权目录下，请检查 url 与支付授权目录是否对

微信被扫支付接口文档（结算中心-受理机构）V0.0

34

微信公众号支付接口文档 （结算中心-受理机构）V0.0

应。

（2） 点击支付按钮，提示“access_not_allow” 答：参与测试人员的微信号没有在白名单中，将测试用户加入白名单。操作在 “mp.weixin.qq.com——微信支付——支付测试”。 （3） 点击支付按钮，提示“access_denied”

答：尝试发起支付的页面 url，不在支付授权目录下，请检查 url 与支付授权目录是否对应。

（4） 点击支付页面链接后，没有反应？

答：在开发调试阶段，测试链接需要在公众号内点击打开。操作方法可以是：白名单用 户在公众号内向公众号发一条消息，消息内容即为测试链接，然后点击打开。 （5） 点击支付按钮，提示“当前公众号没有权限支付本次交易”

答：请确认使用的 APPID 是否正确，确认在 MP 平台前三项审核结果均为“审核通过”。

（6） 点击支付按钮，提示“众账号支付使用了无效的商户号，无法发起该笔交易”

答：请检查是否使用了正确的商户号，确认 MP 平台前三项审核结果均为“审核通过”。

（7） 点击支付按钮，提示“该公众号支付签名无效，无法发起该笔交易”

答：调起支付的签名错误，请检查相关签名。

（8） 用户成功支付，点击“完成”，又再次跳转至输入密码页面，仍可支付并二次扣费

答：用户在商户的 H5 页面点击了两次“微信支付”，生成了两笔订单，需要在 H5 页面 微信支付按钮上增加防二次点击的机制。 （9） Notify url 无法接收通知

答：需要外网地址，直接打开 Notify url 正常，否则需要商户自己检查错误，同时注意 不要被防火墙拦截。

微信被扫支付接口文档（结算中心-受理机构）V0.0

35

微信公众号支付接口文档 （结算中心-受理机构）V0.0

8.3.常见注意事项

（1） 参数大小写问题

请留意文档中要求的字符大小写问题，如“md5运算后，字符串的字符要转换为大写”。

（2） 参数格式问题

所有传入参数，均为字符串类型，请注意文档中各处的具体要求。

（3） 时间戳问题

请使用 Linux 时间戳，注意为字符串格式。精确到秒，不需要到毫秒，即 10 位数字。

（4） 同一商户订单号支付问题

商户的 out trade no 必须全局唯一，调试和生产环境，都需要使用唯一的订单号。、 注意： 当商户的同一个商户号绑定了公众号支付、小额刷卡、APP 支付也需要加标识来区分， 不能出现重复。当发起支付返回失败时，一定要用原订单的 out trade no 而不能重新生 成新的订单号发起支付，避免同一单重复支付。

微信被扫支付接口文档（结算中心-受理机构）V0.0

36

本文来源：https://www.bwwdw.com/article/vih6.html