---
# System prepended metadata

title: 9C - YGR SEAMLESS WALLET API

---

# 9C - YGR SEAMLESS WALLET API 
[TOC]


## 修改歷程
:::info
* 初版
> [time=Thu, Feb 24, 2022 16:51 PM] 
* 1.1 新增老虎機流程圖, 與寫入賽果API(3.1)
> [time=Wed, Apr 13, 2022 16:33 PM]
* 1.2 新增錢包端回傳的錯誤碼定義
> [time=Tue, Apr 19, 2022 09:37 AM]
* 1.3 新增9C專用公司代碼參數
> [time=Wed, Apr 20, 2022 16:00 AM]
* 1.4 新增5.4, 5.5兩隻查詢注單的API
> [time=Wed, May 25, 2022 10:00 AM] 
:::


## 貴司服務的格式
* Request網址: https://{wallet-host}/{action}
* Content-Type: appliction/json

## 請求內容
* 使用貴司系統時, 須在每次請求Header加入固定的 Authorization, 其參數由貴司提供

| Parameter | Type | Value | Description|
|:--------- |:------ |:------- |:------ |
|Authorization  |String|遊戲商token|由貴司提供|

每次回傳皆包含參數status，其代表此次請求之詳細狀況，詳細規格如下 :

| Parameter | Type | Description |
|:--------- |:------ |:------- |
|code |	String | 回應代碼，請參照下方定義。|
|message | String |	回應詳細訊息，為此次請求之回應狀況。|
|dateTime |	DateTimeOffset | 回應時間，記錄此次請求之接收時間。|
|traceCode | String	| 回應追蹤碼，用於查詢此次請求相關紀錄。|

## 注意事項
* 錢包API需設定白名單機制(IP), 遊戲商提供
* 時間格式皆為 RFC3339

## 錯誤碼定義
| ErrCode | Error Message(CN) | Error Message(EN)|
|:--------|:--------|:--------|
|0|成功|Success|
|101|API配置錯誤|API Config Error|
|102|簽名無效|Sign invalid|
|103|API錯誤|API failed|
|104|服務維護中|Under maintence|
|105|IP不允許訪問|IP not allowed to access api|
|106|API超時|API timeout|
|201|參數錯誤|Bad parameter|
|202|帳號重複|Account duplicated|
|203|交易編號重複|Transaction ID duplicated|
|204|餘額不足| Insufficient balance|
|205|帳號不存在|Account not exist|
|206|遊戲不存在|Game not exist|
|208|注單編號重複|Round ID duplicated|
|401|未授權|Unauthorized|
|404|沒有找到|Not Found|
|999|未經定義的錯誤|Something wrong|

