取消交易 (扫脸、扫码)

取消交易 (扫脸、扫码)

使用场景:

场景1:刷脸过程中支付之前如果消费者不想扫脸时可以退出刷脸流程

场景2:刷脸或扫码消费已进入支付中阶段,但由于某种原因(等待时间过长)商户想要关闭订单,即便扣款成功也会原路退回。(暂未发布)

Request

数据项数据类型(默认String)标识是否必填(M/C)说明
应用IdStringappIdM应用包名,android APP程序packagename
交易类型StringtransTypeM10-取消交易        
原Saas系统支付订单号StringoriOrderIdM

Response

数据项数据类型(默认String)标识是否必填(M/C)说明
交易结果返回码StringresultCodeMQ18:已取消Q19:操作失败
返回码描述StringresultMsgC 
交易类型StringtransTypeM10-取消交易        
原Saas系统支付订单号StringoriOrderIdM

退款 (扫码、银行卡、扫脸)

退款 (扫码、银行卡、扫脸) 退款交易包括 (消费撤销、预授权撤销、预授权完成撤销)

说明: 如果退款时因网络原因遇到超时(应答码Q02),可尝试通过单笔交易查询接口 查询退款状态.

Request

数据项数据类型(默认String)标识是否必填(M/C)说明适用范围
应用类型StringappTypeC00:银行卡应用01:聚合扫码支付应用02:银行卡+银联扫码支付应用51:刷脸支付扫码、银行卡、扫脸
应用IdStringappIdM应用包名,android APP程序packagename扫码、银行卡、扫脸
交易类型StringtransTypeM09-退款扫码、银行卡、扫脸
退款金额LongamountC单位为分,1元表示为100L,最多12位,传空则退全款扫码、银行卡、扫脸
Saas系统退款单号StringorderIdM1.Saas系统的支付订单号(字符串),用于标识当笔交易的支付订单号,交易处理结果中会带回。2.业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。3.如果Saas业务系统中业务订单号与支付订单号是一对一的关系或者没有支付订单号的情况那么两个订单号都填写业务订单号即可。4.推荐不要超过32位扫码、银行卡、扫脸
Saas系统业务订单号StringbusinessIdM1.Saas系统的业务订单号(字符串,不包含特殊字符),用于标识当笔交易属于哪一笔业务订单,交易处理结果中会带回。2.业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。3.如果Saas业务系统中业务订单号与支付订单号是一对一的关系或者没有支付订单号的情况那么两个订单号都填写业务订单号即可。4.最多50个字符长度扫码、银行卡、扫脸
原收银台流水号StringoriMisId特殊选项特殊选项N选一扫码、银行卡、扫脸
原Saas系统支付订单号StringoriOrderId特殊选项特殊选项N选一扫码、银行卡、扫脸
原商户(平台)订单号StringoriPlatformId特殊选项特殊选项N选一扫码、银行卡、扫脸
配置参数(UI、打印等参数配置)ConfigconfigC配置UI、打印等参数扫码、扫脸
交易过程中是否播报语音BooleanvoiceBroadcast(Config字段)Ctrue:播报语音;false:不播放语音注意: 1.扫码交易前金额播报、扫码交易结果播报,刷脸交易没有金额和交易结果语音播报2.默认以收银台设置的开关为准3.此参数对金融设备无效,扫码
是否打印小票BooleanprintTicket(Config字段)C为true时打印;为false时不打印;默认打印(兼容老字段)扫码、银行卡、扫脸
指定签购单上的退款订单号类型StringprintIdType(Config字段)C订单类型:“mis”:收银台水号;“order”:Saas软件订单号“platform”商户(第三方)订单号:不传值时默认不打印,参数值传错则返回参数错误扫码、扫脸
备注StringRemarks(Config字段)C打印小票上的备注(200个字符以内)扫码、扫脸

Response

