> ## 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` 做幂等处理。
* OTC 回调的 `data` 为 **JSON 字符串**，须 `JSON.parse` 后再读字段；解析后结构见下方说明。
* 验签、重试与成功应答见 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/global/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

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

## 消息结构

| 字段名 | 类型 | 说明 |
| - | - | - |
| `bizType` | string | 固定为 `OTC` |
| `bizId` | string | OTC 订单 ID |
| `bizStatus` | string | OTC 回调业务状态：`RECHARGE_SUCCESS` 入金成功，`RECHARGE_FAIL` 入金失败，`WITHDRAW_DISPATCHED` 出金已出款/已派发，`WITHDRAW_SUCCESS` 出金成功，`WITHDRAW_FAIL` 出金失败，`WITHDRAW_REFUND` 出金退票（提现成功后退票） |
| `clientId` | string | 商户 clientId |
| `data` | string | 订单明细 JSON 字符串，入金（`type`=`BUY`）与出金（`type`=`SELL`）结构不同，解析后见下方 Option 或说明 |

### 入金 data 字段（`type`=`BUY`，`bizStatus` 为 `RECHARGE_*`）

| 字段名 | 类型 | 说明 |
| - | - | - |
| `type` | string | 固定为 `BUY` |
| `orderId` | string | 平台订单 ID |
| `clientOrderId` | string | 商户侧订单号 |
| `fiatCurrency` | string | 法币币种 |
| `fiatAmount` | string | 法币金额 |
| `cryptoCurrency` | string | 加密货币币种 |
| `cryptoAmount` | string | 加密货币数量 |
| `fiatRate` | string | 汇率 |
| `updateTime` | string | 更新时间（毫秒时间戳字符串） |
| `errMsg` | string | 错误信息 |
| `promoCode` | string | 优惠码 |
| `transferRemark` | string | 转账备注 |
| `paymentReceiptFileUrl` | string | 付款回执短时下载链接 |
| `tradeFee` | string | 各费用项的合计金额。 |
| `feeCurrency` | string | 各费用项的计价币种。 |
| `feeDetail` | array | 费用明细，见下方 `feeDetail[]` |

### 出金 data 字段（`type`=`SELL`，`bizStatus` 为 `WITHDRAW_*`）

| 字段名 | 类型 | 说明 |
| - | - | - |
| `type` | string | 固定为 `SELL` |
| `orderId` | string | 平台订单 ID |
| `clientOrderId` | string | 商户侧订单号 |
| `fiatCurrency` | string | 法币币种 |
| `fiatAmount` | string | 法币金额 |
| `cryptoCurrency` | string | 加密货币币种 |
| `cryptoAmount` | string | 加密货币数量 |
| `fiatRate` | string | 汇率 |
| `updateTime` | string | 更新时间（毫秒时间戳字符串） |
| `finalFiatAmount` | string | 最终法币金额 |
| `bankSlipInfo` | string | 银行水单 / 回单 URL |
| `errMsg` | string | 错误信息 |
| `promoCode` | string | 优惠码 |
| `refundAmount` | string | 退票退回的加密货币金额 |
| `tradeFee` | string | 各费用项的合计金额。 |
| `feeCurrency` | string | 各费用项的计价币种。 |
| `feeDetail` | array | 费用明细，见下方 `feeDetail[]` |

### feeDetail\[] 字段

| 字段名 | 类型 | 说明 |
| - | - | - |
| `feeType` | string | 费用类型：`BANK` 银行渠道收取的费用，`GATE_PAY` Gate Pay 手续费金额，`SUBSIDY` 优惠金额，从收取的费用中减免 |
| `amount` | string | 该项金额。 |

## 回调示例

### 入金成功（`bizStatus=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\",\"transferRemark\":\"\",\"paymentReceiptFileUrl\":\"\",\"tradeFee\":\"100\",\"feeCurrency\":\"USD\",\"feeDetail\":[{\"feeType\":\"BANK\",\"amount\":\"30\"},{\"feeType\":\"GATE_PAY\",\"amount\":\"80\"},{\"feeType\":\"SUBSIDY\",\"amount\":\"10\"}]}"
}
```

### 出金已出款（`bizStatus=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\",\"tradeFee\":\"10.88\",\"feeCurrency\":\"USDT\",\"feeDetail\":[{\"feeType\":\"BANK\",\"amount\":\"2.00\"},{\"feeType\":\"GATE_PAY\",\"amount\":\"10.00\"},{\"feeType\":\"SUBSIDY\",\"amount\":\"1.12\"}]}"
}
```


## OpenAPI

````yaml global/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: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.