#单钱包API参考

本文档描述了单一钱包模式的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-错误处理