Перейти к основному содержанию

​
Fiat Webhooks

Примечание: все числовые значения, суммы и идентификаторы в примерах являются иллюстративными и приведены только для демонстрации.

​
Обзор

Fiat Module использует webhook-и Crypto-Cash, которые отправляются мерчанту после изменения статуса транзакции. Они работают только если на Fiat API key настроен параметр webhookUrl. Если webhookUrl не задан, webhook-и не отправляются.
URL для уведомлений у платёжного провайдера и webhookUrl на Fiat API key — это разные вещи. webhookUrl на Fiat API key — это адрес, на который Crypto-Cash отправляет свои события мерчанту.

​
Ключевые параметры

ПараметрЗначение
Цель webhook Crypto-CashwebhookUrl, настроенный на Fiat API key
HTTP-методPOST
ДоставкаАсинхронная
Формат данныхapplication/json

​
Как работают webhook-и

Пользователь открывает платёжный виджет
↓
Платёжный провайдер обрабатывает платёж
↓
Платёжный провайдер отправляет webhook в Crypto-Cash
↓
Crypto-Cash проверяет подпись провайдера
↓
Crypto-Cash обновляет статус транзакции
↓
Crypto-Cash формирует payment-событие
↓
Если на Fiat API key настроен webhookUrl,
Crypto-Cash отправляет webhook асинхронно

​
Webhook-и Crypto-Cash

Webhook-и Crypto-Cash отправляются после payment-событий. Они работают только если на Fiat API key настроен webhookUrl. При изменении статуса транзакции система формирует payment-событие и асинхронно отправляет webhook на настроенный webhookUrl. Если webhookUrl не настроен, webhook не отправляется. HTTP-формат: 
Method: POST
Content-Type: application/json
Каждый webhook содержит поле signature в теле payload. Мерчант использует Fiat API key, чтобы убедиться, что webhook отправлен Crypto-Cash и не был изменён. Webhook payload и подпись сохраняются для аудита и истории.

​
Типы событий

СобытиеКогда отправляетсяТип
payment::createdТранзакция созданаПромежуточное
payment::waitingСтатус сменился на WaitingПромежуточное
payment::paidСтатус сменился на PaidФинальное
payment::failedСтатус сменился на FailФинальное
payment::canceledСтатус сменился на CanceledФинальное
Промежуточные события (payment::created, payment::waiting) означают, что транзакция в работе и возможны дальнейшие изменения статуса. Финальные события (payment::paid, payment::failed, payment::canceled) означают, что транзакция достигла терминального состояния:
Финальное событиеЗначение
payment::paidКриптовалюта успешно отправлена на адрес кошелька
payment::failedПлатёж не был завершён
payment::canceledПлатёж отменён

​
Что должен проверить мерчант

При получении webhook Crypto-Cash:
  1. Проверить поле signature с помощью Fiat API key (см. раздел «Подпись webhook»).
  2. Прочитать event.event_type, чтобы определить событие.
  3. Прочитать event.data — там полное состояние транзакции.
  4. Обработать событие исходя из того, промежуточное оно или финальное.
Поле id уникально для каждой доставки webhook. Используйте его для дедупликации обработки на своей стороне.

​
Подпись webhook Crypto-Cash

Каждый webhook Crypto-Cash содержит поле signature в теле payload. Подпись формируется по идентификатору и содержимому webhook: 
payload = { id, delivered_at, event }
Мерчант проверяет подпись так: пересобирает тот же payload из полученного webhook, исключая поле signature, и проверяет его с помощью Fiat API key. Способ проверки зависит от типа Fiat API key:
  • ED25519 — проверьте полученное signature, используя publicKey Fiat API.
  • LEGACY — пересоберите ожидаемое значение signature, используя privateKey Fiat API, и сравните его с полученным.
Используйте ту же пару Fiat API key, которая используется для подписанных запросов мерчанта в API. Приватный ключ должен оставаться на стороне мерчанта — не отправляйте его в ответах на webhook, в логах или в обращениях в поддержку.

​
Примеры payload

​
payment::created

