Transaction callback

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 transaction might look like this:

{
   "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"
   },
   "fees":{
      "processing":"7.263031",
      "technical":null
   },
   "eur":"200.12",
   "usd":"207.52",
   "senderDetails": {
      "senderIban": "GB29NWBK60161331926819",
      "senderAccountNumber": "31926819",
      "senderSortCode": "601613",
  }
}

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
applicationId	String	The unique application ID in the merchant system
currency	String	The transaction currency of a deposit/withdraw. 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
info.transactionCurrency	String	The transaction currency
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.

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.