單一錢包 API

接入準備

告知使用單一錢包
提供給我方一個 callback 用網址

需實現的 callbacks

取餘額

請求時機: 於前台網頁中嘗試顯示或更新餘額時

我方 request 格式

欄位	類型	說明
cmd	“GetBalance”	命令標示符
uid	`string(255)`	用戶 ID
time	`datetime`	時間, 格式 `ISO 8601`
sign	`string(255)`	請求簽名請參考驗證 callback 簽名段落

範例

{
  "cmd": "GetBalance",
  "uid": "user001",
  "time": "2024-01-01T00:00:00",
  "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHQiOjk5OTk5OTk5OTksImppdCI6ImQ3MzY3YTE0LTkzZWUtNGQwYy1iODM1LTQ4YjJhMGIzYTI2OSJ9.YD5anPh4cOmqu1JusRB9cFJYJR-7th3crkBsttI5kTs"
}

期望 response 格式

欄位	類型	說明
errorMsg	`string(255) \| null`	失敗原因, 如果為 null 則為成功
balance	`decimal(10,2)`	用戶餘額, 失敗時可不填

接受(成功)範例

{
  "errorMsg": null,
  "balance": 10000
}

拒絕(失敗)範例

{
  "errorMsg": "用戶不存在 / 用戶已停用"
}

加扣點

請求時機: 機台上分/下分或其他異動時發出

我方 request 格式

欄位	類型	說明
cmd	”TradingPoints”	命令標示符
orderId	`string(64)`	訂單 ID
uid	`datetime`	用戶 ID
gametypeId	`string(255)`	遊戲類型 ID
gameRoundSerialNumber	`string(255)`	遊戲局號
machineId	`int32`	機台 ID
amount	`decimal(10,2)`	請求異動金額
reason	`string(255)`	請求事由
time	`datetime`	時間, 格式 `ISO 8601`
sign	`string(255)`	請求簽名請參考

加點範例

{
  "cmd": "TradingPoints",
  "orderId": "2a7fb6fe-37f2-47af-a79a-139de2eeaa93",
  "uid": "user001",
  "gametypeId": 1,
  "gameRoundSerialNumber": "20250101000000_m1",
  "machineId": 1,
  "amount": 100,
  "reason": "機台下分"
  "time": "2024-01-01T00:00:00",
  "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHQiOjk5OTk5OTk5OTksImppdCI6ImQ3MzY3YTE0LTkzZWUtNGQwYy1iODM1LTQ4YjJhMGIzYTI2OSJ9.YD5anPh4cOmqu1JusRB9cFJYJR-7th3crkBsttI5kTs"
}

扣點範例

{
  "cmd": "TradingPoints",
  "orderId": "cd36d0f2-632c-47a5-a9e9-9bdd9761d8f0",
  "uid": "user001",
  "gametypeId": 1,
  "gameRoundSerialNumber": "20250101000000_m1",
  "machineId": 1,
  "amount": -100,
  "reason": "機台上分"
  "time": "2024-01-01T00:00:00",
  "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHQiOjk5OTk5OTk5OTksImppdCI6ImQ3MzY3YTE0LTkzZWUtNGQwYy1iODM1LTQ4YjJhMGIzYTI2OSJ9.YD5anPh4cOmqu1JusRB9cFJYJR-7th3crkBsttI5kTs"
}

期望 response 格式

欄位	類型	說明
errorMsg	`string(255) \| null`	失敗原因, 如果為 null 則為成功

接受(成功)範例

{
  "errorMsg": null
}

拒絕(失敗)範例

{
  "errorMsg": "餘額不足"
}

加扣點檢查

請求時機: 每次交易後，我方會發出請求以確認交易是否成功

我方 request 格式

欄位	類型	說明
cmd	`"CheckOrderId"`	命令標示符
orderId	`string(64)`	訂單 ID

{
  "cmd": "CheckOrderId",
  "orderId": "2a7fb6fe-37f2-47af-a79a-139de2eeaa93",
  "time": "2024-01-01T00:00:00",
  "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHQiOjk5OTk5OTk5OTksImppdCI6ImQ3MzY3YTE0LTkzZWUtNGQwYy1iODM1LTQ4YjJhMGIzYTI2OSJ9.YD5anPh4cOmqu1JusRB9cFJYJR-7th3crkBsttI5kTs",
}

加扣點回滾

我方每個事件僅傳送一次請求

扣點失敗的情況