数据项数据类型(默认String)标识是否必填(M/C)说明适用范围
交易结果返回码StringresultCodeMT00:成功非T00:失败, 见返回码定义(附录B)扫码、银行卡、扫脸
返回码描述StringresultMsgC 扫码、银行卡、扫脸
应用类型StringappTypeC00:银行卡应用01:聚合扫码支付应用02:银行卡+银联扫码支付应用51:刷脸支付扫码、银行卡、扫脸
交易类型StringtransTypeM09-退款扫码、银行卡、扫脸
收银台流水号StringmisIdM用于标识当笔交易的订单号,交易处理结果中会带回。扫码、银行卡、扫脸
Saas系统退款单号StringorderIdM1.Saas系统的支付订单号(字符串,不包含特殊字符),用于标识当笔交易的支付订单号,交易处理结果中会带回。2.业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。3.如果Saas业务系统中业务订单号与支付订单号是一对一的关系或者没有支付订单号的情况那么两个订单号都填写业务订单号即可。扫码、银行卡、扫脸
Saas系统业务订单号StringbusinessIdM1.Saas系统的业务订单号(字符串,不包含特殊字符),用于标识当笔交易属于哪一笔业务订单,交易处理结果中会带回。2.业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。3.如果Saas业务系统中业务订单号与支付订单号是一对一的关系或者没有支付订单号的情况那么两个订单号都填写业务订单号即可。扫码、银行卡、扫脸
原Saas软件订单号StringoriOrderIdC 扫码、银行卡、扫脸
原收银台流水号StringoriMisIdM 扫码、银行卡、扫脸
商户(第三方平台)订单号StringplatformIdC商户(第三方平台)订单号(微信、支付宝客户端显示的订单号,银行卡交易则返回系统参考号)扫码、银行卡、扫脸
支付方式StringplatformMwxpay:微信支付alipay:支付宝支付unionpay:银联钱包支付card:银行卡支付扫码、银行卡、扫脸
交易金额LongamountM单位为分,1元表示为100L扫码、银行卡、扫脸
交易日期StringtransDateC格式“MMdd” 扫码、银行卡、扫脸
交易时间StringtransTimeC格式“HHmmss” 扫码、银行卡、扫脸
凭证号StringvoucherNumC撤销、查询、打印使用银行卡
批次号StringbatchNumC 银行卡
系统参考号StringreferenceNumC部分业务退货使用银行卡
卡号StringcardNumC脱敏处理规则:除前六位和后四位之外其余位变*号处理。银行卡
发卡行StringissuerC 银行卡
收单行StringacquirerC 银行卡
操作员号StringoperatorIdC 银行卡
卡类型StringcardTypeCIC、NFC、MAG银行卡
账户类型StringaccountTypeC“OA”:扫码”CC”:贷记卡
“DC”:借记卡
“SCC”:准贷记卡”EC”:电子现金
“MAG”:磁条卡
“VC”:Visa卡
“MC”:MasterCard 万事达卡
“AE”:美国运通卡
“JCB”:JCB卡是源自日本的世界通用国际信用”RPC”:RuPay(India)印度卡
银行卡
机型StringmodelCPOS外设型号银行卡
版本StringversionCPOS应用版本扫码、银行卡、扫脸
终端号StringterminalIdC 扫码、银行卡、扫脸
商户号StringmerchantIdC 扫码、银行卡、扫脸

消费 (扫码、银行卡、扫脸)

消费 (扫码、银行卡、扫脸)

Request

