Transaction callback
Last updated
Last updated
Your customers can now deposit or withdraw funds within our system. Once the transaction is confirmed or failed, we'll send a POST request to your callback URL.
POST https://your-callback-url-here.com/endpoint-to-handle-transactions-here
This is the callback you will receive when a customer deposits or withdraws funds.
| Name | Type | Description |
|---|---|---|
The callback URL is the URL you provide during the sign-up process.
The callback you get after a confirmed or failed transaction might look like this:
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 us 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 our notifications can reach you. We will retry failed requests up to 10 times. If we fail to reach you, 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.
Due to the involvement of amounts in encoding and decoding hash, the amount will be sent as a string to prevent unforeseen transformations.
The XGateway peer-to-peer payments system operates as a distributed payment network that facilitates direct transactions between customers and payment agents. This arrangement boasts exceptionally high success rates and empowers the provision of personalised services in markets where conventional payment methods fall short.
Typically, the payment flow demonstrates remarkable reliability and speed, with the majority of transactions between customers and agents being confirmed and processed within 5 minutes.
Nevertheless, due to the asynchronous nature of the payment flow, certain scenarios may arise, leading to delays in payments or receipt of payments exhibiting characteristics different from those anticipated.
Here are the two primary scenarios that may occur and require handling by the merchant:
XGateway peer-to-peer invoice usually comes with a 30-minute expiration period (occasionally extended by the payment agent by an additional 30 minutes). The transaction is categorised as successful if the customer settles the invoice within this timeframe.
If the customer fails to make the payment before the expiration of the invoice timer, the invoice is labelled as failed.
Occasionally, delays occur in receiving customer payments. These delays might arise because the customer's bank conducts additional (compliance) checks, or the customer might mistakenly send the payment after the expiration time of the invoice has passed, among other potential reasons.
Under these circumstances, the customer has the option to contact XGateway support and initiate a dispute process to make the team investigate the case. This involves providing evidence that the payment was indeed executed and requesting a status change for the invoice in question from failed to successful.
If the dispute is resolved in favour of the customer, the recommended method for processing the payment involves XGateway initiating a new success callback and informing the merchant about a new successful deposit.
In such case, XGateway will send a successful callback to the merchant:
The callback data here is presented only for the demo purpose.
The new callback will be sent with the original order ID.
Since customer deposits are executed asynchronously, it's not possible to regulate the exact amount that the customer will send to XGateway. There's a possibility that the customer might send either a smaller or larger amount than what is specified on the invoice.
In such a scenario, XGateway will proceed to initiate a successful callback to the merchant, using the actual sum that the customer transferred, even if it differs from the invoice amount.
The callback data here is presented only for the demo purpose.
callbackType
"transaction"
The type of callback
amount
String
The transaction amount
applicationId
String
The unique application ID in the merchant system
currency
String
The transaction currency
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 the merchant system
status
String
The transaction status
transactionHash
String
The transaction hash in the blockchain
type
String
The transaction type
info.exchangeRate
String
The exchange rate used for the conversion from fiat currency to crypto cyrrency
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
fee.processing
String
Processing fee in transaction currency
fee.technical
String
Technical fee in transaction currency