Banking onramp flow API (temporarily suspended)

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.

2. The customer should be able to obtain a virtual IBAN/BIC (EUR) or Account Number/Sort Code (GBP) 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.

KYC is mandatory and is done by a third-party vendor. XGateway operates as a relayer, doesn't store user data, and only forwards the user information. 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.

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

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.

KYC verification and bank account creation

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.

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.

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

This data will be needed at the very end of the flow.

Creates a bank transfer account for a customer.

post

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.

Authorizations

Path parameters

idstringRequired

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

Body

• Contains customer data for creating a bank account.

lastNamestringOptional

firstNamestringOptional

emailstringOptional

currencystring · enumOptionalPossible values:

countrystringOptional

Responses

201

Created

application/json

400

Database violation

application/json

401

Unauthorized

application/json

409

Conflict

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/customer/{id}/bank-transfer HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 87

{
  "lastName": "text",
  "firstName": "text",
  "email": "text",
  "currency": "EUR",
  "country": "text"
}

{
  "data": {
    "bic": "AAAAAA00",
    "country": "EE",
    "currency": "EUR",
    "iban": "EE000000000000000000",
    "status": "ACTIVE"
  },
  "success": true
}

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.

Country parameter must follow the "ISO 3166-1 Alpha-2" code format.

3KB

SupportedCountriesList - country.csv

List of supported country codes

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

This request actually triggers the KYC verification.

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

post

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.

Authorizations

Path parameters

idstringRequired

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

Body

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

documentany ofOptional

or

sourceOfFundsstring · enumOptionalPossible values:

address2stringOptional

address1stringOptional

citystringOptional

postCodestringOptional

dateOfBirthstring · date-timeOptional

countrystringOptional

Responses

201

KYC verification initiated

application/json

400

Database violation

application/json

401

Unauthorized

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/customer/{id}/bank-transfer/kyc HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 287

{
  "document": {
    "content": "text",
    "type": "PASSPORT",
    "country": "text"
  },
  "selfie": {
    "content": "text",
    "type": "SELFIE",
    "country": "text"
  },
  "sourceOfFunds": "BUSINESS_INCOME",
  "address2": "text",
  "address1": "text",
  "city": "text",
  "postCode": "text",
  "dateOfBirth": "2025-05-09T14:23:56.392Z",
  "country": "text"
}

{
  "data": "KYC verification initiated",
  "success": true
}

Upload content as a JPG or PNG image, converted to a base64 string with no metadata. Ensure the file size is under 500 KB. Contact the team if this limitation is too strict for your application.

179KB

Base64PngExample.doc

Valid PNG image converted to base64 string

When the data is uploaded, initiate the KYC process.

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

post

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.

Authorizations

Path parameters

idstringRequired

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

Responses

204

KYC verification started

application/json

400

Database violation

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/customer/{id}/bank-transfer/kyc/verification HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "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.

patch

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.

Authorizations

Path parameters

idstringRequired

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

Body

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

targetAddressstringOptional

dateOfBirthstring · date-timeOptional

lastNamestringOptional

firstNamestringOptional

emailstringOptional

Responses

204

Action has been accepted

application/json

400

Database violation

application/json

401

Unauthorized

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

patch

HTTPcURLJavaScriptPython

PATCH /api/v2/customer/{id}/bank-transfer HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 222

{
  "address": {
    "city": "text",
    "postCode": "text",
    "addressLine2": "text",
    "addressLine1": "text",
    "country": "text"
  },
  "targetAddress": "text",
  "dateOfBirth": "2025-05-09T14:23:56.392Z",
  "lastName": "text",
  "firstName": "text",
  "email": "text"
}

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

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

put

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.

Authorizations

Path parameters

idstringRequired

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

Body

any ofOptional

• The KYC document details to be uploaded.

or

Responses

204

No Content

application/json

400

Database violation

application/json

401

Unauthorized

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

put

HTTPcURLJavaScriptPython

PUT /api/v2/customer/{id}/bank-transfer/kyc/document HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "documentType": "SELFIE",
  "content": "text",
  "country": "text"
}

{
  "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.

get

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.

Authorizations

Path parameters

idstringRequired

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

Responses

200

Ok

application/json

400

Bad request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal server error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v2/customer/{id}/bank-transfer HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "bic": "AAAAAA00",
      "country": "EE",
      "currency": "EUR",
      "iban": "EE000000000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "CREATED"
    }
  ],
  "success": true
}

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.

get

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.

Authorizations

Path parameters

idstringRequired

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

Responses

200

Ok

application/json

400

Bad request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal server error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v2/customer/{id}/bank-transfer/kyc HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "SOFT_KYC_FAILED",
    "docsMissing": [
      {
        "docType": "PASSPORT"
      },
      {
        "docType": "DRIVERS"
      },
      {
        "docType": "ID_CARD"
      },
      {
        "docType": "RESIDENCE_PERMIT"
      },
      {
        "docType": "SELFIE"
      }
    ],
    "kycEndUserErrorMessage": "Enter your date of birth exactly as it is on your identity document."
  },
  "success": true
}

Creating invoice and enabling a customer to pay

In order to create a fixed rate invoice use this guide.

When an invoice is created, and the KYC is successfully passed, show the customer the banking information received on the first step of this guide as a result of bank account creation. This bank account should be used by the customer to send money to. Every deposit will be followed by a callback from the XGateway to your system.