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

# Webhook Structure

## Структура Payload

Каждое событие содержит объект `data` с данными о транзакции на момент события. Структура payload одинакова для всех типов событий, но значения полей различаются в зависимости от типа транзакции и этапа её жизненного цикла.

```json theme={null}
{
  id: "uuid",                          // Идентификатор транзакции
  externalId: "string",                // Внешний идентификатор
  type: "Buy" | "Sale",                // "Buy" = вывод, "Sale" = пополнение
  status: "TransactionStatus",         // Текущий статус

  // Валюта и пара
  pair: "string",                      // Торговая пара: "USDT/TRX" (вывод) или "BTC/USDT" (пополнение)
  currency: "string",                  // Целевая валюта
  network: "string",                   // Блокчейн-сеть: "TRC20", "ERC20", "Bitcoin" и т.д.

  // Суммы (см. раздел "Пояснение полей сумм" ниже)
  requestedAmount: "string",           // Чистая сумма, которую получает пользователь (при выводе) или ожидает внести (при пополнении)
  expectedAmount: "string",            // Общая сумма с комиссией сети (вывод) или то же, что requestedAmount (пополнение)
  amount: "string | null",             // Кумулятивная фактическая сумма. null до обработки.
  usdtTotal: "string | null",          // USDT зарезервированные с удержанием (вывод) или кумулятивная сумма зачисленных USDT (пополнение)
  exchangeRate: "string | null",       // Предварительный курс при создании, фактический курс после конвертации
  dealFee: "string | null",            // Комиссия, начисленная за транзакцию

  // Информация о полученном депозите (только для события `deposit_received` пополнения)
  receivedCurrency: "string | null",   // Фактически полученная криптовалюта
  receivedNetwork: "string | null",    // Сеть полученной криптовалюты
  receivedAmount: "string | null",     // Фактическая сумма пополнения (НЕ кумулятивная)

  // Блокчейн
  address: "string",                   // Адрес назначения (вывода) или адрес депозита (пополнение)
  hash: "string | null",               // Хеш блокчейн-транзакции, пустая строка до появления
  memo: "string | null",               // Memo/tag для сетей, которые этого требуют (XRP, XLM и т.д.)

  // Метаданные
  merchantId: "uuid",                  // Идентификатор мерчанта
  cancelReason: "string | null",       // Причина отмены (только для событий отмены/ошибки)
  createdAt: "ISO 8601",               // Время создания транзакции
  updatedAt: "ISO 8601",               // Время последнего обновления
  completedAt: "ISO 8601 | null"       // Время завершения, null до финализации
}
```

### Пояснение полей сумм

Есть четыре поля, связанных с суммами, и они имеют разное назначение в зависимости от типа транзакции.

#### Вывод (Buy)

| Поле              | Значение                                                             | Пример        |
| ----------------- | -------------------------------------------------------------------- | ------------- |
| `requestedAmount` | Чистая сумма, которую пользователь получит в блокчейне               | `"25"` TRX    |
| `expectedAmount`  | Общая сумма с комиссией сети: `requestedAmount + networkFee`         | `"25.5"` TRX  |
| `amount`          | Фактически отправленная сумма (сообщается после отправки в блокчейн) | `"25"` TRX    |
| `usdtTotal`       | USDT зарезервированные с баланса, включая буфер удержания 1.25%      | `"7.52"` USDT |

Если интегратор передаёт `includeFeeInAmount: true`, расчёт меняется на обратный: `expectedAmount` = исходная сумма, `requestedAmount` = исходная сумма - networkFee. Соотношение всегда: `expectedAmount = requestedAmount + networkFee`.

`usdtTotal` рассчитывается так: конвертированный `expectedAmount` в USDT по предварительному курсу, затем добавленный буфер удержания 1.25%. Это общая сумма USDT, списываемая с баланса мерчанта. После конвертации излишек удержания возвращается.

Пример:

```
Вы запрашивает: вывести 25 TRX
  requestedAmount = "25"       ← что получит пользователь
  expectedAmount  = "25.5"     ← 25 + 0.5 комиссия сети
  exchangeRate    = "0.2971"   ← предварительный курс USDT/TRX
  usdtTotal       = "7.68"    ← (25.5 × 0.2971) × 1.0125 буфер удержания

После отправки в блокчейн:
  amount          = "25"       ← фактически отправлено
```

