Global Cards Processing

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. Find examples of request bodies below. Use Demo environment for tests.

URLs

For tests use Demo env:

https://api.demo.xgateway.tech/api/v2/invoices

For production:

https://api.xgateway.tech/api/v2/invoices

Payment methods with cards

When creating an invoice for Global Cards Processing one is required to specify a payment method.

A payment method defines:

1. Which card can be used by a customer

2. Which code will be used for the tx

3. Which geo locations can be served

4. Which type of traffic can be served

Below is a breakdown of the supported payment methods. Consult with the CS team about the payment methods available for you.

VisaMastercardTradingEU

1. Type of card: Visa and Mastercard

2. Code: 6211 (subject to change)

3. Geo: European Union

4. Traffic: Trading/Forex

VisaMastercardTradingNonEU

1. Type of card: Visa and Mastercard

2. Code: 6211 (subject to change)

3. Geo: Non European Union (see the list below)

4. Traffic: Trading/Forex

13KB

VISA and MC Supported Geos - Trading.xlsx

Open

VisaMastercardIGaming

1. Type of card: Visa and Mastercard

2. Code: 6211 (subject to change)

3. Geo: Requires review on a per-merchant basis

4. Traffic: iGaming casino, sports betting

AmexIGaming

1. Type of card: American Express

2. Code: 8999 (subject to change)

3. Geo: Global except the blocked countries (see the list)

4. Traffic: iGaming casino, sports betting

AmexTrading

1. Type of card: American Express

2. Code: 8999 (subject to change)

3. Geo: Global except the blocked countries (see the list)

4. Traffic: Trading/Forex

10KB

AMEX - Blocked Geos.xlsx

Open

Invoice options

The following examples of a request body will automatically activate the invoice with the pre-defined cards payment method.

Please read this page about the difference between base currency and payment currency.

EUR invoice - Forex Visa or Mastercard, Europe

{
"amount": "10",
"baseCurrency": "EUR",
"paymentCurrency": "EUR",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "VisaMastercardTradingEU"
}

EUR invoice - Forex Visa or Mastercard, Global

{
"amount": "10",
"baseCurrency": "EUR",
"paymentCurrency": "EUR",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "VisaMastercardTradingNonEU"
}

EUR invoice - iGamin Visa or Mastercard

{
"amount": "10",
"baseCurrency": "EUR",
"paymentCurrency": "EUR",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "VisaMastercardIGaming"
}

EUR invoice - iGaming American Express

{
"amount": "10",
"baseCurrency": "EUR",
"paymentCurrency": "EUR",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "AmexIGaming"
}

EUR invoice - Forex American Express

{
"amount": "10",
"baseCurrency": "EUR",
"paymentCurrency": "EUR",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "AmexTrading"
}

USD invoice - Forex Visa or Mastercard, Europe

{
"amount": "10",
"baseCurrency": "USD",
"paymentCurrency": "USD",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "VisaMastercardTradingEU"
}

USD invoice - Forex Visa or Mastercard, Global

{
"amount": "10",
"baseCurrency": "USD",
"paymentCurrency": "USD",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "VisaMastercardTradingNonEU"
}

USD invoice - iGamin Visa or Mastercard

{
"amount": "10",
"baseCurrency": "USD",
"paymentCurrency": "USD",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "VisaMastercardIGaming"
}

USD invoice - iGaming American Express

{
"amount": "10",
"baseCurrency": "USD",
"paymentCurrency": "USD",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "AmexIGaming"
}

USD invoice - Forex American Express

{
"amount": "10",
"baseCurrency": "USD",
"paymentCurrency": "USD",
"orderId": "random-order-id",
"customerId": "random-customer-id",
"paymentMethod": "AmexTrading"
}

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.

Invoice limits

Currency	Min value	Max value
Trading Visa / MC	10$	$15000
Amex	10$	$15000
igaming Visa / MC	10$	$€5,000

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.

Test cards data

Card number	Test scenario
4000 0000 0000 0002	3DS, successful authorisation
4242 4242 4242 4242	3DS, declined authorisation
4000 0000 0000 0408	Not enrolled for 3DS, successful authorisation
4000 0000 0000 0416	Not enrolled for 3DS, declined authorisation

Request example

Invoice creation with curl

curl --location 'https://api.xgateway.tech/api/v2/invoices' \
--header 'Accept: application/json' \
--header 'x-api-key: MERCHANT API KEY HERE' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "10",
    "baseCurrency": "EUR",
    "paymentCurrency": "EUR",
    "orderId": "random-order-id",
    "customerId": "random-customer-id",
    "paymentMethod": "VisaMastercardTradingEU"
}'