Integration using API

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

XGateway provides an API that can be used to integrate the payment platform into your application.

Banking onramp flow (SEPA or Faster Payments)

In order to integrate the banking payment flow it is required to enable a customer to do the following:

1. The customer should be able to pass a KYC for larger transactions or second use of the system.

2. The customer should be able to obtain a virtual IBAN/BIC or Account Number/Sort Code linked to this customer ID.

3. The customer should be able to retrieve the bank account data to send funds to.

4. The customer should be able to create an invoice to lock the exchange prices.

Each of the steps is implemented within a separate API endpoint on the XGateway side.

The KYC is required only for larger transactions or second use of the system and is done by a third-party vendor. XGateway is operating as a relayer, doesn't store user data and just passes the user information forward. The API to use is described below. Note that a successful response to this request doesn't mean the KYC is passed. Usually, KYC takes seconds, but for some users, the manual KYC done by a vendor may take hours.

Invoice creation is an optional step, that should be done to ensure the best user experience - deposits with locked exchange rates. An invoice can be created using the API.

In case a user does a deposit for an amount that differs from the amount in the invoice - XGateway will still account the funds properly and send the call back to the merchant.

It is required that the deposits to are done from a personal bank account that belongs to the person with the same name and surname as used for the the KYC. If a deposit is done from a corporate account or an account that belongs to a person with different name or surname - such a deposit will be bounced back by the banking partner.

Create a bank account and initiate KYC verification

An account should be created and assigned to a customer to send funds using banking payments. When done, all funds sent to this bank account are considered to be deposits in the XGateway system for the linked customer.

To create a customer bank account, initiate the KYC verification process by collecting necessary customer information and documents through the request body. It supports both one-sided and two-sided KYC documents, such as a passport (one-sided) or a driver's license (two-sided). The method validates the provided information, uploads the necessary documents, and finally initiates the KYC verification process.

First, create a bank account associated with the external customer ID.

Creates a bank transfer account for a customer.

Registers a new bank transfer account for a customer associated with the given external ID.

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/customer/{id}/bank-transfer

Authorization

api_key

Path parameters

id*string

• The external identifier for the customer, used to uniquely identify them and associate them with a merchant.

Body

application/json

• Contains customer data for creating a bank account.

lastNamestring

firstNamestring

emailstring

currencyenum

EURGBP

countrystring

Response

201400401409422500

Created

Body

application/json

success*boolean

data*CreateBankTransferAccountResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201400401409422500

{
  "success": true,
  "data": {
    "accountNumber": "text",
    "bic": "text",
    "country": "text",
    "currency": "EUR",
    "iban": "text",
    "sortCode": "text",
    "status": "ACTIVE"
  }
}

If the status of the bank account in the response is PENDING, you should wait for a special Bank Account callback, which will be sent to your system once the bank account is activated. Please follow this page for more details.

Then upload all the necessary data to pass the KYC process.

Initiates the KYC (Know Your Customer) verification process for a customer's bank transfer account.

Initiates the KYC (Know Your Customer) verification process for a customer's bank transfer account.

This endpoint is responsible for starting the KYC verification process by collecting necessary customer information and documents through the request body. It supports both one-sided and two-sided KYC documents, such as a passport (one-sided) or a driver's license (two-sided). The method validates the provided information against a predefined schema, creates KYC applicants, uploads the necessary documents, and finally initiates the KYC verification process.

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/customer/{id}/bank-transfer/kyc

Authorization

api_key

Path parameters

id*string

• The unique identifier of the customer for whom KYC verification is being initiated.

Body

application/json

• The body of the request containing KYC applicant information and document details.

documentany of

objectobject

selfieobject

sourceOfFundsenum

BUSINESS_INCOMEOTHERPENSIONSALARY

address2string

address1string

citystring

postCodestring

dateOfBirthstring (date-time)

countrystring

Response

201400401422500

KYC verification initiated

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201400401422500

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

When the data is uploaded, initiate the KYC process.

Starting a KYC (Know Your Customer) verification with the current documents uploaded.

Starting a KYC (Know Your Customer) verification with the current documents uploaded.

