> ## 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",     // Сума окремого депозиту в receivedCurrency (НЕ кумулятивна)

  // Блокчейн
  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` — що було фактично надіслано