#### Пополнение (Sale)

| Поле              | Значение                                                                       | Пример         |
| ----------------- | ------------------------------------------------------------------------------ | -------------- |
| `requestedAmount` | Сумма, которую интегратор ожидает получить в качестве депозита                 | `"0.001"` BTC  |
| `expectedAmount`  | То же, что `requestedAmount`                                                   | `"0.001"` BTC  |
| `amount`          | Кумулятивная фактическая сумма депозитов по всем частичным внесениям           | `"0.0012"` BTC |
| `receivedAmount`  | Сумма отдельного депозита в `receivedCurrency` (только при `deposit_received`) | `"0.0005"` BTC |
| `usdtTotal`       | Кумулятивная сумма USDT, зачисленная на баланс мерчанта (после комиссий)       | `"45.30"` USDT |

Для пополнения `requestedAmount` и `expectedAmount` всегда одинаковы. Поле `amount` показывает фактическую общую полученную сумму. Сравнивая `amount` с `expectedAmount`, система определяет статус транзакции: `Paid` (ровная сумма), `Overpaid` (сумма больше), `Underpaid` (сумма меньше).

Пример:

```
Вы создаёте заказ: пополнение 0.001 BTC
  requestedAmount = "0.001"    ← ожидаемый депозит
  expectedAmount  = "0.001"    ← то же значение
  amount          = null       ← депозита ещё нет
  usdtTotal       = null

После подтверждения депозита:
  amount          = "0.0012"   ← фактически получено (переплата)
  usdtTotal       = "45.30"   ← зачислено USDT после комиссий
  exchangeRate    = "37750"    ← курс BTC/USDT
  status          = "Overpaid"
```

Сводка

| Поле              | Вывод                                       | Пополнение                               |
| ----------------- | ------------------------------------------- | ---------------------------------------- |
| `requestedAmount` | Чистая сумма к получению (без комиссии)     | Ожидаемая сумма депозита                 |
| `expectedAmount`  | Полная сумма (с комиссией сети)             | То же, что `requestedAmount`             |
| `amount`          | Расчитанная сумма                           | Кумулятивная фактическая сумма депозитов |
| `usdtTotal`       | Зарезервированные USDT (с удержанием 1.25%) | Кумулятивная сумма зачисленных USDT      |

## Значения статусов

| Status                 | Используется в | Описание                                            |
| ---------------------- | -------------- | --------------------------------------------------- |
| `Queued`               | Вывод          | В очереди на обработку                              |
| `New`                  | Пополнение     | Заказ создан, ожидается депозит                     |
| `Waiting`              | Пополнение     | Подтверждение в блокчейне в процессе                |
| `Paid`                 | Пополнение     | Депозит соответствует ожидаемой сумме               |
| `Overpaid`             | Пополнение     | Депозит превышает ожидаемую сумму                   |
| `Underpaid`            | Пополнение     | Депозит меньше ожидаемой суммы                      |
| `Canceled`             | Оба            | Транзакция отменена / отклонена / ошибка            |
| `CurrencyMismatch`     | Пополнение     | Внесена неверная криптовалюта                       |
| `CanceledButPaid`      | Пополнение     | Заказ просрочен/отклонён, но получен точный депозит |
| `CanceledButOverpaid`  | Пополнение     | Заказ просрочен/отклонён, но получена переплата     |
| `CanceledButUnderpaid` | Пополнение     | Заказ просрочен/отклонён, но получена недоплата     |

## Логика валют

Поле `currency` отображает то, что ожидалось, а не то, что было фактически получено:

* Вывод: целевая криптовалюта, которая покупается (например, `"TRX"`, `"BTC"`)
* Пополнение: ожидаемая криптовалюта для депозита из конфигурации заказа (например, `"BTC"`)

Фактически полученная криптовалюта указывается в `receivedCurrency` (см. ниже).

### Поля получения (`receivedCurrency`, `receivedNetwork`, `receivedAmount`)

Эти три поля отображают то, что фактически было внесено в блокчейн для конкретного депозита. Они заполняются только для события `deposit_received` и всегда `null` для всех остальных событий.

