#單錢包API參考

查看完整示例代碼 → 服務端 Demo · 客戶端 Demo

本文檔描述了單一錢包模式的API端點：

商戶回呼APIs：第1-5節是必要的，並且必須由商戶實施。第 6-7 節是可選的。當對應功能啟用時PetaX將呼叫這些API。
PetaX 服務APIs：第 8 至 10 節由 PetaX 提供。商戶呼叫這些API來查詢單一錢包交易並通知餘額變更。

有關轉帳錢包模式APIs，請參閱轉帳錢包API文件。

版本：1.3.0 商戶回呼基準URL：{{MERCHANT_API_BASE_URL}} PetaX服務基地URL：{{API_BASE_URL}}/api/0857-sw 方案：HTTPS

#端點

#商戶回撥APIs

必填

取得用戶餘額
扣除本金
取消投注
投注錯誤
支付

可選

注單結算通知
已結算回合

#1. 取得使用者餘額

端點：GET /balances/{username}/{currency} 摘要：檢索使用者的餘額。
權限：swApi.getBalance 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：您必須實現此API 才能處理我們的請求。

#路徑參數

參數	型別	必填	說明	範例/註解
`username`	字串	是的	使用者的使用者名稱	最小長度：6
`currency`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`

#請求

CURL 範例：

curl -X GET "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/balances/testuser/PHP" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#回應

200 好 描述：餘額數據類型：對象 Schema：

{
  balance: number;
  ccy: string;
  username: string;
}

範例：

{
  "balance": 1000.00,
  "ccy": "PHP",
  "username": "testuser"
}

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#2. 扣除本金

端點：POST /bet 摘要：從用戶的餘額中扣除賭注。
權限：swApi.bet 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：您必須實現此API 才能處理我們的請求。

#請求

CURL 範例：

curl -X POST "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/bet" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "betTime": "2025-01-25T00:00:00.000+01:00",
    "ccy": "PHP",
    "gameCategory": "CASINO",
    "gameType": "BCR",
    "ticketId": "ticket-uuid-123",
    "transactionId": "txn-uuid-123",
    "username": "testuser"
  }'

機身參數 (JSON):

領域	類型	必填	描述	範例/註解
`amount`	數量	是的	從用戶餘額中扣除的投注金額	`100.00`
`betTime`	字串	是的	ISO 8601 格式的投注時間	`"2025-01-25T00:00:00.000+01:00"`
`ccy`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`
`gameCategory`	字串	是的	遊戲類別	`"CASINO"`
`gameType`	字串	是的	遊戲類型	`"BCR"`
`issueId`	字串	沒有	發行/回合 ID（可選）	`"round-uuid-123"`
`ticketId`	字串	是的	唯一的注單識別碼	`"ticket-uuid-123"`
`transactionId`	字串	是的	唯一的交易識別碼	`"txn-uuid-123"`
`username`	字串	是的	使用者的使用者名稱	最小長度：6

#回應

200 好 描述：數據類型：對象 Schema：

{
  balance: number;
  betAmount: number;
  ccy: string;
  username: string;
}

範例：

{
  "balance": 900.00,
  "betAmount": 100.00,
  "ccy": "PHP",
  "username": "testuser"
}

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#3. 取消投注

端點：POST /cancel-bet 摘要：通知用戶的投注已取消。
權限：swApi.cancelBet 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：您必須實現此API 才能處理我們的請求。

#請求

CURL 範例：

curl -X POST "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/cancel-bet" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "ccy": "PHP",
    "gameCategory": "CASINO",
    "gameType": "BCR",
    "ticketId": "ticket-uuid-123",
    "transactionId": "txn-uuid-123",
    "username": "testuser"
  }'

機身參數 (JSON):

