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: 188.42.242.220, 188.42.242.228
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
Copy {
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
Copy {
"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:
INIT - the user proceeded to payment
PENDING - waiting for the full amount or waiting for transaction confirmations in the blockchain
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
Copy {
"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.
Copy {
"id" : "9085a4bd-0099-4f8a-9dc5-9a717ab1d93b" ,
"merchantId" : "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9" ,
"clientId" : "qw12" ,
"clientName" : null ,
"clientEmail" : "site@domain.com" ,
"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.
Copy {
"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.
Copy {
"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
Copy {
"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
Crosschain swap status webhook
When the swap status changes, a webhook is sent to the address specified when the swap was created
Copy {
"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
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
Copy {
"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 статуса авто-обмена
Пример
Copy {
"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: