POS内部接口

列表项

支付 接口

引言

阅读对象

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

业务术语

1.刷卡支付

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

2.扫码支付

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

3.公众号支付

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

4、APP 支付

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

5、支付宝支付

请找商务索取最新文档。

6、QQ 钱包支付

请找商务索取最新文档。

7、百度钱包支付

请找商务索取最新文档。

支付账户

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

表 3.1 账户参数说明

测试支付账户：

刷卡支付

场景介绍

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

我的钱包	刷卡界面

输入密码，确认支付	支付成功后页面提示

支付验证密码规则

• 支付金额>1000 元的交易需要验证用户支付密码
• 用户败号每天最多有 5 笔交易可以免密，超过后需要验证密码
• 微信支付后台判断用户支付行为有异常情况，符合免密规则的交易也会要求验证密码

案例介绍

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

接入模式-商户后台接入

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

图 5.4 商户后台接入刷卡支付

接入模式-门店接入

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

图 5.5 门店接入刷卡支付

免密支付流程

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

图 5.6 刷卡支付免密流程时序图

流程详细说明：

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

验密支付流程

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

图 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）。

图 6.1 支付二维码	图 6.2 打开微信扫一扫二维码	图 6.3 确认支付页面

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

图 6.4 用户确认支付，输入密码	图 6.5 支付成功提示

接口规则

协议规则

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

参数规定

• 交易金额
  交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。对账单中的交易金额单位为【元】。外币交易的支付金额精确到币种的最小单位，参数值不能带小数点。
• 交易类型
  trade.weixin.jspay--公众号支付
  trade.weixin.native--原生扫码支付
  trade.weixin.h5pay--手机浏览器H5支付，统一下单接trade_type的传参可参考这里
  trade.weixin.micropay--刷卡支付，刷卡支付有单独的支付接口，不调用统一下单接口
  trade.alipay.native--支付宝扫码支付
  trade.alipay.micropay–-支付宝小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
  trade.qqpay.micropay--QQ钱包小额支付，刷卡支付有单独的支付接口，不调用统一下单接口
• 货币类型
  货币类型的取值列表：
  CNY：人民币
• 时间
  标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时区先换算成标 准北京时间， 例如商户所在地为 0 时区的伦敦，当地时间为 2014 年 11 月 11 日 0 时 0 分0 秒，换算成北京时间为：2014 年 11 月 11 日 8 时 0 分 0 秒
• 时间戳
  标准北京时间，时区为东八区，自 1970 年 1 月 1 日 0 点 0 分 0秒以来的秒数。注意：部分系统取到的值为毫秒 级，需要转换成秒(10 位数字)。
• 商户订单号
  商户支付的订单号由商户自定义生成，要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单 号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过或已调用关单、撤销（请见后文的 API 列表）的订单号 不能重新发起支付。

安全规范

• 签名算法
  签名生成的通用步骤如下：
  第一步，设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名 ASCII 码从 小到大排序（字典序），使用URL 键值对的格式（即 key1=value1&key2=value2…）拼接成字符串stringA。
  特别注意以下重要规则：
  
  ◆ 参数名 ASCII 码从小到大排序（字典序）；
  ◆ 如果参数的值为空不参与签名；也就是说参数是空的不需要参与签名；
  ◆ 参数名区分大小写；
  ◆ 验证调用返回或主动通知签名时，传送的 sign 参数不参与签名，将生成的签名与该 sign 值作校验。
  ◆ 支付接口可能增加字段，验证签名时必须支持增加的扩展字段
  
  
• 生成随机数算法
  支付API 接口协议中包含字段 nonce_str，主要保证签名不可预测。我们推荐生成随机数算法如下：调用 随机数函数生成，将得到的值转换为字符串。
  例： 假设传送的参数如下

appid： wxd930ea5d5a258f4f
mch_id： 10000100
device_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>

数据格式

采用标准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>

API 列表

签到接口

应用场景

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

接口地址

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

输入参数

返回结果

错误码

签出接口

应用场景

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

接口地址

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

输入参数

返回结果

错误码

刷卡支付接口

应用场景

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

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

接口地址

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

输入参数

返回结果

错误码

注意：如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支付；如果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态，如果长时间（建议 30 秒）都得不到明确状态请调用撤销订单接口。

撤销订单接口

应用场景

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

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

接口地址

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

输入参数

返回结果

错误码

扫码支付接口

应用场景

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

接口地址

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

输入参数

返回结果

错误码

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

查询订单接口

应用场景

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

接口地址

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

请求参数

返回结果

错误码

申请退款接口

应用场景

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

接口地址

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

