> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igamingace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel

当玩家投注未能完成时（因网络问题、超时或系统错误），会发送 `cancel`（取消）回调。你的服务器必须将完整投注金额退还至玩家余额，以确保账户准确。该操作为幂等操作——若钱包收到多个带有相同 `transactionId` 的请求，退款只能登记一次。

***无需在回调 URL 末尾添加“Cancel”；您可以获取请求正文“command”来识别哪个回调即将到来。***

* **URL:** 你配置的 Callback URL(ex: [***https://mycallback.com/cb***](https://mycallback.com/cb))
* **Method:** POST
* **Headers:** `X-Request-Signature`, `Content-Type`, `Accept`

## Request parameters

<ParamField body="command" type="string" required>
  此回调类型始终为 `"cancel"`。
</ParamField>

<ParamField body="transactionId" type="long" required>
  本系统中创建的本次取消交易的唯一引用，用于实现幂等。
</ParamField>

<ParamField body="playerId" type="string" required>
  你系统中玩家的唯一标识。
</ParamField>

<ParamField body="roundId" type="long" required>
  游戏局的唯一引用。
</ParamField>

<ParamField body="providerId" type="number" required>
  本系统中游戏提供商的唯一标识。
</ParamField>

<ParamField body="gameCode" type="number" required>
  本系统中游戏的唯一游戏 ID。
</ParamField>

<ParamField body="timestamp" type="number" required>
  请求的 Unix 时间戳。
</ParamField>

## Response fields

你的服务器必须返回 HTTP 200，以及包含以下字段的 JSON 正文：

<ResponseField name="balance" type="number" required>
  退款应用后玩家的最新余额。
</ResponseField>

<ResponseField name="statusCode" type="string" required>
  操作结果。成功时必须为 `"OK"`。所有可能取值见下方状态码表。
</ResponseField>

## Status codes

| 状态码                              | 说明               |
| :------------------------------- | :--------------- |
| `OK`                             | 请求成功             |
| `ERR_NOT_AUTHENTICATED`          | 玩家未通过身份验证        |
| `ERR_TRANSACTION_DOES_NOT_EXIST` | 你的系统中不存在所引用的投注交易 |
| `ERR_TRANSACTION_ROLLED_BACK`    | 所引用的交易已被回滚       |
| `ERR_INTEGRITY_CHECK_FAILED`     | 消息完整性校验失败        |
| `ERR_UNKNOWN`                    | 内部服务器错误          |

<Warning>
  你的响应必须在 4 秒内返回。若请求超时或返回错误，我们会自动最多再重试 2 次。
</Warning>

<Tip>
  请使用 `referenceId` 在数据库中定位原始投注。若该投注从未被记录（例如你的系统从未收到过），可安全返回 `OK` 及玩家当前余额——此时无需退款
</Tip>

## Examples

<CodeGroup>
  ```json Request theme={null}
  {
    "command": "cancel",
    "transactionId": "SP215202",
    "referenceId": "SP215201",
    "playerId": "1101",
    "roundId": "65215842315484512",
    "providerId": 1,
    "gameCode": 655,
    "timestamp": 1586335186372
  }
  ```

  ```json Success response theme={null}
  {
    "balance": 19839891,
    "statusCode": "OK"
  }
  ```

  ```json Error response theme={null}
  {
    "statusCode": "ERR_TRANSACTION_DOES_NOT_EXIST",
    "balance": 19839890
  }
  ```
</CodeGroup>