[关闭]
@ulodev 2017-06-13T07:55:27.000000Z 字数 32824 阅读 2400

POS内部接口

列表项

支付 接口

引言

阅读对象

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

业务术语

1.刷卡支付

刷卡支付是用户展示微信钱包内的“刷卡条码/二维码”给商户系统扫描后直接完成支付的模式。主要应用线下面对面收银的场景。

2.扫码支付

扫码支付是商户系统生成支付二维码,用户再用微信、支付宝、QQ钱包“扫一扫”完成支付的模式。该模式适用于 PC 网站支付、实体店单品或订单支付、媒体广告支付等场景。

3.公众号支付

公众号支付是用户在微信中打开商户的 H5 页面,商户在 H5 页面通过调用微信支付提供的 JSAPI 接口调起微信支付模块完成支付。应用场景有:
◆ 用户在微信公众败号内进入商家公众号,打开某个主页面,完成支付
◆ 用户的好友在朊友圈、聊天窗口等分享商家页面连接,用户点击链接打开商家页面,完成支付
◆ 将商户页面转换成二维码,用户扫描二维码后在微信浏览器中打开页面后完成支付

4、APP 支付

APP 支付又称移动端支付,是商户通过在移动端应用 APP 中集成开放 SDK 调起微信支付模块完成支付的
模式。

5、支付宝支付

请找商务索取最新文档。

6、QQ 钱包支付

请找商务索取最新文档。

7、百度钱包支付

请找商务索取最新文档。

支付账户

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

表 3.1 账户参数说明

参数 API 参数名 详细说明
商户号 mch_id 商户申请优络支付后,由支付平台分配的商户收款账号。
API 密钥 key 交易过程生成签名的密钥,不会在网络中传播.商户妥善保管该 Key,切勿在网络中传输,不能在其他客户端中存储,保证key不会被泄漏。

测试支付账户:

参数 示例 详细说明
商户号 26104515 商户申请优络支付后,由支付平台分配的商户收款账号。
API 密钥 d014da1ab33d8f3ddfaf7e5a81724f1a 交易过程生成签名的密钥,不会在网络中传播。
金额 100 单位为分,1 元

刷卡支付

场景介绍

步骤 1:用户选择刷卡支付付款并打开微信,进入“我” ->“钱包” ->“刷卡”条码界面;
步骤 2:收银员在商户系统操作生成支付订单,用户确认支付金额;
步骤 3:商户收银员用扫码设备扫描用户的条码/二维码,商户收银系统提交支付;
步骤 4:微信支付后台系统收到支付请求,根据验证密码规则判断是否验证用户的支付密码,不需要验证密码的交易直接发起扣款,需要验证密码的交易会弹出密码输入框。支付成功后微信端会弹出成功页面,支付失败会弹出错误提示。

1.png-42.4kB 2.png-45.6kB
我的钱包 刷卡界面
1.png-42.4kB 2.png-45.6kB
输入密码,确认支付 支付成功后页面提示

支付验证密码规则

案例介绍

目前已上线刷卡支付案例,商户可自行前往店里实际体验。
便利店:711 便利店、国大 36524、好邻居等连锁药店:老百姓大药房、国大药房、海王星辰等
超市:天虹等
根据商户具体的情况,刷卡支付接入模式可分为:商户后台接入和门店接入;
根据用户是否需要输入支付密码可分为:免密模式和验密模式

接入模式-商户后台接入

该模式适合具备统一后台系统的商户。门店收银台不商户后台通信,商户后台系统负责不微信支付系统发送交易请求和接收返回结果。

1.png-42.4kB
图 5.4 商户后台接入刷卡支付

接入模式-门店接入

该模式适合门店收银台通过公网直接不微信后台通信的商户。 门店收银台直接发起交易请求和处理返回结果。
商户可以根据实际需要,处理门店和商户后台系统之间的其它业务流程

7.png-32.4kB
图 5.5 门店接入刷卡支付

免密支付流程

本节以商户后台接入模式说明支付流程,请参看以下时序图:

8.png-71.6kB
图 5.6 刷卡支付免密流程时序图

流程详细说明:

(1)收银员在商户收银台生成支付订单,向用户展示支付金额;
(2)用户打开微信商户端,点击“我的钱包”,选择“刷卡”,进入条码界面;
(3)使用扫码设备读取用户手机屏幕上的条码;
(4)扫码设备将读取的信息上传给门店收银台;
(5)门店收银台得到支付信息后,向商户收银后台发起支付请求。
(6)商户后台对门店收银台的支付请求进行处理,生成签名后调用【提交刷卡支付 API】向微信支付系统发起支付请求。
(7)微信支付系统得到商户侧的支付请求之后会对请求进行验证,验证通过之后会对请求数据进行处理,最后将处理后的支付结果返回给商户收银后台。如果支付成功,微信支付系统会将支付结果返回给商户,同时把支付结果通知给用户(以短信、微信消息的形式通知)。
(8)商户收银后台对得到的支付结果进行签名验证和处理,再将支付结果返回给门店收银台。
(9)收银员看到门店收银台的支付结果后给用户发账。

验密支付流程

场景交互不免密模式相同,不同的是在商户调用【提交刷卡支付API】发起支付请求之后,微信支付后台提示用户输入密码确认支付,接口同步返回USERPAYING状态,商户系统再轮询调用查询订单接口来确认当前用户是否已经支付成功
以下时序图说明验密支付流程:

11.png-138.5kB
图 5.7 刷卡支付验证密码流程时序图

由于在商户收银后台向微信支付系统发起支付请求之前的流程是完全一样的,所以这里只介绍商户发起支付请求之后的逻辑。

(1)商户门店生成订单后,收银台向后台系统发起支付请求。
(2)后台调用微信支付【提交刷卡支付 API】生成支付交易。
(3)微信支付系统对商户请求进行验证,验证通过后判断当前用户需要输入密码。
(4)微信支付系统返回 USERPAYING 状态,商户后台系统将应答结果返回给商户门店收银台。
(5)微信支付系统通知用户微信商户端输入密码。
(6)用户得到输入密码提示后,确认支付并输入密码。
(7)完成密码输入,提交微信支付。
(8)微信商户端在用户完成支付后提示微信支付后台系统返回的支付结果,而且微信支付系统会通过短信、微信消息给用户发送支付结果提醒。
(9)商户收银台得到 USERPAYING 状态后,经过商户后台系统调用【查询订单 API】查询实际支付结果。
(10)如果支付结果仍为 USERPAYING,则每隔 5 秒循环调用【查询订单 API】判断实际支付结果,如果用户取消支付或累计 30 秒用户都未支付,商户收银台退出查询流程后继续调用【撤销订单 API】撤销支付交易。

异常处理

用户遇到支付异常,请按如下说明处理

(1)用户微信端弹出系统错误提示框,用户可在交易列表查看交易情况,如果未找到订单,需要商户重新发起支付交易;如果订单显示成功支付,商户收银系统再次调用【查询订单 API】查询实际支付结果;
(2)用户微信端弹出支付失败提示,例如:余额不足,信用卡失效。需要重新发起支付;
(3)当交易超时或支付交易失败,商户收银系统必须调用【撤销订单 API】,撤销此交易。
(4)由于银行系统异常、用户余额不足、不支持用户卡种等原因使当前支付交易失败,商户收银系统应该把错误提示明确展示给收银员。
(5)根据返回的错误码,判断是否需要撤销交易,具体详见 API 返回错误码列表

扫码支付

场景介绍

用户扫描商户展示在各种场景的二维码进行支付。

步骤 1:商户根据微信支付的规则,为不同商品生成不同的二维码(如图 6.1),展示在各种场景,用于用户扫 描购买。
步骤 2:用户使用微信“扫一扫”(如图 6.2)扫描二维码后,获取商品支付信息,引导用户完成支付(如图 6. 3)。

1.png-42.4kB 2.png-45.6kB 3.png-67.8kB
图 6.1 支付二维码 图 6.2 打开微信扫一扫二维码 图 6.3 确认支付页面

步骤(3):用户确认支付,输入支付密码(如图 6.4)。
步骤(4):支付完成后会提示用户支付成功(如图6.5),商户后台得到支付成功的通知,然后进行发货处理。

1.png-42.4kB 2.png-45.6kB
图 6.4 用户确认支付,输入密码 图 6.5 支付成功提示

接口规则

协议规则

调用API 必须遵循以下规则:

传输方式 为保证交易安全性,采用HTTPS传输
提交方式 采用POST方法提交
数据格式 提交和返回数据都为XML格式,根节点名为xml
字符编码 统一采用UTF-8字符编码
签名算法 MD5,后续会兼容SHA1、SHA256、HMAC等。
签名要求 请求和接收数据均需要校验签名,详细方法请参考[安全规范-签名算法]
证书要求 调用申请退款、撤销订单接口需要商户证书
判断逻辑为保证交易安全性,采用HTTPS传输

参数规定

安全规范

  1. appid: wxd930ea5d5a258f4f
  2. mch_id: 10000100
  3. device_info: 1000 body

第一步:对参数按照 key=value 的格式,并按照参数名ASCII 字典序排序如下:

  1. stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100
  2. &nonce_str=ibuaiVcKdpRxkhJA";

第二步:拼接API 密钥:

  1. stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
  2. sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"

最终得到最终发送的数据:

  1. <xml>
  2. <appid>wxd930ea5d5a258f4f</appid>
  3. <mch_id>10000100</mch_id>
  4. <device_info>1000<device_info>
  5. <body>test</body>
  6. <nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
  7. <sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
  8. <xml>

数据格式

采用标准XML协议,所有参数只存在一级节点中,不采用多级节点嵌套。
协议级错误返回:

  1. <xml>
  2. <return_code><![CDATA[FAIL]]></return_code>
  3. <return_msg><![CDATA[404 Not Found]]></return_msg>
  4. </xml>

