錢包（轉帳）

轉帳錢包：轉入、轉出、查詢轉帳結果與餘額。轉帳以 txnId 冪等。

TIP

範例使用〈認證與簽章〉的範例金鑰與時間戳計算簽章，可直接用〈簽章除錯器〉驗算。

轉入（加點）

POST /api/tenant/v1/wallet/deposit

把金額轉入玩家的遊戲錢包。單階段、冪等：同一個 txnId 重送不會重複入帳，而是回傳第一次的結果（同一個 balance），duplicate 為 true。同一個 txnId 但金額或方向不同，或最近兩個月內已用在另一位玩家，回 TXN_CONFLICT。

玩家不存在時會以請求的 currency 自動建立。
currency 必須等於玩家的幣別，否則回 CURRENCY_MISMATCH。
balance 是這筆轉帳完成當下的餘額。
回應成功的轉帳一定查得到：GET /wallet/transfer?txnId=…&username=…。
逾時或收到 5xx 時，以相同 txnId 與相同內容重送，或先以 GET /wallet/transfer 查詢；不要換一個新的 txnId。

請求本文（application/json）

欄位	型別	必填	說明
`username`	string	是	玩家帳號，1–32 個字元（英數字與 `_ . @ -`）；不分大小寫（`Alice` 與 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`
`txnId`	string	是	你的轉帳單號，1–64 個字元（英數字與 `_ . : -`），作為冪等鍵。請在你的整個租戶內保持唯一（不要在不同玩家之間重複使用）。格式：`^[A-Za-z0-9_.:-]{1,64}$`
`amount`	string	是	大於 0 的金額，十進位字串，最多 4 位小數，例如 `"1000"`、`"99.5"`。請用字串，不要用浮點數。格式：`^\d{1,15}(\.\d{1,4})?$`
`currency`	string	是	必須等於玩家的幣別。格式：`^[A-Za-z]{3,5}$`

請求範例

http

POST /api/tenant/v1/wallet/deposit HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: exc3b9fb78a452ce2fc90cff
X-Signature: a43ebc031d05839610a3d5e52eb10ffa82fd8c83f87e8476d57c3cde3b80917a
Content-Type: application/json

{"username":"alice","txnId":"dep-20260924-000123","amount":"1000","currency":"TWD"}

回應的 data

欄位	型別	說明
`txnId`	string	請求的 `txnId`。
`status`	string	一律為 `done`（單階段，沒有處理中狀態）。
`balance`	string	這筆轉帳完成當下的餘額；重送同一個 `txnId` 時回傳第一次的值。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`duplicate`	boolean	`true` 表示這個 `txnId` 先前已處理過：這次沒有再動到餘額，回應是第一次的結果。

回應範例

第一次處理

json

{
  "ok": true,
  "data": {
    "txnId": "dep-20260924-000123",
    "status": "done",
    "balance": "2500.5",
    "duplicate": false
  }
}

重送同一個 txnId（回傳第一次的結果）

json

{
  "ok": true,
  "data": {
    "txnId": "dep-20260924-000123",
    "status": "done",
    "balance": "2500.5",
    "duplicate": true
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_PARAMETER`	400	缺少必要欄位，或欄位格式、值不正確；`message` 會指出是哪個欄位。
`INVALID_AMOUNT`	400	金額不是大於 0、最多 4 位小數的十進位字串。
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`INVALID_CURRENCY`	400	建立新玩家時指定的幣別代碼不合法（需要 3–5 個英文字母）。
`CURRENCY_NOT_ENABLED`	400	建立新玩家時指定的幣別，租戶還沒開啟（多幣別：Console「限紅方案 → 幣別」）。已存在的玩家不受影響。
`CURRENCY_MISMATCH`	400	轉帳的 `currency` 與玩家的幣別不同。玩家的幣別在建立時決定，之後不能變更。
`PLAYER_LIMIT`	403	玩家帳號數已達方案上限（免費展示方案預設 50、沙箱 500）。
`TXN_CONFLICT`	409	這個 `txnId` 已經用在另一筆金額或方向不同的轉帳，或最近兩個月內已用在另一位玩家。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

轉出（扣點）

POST /api/tenant/v1/wallet/withdraw

從玩家的遊戲錢包轉出。冪等規則同轉入：同一個 txnId 重送會回傳第一次的結果。

只能轉出可用餘額：下注時本金已先扣除，未結算的注不會被轉走；不足時回 INSUFFICIENT_BALANCE。
玩家必須已存在（PLAYER_NOT_FOUND）。

請求本文（application/json）