Access to this endpoint requires a valid API key. The API key is sent in the x-api-key header on requests. Requirements to start the KYC verification process:

• the customer has a bank account;
• the customer has a KYC application;
• the customer has uploaded all the necessary documents;
• the customer has KYC status KYC_PENDING or SOFT_KYC_FAILED.

POSThttps://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc/verification

Authorization

api_key

Path parameters

id*string

• The external identifier for the customer for whom KYC verification is being initiated.

Response

204400401500

KYC verification started

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc/verification', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

204400401500

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

If the uploaded data is not correct, the following two APIs can be used to correct the information - either the text items or the files of the documents.

Updates customer bank transfer profile details. Only the provided fields will be updated.

Updates the bank transfer profile details for a specified customer. This endpoint allows for partial updates; thus, only the fields provided in the request body will be updated.

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

PATCHhttps://api.xgateway.tech/api/v2/customer/{id}/bank-transfer

Authorization

api_key

Path parameters

id*string

• The external identifier for the customer, used to uniquely identify them and associate them with a merchant.

Body

application/json

• The details to be updated. This includes optional fields for the customer's first name, last name, date of birth, email, target address, and physical address.

addressobject

targetAddressstring

dateOfBirthstring (date-time)

lastNamestring

firstNamestring

emailstring

Response

204400401422500

Action has been accepted

Body

application/json

success*boolean

data*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

204400401422500

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

Uploads a KYC (Know Your Customer) document for a specified customer to assist in their KYC verification process.

Uploads a KYC (Know Your Customer) document for a specified customer to assist in their KYC verification process.

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

PUThttps://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc/document

Authorization

api_key

Path parameters

id*string

• The external identifier for the customer whose KYC document is being uploaded.

Body

application/json

• The KYC document details to be uploaded.

UploadKycDocumentInput (any of)

objectobject

Response

204400401422500

No Content

Body

application/json

success*boolean

data*nullable enum

null

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc/document', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

204400401422500

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

It is possible to retrieve the data about the bank account using this API.

Retrieves bank transfer details for all accounts of a specified customer.

Retrieves bank transfer details for all accounts of a specified customer.

This endpoint fetches the bank transfer details for all accounts associated with a given customer ID.

It ensures that the requester has appropriate authorization before providing access to the sensitive account information.

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

The response includes an array of accounts with following properties:

• account number, for GBP
• BIC, for EUR
• country
• currency
• IBAN, for EUR
• ID
• sort core, for GBP
• status.

GEThttps://api.xgateway.tech/api/v2/customer/{id}/bank-transfer

Authorization

api_key

Path parameters

id*string

• The external ID of the customer whose bank transfer details are being requested.

Response

200400401404500

Ok

Body

application/json

success*boolean

data*array of BankTransferAccountResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401404500

{
  "success": true,
  "data": [
    {
      "accountNumber": "text",
      "bic": "text",
      "country": "text",
      "currency": "text",
      "iban": "text",
      "id": "text",
      "sortCode": "text",
      "status": "FULL_USER"
    }
  ]
}

In order to check the status of the KYC process for a specific account use this API.

Retrieves the details of a Know Your Customer (KYC) application for a specified customer.

Retrieves the details of a Know Your Customer (KYC) application for a specified customer. This includes the KYC status, any missing documents, and details about any issues or rejections in the KYC process.

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

GEThttps://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc

Authorization

api_key

Path parameters

id*string

• The external identifier for the customer for whom to retrieve KYC details.

Response

200400401404500

Ok

Body

application/json

success*boolean

data*KycApplicationDetailsResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/customer/{id}/bank-transfer/kyc', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401404500

{
  "success": true,
  "data": {
    "id": "text",
    "status": "FULL_USER",
    "docsMissing": [
      {
        "docType": "ID_CARD"
      }
    ],
    "kycEndUserErrorMessage": "text",
    "kycRejectLabel": "text"
  }
}

Channel payment flow

This is a set of API calls you can support to customize the channel payment flow to your needs.