正确返回数据:

  1. <xml>
  2. <bank_type><![CDATA[SPDB_CREDIT]]></bank_type>
  3. <fee_type><![CDATA[CNY]]></fee_type>
  4. <is_subscribe><![CDATA[Y]]></is_subscribe>
  5. <mch_id><![CDATA[15121009]]></mch_id>
  6. <openid><![CDATA[ozaUDwqSo51HvC0lw9CrL20KXlsQ]]></openid>
  7. <out_trade_no><![CDATA[20150303398]]></out_trade_no>
  8. <result_code><![CDATA[SUCCESS]]></result_code>
  9. <return_code><![CDATA[SUCCESS]]></return_code>
  10. <third_trans_id><![CDATA[1004970044201510081126012906]]></third_trans_id>
  11. <time_end><![CDATA[20151008112037]]></time_end>
  12. <total_fee><![CDATA[1]]></total_fee>
  13. <trade_state><![CDATA[SUCCESS]]></trade_state>
  14. <trade_type><![CDATA[trade.weixin.micropay]]></trade_type>
  15. <transaction_id><![CDATA[1512100920150925000000010]]></transaction_id>
  16. </xml>

业务级错误返回:

  1. <xml>
  2. <err_code><![CDATA[AUTHCODEEXPIRE]]></err_code>
  3. <err_code_des><![CDATA[请扫描微信支付被扫条码/二维码]]></err_code_des>
  4. <result_code><![CDATA[FAIL]]></result_code>
  5. <return_code><![CDATA[SUCCESS]]></return_code>
  6. </xml>

API 列表

签到接口

应用场景

收银员使用在 POS 设备上进行登录。

接口地址

https://api.ulopay.com/pay/mipos/token

输入参数

字段名 变量名 类型 必填 描述
操作员编号 op_user_id String(32) 是 操作员帐号
收银员密码 op_user_pwd String(32) 是 MD5(收银员密码).toUpperCase()
授权类型 grant_type String(32) 否 获取 access_token 填写 client_credential
操作终端类型 op_term_tp String(8) 否 取值:POS,WEB,PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL
此字段是通信标识,非交易标识,交易是否成功需要查看
result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因
签名失败
参数格式校验错误
当 return_code 为 SUCCESS 的时候,还会包括以下字段:
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code 和 result_code 都为 SUCCESS 的时,还会包括以下字段:
临时签名密钥 sign_token String(32) 是 用于参不签名的临时签名密钥
凭证有效期 expires_in Int 是 凭证有效时间,单位:秒
商户编号 mch_id String(32) 是 该收银员归属的商户号
商户名称 mch_name String(64) 是 商户名称

错误码

名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
REQUIRE_POST_METH OD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式

签出接口

应用场景

收银员使用在 POS 设备上进行退出,退出登录之后,签名用的 sign_token 将被作废。

接口地址

https://api.ulopay.com/pay/mipos/token/invalid

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
操作员编号 op_user_id String(32) 是 操作员帐号
操作终端类型 op_term_tp String(8) 否 取值:POS,WEB,PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
随机字符串 nonce_str String(32) 是 随机字符串,不长于 32 位。推荐随机数生成算法
签名 sign String(32) 是 签名,详见签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL
此字段是通信标识,非交易标识,交易是否成功需要查看
result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因
签名失败
参数格式校验错误
当 return_code 为 SUCCESS 的时候,还会包括以下字段:
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述

错误码

名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限 REQUIRE_POST_METH OD
REQUIRE_POST_METHOD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式

刷卡支付接口

应用场景

收银员使用扫码设备读取微信用户刷卡授权码以后,二维码或条码信息传送至商户收银台,由商户收银台或者商户后台调用该接口发起支付。

提醒 1:提交支付请求后微信会同步返回支付结果。当返回结果为“系统错误”时,商户系统等待 5 秒后调用【查询订单API】,查询支付实际交易结果;当返回结果为“USERPAYING”时,商户系统可设置间隔时间(建议 10 秒)重新查询支付结果,直到支付成功或超时(建议 30 秒);
提醒 2:在调用查询接口返回后,如果交易状冴不明晰,请调用【撤销订单API】,此时如果交易失败则关闭订单,该单不能再支付成功;如果交易成功,则将扣款退回到用户败户。当撤销无返回或错误时,请再次调用。
注意:请勿扣款后立即调用【撤销订单API】,建议至少 5 分钟后再调用。

接口地址

https://api.ulopay.com/pay/mipos/micropay

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串,不长于32位
商品描述 body String(32) 是 商品或支付单简要描述
商品详情 detail String(8192) 否 商品名称明细列表
附加数据 attach String(127) 否 附加数据,在查询 API 和支付通知中原样返回,该字段主 要用于商户携带订单的自定义数据
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号,32 个字符内、可包含字母,其他说 明见商户订单号
总金额 total_fee Int 是 订单总金额,单位为分,只能为整数,详见 支付金额
货币类型 fee_type String(16) 否 默认人民币:CNY,其他值列表详见 货币类型
终端 IP spbill_create_id String(16) 是 调用微信支付API的机器IP
商品标记 goods_tag String(32) 否 商品标记,代金券或立减优惠功能的参数
授权码 auth_code String(128) 是 扫码支付授权码,设备读取用户微信中的条码或者二维码 信息
操作终端类型 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL
此字段是通信标识,非交易标识,交易是否成功需要查看
result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因
签名失败
参数格式校验错误
当return_code为SUCCESS的时候,还会包括以下字段:
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名 签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当return_code和result_code都为SUCCESS的时,还会包括以下字段:
用户标识 openid String(128) 否 用户在商户 appid 下的唯一标识
是否关注公众号 is_subscribe String(1) 否 用户是否关注公众号,仅在公众号类型支付有效, 取值范围:Y 或 N;Y-关注;N-未关注
用户子标识 sub_openid String(128) 否 用户在子商户 appid 下的唯一标识
是否关注子公众号 sub_is_subscribe String(1) 否 用户是否关注子公众败号,Y-关注,N-未关注,仅在公 众败号类型支付有效
交易类型 trade_type String(16) 是 支付类型为 trade.weixin.micropay (即刷卡支付)
付款银行 bank_type String(16) 是 银行类型,采用字符串类型的银行标识,值列表详见银行类型
账币类型 fee_type String(16) 否 符合 ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见账币类型
总金额 total_fee Int 是 订单总金额,单位为分,只能为整数,详见支付金额
现金支付账币类型 cash_fee_type String(16) 否 符合 ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见账币类型
现金支付金额 cash_fee Int 是 订单现金支付金额,详见支付金额
代金券或立减优惠金额 coupon_fee Int 否 代金券或立减优惠金额订单总金额,订单总金额-代金券立减优惠金额=现金支付金额
平台支付订单号 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。详见时间规则