## 老虎機遊戲流程
![](https://i.imgur.com/N026ZsB.png)

## 捕漁機遊戲流程
![](https://i.imgur.com/7Ns1VIT.png)

## 錢包端API

### 1.0 取得測試token
* 說明
    * 創建測試用token，可於測試環境中使用(正式環境禁止使用)
    * 測試用token對應到的測試帳號, 裡面需要有測試用的額度
    
* HTTP METHOD
    * GET
* action
    * /token/createGuestConnectToken
    
* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |account |	String | 會員帳號 |
    |currency | String | 幣別(ISO4217)|
    |gameID |	String | 遊戲代碼|
    
    ```json=
    /token/createGuestConnectToken?account=guest2541&currency=CNY&gameID=10001
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data
    
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | connectToken |String | 連線token |
        
    ```json=
    {
        "data": {
            "connectToken": "eebb8fd437b34282b65a6524541fddeb"
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
### 1.1 驗證token
* 說明
    * 使用令牌前, 需先驗證令牌, 並取得該令牌登入的相關資訊
    * token使用期限為600秒
    * 驗證token後, 將移除token使用期限
    * token不能重複驗證
    * ownerId可以與parentId相同

* HTTP METHOD
    * POST
* action
    * /token/authorizationConnectToken

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    
    ```json=
    {
        "connectToken": "eebb8fd437b34282b65a6524541fddeb"
    }
    ```

* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | ownerId |String | 上層代理編號 |
    | parentId |String | 子代理編號 |
    | companyId |String | 公司代碼 |
    | gameId |String | 遊戲編號 |
    | userId |String | 會員編號 |
    | nickname |String | 會員名稱 |
    | currency |String | 幣別（ISO4217）  |
    | amount |Decimal | 額度(小數點後兩位) |    
    ```json=
    {
        "data": {
            "gameId": "10001",
            "userId": "ARWA32144115",
            "nickname": "Kevin",
            "ownerId": "yahucny001",
            "parentId": "yahucny001_1",
            "companyId": "9c",
            "currency": "CNY",
            "amount": 12345.67
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```

### 1.2 取得token額度
* 說明
    * 查詢該令牌對應到的錢包的餘額
    
* HTTP METHOD
    * GET

* action
    * /token/getConnectTokenAmount

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    |companyId |	String | 公司代碼 |
    
    ```json=
    /token/getConnectTokenAmount?connectToken=eebb8fd437b34282b65a6524541fddeb&companyId=9c
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | currency |String | 幣別（ISO4217）  |
    | amount |Decimal | 額度(小數點後兩位) |    
    ```json=
    {
        "data": {
            "currency": "CNY",
            "amount": 12345.67
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
### 1.3 刪除Token
* 說明
    * 會員離線後, 使令牌失效
    
* HTTP METHOD
    * POST

* action
    * /token/delConnectToken

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    |companyId |	String | 公司代碼 |
    ```json=
    {
        "connectToken": "eebb8fd437b34282b65a6524541fddeb",
        "companyId": "9c"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    
    ```json=
    {
        "data": {},
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
### 2.1 取得遊戲注單號
* 說明
    * 取得遊戲注單的號碼
    
* HTTP METHOD
    * GET

* action
    * /betSlip/getSequenceNumbers

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |quantity |	int | 欲取得的數量 |
    |companyId |	String | 公司代碼 |
    ```json=
    /betSlip/getSequenceNumbers?quantity=2&companyId=9c
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |sequenceNumber|string[]|注單號碼(Array)|
    
    ```json=
    {
        "data": {
            "sequenceNumber": [
                "1016321731",
                "1016321732"                
            ]
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
### 3.1 寫入遊戲賽果(老虎機)
* 說明
    * 老虎機轉輪時告知錢包端輸贏結果

* HTTP METHOD
    * POST

* action
    * /transaction/addGameResult

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    |transID | String | 交易編號 |
    |roundID | String | 注單編號 |
    |betAmount | Decimal | 投注額度 |
    |payoutAmount | Decimal | 賠付額度 |
    |winLoseAmount | Decimal | 輸贏額度 |
    |wagersTime| String ｜投注時間(使用RFC3339)| 
    ```json=
    {
        "connectToken": "eebb8fd437b34282b65a6524541fddeb",
        "transID": "3016321731",
        "roundID": "3016321731",
        "betAmount": 10.00,
        "payoutAmount": 6.00,
        "winLoseAmount": -4.00,
        "wagersTime": "2001-02-03T04:05:06.789+08:00"
    }
    ```

* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |currency | String |幣別(使用ISO 4217)|
    |balance | Decimal |錢包餘額 |
    
    ```json=
    {
        "data":{
            "balance" : 400.2,
            "currency" : "CNY"
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```

### 3.2 個人錢包轉至遊戲錢包(捕魚機)
* 說明
    * 從平台端將會員額度轉至遊戲端
    
* HTTP METHOD
    * POST

* action
    * /transaction/rollOut

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    |companyId |	String | 公司代碼 |
    |transID | String | 交易編號 |
    |roundID | String | 注單編號 |
    |amount | Decimal | 取款額度(顯示至小數點後兩位)|
    |takeAll | Boolean | 是否取出全部額度 |
    |rollTime | String | 取款時間(使用RFC3339)| 
    
    ```json=
    {
        "connectToken": "eebb8fd437b34282b65a6524541fddeb",
        "companyId": "9c",
        "transID": "3016321731",
        "roundID": "3016321731",
        "amount": 10.00,
        "takeAll": false,
        "rollTime": "2001-02-03T04:05:06.789+08:00"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |currency | String |幣別(使用ISO 4217)|
    |balance | Decimal |錢包餘額 |
    |amount | Decimal | 取款額度 |
    
    ```json=
    {
        "data":{
            "amount": 10,
            "balance" : 400.2,
            "currency" : "CNY"
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
### 3.3 遊戲錢包轉至個人錢包(捕魚機)
* 說明
    * 從遊戲端錢包額度轉至平台端將會員錢包
    
* HTTP METHOD
    * POST

* action
    * /transaction/rollIn

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    |companyId |	String | 公司代碼 |
    |transID | String | 交易編號 |
    |roundID | String | 注單編號 |
    |amount | Decimal | 取款額度(顯示至小數點後兩位)|
    |rollTime | String | 取款時間(使用RFC3339)| 

    
    ```json=
    {
        "connectToken": "eebb8fd437b34282b65a6524541fddeb",
        "companyId": "9c",
        "transID": "3016321731",
        "roundID": "3016321731",
        "amount": 10.00,
        "rollTime": "2001-02-03T04:05:06.789+08:00"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |currency | String |幣別(使用ISO 4217)|
    |balance | Decimal |錢包餘額 |
    
    ```json=
    {
        "data":{
            "balance" : 400.2,
            "currency" : "CNY"
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
### 3.4 退款(取消注單, 僅捕魚機可用)

* 說明
    * 取消注單, 將該額度從遊戲錢包退回個人錢包
    * 退款的參數transID, 必須與rollOut的相同
    * 已經rollIn後, 結束的局無法執行退款
    * 已經refund過的局, 無法再次refund 
    
* HTTP METHOD
    * POST

* action
    * /transaction/refund

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |connectToken |	String | 連線token |
    |companyId |	String | 公司代碼 |
    |transID | String | 交易編號 |
    |refTime | String | 退款時間(使用RFC3339)| 

    
    ```json=
    {
        "connectToken": "eebb8fd437b34282b65a6524541fddeb",
        "companyId": "9c",
        "transID": "3016321731",
        "refTime": "2001-02-03T04:05:06.789+08:00"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object | 回應數據 |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |currency | String |幣別(使用ISO 4217)|
    |balance | Decimal |錢包餘額 |
    
    ```json=
    {
        "data":{
            "balance" : 400.2,
            "currency" : "CNY"
        },
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
### 補單機制(捕魚機)
* 平台端有rollout, 有rollin, 遊戲端DB也有注單數據 ===> 完整的一回合
* 平台端有rollout, 沒有rollin, 遊戲端DB沒有注單數據 ===> 遊戲端執行refund取消該筆交易
* 平台端有rollout, 沒有rollin, 遊戲端DB有注單數據 ===> 遊戲端查詢DB注單數據後, 補送rollin

### 4.1 取得未完成注單列表

* 說明
    * 查詢時間區段內, 有哪些注單是有執行rollout, 沒執行過rollin的列表
    * 每筆數據中需提供對應的connectToken, 協助遊戲端可以在必要時執行補單或是取消的API

* HTTP METHOD
    * POST

* action
    * /betSlip/roundCheck

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |companyId |	String | 公司代碼 |
    |fromDate |	String | 開始時間(RFC3339) |
    |toDate | String | 結束時間(RFC3339) |
    
    ```json=
    {
        "companyId": "9c",
        "fromDate": "2022-02-03T00:00:00.000+08:00"
        "toDate": "2022-02-03T01:00:00.000+08:00"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | data |	Object[] | 回應數據(陣列) |
    | status | Object | 回應狀態|
    
    * data

    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |transID | String |交易編號|
    |roundID | String |注單編號 |
    |amount  | Decimal|取款額度 |
    |connectToken|String|連線token|
    |rollTime| String |取款時間(RFC3339)| 
    
    ```json=
    {
        "data": [
            {
                "transID": "3016321731",
                "roundID": "3016321731",
                "amount": 500.00,
                "connectToken": "eebb8fd437b34282b65a6524541fddeb",
                "rollTime": "2022-02-03T00:14:13.997+08:00"
            },
            ...,
            ...,
            ...
        ],
        "status": {
            "code": "0",
            "message": "Success",
            "dateTime": "2001-02-03T04:05:06.789+08:00",
            "traceCode": "2acefc9a1ccb4dd78d3bd62037e79e9c"
        }
    }
    ```
    
## 遊戲端提供的API
* Request網址: https://{gamesrv-host}/{action}
* API Header - Content-Type設定為application/json
* 每次使用API必定會回傳200狀態碼，如有其他狀態碼則表示服務不通，或是服務路徑有錯
* 每個接口若有用到時區，時間時區為 UTC-04:00 美東時間(可討論修改)
* Response 返回格式, 下述遊戲端API的ResponseData都是Data欄位的內容
    * ResponseData
        | Parameter | Type | Description |
        |:--------- |:------ |:------- |
        |ErrorCode | Number |錯誤碼|
        |Message | String | 錯誤碼敘述 |
        |Data  | String| 返回的數據 |
    ```json=
    {    
        "ErrorCode":0,
        "Message":"",
        "Data":{
            ......
        }
    }
    OR
    {    
        "ErrorCode":0,
        "Message":"",
        "Data":[
            ......
        ]
    }
    ```
   
## 5.1 登入遊戲
* 說明
    * 會員登入遊戲的入口API
    * 登入時帶入連線token, 遊戲端後續會使用錢包端API對連線token進行認證
    * language 繁中(zh-TW), 簡中(zh-CN), 英文(en-US), 泰文(th-TH), 日文(ja-JP), 越南文(vi-VN)

* HTTP METHOD
    * GET

* action
    * /launch
    

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |token |	String | 連線token |
    |language| String | 使用語系 |
    
    ```json=
    /launch/?token=eebb8fd437b34282b65a6524541fddeb&language=zh-CN
    ```
    
* Response Data
    * 可自動跳轉Redirect(301)遊戲網址或是返回遊戲網址
    
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |url |	String | 遊戲連接網址 |
    
    ```json=
    {    
        "url": "https://abc.com/index.html?token=23523wtr23tr23^244"
    }
    ```
    
## 5.2 踢除token
* 說明
    * 將線上使用此支連線token的會員踢下線

* HTTP METHOD
    * POST

* action
    * /kickToken
    

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |adminAccount |	String | 操作人員帳號 |
    |token| String | 會員的連線令牌 |
    |reason|String | 踢除原因 |
    
    ```json=
    {    
        "adminAccount":"gm001",
        "token":"533f47774e194c199bb71a80e1db8e85",
        "reason":"suspicious behavior"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |

    
    ```json=
    {    
        "ErrorCode": 0,
        "Message": null,
        "Data": null
    }
    ```
    
|Error Code| Error Message(CN)| Error Message(EN) |
|:--------|:--------|:--------|
|0|成功|Success|
|90001|找不到該Token|Not Found this token|
    
## 5.3 確認token是否在線
* 說明
    * 確認線上使用此支連線token的會員是否在線

* HTTP METHOD
    * POST

* action
    * /isTokenOnline
    

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |adminAccount |	String | 操作人員帳號 |
    |token| String | 會員的連線令牌 |

    
    ```json=
    {    
        "adminAccount":"gm001",
        "token":"533f47774e194c199bb71a80e1db8e85"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    | isOnline|Boolean|是否在線|
    
    ```json=
    {    
        "ErrorCode": 0,
        "Message": "",
        "Data": {
            "isOnline": true
        }
    }
    ```

## 5.4 查詢時間區段內的所有注單列表
* 說明
    * 查詢時間區段內的所有注單列表

* HTTP METHOD
    * POST

* action
    * /GetBetRecordByDateTime
    

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |StartTime |	String | 起始時間 |
    |EndTime| String | 結束時間 |
    |PageLimit|Number|分頁回傳的最大筆數|
    |Page|Number|查詢第幾頁|
    
    ```json=
    {    
        "StartTime": "2022-05-10T03:00:00.000+08:00",
        "EndTime":"2022-05-10 04:00:00.000+08:00",
        "Page": 1,
        "Page": 1000
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |Result | Array of Object | 注單列表數據|
    |Pagination	| Object | 分頁數據|
    
* Pagination
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |CurrentPage | Number | 當前頁數 |
    |TotalPages | Number | 總頁數 |
    |PageLimit | Number | 每頁筆數 |
    |TotalNumber | Number | 總筆數 |
    
* Result
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |Account | String | 會員帳號 |
    |WagersId | String | 注單編號(同交易編號) |
    |GameId | String | 遊戲ID |
    |WagersTime | String | 注單時間 |
    |Currency | String | 貨幣類型 |
    |BetAmount | Number | 投注額 |
    |PayoffAmount | Number | 輸贏額 |


## 5.5 查詢單筆注單數據
* 說明
    * 查詢單筆注單數據

* HTTP METHOD
    * POST

* action
    * /GetBetRecordById

* Request Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |WagersId |	String | 注單編號(交易編號) |
    
    ```json=
    {    
        "WagersId": "ea8420e282eadfb3"
    }
    ```
    
* Response Data
    | Parameter | Type | Description |
    |:--------- |:------ |:------- |
    |Account | String | 會員帳號 |
    |WagersId | String | 注單編號(同交易編號) |
    |GameId | String | 遊戲ID |
    |WagersTime | String | 注單時間 |
    |Currency | String | 貨幣類型 |
    |BetAmount | Number | 投注額 |
    |PayoffAmount | Number | 輸贏額 |
    
    ```json=
    {
        "Account": "9sbons479762",
        "WagersId": "ea8420e282eadfb3",
        "GameId": "019",
        "WagersTime": "2022-05-10T03:15:07.930+08:00",
        "Currency": "USD",
        "BetAmount": 0.2,
        "PayoffAmount": -0.1,
    }
    ```