汽车票线下自助机接入参考

更新时间：2021/04/07 访问次数：13148

一、业务流程图：
二、正向交易描述
三、正常交易全流程概述
四、取消订单概述
五、退款交易流程
六、订单状态说明
七、关于分账
八、线下终端售票总账对账
九、汽车票自助机API列表

一、业务流程图：

* 注意数据安全保密，采用相应的加密规则加密。

二、正向交易描述

角色说明：本需求主要涉及6方角色，包括购票用户、终端机、终端服务器、代理商后台、飞猪、支付宝等。
各角色说明：
1）购票用户
该用户实际在车站购票，这些用户通过使用非车站窗口渠道购票即可快速选择车次并获取车票。
2）终端机
本终端机器为客运站自有终端，主要支持搜索、车次选择、购票等一系列用户端应用。
3）终端服务器
终端机直连服务器，该服务器内接车站站务器，可实时获取车次信息，并可以支持实时锁单出票等处理。
4）代理商
如 “中国公路客票网”。所有涉及出票相关的交易控制，均由该代理商完成，代理商后台收款控制和整个交易控制都需要在我平台留痕处理。
注意：注册app的淘宝对应的支付宝账户为默认的收款账户，票款会自动打入该账户。如果有分账，比如100块钱票款，98自己账户，2块钱车站账户，需要采用分账功能。具体参考分账章节。
5）飞猪
平台主要是确保用户可以正常购票，后续在出票过程中对交易进行控制，并提供相应用户体验提升。
6）支付宝
主要负责生成用户付款应用以及商户收单应用。

三、正常交易全流程概述

1）用户在车站窗口现场选择车次。

2）由车站服务器负责根据用户请求提供车次、报价数据。

3）用户确认下单，车站服务器自动完成锁座处理，并通知代理商后台。