错误码

注意:如果当前交易返回的支付状态是明确的错误原因造成的支付失败(支付确认失败),请重新下单支付;如果当前交易返回的支付状态是不明错误(支付结果未知),请调用查询订单接口确认状态,如果长时间(建议 30 秒)都得不到明确状态请调用撤销订单接口。
名称 描述 支付状态 原因 解决方案
SYSTEMERROR 接口返回错误 支付结果未知 系统超时 请立即调用被扫订单结果查询 API,查询当前订单状态,并根据订单的状态决定下一步的操作。
PARAM_ERROR 参数错误 支付确认失败 请求参数未按指引进行填写 请根据接口返回的详细信息检查您的程序
ORDERPAID 订单已支付 支付确认失败 订单号重复 请确认该订单号是否重复支付,如果是新单,请使用新订单号提交
NOAUTH 商户无权限 支付确认失败 商户没有开通被扫支付权限 请开通商户号权限。请联系产品或商务申请
AUTHCODEEXPIRE 二维码已过期,请用户在微信上刷新后再试 支付确认失败 用户的条码已经过期 请收银员提示用户,请用户在微信上刷新条码,然后请收银员重新扫码。 直接将错误展示给收银员
NOTENOUGH 余额不足 支付确认失败 用户的零钱余额不足 请收银员提示用户更换当前支付的卡,然后请收银员重新扫码。建议:商户系统返回给收银台的提示为“用户余额不足.提示用户换卡支付”
NOTSUPORTCARD 不支持卡类型 支付确认失败 用户使用卡种不支持当前支付形式 请用户重新选择卡种 建议:商户系统返回给收银台的提示为“该卡不支持当前支付,提示用户换卡支付或绑新卡支付”
ORDERCLOSED 订单已关闭 支付确认失败 该订单已关 商户订单号异常,请重新下单支付
ORDERREVERSED 订单已撤销 支付确认失败 当前订单已经被撤销 当前订单状态为“订单已撤销”,请提示用户重新支付
BANKERROR 银行系统异常 支付结果未知 银行端超时 请立即调用被扫订单结果查询 API,查询当前订单的不同状态,决定下一步的操作。
USERPAYING 用户支付中,需要输入密码 支付结果未知 该笔交易因为业务规则要求,需要用户输入支付密码。 等待 5 秒,然后调用被扫订单结果查询 API,查询当前订单的不同状态,决定下一步的操作。
AUTH_CODE_ERROR 授权码参数错误 支付确认失败 请求参数未按指引进行填写 每个二维码仅限使用一次,请刷新再试
AUTH_CODE_INVALID 授权码检验错误 支付确认失败 收银员扫描的不是微信支付的条码 请扫描微信支付被扫条码/二维码
XML_FORMAT_ERROR XML 格式错误 支付确认失败 XML 格式错误 请检查 XML 参数格式是否正确
REQUIRE_POST_METHOD 请使用 post 方法 支付确认失败 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
SIGNERROR 签名错误 支付确认失败 参数签名结果不正确 请检查签名参数和方法是否都符合签名算法要求
LACK_PARAMS 缺少参数 支付确认失败 缺少必要的请求参数 请检查参数是否齐全
NOT_UTF8 编码格式错误 支付确认失败 未使用指定编码格式 请使用 UTF-8 编码格式
BUYER_MISMATCH 支付帐号错误 支付确认失败 暂不支持同一笔订单更换支付方 请确认支付方是否相同
APPID_NOT_EXIST APPID 不存在 支付确认失败 参数中缺少 APPID 请检查 APPID 是否正确
MCHID_NOT_EXIST MCHID 不存在 支付确认失败 参数中缺少 MCHID 请检查 MCHID 是否正确
OUT_TRADE_NO_USED 商户订单号重复 支付确认失败 同一笔交易不能多次提交 请核实商户订单号是否重复提交
APPID_MCHID_NOT_MATCH appid 和 mch_id不匹配 支付确认失败 appid 和 mch_id 不匹配 请确认 appid 和 mch_id 是否匹配

撤销订单接口

应用场景

支付交易返回失败或支付系统超时,调用该接口撤销交易。如果此订单用户支付失败,支付系统会将此订单关闭;如果用户支付成功,系统会将此订单资金退还给用户。