領域	類型	必填	描述	範例/註解
`amount`	數量	是的	投注金額退還至用戶餘額	`100.00`
`ccy`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`
`gameCategory`	字串	是的	遊戲類別	`"CASINO"`
`gameType`	字串	是的	遊戲類型	`"BCR"`
`issueId`	字串	沒有	發行/回合 ID（可選）	`"round-uuid-123"`
`ticketId`	字串	是的	唯一的注單識別碼	`"ticket-uuid-123"`
`transactionId`	字串	是的	唯一的交易識別碼	`"txn-uuid-123"`
`username`	字串	是的	使用者的使用者名稱	最小長度：6

#回應

200 好 描述：數據類型：對象 Schema：

{
  balance: number;
  ccy: string;
  username: string;
}

範例：

{
  "balance": 1000.00,
  "ccy": "PHP",
  "username": "testuser"
}

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#4. 錯誤投注

端點：POST /error-bet 摘要：通知用戶投注失敗，餘額應退回。
權限：swApi.errorBet 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：您必須實現此API 才能處理我們的請求。

#請求

CURL 範例：

curl -X POST "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/error-bet" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "ccy": "PHP",
    "gameCategory": "CASINO",
    "gameType": "BCR",
    "ticketId": "ticket-uuid-123",
    "transactionId": "txn-uuid-123",
    "username": "testuser"
  }'

機身參數 (JSON):

領域	類型	必填	描述	範例/註解
`amount`	數量	是的	投注金額退還至用戶餘額	`100.00`
`ccy`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`
`gameCategory`	字串	是的	遊戲類別	`"CASINO"`
`gameType`	字串	是的	遊戲類型	`"BCR"`
`issueId`	字串	沒有	發行/回合 ID（可選）	`"round-uuid-123"`
`ticketId`	字串	是的	唯一的注單識別碼	`"ticket-uuid-123"`
`transactionId`	字串	是的	唯一的交易識別碼	`"txn-uuid-123"`
`username`	字串	是的	使用者的使用者名稱	最小長度：6

#回應

200 好 描述：數據類型：對象 Schema：

{
  balance: number;
  ccy: string;
  username: string;
}

範例：

{
  "balance": 1000.00,
  "ccy": "PHP",
  "username": "testuser"
}

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#5. 支付

端點：POST /payout 摘要：通知用戶已收到付款。
權限：swApi.payout 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：您必須實現此API 才能處理我們的請求。

#請求

CURL 範例：

curl -X POST "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/payout" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200.00,
    "ccy": "PHP",
    "gameCategory": "CASINO",
    "gameType": "BCR",
    "payoutTime": "2025-01-25T00:00:00.000+01:00",
    "ticketId": "ticket-uuid-123",
    "transactionId": "txn-uuid-123",
    "username": "testuser"
  }'

機身參數 (JSON):

