文 / 城轨易行项目组

整体介绍

城轨易行SDK是城轨易行平台面向各个互联互通城市的城轨官方APP封装的出行能力组件。易行SDK采用提供类似小程序页面的方式，便于各个城轨官方APP快速便捷的接入城轨易行平台，同时具备全部出行相关的功能。

城轨易行SDK借助于城轨官方APP的载体，主要提供以下功能：脱机/联机生码、蓝牙回写、互通城市列表查询、用户注册开通、实名认证及绑卡、乘车码页（请码、发授授权及生码等）、行程信息和行程消费信息的推送及展示等。如下图所示：

安全规范

为了防止参与业务各方之间交易过程中报文信息被恶意篡改，业务各方之间的交易报文要求实现签名，以保证交易的安全性。服务请求方实现对请求参数数据的签名，服务提供方根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。同时，为了保证通信的私密性，服务请求方需要对通信的敏感信息做对称加密处理，避免通信过程中敏感性信息的泄漏。

系统采用RSA2、RSA两种方式对移动应用和后台对话的授权进行签名，以及对SDK发起的业务如（发码授权、规则同步等）进行签名。除对会话进行签名外，为了防止敏感信息泄露，交易报文中的敏感字段也需要加密传输，加密算法采用AES对称算法。易行SDK生成16位随机码(数字+字母)作为加密秘钥，经易行平台公钥加密后将秘钥同步给易行平台。每次发起报文之前加密秘钥都会采用最新秘钥进行传输。

业务场景及流程

二维码运用到乘客在地铁等交通工具的通行过程中，乘客只需用移动终端通过手机支付，并凭移动终端生成的二维码即可实现地铁“刷码过闸”，解决地铁购票效率低、客流高峰期排队购票时间长、车票单次使用成本大等问题，为乘客提供便捷的出行体验。

以下为基本的核心业务流程：

1.城轨易行服务开通流程

地铁官方App用户要使用城轨易行乘车码服务，就必须先进行城轨易行开通操作。其业务说明如下：

（1）地铁官方APP采用集成城轨易行SDK方式提供城轨易行乘车码服务；

（2）用户在首次使用城轨易行乘车码服务时，城轨易行SDK会展示服务开通用户协议页面；

（3）用户点击同意协议后，城轨易行SDK会通知地铁官方APP进行城轨易行服务开通；

（4）地铁官方APP在收到服务开通通知后，会向易行平台发起服务开通请求，将用户实名信息发送给城轨易行平台；

（5）城轨易行平台接收到请求，判断请求合法后即对数据进行解析处理，按服务开通注册手机号进行用户注册，并保存用户实名信息，并将处理结果返回地铁官方APP；

（6）城轨易行SDK打开实名认证页面，用户进行实名信息确认以及提交；

（7）城轨易行SDK向城轨易行平台发起实名认证请求，城轨易行平台进行实名认证处理，并返回认证结果；

（8）城轨易行SDK接收到认证结果完成用户服务开通处理，即可使用乘车码服务。

2.城轨易行扫码乘车业务流程

城轨易行SDK旨在为用户提供跨区域的轨道交通出行移动支付基础服务，乘客可通过地铁官方APP生成的指定城市轨道交通乘车二维码即可实现“刷码过闸”，为乘客提供更多便捷的轨道交通出行体验。

以乘客持地铁官方APP请求乘车二维码进出站为例，其业务流程说明如下图：

流程具体说明如下：

（1）地铁官方APP采用集成城轨易行SDK方式提供城轨易行乘车码服务，用户在完成城轨易行服务开通操作后即可使用城轨易行乘车码服务；

（2）用户在地铁官方APP上点击使用“城轨易行乘车码”，调起城轨易行SDK提供的乘车码页面；

（3）城轨易行SDK发起请求授权及用户状态查询，当易行平台合法性校验通过后，返回会话授权签名给到城轨易行SDK；

（4）城轨易行SDK使用获取到的会话授权签名信息进行与城轨易行平台间会话处理； 城轨易行平台获取到地铁互联网票务平台的行业发码授权数据后，将数据返回城轨易行SDK；

（5）城轨易行SDK接收到授权数据后生成乘车二维码并进行展示；

（6）乘客持地铁官方APP展示的乘车二维码过闸；

易行SDK对移动应用开放的功能

1.SDK 初始化

为了让易行SDK能够在可信赖的移动应用中安全集成，在使用SDK前需要初始化用来校验移动应用的合法性。任何需要接入易行平台的应用，都需要在易行平台注册并获得对应的接入参数，任何SDK与易行平台之间的交互，都需要对appId，apiKey，platPubKey等参数进行加密和校验。

2.会话授权

为了让移动应用与易行平台建立信任关系，双方平台在交易前需要完成会话授权，只有在会话授权的有效期范围之内才SDK可以正常的请码。乘客使用接入SDK的移动应用，打开易行SDK中的乘车码页面，如果此时移动应用尚未获得会话授权，需要向易行平台发起会话授权申请。

（1）地铁官方APP集成SDK后首次使用或会话授权过期后需要进行授权处理。通过APP后台获取会话签名。

（2）在会话授权有效期内，地铁官方APP方能正常使用易行SDK提供功能。

（3）会话授权成功后，SDK记录会话授权信息，供其他服务使用。

3.打开乘车码页面

由于易行SDK采用带页面的方式，移动应用可以直接唤起SDK乘车码首页即可使用包括乘车码展示页面、城市列表页面、开通注册、行程列表、行程查询等功能。

4.用户注册开通

由于易用户必须先进行注册开通易行乘车码服务后，才能使用易行平台相关服务。

（1）易行SDK向地铁官方APP发起用户注册开通请求

（2）地铁官方APP则通过地铁官方APP后台向易行平台发起用户注册开通，并提交：注册手机号、姓名、身份证、银行卡、预留手机号信息，注册手机号为必填项；

（3）易行平台返回开通结果给地铁官方APP后台；

（4）地铁官方APP后台返回结果给地铁官方APP；

（5）地铁官方APP则将结果返回给易行SDK；

（6）易行SDK根据返回结果进行处理

5.清理授权信息

当移动应用升级后或者出现频繁的请码请求失败时，可以通过清理用户授权触发用户重新授权 。

（1）地铁官方APP可根据自身情况主动发起清理用户授权信息操作；

（2）易行SDK接收到请求后，则将对应用户授权信息清理。

6.消息通知

当用户扫码进站成功后，需要刷新当前的乘车二维码，防止同一个二维码被重刷。

（1）易行平台接收到用户行程消息或进行行程扣费后，将行程消息或行程扣费消息推送给地铁官方APP后台；

（2）地铁官方APP后台收到消息后将消息同步给地铁官方APP；

（3）地铁官方APP接收到消息后将消息同步给易行 SDK；

（4）易行SDK接收到消息后，自动刷新二维码并进行手机震动提示。