注意:7天以内的交易单可调用撤销,其他正常支付的单如需实现相同功能请调用申请退款 API。提交支付交易后调用【查询订单 API】,没有明确的支付结果再调用【撤销订单 API】。
调用支付接口后请勿立即调用撤销订单 API,建议支付后至少 5 分钟再调用撤销订单接口。
只有刷卡支付接口有撤销订单接口。

接口地址

https://api.ulopay.com/pay/mipos/reverse

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
平台订单号 transaction_ id String(32) 否 平台支付订单号,优先使用
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号,transaction_id、out_trade_no 二 选一,如果同时存在优先级:transaction_id> out_trad e_no
随机字符串 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL此字段是通信标识,非交易标识,交易是否成功需要查看result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因签名失败参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述

错误码

名称 描述 原因 解决方案
SYSTEMERROR 接口返回错误 系统超时 请用相同参数再次调用 API
INVALID_TRANSACTI ONID 无效 transaction_id 请求参数未按指引进 行填写 请求参数错误,检查原交易号是否存在或发起支付 交易接口返回失败
PARAM_ERROR 参数错误 请求参数未按指引进 行填写请求参数错误,请重新检查再调用退款申请
REQUIRE_POST_METH OD 请使用 post 方法 未使用 post 传递参 数 请检查请求参数是否通过 post 方法提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算法要求

扫码支付接口

应用场景

收银员使用在 POS 设备上输入金额,POS将信息传送至商户收银台,由商户收银台或者商户后台调用该接口发起支付,接口后台返回支付二维码,用户扫码进行支付。
根据 trade_type 参数,切换支付类型

接口地址

https://api.ulopay.com/pay/mipos/unifiedorder

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 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_id String(16) 是 调用微信支付API的机器IP
商品标记 goods_tag String(32) 否 商品标记,代金券或立减优惠功能的参数
通知地址 notify_url String(256) 是 接收支付结果异步通知回调地址,PC 网站必填,POS 机器扫码支付填写空字符串即可。示例:http://www.baidu.com/
交易类型 trade_type String(32) 是 取值:trade.weixin.native,详细说明见参数规定
指定支付方式 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因:签名失败、参数格式校验错误
当return_code为SUCCESS的时候,还会包括以下字段:
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当return_code和result_code都为SUCCESS的时,还会包括以下字段:
交易类型 trade_type String(32) 是 取值:trade.weixin.native,详细说明见参数规定
预支付标识 prepay_id String(64) 是 预支付会话标识,用于后续接口调用中使用,该值有效期 为 2 小时
二维码链接 code_url String(64) 否 trade_type 为 trade.weixin.native 是有返回,可将该参 数值生成二维码展示出来进行扫码支付
二维码图片链 接地址 code_img_url String(128) 否 trade_type 为 trade.weixin.native 是有返回

错误码

注意:如果当前交易返回的支付状态是明确的错误原因造成的支付失败(支付确认失败),请重新下单支付;如 果当前交易返回的支付状态是不明错误(支付结果未知),请调用查询订单接口确认状态。
名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
NOTENOUGH 余额不足 用户帐号余额不足 用户帐号余额不足,请用户充值或更换支付 卡后再支付
ORDERPAID 商户订单已支付 商户订单已支付,无需重复操作 商户订单已支付,无需更多操作
ORDERCLOSED 订单已关闭 当前订单已关闭,无法支 付 当前订单已关闭,请重新下单
SYSTEMERROR 系统错误 系统超时 系统异常,请用相同参数重新调用
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
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 编码格式

查询订单接口

应用场景

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

接口地址

https://api.ulopay.com/pay/orderquery

请求参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
平台订单号 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL此字段是通信标识,非交易标识,交易是否成功需要查看result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因签名失败参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见 签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
以下字段在return_code 和 result 都为SUCCESS的时候有返回
商户号 mch_id String(32) 是 商户号
交易类型 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) 否 对当前查询订单状态的描述和下一步操作的指引

错误码

名称 描述 原因 解决方案
ORDERNOTEXIST 此交易订单号 不存在 查询系统中不存 在此交易订单号 该 API 只能查提交支付交易返回成功的订单,请商户检查需要查询的订 单号是否正确
SYSTEMER ROR 系统错误 后台系统返回错误 系统异常,请再调用发起查询

申请退款接口

应用场景

当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。
注意:
退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。
一笔退款失败后重新提交,要采用原来的退款单号。总退款金额不能超过用户实际支付金额。

接口地址

https://api.ulopay.com/secapi/pay/refund

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因 签名失败 参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名生成算法
业务结果 result_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

错误码

名称 描述 原因 解决方案
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 参数格式是否正确

查询退款接口

应用场景

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

接口地址

https://api.ulopay.com/pay/refundquery

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 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) 微信生成的退款单号,在申请退款接口有返回

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL此字段是通信标识,非交易标识,交易是否成功需要查看result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因 签名失败 参数格式校验错误
以下字段在 return_code 为 SUCCESS 的时候有返回
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名生成算法
业务结果 result_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—转入代发,退款到银行发现用户的卡作废或者冻结 了,导致原路退款银行卡失败,资金回流到商户的现金帐 号,需要商户人工干预,通过线下或者财付通转账的方式进 行退款。

错误码

名称 描述 原因 解决方案
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 参数格式是否正确

