How to process the callback
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.
Sends the transaction details to you
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.
Request Body
| Name | Type | Description |
|---|---|---|
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: |
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 |
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.
Fiat Deposits with Instant Conversion to Crypto
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:
Disputes of Failed Deposits
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.
Customer Deposit Amount is Smaller or Larger
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.
Last updated