# 單一錢包接口

**最近更新： 2026-04-02**

## API基本信息

單一錢包為"PKG"呼叫商戶

* PKG請求格式為 `application/x-www-form-urlencoded`
* 商戶響應格式为 `JSON` \*所有時間和時間戳相關欄位均以**毫秒**為預設單位。
* 对参数的顺序不做要求

### 回應標頭:

| 參數           | 類型     | 是否必填 | 描述               |
| ------------ | ------ | ---- | ---------------- |
| Content-Type | string | YES  | application/json |

### 错误代码

* 具体的错误码及其解释在[错误代码汇总](/enum/enum-error-code.md)

## 驗證玩家

```
POST ( 营运商 API 位址 )/validate
```

**請求参数:**

| 名称         | 类型     | 是否必须 | 描述         |
| ---------- | ------ | ---- | ---------- |
| token      | string | YES  | 营运商提供的玩家令牌 |
| operatorID | string | YES  | 营运商ID      |
| appSecret  | string | YES  | 平台提供的凭证金钥  |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述                       |
| -------- | ------ | ---- | ------------------------ |
| playerID | string | YES  | 玩家ID                     |
| nickname | string | YES  | 玩家昵称                     |
| currency | string | YES  | 货币                       |
| time     | int64  | NO   | 时间(millisecond)          |
| balance  | int64  | YES  | 玩家餘額(单位:分), 不輸入參數,餘額將會是0 |

**回傳成功範例:**

```json
{
  "playerID": "BMJCP2DH5S5VCC8S9RHG", // string 玩家ID
  "nickname": "Player 1",             // string 玩家昵称
  "currency": "RMB",                  // string 货币
  "time": 1574476825000,              // int64 时间(millisecond)
  "balance": 300000                   // int64 玩家餘額(单位:分)
}
```

**回傳錯誤範例:**

```json
// HTTP状态码:400:非法請求
{
  "error": "Bad Request"        
}
```

```json
// HTTP状态码:401:金钥凭证错误等状况
{
  "error":"Incorrect appSecret"
}
```

```json
// HTTP状态码:404:玩家令牌无效、玩家令牌过期等状况
{
  "error":"Invalid Token"
}
```

## 取得玩家余额

取得营运商玩家余额，回传余额以分为单位，且必须为整数

```
POST ( 营运商 API 位址 )/balance
```

**請求参数:**

| 名称         | 类型     | 是否必须 | 描述         |
| ---------- | ------ | ---- | ---------- |
| token      | string | YES  | 营运商提供的玩家令牌 |
| operatorID | string | YES  | 营运商ID      |
| appSecret  | string | YES  | 平台提供的凭证金钥  |
| playerID   | string | YES  | 玩家ID       |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述              |
| -------- | ------ | ---- | --------------- |
| balance  | int64  | YES  | 玩家餘額(单位:分)      |
| currency | string | YES  | 货币              |
| time     | int64  | NO   | 时间(millisecond) |

**回傳成功範例:**

```json
{     
  "balance": 300000,                // int64 玩家餘額(单位:分)
  "currency": "RMB",                // string 货币
  "time": 1574476825000             // int64 时间(millisecond)  
}
```

## 余额扣款

扣除营运商玩家余额 (投注、小费)，回传余额以分为单位

且必须为整数，如果我方请求超过 10 秒没有回应或者回应错误，系统会加入排程取消该投注

并调用一次取消交易(/rollback)，让营运商取消此笔交易

备注:

1."每一次"的下注，都会请求一次,下注多筆選項則會有多筆投注資料, 如果需要每一筆投注拆開不同請求需要改用[單注模式](#yuekou-kuan-dan-zhu-mo-shi)

2.請"正確"的計算每一筆扣款後的餘額(包含派彩),HTTP狀態碼回200一律視為正常下注,請謹慎回傳

```
POST ( 营运商 API 位址 )/debit
```

**請求参数:**

| 名称          | 类型            | 是否必须 | 描述                                                                                                     |
| ----------- | ------------- | ---- | ------------------------------------------------------------------------------------------------------ |
| token       | string        | YES  | 营运商提供的玩家令牌                                                                                             |
| operatorID  | string        | YES  | 营运商ID                                                                                                  |
| appSecret   | string        | YES  | 平台提供的凭证金钥                                                                                              |
| playerID    | string        | YES  | 玩家ID                                                                                                   |
| gameID      | string        | YES  | 游戏ID                                                                                                   |
| gameRoundID | string        | YES  | 游戏局ID                                                                                                  |
| currency    | string        | YES  | 货币代码                                                                                                   |
| time        | int64         | YES  | 交易时间 (millisecond)                                                                                     |
| ip          | string        | YES  | 客户IP                                                                                                   |
| data        | string (json) | YES  | 投注資料 ex: `[{"betID": "","parentBetID": "","betType": "","type": "","amount": 0,"time": 0,"odds": ""}]` |

**投注資料結構**

| 名称          | 类型     | 是否必须 | 描述                                       |
| ----------- | ------ | ---- | ---------------------------------------- |
| betID       | string | YES  | 注单ID                                     |
| parentBetID | string | YES  | 父注单编号                                    |
| betType     | string | YES  | 下注类型,请参考betCode                          |
| amount      | int64  | YES  | 金额 (单位:分 最大长度: 1000億分)                   |
| dpsAmount   | int64  | YES  | 押金,或財神費 (单位:分 最大长度: 1000億分)              |
| time        | int64  | YES  | 投注時間 (millisecond)                       |
| type        | string | YES  | <p>交易类型:<br>● 投注 - bet<br>● 小费 - tip</p> |
| odds        | string | NO   | 投注位倍率,支援到小數點後６位數                         |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述              |
| -------- | ------ | ---- | --------------- |
| balance  | int64  | YES  | 玩家餘額(单位:分)      |
| currency | string | YES  | 货币              |
| time     | int64  | NO   | 时间(millisecond) |
| refID    | string | NO   | 交易编号            |

**回傳成功範例:**

```json
{     
  "balance": 300000,                // int64 玩家餘額(单位:分)
  "currency": "RMB",                // string 货币
  "time": 1574476825000,            // int64 时间(millisecond)
  "refID": "20200420XDCFSEDSE"      // string 交易编号
}
```

**回傳錯誤範例:**

```json
// HTTP状态码:402:余额不足
{
  "error": "Insufficient balance"        
}
```

```json
// HTTP状态码:404:玩家令牌无效、玩家令牌过期等状况
{
  "error":"Invalid Token"
}
```

```json
// HTTP状态码:409:重复交易等状况
{
  "error":"Duplicate transaction"
}
```

```json
// HTTP状态码:500:内部存取错误等状况
{
  "errorcode": 11013,            // 可使用錯誤代碼控制遊戲畫面錯誤訊息
  "error": "User account locked",
}
```

errorcode 可以參考 [投注錯誤代碼](/enum/enum-debit-error-code.md)

## 余额扣款(單注模式)

需要找平台調整為單注模式

扣除营运商玩家余额 (投注、小费)，回传余额以分为单位

且必须为整数，如果我方请求超过 10 秒没有回应或者回应错误，系统会加入排程取消该投注

并调用一次取消交易(/rollback)，让营运商取消此笔交易

备注:

1."每一次"的下注，都会请求一次,下注多筆選項則會同時呼叫API

2.請"正確"的計算每一筆扣款後的餘額(包含派彩),HTTP狀態碼回200一律視為正常下注,請謹慎回傳

```
POST ( 营运商 API 位址 )/debit
```

**請求参数:**

| 名称          | 类型     | 是否必须 | 描述                                       |
| ----------- | ------ | ---- | ---------------------------------------- |
| token       | string | YES  | 营运商提供的玩家令牌                               |
| operatorID  | string | YES  | 营运商ID                                    |
| appSecret   | string | YES  | 平台提供的凭证金钥                                |
| playerID    | string | YES  | 玩家ID                                     |
| gameID      | string | YES  | 游戏ID                                     |
| gameRoundID | string | YES  | 游戏局ID                                    |
| currency    | string | YES  | 货币代码                                     |
| time        | int64  | YES  | 交易时间 (millisecond)                       |
| ip          | string | YES  | 客户IP                                     |
| betID       | string | YES  | 注单ID                                     |
| parentBetID | string | YES  | 父注单编号                                    |
| betType     | string | YES  | 下注类型,请参考betCode                          |
| amount      | int64  | YES  | 金额 (单位:分 最大长度: 1000億分)                   |
| type        | string | YES  | <p>交易类型:<br>● 投注 - bet<br>● 小费 - tip</p> |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述              |
| -------- | ------ | ---- | --------------- |
| balance  | int64  | YES  | 玩家餘額(单位:分)      |
| currency | string | YES  | 货币              |
| time     | int64  | NO   | 时间(millisecond) |

**回傳成功範例:**

```json
{     
  "balance": 300000,                // int64 玩家餘額(单位:分)
  "currency": "RMB",                // string 货币
  "time": 1574476825000             // int64 时间(millisecond)
}
```

## 增加余额

增加营运商玩家余额，回传余额以分为单位，且必须为整数

营运商回传失败时，每小时会重发一次，为了避免发生重复结算，营运商必须检查注单是否已经结算

备注:

```
1.odds支援所有游戏,支援到小數點後６位數
2.发送次数以betID为单位,一个betID发送一次
3.如果线路不稳定，或回传失败，则每小时发送一次，持续10天
4.回传为"阵列"，同一局，同一玩家的游戏会同时传送      
5.當後台已結算，但是API未收到時，意味著貴司線路不穩定導致發送失敗，系統將會每小時重發一次，請先檢查線問是否穩定
```

```
POST ( 营运商 API 位址 )/credit
```

**請求参数:**

| 名称   | 类型            | 是否必须 | 描述                                                    |
| ---- | ------------- | ---- | ----------------------------------------------------- |
| data | string (json) | YES  | 增加餘額資料 ex: `[{"operatorID": "","appSecret": "",...}]` |

**增加餘額資料結構**

| 名称             | 类型     | 是否必须 | 描述                                       |
| -------------- | ------ | ---- | ---------------------------------------- |
| operatorID     | string | YES  | 营运商ID                                    |
| appSecret      | string | YES  | 平台提供的凭证金钥                                |
| playerID       | string | YES  | 玩家ID                                     |
| gameID         | string | YES  | 游戏ID                                     |
| betID          | string | YES  | 注单ID                                     |
| amount         | string | YES  | 金額 ( 單位:分 )                              |
| gameStatus     | string | YES  | [遊戲狀態](/enum/enum-single-game-status.md) |
| gameResult     | string | YES  | [遊戲結果](/enum/enum-game-result.md)        |
| roundCard      | string | YES  | [遊戲牌局卡牌](/enum/enum-roundcard.md)        |
| roundWin       | string | YES  | [遊戲牌局結果](/enum/enum-roundwin.md)         |
| validBetAmount | string | YES  | 有效投注额( 單位:分 )                            |
| currency       | string | YES  | 货币代码                                     |
| time           | int64  | YES  | 交易时间 (millisecond)                       |
| type           | string | YES  | [交易類型](/enum/enum-single-credit-type.md) |
| odds           | string | YES  | 賠率                                       |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述               |
| -------- | ------ | ---- | ---------------- |
| balance  | int64  | YES  | 玩家餘額(单位:分)       |
| currency | string | YES  | 货币               |
| time     | int64  | NO   | 时间(millisecond ) |
| refID    | string | NO   | 交易编号             |

**回傳成功範例:**

```json
{     
  "balance": 300000,                // int64 玩家餘額(单位:分)
  "currency": "RMB",                // string 货币
  "time": 1574476825000             // int64 时间(millisecond)
}
```

**回傳錯誤範例:**

```json
// HTTP状态码:409:重复交易等状况
{
  "error": "Duplicate transaction"
}
```

```json
// HTTP状态码:410:无法派彩等状况
{
  "error": "Can't credit"
}
```

## 重新結算

當注單結算後,平台判斷需更改遊戲結果時,回傳該局必須修正的金額,

營運商回傳餘額以分為單位,且必須為整數,營運商對接此接口,請先提出申請。

备注:

```
1.odds支援所有游戏,支援到小數點後６位數
2.发送次数以betID为单位,一个betID发送一次
3.如果线路不稳定，或回传失败，则每小时发送一次，持续10天
```

```
POST ( 营运商 API 位址 )/resettlement
```

**請求参数:**

| 名称   | 类型            | 是否必须 | 描述                                                    |
| ---- | ------------- | ---- | ----------------------------------------------------- |
| data | string (json) | YES  | 重新結算資料 ex: `[{"operatorID": "","appSecret": "",...}]` |

**重新結算資料結構**

基於[增加餘額結構](#zeng-jia-yu-e)增加兩個參數(resettleTime, resettleAmount)

| 名称             | 类型     | 是否必须 | 描述                     |
| -------------- | ------ | ---- | ---------------------- |
| resettleTime   | int64  | YES  | 重新结算时间(millisecond)    |
| resettleAmount | string | YES  | 最後一次重新結算 派彩金額 ( 單位:分 ) |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述              |
| -------- | ------ | ---- | --------------- |
| balance  | int64  | YES  | 玩家餘額(单位:分)      |
| currency | string | YES  | 货币              |
| time     | int64  | NO   | 时间(millisecond) |
| refID    | string | NO   | 交易编号            |

**回傳成功範例:**

```json
{     
  "balance": 300000,                // int64 玩家餘額(单位:分)
  "currency": "RMB",                // string 货币
  "time": 1574476825000             // int64 时间(millisecond)
}
```

**回傳錯誤範例:**

```json
// HTTP状态码:409:重复交易等状况
{
  "error": "Duplicate transaction"
}
```

```json
// HTTP状态码:410:无法派彩等状况
{
  "error": "Can't credit"
}
```

## 取消交易

当游戏发生错误,我方判断游戏局取消时，回传该局必须返还给玩家的余额

```
POST ( 营运商 API 位址 )/rollback
```

**請求参数:**

| 名称         | 类型     | 是否必须 | 描述                                                                     |
| ---------- | ------ | ---- | ---------------------------------------------------------------------- |
| operatorID | string | YES  | 营运商ID                                                                  |
| appSecret  | string | YES  | 平台提供的凭证金钥                                                              |
| playerID   | string | YES  | 玩家ID                                                                   |
| gameID     | string | YES  | 游戏ID                                                                   |
| betID      | string | YES  | 注单ID                                                                   |
| amount     | string | YES  | <p>金額 ( 單位:分 )<br>总金额 = 投注 - 已派彩金额<br>正数: 增加玩家余额<br>0 : 由营运商处理此笔交易</p> |
| currency   | string | YES  | 货币代码                                                                   |
| time       | int64  | YES  | 交易时间 (millisecond)                                                     |
| type       | string | YES  | 交易類型 cancel                                                            |

**回應參數:**

| 名称       | 类型     | 是否必须 | 描述               |
| -------- | ------ | ---- | ---------------- |
| balance  | int64  | YES  | 玩家餘額(单位:分)       |
| currency | string | YES  | 货币               |
| time     | int64  | NO   | 时间(millisecond ) |
| refID    | string | NO   | 交易编号             |

**回傳成功範例:**

```json
{     
  "balance": 300000,                // int64 玩家餘額(单位:分)
  "currency": "RMB",                // string 货币
  "time": 1574476825000             // int64 时间(millisecond)
}
```

**回傳錯誤範例:**

```json
// HTTP状态码:400:非法請求
{
  "error": "Bad Request"
}
```

```json
// HTTP状态码:409:重复交易等状况
{
  "error": "Duplicate transaction"
}
```

## 網路檢查

驗證商戶callback是否暢通，請響應HTTP狀態碼200即可

```
POST ( 营运商 API 位址 )/netcheck
```

**回應參數:**

| 名称         | 类型     | 是否必须 | 描述    |
| ---------- | ------ | ---- | ----- |
| operatorID | string | YES  | 营运商ID |

**回傳成功範例:**

```json
{     
  "operatorID": "test12345"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pkg333.app/single-wallet-api_cn.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.