最后订单接口

应用场景

最后一笔交易的查询(为了防止商户付款后,柜员误操作退出,无法打印凭条,无法知道订单状态)。查询当前签到用户的最后一笔交易。
重打最后一笔的功能,需要把 trade_state 传递为 SUCCESS。

接口地址

https://api.ulopay.com/pay/mipos/orderlast

请求参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
交易状态 trade_state String(8) 否 不传则只查最后一条记录,传则根据状态查询,取值有:
SUCCESS—支付成功
REFUND—转入退款
NOTPAY—未支付
随机字符串 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因:签名失败、参数格式校验错误
当return_code为SUCCESS的时候,还会包括以下字段:
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名 签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当return_code和result_code都为SUCCESS的时,还会包括以下字段:
用户标识 openid String(128) 否 用户在商户 appid 下的唯一标识
是否关注公众号 is_subscribe String(1) 否 用户是否关注公众号,仅在公众号类型支付有效, 取值范围:Y 或 N;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) 是 银行类型,采用字符串类型的银行标识,值列表详见银行类型
货币种类 fee_type String(8) 否 货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见 货币类型
总金额 total_fee Int 是 订单总金额,单位为分,只能为整数,详见支付金额
现金支付账币类型 cash_fee_type String(16) 否 符合 ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见账币类型
现金支付金额 cash_fee Int 是 订单现金支付金额,详见支付金额
代金券或立减 优惠金额 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) 否 对当前查询订单状态的描述和下一步操作的指引

错误码

名称 描述 原因 解决方案
ORDERNOTEXIST 此交易订单号 不存在 查询系统中不存 在此交易订单号 该 API 只能查提交支付交易返回成功的订单,请商户检查需要查询的订 单号是否正确
SYSTEMER ROR 系统错误 后台系统返回错误 系统异常,请再调用发起查询

交易汇总接口

应用场景

查询交易汇总功能。便于统计交易金额。可用于当前用户签出时可能需要结算小票。
是指查询当前签到用户的汇总交易金额、交易笔数、退款金额、退款笔数。
指定日期查询交易汇总,日期范围时间最大不能超过当前日期的 7 天,超过 7 天则无法查询。

接口地址

https://api.ulopay.com/pay/mipos/checkout

请求参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 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) 是 签名,详见 签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因:签名失败、参数格式校验错误
当return_code为SUCCESS的时候,还会包括以下字段:
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名,详见签名 签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当return_code和result_code都为SUCCESS的时,还会包括以下字段:
结算起始时间 start_time String(14) 是 格式为 yyyyMMddHHmmss,如 2009 年 12 月 25 日9 点 10 分 10 秒表示为 20091225091010。详见时间规则
结算结束日期 end_time String(14) 是 格式为 yyyyMMddHHmmss,如 2009 年 12 月 25 日9 点 10 分 10 秒表示为 20091225091010。详见时间规则
交易总金额 total_fee Number(10,2) 是 订单总金额,单位为元,保留两位小数
收款总金额 cash_fee Number(10,2) 是 现金支付金额订单现金支付金额,详见支付金额 订单总金额,单位为元,保留两位小数交易
总笔数 total_count Int 是 支付成功订单的总笔数
退款金额 refund_fee Number(10,2) 是 退款总金额,单位为分,可以做部分退款,单位为元,保留两位小数
退款总笔数 refund_count Int 是 提交退款的总笔数
撤 销 ( 冲 正 )笔数 reverse_count Int 是 提交冲正的总笔数

错误码

名称 描述 原因 解决方案
SYSTEMER ROR 系统错误 后台系统返回错误 系统异常,请再调用发起查询

查询卡券接口

应用场景

根据微信卡券的领用条形码值,获取对应的卡券信息。

接口地址

https://api.ulopay.com/pay/mipos/cardcode/get

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
卡券领用码 code String(32) 是 单张卡券的唯一标准
卡券 ID card_id String(32) 否 卡券 ID 代表一类卡券
操作员编号 op_user_id String(32) 是 操作员帐号
操作终端类型 op_term_tp String(8) 否 取值:POS,WEB,PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
随机字符串 nonce_str String(32) 是 随机字符串,不长于 32 位。推荐随机数生成算法
签名 sign S tring(32) 是 签名,详见签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因:签名失败、参数格式校验错误
当return_code为SUCCESS的时候,还会包括以下字段:
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code 和 result_code 都为 SUCCESS 的时,还会包括以下字段:
卡券 ID card_id String(32) 是 卡券 ID
卡券券类型 card_type String(6) 是 卡券券类型
起用门槛 least_cost Int 是 表示起用金额(单位为分),如果无起用门槛则填 0
减免金额 reduce_cost Int 是 代金券与用,表示减免金额。(单位为分)
打折额度 discount Int 是 折扣券与用,表示打折额度(百分比)。填 30 就是七折
卡券名 title String(128) 是 卡券的名称
券名 sub_title String(64) 否 券名
卡券 logo logo_url String(255) 否 卡券的小图片
起始使用时间 begin_time Int 是 起始使用时间
结束时间 end_time Int 是 结束时间
是否可以核销 can_consume Int 是 是否可以核销,1 为可以核销,0 为不可核销
核销信息提示 consume_msg String(32) 是 核销的信息提示,如 can_consume 为 0,则该字段返 回的消息是表示不可以核销的原因

