OTC 回调通知

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

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

WEBHOOK

otcCallbackNotify

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

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

概述

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

说明

建议基于 bizId 或 clientOrderId 做幂等处理。
OTC 回调的 data 为 JSON 字符串，须 JSON.parse 后再读字段；解析后结构见下方说明。
验签、重试与成功应答见通知概览；签名规则见安全与签名。

触发情形

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

消息结构

字段名	类型	说明
`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`）

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

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

请求体

application/json

OTC 订单状态回调通知结构

bizType

string

必填

固定的 OTC 业务类型。

bizId

string

必填

OTC 订单 ID。

bizStatus

string

必填

OTC 回调业务状态：RECHARGE_SUCCESS 入金成功，RECHARGE_FAIL 入金失败，WITHDRAW_DISPATCHED 出金已出款/已派发，WITHDRAW_SUCCESS 出金成功，WITHDRAW_FAIL 出金失败，WITHDRAW_REFUND 出金退票（提现成功后退票）

data

入金（BUY） · object

必填

订单明细 JSON 字符串，入金（type=BUY）与出金（type=SELL）解析后结构不同，见下方 Option。

入金（BUY）
出金（SELL）

Show child attributes

clientId

string

商户 clientId。

响应

200 - application/json

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

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

returnCode

string

必填

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

returnMessage

string | null

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

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

概述

说明

触发情形

消息结构

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

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

feeDetail[] 字段

回调示例

入金成功（`bizStatus=RECHARGE_SUCCESS`）

出金已出款（`bizStatus=WITHDRAW_DISPATCHED`）

请求体

响应

​概述

​说明

​触发情形

​消息结构

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

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

​feeDetail[] 字段

​回调示例

​入金成功（bizStatus=RECHARGE_SUCCESS）

​出金已出款（bizStatus=WITHDRAW_DISPATCHED）

请求体

响应

概述

说明

触发情形

消息结构

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

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

feeDetail[] 字段

回调示例

入金成功（`bizStatus=RECHARGE_SUCCESS`）

出金已出款（`bizStatus=WITHDRAW_DISPATCHED`）