公众号
取消
中文
中文
EN
取消
  • 公众号开发指南

    • # 微信非税缴费

    # 1 业务说明

    # 1.1 概念介绍

    非税收入：除税收以外，由各级政府、事业单位提供公共服务取得的财政性资金。例如：出入境、身份证等办证费用，交警、工商、物价等罚没收入，市政公园、国家景区旅游门票等。以广州为例，去年有1000万笔，超过1000亿的收入。2016年全国地方非税收入达到6万亿，中央非税收入达到4000亿。 收款模式：实行“收支双线”，一个单位原则上只能开立一个收入专户，一个支出专户。收入专户除财政划解外，只能收，不能支；支出专户除财政核拨支出外，只能支，不能收。单位不允许存在收入过渡户，应缴非税收入直接缴入相应的政府非税收入财政专户，在指定的代理银行开设财政专户，实行非税收入“单位开票、银行代收、实时入库(或专户)”。

    # 1.2 现状难题

    收款模式：现场办理完业务，要到另一个窗户去缴费，而且只接受刷卡，或者去银行缴费。线上绝大多数公共服务只能查询，无法缴费。或者即使实现办理，也要在办理完成后，去往其他公众号或者线下缴费。 信息交互：除了收款方式特殊外，由于需要业务信息交互，因此需要业务部门与银行对接，对于银行和业务部门而言成本非常高。 由于以上原因严重制约了公共服务领域服务办结能力的提升。

    # 1.3 解决问题

    我们将搭建一个非税平台，建立并简化各业务部门与财政、银行间非税支付的连接。将银行的非税账户接入微信支付后，建立灵活收入账户选择机制，建设标准化的信息传输API接口，便捷各业务部门的接入，解决限制公众平台服务闭环发展的核心问题。

    # 2 角色说明

    # 2.1 银行

    银行，主要是作为缴费渠道。用户缴费后，费用会划到银行的商户号下，同时非税平台会调用银行提供的接口通知订单的缴费状态。微信支付会定期（T+1）将费用结算到对应的银行账户。

    # 2.2 财政

    财政角色的主要任务是记录缴费单的状态。用户缴费后，非税平台会调用财政提供的接口通知缴费单的支付状态。所有缴费单的状态，以财政记录的状态为准。

    某些地区可能由银行代为实现财政角色的功能，如广东的部分地方财政，则是由建行代为收费和记录缴费单的状态。具体可以参考接入模式说明中的银行直连模式。

    # 2.3 委办局

    委办局（即业务方），可以调用非税平台提供的下单接口给用户下单。

    # 3 接入模式说明

    这一节简单介绍微信非税支付的三种接入模式，后面会对下面三种模式的信息流、接口内容做详细介绍（业务流程说明，其它场景特例说明，接口详细说明）。

    # 3.1 银行直连模式

    非税支付由银行过桥连接财政，打通信息流的模式。适用于当地财政不安排统筹接入，或当地财政开发资源不足的情况。

    银行直连模式非税支付前后台流程时序图

    # 3.2 财政直连模式

    非税支付与财政系统直连，打通信息流的模式。适用于当地财政统筹接入，且当地财政开发能力较强的情况。

    财政直连模式非税支付前后台流程时序图

    # 3.3 业务直连模式

    非税支付以业务单位的应收信息为准，过桥至财政系统，打通信息流。适用于本地业务单位与财政系统无直连的情况。

    业务直连模式非税支付前后台流程时序图

    # 4 账号及相关配置

    # 4.1 接入方需准备的信息

    # 4.1.1 公众号的 APPID和 APPSECRET

    1. 公众号的 APPID 和APPSECRET主要用于获取 access_token。关于access_token的使用最佳实践可参考getAccessToken
    2. 开发者需要提供公众号的APPID给微信非税支付的对接人配置接口权限。如果有测试环境和正式环境两个公众号，请分别提供。

    # 4.1.2 微信网页授权

    通过微信网页授权，公众号可以获取用户的openid。openid 是公众号下的用户唯一标识。

    1.设置网页授权回调域名

    1）在微信公众号请求用户网页授权之前，开发者需要先到公众平台官网中的“开发 - 接口权限 - 网页服务 - 网页账号 - 网页授权获取用户基本信息”的配置选项中，修改授权回调域名。请注意，这里填写的是域名（是一个字符串），而不是URL，因此请勿加 http:// 等协议头；

    2）授权回调域名配置规范为全域名，比如需要网页授权的域名为：www.qq.com，配置以后此域名下面的页面 "http://www.qq.com/music.html" 、 "http://www.qq.com/login.html" 都可以进行 OAuth2.0鉴权。但 "http://pay.qq.com" 、 "http://music.qq.com 、 "http://qq.com" 无法进行 OAuth2.0鉴权。

    2.网页授权的流程

    1）引导用户进入授权页面同意授权，获取code

    2）通过code换取网页授权access_token（与基础支持中的access_token不同）

    3）如果需要，开发者可以刷新网页授权access_token，避免过期

    4）通过网页授权access_token和openid获取用户基本信息（支持UnionID机制）

    关于微信网页授权的更多介绍，请见微信网页授权。

    # 4.1.3 支付结果通知接口

    支付结果通知接口用来接收缴费单的缴费状态。详细介绍请见支付结果通知一节。

    请开发者将测试环境和正式环境的支付通知接口分别提供给微信非税支付的对接人进行配置。

    # 4.1.4 查询应收信息接口

    承担银行/财政角色的开发需要提供一个应收信息的查询接口。详细介绍请见查询应收信息一节。

    请开发者将测试环境和正式环境的支付通知接口分别提供给微信非税支付的对接人进行配置。

    # 4.1.5 调用退款接口的 IP 地址

    微信非税支付提供的退款接口有IP限制，调用方需要提供自己的IP列表。

    请开发者将测试环境和正式环境的退款IP分别提供给微信非税支付的对接人进行配置。

    # 4.2 公共测试账号资源

    # 4.2.1 测试商户号

    微信非税支付公共的测试商户号是1900016021。

    测试的订单都是支付给这个商户号，可以通过此商户号下载对应的对账单。

    # 4.2.2 测试银行ID

    test_bank_id是微信非税支付的一个特殊测试银行ID。

    可以通过这个银行ID测试下单支付的流程，而不受支付结果通知接口和应收信息查询接口的影响。

    # 4.3 微信非税支付的出口IP

    微信非税支付调用支付接口通知接口和应收信息查询接口的出口 IP为：

    101.227.131.239
