🛠️
Integration Guide
  • 🔎Overview
    • 👋Welcome to XGateway
      • Integrate with XGateway
      • Supported currencies
      • KYC
  • ⚙️Integration Guides
    • Crypto Payments using Checkout
    • SEPA Secure payments using Checkout
    • Alternative Payment Methods using Checkout
    • Crypto Payments using API
    • Advanced features of Invoice creation
  • ❔Miscellaneous
    • Keys and authentication
    • Check transaction status
    • Environments
    • Invoice currencies
    • Deposit data confirmation
    • Callbacks
      • Transaction callback
      • Bank Account callback
      • KYC callback
    • Withdrawal initiation with API
    • Disputes resolution
  • 💱Payment flows
    • Transaction flowchart
    • KYC checks diagram
    • Confirmation subprocess
    • User flow for Crypto Payments
    • User flow for SEPA Secure
    • Fees structure
      • Adjustable BTC Minimum Deposit Fee Framework
  • 🏤Back office
Powered by GitBook
On this page
  • Creating an invoice
  • Limits
  • Processing a callback
  • Confirming a transaction
  • Testing SEPA Secure deposits on Demo environment
  • Improving the conversion rate of bank transfers
  1. Integration Guides

SEPA Secure payments using Checkout

PreviousCrypto Payments using CheckoutNextAlternative Payment Methods using Checkout

Last updated 6 days ago

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

XGateway supports deposits with preliminary creation of with a fixed exchange rate. This is the recommended integration form, which providers merchants with ready-made UI for deposits with crypto assets.

Creating an invoice

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

The XGateway provides one , which automatically defines a corresponding payment method based on the input parameters provided by the merchant. Below are examples of a payload to create an invoice for a SEPA Secure deposit in such currencies as EUR or GBP.

he system will skip all XGateway intermediate pages and redirect the customer directly to the payment method, but only if all required data is provided. Integration can be implemented and tested with the mandatory fields alone; however, it is highly recommended to proceed with pre-filled forms, as this can dramatically simplify the flow for the end user and improve conversion. Please don't forget to check the and the guide on conversion optimisation down below.

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": "john.doe@gmail.com",
    "customerCountry": "AU"
}

The request returns a link to a correspondingly configured Checkout page.

The Checkout page will lead the customer through a KYC if this is the first deposit.

If the KYC is soft failed (example due to address or DoB mismatch), the Checkout page will allow the customer to go through the KYC again and correct the error.

This Checkout page will eventually provide the customer with a virtual bank account number (IBAN) that must be used as an address for deposits.

The created IBAN remains active forever, considering the customer is active. If the IBAN was not used at all or was used long time ago (3 to 6 months ago) - XGateway team may deactivate the IBAN.

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

The default lifetime of an invoice is 15 minutes.

Limits

The invoice creation API validates the amount value.

An invoice will not be created, if the amount exceeds the limits.

Invoice limits
Currency
Min value
Max value

EUR

1

-

GBP

1

-

USD

1

-

Processing a callback

{
   "callbackType":"transaction",
   "amount":"200",
   "applicationId":null,
   "currency":"EUR",
   "customerId":"000394",
   "hash":"...",
   "id":"7e71d132-d80d-4140-8e60-9c89d0bd9eed",
   "invoiceId":"184e9933-1526-...-fe567091b5bd",
   "network":"tron",
   "orderId":null,
   "status":"confirmed",
   "transactionHash":null,
   "type":"deposit",
   "info":{
      "exchangeRate":"1.03759",
      "referenceAmount":"207.52",
      "referenceCurrency":"USD",
      "referenceExchangeRate":"1.000065",
      "transactionAmount":"207.51518",
      "transactionCurrency":"tUSDT"
   },
   "fees":{
      "processing":"7.263031",
      "technical":null
   },
   "eur":"200.12",
   "usd":"207.52"
}

Confirming a transaction

Testing SEPA Secure deposits on Demo environment

Test instructions

For a new customer:

  1. Create an invoice

  2. Go through usual flow including SumSub KYC

    1. Make sure to input proper KYC data, that matches with the proof of address

    2. Use the attached passport and proof of address photos (it is possible to use other test or real data too)

  3. Wait till the KYC is passed

  4. Make a POST request to /customer/{id}/bank-transfer/simulate

    1. See example of the curl request

  5. Wait for a callback (may be delayed for some minutes)

For an existing customer with FULL_USER status (KYC is passed successfully):

  1. Create an invoice (optional)

  2. Make a POST request to /customer/{id}/bank-transfer/simulate

    1. See example of the curl request

  3. Wait for a callback (may be delayed for some minutes)

Example of the POST call that should be made to simulate a deposit.

This API endpoint is only available on the sandbox environment and can not be used in production.

curl --location 'https://api.demo.xgateway.tech/api/v2/customer/test-prod202517/bank-transfer/simulate' \
--header 'Accept: application/json' \
--header 'x-api-key: ae304c01-f2fb-4d7f-aed6-0843b235ce9b' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "100",
    "currency": "EUR"
}'

Test data

Improving the conversion rate of bank transfers

Improving the conversion rate of bank transfers

Default flow

The standard bank transfer deposit flow includes four key steps:

  1. KYC Form – The customer enters personal details like address, country, city, and postcode.

  2. KYC Verification (SumSub Widget) – The customer uploads proof of address and identity.

  3. Bank Account Creation Form – The customer provides their first name, last name, email, and other details to create a bank account.

  4. Requisites Page – The IBAN is displayed to the customer.

Steps 1 and 2 are always required and must be completed via our checkout page before a bank account can be created. Step 3 is optional though.

  • Experience:

    • 4 steps for first invoice setup

    • 2 steps for recurring payments

  • Impact: Slower onboarding and more friction for returning users

Optimised Flow with Optional Fields

While the base Invoice creation flow only requires mandatory fields, including the following optional fields during invoice creation can significantly streamline the user experience:

  • paymentCurrency

  • customerCountry

  • customerFirstName

  • customerLastName

  • customerEmail

These values are usually already known when generating an invoice. Supplying them upfront allows the customer to skip the bank account creation form entirely (Step 3).

  • Experience:

    • 3 steps for first invoice setup

    • Direct redirection (1 step) to Requisites page for recurring payments

  • Impact: Seamless user journey and faster payment completion

When a customer makes a deposit using a cryptocurrency, XGateway detects the transaction and sends a deposit callback to the merchant. Below is an example of such a callback. For detailed information, please visit.

Due to security risks, merchants must use our to request transaction details. XGateway is not liable for issues caused by relying only on callback data.

To confirm the callback is valid, please use the .

You can test direct crypto deposits in the.

⚙️
this page
API endpoint
API endpoint
demo environment
this
API endpoint
pre-population section
invoices
286KB
passport.jpg
image
288KB
proofAddress.jpg
image
288KB
62349849-poa-krause-green.jpg
image
Comparison of flows with incomplete customer information and fully filled customer data.