由於扣點失敗, 相當於餘額不足以進行操作, 玩家操作結果為失敗, 不須額外處理

加點失敗的情況

金額會先由我方扣除並保留於紀錄中, 處理步驟

使用查詢轉點回滾 (/users/trade_points_rollback)搜尋這些加扣點回滾
使用/accept_trade_points 標記完成這些加扣點請求

驗證 callback 簽名

簽名使用 JWT (HS256)，將完成的 jwt token 以 sign 作為屬性名加入請求中

密鑰(secret)

未來可以在後台自行變更, 目前可以自行提供, 默認我方生成後提供

JWT payload

claims	說明
exp	過期時間 (5 分鐘)
jit	WT ID, 用於防止重放攻擊, 在有效時間範圍內不重複(5 分鐘)

範例

密鑰: LeDubJdPoMme7lUogt7kBkQ5XfrF0C3lISOKjq1bJ0p1kAyysytAH5VxzatIY1oD

{
  "cmd": "GetBalance",
  "uid": "user001",
  "time": "2024-01-01T00:00:00",
  "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHQiOjk5OTk5OTk5OTksImppdCI6ImQ3MzY3YTE0LTkzZWUtNGQwYy1iODM1LTQ4YjJhMGIzYTI2OSJ9.YD5anPh4cOmqu1JusRB9cFJYJR-7th3crkBsttI5kTs" // [!code focus]
}

調試器

以上步驟完成後可使用 Debugger 來進行快速簡易測試

API

查詢交易轉點紀錄

`GET /api/v2/single_wallet/trade_logs`

說明：查詢用戶的交易轉點紀錄

請求參數

參數	類型	說明	預設值	限制條件
`order_id`	string	篩選訂單編號	-	-
`uid`	string	篩選用戶 ID	-	-
`points_gte`	number	篩選點數大於等於	-	-
`points_lte`	number	篩選點數小於等於	-	-
`created_start`	string($date-time)	篩選起始時間	-	-
`created_end`	string($date-time)	篩選結束時間	-	-
`sort_by`	string	排序依據	`id`	可用值：`id`
`sort_dir`	string	排序方向	`desc`	可用值：`asc`, `desc`
`next_id`	integer	從此 ID 開始搜尋	-	最小值：1
`size`	integer	每頁筆數	`10`	最小值：1，最大值：1000
`page`	integer	頁數	`1`	最小值：1
`count`	boolean	是否計算總筆數	`false`	-

200: 成功回應

{
  "hasNext": true,
  "total": 0,
  "items": [
    {
      "id": 1,
      "order_id": "string",
      "machine_id": 0,
      "game_round": "string",
      "uid": "string",
      "points": 0,
      "reason": "string",
      "comment": "string",
      "created_at": "2025-02-14T05:45:42.166Z"
    }
  ]
}

4XX: 錯誤回應，更多資訊請參考錯誤代號參考

{
  "code": 0,
  "msg": "string",
  "msg_zh": "string",
  "detail": "string"
}

查詢交易回滾

`GET /api/v2/single_wallet/trade_rollback`

說明：查詢交易回滾紀錄

請求參數

無需傳入參數。

200: 成功回應

{
  "hasNext": true,
  "total": 0,
  "items": [
    {
      "id": 1,
      "order_id": "string",
      "machine_id": 1,
      "game_round": "string",
      "uid": "string",
      "points": 0,
      "reason": "string",
      "comment": "string",
      "created_at": "2025-02-14T05:47:10.714Z"
    }
  ]
}

4XX: 錯誤回應，更多資訊請參考錯誤代號參考

{
  "code": 0,
  "msg": "string",
  "msg_zh": "string",
  "detail": "string"
}

接受轉點回滾

`POST /api/v2/single_wallet/accept_rollback`

說明：接受轉點回滾

請求參數

無需傳入參數。

請求主體

{
  "order_ids": ["string"]
}

200: 成功回應

{
  "success_count": 0
}

4XX: 錯誤回應，更多資訊請參考錯誤代號參考

{
  "code": 0,
  "msg": "string",
  "msg_zh": "string",
  "detail": "string"
}

常見問題 (FAQ)

單一錢包的 API 不完整?

我方的 單一錢包 需與 轉帳錢包 API 配合使用，涉及的 API 包括：

POST /api/v2/users 建立用戶
POST /api/v2/users/generate_access_url 生成訪問網址

Arcade 記錄部分 可根據需求決定是否接入。