Integration using Checkout Page

This option 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.

Please check the Payment flows page for a list of payment flows and currencies available for this integration form.

Invoice payment flow

XGateway supports two types of invoices: with a floating and with a fixed exchange rate.

Floating Rate invoices

Invoice with 24-hour expiration time. An exchange rate is "floating", which means that the exchange rate updates every 15 minutes and a payment amount can change over time. The customer can have only 1 floating invoice at a time, once the customer creates a new invoice all previous invoices will be cancelled.

To create a Floating Rate invoice in the payment processing system, you need to make a POST request to the Invoice API v1 endpoint.

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

Creates an invoice with floating exchange rate strategy. Returns a checkout link.

The invoice will be activated right away if the payment currency and provider ID parameters are passed.

The link to the final step will be returned if the payment system has been passed as a parameter. If the payment system is not found, the user will be redirected to the select payment method step.

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

POSThttp://localhost:8000/api/v1/invoice

Authorization

api_key

Body

application/json

• The request body contains different fields for different providers (see below).

Crypto:

• amount - The amount to issue an invoice for.
• applicationId - The application identifier.
• baseCurrency - The base currency.
• customerId - The customer identifier.
• orderId - The order identifier.
• paymentCurrency - The payment currency.
• providerId - The provider identifier [DEPRECATED].

Peer-to-peer:

• amount - The amount to issue an invoice for.
• applicationId - The application identifier.
• baseCurrency - The base currency.
• customerId - The customer identifier.
• orderId - The order identifier.
• paymentCurrency - The payment currency.
• paymentSystem - The payment system.
• providerId - The provider identifier [DEPRECATED].

Peer-to-peer2:

• amount - The amount to issue an invoice for.
• applicationId - The application identifier.
• baseCurrency - The base currency.
• customerId - The customer identifier.
• customerName - The customer name (min 1, max 150).
• customerStreetAddress1 - The customer address (min 2, max 250, optional).
• customerCity - The customer city (min 2, max 20, optional).
• customerState - The customer state (min 2, max 100, optional).
• customerCountry - The customer country (min 2, max 100, optional).
• customerZip - The customer zip (min 6, max 9, optional).
• customerPhone - The customer phone (length - 10, to be passed without country code).
• customerEmail - The customer email (min 6, max 120).
• orderDescription - Description of product (min 1, max 1024, optional).
• orderId - The order identifier.
• paymentCurrency - The payment currency.
• paymentSystem - The payment system.
• providerId - The provider identifier [DEPRECATED].

CreateInvoiceV1Input (any of)

objectobjectobjectobject

Response

201400401422500

Created

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:8000/api/v1/invoice', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "paymentCurrency": "BNB",
      "customerId": "text",
      "baseCurrency": "EUR",
      "amount": "text"
    }),
});
const data = await response.json();

Response

201400401422500

{
  "success": true,
  "data": "text"
}

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

Headers

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

Fixed Rate invoices

Invoice with short time to live. Exchange rate fixes in a moment of invoice activation. Customers can create an unlimited amount of invoices but can have only up to 10 activated invoices. To activate a new one wait till previous invoices expire.

To create a Fixed Rate invoice in the payment processing system, you need to make a POST request to the Invoice API v2 endpoint. To manage the display of currencies on checkout page — use displayCurrencies parameter. When an array is provided, the function preserves and respects the specified order of the currencies. If parameter is not provided — checkout will show every enabled currency

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

Creates an invoice with fixed exchange rates strategy. The invoice is created based on the passed parameters: amount, base currency, customer id and order id (if any). Returns a checkout link.

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

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

Authorization

api_key

Body

application/json

• Contains amount, base currency, customer id and order id.

amount*number (double)

applicationIdstring

baseCurrency*Currency (enum)

Represents all currencies in the payment processing system.

Used to specify the currency of accounts, exchange rates, and transactions in the payment processing system.

It provides a controlled and standardized list of supported currencies for all transactions and balances in the payment processing system.

New currencies can be added to the payment processing system as additional members.

BNBbUSDTBTCETHeUSDCeUSDTFTNPOLpUSDCSOLsUSDTtUSDCtUSDTwpUSDCwpUSDTEURGBPAZNBDTINRJPYPKRRUBTRYUZSKESUSDUSDCUSDTTRX

customerId*string

orderIdstring

invoiceStrategyInvoiceStrategy (enum)

Represents the possible strategies of an invoice.

floatingfixed

displayCurrenciesany of

Currency (enum)array of Currency (enum)

Response

201400401422500

Created

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/invoices', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount": 0,
      "baseCurrency": "BNB",
      "customerId": "text"
    }),
});
const data = await response.json();

Response

201400401422500

{
  "success": true,
  "data": "text"
}

Remember to authorize 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)

v1

The time to live for floating invoices is 24 hours.

v2

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.