Crypto Payments using Checkout#
Please read the invoice currencies page before starting. The invoice creation API uses several parameters that need explanation.
XGateway supports deposits with preliminary creation of invoices with a fixed exchange rate. This is the recommended integration form, which providers merchants with ready-made UI for deposits with crypto assets.
Creating an invoice#
In order to create a Fixed Rate Invoice in the payment processing system, you need to make a POST request to the Invoice API endpoint.
Demo / Prod URLs
For tests use Demo env:
https://api.demo.xgateway.tech/api/v2/invoices
For production:
The XGateway provides one API endpoint, which automatically defines a corresponding payment method based on the input parameters provided by the merchant. Below is an example of a payload that contains the minimum fields set required to create an invoice for a Crypto Payment.
{
"orderId": "test-prod-order",
"customerId": "test-prod-customer",
"baseCurrency": "USD",
"invoiceStrategy": "fixed",
"amount": 10
}
cURL example
curl -X POST https://api.demo.xgateway.tech/api/v2/invoices \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-H "Accept: */*" \
-d '{
"orderId": "test-prod-order",
"customerId": "test-prod-customer",
"baseCurrency": "USD",
"invoiceStrategy": "fixed",
"amount": 10
}'
If you get a bad request response without exact information about the erroneous field, please check the syntax of the request.
The request returns a link to a correspondingly configured Checkout page. This page contains the wallet address for a deposit to be made. The page is used by a customer to finish the deposit.
By default, the payment gateway links the created wallet to a customer forever. The created wallet can be used across all EVM compatible chains.
Remember to authorise the request with your key using x-api-key header.
The default lifetime of an invoice is 15 minutes.
iFrame or redirect#
The URL returned by the invoice creation API can be used in two ways: as a redirect or within an iFrame.
In case of a redirect, the user is sent to a new page, where they complete the payment. This can be done using a new tab too. A redirect is an option with less effort.
When the deposit is done, the user is redirected back to your app: either to the dynamic URL specified in the redirectUrl parameter or to a pre-set static URL.
The invoice URL may also be used in an iFrame. Please check this page for detailed instructions on the iFrame setup.
Processing a callback#
When a customer makes a deposit using a cryptocurrency, XGateway detects the transaction and sends a deposit callback to the merchant. Below is an example of such a callback. For detailed information, please visit the transaction callbacks for deposits and withdrawals page.
Callback example
{
"callbackType":"transaction",
"amount":"200",
"applicationId":null,
"currency":"USDT",
"customerId":"000394",
"hash":"...",
"id":"7e71d132-d80d-4140-8e60-9c89d0bd9eed",
"invoiceId":"184e9933-1526-...-fe567091b5bd",
"network":"tron",
"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"
}
Callbacks for Withdraw requests will be sent to the same URL. Make sure to properly filter callbacks by type.
Limits#
The invoice creation API validates the amount value.
An invoice will not be created if the amount is outside the allowed limits.
Invoice limits
| Currency | Min value | Max value |
|---|---|---|
| BNB | 0.001000000000000000 | None |
| BTC | 0.000082000000000000 | None |
| BSC USDT | 5.000000000000000000 | None |
| ETH | 0.002000000000000000 | None |
| Ethereum USDC | 5.000000000000000000 | None |
| Ethereum USDT | 5.000000000000000000 | None |
| FTN | 2.000000000000000000 | None |
| POL | 12.000000000000000000 | None |
| Polygon USDC | 5.000000000000000000 | None |
| TRX | 25.000000000000000000 | None |
| Tron USDC | 5.000000000000000000 | None |
| Tron USDT | 5.000000000000000000 | None |
Confirming a transaction#
Prefer callbacks over polling; they are signed and retried. For high-risk operations, confirm state via API (see the risks and details on the Callbacks Handling page). API responses are the source of truth.
To confirm the callback is valid, please use the API endpoint.
Testing Crypto Payments on Demo environment#
You can test direct crypto deposits in the Demo Environment.
Testing with transaction simulation#
The Demo Environment provides an API to simulate a deposit. This is the best way to test the integration, because it does not require to make real blockchain transactions.
Testing with real transactions#
An alternative way to test the integration is to deposit native token on a test network. Proceed with the integration up to the point where the customer wallet is generated and returned to you. Make sure that deposits of ETH are enabled for your profile.
Use faucets, like this one, to get some ETH on Sepolia test network.
Send a portion of this ETH to the wallet, assigned to your customer.
Wait for the system to send you a callback about a successful deposit.
More faucets: