SEPA Secure payments using Checkout
Please read this 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.
The XGateway provides one API endpoint, which automatically defines a corresponding payment method based on the input parameters provided by the merchant. Below are examples of a payload to create an invoice for a SEPA Secure deposit in such currencies as EUR or GBP.
The system will skip all XGateway intermediate pages and redirect the customer directly to the payment method, but only if all required data is provided. Integration can be implemented and tested with the mandatory fields alone; however, it is highly recommended to proceed with pre-filled forms, as this can dramatically simplify the flow for the end user and improve conversion. Please don't forget to check the pre-population section and the guide on conversion optimisation down below.
Create an invoice:
{
"orderId": "order-test-prod",
"customerId": "test-prod2025",
"baseCurrency": "EUR",
"amount": 100
}
Create and activate invoice (opens the payment method directly):
{
"orderId": "order-test-prod",
"customerId": "test-prod2025",
"baseCurrency": "EUR",
"amount": 100,
"paymentCurrency": "EUR",
"customerFirstName": "John",
"customerLastName": "Doe",
"customerEmail": "[email protected]",
"customerCountry": "AU"
}
The request returns a link to a correspondingly configured Checkout page.
The Checkout page will lead the customer through a KYC if this is the first deposit.
If the KYC is soft failed (example due to address or DoB mismatch), the Checkout page will allow the customer to go through the KYC again and correct the error.
This Checkout page will eventually provide the customer with a virtual bank account number (IBAN) that must be used as an address for deposits.
The created IBAN remains active forever, considering the customer is active. If the IBAN was not used at all or was used long time ago (3 to 6 months ago) - XGateway team may deactivate the IBAN.
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 may be used to redirect a user to a new page, where they finish the payment. This can be done using a new tab too. A redirect is an option with less efforts.
When the deposit is done, a user is redirected back to your app to the URLspecified in the redirectUrl parameter.
The invoice URL may also be used in an iFrame. Please check this page for detailed instructions on the iFrame setup.
Limits
The invoice creation API validates the amount value.
An invoice will not be created, if the amount exceeds the limits.
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 this page.
{
"callbackType":"transaction",
"amount":"200",
"applicationId":null,
"currency":"EUR",
"customerId":"000394",
"hash":"...",
"id":"7e71d132-d80d-4140-8e60-9c89d0bd9eed",
"invoiceId":"184e9933-1526-...-fe567091b5bd",
"network":"tron",
"orderId":null,
"status":"confirmed",
"transactionHash":null,
"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"
}
Confirming a transaction
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.
To confirm the callback is valid, please use the API endpoint.
Testing SEPA Secure deposits on Demo environment
You can test direct crypto deposits in the demo environment.
Test data
Improving the conversion rate of bank transfers
Last updated