Global Card Rail
XGateway offers deposits with the preliminary creation of invoices at a fixed exchange rate. This is the recommended integration method, as it provides merchants with a ready-made UI for accepting deposits in EUR and USD.
Creating an invoice
It is highly recommended to warn customers not to use VPN (including Apple Private Relay).
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.
Please read this page about the difference between base currency and payment currency.
Create and activate invoice (opens the payment method directly):
{
"orderId": "order-test-prod",
"customerId": "test-prod2025",
"baseCurrency": "EUR",
"amount": 100,
"paymentCurrency": "EUR"
}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.
The Checkout page will lead the customer through the deposit flow.
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.
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, XGateway detects the transaction and sends a deposit callback to the merchant. Please visit this page for further information about the callbacks.
In case of Global Card Rail chargebacks are possible. XGateway also relays this information to the merchant using a special callback type.
Callbacks for Withdraw requests will be sent to the same URL. Make sure to properly filter callbacks by type.
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 on Demo environment
One may use the following data to simulate successful deposits on the Demo Environment.
Last updated