4）代理商后台透传用户购票数据给飞猪创建订单（taobao.bus.tvmcreateorder.set）(如果有和车站进行分账的请参考[分账](https://open.alitrip.com/docs/doc.htm?spm=a21tt.7629140.0.0.mx1CCS&treeId=276&articleId=106841&docType=1#s6))。

5）飞猪执行创建订单，记录相关订单信息（注意实名制 realname 传递 true必须传身份证，realname false 不需要传身份证）。

6）创建二维码（taobao.bus.tvmcreateqrcode.set），或者用户执行条形码扫码（taobao.bus.tvmpayorder.set）
      如果是二维码：飞猪收到代理商请求，支付宝收到飞猪请求支付，生成二维码，并通过飞猪、代理商服务器直接传输到购票服务终端。如果是条形码：飞猪直接扣除票款。

7）用户扫码支付：用户使用支付宝app扫码实现支付或者条形码支付，并由飞猪监听支付宝结果，在规定的时间内（当前为5-15分钟（业务方自行控制）有效）完成付款，飞猪会通过异步消息（taobao_bus_TVMTradePay）通知代理商付款完成，消息接入请参考[消息接入文档](https://open.alitrip.com/doc2/detail.htm?treeId=2&articleId=101663&docType=1)
      注意：代理商应该接收异步消息和查询订单状态相结合的方式（查询频率建议3s）确定支付结果

8）车站服务器收到支付完成通知，并实现立即出票。

9）通知飞猪出票：（taobao.bus.tvmbookorder.set），如果出票成功：success = true，并告知支付方式（目前取值范围ALIPAY; WECHAT; BANKCARD;CASH; ），此时飞猪进行划拨账款到商家账号，涉及分账的，会分账到每个账号； 如果出票失败：success = false，并告知支付方式（目前取值范围ALIPAY; WECHAT; BANKCARD;CASH;）此时飞猪会将采用飞猪渠道支付的用户付款原路返回，注意：不需要代理商调用退款接口，飞猪会自动原路退给用户。

10）车站自助机为用户打印车票，交易完成

注意：

1）用户切换支付方式，如二维码切换到现金，需要调用二维码失效接口（taobao.bus.disableqrcode.set），用户再切回二维码，需要重新创建二维码。

2）用户退出该班次，重新选定车次，应该调用取消订单接口（cancel），然后应该重新下单，并且保证新订单代理商agent_order_id 不能重复。

异常情况处理：

1）创建飞猪订单失败，业务方自行控制重试，如果还是失败建议走原始自助机流程。（这样的订单希望记录下来，反馈飞猪双方排查问题 ）

2）如果用户付款了，但是自助机一直未收到支付成功消息（网络或者支付宝问题等），业务方控制超时时间，直接调用取消订单接口。

3）代理商调用出票成功或者出票失败接口超时，或者网络异常未成功，订单状态一直是已支付待出票，需要对账接口中查询前一天或者之前单未出票的单子，代理商确认该单到底是否出票，调用出票接口，飞猪完成划款或者给客户退款；或者通过单个订单查询接口获取订单状态，根据实际出票情况再重新调用出票接口。

4）注意：退款接口只适用于出票成功之后的退款，不支持未出票退款。

四、取消订单概述

1）未支付情况下，或者支付结果未知可取消订单。
2）已经支付成功的，出票结果必须调用出票接口告知失败或成功，不能调用取消订单接口。

五、退款交易流程

注：只有飞猪订单状态是出票成功的才能进行退款，也就是说退款是发生在出票之后，用户要退掉票款或者代理商因为其他原因要进行退款可调用此接口，（taobao.bus.tvmrefundorder.set），出票失败不用调用退款，需调用出票接口，告知失败，飞猪会自动退款给客户。
退款接口可以分多次调用，分多批次退款。
1）资金逆向整体说明
整体逆向交易是按照实际情况执行逆向处理。飞猪不会对异常交易做逆向处理。如正常的退款交易。建议终端不能支持用户请求主动退票交易，不予支持逆向退款处理。但其他异常交易情况按照2）、3）流程操作。
2）用户出票超时逆向处理
飞猪会监听用户支付结果，并将消息及时反馈给前端。但当用户付款后会优先存入中间担保账户，待代理商确认出票完成会立即拨款到代理商账户。但如果由于网络原因等没有收到地代理商出票成功调用，票款不会主动划拨入代理商账户。后续需要代理商在对账环节（或者查询订单环节）补上出票成功调用。
3）用户出票失败处理
代理商需明确提供出票状态。飞猪会根据代理商状态判断后续应用规则，如果代理商明确说明出票失败，将由飞猪直接给用户退款。

其他注意事项

1）飞猪通知支付宝后台获取支付码，并生成二维码支付控制。通知支付宝支付失效时间。
2）飞猪后台不会处理用户是否购买保险，代理商只要把总金额传给飞猪后台即可。
3）代理商如有自售保险，需增加保险购买的标示和对应的金额，以便应对逆向交易中，用户申请单独退保退款操作。
4）飞猪后台记录支付宝订单流水号，并待后续对账使用。
5）飞猪后台记录对应的出票状态，代理商需要及时通知。

六、订单状态说明

由于订单只是记录应用，所以不涉及锁单出票流程，整个订单状态可参考如下：
1）已创建，待支付
2）已支付，待出票
3）已支付，等待出票
4）交易完成
5) 取消出票

具体以接口为准
CREATED_NO_PAY(10, “已创建，待支付”), PAYED_NO_NOTIFY(20, “已支付，待通知代理商”), PAYED_AND_NOTIFY(30, “已支付，待代理商出票”), BOOKED_AND_CONFIRM(50, “已出票，已确认”), BOOK_FAILED(-1, “出票失败”), PAY_TIME_OUT(-2, “支付超时”), BOOK_TIME_OUT(-3, “出票超时”), CANCEL(-4, “订单取消”), CLOSE(-5, “订单关闭”);

七、关于分账

分账接口适用于：1、和车站有分成，比如100票款，自己支付宝划拨98块，车站支付宝划拨2块。
具体调用接口：在创建订单接口中传入分账明细创建订单（taobao.bus.tvmcreateorder.set）
参数：account_in_details 分润账户明细列表，是个数组，有几个分账，写几个，分账多少钱由代理商接口控制，飞猪不校验（比如上面100块钱例子，应该写代理商支付宝账号 98块，xx车站支付宝2块）。注意只有需要分润到多账号才需要填，不需要分账，全部进入自己支付宝的否则为空，不需要传递该参数。分账总和等于订单总价。

八、线下终端售票总账对账

接口 taobao.bus.historyorder.get （历史订单会保留近2个月的订单）

注意：建议代理商第二天对前一天的订单进行核对，对于因为网络问题导致出票接口没有调用成功导致没有划款的订单，补调用出票成功接口。

提供代理商调取总账对账接口，分日汇总接口和日明细双接口。
汇总接口：
代理商按日期查询当日累计售票汇总情况，返回主要接口：创建订单数、支付订单数（仅支付宝）、支付总金额（仅支付宝）、退款申请订单数、退款金额（仅支付宝）、支付手续费（需要运营提供支付结算手续费费率，后台根据单笔金额乘费率后并以汇总计算）、应结金额。
明细接口：
按代理商实际日出票明细，提供单日每一笔订单详情信息查询接口，主要涉及字段：飞猪订单号、代理商订单号、支付宝支付流水号（如有）、支付状态（支付成功和退款完成、未退款）、出票状态（含已支付和已取消）、金额。

除了可以采用这种统一对账方式外，建议商家每天晚上对当天的订单每笔调用查询订单接口，看下状态是否是已出票，做一下核对，如果你们是出票了，可能网络或者其他原因，我们这边还没有出票，你们补调用一下出票成功接口，这样钱才能回款到商家支付宝账号，这样可以解决钱款对账问题，还有就是不会导致今天的钱明天才打给你们。