> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OTC Order Status Update Notification

> OTC order result callback sent to the merchant callback URL for both on-ramp and off-ramp flows.

## 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](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) 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](/global/api-reference/version/100/en/common/asyncNotification)

## 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`)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "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\"}]}"
}
```


## OpenAPI

````yaml global/api-reference/version/100/en/openapi/otc-fiat-openapi.json webhook otcCallbackWebhook
openapi: 3.1.0
info:
  title: GatePay OTC Fiat API
  description: Reference for OTC fiat withdrawal and deposit APIs.
  version: 2.1.0
servers:
  - url: https://openplatform.gateapi.io
security: []
paths: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.