領域	類型	必填	描述	範例/註解
`amount`	數量	是的	付款金額存入用戶餘額	`200.00`
`ccy`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`
`gameCategory`	字串	是的	遊戲類別	`"CASINO"`
`gameType`	字串	是的	遊戲類型	`"BCR"`
`issueId`	字串	沒有	發行/回合 ID（可選）	`"round-uuid-123"`
`payoutTime`	字串	是的	ISO 8601 格式的付款時間	`"2025-01-25T00:00:00.000+01:00"`
`ticketId`	字串	是的	唯一的注單識別碼	`"ticket-uuid-123"`
`transactionId`	字串	是的	唯一的交易識別碼	`"txn-uuid-123"`
`username`	字串	是的	使用者的使用者名稱	最小長度：6

#回應

200 好 描述：數據類型：對象 Schema：

{
  balance: number;
  ccy: string;
  username: string;
}

範例：

{
  "balance": 1200.00,
  "ccy": "PHP",
  "username": "testuser"
}

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#6. 注單結算通知

端點：POST /settled-ticket 摘要：當注單已結算（贏得或遺失）時，收到有關注單資訊的通知。這只是通知API - 不要用它來處理付款（請改用付款API）。
權限：swApi.bet 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345） 可用性：可選商戶回呼API。
注意：您必須實現此API 才能處理我們的請求。商戶必須回覆 HTTP 狀態 200，以防止 PetaX 重新發送請求。 重要提示：此API 僅用於通知目的（告知注單贏/輸狀態）。請勿使用此API 處理支出 - 請使用支出API 處理獎金。

#請求

CURL 範例：

curl -X POST "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/settled-ticket" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "betItems": "[{\"betType\":\"LIVE_BCR_PLAYER\",\"betAmt\":100000,\"payoutAmt\":200000,\"wonAmt\":100000}]",
    "betTime": 1702656000000,
    "ccy": "PHP",
    "createdAt": 1702656000000,
    "gameCategory": "CASINO",
    "gameType": "BCR",
    "roundId": "BCR_MB553-250908-1550",
    "status": "WON",
    "tableId": "BCR_MB553",
    "ticketId": "550e8400-e29b-41d4-a716-446655440000",
    "totalBet": 100000.00,
    "totalPayout": 200000.00,
    "updatedAt": 1702656300000,
    "userId": "66c93b85205a1e146ed79b9b",
    "username": "player001"
  }'

機身參數 (JSON):

領域	類型	必填	說明	範例/註解
`betItems`	字串	是的	投注詳情為 JSON 字串。有關BCR 投注類型值，請參閱投注類型。	`"[{\"betType\":\"LIVE_BCR_PLAYER\",...}]"`
`betTime`	數量	是的	投注時間（時間戳以毫秒為單位）	`1702656000000`
`ccy`	字串	是的	貨幣代碼	`"PHP"`、`"USDT"`、`"KRW"`
`createdAt`	數量	是的	創建時間（時間戳以毫秒為單位）	`1702656000000`
`gameCategory`	字串	是的	遊戲類別	`"CASINO"`
`gameType`	字串	是的	遊戲類型	`"BCR"`
`roundId`	字串	是的	圓形 ID	`"BCR_MB553-250908-1550"`
`status`	字串	是的	注單狀態。請參閱投注/注單狀態。	`"WON"`、`"LOST"`
`tableId`	字串	是的	表格 ID	`"BCR_MB553"`
`ticketId`	字串	是的	唯一的注單識別碼	`"550e8400-e29b-41d4-a716-446655440000"`
`totalBet`	數量	是的	總投注金額（小數）	`100000.00`
`totalPayout`	數量	是的	支付總額（十進位）	`200000.00`
`updatedAt`	數量	是的	更新時間（時間戳以毫秒為單位）	`1702656300000`
`userId`	字串	是的	使用者名稱	`"66c93b85205a1e146ed79b9b"`
`username`	字串	是的	使用者的使用者名稱	最小長度：6
範例：

{
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "player001",
  "ticketId": "550e8400-e29b-41d4-a716-446655440000",
  "gameCategory": "CASINO",
  "gameType": "BCR",
  "tableId": "BCR_MB553",
  "roundId": "BCR_MB553-250908-1550",
  "ccy": "PHP",
  "status": "WON",
  "betTime": 1702656000000,
  "betItems": "[{\"betType\":\"LIVE_BCR_PLAYER\",\"betAmt\":100000,\"payoutAmt\":200000,\"wonAmt\":100000}]",
  "totalBet": 100000.00,
  "totalPayout": 200000.00,
  "createdAt": 1702656000000,
  "updatedAt": 1702656300000
}

#回應

200 好 描述：成功響應。商戶必須返回HTTP狀態200以確認收到通知並防止PetaX重新發送請求。
類型：對象 Schema：
```
{
  success: boolean;
}
```
範例：
```
{
  "success": true
}
```
有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#7. 結算回合

端點：POST /settled-round 摘要：用於接收回合結算資訊。
權限：swApi.bet 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345） 可用性：可選商戶回呼API。
注意：您使用這個API來接收我們發送的回合結算訊息。您必須實施此API才能接收回合結算資訊。

#請求

CURL 範例：

curl -X POST "{{MERCHANT_API_BASE_URL}}/api/0857-sw/sample/settled-round" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "closeAt": 1702656300000,
    "gameCategory": "CASINO",
    "gameType": "BCR",
    "openAt": 1702656000000,
    "result": "33,37-29,29",
    "roundId": "BCR_MB553-250908-1550",
    "tableId": "BCR_MB553"
  }'

機身參數 (JSON):

領域	類型	必填	說明	範例/註解
`closeAt`	數量	是的	回合關閉時間（時間戳以毫秒為單位）	`1702656300000`
`gameCategory`	字串	是的	遊戲類別	`"CASINO"`
`gameType`	字串	是的	遊戲類型	`"BCR"`
`openAt`	數量	是的	回合開放時間（時間戳以毫秒為單位）	`1702656000000`
`result`	字串	是的	回合結果。 BCR結果編碼請參閱百家樂結果格式。	`"33,37-29,29"`（百家樂牌指數）
`roundId`	字串	是的	圓形 ID	`"BCR_MB553-250908-1550"`
`tableId`	字串	是的	表格 ID	`"BCR_MB553"`

#回應

200 好 描述：成功響應。商戶必須返回 HTTP 狀態 200 以確認收到通知。
類型：對象 Schema：
```
{
  success: boolean;
}
```
範例：
```
{
  "success": true
}
```
有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#8. 通知餘額變化

端點：POST /a/sw/wallets/notify-change-balance 摘要：當用戶的餘額發生變化時通知應用程式。
權限：swApi.notifyBalance 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API來通知PetaX用戶的單一錢包餘額已更改。

#請求

CURL 範例：

curl -X POST "{{API_BASE_URL}}/api/0857-sw/a/sw/wallets/notify-change-balance" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "balance": 900.00,
    "ccy": "PHP",
    "username": "testuser"
  }'

機身參數 (JSON):

領域	類型	必填	描述	範例/註解
`balance`	數量	是的	變更後當前使用者餘額	`900.00`，最小值：`0`
`ccy`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`
`username`	字串	是的	使用者的使用者名稱	最小長度：6