{
  "id": "webhook-id",
  "delivered_at": "2026-04-16T10:00:01.000Z",
  "event": {
    "event_type": "payment::created",
    "timestamp": "2026-04-16T10:00:01.000Z",
    "data": {
      "id": "crypto-cash-transaction-id",
      "externalId": "merchant-order-id",
      "status": "New",
      "fiatCurrency": "SGD",
      "fiatAmount": "51",
      "currency": "USDT",
      "network": "TRC20",
      "address": "wallet-address",
      "cryptoAmount": null,
      "exchangeRate": null,
      "paymentMethod": null,
      "hash": null,
      "buyId": null,
      "withdrawId": null,
      "customerId": null,
      "merchantEarning": null,
      "merchantId": "merchant-id",
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:00:00.000Z"
    }
  },
  "signature": "signature"
}

​
payment::waiting

{
  "id": "webhook-id",
  "delivered_at": "2026-04-16T10:00:15.000Z",
  "event": {
    "event_type": "payment::waiting",
    "timestamp": "2026-04-16T10:00:15.000Z",
    "data": {
      "id": "crypto-cash-transaction-id",
      "externalId": "merchant-order-id",
      "status": "Waiting",
      "fiatCurrency": "SGD",
      "fiatAmount": "51",
      "currency": "USDT",
      "network": "TRC20",
      "address": "wallet-address",
      "cryptoAmount": null,
      "exchangeRate": null,
      "paymentMethod": "card",
      "hash": null,
      "buyId": "provider-operation-id",
      "withdrawId": null,
      "customerId": "customer-id",
      "merchantEarning": null,
      "merchantId": "merchant-id",
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:00:10.000Z"
    }
  },
  "signature": "signature"
}

​
payment::paid

{
  "id": "webhook-id",
  "delivered_at": "2026-04-16T10:07:30.000Z",
  "event": {
    "event_type": "payment::paid",
    "timestamp": "2026-04-16T10:07:30.000Z",
    "data": {
      "id": "crypto-cash-transaction-id",
      "externalId": "merchant-order-id",
      "status": "Paid",
      "fiatCurrency": "SGD",
      "fiatAmount": "51",
      "currency": "USDT",
      "network": "TRC20",
      "address": "wallet-address",
      "cryptoAmount": "50.12",
      "exchangeRate": "1.02",
      "paymentMethod": "card",
      "hash": "blockchain-hash",
      "buyId": "provider-operation-id",
      "withdrawId": "provider-withdraw-id",
      "customerId": "customer-id",
      "merchantEarning": "0.9306",
      "merchantId": "merchant-id",
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:07:00.000Z"
    }
  },
  "signature": "signature"
}

​
payment::failed

{
  "id": "webhook-id",
  "delivered_at": "2026-04-16T10:02:05.000Z",
  "event": {
    "event_type": "payment::failed",
    "timestamp": "2026-04-16T10:02:05.000Z",
    "data": {
      "id": "crypto-cash-transaction-id",
      "externalId": "merchant-order-id",
      "status": "Fail",
      "fiatCurrency": "SGD",
      "fiatAmount": "51",
      "currency": "USDT",
      "network": "TRC20",
      "address": "wallet-address",
      "cryptoAmount": null,
      "exchangeRate": null,
      "paymentMethod": "card",
      "hash": null,
      "buyId": "provider-operation-id",
      "withdrawId": null,
      "customerId": "customer-id",
      "merchantEarning": null,
      "merchantId": "merchant-id",
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:02:00.000Z"
    }
  },
  "signature": "signature"
}

​
payment::canceled

{
  "id": "webhook-id",
  "delivered_at": "2026-04-16T10:03:05.000Z",
  "event": {
    "event_type": "payment::canceled",
    "timestamp": "2026-04-16T10:03:05.000Z",
    "data": {
      "id": "crypto-cash-transaction-id",
      "externalId": "merchant-order-id",
      "status": "Canceled",
      "fiatCurrency": "SGD",
      "fiatAmount": "51",
      "currency": "USDT",
      "network": "TRC20",
      "address": "wallet-address",
      "cryptoAmount": null,
      "exchangeRate": null,
      "paymentMethod": "card",
      "hash": null,
      "buyId": "provider-operation-id",
      "withdrawId": null,
      "customerId": "customer-id",
      "merchantEarning": null,
      "merchantId": "merchant-id",
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:03:00.000Z"
    }
  },
  "signature": "signature"
}