#轉帳錢包API參考

本文檔描述了PetaX為商戶調用的轉帳錢包模式提供的API端點：取得使用者餘額、存款和提款。

註：這些API是PetaX提供給商戶呼叫的。單一錢包模式API（商戶實施），請參閱單一錢包API文件。

版本：1.0.1 基礎URL：{{API_BASE_URL}}/api/0857-tw 方案：HTTPS

#端點

#餘額和交易APIs

取得使用者餘額：

1. 取得使用者餘額 (基於使用者Id，推薦)
1. 透過使用者名稱取得使用者餘額 (基於使用者名稱)

押金：

1. 存款 (基於使用者ID，推薦)
1. 依使用者名稱存款 (基於使用者名稱)

提款：

1. 提現 (基於使用者Id，推薦)
1. 透過使用者名稱提現 (基於使用者名稱)

效能說明：我們建議使用 基於使用者 ID 的 APIs（第 1、3、5 節）而不是 基於使用者名稱的 APIs（第 2、4、6 節），以獲得更好的效能。基於 UserId 的 API 已針對更快的回應時間進行了最佳化，因為它們直接按使用者 ID 進行查詢。

#1. 取得使用者餘額

端點：GET /a/tw/balances/{userId}/{currency} 摘要：取得用戶目前轉帳錢包中特定幣種的餘額。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API從PetaX取得使用者餘額。

#路徑參數

參數	型別	必填	說明	範例/註解
`userId`	字串	是的	使用者ID	`"66c93b85205a1e146ed79b9b"`
`currency`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`

#請求

CURL 範例：

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

#回應

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

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

範例：

{
  "balance": 1000.00,
  "ccy": "PHP",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser"
}

400 錯誤請求 描述：錯誤的請求 Schema：請參閱API 錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API 錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#2. 透過使用者名稱取得使用者餘額

端點：GET /a/tw/by-username/{username}/balances/{currency} 摘要：透過使用者名稱取得使用者轉帳錢包中特定幣種的當前餘額。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API，透過使用者名稱從PetaX取得使用者餘額。

效能說明：我們建議使用基於使用者 ID 的獲取使用者餘額API 來獲得更好的效能。

#路徑參數

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

#請求

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/by-username/testuser/balances/PHP" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#回應

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

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

範例：

{
  "balance": 1000.00,
  "ccy": "PHP",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser"
}

400 錯誤請求 描述：錯誤的請求 Schema：請參閱API 錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#3. 存款

端點：POST /a/tw/balances/{userId}/{currency}/deposit 概要：將特定金額的特定幣種存入用戶的轉帳錢包。這將增加用戶的餘額。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API，將錢存入PetaX用戶的轉帳錢包。

#路徑參數

參數	型別	必填	說明	範例/註解
`userId`	字串	是的	使用者ID	`"66c93b85205a1e146ed79b9b"`
`currency`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`

#請求

CURL 範例：

curl -X POST "{{API_BASE_URL}}/api/0857-tw/a/tw/balances/66c93b85205a1e146ed79b9b/PHP/deposit" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "txReference": "tx-ref-123"
  }'

機身參數 (JSON):

領域	類型	必填	說明	範例/註解
`amount`	數量	是的	加到用戶餘額的存款金額	`100.00`
`txReference`	字串	是的	交易參考識別碼	`"tx-ref-123"`，最大長度：40

#回應

200 好 描述：存款結果包括userId、使用者名稱、更新的餘額和幣種類型：對象 Schema：

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

範例：

{
  "balance": 1100.00,
  "ccy": "PHP",
  "transactionId": "txn-uuid-123",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser"
}

400 錯誤請求 描述：錯誤的請求 Schema：請參閱API錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#透過 txReference 找出交易

若要使用您提供的 txReference 來尋找存款交易，請使用尋找交易 API 和 refId 查詢參數：

對於refId 格式，請參閱交易參考 ID。

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/transactions?refId=deposit.tx-ref-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#4. 使用者名稱儲值

