# Crypto Payments using Checkout

{% hint style="warning" %}
Please read [this](https://docs.xgateway.tech/miscellaneous/invoice-currencies) page before starting. The invoice creation API uses several parameters that need explanation. 
{% endhint %}

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

<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>

The XGateway provides one [API endpoint](https://docs.xgateway.tech/integration-guides/advanced-features-of-invoice-creation), which automatically defines a corresponding payment method based on the input parameters provided by the merchant. Below is an example of a payload that contains the minimum fields set required to create an invoice for a Crypto Payment.

```json
{
    "orderId": "test-prod-order",
    "customerId": "test-prod-customer",
    "baseCurrency": "USD",
    "invoiceStrategy": "fixed",
    "amount": 10
}
```

<details>

<summary>Curl example</summary>

```json
curl -X POST https://api.demo.xgateway.tech/api/v2/invoices \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: */*" \
  -d '{
    "orderId": "test-prod-order",
    "customerId": "test-prod-customer",
    "baseCurrency": "USD",
    "invoiceStrategy": "fixed",
    "amount": 10
}'
```

</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. This page contains the wallet address for a deposit to be made. The page is used by a customer to finish the deposit.

By default, the payment gateway links the created wallet to a customer forever. The created wallet can be used across all EVM compatible chains.&#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.

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

<details>

<summary>Callback example</summary>

```json
{
   "callbackType":"transaction",
   "amount":"200",
   "applicationId":null,
   "currency":"USDT",
   "customerId":"000394",
   "hash":"...",
   "id":"7e71d132-d80d-4140-8e60-9c89d0bd9eed",
   "invoiceId":"184e9933-1526-...-fe567091b5bd",
   "network":"tron",
   "orderId":null,
   "status":"confirmed",
   "transactionHash":"0x58f6",
   "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"
}
```

</details>

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

### Limits

The invoice creation API validates the amount value.&#x20;

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

<details>

<summary>Invoice limits</summary>

<table><thead><tr><th valign="top">Currency</th><th valign="top">Min value</th><th>Max value</th></tr></thead><tbody><tr><td valign="top">BNB</td><td valign="top">0.001000000000000000</td><td>None</td></tr><tr><td valign="top">BTC</td><td valign="top">0.000082000000000000</td><td>None</td></tr><tr><td valign="top">BSC USDT</td><td valign="top">5.000000000000000000</td><td>None</td></tr><tr><td valign="top">ETH</td><td valign="top">0.002000000000000000</td><td>None</td></tr><tr><td valign="top">Ethereum USDC</td><td valign="top">5.000000000000000000</td><td>None</td></tr><tr><td valign="top">Ethereum  USDT</td><td valign="top">5.000000000000000000</td><td>None</td></tr><tr><td valign="top">FTN</td><td valign="top">2.000000000000000000</td><td>None</td></tr><tr><td valign="top">POL</td><td valign="top">12.000000000000000000</td><td>None</td></tr><tr><td valign="top">Polygon USDC</td><td valign="top">5.000000000000000000</td><td>None</td></tr><tr><td valign="top">TRX</td><td valign="top">25.000000000000000000</td><td>None</td></tr><tr><td valign="top">Tron USDC</td><td valign="top">5.000000000000000000</td><td>None</td></tr><tr><td valign="top">Tron USDT</td><td valign="top">5.000000000000000000</td><td>None</td></tr></tbody></table>

</details>

### 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 Crypto Payments on Demo environment

You can test direct crypto deposits in the [Demo Environment](https://docs.xgateway.tech/miscellaneous/environments).&#x20;

#### Testing with transaction simulation

The Demo Environment provides and [API](https://docs.xgateway.tech/miscellaneous/deposit-and-withdrawal-simulation) to simulate a deposit. This is the best way to test the integration, because it does not require to make real blockchain transactions.&#x20;

#### Testing with real transactions

An alternative way to test the integration is to deposit native token on a test network. Proceed with the integration up to the point where the customer wallet is generated and returned to you. Make sure that deposits of ETH are enabled for your profile.

Use faucets, like [this](https://www.alchemy.com/faucets) one, to get some ETH on Sepolia test network.&#x20;

Send a portion of this ETH to the wallet, assigned to your customer.&#x20;

Wait for the system to send you a callback about a successful deposit.&#x20;

More faucets:

1. <https://faucet.quicknode.com/ethereum> - ETH
2. <https://docs.metamask.io/developer-tools/faucet/> - ETH
3. <https://bitcoinfaucet.uo1.net/> - BTC
4. <https://testnet.help/en/btcfaucet/testnet> - BTC


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xgateway.tech/integration-guides/crypto-payments-using-checkout.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.