* `receivedAmount` фактически зачисленная сумма, а НЕ кумулятивный итог (используйте `amount` для кумулятивного)
* `receivedCurrency` — фактически зачисленная криптовалюта
* `receivedNetwork` — сеть фактически зачисленной криптовалюты

| Сценарий                           | `receivedCurrency`             | `receivedNetwork` | `receivedAmount`          |
| ---------------------------------- | ------------------------------ | ----------------- | ------------------------- |
| Вывод (любое событие)              | `null`                         | `null`            | `null`                    |
| Пополнение — `deposit_received`    | фактический тикер криптовалюты | сеть депозита     | сумма отдельного депозита |
| Пополнение — все остальные события | `null`                         | `null`            | `null`                    |

### Детали полей по событиям

#### События вывода

| Поле           | `created`            | `completed`        | `declined` | `failed`            | `canceled`      |
| -------------- | -------------------- | ------------------ | ---------- | ------------------- | --------------- |
| `status`       | `Queued`             | финальный статус   | `Canceled` | `Canceled`          | `Canceled`      |
| `amount`       | `null`               | финальная сумма    | из БД      | из БД               | из БД           |
| `hash`         | `""`                 | хеш блокчейна      | хеш        | может быть `""`     | может быть `""` |
| `usdtTotal`    | сумма резерва        | финальное значение | из БД      | из БД               | из БД           |
| `exchangeRate` | предварительный курс | фактический курс   | из БД      | из БД               | из БД           |
| `dealFee`      | `"0"`                | рассчитано         | из БД      | из БД               | из БД           |
| `cancelReason` | `null`               | `null`             | причина    | сообщение об ошибке | причина отката  |
| `completedAt`  | `null`               | метка времени      | `null`     | `null`              | `null`          |
| `received*`    | `null`               | `null`             | `null`     | `null`              | `null`          |

#### События пополнения

| Поле               | `created`              | `confirmation_started` | `deposit_received`        | `completed` / `overpaid` / `underpaid` / `currency_mismatch` | `declined`              | `canceled`             |
| ------------------ | ---------------------- | ---------------------- | ------------------------- | ------------------------------------------------------------ | ----------------------- | ---------------------- |
| `status`           | `New`                  | `Waiting`              | зависит                   | зависит                                                      | зависит                 | `Canceled`             |
| `currency`         | ожидаемая криптовалюта | ожидаемая криптовалюта | ожидаемая криптовалюта    | ожидаемая криптовалюта                                       | ожидаемая криптовалюта  | ожидаемая криптовалюта |
| `receivedCurrency` | `null`                 | `null`                 | фактическая криптовалюта  | `null`                                                       | `null`                  | `null`                 |
| `receivedNetwork`  | `null`                 | `null`                 | сеть депозита             | `null`                                                       | `null`                  | `null`                 |
| `receivedAmount`   | `null`                 | `null`                 | сумма отдельного депозита | `null`                                                       | `null`                  | `null`                 |
| `amount`           | `null`                 | `null`                 | кумулятивная              | кумулятивная                                                 | кумулятивная или `null` | `null`                 |
| `hash`             | `""`                   | хеш блокчейна          | хеш                       | хеш                                                          | хеш                     | `""`                   |
| `usdtTotal`        | `null`                 | `null`                 | кумулятивная USDT         | кумулятивная USDT                                            | кумулятивная или `null` | `null`                 |
| `exchangeRate`     | `null`                 | `null`                 | взвешенное среднее        | взвешенное среднее                                           | из БД                   | `null`                 |
| `dealFee`          | `null`                 | `null`                 | рассчитано                | рассчитано                                                   | из БД                   | `null`                 |
| `completedAt`      | `null`                 | `null`                 | если доступно             | если доступно                                                | если доступно           | `null`                 |
| `cancelReason`     | `null`                 | `null`                 | `null`                    | `null`                                                       | `null`                  | `null`                 |

Примечания:

* `deposit_received` всегда отправляется вместе с одним из: `completed`, `overpaid`, `underpaid` или `currency_mismatch`
* `declined` может содержать или не содержать данные депозита, в зависимости от того, были ли получены депозиты до отклонения
* Суммы пополнения являются кумулятивными по нескольким депозитам (каждый вебхук `was_final_exchange` добавляется к общей сумме)
* Для `currency_mismatch` поле `currency` показывает, что ожидалось, а `receivedCurrency` — что было фактически отправлено