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


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