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.

Demo / Prod 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:

Which card can be used by a customer
Which MCC Code will be used for the transactions
Which geo locations can be served
Which type of traffic can be served

Payment method is a mandatory parameter.
To avoid blocked payments, use the correct payment method.

The client's address and the client's issuer bank country must be the same.

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

VisaMastercardTradingEU

Type of card: Visa and Mastercard
Geo: European Union
Traffic: Trading/Forex

VisaMastercardTradingNonEU

Type of card: Visa and Mastercard
Geo: Non European Union (see the list below)
Traffic: Trading/Forex

VISA and MC supported countries by MID.xlsx - Download

VisaMastercardIGaming

Type of card: Visa and Mastercard
Geo: Requires review on a per-merchant basis
Traffic: iGaming casino, sports betting

AmexIGaming

Type of card: American Express
Geo: Global except the blocked countries (see the list)
Traffic: iGaming casino, sports betting

AmexTrading

Type of card: American Express
Geo: Global except the blocked countries (see the list)
Traffic: Trading/Forex

AMEX - Blocked Geos.xlsx - Download

BASIC_CARD

Type of card: Visa, Mastercard
Geo: Global except the blocked countries
Traffic: Contact business team for clarifications

Base Card Blocked Countries.csv - Download

Invoice options#

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

Please read the page explaining the several important currency terms before testing.

EUR#

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 - iGaming 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"
}

EUR invoice - BasicCards

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

Extended form for automatic invoice activation

{
"amount": 10,
"baseCurrency": "EUR",
"customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
"customerEmail": "[email protected]",
"customerFirstName": "John",
"customerLastName": "Doe",
"customerPhone": "49 15123456789",
"customerDateOfBirth": "2000-02-10",
"paymentMethod": "BASIC_CARD",
"paymentCurrency": "EUR",
"billingAddress": {
    "addressLine1": "Hlavni mesto Praha 11 22",
    "city": "Prague",
    "countryCode": "CZ",
    "postalCode": "15000",
    "state": "Praha, Hlavni mesto"
}
}

Response includes checkout URL for the customer to continue the flow.

{
"data": "https://checkout.xgateway.tech/...",
"success": "true"
}

Extended form for automatic payment execution (host-to-host approach)

{
"amount": 1,
"baseCurrency": "EUR",
"customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
"customerEmail": "[email protected]",
"customerFirstName": "John",
"customerLastName": "Doe",
"customerPhone": "49 15123456789",
"customerDateOfBirth": "2000-02-10",
"paymentMethod": "BASIC_CARD",
"paymentCurrency": "EUR",
"accountId": "a67ec03c-0253-4c14-9961-28985186f90c",
"userIp": "217.138.202.40",
"billingAddress": {
    "addressLine1": "Hlavni mesto Praha 11 22",
    "city": "Prague",
    "countryCode": "CZ",
    "postalCode": "15000",
    "state": "Praha, Hlavni mesto"
},
"card": {
    "cardNumber": "4000 0000 0000 0002",
    "cardholderName": "John Doe",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "cardSecurityCode": "444"
}
}

Response includes a URL for the customer to continue the flow with 3DS verification.

{
"data": "https://bank-3ds-url/payment/...",
"success": "true"
}

In case of any issues (validation errors, insufficient balance, failed 3DS validation) the customer is returned back to XGateway checkout for graceful error handling.

Cards for tests:

4000000000000002 - 10/28 - 123 - Success tx

4242424242424242 - <any> - <any> - Failed tx

USD#

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 - iGaming 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 the iFrame setup 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 is outside the allowed 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 the transaction callbacks for deposits and withdrawals page.

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#

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 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: <your-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"
}'

Pre-populate data#

The API for invoice creation supports data pre-population. It is allowed to leave any of the fields empty.

Invoice creation with pre-population of data

curl --location 'https://api.xgateway.tech/api/v2/invoices' \
--header 'Accept: application/json' \
--header 'x-api-key: <your-api-key-here>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": "100",
    "baseCurrency": "EUR",
    "paymentCurrency": "EUR",
    "orderId": "some order id here",
    "customerId": "some customer id here",
    "customerCountry": "EE",
    "customerEmail": "[email protected]",
    "customerFirstName": "Jane",
    "customerLastName": "Doe",
    "customerPhone": "1234567",
    "customerPostCode": "1234",
    "customerCity": "Tallinn",
    "customerState": "Harjumaa",
    "customerStreet": "Vee 1234",
    "paymentMethod": "VisaMastercardTrading"
}'