数据项 数据类型(默认String) 标识 是否必填(M/C) 说明 适用范围
应用类型 String appType C(收银台1.4.60及以上版本选填,以下必填) 00:银行卡应用;01:聚合扫码支付应用; 02:银行卡+银联扫码支付应用;51:扫脸支付。appType为空或者传01且paycode为空:如果设备支持刷脸,则显示刷脸和扫码二合UI。 扫码、银行卡、扫脸
应用Id String appId M 应用包名,android APP程序packagename 扫码、银行卡、扫脸
交易类型 String transType M 00-消费         扫码、银行卡、扫脸
交易金额 Long amount M 单位为分,1元表示为100L,最多12位 扫码、银行卡、扫脸
Saas系统支付订单号 String orderId M 1.Saas系统的支付订单号(字符串),用于标识当笔交易的支付订单号,交易处理结果中会带回。2.业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。3.如果Saas业务系统中业务订单号与支付订单号是一对一的关系或者没有支付订单号的情况那么两个订单号都填写业务订单号即可。4.推荐不要超过32位 扫码、银行卡、扫脸
Saas系统业务订单号 String businessId M 1.Saas系统的业务订单号(字符串,不包含特殊字符),用于标识当笔交易属于哪一笔业务订单,交易处理结果中会带回。2.业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。3.如果Saas业务系统中业务订单号与支付订单号是一对一的关系或者没有支付订单号的情况那么两个订单号都填写业务订单号即可。4.最多50个字符长度 扫码、银行卡、扫脸
商品信息 String orderInfo C 商品名称或者其他商品信息。 扫码、银行卡、扫脸
配置参数(UI、打印等参数配置) Config(实体) config C 配置UI、打印等参数 扫码、扫脸
  交易是否轮询 String pollingType(Config字段) C polling:轮询,收银台发起交易后,如果云端返回的交易结果状态为中间状态(支付中),由收银台自动轮询做交易查询直至查询到交易的最终结果(成功或失败或超时),收银台轮询时间最长为120s; not_polling: 不轮询,收银台发起交易后,直接将云端交易结果返回给调用方,如果返回中间状态的交易结果,应由调用方去查询交易的最终结果; 注意: 1.默认是polling模式2.当交易返回码为D01、D07、F01、F02、Q02、Q04、Q07、Q11、
Q14、
S01、S02、S03(具体意义见附录B)的交易需要设计一个状态不明的订单状态并保存此订单等待后续追溯,可以在交易结果页放置一个查询按钮,由用户点击后发起查询3. 不传值默认是polling模式,参数值传错则返回参数错误
扫码、扫脸
  交易过程中是否播报语音 Boolean voiceBroadcast(Config字段) C true:播报语音;false:不播放语音 注意: 1.扫码交易前金额播报、扫码交易结果播报,刷脸交易没有金额和交易结果语音播报2.默认以收银台设置的开关为准3.此参数对金融设备无效,  扫码
  是否打印小票 Boolean printTicket(Config字段) C 为true时打印;为false时不打印;默认打印(兼容老字段) 扫码、银行卡、扫脸
  指定签购单上的订单号类型 String printIdType(Config字段) C 订单类型:mis:商米收银台流水号order:Saas软件订单号“platform”商户(第三方)订单号(银联扫码不支持),不传值默认打印商米收银台流水号,参数值传错则返回参数错误 扫码、扫脸
  备注 String remarks(Config字段) C 打印小票上的备注(200个字符以内) 扫码、扫脸

继续阅读

术语定义和产品介绍

1 范围

本部分内容定义了Saas业务App与商米收银台的通讯接口。

2 术语定义

Saas应用软件

商户Android收银机中的应用软件,如ERP等App应用。

收银台接口

用于传递Saas应用软件与商米收银台交易指令。

收银台流水号-misId

商米订单号,用于标识当笔交易的订单号,交易处理结果中会带回。

Saas系统支付订单号-orderId

App自定义的字符串(不包含特殊字符),用于标识当笔交易的Saas软件订单号,交易处理结果中会带回。

Saas系统业务订单号-businessId

业务订单号与支付订单号的关系:一个业务订单号可以对应多个支付订单号,比如用户买了一件商品后会产生一个业务订单号和一个消费支付订单号,用户将此商品退款后又会产生一个退款的支付订单号。

商户(第三方平台)订单号- platformId

