Webhooks

Description

You can configure notifications to be sent to any system that accepts incoming webhooks over the HTTP/HTTPS protocol. To do this, you must specify the Webhook URL when creating an order, to which notifications about the order will be sent.

If you do not respond with the status 200, then we will send 6 request: with 10 seconds interval, then 5 with 30 minutes interval, then 4 with 2 hour interval, then 3 with 12 hour interval.

If Webhook URL was provided within API method, it will have following additional headers:

• x-api-public-key - public key, which was used in origin request with provided Webhook URL

• x-api-signature - signature that was made with same algorithm from "Creating request signature" section

Server IP addresses: 94.242.240.228, 188.42.242.132

Order status webhook

Webhook URL example

"successWebhook": "https://example.com/success-webhook-url"

"errorWebhook": "https://example.com/error-webhook-url"

Attention

Please note that the statuses processed, expired, partial, overpaid ** are not final**

When processing a webhook, you should separately process the array of received transactions to correctly process the payment amount

Server response example

{
  id: 'a020272e-b97a-4ed8-ab74-696426913627',
  advancedBalanceId: '316a59ea-be39-4eaa-9392-6fda708f24d8',
  currency: 'USDT',
  network: 'tron',
  status: 'processed',
  order: '#1234567',
  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"
}

Invoice status webhook

Server response example

{
  "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"
}

Possible values for status:

• CREATED - created

• INIT - the user proceeded to payment

• PENDING - waiting for the full amount or waiting for transaction confirmations in the blockchain

• PROCESSED - completed

• PARTIAL - partial payment

• REJECTED - the invoice was rejected, contact support for clarification

• ERROR - error during creation or processing

• EXPIRED - the invoice has expired

Withdrawal status webhook

When the withdrawal is completed, a webhook with the status of this payment is sent to the webhookUrl specified when creating the withdrawal.

• addressId - personal address to which the deposit came

• userId - the ID (internal) of the user who owns the personal address

• clientId - the ID (external, in your service) of the user who owns the personal address

{
  "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"
}

Possible values for status:

• error - error occured during withdrawal processing

• processed - successful withdrawal

Billing link status webhook

When the status of a billing link changes, a webhook is sent to the address specified when the link was created.

{
  "id": "9085a4bd-0099-4f8a-9dc5-9a717ab1d93b",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "clientId": "qw12",
  "clientName": null,
  "clientEmail": "[e-mail]",
  "webhookUrl": "https://site.com/webhook",
  "returnUrl": null,
  "address": "0xf038f6b",
  "currency": "USDC",
  "network": "ethereum",
  "status": "SUCCESS",
  "createdAt": "2023-03-02T10:10:21.064Z",
  "updatedAt": "2023-03-02T10:13:25.509Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

Subscription status webhook

When the subscription status changes or when a payment is made, a webhook is sent to the address specified when the subscription was created.

{
  "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"
}

When the subscription status changes, a webhook with the subscription object is sent. In this case, paymentEvent is filled only if the webhook event is related to making a payment.

Possible values for status:

• ACTIVE - subscription active/renewed

• ERROR - subscription payment failed

• DECLINE - unable to complete the payment (e.g. lack of money)

• CANCEL - subscription canceled

The status comment can be contained in the message field

After the payment is made, a webhook is sent with the object of this payment in the paymentEvent field. Possible values of the paymentEvent.status field:

• PROCESSED - successful payment

• ERROR - unsuccessful payment

Payment status webhook with free amount

When a payment is completed, a webhook with the status of this payment (the same object as in the paymentEvent field of the webhook with the subscription status) is sent to the address specified during the payment request.

{
  "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"
}

Possible values for status:

• PROCESSED - successful payment

• ERROR - unsuccessful payment

Crosschain bridge operation status webhook

When the operation status changes, a webhook is sent to the address specified when the operation was created

{
  "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"
}

Available statuses

Status	Description
CREATED	Request registered
PENDING	Being processed
ERROR	Error during execution
REJECTED	Request denied
PROCESSED	Success

Crosschain swap status webhook

When the swap status changes, a webhook is sent to the address specified when the swap was created

{
        "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"
}

Available statuses

Status	Description
CREATED	Request registered
PENDING	Being processed
ERROR	Error during execution
REJECTED	Request denied
PROCESSED	Success

Webhook for deposit on personal address

When the payment is completed, a webhook with the status of this payment is sent to the URL depositWebhookUrl specified when creating the user.

• addressId - personal address to which the deposit came

• userId - ID of the user who owns the personal address

Example

{
  "id": "2fa68ddf-2479-47cb-9e66-ae91139c3063",
  "addressId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "userId": "6196a1f2-b6b5-40a5-a672-f1ffd70fdd7d",
  "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"
}

Possible values of status:

• PENDING - deposit is in processing

• PROCESSED - successful deposit

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

Пример

{
    "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:

Status	Description
PENDING	In processing
WITHDRAWING	Waiting to be sent to the destination address
PROCESSED	Successfully
REJECTED	Rejected
ERROR	Processing error