In order to make a deposit, your customer will first need to get an address assigned to them. To generate an address for a customer, make a POST request to /wallet/address specifying customer ID and currency (here's the list we currently support).

Returns a previously created or brand-new address with a link to a QR code.

Create a channel for the customer for a specified currency.

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

Authorization

api_key

Body

application/json

• Contains currency and customer id.

currency*SupportedCryptoCurrency (enum)

Represents supported crypto currencies in the payment processing system.

Currencies:

• BNB - Binance Coin
• bUSDT - Tether (pegged to USD), issued on BNB Smart Chain network (BEP20 token)
• BTC - Bitcoin
• ETH - Ether
• eUSDC - USD Coin (pegged to USD), issued on Ethereum network (ERC20 token)
• eUSDT - Tether (pegged to USD), issued on Ethereum network (ERC20 token)
• FTN - Fasttoken
• POL - POL
• pUSDC - USD Coin (pegged to USD), issued on Polygon network (ERC20 token)
• SOL - SOL
• sUSDT - Tether (pegged to USD), issued on Solana network (SPL token)
• tUSDC - USD Coin (pegged to USD), issued on Tron network (TRC20 token)
• tUSDT - Tether (pegged to USD), issued on Tron network (TRC20 token)
• wpUSDC - wrapped USD Coin (pegged to USD), issued on Polygon network (ERC20 token)
• wpUSDT - wrapped Tether (pegged to USD), issued on Polygon network (ERC20 token).

BNBbUSDTBTCETHeUSDCeUSDTFTNPOLpUSDCSOLsUSDTtUSDCtUSDTwpUSDCwpUSDT

customerId*string

Response

200201400401422500

Ok

Body

application/json

any of

AppSuccessResponse_IAddressResponse_ (object)AppErrorResponse (object)

Request

JavaScriptCurlPython

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

Response

200201400401422500

{
  "success": true,
  "data": {
    "address": "text",
    "qrCodeURL": "text",
    "qrCode": "text"
  }
}

In case of a successful response, the data property contains the address that you can display to your customer. You can also use the qrCodeURL property to display the address in an easy-to-use format. Once the customer deposits funds to this address, you will get a notification to your callback URL that will carry a payload similar to:

{
  "amount": "10",
  "currency": "USD",
  "customerId": "demo_customer_id",
  "hash": "[HASH]",
  "id": "916c9ef9-8678-4676-b8bf-14e6333090f6",
  "invoiceId": "2ab1fcbe-6044-420b-8457-2d26bf58d70a",
  "network": null,
  "orderId": "demo_order_id",
  "status": "confirmed",
  "transactionHash": null,
  "type": "deposit",
  "info": {
    "exchangeRate": "1",
    "referenceAmount": "10",
    "referenceCurrency": "USD",
    "referenceExchangeRate": "1",
    "transactionAmount": "10",
    "transactionCurrency": "USDC"
  }
}

You can then handle this information, e.g. top up the customer’s balance on your website with the given amount. See Callbacks to learn about this in detail.

Once an address for a certain customer ID has been created, it gets saved in our database and each time you request it again, you will get the same address back. This means that the customer can safely store the address and continue depositing funds onto it, and you will be notified every time.

If for any reason you need to convert the transaction amount into another currency, for example - the base currency of the merchant, it is possible to use the exchange rate service.

Example:

curl -X 'GET' \ 
'https://api.xgateway.dev/api/v1/exchange/rate?amount=100&source=RUB&target=EUR'
-H 'accept: application/json'

Response:

}
  "data": "1.00332217540039999959",
  "success": true
}

Get balance

Merchant balances for each specific account can also be retrieved using an API request.

Retrieves balances for all merchant assets.

Retrieves balances for all merchant assets, expressed in the configured reference currency.

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

GEThttps://api.xgateway.tech/api/v2/balance/assets

Authorization

api_key

Response

200400401500

Ok

Body

application/json

success*boolean

data*array of IAssetMerchantBalanceResult (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.xgateway.tech/api/v2/balance/assets', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401500

{
  "success": true,
  "data": [
    {
      "accountCurrency": "BNB",
      "accountId": "text",
      "balance": "text",
      "currency": "BNB"
    }
  ]
}