Получение веб-хуков

Для успешной обработки вебхуков всегда необходимо возвращать следующий ответ, иначе сервис будет повторять попытки отправки (до 30 раз):

{
  "success": true
}

1. Вебхук: Платеж получен

Вы можете настроить адреса для отправки уведомлений о зачислении платежей на странице настройки проекта. Этот вебхук отправляется, когда платеж подтвержден в сети блокчейн и зачислен.

Пример вебхука о зачисленнии:

{
  "amount": "2.395", - Значение платежа в USD
  "created_at": "2025-03-17T12:57:52.449795Z", - Время создания платежа
  "paid_at": "2025-03-17T12:57:19Z",- Время оплаты платежа
  "status": "completed", - Статус платежа
  "transactions": {
    "amount": "0.02552778", - Значение платежа в криптовалюте
    "amount_usd": "2.395", - Значение платежа в USD
    "bc_uniq_key": "0", - Порядковый номер в транзакции, особенно актуально в btc-like сетях bc_uniq_key + tx_hash дает уникальность платежа
    "blockchain": "litecoin", - Наименование блокчейна
    "created_at": "2025-03-17T12:57:52.449795Z", - Время создания платежа
    "currency": "LTC", - Значение криптовалюты
    "currency_id": "LTC.Litecoin", - Идентификатор криптовалюты
    "tx_hash": "2be41b0cad76bc5699c3da5d5a1d390f9fb4038e5bfe49aec3b675f9dd4515fd", - Хеш транзакции
    "tx_id": "4bbc91fd-a950-4fd0-83f3-9f1c09a6b54f" - Идентификатор транзакции в мерчанте
  },
  "type": "PaymentReceived",  - Тип вебхука
  "wallet": {
    "id": "9a07b545-f99e-4f51-bf37-a84fcbe4df4d", - Внутренний идентификатор пользователя
    "store_external_id": "1" - Внешний идентификатор пользователя
  }
}

2. Вебхук: Платеж в Mempool (Ожидает подтверждения)

Этот вебхук отправляется, когда платеж поступил в Mempool, но еще не получил необходимого количества подтверждений в сети. Зачисление будет доступно только после его подтверждения (после получения вебхука типа PaymentReceived).

Обратите внимание: В этом типе вебхука все поля имеют префикс unconfirmed_.

Пример вебхука: Платеж в Mempool:

{
  "unconfirmed_amount":"1000000000000", - Значение платежа в USD (неподтвержденное)
  "unconfirmed_created_at":"2025-10-06T12:39:39.457399475", - Время создания платежа (неподтвержденное)
  "unconfirmed_paid_at":"2025-10-06T12:39:39.457399475", - Время оплаты платежа (неподтвержденное)
  "unconfirmed_status":"completed", - Статус платежа (неподтвержденный)
  "unconfirmed_transactions":{
    "unconfirmed_amount":"1000000000000", - Значение платежа в криптовалюте (неподтвержденное)
    "unconfirmed_amount_usd":"1000000000000", - Значение платежа в USD (неподтвержденное)
    "unconfirmed_bc_uniq_key":"bc_uniq_key_example", - Порядковый номер в транзакции (для идемпотентности)
    "unconfirmed_blockchain":"bitcoin", - Наименование блокчейна
    "unconfirmed_created_at":"2025-10-06T12:39:39.457399475", - Время создания платежа (неподтвержденное)
    "unconfirmed_currency":"BTC", - Значение криптовалюты
    "unconfirmed_currency_id":"BTC.Bitcoin", - Идентификатор криптовалюты
    "unconfirmed_tx_hash":"tx_hash_example", - Хеш транзакции (для идемпотентности)
    "unconfirmed_tx_id":"165d8dd3-0d9b-4144-979e-23f593f48cdf" - Идентификатор транзакции в мерчанте
  },
  "unconfirmed_type":"PaymentNotConfirmed", Тип вебхука: - Платеж ожидает подтверждения
  "unconfirmed_wallet":{
    "unconfirmed_id":"5f185a18-a8d5-469d-a853-7fbcb048635b", - Внутренний идентификатор пользователя
    "unconfirmed_store_external_id":"store_external_example" - Внешний идентификатор пользователя
  }
}

3. Вебхук: Вывод с процессингового кошелька

Этот вебхук уведомляет вас о том, что средства, которые вы отправляли своим пользователям через сервис, были успешно зачислены на кошелек получателя.

Пример вебхука: Вывод с процессингового кошелька:

{
  "amount": "100", - Сумма вывода в USD
  "created_at": "2025-09-23T12:27:08.166963191", - Время создания операции вывода
  "paid_at": "2025-09-23T12:27:08.166963191", - Время фактического осуществления вывода
  "status": "completed", - Статус операции вывода
  "transactions": {
    "amount": "100", - Сумма вывода в криптовалюте
    "amount_usd": "100", - Сумма вывода в USD
    "bc_uniq_key": "bc_uniq_key_example", - Уникальный идентификатор события (для проверки идемпотентности)
    "blockchain": "bitcoin", - Наименование блокчейна
    "created_at": "2025-09-23T12:27:08.166963191", - Время создания транзакции
    "currency": "BTC", - Значение криптовалюты
    "currency_id": "BTC.Bitcoin", - Идентификатор криптовалюты
    "tx_hash": "tx_hash_example", - Хеш транзакции в блокчейне (для проверки идемпотентности)
    "tx_id": "408a97b1-d1e3-423e-9c8b-5ae4cd902f7f" - Идентификатор транзакции в мерчанте
  },
  "type": "WithdrawalFromProcessingReceived", - Тип вебхука: Уведомление о завершении вывода
  "wallet": {
    "id": "8a279ec7-31fb-41f2-a2a5-3d066b77bd8a", - Внутренний идентификатор кошелька отправителя (процессингового кошелька)
    "store_external_id": "store_external_example" - Внешний идентификатор пользователя/магазина
  }
}

Проверка идемпотентности при получении вебхука

При обработке входящих вебхуков критически важно гарантировать идемпотентность, чтобы избежать повторной обработки одного и того же события (например, двойного зачисления средств). Для этого используйте следующие два поля из объекта transactions (или unconfirmed_transactions):

tx_hash — Хеш транзакции (хеш-сумма содержимого запроса или события). bc_uniq_key — Уникальный идентификатор события в рамках транзакции, предоставляемый отправителем вебхука.

Алгоритм проверки:

1. Перед обработкой вебхука необходимо проверить, что сочетание hash + uniq_key еще не было обработано ранее и не зафиксировано в вашей системе.
2. Если такое событие уже зафиксировано, оно должно быть проигнорировано как дубликат.
3. Если событие новое, его следует обработать и зафиксировать в вашей базе данных.