优络服务接口文档-微信原生公众号支付

支付 接口

1. 引言

1.1. 阅读对象

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

2. 公众号支付

2.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）的触发不保证遵循严格的时序。JSAPI返回值作为触发商户网页跳转的标志，但商户后台应该只在收到微信后台的支付成功回调通知后，才做真正的支付成功的处理。

2.2. 业务流程

商户系统和微信支付系统主要交互：
1. 商户 server 调用统一下单接口请求订单，api 参见公共 api【统一下单 API】
2. 商户 server 接收支付通知，api 参见公共 api【支付结果通知 API】
3. 商户 server 查询支付结果，api 参见公共 api【查询订单 API】

2.3. 获取 openid

微信公众平台
      在关注者与公众号产生消息交互后，公众号可获得关注者的OpenID（加密后的微信号，每个用户对每个公 众号的 OpenID 是唯一的。对于不同公众号，同一用户的 openid 不同）。
      公众号可根据以下接口来获取用户的openid，如需获取用户的昵称、头像、性别、所在城市、语言和关注 时间，则需要用户授权。
参考信息：http://mp.weixin.qq.com/wiki/17/c0f37d5704f0b64713d5d2c37b468d75.html
      开发者如果需要将同一个用户在不同公众号下的openid统一为一个id来记录，可以参考以下接口：
参考信息：http://mp.weixin.qq.com/wiki/14/bb5031008f1494a59c6f71fa0f319c66.html

2.4. 支付账户

     商户在优络服务平台(申请扫码支付、公众号支付)按照相应提示，申请相应支付模式。工作人员审核资料 无误后开通相应的支付模式，如：微信支付、支付宝支付、百度钱包、QQ 钱包支付等。申请审核通过后，商户 在申请资料填写的邮箱中收取到由优络服务平台发送的邮件，此邮件包含开发时需要使用的支付账户信息

2.4.1. 服务账户参数说明

3. API 列表

3.1. 微信公众号支付接口

3.1.1 应用场景

    除被扫支付场景以外，商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易回 话标识后再按扫码、JSAPI、APP等不同场景生成交易串调起支付。

3.1.2. 接口地址

正式环境地址：https://api.ulopay.com/pay/unifiedorder

3.1.3. 输入参数

3.1.4. 返回结果

3.1.5. 错误码

注意:如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支付;如 果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态。

3.2. 前端页面回调

3.2.1. 应用场景

    支付完成后，微信公众账号页面会引导用户跳转至商户提交订单所填的 return_url 上；但是该不跳转不会 携带支付成功相关的信息，商户需要自行调用查询订单接口进行交易结果查询判断。

3.2.2. 请求参数

无

3.2.3. 返回参数

无

2.3. 支付结果通知

3.3.1. 应用场景

支付完成后，微信会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。对后台通知交互时，如果微信收到商户的应答不是成功或超时，微信认为通知失败，微信会通过一定的策略（如30分钟共8 次 ） 定期重新发起通知 ， 尽可能提高通知的成功率， 但 微信不保证通知最终能成功。（通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒）
注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如 果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数 据锁进行幵发控制，以避免函数重入造成的数据混乱。
特别提醒：商户系统对于支付结果通知的内容一定要做签名验证，防止数据泄漏导致出现“假通知”，造成资 金损失。
◆ POS 机器需要主动调用 POS 前置查询接口，查询支付最终结果。POS 机无法得到后台通知结果。

2.3.2. 通知参数

3.3.3. 返回参数

商户处理后同步返回给服务平台，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：

示例如下：

success

3.4. 查询订单接口

3.4.1. 应用场景

该接口提供所有支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。 需要调用查询接口的情况：
◆ 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；
◆ 调用支付接口后，返回系统错误或未知交易状态情况；
◆调用被扫支付 API，返回 USERPAYING 的状态；
◆ 调用关单或撤销接口API 之前，需确认支付状态；

3.4.2. 接口地址

正式环境地址：https://api.ulopay.com/pay/orderquery

3.4.3. 请求参数

3.4.4. 返回结果

3.4.5. 错误码

3.5. 申请退款接口

3.5.1. 应用场景

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，支付将在收到退款请求幵且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。

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

3.5.2. 接口地址

正式环境地址：https://api.ulopay.com/secapi/pay/refund

3.5.3. 输入参数

3.5.4. 返回结果

3.5.5. 错误码

3.6. 查询退款接口

3.6.1. 应用场景

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

3.6.2. 接口地址

正式环境地址：https://api.ulopay.com/secapi/pay/refund

3.6.3. 输入参数

3.6.4. 返回结果

3.6.5. 错误码

3.7. 下载账单接口

3.7.1. 应用场景

商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和平台侧数据不一致，通过对账单核对后可校正支付状态。
注意：
1、平台侧未成功下单的交易不会出现在对账单中。
2、平台在次日 10 点启动生成前一天的对账单，建议商户 11 点后再获取；
3、对账单中涉及金额的字段单位为“元”。
4、对账单接口只能下载三个月以内的账单。

3.7.2. 接口地址

正式环境地址：https://api.ulopay.com/pay/downloadbill

3.7.3. 请求参数

3.7.4. 返回结果

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

第一行为表头：
交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币 种类,总金额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品 名称, 商户数据包

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

倒数第二行为订单统计标题，最后一行为
统计数据 总交易单数,总交易额,总退款金额,总红包退款金额
示例如下：

交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金 额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品名称,商户数据包

`2016-09-03     10:40:11,`15121009,`15121009,`,`1512100920160903109790993,`8012016090310243946534287,`201609031039491
05714,`,`trade.weixin.jspay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,`
`2016-09-03     14:56:38,`15121009,`15121009,`,`1512100920160903149824853,`8012016090314245624846302,`201609031456288
62401,`,`trade.weixin.jspay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,`
总交易单数,总交易额,总退款金额,总红包退款金额
`2,`0.02,`0.00,`0

3.7.5. 错误码