@ulodev
2018-07-03T10:05:11.000000Z
字数 19429
阅读 2002
优络服务接口文档-APP支付
支付 接口
1. 引言
1.1. 阅读对象
本文阅读对象：商户系统（在线购物平台、人工收银系统、自化智能收银系统 或其他）集成微信、支付 宝、QQ 钱包支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。
1.2. 业务术语
1、刷卡支付
请找商务索取最新文档。
2、扫码支付
请找商务索取最新文档。
3、公众号支付
请找商务索取最新文档。
4、WAP支付
请找商务索取最新文档。
5、APP 支付
APP 支付又称移动端支付，是商户通过在移动端应用 APP 中集成开放 SDK 调起微信支付模块完成支付的 模式。
6、支付宝支付
请找商务索取最新文档。
7、QQ 钱包支付
请找商务索取最新文档。
8、百度钱包支付
请找商务索取最新文档。
1.3. 支付账户
商户在优络支付平台(申请扫码支付、公众号支付)按照相应提示，申请相应支付模式. 工作人员审核资料无误后开通相应的支付模式，如：微信支付、支付宝支付、百度钱包、QQ 钱包支付等。申请审核通过后， 商户在申请资料填写的邮箱中收取到由优络支付平台发送的邮件，此邮件包含开发时需要使用的支付账户信息。
1.3.1. 服务账户参数说明
| 参数 | API 参数名 | 详细说明 |
| 服务商号 | provider_no | 服务商申请优络服务后，由服务平台分配的服务商号 |
| API 密钥 | key | 交易过程生成签名的密钥，不会在网络中传播。商户妥善保管该 Key， 切勿在网络中传输，不能在其他客户端中存储，保证 key 不会泄露 |
| 参数 | API 参数名 | 详细说明 |
| 商户号 | mch_id | 商户申请优络服务后，由服务平台分配的商户收款账号。 |
| API 密钥 | key | 交易过程生成签名的密钥，不会在网络中传播。商户妥善保管该 Key， 切勿在网络中传输，不能在其他客户端中存储，保证 key 不会泄露 |
1.3.2. 测试商户账户
注意：此账户为生产环境商户账户，接口需调用生产环境接口地址！
| 参数 | API 参数名 | 详细说明 |
| 商户号 | 26384580 | 商户申请优络服务后，由服务平台分配的商户收款账号。 |
| API 密钥 | fcc635d8880de1135581bf07fc23ca79 | 交易过程生成签名的密钥，不会在网络中传播。 |
| 金额 | 100 | 单位为分,1 元 |
1.4. APP支付Demo下载
- app端SDK下载
请参考微信官方APP支付Demo：微信APP支付SDK
2. APP 支付
2.1. 阅读对象
本文阅读对象：商户系统（在线购物平台、人工收银系统、自劢化智能收银系统 或其他）集成微信、支付 宝、QQ 钱包支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。
2.2. 场景介绍
适用于商户在移动端 APP 中集成微信支付功能。商户 APP 调用微信提供的 SDK调用微信支付模块，商户 APP 会跳转到微信中完成支付，支付完后跳回到商 户 APP 内，最后展示支付结果。目前微信支付支持手机系统有：IOS（苹果）、Android（安卓）和 WP（Windows Phone）。 交互细节如下：
步骤 1：用户迚入商户 APP，选择商品下单、确认购买，迚入支付环节。商户朋务后台生成支付订单，签名 后将数据传输到 APP 端。以微信提供的 DEMO 为例，见图 8.1。
步骤 2：用户点击后发起支付操作，迚入到微信界面，调起微信支付，出现确认支付界面，见图 8.2。
步骤 3：用户确认收款方和金额，点击立即支付后出现输入密码界面，可选择零钱 或银行卡支付见图 8.3。
步骤4：输入正确密码后，支付完成，用户端微信出现支付详情页面。见图 8.4。
步骤5：回跳到商户 APP 中，商户 APP 根据支付结果个性化展示订单处理结果。见8.5。
| 图 8.1 商户 APP 界面 | 图 8.2 跳转到微信支 | 图 8.3 用户确认支付 |
|---|---|---|
 |
 |
 |
| 图 8.4 支付成功提示页面 | 图 8.5 返回到商户 APP 提示 | |
 |
 |
