# Webhooks

## Описание

Вы можете настроить отправку уведомлений в любую систему, которая принимает входящие вебхуки по протоколу HTTP/HTTPS. Для этого необходимо указать Webhook URL **при создании ордера**, на который будут отправляться уведомления об ордере.

Если Вы не ответите статусом 200, то мы продолжим слать запрос: первые 6 с интервалом 10 секунд, следующие 5 с интервалом 30 минут, потом 4 с интервалом 2 часа и последние 3 с интервалом 12 часов.

Если Webhook URL был указан через API, то в запросе будут присланы следующие дополнительные заголовки:

* `x-api-public-key` - публичный ключ, с помощью которого был выполнен запрос с указанием Webhook URL
* `x-api-signature` - подись, созданная по принципу, описанному в п. "Формирование подписи запроса"

**IP-адреса сервера:** 92.62.137.125

## Webhook статуса ордера

#### Webhook URL пример

"successWebhook": "[https://example.com/success-webhook-url"](https://example.com/success-webhook-url)

"errorWebhook": "[https://example.com/error-webhook-url"](https://example.com/error-webhook-url)

> #### Внимание
>
> Обратите внимание, что статусы `processed`, `expired`, `partial`, `overpaid` **не являются конечными**
>
> При обработке вебхука вам стоит отдельно обрабатывать массив полученных транзакций для корректной обработки суммы платежа

#### Пример ответа сервера

```json
{
  id: 'a020272e-b97a-4ed8-ab74-696426913627',
  advancedBalanceId: '316a59ea-be39-4eaa-9392-6fda708f24d8',
  currency: 'USDT',
  network: 'tron',
  status: 'processed',
  order: '#12345',
  description: null,
  address: 'TCpyHjEF7weWw2284sy7yYX5KUo9GTs6R6',
  tag: null,
  amount: '0.2',
  received: '0.20000000',
  transactions: [
    {
      id: '9812eb5f-b8b7-4e33-90e7-c8139d7cf46d',
      status: 'processed',
      currency: 'USDT',
      network: 'tron',
      amount: '0.1',
      tx: '86464a34fbecb77d67bda0604a883a796ddc3ccd54854637cd6fa0b95ccf1f3f',
      confirmations: '10',
      sender: 'TUdtD3oXvX37NM5mH5W561p6GSeDHeUDTD',
      priceUSD: '1',
      amountUSD: '0.1'
    },
    {
      id: '87fa47d7-9d83-42d0-9dc9-aba52b9869a3',
      status: 'processed',
      currency: 'USDT',
      network: 'tron',
      amount: '0.1',
      tx: 'fbc94452bc9f2a097a73ade40eada72125224f3a4c39965941a431d641493399',
      confirmations: '10',
      sender: 'TUdtD3oXvX37NM5mH5W561p6GSeDHeUDTD',
      priceUSD: '1',
      amountUSD: '0.1'
    }
  ],
  link: 'https://payment.domain/a020272e-b97a-4ed8-ab74-696426913627',
  successWebhook: 'https://merchant.domain/success',
  errorWebhook: 'https://merchant.domain/error',
  returnUrl: null,
  expiresAt: '2022-07-05T15:40:29.837Z',
  createdAt: '2022-07-05T13:39:26.006Z',
  updatedAt: '2022-07-05T13:42:00.588Z',
  webhookId: "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

## Webhook статуса счета

#### Пример ответа сервера

```json
{
  "id": "fd1dbab8-06c2-4e0e-88fb-32f5e97cc0e2",
  "advancedBalanceId": "316a59ea-be39-4eaa-9392-6fda708f24d8",
  "externalId": "external-merchant-id-1234",
  "orderId": "87fa47d7-9d83-42d0-9dc9-aba52b9869a3",
  "orderLink": "https://payment.domain/87fa47d7-9d83-42d0-9dc9-aba52b9869a3",
  "invoiceLink": "https://invoices.domain/fd1dbab8-06c2-4e0e-88fb-32f5e97cc0e2",
  "status": "PROCESSED",
  "order": "Payment #1234",
  "description": "Payment for ...",
  "currency": "USD",
  "amount": "100",
  "receivedNetwork": "ethereum",
  "receivedCurrency": "USDT",
  "receivedAmount": "101.12",
  "receivedAmountInInvoiceCurrency": "100.92",
  "rate": "0.998",
  "includeFee": true,
  "additionalFees": ["SEPA_WITHDRAWAL"],
  "insurancePercent": "1",
  "slippagePercent": "2.5",
  "transactions": [
    {
      "id": "9812eb5f-b8b7-4e33-90e7-c8139d7cf46d",
      "status": "processed",
      "currency": "USDT",
      "network": "tron",
      "amount": "101.12",
      "tx": "86464a34fbecb77d67bda0604a883a796ddc3ccd54854637cd6fa0b95ccf1f3f",
      "confirmations": "10",
      "sender": "TUdtD3oXvX37NM5mH5W561p6GSeDHeUDTD",
      "priceUSD": "1",
      "amountUSD": "100"
    }
  ],
  "webhookUrl": "https://merchant.domain/webhooks/invoice",
  "returnUrl": "https://merchant.domain/",
  "expiresAt": "2023-09-04T09:00:00.960Z",
  "createdAt": "2023-09-04T06:39:01.960Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}
```

Возможные значения `status`:

* `CREATED` - создан
* `INIT` - пользователь перешел к оплате
* `PENDING` - ожидаение полной суммы или ожидание подтверждений транзакции в блокчейне
* `PROCESSED` - исполнен
* `PARTIAL` - частичная оплата
* `REJECTED` - инвойс отклонен, свяжитесь с поддержкой для уточнения
* `ERROR` - ошибка в процессе создания или обработки
* `EXPIRED` - скрок действия инвойса истек

## Webhook статуса вывода

При завершения вывода присылается вебхук со статусом этого платежа на URL адрес `webhookUrl`, указанный при создании вывода.

* `addressId` - персональный адрес, на который пришел депозит
* `userId` - идентификатор пользователя, владеющего персональным адресом

#### Пример

```json
{
  "id": "fd1dbab8-06c2-4e0e-88fb-32f5e97cc0e2",
  "addressId": "a3018d42-aa59-42f3-a0f9-6d47e461d344",
  "amount": "0.32",
  "currency": "USDT",
  "network": "tron",
  "status": "processed",
  "tx": "46f4c1bafd9925de3d61d8a86d83851e73e",
  "createdAt": "2023-03-21T13:50:48.603Z",
  "updatedAt": "2023-03-21T13:51:14.018Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Возможные значения `status`:

* `ERROR` - во время вывода произошла ошибка
* `PROCESSED` - успешный вывод

## Webhook статуса платежной связки

При изменении статуса платежной связки высылается вебхук на адрес, указанный при создании этой связки.

```json
{
  "id": "e457d90c-2321-4f9c-9f71-7a16fecc9b66",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "clientId": "199933300",
  "network": "bsc",
  "currency": "USDT",
  "address": "0x1d9e9703",
  "status": "SUCCESS",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

## Webhook статуса подписки

При изменении статуса подписки или при проведения платежа высылается вебхук на адрес, указанный при создании подписки.

#### Пример

```json
{
  "id": "d5743dea-5a78-4096-ae07-95b1f10bc5dd",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "billingLinkId": "e7e7a111-2d24-4aa3-afae-540f313c738b",
  "title": "Flixnet/monthly",
  "description": "Flixnet monthly subscription / HD quality",
  "currency": "USDT",
  "amount": "2.0000000",
  "spendInterval": 120,
  "message": null,
  "webhookUrl": "https://site.com/webhook",
  "status": "ACTIVE",
  "createdAt": "2023-02-27T11:50:53.710Z",
  "updatedAt": "2023-03-01T19:29:04.090Z",
  "paymentEvent": {
    "id": "9c06e989-9d19-461b-bd94-e94032012407",
    "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
    "billingLinkId": "e7e7a111-2d24-4aa3-afae-540f313c738b",
    "amount": "2",
    "status": "PROCESSED",
    "tx": "0xdabd91e979122bb78d0a5cf1e5174dff3e10b906a31adbfd625ff80cca14e8c2",
    "createdAt": "2023-03-01T13:11:57.662Z",
    "updatedAt": "2023-03-01T13:14:32.868Z"
  },
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

При изменении статуса подписки высылается вебхук с объектом подписки. При этом `paymentEvent` заполняется только если событие вебхука связано с проведением платежа.

Возможные значения `status`:

* `ACTIVE` - подписка активна/возобновлена
* `ERROR` - неуспешный платеж по подписке
* `DECLINE` - невозможно выполнить платеж (напр. нехватка денег)
* `CANCEL` - подписка отменена

Комментарий к статусу может содержаться в поле `message`

После проведения платежа высылается вебхук с объектом этого платежа в поле `paymentEvent`. Возможные значения поля `paymentEvent.status`:

* `PROCESSED` - успешный платеж
* `ERROR` - неуспешный платеж

## Webhook статуса платежа со свободной суммой

При завершения платежа присылается вебхук со статусом этого платежа (тот же объект, что и в поле `paymentEvent` вебхука со статусом подписки) на адрес, указанный при запросе на платеж.

#### Пример

```json
{
  "id": "2fa68ddf-2479-47cb-9e66-ae91139c3063",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "billingLinkId": "6196a1f2-b6b5-40a5-a672-f1ffd70fdd7d",
  "amount": "0.005",
  "status": "PROCESSED",
  "tx": "0x5b9b3b55b366266025e",
  "createdAt": "2023-03-02T06:58:00.365Z",
  "updatedAt": "2023-03-02T07:01:50.693Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Возможные значения `status`:

* `PROCESSED` - успешный платеж
* `ERROR` - неуспешный платеж

## Webhook статуса операции кроссчейн моста

При изменении статуса операции присылается вебхук на адрес, указанный при создании операции

```json
{
  "id": "816a19eb-be39-4eaa-9392-6fda708f24d8",
  "clientId": "...",
  "advancedBalanceId": "316a59ea-be39-4eaa-9392-6fda708f24d8",
  "currency": "USDT",
  "networkFrom": "bsc",
  "networkTo": "tron",
  "status": "PENDING",
  "rejectMessage": null,
  "addressFromId": "fa475cfa-15e8-c31d-7469-5f1168052cd6",
  "addressToId": "607976c9-0270-59a3-a528-0d92489c3fc8",
  "amount": "10000",
  "amountUSD": "10000",
  "blockchainFee": "1.80",
  "blockchainFeeUSD": "1.80",
  "serviceFeeUSD": "1.50",
  "webhookUrl": "https://my-show.com/...",
  "createdAt": "2022-02-02T06:07:34.067Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Доступные статусы

| **Статус** | **Описание**                 |
| ---------- | ---------------------------- |
| CREATED    | Запрос зарегистрирован       |
| PENDING    | Обрабатывается               |
| ERROR      | Ошибка в процессе исполнения |
| REJECTED   | Запрос отклонен              |
| PROCESSED  | Успех                        |

## Webhook статуса кроссчейн обмена

При изменении статуса обмена присылается вебхук на адрес, указанный при создании обмена

```json
{
        "id": "816a19eb-be39-4eaa-9392-6fda708f24d8",
        "clientId": "...",
        "advancedBalanceId": "316a59ea-be39-4eaa-9392-6fda708f24d8",
        "currencyFrom": "TRX",
        "currencyTo": "USDT",
        "networkFrom": "tron",
        "networkTo": "bsc",
        "status": "PENDING",
        "rejectMessage": null,
        "addressFromId": "fa475cfa-15e8-c31d-7469-5f1168052cd6",
        "addressToId": "607976c9-0270-59a3-a528-0d92489c3fc8",
        "amountFrom": "100000",
        "amountTo": "10000",
        "price": "0.1",
        "serviceBlockchainFeeSource": "ADDRESS",
        "serviceBlockchainFee": "1.80",
        "serviceBlockchainFeeUSD": "1.80",
        "providerBlockchainFeeSource": "AMOUNT",
        "providerBlockchainFee": "1.80",
        "providerBlockchainFeeUSD": "1.80",
        "serviceFeeSource": "ADVANCE",
        "serviceFee": "1.80",
        "serviceFeeUSD": "1.80",
        "webhookUrl": "https://my-show.com/...",
        "createdAt": "2022-02-02T06:07:34.067Z",
        "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Доступные статусы

| **Статус** | **Описание**                 |
| ---------- | ---------------------------- |
| CREATED    | Запрос зарегистрирован       |
| PENDING    | Обрабатывается               |
| ERROR      | Ошибка в процессе исполнения |
| REJECTED   | Запрос отклонен              |
| PROCESSED  | Успех                        |

## Webhook статуса депозита на персональный адрес

При завершения платежа присылается вебхук со статусом этого платежа на URL адрес `depositWebhookUrl`, указанный при создании пользователя.

* `addressId` - персональный адрес, на который пришел депозит
* `userId` - идентификатор пользователя (внутренний), владеющего персональным адресом
* `clientId` - идентификатор пользователя (внешний, в вашей системе), владеющего персональным адресом

#### Пример

```json
{
  "id": "2fa68ddf-2479-47cb-9e66-ae91139c3063",
  "addressId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "userId": "6196a1f2-b6b5-40a5-a672-f1ffd70fdd7d",
  "clientId": "133357",
  "amount": "0.005",
  "currency": "USDT",
  "network": "bsc",
  "addressFrom": ["0x....", "0x...."],
  "addressTo": "0x....",
  "status": "PROCESSED",
  "confirmations": 10,
  "tx": "0x5b9b3b55b366266025e",
  "risks": {"level": "yellow", "categories": [{ "level": "yellow", "usdAmount": 41159.8, "category": "stolen funds", "service": "Reported as stolen funds bc1qlf4vel", "exposure": "DIRECT" }],
  "createdAt": "2023-03-02T06:58:00.365Z",
  "updatedAt": "2023-03-02T07:01:50.693Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Возможные значения `status`:

* `PENDING` - платеж в обработке
* `PROCESSED` - успешный платеж

## Webhook статуса авто-обмена

#### Пример

```json
{
    "id":"25e2d6ab-44a2-4a7f-9898-a1fc8b27ee19",
    "organizationId":"1f07eb01-5fd8-4e05-89b5-bebcd1d1fc39",
    "userId":null,
    "status":"PROCESSED",
    "currencyFrom":"USDT",
    "currencyTo":"BTC",
    "networkFrom":"tron",
    "networkTo":"bitcoin",
    "addressFromId":"5cb5fefa-7e08-453c-8910-3dc268b16e52",
    "addressFrom":"TF4pfwhPsKzHB1bEV6kGt5T3jejLANW2T3",
    "addressTo":"bc1q9zqj930c0ehss7rsg9sg3nhcccys068c5s3max",
    "amountFrom":"31.56426000",
    "amountFromUSD":"31.56",
    "amountTo":"0.00044955",
    "amountToUSD":"31.59",
    "amountToReceive":"0.00020955",
    "rate":"70213.01301301",
    "blockchainFeeFrom":"2.64000000",
    "blockchainFeeFromUSD":"2.64",
    "blockchainFeeTo":"0.00024000",
    "blockchainFeeToUSD":"16.87",
    "serviceFee":"1.5",
    "webhookUrl":"https://...",
    "createdAt":"2024-03-27T12:12:31.688Z",
    "updatedAt":"2024-03-27T12:19:33.768Z",
    "webhookId":"2636d60c-a3f5-4938-bbd6-ca15d365279a"
}

```

Возможные значения `status`:

| Статус        | Описание                            |
| ------------- | ----------------------------------- |
| `PENDING`     | В обработке                         |
| `WITHDRAWING` | Ожидание отправки на конечный адрес |
| `PROCESSED`   | Успешно                             |
| `REJECTED`    | Отклонен                            |
| `ERROR`       | Ошибка при обработке                |