输入参数

返回结果

错误码

查询退款接口

应用场景

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

接口地址

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

输入参数

返回结果

错误码

最后订单接口

应用场景

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

接口地址

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

请求参数

返回结果

错误码

交易汇总接口

应用场景

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

接口地址

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

请求参数

返回结果

错误码

查询卡券接口

应用场景

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

接口地址

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

输入参数

返回结果

结果示例：

{
    "return_code":"SUCCESS",
    "result_code:"SUCCESS",
    "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
    "begin_time": 1448449938,
    "end_time": 1448449938,
    "user_card_status": "NORMAL",
    "can_consume":1
}

错误码

核销卡券接口

应用场景

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

接口地址

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

输入参数

返回结果

结果示例：

{
"return_code":"SUCCESS",
"result_code:"SUCCESS",
"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

查询收款列表

应用场景

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

接口地址

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

输入参数

返回结果

结果实例：
{
"status":1400,
"message":"商户不存在"
}

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

结果示例：
    {
     "pageCount": 2,
     "totalRows": 13,
     "data": [
     {
     "returnUrl": null,
     "body": "反扫商品",
     "tradeName": "微信刷卡支付",
     "appid": "wx96dfe920b23c06d2",
     "subIsSubscribe": null,
     "subAppid": null,
     "isSubscribe": "Y",
     "mchCreateIp": "127.0.0.1",
     "bankNo": "10000",
     "subPartner": null,
     "reqtype": 0,
     "decryptKey": null,
     "partner": "1271112101",
     "openid": "ozaUDwiw56Hbzl3LhirdNAhLdzX4",
     "mchNo": "15121009",
     "mchName": "Test001",
     "refundMoney": 1,
     "charset": "UTF-8",
     "mchId": 1,
     "shopno": null,
     "agentid": "15121000",
     "tradeState": 4,
     "totalFee": 1,
     "mchtradeId": 0,
     "bankType": "CFT",
     "centerId": 2,
     "addTime": 1447328774000,
     "notifyTime": null,
     "tradeType": "trade.weixin.micropay",
     "notifyState": 0,
     "transactionId": "1008220044201511121574229274",
     "signType": "MD5",
     "groupno": "15121009",
     "outTradeNo": "20151112194600201",
     "payCreateIp": "127.0.0.1",
     "couponFee": null, 
     "cashFee": null,
     "termtype": null,
     "termno": null,
     "operno": "002@15121009",
     "feeType": "CNY",
     "money": 1,
     "notifyUrl": null,
     "agentno": "001001",
     "cashFeeType": null,
     "tradeTime": 1447328774000,
     "bankTypeNo": null,
     "deparno": null,
     "deviceInfo": null,
     "orderNo": "1512100920151112000000380",
     "subOpenid": null,
     "attach": null
     }
     ],
     "perPage": 10,
     "currentPage": 0
    }

查询退款列表

应用场景

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

接口地址

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

输入参数

返回结果

结果实例：
{
"status":1400,
"message":"商户不存在"
}

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

结果示例：
    {
     "pageCount": 1,
     "totalRows": 2,
     "data": [
     {
     "tradeType": "trade.weixin.micropay",
     "refundNo": "1512100920151202000001947",
     "transactionId": "1009520044201512021864758694",
     "outRefundNo": "20151202153813676",
     "refundFee": 1,
     "riskCtr": 1,
     "refundUser": null,
     "daemonAudit": 3,
     "groupno": "15121009",
     "ptReviewTime": null,
     "tradeName": "微信刷卡支付",
     "ptAuditUser": null,
     "outTradeNo": "3SD201085B5K261001201512020038",
     "refundTime": 1449041896000,
     "bankNo": "10000",
     "mchAudit": 0,
     "termtype": "POS",
     "updateVersion": 2,
     "termno": null,
     "mchAuditUser": null,
     "operno": "002@15121009",
     "feeType": "CNY",
     "agentno": "001001",
     "mchReviewTime": null,
     "refundid": "2009520044201512020090982022",
     "mchName": "测试个体商户",
     "mchNo": "15121009",
     "mchRefuseReason": null,
     "orderState": 2,
     "deparno": null,
     "mchId": 1,
     "shopno": null,
     "refundState": 3, 
     "groupId": null,
     "riskInfo": "NORMAL",
     "refundChannel": "ORIGINAL",
     "totalFee": 1,
     "orderNo": "1512100920151202000001937",
     "refuseReason": null,
     "centerId": 2,
     "refundSource": 0,
     "addTime": 1449041895000
     }
     ],
     "perPage": 6,
     "currentPage": 0
    }