OTC Order Status Update Notification

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

otcCallbackWebhook

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

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 after parsing data.
Signature verification, retries, parsing data, 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

bizStatus values

Value	Description
`RECHARGE_SUCCESS`	OTC on-ramp succeeded
`RECHARGE_FAIL`	OTC on-ramp failed
`WITHDRAW_DISPATCHED`	OTC off-ramp payout dispatched
`WITHDRAW_SUCCESS`	OTC off-ramp succeeded
`WITHDRAW_FAIL`	OTC off-ramp failed

Message Structure

Field	Type	Description
`bizType`	string	Always `OTC`
`bizId`	string	OTC order ID
`bizStatus`	string	Order status, for example `WITHDRAW_DISPATCHED`
`clientId`	string	Merchant `client_id`
`data`	object	Order details object (not a JSON string)

data Field Reference

Field	Type	Description
`type`	string	Trade direction, for example `BUY`, `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
`finalFiatAmount`	string	Final fiat amount
`updateTime`	string	Update time (millisecond timestamp string)
`bankSlipInfo`	string	Bank receipt / slip URL (may appear in off-ramp scenarios)
`errMsg`	string	Error message (empty on success)
`promoCode`	string	Promo code (if any)

Callback Example (off-ramp `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"
  }
}

Callback example (on-ramp `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\"}"
}

Body

application/json

OTC order status callback notification structure

bizType

string

required

Fixed OTC business type.

bizId

string

required

OTC order ID.

bizStatus

enum<string>

required

OTC callback business status.

Available options:

RECHARGE_SUCCESS,

RECHARGE_FAIL,

WITHDRAW_SUCCESS,

WITHDRAW_FAIL,

WITHDRAW_DISPATCHED

data

string

required

JSON string containing the order snapshot.

clientId

string

Merchant client ID.

client_id

string

Alternate merchant client ID field used by some integrations.

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.

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

OTC Order Status Update Notification

Overview

Notes

Trigger scenarios

bizStatus values

Message Structure

data Field Reference

Callback Example (off-ramp `WITHDRAW_DISPATCHED`)

Callback example (on-ramp `RECHARGE_SUCCESS`)

Body

Response

​Overview

​Notes

​Trigger scenarios

​bizStatus values

​Message Structure

​data Field Reference

​Callback Example (off-ramp WITHDRAW_DISPATCHED)

​Callback example (on-ramp RECHARGE_SUCCESS)

Body

Response

Overview

Notes

Trigger scenarios

bizStatus values

Message Structure

data Field Reference

Callback Example (off-ramp `WITHDRAW_DISPATCHED`)

Callback example (on-ramp `RECHARGE_SUCCESS`)