101.227.169.13
182.254.90.117
121.51.76.135
101.89.14.152
180.97.118.178
223.167.253.106
58.246.221.98
117.184.239.113
183.192.201.151

    请将以上IP加入防火墙白名单。

    # 5 业务流程说明

    目前，微信非税支付支持多种业务场景，具体可以参考支付下单接口的说明。下面主要以最常用的支付场景进行说明。

    # 5.1 整体模块架构


    业务方的前端页面向业务方的后台发起缴费请求。 业务方后台从自己搭建的`access_token`中控服务获取`access_token`。 业务方后台按照要求拼装请求参数，并使用`access_token`调用微信非税支付的 api。 `access_token`中控服务定时刷新`access_token`（如：1小时刷新一次）。 ### 5.2 下单支付时序图 微信非税支付目前支持多种支付方式以满足不同的支付场景需求。下面以最常用的JSAPI支付为例，对下单支付的时序进行介绍。其它支付场景的交互时序总体相差不大，主要在下单请求参数和下单返回参数有细微差别。
    下单支付时序图

    用户在业务方的页面或缴费单上确认订单（点击按钮或扫描二维码），业务方获取用户`open_id`，并发起下单请求， 微信非税支付查询缴费单信息后，执行下单操作，返回订单号和支付链接。 业务方将支付链接返回给前端（或直接HTTP302），打开支付链接。 用户在支付页面发起支付。 用户支付后，微信非税支付调用财政、银行、委办局的支付通知接口通知缴费单的支付结果。 在支付页面刷新支付结果（以财政的记录为准）。 ### 5.3 其它特例场景说明 #### 5.3.1 小程序非税支付 小程序场景下，需要通过调用方小程序的appId下单，接口会返回拉起非税支付小程序所需的参数（appId和path）。具体见支付下单接口的返回结果说明。

    小程序中调用wx.navigateToMiniProgram可以唤起非税支付小程序，具体文档可参见小程序API，其中appId和path为必传（支付下单接口会返回参数）

    wx.navigateToMiniProgram({
    appId: '',
    path: 'pages/index/index?id=123',
    success(res) {
        // 打开成功
    }
})

    用户支付或其他操作返回到调用方小程序，调用方可以通过orderId（下单接口会返回）调用查询订单接口确认订单的支付情况

    # 5.3.2 非微信浏览器上的 H5非税支付

    在非微信浏览器上打开的 H5 无法获取用户 openid，下单时openid 不用传，trade_type 传 MWEB。

    关于 H5 支付的几点问题：

    用户IP：必须保证下单传入的用户IP和最终发起微信支付的用户IP是一致的，建议在用户页面上调用此接口获取用户IP。否则会报错（如下图所示）。部分浏览器，如华为浏览器、UC浏览器会通过代理服务器访问互联网，每次请求IP可能会改变。


    Referer：发起微信支付的时候，会检查 Referer 参数，以确保请求是在合法的域名上发起的。正常浏览器一般会自动带上 Referer，如果出现这种错误，请自行抓包确认。 Referer的作用是，检查请求的来源。H5支付调用微信客户端时，会检查请求是否是从 https://mp.weixin.qq.com 这个域名发起的。所以，如果要在APP上使用H5支付，请针对域名为 https://mp.weixin.qq.com 的页面发起的请求设置 referer 为 https://mp.weixin.qq.com，同时设置一个可以标识 APP 的 User-Agent（用于支付完APP 回跳，下面会说明）。

    iOS Webview 设置 Referer，请参考本文。 Android Webview 设置 Referer，请参考本文。

    APP 的跳转：如果是从 APP 上发起 H5 支付，微信支付成功后，默认情况下可能不会跳回到原来的APP，而是回到默认浏览器。如果希望支付结束回到 APP，请在打开 Webview 设置一个能标识 APP 的 User-Agent，同时将 User-Agent 上能标识APP的关键字和 Url Scheme 提供给我们进行配置。支付结束后会根据 User-Agent 使用不同的 Url Scheme 进行跳转。

    如果不清楚 Url Scheme，可以参考这篇文章。
    Android Webview 设置 User-Agent，可以参考这篇文章。
    webview加载网页出现找不到网页net:err_unknown_url_scheme，解决方法请参考这篇文章。

    # 6 接口详细说明

    涉及的接口列表如下：

    接口名称英文名请求路径
    查询应收信息nontaxqueryfee/nontax/queryfee
    获取缴费订单列表nontaxgetorderlist/nontax/getorderlist
    获取缴费订单详情nontaxgetorder/nontax/getorder
    缴费订单退款nontaxrefund/nontax/refund
    缴费支付下单nontaxunifiedorder/nontax/unifiedorder
    模拟查询应收信息nontaxmockqueryfee/nontax/mockqueryfee
    模拟支付结果通知nontaxmocknotification/nontax/mocknotification
    提交刷卡支付nontaxmicropay/nontax/micropay
    通知不一致订单nontaxnotifyinconsistentorder/nontax/notifyinconsistentorder
    下载缴费对帐单nontaxdownloadbill/nontax/downloadbill

    # 7 常见问题

    7.1 支付中间页支付后显示状态为处理中

    回答：原因是支付结果通知财政还没有成功。具体通知情况可以通过查询订单api查看。

    7.2 下单时出现以下情况：

    回答：原因可能是下单openid与支付openid不一致。

    7.3 非税支付下单返回的订单多少时间内有效？ 回答：订单号10分钟有效期。

    7.4 调用AccessToken时，如何添加IP白名单？ 回答：登录微信公众平台，在页面的设置->安全中心->IP白名单 中添加。

    7.5 在调用非税文档中的API时，出现access_token无效等问题？ 回答：1、检查调用的access_token和获取时的access_token的appid是否一致。 2、检查调用的access_token是否过期，可参照缓存access_token的方法： https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140183

    7.6 下载对账单数据以什么文件格式返回？ 回答：以csv格式的文本返回。

    7.7 如何判断是否重复缴费？ 回答：判断是否重复缴费：缴费通知书编号+执收单位编码+行政区划代码唯一。

    7.8 退款周期多少日以内的交易可以退？ 回答：目前最长一年。

    7.9 pc场景调用支付接口的时候，openid应该怎么获取？ 回答：业务方可以出示二维码，用户扫码之后，打开业务方的网页，在网页里做微信网页授权，然后就可以拿到了openid。

    7.10 小程序场景下，支付成功为什么不通过前端API 返回订单状态？ 回答：很多触发返回调用方小程序的操作，不会触发API wx.navigateBackMiniProgram，所以使用该接口传递参数不可靠。