@ulodev
2018-07-03T10:04:24.000000Z
字数 19976
阅读 2691
优络服务接口文档-公众号支付
支付 接口
1. 引言
1.1. 阅读对象
本文阅读对象：商户系统（在线购物平台、人工收银系统、自动化智能收银系统或其他）集成微信、支付宝、QQ钱包支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。
1.2. 业务术语
1、刷卡支付
请找商务索取最新文档。
2、扫码支付
请找商务索取最新文档。
3、公众号支付
公众号支付是用户在微信中打开商户的 H5 页面，商户在 H5页面通过调用微信支付提供的 JSAPI 接口调起 微信支付模块完成支付。应用场景有：
◆用户在微信公众账号内进入商家公众号，打开某个主页面，完成支付
◆用户的好友在朋友圈、聊天窗口等分享商家页面连接，用户点击链接打开商家页面，完成支付
◆将商户页面转换成二维码，用户扫描二维码后在微信浏览器中打开页面后完成支付
4、APP 支付
请找商务索取最新文档。
5、支付宝支付
请找商务索取最新文档。
6、QQ 钱包支付
请找商务索取最新文档。
7、百度钱包支付
请找商务索取最新文档。
1.3. 支付账户
商户在优络服务平台(申请扫码支付、公众号支付)按照相应提示，申请相应支付模式。工作人员审核资料 无误后开通相应的支付模式，如：微信支付、支付宝支付、百度钱包、QQ 钱包支付等。申请审核通过后，商户 在申请资料填写的邮箱中收取到由华润银行服务平台发送的邮件，此邮件包含开发时需要使用的支付账户信息
1.3.1. 服务账户参数说明
| 参数 | API 参数名 | 详细说明 |
| 服务商号 | provider_no | 服务商申请优络服务后，由服务平台分配的服务商号 |
| API 密钥 | key | 交易过程生成签名的密钥，不会在网络中传播。商户妥善保管该 Key， 切勿在网络中传输，不能在其他客户端中存储，保证 key 不会泄露 |
| 参数 | API 参数名 | 详细说明 |
| 商户号 | mch_id | 商户申请优络服务后，由服务平台分配的商户收款账号。 |
| API 密钥 | key | 交易过程生成签名的密钥，不会在网络中传播。商户妥善保管该 Key， 切勿在网络中传输，不能在其他客户端中存储，保证 key 不会泄露 |
1.3.2. 测试服务商账户
注意：此账户为测试环境服务商账户，接口需调用测试环境接口地址！
| 参数 | API 参数名 | 详细说明 |
| 服务商号 | 26101575 | 服务商申请优络服务后，由服务平台分配的服务商号。 |
| API 密钥 | e4b7971ecf14704c78da71bea45af4fc | 交易过程生成签名的密钥，不会在网络中传播。 |
| 金额 | 100 | 单位为分,1 元 |
1.3.3. 测试商户账户
注意：此账户为生产环境商户账户，接口需调用生产环境接口地址！
| 参数 | API 参数名 | 详细说明 |
| 商户号 | 26384580 | 商户申请优络服务后，由服务平台分配的商户收款账号。 |
| API 密钥 | fcc635d8880de1135581bf07fc23ca79 | 交易过程生成签名的密钥，不会在网络中传播。 |
| 金额 | 100 | 单位为分,1 元 |
1.4. 公众号支付Demo下载
- Service端Demo下载
公众号支付Demo（java版）
公众号支付Demo（php版）
公众号支付Demo（c#版）
2. 公众号支付
2.1. 场景介绍
商户已有 H5 商城网站，用户通过消息或扫描二维码在微信内打开网页时，可以调用微信支付完成下单购买的流程。
 |
 |
| 图 7.1 商户自定义消息界面 | 图 7.2 商户网页下单 |
 |
 |
| 图 7.3 用户确认支付，输入密码 | 图 7.4 用户支付成功提示 |
 |
 |
