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

# OTC 回调通知

> OTC 入金与出金订单状态变更时，系统会向商户配置的回调地址发送通知。

## 概述

本页说明 `webhook otcCallbackNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

用于接收 OTC 入金与出金订单状态变更通知。

## 说明

* 建议基于 `bizId` 或 `clientOrderId` 做幂等处理。
* 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

* OTC 入金或出金订单状态变更时，GatePay 向商户配置的 **callback URL** 发送通知
* 若通知投递失败，重试规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。

## bizStatus 枚举值

| 值                     | 说明              |
| --------------------- | --------------- |
| `RECHARGE_SUCCESS`    | OTC 入金成功        |
| `RECHARGE_FAIL`       | OTC 入金失败        |
| `WITHDRAW_DISPATCHED` | OTC 出金已出款 / 已派发 |
| `WITHDRAW_SUCCESS`    | OTC 出金成功        |
| `WITHDRAW_FAIL`       | OTC 出金失败        |

## 消息结构

| 字段名         | 类型     | 说明                            |
| ----------- | ------ | ----------------------------- |
| `bizType`   | string | 固定为 `OTC`                     |
| `bizId`     | string | OTC 订单 ID                     |
| `bizStatus` | string | 订单状态，例如 `WITHDRAW_DISPATCHED` |
| `clientId`  | string | 商户 `client_id`                |
| `data`      | string | 订单明细 JSON 字符串                 |

### data 字段说明

| 字段名               | 类型     | 说明                      |
| ----------------- | ------ | ----------------------- |
| `type`            | string | 交易方向，例如 `BUY`、`SELL`    |
| `orderId`         | string | 平台订单 ID                 |
| `clientOrderId`   | string | 商户侧订单号                  |
| `fiatCurrency`    | string | 法币币种                    |
| `fiatAmount`      | string | 法币金额                    |
| `cryptoCurrency`  | string | 加密货币币种                  |
| `cryptoAmount`    | string | 加密货币数量                  |
| `fiatRate`        | string | 汇率                      |
| `finalFiatAmount` | string | 最终法币金额                  |
| `updateTime`      | string | 更新时间（毫秒时间戳字符串）          |
| `bankSlipInfo`    | string | 银行水单 / 回单 URL（出金场景可能出现） |
| `errMsg`          | string | 错误信息（成功时为空）             |
| `promoCode`       | string | 优惠码（如有）                 |

## 回调示例（出金 `WITHDRAW_DISPATCHED`）

```json theme={null}
{
  "bizType": "OTC",
  "bizId": "79550727153516602",
  "bizStatus": "WITHDRAW_DISPATCHED",
  "clientId": "UGxnuTtJHDuXPjYm",
  "data": "{\"type\":\"SELL\",\"errMsg\":\"\",\"orderId\":\"79550727153516602\",\"fiatRate\":\"1\",\"promoCode\":\"\",\"fiatAmount\":\"124710\",\"updateTime\":\"1779958032486\",\"bankSlipInfo\":\"https://gateio-payments.s3.ap-northeast-1.amazonaws.com/otc_trade_file/otc-trade-record-file43255011-d96f549e1869e47908db891fb512c308.pdf\",\"cryptoAmount\":\"124710\",\"fiatCurrency\":\"USD\",\"clientOrderId\":\"PCC101800177995803114487146200\",\"cryptoCurrency\":\"USDT\",\"finalFiatAmount\":\"124710\"}"
}
```

## 回调示例（入金 `RECHARGE_SUCCESS`）

```json theme={null}
{
  "bizType": "OTC",
  "bizId": "79550727153516601",
  "bizStatus": "RECHARGE_SUCCESS",
  "clientId": "UGxnuTtJHDuXPjYm",
  "data": "{\"type\":\"BUY\",\"errMsg\":\"\",\"orderId\":\"79550727153516601\",\"fiatRate\":\"1\",\"promoCode\":\"\",\"fiatAmount\":\"10000\",\"updateTime\":\"1779958032486\",\"cryptoAmount\":\"10000\",\"fiatCurrency\":\"USD\",\"clientOrderId\":\"PCC101800177995803114487146201\",\"cryptoCurrency\":\"USDT\",\"finalFiatAmount\":\"10000\"}"
}
```


## OpenAPI

````yaml api-reference/version/100/cn/openapi/otc-fiat-openapi.json webhook otcCallbackNotify
openapi: 3.1.0
info:
  title: GatePay OTC 法币 API
  description: OTC 法币出金与入金 API 参考。
  version: 2.1.0
servers:
  - url: https://openplatform.gateapi.io
security: []
paths: {}

````