#回應

200 好 描述：空響應Body 類型：字串範例：
```
""
```
有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#9. 尋找交易

端點：GET /a/sw/transactions 摘要：查找交易。
權限：swApi.transactions.list 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API以尋找PetaX的單一錢包系統中的交易。單錢包交易僅包含bet和payout交易類型；單一錢包模式下沒有deposit 或withdraw 交易。

#查詢參數

參數	型別	必填	說明	範例/註解
`createdAtGte`	字串	沒有	建立日期的開始日期，ISO 日期時間	`"2025-01-25T00:00:00.000+01:00"`
`createdAtLt`	字串	沒有	建立日期的結束日期，ISO 日期時間	`"2025-01-26T00:00:00.000+01:00"`
`id`	字串	沒有	您要尋找的交易ID（最小長度：24）	`"66c93b85205a1e146ed79b9b"`
`refId`	字串	沒有	交易參考 ID（最小長度：1）。請參閱交易參考 ID。	`"bet.ticket-uuid-123"`、`"payout.ticket-uuid-123"`
`page`	整數	沒有	頁數，預設為1	`1`
`size`	整數	沒有	頁大小，預設為10	`10`

#請求

CURL 範例：

# Find transactions with pagination and date filter
curl -X GET "{{API_BASE_URL}}/api/0857-sw/a/sw/transactions?page=1&size=10&createdAtGte=2025-01-25T00:00:00.000+01:00" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

# Find bet transaction by ticketId
curl -X GET "{{API_BASE_URL}}/api/0857-sw/a/sw/transactions?refId=bet.ticket-uuid-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

# Find payout transaction by ticketId
curl -X GET "{{API_BASE_URL}}/api/0857-sw/a/sw/transactions?refId=payout.ticket-uuid-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#回應

200 好 描述：交易列表類型：數組 Schema：

{
  balanceChange: number;
  ccy: string;
  createdAt: string;
  id: string;
  priorBalance: number;
  userId: string;
  username: string;
}[]

範例：

[
  {
    "id": "66c93b85205a1e146ed79b9b",
    "userId": "66c93b85205a1e146ed79b9b",
    "username": "testuser",
    "ccy": "PHP",
    "balanceChange": -100.00,
    "priorBalance": 1000.00,
    "createdAt": "2025-01-25T10:30:00.000Z"
  }
]

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理

#10. 透過 ID 取得交易

端點：GET /a/sw/transactions/{id} 總結：透過ID取得一筆交易。
權限：swApi.transactions.get 消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API以從PetaX的單一錢包系統取得特定交易。

#路徑參數

參數	型別	必填	說明	範例/註解
`id`	字串	是的	交易ID	`"66c93b85205a1e146ed79b9b"`

#請求

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-sw/a/sw/transactions/66c93b85205a1e146ed79b9b" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#回應

200 好 描述：一筆交易類型：對象 Schema：

{
  balanceChange: number;
  ccy: string;
  createdAt: string;
  id: string;
  priorBalance: number;
  userId: string;
  username: string;
}

範例：

{
  "id": "66c93b85205a1e146ed79b9b",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser",
  "ccy": "PHP",
  "balanceChange": 200.00,
  "priorBalance": 1000.00,
  "createdAt": "2025-01-25T10:30:00.000Z"
}

有關錯誤狀態（4xx、5xx），請參閱 API-錯誤處理