#转账钱包API参考

本文档描述了PetaX为商户调用的转账钱包模式提供的API端点：获取用户余额、存款和取款。

注：这些API是PetaX提供给商户调用的。对于单一钱包模式API（商户实施），请参阅单一钱包API文档。

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

#端点

#余额和交易APIs

获取用户余额：

• 1. 获取用户余额 (基于用户Id，推荐)
• 2. 通过用户名获取用户余额 (基于用户名)

押金：

• 3. 存款 (基于用户ID，推荐)
• 4. 按用户名存款 (基于用户名)

提款：

• 5. 提现 (基于用户Id，推荐)
• 6. 通过用户名提现 (基于用户名)

#交易查询APIs

• 7. 查找交易
• 8. 通过ID获取交易

性能说明：我们建议使用 基于用户 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获取用户余额。

#路径参数

#请求

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 来获得更好的性能。

#路径参数

#请求

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用户的转账钱包。

#路径参数

#请求

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):

#回应

• 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 来获得更好的性能。

#路径参数

#请求

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):

#回应

• 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用户的转账钱包中提款。

#路径参数

#请求

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):

#回应

• 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 来获得更好的性能。

#路径参数

#请求

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):

#回应

• 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的转账钱包系统中的交易。

#查询参数

#请求

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的转账钱包系统获取特定交易。

#路径参数

#请求

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 错误处理。