Transaction callback for Deposit and Withdraw

Your customers can now deposit funds within our system. Once a transaction is confirmed, failed or manually rejected, the XGateway system sends a POST request to your callback URL.

Due to security risks, merchants must use our API endpoint to request transaction details. XGateway is not liable for issues caused by relying only on callback data.

The callback you get after a confirmed or failed Deposit transaction might look like this:

Deposit callback

{
   "callbackType":"transaction",
   "amount":"200",
   "applicationId":null,
   "currency":"EUR",
   "customerId":"000394",
   "hash":"...",
   "id":"7e71d132-d80d-4140-8e60-9c89d0bd9eed",
   "invoiceId":"184e9933-1526-...-fe567091b5bd",
   "network":null,
   "orderId":null,
   "status":"confirmed",
   "transactionHash":"0x58f6",
   "type":"deposit",
   "info":{
      "exchangeRate":"1.03759",
      "referenceAmount":"207.52",
      "referenceCurrency":"USD",
      "referenceExchangeRate":"1.000065",
      "transactionAmount":"207.51518",
      "transactionCurrency":"tUSDT",
      "invoiceBaseAmount":"200",
      "invoiceBaseCurrency":"EUR",
      "transactionAmountBaseCurrency":"199.984"
   },
   "additionalParams": {
    "utr": "111111111111"
   },
   "fees":{
      "processing":"7.263031",
      "technical":null
   },
   "eur":"200.12",
   "usd":"207.52",
   "senderDetails": {
      "senderIban": "GB29NWBK60161331926819",
      "senderAccountNumber": "31926819",
      "senderSortCode": "601613",
   },
   "additionalParams": {
     "utr": "111111111111"
   }
}

The callback you get after a confirmed or failed Withdraw transaction might look like this:

Withdraw callback

{
  "callbackType": "transaction",
  "senderDetails": null,
  "amount": "1.71",
  "applicationId": null,
  "currency": "EUR",
  "customerId": "sepa-secure-wilson",
  "hash": "FA5h8Ff4OnrbLXAzumKUt9Erpwq1UptifSpWtYkGYVsaKGeYkkv43BT7bfkGHc1aMs7T2fjN/JybzwwMAjgg6g==",
  "id": "ffb19985-da0s0-4144-beba-d4768fc6daec",
  "invoiceId": "62bdfd2dd-97a7-4e85-9320-2779ee9b2ece",
  "network": null,
  "orderId": "order_test_prod",
  "status": "confirmed",
  "transactionHash": null,
  "type": "withdrawal",
  "createdAt": "2025-07-18T07:45:18.732Z",
  "updatedAt": "2025-07-18T07:46:38.611Z",
  "info": {
    "exchangeRate": "1.162371703223256733",
    "referenceAmount": "2",
    "referenceCurrency": "USD",
    "referenceExchangeRate": "1.000065",
    "transactionAmount": "2",
    "transactionCurrency": "tUSDT",
    "invoiceBaseAmount":"1.71",
    "invoiceBaseCurrency":"EUR",
    "transactionAmountBaseCurrency":"1.927"
  },
  "additionalParams": {
    "utr": "111111111111"
  },
  "fees": {
    "processing": "0.08",
    "technical": null
  },
  "eur": "1.72",
  "usd": "2"
}

The callback data here is presented only for the demo purpose.

You may then handle this information as necessary. You don't need to send anything back other than a success status so that we know the callback has been received and handled on your side.

It is always best to ensure that your callback endpoint is up and running so that the notifications can reach you. XGateway will retry failed requests up to 10 times.

All notifications (delivered or not) will be available on your dashboard. You can also see the error messages for failed notifications and investigate the issue on your side.

Crypto transactions are permanently recorded on the public blockchain as well as stored in our database. This data may be used for cross check and debugging.

Due to the involvement of amounts in encoding and decoding hash, the amount will be sent as a string to prevent unforeseen transformations.

Callback fields explanation

Below is a breakdown of some of the callback fields.

Callback body breakdown

Name	Type	Description
callbackType	"transaction"	The type of a callback
amount	String	The transaction amount how it was sent by the customer.
applicationId	String	The unique application ID in the merchant system
currency	String	The currency sent by the customer. A full list of supported currencies is here.
customerId	String	The unique customer ID in the merchant system
hash	String	The base64-encoded hash is generated using the sha512 algorithm and includes the transaction ID, customer ID, amount, currency, and secret key. The string that will be hashed: {transaction ID}.{customer ID}.{amount}.{currency}.{secretKey}.
id	String	The unique transaction ID in the XGateway system
invoiceId	String	The unique invoice ID in the XGateway system
network	String	The blockchain network the transaction was made in
orderId	String	The unique order ID in the merchant system
status	String	The transaction status
transactionHash	String	The transaction hash in a blockchain
type	String	The transaction type
info.exchangeRate	String	The exchange rate used for the conversion from fiat currency to crypto currency, if applicable
info.referenceAmount	String	The transaction amount in the reference currency set during the sign-up process
info.referenceCurrency	String	The reference currency set during the sign-up process
info.referenceExchangeRate	String	The exchange rate used for the conversion from transaction currency to the reference currency
info.transactionAmount	String	The transaction amount received by the merchant after swaps applied.
info.transactionCurrency	String	The transaction currency received by the merchant.
info.invoiceBaseAmount	String	The amount how it sent in invoice
info.invoiceBaseCurrency	String	The currency how it sent in invoice
info.transactionAmountBaseCurrency	String	The actual transaction amount converted into currency of the invoice
fees.processing	String	Processing fee in transaction currency
fees.technical	String	Technical fee in transaction currency
senderDetails.senderIban	String	The sender IBAN, used to initiate the deposit. The entire block is sent only for Fiat to Crypto deposits.
additionalParams.utr	String	UTR for UPI payments

Here is an example of how the different currencies work. Let's say a merchant operates in USD (reference currency). A customer sends 10 EUR through SEPA Secure with a conversion to USDT on Polygon. In this case the callback will contain:

1. Amount and currency field will contain 10 and EUR.

2. Reference currency USD and amount of the transaction as 10 EUR converted to USD.

3. info.transactionAmount and info.transactionCurrency will contain the amount in pUSDT after swap to pUSDT.

Transaction Status

Below are the statuses (not an exhaustive list) of transactions supported in the system. Note that callbacks are sent for only confirmed and failed transaction statuses. Other statuses are listed for informational purpose. They exist in the system and displayed in Merchant Back Office.

Transaction Statuses

Status	Description
confirmed	The transaction has been successfully processed
created	The transaction has been initiated but is awaiting further processing
failed	The transaction has been failed
processing	The transaction is currently being processed
misdirected	The transaction has been processed but cannot be linked to an existing invoice.
on_hold_review	The transaction is under review for additional checks to prevent potential risks.
manually_approved	The transaction has been manually reviewed and is awaiting further processing.
manually_rejected	The transaction has been manually rejected due to identified vulnerabilities.