跳转到主要内容
WEBHOOK
otcCallbackNotify
{
  "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\"}"
}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

​
概述

本页说明 webhook otcCallbackNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 用于接收 OTC 入金与出金订单状态变更通知。

​
说明

  • 建议基于 bizId 或 clientOrderId 做幂等处理。
  • 验签、重试、data 解析与成功应答见 通知概览；签名规则见 安全与签名。

​
触发情形

  • OTC 入金或出金订单状态变更时，GatePay 向商户配置的 callback URL 发送通知
  • 若通知投递失败，重试规则见 通知概览。

​
bizStatus 枚举值

值说明
RECHARGE_SUCCESSOTC 入金成功
RECHARGE_FAILOTC 入金失败
WITHDRAW_DISPATCHEDOTC 出金已出款 / 已派发
WITHDRAW_SUCCESSOTC 出金成功
WITHDRAW_FAILOTC 出金失败

​
消息结构

字段名类型说明
bizTypestring固定为 OTC
bizIdstringOTC 订单 ID
bizStatusstring订单状态，例如 WITHDRAW_DISPATCHED
clientIdstring商户 client_id
datastring订单明细 JSON 字符串

​
data 字段说明

字段名类型说明
typestring交易方向，例如 BUY、SELL
orderIdstring平台订单 ID
clientOrderIdstring商户侧订单号
fiatCurrencystring法币币种
fiatAmountstring法币金额
cryptoCurrencystring加密货币币种
cryptoAmountstring加密货币数量
fiatRatestring汇率
finalFiatAmountstring最终法币金额
updateTimestring更新时间（毫秒时间戳字符串）
bankSlipInfostring银行水单 / 回单 URL（出金场景可能出现）
errMsgstring错误信息（成功时为空）
promoCodestring优惠码（如有）

​
回调示例（出金 WITHDRAW_DISPATCHED）

{
  "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）

{
  "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\"}"
}

请求体

application/json

OTC 订单状态回调通知结构

​
bizType
string
必填

固定的 OTC 业务类型。

​
bizId
string
必填

OTC 订单 ID。

​
bizStatus
enum<string>
必填

OTC 回调业务状态。

可用选项:
RECHARGE_SUCCESS,
RECHARGE_FAIL,
WITHDRAW_SUCCESS,
WITHDRAW_FAIL,
WITHDRAW_DISPATCHED
​
data
string
必填

包含订单快照的 JSON 字符串。

​
clientId
string

商户 clientId。

​
client_id
string

部分集成中使用的备用商户 clientId 字段。

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收通知。

商户接收通知后的响应体。

​
returnCode
string
必填

返回状态码，SUCCESS 表示成功。

​
returnMessage
string | null

返回说明，成功时可为空。