Integration using Checkout Page

This form of integration allows you to get a head start on integration and saves you the trouble of building your own UI, generating user addresses for each currency and displaying them to the user.

The main mode of operation of XGateway is using invoices with a fixed exchange rate.

Please read this page before starting. The invoice creation API uses several parameters that need explanation.

Fixed Rate invoices

A fixed rate invoice locks exchange rate for the transfer of funds for 15 minutes. After this period the invoice is marked as expired.

In order to create a Fixed Rate invoice in the payment processing system, you need to make a POST request to the Invoice API v2 endpoint.

The XGateway provides one API endpoint, which automatically defines a corresponding payment methods based on the input parameters provided by the merchant.

Below you can see examples of requests for different payment methods. A detailed explanation of the API endpoint is available in the next section.

The system will skip all XGateway intermediate pages and redirect the customer directly to the payment method only if all required data is provided.

Examples of requests

Crypto deposit

Create an invoice:

{
    "orderId": "order-test-prod",
    "customerId": "test-prod",
    "baseCurrency": "USD",
    "amount": 10
}

EUR or GBP deposit

Create an invoice:

{
    "orderId": "order-test-prod",
    "customerId": "test-prod2025",
    "baseCurrency": "EUR",
    "amount": 100
}

Create and activate invoice (opens the payment method directly):

{
    "orderId": "order-test-prod",
    "customerId": "test-prod2025",
    "baseCurrency": "EUR",
    "amount": 100,
    "paymentCurrency": "EUR",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerEmail": "[e-mail]",
    "customerCountry": "AU"
}

TRY Papara request

NOTE: For Papara the amount must be a multiple of 50 (example: 150, 200, 250 TRY etc.)

Create an invoice:

{
    "amount": 150,
    "baseCurrency": "TRY",
    "displayCurrencies": "TRY",
    "customerId": "test-customer-id",
    "orderId": "test-order-id"
}

Create and activate an invoice (opens the payment method directly):

{
    "amount": 150,
    "baseCurrency": "TRY",
    "displayCurrencies": "TRY",
    "customerId": "test-customer-id",
    "orderId": "test-order-id",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerAccount": "123456789", // Papara account
    "customerEmail": "[e-mail]",
    "paymentCurrency": "TRY"
}

INR deposit

Create an invoice:

{
    "orderId": "order-test-prod",
    "customerId": "test-prod2025",
    "baseCurrency": "INR",
    "amount": 1000
}

Create and activate an invoice for INR (opens the payment method directly):

{    
    "orderId": "order-test-prod",
    "customerId": "test-prod2025",
    "baseCurrency": "INR",
    "amount": 1000,
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "paymentCurrency": "INR",
    "customerEmail": "[e-mail]",
    "customerCountry": "AU", // Optional for INR-P3
    "customerPhone": "1234567890" // Optional for INR-P3
}

API endpoint specification

The full API endpoint specification is available below.

The request to create an invoice may specify application (applicationId). This is an optional parameter used to customise the look and feel of the checkout page. Every application contains its own settings set to tailor the checkout page for different needs.

Note, that baseCurrency parameter defines the expected currency of the deposit. It does not change or affect the reference currency - the currency used for all the internal accounting for you as a merchant.

The customer identificator is a mandatory field, which must contain the id of the customer, used in your system. This id is sent back in the callbacks on every deposit in order to link deposits with corresponding customers.

The order identificator is an optional parameter, which will be sent back to your system with a callback for the deposit linked to this exact invoice.

Create an invoice for the customer for a specified currency and optional order id.

post

Creates an invoice using a fixed or floating exchange rate strategy. The invoice is generated based on the provided parameters, including amount, base currency, customer ID, and optionally, an order ID.

If paymentCurrency is provided and all required activation parameters for a specific payment are included (customerFirstName, customerLastName, customerEmail, customerCountry, customerPhone, customerAccount), the invoice is instantly activated.

Returns a checkout link upon successful creation.

Access to this endpoint requires a valid API key. The API key is sent in the x-api-key header on requests.

Authorizations

Body

• The input data for creating an invoice.

Params:

• amount - The amount. Must be greater than 0.
• applicationId - The associated application ID in your system.
• baseCurrency - The base currency.
• customerId - The customer ID in the your system.
• orderId - The associated order ID in the your system.
• invoiceStrategy - The invoice strategy. "floating" || "fixed"
• displayCurrencies - The display currencies.
• customerAccount - The Customer Account number in payment system.
• customerCountry - The ISO 3166-1 alpha-2 country name.
• customerEmail - The email address.
• customerFirstName - The first name.
• customerLastName - The last name.
• customerPhone - The phone number.
• paymentCurrency - The currency in which the payment will be made.

amountnumber · doublerequired

applicationIdstringoptional

baseCurrencystring · enumrequired

Base Currency is the currency of a customer deposit or withdrawal. It is used to initiate the deposit invoice or withdrawal request. This is the currency a customer will typically see on the merchant cashier page.

Example: A customer wants to deposit 10 EUR of ETH. In this case the base currency is EUR.

Available options:

customerAccountstringoptional

customerCountrystringoptional

customerEmailstringoptional

customerFirstNamestringoptional

customerIdstringrequired

customerLastNamestringoptional

customerPhonestringoptional

displayCurrenciesany ofoptional

This is an array of currencies used to manage the display of currencies on the Checkout page. When an array is provided, the function preserves and respects the specified list and order of the currencies shown to the customer.

invoiceStrategystring · enumoptional

Represents the possible strategies of an invoice.

Available options:

orderIdstringoptional

paymentCurrencystring · enumoptional

A transaction currency is the native currency that is received by XGateway and available for settlement by the corresponding merchant. This is the currency used to make the transaction on the blockchain to move the value, ie ETH, BTC, any ERC-20 token etc.

Example: A customer wants to deposit 10 EUR of ETH. In this case the transaction currency is ETH.

Available options:

Responses

application/json

application/json

application/json

application/json

application/json

post

cURLJavaScriptPythonHTTP

curl -L \
  --request POST \
  --url 'https://api.xgateway.tech/api/v2/invoices' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 0.1,
    "applicationId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
    "baseCurrency": "BNB",
    "customerAccount": "2004169722",
    "customerCountry": "AU",
    "customerEmail": "[e-mail]",
    "customerFirstName": "John",
    "customerId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
    "customerLastName": "Doe",
    "customerPhone": "79111234567",
    "orderId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8",
    "invoiceStrategy": "floating",
    "displayCurrencies": "BNB",
    "paymentCurrency": "BNB"
  }'

201

400

401

422

500

201

{
  "data": "https://checkout.xgateway.tech/ff36a7a5-08fd-418a-a150-f6f2d36676a8",
  "success": true
}

Created

Remember to authorise the request with your x-api-key header.

Headers

Name	Type	Description
x-api-key*	String	Your API key

Session Life

Invoices at the moment of creation have no expiration time. After invoice activation on the checkout page (when the customer selects the payment currency and clicks "Proceed"), the system will set an expiration time according to invoice TTL. Once an invoice has expired, the link will show an error.

You can make several requests for the same customer with a different amount/base currency and get a different checkout link back.

Invoice time to live(TTL)

The time to live for floating invoices is 24 hours.

The time to live for fixed invoices can be configured during merchant creation and can also be adjusted later in the Merchant's back office. The default value for the invoice TTL is 1200 seconds, which is equivalent to 20 minutes.

Pre-populate the form for KYC

The KYC flow through the Checkout V2 supports pre-population of fields in case your service already has the personal data of the customers. This function is only available for banking onramp. In order to pre-populate the form add the information into the URL parameters (query parameters) when working with an invoice. See the example below:

Query Params

Used to pre-fill customer data on the checkout page.

• firstName

• lastName

• email

• address1

• address2

• postCode

• city

• country: (ISO 3166-1 alfa-2 country code)

• dateOfBirth: YYYY-MM-DD

• sourceOfFunds: SALARY, BUSINESS_INCOME, PENSION, OTHER

Add all or some query params to a URL. Example of usage:

https://checkout.xgateway.dev/v2/invoice/4f61498c-6e80-4b15-a88a-b7e5a29292bd?firstName=Genry&lastName=Pollok&email=[e-mail]&address1=Some-Street 12 tn.2&address2=ap.3&postCode=12345&city=New York&country=US&dateOfBirth=1984-09-09&sourceOfFunds=SALARY