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 KYC for larger transactions.

  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.

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

The KYC is required only for larger transactions 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.

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.

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

When the data is uploaded, initiate the KYC process.

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.

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

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

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

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.

Last updated