端點：POST /a/tw/by-username/{username}/balances/{currency}/deposit 概要：透過使用者名稱將特定金額的特定幣種存入用戶的轉帳錢包。這將增加用戶的餘額。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API，透過用戶名稱將錢存入PetaX中的用戶轉帳錢包。

效能說明：我們建議使用基於使用者 ID 的存款 API 來獲得更好的效能。

#路徑參數

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

#請求

CURL 範例：

curl -X POST "{{API_BASE_URL}}/api/0857-tw/a/tw/by-username/testuser/balances/PHP/deposit" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "txReference": "tx-ref-123"
  }'

機身參數 (JSON):

領域	類型	必填	說明	範例/註解
`amount`	數量	是的	加到用戶餘額的存款金額	`100.00`
`txReference`	字串	是的	交易參考識別碼	`"tx-ref-123"`，最大長度：40

#回應

200 好 描述：存款結果包括userId、使用者名稱、更新的餘額和幣種類型：對象 Schema：

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

範例：

{
  "balance": 1100.00,
  "ccy": "PHP",
  "transactionId": "txn-uuid-123",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser"
}

400 錯誤請求 描述：錯誤的請求 Schema：請參閱API錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#透過 txReference 找出交易

若要使用您提供的 txReference 來尋找存款交易，請使用尋找交易 API 和 refId 查詢參數：

對於refId 格式，請參閱交易參考 ID。

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/transactions?refId=deposit.tx-ref-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#5. 退出

端點：POST /a/tw/balances/{userId}/{currency}/withdraw 摘要：從用戶的轉帳錢包中提取特定貨幣的指定金額。這將減少用戶的餘額。如果使用者餘額不足，操作將會失敗。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API從PetaX用戶的轉帳錢包提款。

#路徑參數

參數	型別	必填	說明	範例/註解
`userId`	字串	是的	使用者ID	`"66c93b85205a1e146ed79b9b"`
`currency`	字串	是的	貨幣代碼。請參閱支援的貨幣以了解可用代碼。	`"PHP"`、`"USDT"`、`"KRW"`

#請求

CURL 範例：

curl -X POST "{{API_BASE_URL}}/api/0857-tw/a/tw/balances/66c93b85205a1e146ed79b9b/PHP/withdraw" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "txReference": "tx-ref-123"
  }'

機身參數 (JSON):

領域	類型	必填	說明	範例/註解
`amount`	數量	是的	提款金額從用戶餘額中扣除	`100.00`
`txReference`	字串	是的	交易參考識別碼	`"tx-ref-123"`，最大長度：40

#回應

200 好 描述：提現結果包括userId、使用者名稱、更新後的餘額、幣種和transactionId 類型：對象 Schema：

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

範例：

{
  "balance": 900.00,
  "ccy": "PHP",
  "transactionId": "txn-uuid-123",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser"
}

400 錯誤請求 描述：錯誤請求（可能包括餘額不足） Schema：請參閱API錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#透過 txReference 找出交易

若要使用您提供的 txReference 尋找提款交易，請使用查找交易 API 和 refId 查詢參數：

對於refId 格式，請參閱交易參考 ID。

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/transactions?refId=withdraw.tx-ref-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#6. 透過使用者名稱提現

端點：POST /a/tw/by-username/{username}/balances/{currency}/withdraw 摘要：透過使用者名稱從使用者的轉帳錢包中提取特定貨幣的指定金額。這將減少用戶的餘額。如果使用者餘額不足，操作將會失敗。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API，透過使用者名稱從PetaX使用者的轉帳錢包提款。

效能說明：我們建議使用 userId-based Withdraw API 來獲得更好的效能。

#路徑參數

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

#請求

CURL 範例：

curl -X POST "{{API_BASE_URL}}/api/0857-tw/a/tw/by-username/testuser/balances/PHP/withdraw" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "txReference": "tx-ref-123"
  }'

機身參數 (JSON):

領域	類型	必填	說明	範例/註解
`amount`	數量	是的	提款金額從用戶餘額中扣除	`100.00`
`txReference`	字串	是的	交易參考標識符	`"tx-ref-123"`，最大長度：40