欄位	型別	必填	說明
`username`	string	是	玩家帳號，1–32 個字元（英數字與 `_ . @ -`）；不分大小寫（`Alice` 與 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`
`txnId`	string	是	你的轉帳單號，1–64 個字元（英數字與 `_ . : -`），作為冪等鍵。請在你的整個租戶內保持唯一（不要在不同玩家之間重複使用）。格式：`^[A-Za-z0-9_.:-]{1,64}$`
`amount`	string	是	大於 0 的金額，十進位字串，最多 4 位小數，例如 `"1000"`、`"99.5"`。請用字串，不要用浮點數。格式：`^\d{1,15}(\.\d{1,4})?$`
`currency`	string	是	必須等於玩家的幣別。格式：`^[A-Za-z]{3,5}$`

請求範例

http

POST /api/tenant/v1/wallet/withdraw HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: exc26f22db83dc51cea1eb7f
X-Signature: 3cdc9cb2100e63618316b3d333d880daab0adae2e861f2a40e1ff8ab4fd971a7
Content-Type: application/json

{"username":"alice","txnId":"wd-20260924-000077","amount":"500.25","currency":"TWD"}

回應的 data

欄位	型別	說明
`txnId`	string	請求的 `txnId`。
`status`	string	一律為 `done`（單階段，沒有處理中狀態）。
`balance`	string	這筆轉帳完成當下的餘額；重送同一個 `txnId` 時回傳第一次的值。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`duplicate`	boolean	`true` 表示這個 `txnId` 先前已處理過：這次沒有再動到餘額，回應是第一次的結果。

回應範例

json

{
  "ok": true,
  "data": {
    "txnId": "wd-20260924-000077",
    "status": "done",
    "balance": "2000.25",
    "duplicate": false
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_PARAMETER`	400	缺少必要欄位，或欄位格式、值不正確；`message` 會指出是哪個欄位。
`INVALID_AMOUNT`	400	金額不是大於 0、最多 4 位小數的十進位字串。
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`CURRENCY_MISMATCH`	400	轉帳的 `currency` 與玩家的幣別不同。玩家的幣別在建立時決定，之後不能變更。
`PLAYER_NOT_FOUND`	404	這個帳號的玩家不存在。
`TXN_CONFLICT`	409	這個 `txnId` 已經用在另一筆金額或方向不同的轉帳，或最近兩個月內已用在另一位玩家。
`INSUFFICIENT_BALANCE`	409	轉出金額大於可用餘額（未結算注單的本金不可轉出）。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

查詢轉帳

GET /api/tenant/v1/wallet/transfer

依 txnId 查詢轉帳結果。用在轉入、轉出逾時之後，確認是否已經處理。

請一併帶 username：這樣只要轉帳已經成功就一定查得到（包含租戶流水的副本還在送達途中的時候）。
租戶流水的查詢範圍是當月與前 3 個月（依 UTC 月份）。
回 TXN_NOT_FOUND 表示這筆轉帳沒有執行（或仍在處理中）：請以相同 txnId、相同內容重送，直到得到明確的成功或 4xx 結果；不要改用新的 txnId。
dir 為 adjust 表示這個單號是 Console 的人工上下分。

參數

參數	位置	型別	必填	說明
`txnId`	query	string	是	轉帳時使用的 `txnId`。格式：`^[A-Za-z0-9_.:-]{1,64}$`
`username`	query	string	否	轉帳的玩家帳號（建議帶）。租戶流水查不到時，改以這位玩家錢包自己的紀錄回答。格式：`^[A-Za-z0-9_.@-]{1,32}$`

請求範例

http

GET /api/tenant/v1/wallet/transfer?txnId=dep-20260924-000123&username=alice HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex6926b9a725a67c6cc02f60
X-Signature: 93a44cb15149333af7e00fc57274af52ba62f79f102be9a9269edc1eaede7a67

回應的 data

欄位	型別	說明
`txnId`	string	轉帳單號。
`username`	string	玩家帳號。
`dir`	string	`in` 轉入、`out` 轉出、`adjust` Console 人工上下分。可能的值：`in`、`out`、`adjust`
`amount`	string	金額（正數）。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`status`	string	一律為 `done`。
`balance`	string \| null	這筆轉帳完成後的餘額。
`at`	string (date-time)	UTC 時間，ISO-8601 含毫秒。

回應範例

json

{
  "ok": true,
  "data": {
    "txnId": "dep-20260924-000123",
    "username": "alice",
    "dir": "in",
    "amount": "1000",
    "status": "done",
    "balance": "2500.5",
    "at": "2026-09-24T03:00:01.250Z"
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_PARAMETER`	400	缺少必要欄位，或欄位格式、值不正確；`message` 會指出是哪個欄位。
`TXN_NOT_FOUND`	404	查不到這個 `txnId` 的轉帳：查詢時有帶 `username` 表示這筆轉帳沒有執行（或仍在處理中）；沒帶時只查租戶流水（當月與前 3 個月）。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

查詢餘額

GET /api/tenant/v1/wallet/balance

玩家目前的可用餘額（已扣除未結算注單的本金）。

參數

參數	位置	型別	必填	說明
`username`	query	string	是	玩家帳號。格式：`^[A-Za-z0-9_.@-]{1,32}$`

請求範例

http

GET /api/tenant/v1/wallet/balance?username=alice HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex176285a304e084623ee6cf
X-Signature: d80f06a9225952f186571488addf4319ae8f87645fb80486d46cf5eac36db51f

回應的 data

欄位	型別	說明
`balance`	string	玩家金額，十進位字串，最多 4 位小數；回應會去掉小數尾端的 0（例如 `"100"`、`"0.95"`、`"1000.5"`）。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`currency`	string	幣別。

回應範例

json

{
  "ok": true,
  "data": {
    "balance": "2500.5",
    "currency": "TWD"
  }
}

錯誤碼

錯誤碼	HTTP	意義
`INVALID_USERNAME`	400	玩家帳號不符合規則（1–32 個字元，英數字與 `_ . @ -`），或查詢時沒有帶 `username`。
`PLAYER_NOT_FOUND`	404	這個帳號的玩家不存在。

所有端點另外都可能回傳共通錯誤（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

錢包（轉帳） ​

轉入（加點） ​

轉出（扣點） ​

查詢轉帳 ​

查詢餘額 ​

錢包（轉帳）

轉入（加點）

轉出（扣點）

查詢轉帳

查詢餘額