OTC Order Status Update Notification

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

otcCallbackWebhook

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

Overview

This page documents webhook otcCallbackWebhook. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. Use this webhook to receive OTC on-ramp and off-ramp order status change notifications.

Notes

Use bizId or clientOrderId for idempotency.
For OTC callbacks, data is a JSON string — call JSON.parse before reading fields. See below for the parsed structure.
Signature verification, retries, and the success response are covered in Notifications Overview; see Security and Signature for signing rules.

Trigger scenarios

GatePay sends notifications when OTC on-ramp or off-ramp order status changes
If delivery fails, GatePay retries according to the schedule in Notifications overview

Message Structure

Field	Type	Description
`bizType`	string	Always `OTC`
`bizId`	string	OTC order ID
`bizStatus`	string	OTC callback business status: `RECHARGE_SUCCESS` on-ramp succeeded, `RECHARGE_FAIL` on-ramp failed, `WITHDRAW_DISPATCHED` off-ramp payout dispatched, `WITHDRAW_SUCCESS` off-ramp succeeded, `WITHDRAW_FAIL` off-ramp failed, `WITHDRAW_REFUND` off-ramp refunded after successful payout
`clientId`	string	Merchant client ID
`data`	string	Order details as a JSON string; on-ramp (`type`=`BUY`) and off-ramp (`type`=`SELL`) differ after parsing — see Option below or field tables

On-ramp data fields (`type`=`BUY`, `bizStatus` is `RECHARGE_*`)

Field	Type	Description
`type`	string	Always `BUY`
`orderId`	string	Platform order ID
`clientOrderId`	string	Merchant-side order ID
`fiatCurrency`	string	Fiat currency
`fiatAmount`	string	Fiat amount
`cryptoCurrency`	string	Cryptocurrency
`cryptoAmount`	string	Cryptocurrency amount
`fiatRate`	string	Exchange rate
`updateTime`	string	Update time (millisecond timestamp string)
`errMsg`	string	Error message
`promoCode`	string	Promo code
`transferRemark`	string	Transfer remark
`paymentReceiptFileUrl`	string	Payment receipt download URL
`tradeFee`	string	Total amount of all fee items.
`feeCurrency`	string	Currency in which each fee item is denominated.
`feeDetail`	array	Fee breakdown; see `feeDetail[]` below

Off-ramp data fields (`type`=`SELL`, `bizStatus` is `WITHDRAW_*`)

Field	Type	Description
`type`	string	Always `SELL`
`orderId`	string	Platform order ID
`clientOrderId`	string	Merchant-side order ID
`fiatCurrency`	string	Fiat currency
`fiatAmount`	string	Fiat amount
`cryptoCurrency`	string	Cryptocurrency
`cryptoAmount`	string	Cryptocurrency amount
`fiatRate`	string	Exchange rate
`updateTime`	string	Update time (millisecond timestamp string)
`finalFiatAmount`	string	Final fiat amount
`bankSlipInfo`	string	Bank receipt / slip URL
`errMsg`	string	Error message
`promoCode`	string	Promo code
`refundAmount`	string	Refunded cryptocurrency amount
`tradeFee`	string	Total amount of all fee items.
`feeCurrency`	string	Currency in which each fee item is denominated.
`feeDetail`	array	Fee breakdown; see `feeDetail[]` below

feeDetail[] fields

Field	Type	Description
`feeType`	string	Fee type: `BANK` fee charged by the bank channel, `GATE_PAY` Gate Pay service fee amount, `SUBSIDY` promotional amount deducted from charged fees
`amount`	string	Amount for this fee item.

Callback examples

On-ramp success (`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\"}]}"
}

Off-ramp dispatched (`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\"}]}"
}

Body

application/json

OTC order status callback notification structure

bizType

string

required

Fixed OTC business type.

bizId

string

required

OTC order ID.

bizStatus

string

required

OTC callback business status: RECHARGE_SUCCESS on-ramp succeeded, RECHARGE_FAIL on-ramp failed, WITHDRAW_DISPATCHED off-ramp payout dispatched, WITHDRAW_SUCCESS off-ramp succeeded, WITHDRAW_FAIL off-ramp failed, WITHDRAW_REFUND off-ramp refunded after successful payout

data

On-ramp (BUY) · object

required

Order details as a JSON string; on-ramp (type=BUY) and off-ramp (type=SELL) parsed structures differ — see Option below.

On-ramp (BUY)
Off-ramp (SELL)

Show child attributes

clientId

string

Merchant client ID.

Response

200 - application/json

Returns HTTP 200 to indicate the notification has been received successfully.

Response body returned by the merchant after receiving the notification.

returnCode

string

required

Return status code; SUCCESS indicates successful processing.

returnMessage

string | null

Return message; may be empty on success.

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

OTC Order Status Update Notification

Overview

Notes

Trigger scenarios

Message Structure

On-ramp data fields (`type`=`BUY`, `bizStatus` is `RECHARGE_*`)

Off-ramp data fields (`type`=`SELL`, `bizStatus` is `WITHDRAW_*`)

feeDetail[] fields

Callback examples

On-ramp success (`bizStatus=RECHARGE_SUCCESS`)

Off-ramp dispatched (`bizStatus=WITHDRAW_DISPATCHED`)

Body

Response

​Overview

​Notes

​Trigger scenarios

​Message Structure

​On-ramp data fields (type=BUY, bizStatus is RECHARGE_*)

​Off-ramp data fields (type=SELL, bizStatus is WITHDRAW_*)

​feeDetail[] fields

​Callback examples

​On-ramp success (bizStatus=RECHARGE_SUCCESS)

​Off-ramp dispatched (bizStatus=WITHDRAW_DISPATCHED)

Body

Response

Overview

Notes

Trigger scenarios

Message Structure

On-ramp data fields (`type`=`BUY`, `bizStatus` is `RECHARGE_*`)

Off-ramp data fields (`type`=`SELL`, `bizStatus` is `WITHDRAW_*`)

feeDetail[] fields

Callback examples

On-ramp success (`bizStatus=RECHARGE_SUCCESS`)

Off-ramp dispatched (`bizStatus=WITHDRAW_DISPATCHED`)