2.3. APP端开发步骤
详细请参考：微信官方app开发步骤
3. 接口规则
3.1. 协议规则
| 传输方式 | 为保证交易安全性，采用HTTPS传输 |
| 提交方式 | 采用POST方法提交 |
| 数据格式 | 提交和返回数据都为XML格式，根节点名为xml |
| 字符编码 | 统一采用UTF-8字符编码 |
| 签名算法 | MD5，后续会兼容SHA1、SHA256、HMAC等。 |
| 签名要求 | 请求和接收数据均需要校验签名，详细方法请参考[安全规范-签名算法] |
| 证书要求 | 调用申请退款、撤销订单接口需要商户证书 |
| 判断逻辑 | 先判断协议字段返回，再判断业务返回，最后判断交易状态 |
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. 应用场景
商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易回话标识后再在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) | 是 | 商户号 |
| 服务商号 | provider_no | String(32) | 否 | 服务商可以替商户发起交易，所传商户号（mch_id）必须所属该服务商，签名的API 密钥（key）也要用对应的服务商的，不能用商户的API 密钥（key）。当服务商号为空时，签名用的API 密钥（key）应为商户的 |
| 商户应用id | sub_appid | String(32) | 否 | 微信分配的应用ID |
| 随机字符串 | 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.apppay，详见 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.apppay，详细说明见参数规定 |
| 预支付标识 | prepay_id | String(64) | 是 | 预支付会话标识，用于后续接口调用中使用，该值有效期 为 2 小时 |
| APP 签名包 | package_json | String(255) | 是 | 该参数为 JSON 格式，参数配置微信 SDK 拉起微信支付 |
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. APP 调起微信
4.2.1. APP 端开发步骤说明
参考微信官方文档：https://pay.weixin.qq.com/wiki/doc/api/app/app.php?chapter=8_5
统一支付接口 packge_json 返回的字段说明，用于传递给微信 SDK：
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 应用 ID | appId | String(32) | 是 | 微信开放平台実核通过的应用 APPID |
| 商户号 | partnerId | String(32) | 是 | 微信支付分配的商户号 |
| 预 支 付 交 易 会 话 ID | prepayId | String(32) | 是 | 微信返回的支付交易会话 ID |
| 扩展字段 | package | String(128) | 否 | 暂填写固定值 Sign=WXPay |
| 随机字符串 | nonceStr | String(32) | 否 | 随机字符串 |
| 时间戳 | timeStamp | String(10) | 是 | 时间戳 |
| 签名 | sign | String(32) | 是 | 签名 |
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) | 是 | 微信返回的随机字符串 |
| 交易类型 | 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) | 是 | 微信支付订单号/第三方单号 |
| 微信单号 | bank_no | 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) | 是 | 商户号 |
| 服务商号 | 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) | 是 | 商户号 |
| 交易类型 | 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) | 是 | 商户号 |
| 服务商号 | 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. 查询退款接口
4.6.1. 应用场景
提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，用零钱支付的退款 20 分钟内到账，银行
卡支付的退款 3 个工作日后重新查询退款状态。
4.6.2. 接口地址
测试环境地址：https://api.test.szulodev.com/pay/refundquery
生产环境地址：https://api.ulopay.com/pay/refundquery
特别提醒：服务商测试交易，请调用测试环境的地址,调试通过，没有问题后再使用正式服务商号和API密钥调生产环境地址，商户测试交易不受限制
4.6.3. 输入参数
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 商户号 | mch_id | String(32) | 是 | 商户号 |
| 服务商号 | 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.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(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.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_MET HOD | 请使用 post 方法 | 未使用 post 传递参数 | 请检查请求参数是否通过 post 方法提交 |
| SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算法要求 |
| XML_FORMAT_ERRO R | XML 格式错 | XML 格式错误 | 请检查 XML 参数格式是否正确 |
4.7. 下载账单接口
4.7.1. 应用场景
商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和平台侧数据不一致，通过对账单核对后可校正支付状态。
注意：
1、平台侧未成功下单的交易不会出现在对账单中。
2、平台在次日 10 点启动生成前一天的对账单，建议商户 11 点后再获取；
3、对账单中涉及金额的字段单位为“元”。
4、对账单接口只能下载三个月以内的账单。
3.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-商户（不传默认为商户，如果为服务商，签名时API密钥必须为服务商的） |
| 签名 | sign | String(32) | 是 | 签名，详见 签名生成算法 |
4.7.4. 返回结果
| 字段名 | 变量名 | 类型 | 必填 | 描述 |
| 返回状态码 | return_code | String(16) | 是 | SUCCESS/FAIL## 标题 ## 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断 |
| 返回信息 | return_msg | String(128) | 否 | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退 款结果一致，具体字段说明可查阅相应接口。
第一行为表头：
交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币 种类,总金额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品 名称, 商户数据包
从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘 1 左边键的字符，字段顺序不表 头一致。
倒数第二行为订单统计标题，最后一行为
统计数据 总交易单数,总交易额,总退款金额,总红包退款金额
示例如下：
交易时间,商户号,子商户号,设备号,平台单号,第三方单号,商户单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金 额,红包金额,平台退款单号,商户退款单号,退款金额,企业红包退款金额,退款类型,退款状态,商品名称,商户数据包
`2016-09-03 10:40:11,`15121009,`15121009,`,`1512100920160903109790993,`8012016090310243946534287,`20160903103949105714,`,`trade.weixin.apppay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,``2016-09-03 14:56:38,`15121009,`15121009,`,`1512100920160903149824853,`8012016090314245624846302,`20160903145628862401,`,`trade.weixin.apppay,`SUCCESS,`,`CNY,`0.01,`0,`,`,`0,`0,`,`,`测试购物,`总交易单数,总交易额,总退款金额,总红包退款金额`2,`0.02,`0.00,`0
4.7.5. 错误码
| 名称 | 描述 | 原因 | 解决方案 |
| SYSTEMERROR | 系统错误 | 后台系统返回错误 | 系统异常，请再调用发起查询 |
