文 / 城軌易行項目組

整體介紹

城軌易行SDK是城軌易行平臺面向各個互聯(lián)互通城市的城軌官方APP封裝的出行能力組件。易行SDK采用提供類似小程序頁面的方式，便于各個城軌官方APP快速便捷的接入城軌易行平臺，同時具備全部出行相關的功能。

城軌易行SDK借助于城軌官方APP的載體，主要提供以下功能：脫機/聯(lián)機生碼、藍牙回寫、互通城市列表查詢、用戶注冊開通、實名認證及綁卡、乘車碼頁（請碼、發(fā)授授權及生碼等）、行程信息和行程消費信息的推送及展示等。如下圖所示：

安全規(guī)范

為了防止參與業(yè)務各方之間交易過程中報文信息被惡意篡改，業(yè)務各方之間的交易報文要求實現簽名，以保證交易的安全性。服務請求方實現對請求參數數據的簽名，服務提供方根據請求參數，對簽名進行驗證，簽名不合法的請求將會被拒絕。同時，為了保證通信的私密性，服務請求方需要對通信的敏感信息做對稱加密處理，避免通信過程中敏感性信息的泄漏。

系統(tǒng)采用RSA2、RSA兩種方式對移動應用和后臺對話的授權進行簽名，以及對SDK發(fā)起的業(yè)務如（發(fā)碼授權、規(guī)則同步等）進行簽名。除對會話進行簽名外，為了防止敏感信息泄露，交易報文中的敏感字段也需要加密傳輸，加密算法采用AES對稱算法。易行SDK生成16位隨機碼(數字+字母)作為加密秘鑰，經易行平臺公鑰加密后將秘鑰同步給易行平臺。每次發(fā)起報文之前加密秘鑰都會采用最新秘鑰進行傳輸。

業(yè)務場景及流程

二維碼運用到乘客在地鐵等交通工具的通行過程中，乘客只需用移動終端通過手機支付，并憑移動終端生成的二維碼即可實現地鐵“刷碼過閘”，解決地鐵購票效率低、客流高峰期排隊購票時間長、車票單次使用成本大等問題，為乘客提供便捷的出行體驗。

以下為基本的核心業(yè)務流程：

1.城軌易行服務開通流程

地鐵官方App用戶要使用城軌易行乘車碼服務，就必須先進行城軌易行開通操作。其業(yè)務說明如下：

（1）地鐵官方APP采用集成城軌易行SDK方式提供城軌易行乘車碼服務；

（2）用戶在首次使用城軌易行乘車碼服務時，城軌易行SDK會展示服務開通用戶協(xié)議頁面；

（3）用戶點擊同意協(xié)議后，城軌易行SDK會通知地鐵官方APP進行城軌易行服務開通；

（4）地鐵官方APP在收到服務開通通知后，會向易行平臺發(fā)起服務開通請求，將用戶實名信息發(fā)送給城軌易行平臺；

（5）城軌易行平臺接收到請求，判斷請求合法后即對數據進行解析處理，按服務開通注冊手機號進行用戶注冊，并保存用戶實名信息，并將處理結果返回地鐵官方APP；

（6）城軌易行SDK打開實名認證頁面，用戶進行實名信息確認以及提交；

（7）城軌易行SDK向城軌易行平臺發(fā)起實名認證請求，城軌易行平臺進行實名認證處理，并返回認證結果；

（8）城軌易行SDK接收到認證結果完成用戶服務開通處理，即可使用乘車碼服務。

2.城軌易行掃碼乘車業(yè)務流程

城軌易行SDK旨在為用戶提供跨區(qū)域的軌道交通出行移動支付基礎服務，乘客可通過地鐵官方APP生成的指定城市軌道交通乘車二維碼即可實現“刷碼過閘”，為乘客提供更多便捷的軌道交通出行體驗。

以乘客持地鐵官方APP請求乘車二維碼進出站為例，其業(yè)務流程說明如下圖：

流程具體說明如下：

（1）地鐵官方APP采用集成城軌易行SDK方式提供城軌易行乘車碼服務，用戶在完成城軌易行服務開通操作后即可使用城軌易行乘車碼服務；

（2）用戶在地鐵官方APP上點擊使用“城軌易行乘車碼”，調起城軌易行SDK提供的乘車碼頁面；

（3）城軌易行SDK發(fā)起請求授權及用戶狀態(tài)查詢，當易行平臺合法性校驗通過后，返回會話授權簽名給到城軌易行SDK；

（4）城軌易行SDK使用獲取到的會話授權簽名信息進行與城軌易行平臺間會話處理； 城軌易行平臺獲取到地鐵互聯(lián)網票務平臺的行業(yè)發(fā)碼授權數據后，將數據返回城軌易行SDK；

（5）城軌易行SDK接收到授權數據后生成乘車二維碼并進行展示；

（6）乘客持地鐵官方APP展示的乘車二維碼過閘；

易行SDK對移動應用開放的功能

1.SDK 初始化

為了讓易行SDK能夠在可信賴的移動應用中安全集成，在使用SDK前需要初始化用來校驗移動應用的合法性。任何需要接入易行平臺的應用，都需要在易行平臺注冊并獲得對應的接入參數，任何SDK與易行平臺之間的交互，都需要對appId，apiKey，platPubKey等參數進行加密和校驗。

2.會話授權

為了讓移動應用與易行平臺建立信任關系，雙方平臺在交易前需要完成會話授權，只有在會話授權的有效期范圍之內才SDK可以正常的請碼。乘客使用接入SDK的移動應用，打開易行SDK中的乘車碼頁面，如果此時移動應用尚未獲得會話授權，需要向易行平臺發(fā)起會話授權申請。

（1）地鐵官方APP集成SDK后首次使用或會話授權過期后需要進行授權處理。通過APP后臺獲取會話簽名。

（2）在會話授權有效期內，地鐵官方APP方能正常使用易行SDK提供功能。

（3）會話授權成功后，SDK記錄會話授權信息，供其他服務使用。

3.打開乘車碼頁面

由于易行SDK采用帶頁面的方式，移動應用可以直接喚起SDK乘車碼首頁即可使用包括乘車碼展示頁面、城市列表頁面、開通注冊、行程列表、行程查詢等功能。

4.用戶注冊開通

由于易用戶必須先進行注冊開通易行乘車碼服務后，才能使用易行平臺相關服務。

（1）易行SDK向地鐵官方APP發(fā)起用戶注冊開通請求

（2）地鐵官方APP則通過地鐵官方APP后臺向易行平臺發(fā)起用戶注冊開通，并提交：注冊手機號、姓名、身份證、銀行卡、預留手機號信息，注冊手機號為必填項；

（3）易行平臺返回開通結果給地鐵官方APP后臺；

（4）地鐵官方APP后臺返回結果給地鐵官方APP；

（5）地鐵官方APP則將結果返回給易行SDK；

（6）易行SDK根據返回結果進行處理

5.清理授權信息

當移動應用升級后或者出現頻繁的請碼請求失敗時，可以通過清理用戶授權觸發(fā)用戶重新授權 。

（1）地鐵官方APP可根據自身情況主動發(fā)起清理用戶授權信息操作；

（2）易行SDK接收到請求后，則將對應用戶授權信息清理。

6.消息通知

當用戶掃碼進站成功后，需要刷新當前的乘車二維碼，防止同一個二維碼被重刷。

（1）易行平臺接收到用戶行程消息或進行行程扣費后，將行程消息或行程扣費消息推送給地鐵官方APP后臺；

（2）地鐵官方APP后臺收到消息后將消息同步給地鐵官方APP；

（3）地鐵官方APP接收到消息后將消息同步給易行 SDK；

（4）易行SDK接收到消息后，自動刷新二維碼并進行手機震動提示。