# 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|
## 老虎機遊戲流程
## 捕漁機遊戲流程
## 錢包端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¤cy=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,
}
```
Sign in with Wallet
Connect another wallet