| 图 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】
3. 接口规则
3.1. 协议规则
| 传输方式 | 为保证交易安全性，采用HTTPS传输 |
| 提交方式 | 采用POST方法提交 |
| 数据格式 | 提交和返回数据都为XML格式，根节点名为xml |
| 字符编码 | 统一采用UTF-8字符编码 |
| 签名算法 | MD5，后续会兼容SHA1、SHA256、HMAC等。 |
| 签名要求 | 请求和接收数据均需要校验签名，详细方法请参考[安全规范-签名算法] |
| 证书要求 | 调用申请退款、撤销订单接口需要商户证书 |
| 判断逻辑 | 为保证交易安全性，采用HTTPS传输 |
3.2. 参数规定
- 交易金额
交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。对账单中的交易金额单位为【元】。外币交易的支付金额精确到币种的最小单位，参数值不能带小数点。 - 交易类型
trade.weixin.jspay--微信公众号支付，调用统一下单接口
trade.weixin.native--微信扫码支付，调用统一下单接口
trade.weixin.apppay--微信APP支付，调用统一下单接口
trade.weixin.h5pay--微信WAP支付，调用统一下单接口
trade.weixin.micropay--微信刷卡支付，刷卡支付有单独的支付接口，不调用统一下单接口
trade.alipay.native--支付宝扫码支付，调用统一下单接口
trade.alipay.jspay--支付宝公众号支付，调用统一下单接口
trade.alipay.micropay–-支付宝小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
trade.qqpay.micropay--QQ钱包小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
trade.qqpay.native--QQ钱包扫码支付，调用统一下单接口
trade.qqpay.jspay--QQ钱包公众号支付，调用统一下单接口
trade.qqpay.wappay--QQ钱包WAP支付，调用统一下单接口
trade.baidu.native--百度扫码支付，调用统一下单接口 - 货币类型
货币类型的取值列表：
CNY：人民币 - 时间
标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时区先换算成标 准北京时间， 例如商户所在地为 0 时区的伦敦，当地时间为 2014 年 11 月 11 日 0 时 0 分0 秒，换算成北京时间为：2014 年 11 月 11 日 8 时 0 分 0 秒 - 时间戳
标准北京时间，时区为东八区，自 1970 年 1 月 1 日 0 点 0 分 0秒以来的秒数。注意：部分系统取到的值为毫秒 级，需要转换成秒(10 位数字)。 - 商户订单号
商户支付的订单号由商户自定义生成，要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单 号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过或已调用关单、撤销（请见后文的 API 列表）的订单号 不能重新发起支付。
3.3. 安全规范
- 签名算法
签名生成的通用步骤如下：
第一步，设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名 ASCII 码从 小到大排序（字典序），使用URL 键值对的格式（即 key1=value1&key2=value2…）拼接成字符串stringA。
特别注意以下重要规则：
◆ 参数名 ASCII 码从小到大排序（字典序）；
◆ 如果参数的值为空不参与签名；也就是说参数是空的不需要参与签名；
◆ 参数名区分大小写；
◆ 验证调用返回或主动通知签名时，传送的 sign 参数不参与签名，将生成的签名与该 sign 值作校验。
◆ 支付接口可能增加字段，验证签名时必须支持增加的扩展字段
- 生成随机数算法
支付API 接口协议中包含字段 nonce_str，主要保证签名不可预测。我们推荐生成随机数算法如下：调用 随机数函数生成，将得到的值转换为字符串。
例： 假设传送的参数如下
appid： wxd930ea5d5a258f4fmch_id： 10000100device_info： 1000 body
第一步：对参数按照 key=value 的格式，幵按照参数名ASCII 字典序排序如下：
stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
第二步：拼接API 密钥：
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
最终得到最终发送的数据：
<xml><appid>wxd930ea5d5a258f4f</appid><mch_id>10000100</mch_id><device_info>1000<device_info><body>test</body><nonce_str>ibuaiVcKdpRxkhJA</nonce_str><sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign><xml>
3.4. 数据格式
采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。
协议级错误返回：
<xml><return_code><![CDATA[FAIL]]></return_code><return_msg><![CDATA[404 Not Found]]></return_msg></xml>
正确返回数据：
<xml><bank_type><![CDATA[SPDB_CREDIT]]></bank_type><fee_type><![CDATA[CNY]]></fee_type><is_subscribe><![CDATA[Y]]></is_subscribe><mch_id><![CDATA[15121009]]></mch_id><openid><![CDATA[ozaUDwqSo51HvC0lw9CrL20KXlsQ]]></openid><out_trade_no><![CDATA[20150303398]]></out_trade_no><result_code><![CDATA[SUCCESS]]></result_code><return_code><![CDATA[SUCCESS]]></return_code><third_trans_id><![CDATA[1004970044201510081126012906]]></third_trans_id><time_end><![CDATA[20151008112037]]></time_end><total_fee><![CDATA[1]]></total_fee><trade_state><![CDATA[SUCCESS]]></trade_state><trade_type><![CDATA[trade.weixin.micropay]]></trade_type><transaction_id><![CDATA[1512100920150925000000010]]></transaction_id></xml>
业务级错误返回：
<xml><err_code><![CDATA[AUTHCODEEXPIRE]]></err_code><err_code_des><![CDATA[请扫描微信支付被扫条码/二维码]]></err_code_des><result_code><![CDATA[FAIL]]></result_code><return_code><![CDATA[SUCCESS]]></return_code></xml>
4. API 列表
4.1. 统一支付接口
4.1.1. 应用场景
除被扫支付场景以外，商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易回 话标识后再按扫码、JSAPI、APP等不同场景生成交易串调起支付。
4.1.2. 接口地址
测试环境地址：http://api.test.szulodev.com/pay/unifiedorder
生产环境地址：https://api.ulopay.com/pay/unifiedorder
特别提醒：服务商测试交易，请调用测试环境的地址,调试通过，没有问题后再使用正式服务商号和API密钥调生产环境地址，商户测试交易不受限制
4.1.3. 输入参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 商户号 | mch_id | String(32) | 是 | 商户号（服务商测试需传下属子商户号，如使用测试服务商号26101575，商户号可传26101576） |
| 服务商号 | provider_no | String(32) | 否 | 服务商可以替商户发起交易，所传商户号（mch_id）必须所属该服务商，签名的API 密钥（key）也要用对应的服务商的，不能用商户的API 密钥（key）。当服务商号为空时，签名用的API 密钥（key）应为商户的 |
| 随机字符串 | nonce_str | String(32) | 是 | 随机字符串，不长于32位 |
| 商品描述 | body | String(32) | 是 | 商品或支付单简要描述 |
| 商品详情 | detail | String(8192) | 否 | 详见如下说明 |
| 附加数据 | attach | String(127) | 否 | 详见如下说明 |
| 商户订单号 | out_trade_no | String(32) | 是 | 商户系统内部的订单号,32 个字符内、可包含字母,其他说 明见商户订单号 |
| 总金额 | total_fee | Int | 是 | 订单总金额，单位为分，只能为整数，详见 支付金额 |
| 货币类型 | fee_type | String(16) | 否 | 默认人民币：CNY，其他值列表详见 货币类型 |
| 终端 IP | spbill_create_ip | String(16) | 是 | 调用微信支付API的机器IP |
| 商品标记 | goods_tag | String(32) | 否 | 商品标记，代金券或立减优惠功能的参数 |
| 通知地址 | notify_url | String(256) | 是 | 接收支付结果异步通知回调地址，PC 网站必填，POS 机器扫码支付填写空字符串即可。示例：http://www.baidu.com/ |
| 页面回调地址 | return_url | String(256) | 是 | 收页面回调的地址，该地址不带支付结果参数，最终支付 结果需要调用查询接口进行获取 |
| 交易类型 | trade_type | String(32) | 是 | 取值：trade.weixin.jspay，详细说明见 3.2. 参数规定 |
| 指定支付方式 | limit_pay | String(32) | 否 | no_credit--指定不能使用信用卡支付 |
| 操作终端类型 | op_term_tp | String(8) | 否 | 取值：POS，WEB，PC |
| 操作终端编号 | op_term_no | String(32) | 否 | 终端设备号 |
| 操作门店编号 | op_shop_no | String(32) | 否 | 门店编号 |
| 操作员编号 | op_user_id | String(32) | 否 | 操作员帐号 |
| 签名 | sign | String(32) | 是 | 签名，详见 签名生成算法 |
4.1.4. 返回结果
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因:签名失败、参数格式校验错误 |
| 当return_code为SUCCESS的时候，还会包括以下字段： | ||||
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL |
| 业务结果 | result_code | String(16) | 是 | SUCCESS/FAIL |
| 错误代码 | err_code | String(32) | 否 | 详细参见错误列表 |
| 错误代码描述 | err_code_des | String(128) | 否 | 错误返回的信息描述 |
| 当return_code和result_code都为SUCCESS的时，还会包括以下字段： | ||||
| 商户号 | mch_id | String(32) | 是 | 商户号 |
| 签名 | sign | String(32) | 是 | 微信返回的签名，详见签名 签名生成算法 |
| 交易类型 | trade_type | String(32) | 是 | 取值：trade.weixin.jspay，详细说明见参数规定 |
| 预支付标识 | prepay_id | String(64) | 是 | 预支付会话标识，用于后续接口调用中使用，该值有效期为2小时 |
| 预支付 URL | prepay_url | String(255) | 是 | 在微信内访问此 URL 地址，进行付款 |
4.1.5. 错误码
注意:如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支付;如 果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态。
| 名称 | 描述 | 原因 | 解决方案 |
| NOAUTH | 商户无此接口权限 | 商户未开通此接口权限 | 请商户前往申请此接口权限 |
| NOTENOUGH | 余额不足 | 用户帐号余额不足 | 用户帐号余额不足，请用户充值或更换支付 卡后再支付 |
| ORDERPAID | 商户订单已支付 | 商户订单已支付，无需重复操作 | 商户订单已支付，无需更多操作 |
| ORDERCLOSED | 订单已关闭 | 当前订单已关闭，无法支 付 | 当前订单已关闭，请重新下单 |
| SYSTEMERROR | 系统错误 | 系统超时 | 系统异常，请用相同参数重新调用 |
| 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 是否匹配 |
| LACK_PARAMS | 缺少参数 | 缺少必要的请求参数 | 请检查参数是否齐全 |
| OUT_TRADE_NO_USE D | 商户订单号重复 | 同一笔交易不能多次提 交 | 请核实商户订单号是否重复提交 |
| SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算 法要求 |
| XML_FORMAT_ERROR | XML 格式错误 | XML 格式错误 | 请检查 XML 参数格式是否正确 |
| REQUIRE_POST_METH OD | 请使用 post 方法 | 未使用 post 传递参数 | 请检查请求参数是否通过 post 方法提交 |
| POST_DATA_EMPTY | post 数据为空 | post 数据不能为空 | 请检查 post 数据是否为空 |
| NOT_UTF8 | 编码格式错误 | 未使用指定编码格式 | 请使用 NOT_UTF8 编码格式 |
4.2. 前端页面回调
4.2.1. 应用场景
支付完成后，微信公众账号页面会引导用户跳转至商户提交订单所填的 return_url 上；但是该不跳转不会 携带支付成功相关的信息，商户需要自行调用查询订单接口进行交易结果查询判断。
4.2.2. 请求参数
无
4.2.3. 返回参数
无
4.3 支付结果通知
4.3.1. 应用场景
支付完成后，微信会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。对后台通知交互时，如果微信收到商户的应答不是成功或超时，微信认为通知失败，微信会通过一定的策略（如30分钟共8 次 ） 定期重新发起通知 ， 尽可能提高通知的成功率， 但 微信不保证通知最终能成功。（通知频率为15/15/30/180/1800/1800/1800/1800/3600，单位：秒）
注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如 果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数 据锁进行幵发控制，以避免函数重入造成的数据混乱。
特别提醒：商户系统对于支付结果通知的内容一定要做签名验证，防止数据泄漏导致出现“假通知”，造成资 金损失。
◆ POS 机器需要主动调用 POS 前置查询接口，查询支付最终结果。POS 机无法得到后台通知结果。
4.3.2. 通知参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL,此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因 签名失败参数格式校验错误 |
| 以下字段在return_code为SUCCESS的时候有返回 | ||||
| 业务结果 | result_code | String(16) | 是 | SUCCESS/FAIL |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL |
| 错误代码 | err_code | String(32) | 否 | 详细参见错误列表 |
| 错误代码描述 | err_code_des | String(128) | 否 | 错误返回的信息描述 |
| 以下字段在return_code和result_code都为SUCCESS的时候有返回 | ||||
| 商户号 | mch_id | String(16) | 是 | 调用接口提交的商户号 |
| 随机字符串 | nonce_str | String(16) | 是 | 微信返回的随机字符串 |
| 用户标识 | openid | String(128) | 是 | 用户在商户appid下的唯一标识 |
| 微信appid | appid | String(32) | 是 | 公众号标识 |
| 是否关注公众账号 | is_subscribe | String(1) | 否 | 用户是否关注公众账号，Y-关注，N-未关注，仅在公众 账号类型支付有效 |
| 用户子标识 | sub_openid | String(128) | 否 | 用户在子商户 appid 下的唯一标识 |
| 是否关注子公 众账号 | sub_is_subscribe | String(1) | 否 | 用户是否关注子公众账号，Y-关注，N-未关注，仅在公 众账号类型支付有效 |
| 交易类型 | trade_type | String(16) | 是 | 调用接口提交的交易类型，取值详细说明见 参数规定 |
| 付款银行 | bank_type | String(16) | 是 | 银行类型，采用字符串类型的银行标识 |
| 总金额 | total_fee | Int | 是 | 订单总金额，单位为分 |
| 货币种类 | fee_type | String(8) | 否 | 货币类型，符合 ISO 4217 标准的三位字母代码，默 认人民币：CNY，其他值列表详见 货币类型 |
| 现金支付金额 | cash_fee | Int | 是 | 现金支付金额订单现金支付金额，详见 支付金额 |
| 现金支付货币 类型 | cash_fee_type | String(16) | 否 | 货币类型，符合 ISO 4217 标准的三位字母代码，默 认人民币：CNY，其他值列表详见 货币类型 |
| 代金券或立减 优惠金额 | coupon_fee | Int | 否 | “代金券或立减优惠”金额<=订单总金额， 订单总金额-“代金券或立减优惠”金额=现金支付金额，详见 代金券或立减优惠 |
| 代金券或立减 优惠使用数量 | coupon_count | Int | 否 | 代金券或立减优惠使用数量 |
| 代金券或立减 优惠批次 ID | coupon_batch_id_$n | String(20) | 否 | 代金券或立减优惠批次ID,$n为下标，从0开始编号 |
| 代金券或立减 | coupon_id_$n | String(20) | 否 | 代金券或立减优惠ID,$n为下标，从0开始编号 |
| 优惠 ID | ||||
| 单个代金券或 立减优惠支付 金额 | coupon_fee_$n | Int | 否 | 单个代金券或立减优惠支付金额, $n 为下标，从 0 开 始编号 |
| 平台支付订单 号 | transaction_id | String(32) | 是 | 平台支付订单号 |
| 微信支付订单 号 | third_trans_id | String(32) | 是 | 微信支付订单号 |
| 商户订单号 | out_trade_no | String(32) | 是 | 商户系统的订单号，不请求一致。 |
| 附加数据 | attach | String(128) | 否 | 附加数据，原样返回 |
| 支付完成时间 | time_end | String(14) | 是 | 订单支付时间，格式为 yyyyMMddHHmmss，如 2009 年 12 月 25 日 9 点 10 分 10秒表示为20091225091010。其他详见时间规则 |
4.3.3. 返回参数
商户处理后同步返回给服务平台，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：
| 返回结果 | 结果说明 |
| success | 处理成功，服务平台系统收到此结果后不再进行后续通知 |
| fail 或其它字符 | 处理不成功，服务平台系统收到此结果或者没有收到任何结果，系统通过补单机制再次通知 |
示例如下：
success
4.4. 查询订单接口
4.4.1. 应用场景
该接口提供所有支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。 需要调用查询接口的情况：
◆ 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；
◆ 调用支付接口后，返回系统错误或未知交易状态情况；
◆调用被扫支付 API，返回 USERPAYING 的状态；
◆ 调用关单或撤销接口API 之前，需确认支付状态；
4.4.2. 接口地址
测试环境地址：http://api.test.szulodev.com/pay/orderquery
生产环境地址：https://api.ulopay.com/pay/orderquery
特别提醒：服务商测试交易，请调用测试环境的地址,调试通过，没有问题后再使用正式服务商号和API密钥调生产环境地址，商户测试交易不受限制
4.4.3. 请求参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 商户号 | mch_id | String(32) | 是 | 商户号（服务商测试需传下属子商户号，如使用测试服务商号26101575，商户号可传26101576） |
| 服务商号 | provider_no | String(32) | 否 | 服务商可以替商户发起交易，所传商户号（mch_id）必须所属该服务商，签名的API 密钥（key）也要用对应的服务商的，不能用商户的API 密钥（key）。当服务商号为空时，签名用的API 密钥（key）应为商户的 |
| 平台订单号 | transaction_ id | String(32) | 二选 一 | 平台订单号 |
| 商户订单号 | out_trade_no | String(32) | 商户系统内部的订单号，当没提供 transaction_id 时需 要传这个。 | |
| 随机字符串 | nonce_str | String(32) | 是 | 随机字符串，不长于 32 位。推荐 随机数生成算法 |
| 操作终端类型 | op_term_tp | String(8) | 否 | 取值：POS，WEB，PC |
| 操作终端编号 | op_term_no | String(32) | 否 | 终端设备号 |
| 操作门店编号 | op_shop_no | String(32) | 否 | 门店编号 |
| 操作员编号 | op_user_id | String(32) | 否 | 操作员帐号 |
| 签名 | sign | String(32) | 是 | 签名，详见 签名生成算法 |
4.4.4. 返回结果
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因签名失败参数格式校验错误 |
| 以下字段在return_code为SUCCESS的时候有返回 | ||||
| 业务结果 | result_code | String(16) | 是 | SUCCESS/FAIL |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL |
| 错误代码 | err_code | String(32) | 否 | 详细参见错误列表 |
| 错误代码描述 | err_code_des | String(128) | 否 | 错误返回的信息描述 |
| 以下字段在return_code 和 result 都为SUCCESS的时候有返回 | ||||
| 商户号 | mch_id | String(32) | 是 | 商户号 |
| 用户标识 | openid | String(128) | 是 | 用户在商户 appid 下的唯一标识 |
| 是否关注公众 账号 | is_subscribe | String(1) | 否 | 用户是否关注公众账号，Y-关注，N-未关注，仅在公众 账号类型支付有效 |
| 用户子标识 | sub_openid | String(128) | 否 | 用户在子商户 appid 下的唯一标识 |
| 是否关注子公 众账号 | sub_is_subscribe | String(1) | 否 | 用户是否关注子公众账号，Y-关注，N-未关注，仅在公 众账号类型支付有效 |
| 交易类型 | trade_type | String(16) | 是 | 调用接口提交的交易类型，取值详细说明见 参数规定 |
| 交易状态 | trade_state | String(32) | 是 | SUCCESS—支付成功 REFUND—转入退款 NOTPAY—未支付 CLOSED—已关闭 REVOKED—已撤销（刷卡支付） USERPAYING--用户支付中 PAYERROR--支付失败(其他原因，如银行返回失败) |
| 付款银行 | bank_type | String(16) | 是 | 银行类型，采用字符串类型的银行标识 |
| 总金额 | total_fee | Int | 是 | 订单总金额，单位为分 |
| 货币种类 | fee_type | String(8) | 否 | 货币类型，符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见 货币类型 |
| 现金支付金额 | cash_fee | Int | 是 | 现金支付金额订单现金支付金额，详见 支付金额 |
| 现金支付货币 类型 | cash_fee_type | String(16) | 否 | 货币类型，符合 ISO 4217 标准的三位字母代码，默 认人民币：CNY，其他值列表详见 货币类型 |
| 代金券或立减 优惠金额 | coupon_fee | Int | 否 | “代金券或立减优惠”金额<=订单总金额， 订单总金额-“代金券或立减优惠”金额=现金支付金额，详见 代金券或立减优惠 |
| 代金券或立减 优惠使用数量 | coupon_count | Int | 否 | 代金券或立减优惠使用数量 |
| 代金券或立减 优惠批次 ID | coupon_batch_i d_$n | String(20) | 否 | 代金券或立减优惠批次 ID ,$n 为下标，从 0 开始编号 |
| 代金券或立减 优惠 ID | coupon_id_$n | String(20) | 否 | 代金券或立减优惠 ID, $n 为下标，从 0 开始编号 |
| 单个代金券或 立减优惠支付 金额 | coupon_fee_$n | Int | 否 | 单个代金券或立减优惠支付金额, $n 为下标，从 0 开 始编号 |
| 平台支付订单 号 | transaction_id | String(32) | 是 | 平台支付订单号 |
| 微信支付订单 号 | third_trans_id | String(32) | 是 | 微信支付订单号 |
| 商户订单号 | out_trade_no | String(32) | 是 | 商户系统的订单号，不请求一致。 |
| 附加数据 | attach | String(128) | 否 | 附加数据，原样返回 |
| 支付完成时间 | time_end | String(14) | 是 | 订单支付时间，格式为 yyyyMMddHHmmss，如 200 9 年 12 月 25 日 9 点 10 分 10 秒表示为 20091225091 010。其他详见时间规则 |
| 交易状态描述 | trade_state_des c | String(256) | 否 | 对当前查询订单状态的描述和下一步操作的指引 |
4.4.5. 错误码
| 名称 | 描述 | 原因 | 解决方案 |
| ORDERNOTEXIST | 此交易订单号 不存在 | 查询系统中不存 在此交易订单号 | 该 API 只能查提交支付交易返回成功的订单，请商户检查需要查询的订 单号是否正确 |
| SYSTEMER ROR | 系统错误 | 后台系统返回错误 | 系统异常，请再调用发起查询 |
4.5. 申请退款接口
4.5.1. 应用场景
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，支付将在收到退款请求幵且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。
注意：退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。 一笔退款失败后重新提交，要采用原来的退款单号。总退款金额不能超过用户实际支付金额。
4.5.2. 接口地址
测试环境地址：http://api.test.szulodev.com/secapi/pay/refund
生产环境地址：https://api.ulopay.com/secapi/pay/refund
特别提醒：服务商测试交易，请调用测试环境的地址,调试通过，没有问题后再使用正式服务商号和API密钥调生产环境地址，商户测试交易不受限制
4.5.3. 输入参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 商户号 | mch_id | String(32) | 是 | 商户号（服务商测试需传下属子商户号，如使用测试服务商号26101575，商户号可传26101576） |
| 服务商号 | provider_no | String(32) | 否 | 服务商可以替商户发起交易，所传商户号（mch_id）必须所属该服务商，签名的API 密钥（key）也要用对应的服务商的，不能用商户的API 密钥（key）。当服务商号为空时，签名用的API 密钥（key）应为商户的 |
| 随机字符串 | nonce_str | String(32) | 是 | 随机字符串，不长于 32 位。推荐 随机数生成算法 |
| 平台订单号 | transaction_id | String(28) | 二选一 | 平台生成的订单号，在支付通知中有返回 |
| 商户订单号 | out_trade_no | String(32) | 商户的订单号 | |
| 商户退款单号 | out_refund_no | String(32) | 是 | 商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔 |
| 总金额 | total_fee | Int | 是 | 订单总金额，单位为分，只能为整数，详见 支付金额 |
| 退款金额 | refund_fee | Int | 是 | 退款总金额，订单总金额，单位为分，只能为整数，详见 支付金额 |
| 货币种类 | refund_fee_typ e | String(8) | 否 | 货币类型，符合 ISO 4217 标准的三位字母代码，默认人 民币：CNY，其他值列表详见 货币类型 |
| 操作终端类型 | op_term_tp | String(8) | 否 | 取值：POS，WEB，PC |
| 操作终端编号 | op_term_no | String(32) | 否 | 终端设备号 |
| 操作门店编号 | op_shop_no | String(32) | 否 | 门店编号 |
| 操作员编号 | op_user_id | String(32) | 否 | 操作员帐号 |
| 签名 | sign | String(32) | 是 | 签名，详见 签名生成算法 |
4.5.4. 返回结果
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
| 以下字段在return_code为SUCCESS的时候有返回 | ||||
| 业务结果 | result_code | String(16) | 是 | SUCCESS/FAIL |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL |
| 错误代码 | err_code | String(32) | 否 | 详细参见错误列表 |
| 错误代码描述 | err_code_des | String(128) | 否 | 错误返回的信息描述 |
| 当 return_code和result_code 都为SUCCESS的时，还会包括以下字段： | ||||
| 商户号 | mch_id | String(32) | 是 | 商户号 |
| 平台订单号 | transaction_id | String(28) | 是 | 平台订单号 |
| 微信订单号 | third_trans_id | String(28) | 是 | 微信订单号 |
| 商户订单号 | out_trade_no | String(32) | 是 | 商户系统内部的订单号 |
| 商户退款单号 | out_refund_no | String(32) | 是 | 商户退款单号 |
| 平台退款单号 | refund_id | String(28) | 是 | 平台退款单号 |
| 微信退款单号 | third_refund_id | String(28) | 是 | 微信退款单号 |
| 退款渠道 | refund_channel | String(16) | 否 | ORIGINAL—原路退款 BALANCE—退回到余额 |
| 退款金额 | refund_fee | Int | 是 | 退款总金额,单位为分,可以做部分退款 |
| 订单总金额 | total_fee | Int | 是 | 订单总金额，单位为分，只能为整数，详见 支付金额 |
| 订单金额货币 种类 | fee_type | String(8) | 否 | 订单金额货币类型，符合 ISO 4217 标准的三位字母代码， 默认人民币：CNY，其他值列表详见 货币类型 |
| 现金支付金额 | cash_fee | Int | 否 | 现金支付金额，单位为分，只能为整数，详见 支付金额 |
| 现金退款金额 | cash_refund_fee | Int | 否 | 现金退款金额，单位为分，只能为整数，详见 支付金额 |
| 代金券或立减 优惠退款金额 | coupon_refund_f ee | Int | 否 | 代金券或立减优惠退款金额=订单金额-现金退款金额，注 意：立减优惠金额不会退回 |
| 代金券或立减 优惠使用数量 | coupon_refund_ count | Int | 否 | 代金券或立减优惠使用数量 |
| 代金券或立减 优惠 ID | coupon_refund_i d | String(20) | 否 | 代金券或立减优惠 ID |
4.5.5. 错误码
| 名称 | 描述 | 原因 | 解决方案 |
| SYSTEMERROR | 接口返回错误 | 系统超时 | 请用相同参数再次调用 API |
| INVALID_TRANSACTI ONID | 无效 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_METH OD | 请使用 post 方法 | 未使用 post 传递参 数 | 请检查请求参数是否通过 post 方法提交 |
| SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算法要求 |
| XML_FORMAT_ERROR | XML 格式错误 | XML 格式错误 | 请检查 XML 参数格式是否正确 |
4.6. 查询退款接口
应用场景
提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，用零钱支付的退款 20 分钟内到账，银行
卡支付的退款 3 个工作日后重新查询退款状态。
4.6.1. 接口地址
测试环境地址：https://api.test.szulodev.com/pay/refundquery
生产环境地址：https://api.ulopay.com/pay/refundquery
特别提醒：服务商测试交易，请调用测试环境的地址,调试通过，没有问题后再使用正式服务商号和API密钥调生产环境地址，商户测试交易不受限制
4.6.2. 输入参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 商户号 | mch_id | String(32) | 是 | 商户号（服务商测试需传下属子商户号，如使用测试服务商号26101575，商户号可传26101576） |
| 服务商号 | provider_no | String(32) | 否 | 服务商可以替商户发起交易，所传商户号（mch_id）必须所属该服务商，签名的API 密钥（key）也要用对应的服务商的，不能用商户的API 密钥（key）。当服务商号为空时，签名用的API 密钥（key）应为商户的 |
| 随机字符串 | nonce_str | String(32) | 是 | 随机字符串，不长于 32 位。推荐 随机数生成算法 |
| 签名 | sign | String(32) | 是 | 签名，详见 签名生成算法 |
| 操作终端类型 | op_term_tp | String(8) | 否 | 取值：POS，WEB，PC |
| 操作终端编号 | op_term_no | String(32) | 否 | 终端设备号 |
| 操作门店编号 | op_shop_no | String(32) | 否 | 门店编号 |
| 操作员编号 | op_user_id | String(32) | 否 | 操作员帐号 |
| 平台订单号 | transaction_id | String(28) | 四 选 一 | 平台订单号 |
| 商户订单号 | out_trade_no | String(32) | 商户系统内部的订单号 | |
| 商户退款单号 | out_refund_no | String(32) | 商户退款单号 | |
| 平台退款单号 | refund_id | String(28) | 微信生成的退款单号，在申请退款接口有返回 |
4.6.3. 返回结果
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
| 以下字段在 return_code 为 SUCCESS 的时候有返回 | ||||
| 业务结果 | result_code | String(16) | 是 | SUCCESS/FAIL |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL |
| 错误代码 | err_code | String(32) | 否 | 详细参见错误列表 |
| 错误代码描述 | err_code_des | String(128) | 否 | 错误返回的信息描述 |
| 当return_code和 result_code 都为 SUCCESS 的时，还会包括以下字段： | ||||
| 商户号 | mch_id | String(32) | 是 | 商户号 |
| 平台订单号 | transaction_id | String(32) | 是 | 平台订单号 |
| 微信订单号 | third_trans_id | String(32) | 是 | 微信订单号 |
| 商户订单号 | out_trade_no | String(32) | 是 | 商户系统内部的订单号 |
| 订单总金额 | total_fee | Int | 是 | 订单总金额，单位为分，只能为整数，详见 支付金额 |
| 订单金额货币 种类 | fee_type | String(8) | 否 | 订单金额货币类型，符合 ISO 4217 标准的三位字母代码， 默认人民币：CNY，其他值列表详见 货币类型 |
| 现金支付金额 | cash_fee | Int | 是 | 现金支付金额，单位为分，只能为整数，详见 支付金额 |
| 退款笔数 | refund_count | Int | 是 | 退款记录数 |
| 商户退款单号 | out_refund_no _$n | String(32) | 是 | 商户退款单号 |
| 平台退款单号 | refund_id_$n | String(28) | 是 | 平台退款单号 |
| 退款渠道 | refund_channel _$n | String(16) | 否 | ORIGINAL—原路退款 BALANCE—退回到余额 |
| 退款金额 | refund_fee_$n | Int | 是 | 退款总金额,单位为分,可以做部分退款 |
| 代金券或立减 优惠退款金额 | coupon_refund _fee_$n | Int | 否 | 代金券或立减优惠退款金额<=退款金额，退款金额-代金 券或立减优惠退款金额为现金，说明详见 代金券或立减优惠 |
| 代金券或立减 优惠使用数量 | coupon_refund _count_$n | Int | 否 | 代金券或立减优惠使用数量 ,$n 为下标,从 0 开始编号 |
| 代金券或立减 优惠批次 ID | coupon_refund _ batch_ id_$n_ $m | String(20) | 否 | 批次 ID ,$n 为下标，$m 为下标，从 0 开始编号 |
| 代金券或立减 优惠 ID | coupon_refund _id_$n_$m | String(20) | 否 | 代金券或立减优惠 ID, $n 为下标，$m 为下标，从 0 开 始编号 |
| 单个代金券 或 立减优惠支付 金额 | coupon_refund _fee_$n_$m | Int | 否 | 单个代金券或立减优惠支付金额, $n 为下标，$m 为下标， 从 0 开始编号 |
| 退款状态 | refund_status_$n | String(16) | 是 | 退款状态： SUCCESS—退款成功 FAIL—退款失败 PROCESSING—退款处理中 NOTSURE—未确定，需要商户原退款单号重新发起 CHANGE—转入代发，退款到银行发现用户的卡作废或者冻结 了，导致原路退款银行卡失败，资金回流到商户的现金帐 号，需要商户人工干预，通过线下或者财付通转账的方式进 行退款。 |
4.6.4. 错误码
| 名称 | 描述 | 原因 | 解决方案 |
| SYSTEMERROR | 接口返回错误 | 系统超时 | 请尝试再次掉调用 API。 |
| INVALID_TRANSACTI ONID | 无效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_MET HOD | 请使用 post 方法 | 未使用 post 传递参数 | 请检查请求参数是否通过 post 方法提交 |
| SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算法要求 |
| XML_FORMAT_ERRO R | XML 格式错 | XML 格式错误 | 请检查 XML 参数格式是否正确 |
4.7. 下载账单接口
4.7.1. 应用场景
商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和平台侧数据不一致，通过对账单核对后可校正支付状态。
注意：
1、平台侧未成功下单的交易不会出现在对账单中。
2、平台在次日 10 点启动生成前一天的对账单，建议商户 11 点后再获取；
3、对账单中涉及金额的字段单位为“元”。
4、对账单接口只能下载三个月以内的账单。
4.7.2. 接口地址
测试环境地址：http://api.test.szulodev.com/pay/downloadbill
生产环境地址：https://api.ulopay.com/pay/downloadbill
4.7.3. 请求参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 商户号 | mch_id | String(32) | 是 | 当bill_type为“1”时，mch_id传服务商号，为“2”时传商户号 |
| 随机字符串 | nonce_str | String(32) | 是 | 随机字符串，不长于 32 位。推荐 随机数生成算法 |
| 对账单日期 | bill_date | String(8) | 是 | 下载对账单的日期，格式：20140603 |
| 商户类型 | bill_type | String(2) | 否 | 1-服务商 2-商户（不传默认为商户） |
| 签名 | sign | String(32) | 是 | 签名，详见 签名生成算法 |
4.7.4. 返回结果
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | FAIL（失败）,成功时，数据以文本表格的方式返回 result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退 款结果一致，具体字段说明可查阅相应接口。
第一行为表头：
交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币 种类,总金额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品 名称, 商户数据包
从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘 1 左边键的字符，字段顺序不表 头一致。
倒数第二行为订单统计标题，最后一行为
统计数据 总交易单数,总交易额,总退款金额,总红包退款金额
示例如下：
交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金 额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品名称,商户数据包
`2016-09-03 10:40:11,`15121009,`15121009,`,`1512100920160903109790993,`8012016090310243946534287,`20160903103949105714,`,`trade.weixin.jspay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,``2016-09-03 14:56:38,`15121009,`15121009,`,`1512100920160903149824853,`8012016090314245624846302,`20160903145628862401,`,`trade.weixin.jspay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,`总交易单数,总交易额,总退款金额,总红包退款金额`2,`0.02,`0.00,`0
4.7.5. 错误码
| 名称 | 描述 | 原因 | 解决方案 |
| SYSTEMERROR | 系统错误 | 后台系统返回错误 | 系统异常，请再调用发起查询 |