结果示例:

  1. {
  2. "return_code":"SUCCESS",
  3. "result_code:"SUCCESS",
  4. "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
  5. "begin_time": 1448449938,
  6. "end_time": 1448449938,
  7. "user_card_status": "NORMAL",
  8. "can_consume":1
  9. }

错误码

名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
REQUIRE_POST_METHOD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式

核销卡券接口

应用场景

核销卡券接口,如果用户使用线下收款方式,如现金,银行卡。则 consume 字段传递 0 表示直接核销掉。
如果是使用微信支付、支付宝支付等线上收款方式,则 consume 字段传递 1 表示卡券要等交易成功之后自动核销

接口地址

https://api.ulopay.com/pay/mipos/cardcode/consume

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
卡券领用码 code String(32) 是 单张卡券的唯一标准
卡券 ID card_id String(32) 否 卡券 ID 代表一类卡券
是否核销 consume Int 是 是否直接核销
线下支付传递 0,
线上支付完成之后核销传递 1
收款金额 total_fee Int 否 单位为分,consume 为 1 时必传递
折扣金额 discount_fee Int 否 单位为分,consume 为 1 时必传递,终端计算出来的折
扣金额,传递该字段则后台将会验证折扣金额是否一致
操作员编号 op_user_id String(32) 是 操作员帐号
操作终端类型 op_term_tp String(8) 否 取值:POS,WEB,PC
操作终端编号 op_term_no String(32) 否 终端设备号
操作门店编号 op_shop_no String(32) 否 门店编号
随机字符串 nonce_str String(32) 是 随机字符串,不长于 32 位。推荐随机数生成算法
签名 sign S tring(32) 是 签名,详见签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息,如非空,为错误原因:签名失败、参数格式校验错误
当return_code为SUCCESS的时候,还会包括以下字段:
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code 和 result_code 都为 SUCCESS 的时,还会包括以下字段:
使用 ID use_id String(32) 是 卡券预使用 ID
卡券 ID card_id S tring(32) 是 卡券 ID
收款金额 total_fee Int 是 单位为分
折扣金额 discount_fee Int 是 单位为分
实收金额 paid_fee Int 是 单位为分

结果示例:

  1. {
  2. "return_code":"SUCCESS",
  3. "result_code:"SUCCESS",
  4. "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
  5. }

查询收款列表

应用场景

查询收款列表接口,列表显示收款信息

接口地址

https://xpay.ulopay.com/xpay/order/listSearch

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
交易时间 check_date String(32) 是 交易时间,例如:20151210
交易单号 order_num String(32) 是 订单号 order_no
交易状态 status String(2) 是 交易状态,取值: 1:未支付,2:支付成功,3:已关闭, 4:转入退款,8:已冲正,9:已撤销
当前页 currentPage String(32) 否 当前页,默认为 0
行数 pageSize String(2) 否 每页的行数,默认为 10
操作员编号 op_user_id String(32) 是 操作员帐号
随机字符串 nonce_str String(32) 是 随机字符串,不长于 32 位。推荐随机数生成算法
签名 sign String(32) 是 签名,详见签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 status String(16) 是 数字串,详见参数列表
返回信息 message String(128) 否 返回信息,如非空,为错误原因
  1. 结果实例:
  2. {
  3. "status":1400,
  4. "message":"商户不存在"
  5. }

当调用正常时返回下列参数:

字段名 变量名 类型 必填 描述
页数 totalRows Intr 是 一共的页数,按所传 pageSize 大小分页
总行数 totalRows Int 是 总行数,返回的行数
支付方式 tradeName String(32) 是 支付方式,例如:微信刷卡支付、手 Q 支付等
交易时间 addTime Date 是 返回时间戳
交易单号 orderNo String(32) 是 订单号 orderNo
交易状态 tradeState Int 是 交易状态(1:未支付,2:支付成功,3:已关闭,4:转 入退款,8:已冲正,9:已撤销)
交易金额 money Int 是 交易金额,返回的是 Int,需做除 100 处理
商品名称 body String(32) 是 商品名称
收银员 operno String(32) 是 收银员
商户号 groupno String(32) 是 商户号
商户单号 outTradeNo String(32) 是 商户单号
第三方单号 transactionId String(32) 是 第三方单号
退款金额 refundMoney Int 是 退款金额,返回的是 Int,需做除 100 处理
  1. 结果示例:
  2. {
  3. "pageCount": 2,
  4. "totalRows": 13,
  5. "data": [
  6. {
  7. "returnUrl": null,
  8. "body": "反扫商品",
  9. "tradeName": "微信刷卡支付",
  10. "appid": "wx96dfe920b23c06d2",
  11. "subIsSubscribe": null,
  12. "subAppid": null,
  13. "isSubscribe": "Y",
  14. "mchCreateIp": "127.0.0.1",
  15. "bankNo": "10000",
  16. "subPartner": null,
  17. "reqtype": 0,
  18. "decryptKey": null,
  19. "partner": "1271112101",
  20. "openid": "ozaUDwiw56Hbzl3LhirdNAhLdzX4",
  21. "mchNo": "15121009",
  22. "mchName": "Test001",
  23. "refundMoney": 1,
  24. "charset": "UTF-8",
  25. "mchId": 1,
  26. "shopno": null,
  27. "agentid": "15121000",
  28. "tradeState": 4,
  29. "totalFee": 1,
  30. "mchtradeId": 0,
  31. "bankType": "CFT",
  32. "centerId": 2,
  33. "addTime": 1447328774000,
  34. "notifyTime": null,
  35. "tradeType": "trade.weixin.micropay",
  36. "notifyState": 0,
  37. "transactionId": "1008220044201511121574229274",
  38. "signType": "MD5",
  39. "groupno": "15121009",
  40. "outTradeNo": "20151112194600201",
  41. "payCreateIp": "127.0.0.1",
  42. "couponFee": null,
  43. "cashFee": null,
  44. "termtype": null,
  45. "termno": null,
  46. "operno": "002@15121009",
  47. "feeType": "CNY",
  48. "money": 1,
  49. "notifyUrl": null,
  50. "agentno": "001001",
  51. "cashFeeType": null,
  52. "tradeTime": 1447328774000,
  53. "bankTypeNo": null,
  54. "deparno": null,
  55. "deviceInfo": null,
  56. "orderNo": "1512100920151112000000380",
  57. "subOpenid": null,
  58. "attach": null
  59. }
  60. ],
  61. "perPage": 10,
  62. "currentPage": 0
  63. }

