Webhook Structure - CryptoCash Documentation

Структура Payload

Кожна подія містить об’єкт data з даними на момент події. Структура payload однакова для всіх типів подій, але значення полів відрізняються залежно від типу транзакції та етапу її життєвого циклу.

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

​Структура Payload

​Пояснення полів сум

​Виведення (Buy)

​Поповнення (Sale)

​Значення статусів

​Логіка валют

​Поля отримання (receivedCurrency, receivedNetwork, receivedAmount)

​Деталі полів за подіями

​Події виведення

​Події поповнення