#回應

200 好 描述：提現結果包括userId、使用者名稱、更新後的餘額、幣種和transactionId 類型：對象 Schema：

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

範例：

{
  "balance": 900.00,
  "ccy": "PHP",
  "transactionId": "txn-uuid-123",
  "userId": "66c93b85205a1e146ed79b9b",
  "username": "testuser"
}

400 錯誤請求 描述：錯誤請求（可能包括餘額不足） Schema：請參閱API 錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#透過 txReference 找出交易

若要使用您提供的 txReference 尋找提款交易，請使用查找交易 API 和 refId 查詢參數：

對於refId 格式，請參閱交易參考 ID。

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/transactions?refId=withdraw.tx-ref-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

#7. 尋找交易

端點：GET /a/tw/transactions 摘要：查找交易。
消耗：application/json 產生：application/json 安全：BearerAuth（授權：承載abcde12345）注意：這是PetaX 服務API。您（商戶）呼叫此API來尋找PetaX的轉帳錢包系統中的交易。

#查詢參數

參數	型別	必填	說明	範例/註解
`createdAtGte`	字串	沒有	建立日期的開始日期，ISO 日期時間	`"2025-01-25T00:00:00.000+01:00"`
`createdAtLt`	字串	沒有	建立日期的結束日期，ISO 日期時間	`"2025-01-25T00:00:00.000+01:00"`
`id`	字串	沒有	您要尋找的交易 ID（最小長度：24）	`"66c93b85205a1e146ed79b9b"`
`refId`	字串	沒有	交易參考 ID（最小長度：1）。請參閱交易參考 ID。	`"deposit.tx-ref-123"`、`"withdraw.tx-ref-123"`、`"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-tw/a/tw/transactions?page=1&size=10&createdAtGte=2025-01-25T00:00:00.000+01:00" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

# Find deposit transaction by txReference
curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/transactions?refId=deposit.tx-ref-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

# Find withdraw transaction by txReference
curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/transactions?refId=withdraw.tx-ref-123" \
  -H "Authorization: Bearer abcde12345" \
  -H "Accept: application/json"

# Find bet transaction by ticketId
curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/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-tw/a/tw/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": 900.00,
    "createdAt": "2025-01-25T10:30:00.000Z"
  }
]

400 錯誤請求 描述：錯誤的請求 Schema：請參閱API錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API 錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#8. 透過 ID 取得交易

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

#路徑參數

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

#請求

CURL 範例：

curl -X GET "{{API_BASE_URL}}/api/0857-tw/a/tw/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": 100.00,
  "priorBalance": 900.00,
  "createdAt": "2025-01-25T10:30:00.000Z"
}

400 錯誤請求 描述：錯誤的請求 Schema：請參閱API錯誤處理
500 內部伺服器錯誤 描述：內部伺服器錯誤 Schema：請參閱API 錯誤處理
其他錯誤狀態（4xx、5xx），請參閱 API-Error-Handling

#重要提示

這些是PetaX提供的服務API。商戶呼叫這些API與PetaX的轉帳錢包系統互動。
所有端點都需要 Authorization 標頭中的承載令牌身份驗證。使用PetaX提供的JWT令牌。
效能建議：使用基於使用者ID的APIs（第1、3、5節）而不是基於使用者名稱的APIs（第2、4、6節）以獲得更好的效能。基於 UserId 的 API 已針對更快的回應時間進行了最佳化，因為它們直接按使用者 ID 進行查詢。 -deposit端點增加PetaX轉帳錢包中使用者的餘額。 -withdraw端點會減少PetaX轉帳錢包中用戶的餘額，如果用戶餘額不足，將會失敗。
txReference 欄位的最大長度為 40 個字元。
所有金額均以指定貨幣表示，並應以十進制數字處理。
當呼叫 PetaX APIs 時，請將提供的 JSON Web 令牌包含在請求標頭 Authorization 中，並帶有 Bearer 前綴。
有關錯誤處理的詳細信息，請參閱API 錯誤處理。