# Global Cards Processing

XGateway offers deposits with the preliminary creation of [invoices](https://docs.xgateway.tech/payment-flows#invoice) 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

{% hint style="danger" %}
It is highly recommended to warn customers not to use VPN (including [Apple Private Relay](https://support.apple.com/en-us/102602)).
{% endhint %}

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](https://docs.xgateway.tech/integration-guides/advanced-features-of-invoice-creation). Find examples of request bodies below. Use Demo environment for tests.

<details>

<summary>URLs</summary>

For tests use Demo env:

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

For production:

[https://api.xgateway.tech/api/v2/invoices](https://api.demo.xgateway.tech/api/v2/invoices)

</details>

#### Payment methods with cards

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

A payment method defines:

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

{% hint style="warning" %}
Payment method is a **mandatory** parameter. &#x20;

To avoid **blocked** payments, use the correct payment method.
{% endhint %}

{% hint style="info" %}
The client's address and the client's issuer bank country must be the same.
{% endhint %}

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

**VisaMastercardTradingEU**

1. Type of card: Visa and Mastercard
2. Geo: European Union
3. Traffic: Trading/Forex

**VisaMastercardTradingNonEU**

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

{% file src="<https://1560383694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz4bIs7jkRtsghj4Pgs6Z%2Fuploads%2F5WpAbTr0XSSjgLcdSPXN%2FVisa%20and%20MC%20supported%20countries%20by%20MID.xlsx?alt=media&token=1f57ede4-6f52-4f36-b2f7-35bf4f85f4ee>" %}

**VisaMastercardIGaming**

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

**AmexIGaming**

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

**AmexTrading**

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

{% file src="<https://1560383694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz4bIs7jkRtsghj4Pgs6Z%2Fuploads%2FZauZ9bBJ515GpOtotpoy%2FAMEX%20-%20Blocked%20Geos.xlsx?alt=media&token=d628b60a-0abf-4de4-a513-bb65e5e2f3a0>" %}

**BasicCards**

1. Type of card: Visa, Mastercard, American Express
2. Geo: Global except the blocked countries
3. Traffic: Contact business team for clarifications

#### Invoice options

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

{% hint style="warning" %}
Please read [this](https://docs.xgateway.tech/miscellaneous/invoice-currencies) page about the difference between base currency and payment currency.&#x20;
{% endhint %}

<details>

<summary>EUR invoice - Forex Visa or Mastercard, Europe</summary>

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

</details>

<details>

<summary>EUR invoice - Forex Visa or Mastercard, Global</summary>

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

</details>

<details>

<summary>EUR invoice - iGamin Visa or Mastercard</summary>

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

</details>

<details>

<summary>EUR invoice - iGaming American Express</summary>

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

</details>

<details>

<summary>EUR invoice - Forex American Express</summary>

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

</details>

<details>

<summary>EUR invoice - BasicCards</summary>

```json
{
  "amount": 10,
  "baseCurrency": "EUR",
  "paymentCurrency":"EUR",
  "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "paymentMethod": "BASIC_CARD"
}
```

For automatic invoise activation:

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

</details>

<details>

<summary>USD invoice - Forex Visa or Mastercard, Europe</summary>

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

</details>

<details>

<summary>USD invoice - Forex Visa or Mastercard, Global</summary>

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

</details>

<details>

<summary>USD invoice - iGamin Visa or Mastercard</summary>

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

</details>

<details>

<summary>USD invoice - iGaming American Express</summary>

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

</details>

<details>

<summary>USD invoice - Forex American Express</summary>

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

</details>

{% hint style="warning" %}
If you get a bad request response without exact information about the erroneous field, please check the syntax of the request.&#x20;
{% endhint %}

The request returns a link to a correspondingly configured Checkout page.&#x20;

The Checkout page will lead the customer through the deposit flow.&#x20;

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](https://docs.xgateway.tech/advanced-features-of-invoice-creation#the-invoice-creation-api) or to a pre-set static URL.

The invoice URL may also be used in an iFrame. Please check [this](https://docs.xgateway.tech/miscellaneous/iframe-setup) page for detailed instructions on the iFrame setup.

### Limits

The invoice creation API validates the amount value.

{% hint style="danger" %}
An invoice will not be created, if the amount exceeds the limits.
{% endhint %}

<details>

<summary>Invoice limits</summary>

| Currency          | Min value | Max value      |
| ----------------- | --------- | -------------- |
| Trading Visa / MC | 10$       | $15000         |
| Amex              | 10$       | $15000         |
| iGaming Visa / MC | 10$       | $€5,000        |
| Basic Cards       | 10$       | $1,000,000,000 |

</details>

### 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](https://docs.xgateway.tech/miscellaneous/how-to-process-the-callback/transaction-callback-for-deposit-and-withdraw) for further information about the callbacks.&#x20;

In case of Global Card Rail chargebacks are possible. XGateway also relays this information to the merchant using a special [callback type](https://docs.xgateway.tech/miscellaneous/how-to-process-the-callback/global-card-rail-chargeback-callback).

{% hint style="warning" %}
Callbacks for Withdraw requests will be sent to the same URL. Make sure to properly filter callbacks by type.
{% endhint %}

### Confirming a transaction

{% hint style="danger" %}
Due to security risks, merchants *must* use our [API endpoint](https://docs.xgateway.tech/miscellaneous/deposit-data-confirmation) to request transaction details. XGateway is not liable for issues caused by relying only on callback data.
{% endhint %}

To confirm the callback is valid, please use the [API endpoint](https://docs.xgateway.tech/miscellaneous/deposit-data-confirmation).

### Testing on Demo environment

One may use the following data to simulate successful deposits on the [Demo Environment](https://docs.xgateway.tech/miscellaneous/environments).&#x20;

<details>

<summary>Test cards data</summary>

<table><thead><tr><th width="226.21875">Card number</th><th>Test scenario</th></tr></thead><tbody><tr><td>4000 0000 0000 0002</td><td>3DS, successful authorisation</td></tr><tr><td>4242 4242 4242 4242 </td><td>3DS, declined authorisation</td></tr><tr><td>4000 0000 0000 0408</td><td>Not enrolled for 3DS, successful authorisation</td></tr><tr><td>4000 0000 0000 0416</td><td>Not enrolled for 3DS, declined authorisation</td></tr></tbody></table>

</details>

### Request example

<details>

<summary>Invoice creation with curl </summary>

```
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"
}' 
```

</details>

### Pre-populate data

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

<details>

<summary>Invoice creation with pre-population of data </summary>

```
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-raw '{
    "amount": "100",
    "baseCurrency": "EUR",
    "paymentCurrency": "EUR",
    "orderId": "some order id here",
    "customerId": "some customer id here",
    "customerCountry": "EE",
    "customerEmail": "info77@riddec.com",
    "customerFirstName": "Jane",
    "customerLastName": "Doe",
    "customerPhone": "1234567",
    "customerPostCode": "1234",
    "customerCity": "Tallinn",
    "customerState": "Harjumaa",
    "customerStreet": "Vee 1234",
    "paymentMethod": "VisaMastercardTrading"
}'
```

</details>