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",     // Фактическая сумма пополнения (НЕ кумулятивная)

  // Блокчейн
  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)

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

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

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