商户(第三方平台)订单号(微信、支付宝客户端显示的订单条形码)。

3 商米的产品

商米的产品分为:手持设备(V系列、L2、M2)、台式设备(T系列、D系列)、

自助设备(K系列)、金融设备(P系列)

4 系统结构

介绍

 调用方法

商米收银台在android系统中使用Service对外提供调用接口,使用附录A提供jar包,传入JSON格式的调用参数启动Service,唤起收银台,交易结束后商米收银台会通过定向广播通知Saas应用软件(action为sunmi.payment.action.result)。实例代码见附录A。

交易类型

— — 00-消费

— — 03-预授权

— — 05-预授权完成

— — 09-退款

— — 10-取消交易A1-打印

— — A2-单笔交易记录查询

— — A3-批量交易记录查询

 接口与参数说明

    关于Response参数的说明:是否必填栏的M参数是指交易成功的情况下必须返回。

支付接口对接常见问题解答

  • 收不到交易结果广播怎么办?
    • 原因:收不到交易结果广播主要原因是SaaS程序发送交易请求到收银台后程序奔溃或被人为关闭
    • 如何解决:
      • 应用再次启动,对于没有结果的订单,应该要有查询机制
      • 对接商米云端回调接口,交易结果最好以云端交易通知为最终结果
  • 个别返回码、异常处理方案是什么?
    • 返回码为D01、D07、F01、F02、Q02、Q04、Q07、Q11、Q14、S01、S02、S03的交易需要设计一个状态不明的订单状态,可以在交易结果页放置一个查询按钮,点击后发起查询
    • D05表示交易已经成功,当作成功处理就可以了,这个返回码不用当异常处理
    • Q09表示重复请求,业务方自定义处理方式,不处理或者设计一个防止连续点击的机制都可以
    • 其他错误码:根据不同的错误码提示收银员和消费者对应的文案即可(见Excel)
  • 目前没有支付撤销接口?
    • 退款接口即支付撤销也支持退货,调用方不需要区分直接调用即可。
  • 用户发起10元的支付,收银台返回【网络超时】,但实际用户支付成功,如果用户支付成功,商米是否主动发起退款?建议业务方如何处理?
    • 商米不会主动发起退款,业务方可以调用云端的关单接口(正在开发中)关闭订单退回款项,也可以调用查询接口查明订单状态后做对应处理。
  • 支付时,通过广播拿到的支付结果到底有多精准?若是有广播拿到的结果是失败或者超时,但是客户那边已经扣款了,怎么处理此种情况?
  • 正常情况结果广播的到达率和准确率都是100%,除非在接到结果之前设备断电了,业务方可以调用云端的关单接口(正在开发中)关闭订单退回款项,也可以调用查询接口查明订单状态后做对应处理。
  • 目前的支付超时是120秒,正常来讲,哪怕用户没事,等120秒也会有些焦躁,那么怎么可以取消当前进行的支付,重新发起支付呢?
    • 商米会提供关单接口(正在开发中)
    • 可以不使用默认的轮训模式不用等待120秒,参考 交易是否轮询
  • 接口返回错误码Q09请求正在处理中,这种情况,再发起支付是不是无法发起交易了?
    • 需要等到前一笔交易返回,收银台只允许同时进行一笔交易
  • Q09请求正在处理中,这种情况为什么没有流水号
    • 这个只是告知调用方有正在进行的交易,这次请求不算一笔交易
  • 交易失败为什么有的有交易号,有的没有交易号呢?
    • 如果是终端判断失败,请求没有发送到云端,就不会有交易号。
  • 交易金额/实付金额/优惠金额 具体业务定义
    • 交易金额指的是商户当笔交易的收款金额,在调用支付接口时传入
    • 实付金额是指支付通道方在活动期间补贴消费者一定优惠金额后,消费者的实际付款金额,在交易完成由后返回
    • 优惠金额即支付通道在活动期间的补贴金额,在交易完成由后返回