查询退款列表

应用场景

查询退款列表接口,列表显示退款信息

接口地址

https://xpay.ulopay.com/xpay/order/refundListSearch

输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
交易时间 check_date String(32) 是 交易时间,例如:20151210
交易单号 order_num String(32) 是 订单号 order_no
交易状态 status String(2) 是 交易状态,取值: 1:未支付,2:支付成功,3:已关闭, 4:转入退款,8:已冲正,9:已撤销
当前页 currentPage String(32) 否 当前页,默认为 0
行数 pageSize String(2) 否 每页的行数,默认为 10
操作员编号 op_user_id String(32) 是 操作员帐号
随机字符串 nonce_str String(32) 是 随机字符串,不长于 32 位。推荐随机数生成算法
签名 sign String(32) 是 签名,详见签名生成算法

返回结果

字段名 变量名 类型 必填 描述
返回状态码 status String(16) 是 数字串,详见参数列表
返回信息 message String(128) 否 返回信息,如非空,为错误原因
  1. 结果实例:
  2. {
  3. "status":1400,
  4. "message":"商户不存在"
  5. }

当返回结果正常时返回以下参数:

字段名 变量名 类型 必填 描述
页数 totalRows Intr 是 一共的页数,按所传 pageSize 大小分页
总行数 totalRows Int 是 总行数,返回的行数
支付方式 tradeName String(32) 是 支付方式,例如:微信刷卡支付、手 Q 支付等
交易时间 addTime Date 是 返回时间戳
退款单号 refundNo String(32) 是 订单号 refundNo
退款状态 refundState Int 是 退款状态 (0 初始,1 退款成功,2 退款失败,3 退款处理中,4 未确定,5 转入代发)
订单总额 totalFee Int 是 订单总额,返回的是 Int,需做除 100 处理
退款总额 refundFee Int 是 退款总额,返回的是 Int,需做除 100 处理
收银员 operno String(32) 是 收银员
商户号 groupno String(32) 是 商户号
商户单号 outTradeNo String(32) 是 商户单号
第三方单号 transactionId String(32) 是 第三方单号
  1. 结果示例:
  2. {
  3. "pageCount": 1,
  4. "totalRows": 2,
  5. "data": [
  6. {
  7. "tradeType": "trade.weixin.micropay",
  8. "refundNo": "1512100920151202000001947",
  9. "transactionId": "1009520044201512021864758694",
  10. "outRefundNo": "20151202153813676",
  11. "refundFee": 1,
  12. "riskCtr": 1,
  13. "refundUser": null,
  14. "daemonAudit": 3,
  15. "groupno": "15121009",
  16. "ptReviewTime": null,
  17. "tradeName": "微信刷卡支付",
  18. "ptAuditUser": null,
  19. "outTradeNo": "3SD201085B5K261001201512020038",
  20. "refundTime": 1449041896000,
  21. "bankNo": "10000",
  22. "mchAudit": 0,
  23. "termtype": "POS",
  24. "updateVersion": 2,
  25. "termno": null,
  26. "mchAuditUser": null,
  27. "operno": "002@15121009",
  28. "feeType": "CNY",
  29. "agentno": "001001",
  30. "mchReviewTime": null,
  31. "refundid": "2009520044201512020090982022",
  32. "mchName": "测试个体商户",
  33. "mchNo": "15121009",
  34. "mchRefuseReason": null,
  35. "orderState": 2,
  36. "deparno": null,
  37. "mchId": 1,
  38. "shopno": null,
  39. "refundState": 3,
  40. "groupId": null,
  41. "riskInfo": "NORMAL",
  42. "refundChannel": "ORIGINAL",
  43. "totalFee": 1,
  44. "orderNo": "1512100920151202000001937",
  45. "refuseReason": null,
  46. "centerId": 2,
  47. "refundSource": 0,
  48. "addTime": 1449041895000
  49. }
  50. ],
  51. "perPage": 6,
  52. "currentPage": 0
  53. }
添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注