OTC 回调通知

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

{
  "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_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	优惠码（如有）
`paymentReceiptFileUrl`	string	付款回执短时下载链接（如有）
`paymentReceiptFileUrl`	string	付款回执短时下载链接（如有）
`transferRemark`	string	转账备注（如有）

回调示例（出金 `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

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

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

概述

说明

触发情形

bizStatus 枚举值

消息结构

data 字段说明

回调示例（出金 `WITHDRAW_DISPATCHED`）

回调示例（入金 `RECHARGE_SUCCESS`）

请求体

响应

​概述

​说明

​触发情形

​bizStatus 枚举值

​消息结构

​data 字段说明

​回调示例（出金 WITHDRAW_DISPATCHED）

​回调示例（入金 RECHARGE_SUCCESS）

请求体

响应

概述

说明

触发情形

bizStatus 枚举值

消息结构

data 字段说明

回调示例（出金 `WITHDRAW_DISPATCHED`）

回调示例（入金 `RECHARGE_SUCCESS`）