SEPA Secure payments using host-to-host

The host-to-host communication allows a merchant to send all the data needed for a KYC of a customer in the background. The customer will not be required to fill in data or manually send proof of identity or proof of address. This flow has the best conversion rate.

Step 1 needs to be finished only once and only if SumSub token sharing is not implemented.

High-Level Flow

The host-to-host flow for a customer includes the following steps:

1. Pass KYC for a customer

• Step 1: Create SEPA Secure user account

• Step 2: Create KYC applicant

Wait till the applicant is created. Average response time for this API is 15 seconds. To check if step completed you must poll the user status API or wait for a KYC callback.

• Step 3. Upload KYC documents

• Step 4. KYC verification

Wait for KYC to be passed. Final successful status: FULL_USER. In rare cases the process may take several minutes. To check if step completed you must poll the user status API or wait for a KYC callback.

• Step 5 (Optional). Patch data for a SOFT_KYC_FAILED case

1. After KYC Is Passed

• Step 1. Get the customer bank details via API

• Step 2 (Optional). Create an invoice for a user. (An invoice allows to pass additional parameters to track specific payment request. You can also use the invoice checkout link to display payment details in our UI)

• Step 3. Process a callback on every deposit

Important Integration rules

• Ensure to check customer status before creating an invoice.

• Control the result of each KYC API request. If one request fails, all subsequent requests will also fail.

• KYC must be passed only once. After completing KYC (reaching FULL USER status) do not trigger KYC endpoints before every deposit.

KYC status explanation

KYC Status	Meaning	Required Action
null	User not created	Create user
CREATED	User created, no applicant	Create applicant
PENDING_KYC_DATA	Awaiting KYC data	Upload documents & Trigger verification
KYC_PENDING	Verification in progress/ Awaiting KYC data	Wait/ Can require actions if specific message returns in callback details
SOFT_KYC_FAILED	Non-critical failure	Patch data
HARD_KYC_FAILED	Critical failure	Stop process, address to support
FULL_USER	KYC completed	Continue with deposit / Create invoice

KYC Processing status explanation

The kycProcessingStatus field helps you understand which API request is currently being processed (integration-level state) and allows to handle the integration flow more smoothly on your side.

Possible processing statuses:

• null = No active request. The next request can be initiated.

• USER_CREATION_IN_PROGRESS

• APPLICANT_CREATION_IN_PROGRESS

• DOCUMENT_UPLOAD_IN_PROGRESS

• VERIFICATION_IN_PROGRESS

Confirming a transaction

Due to security risks, merchants must use our API endpoint 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 API endpoint.

Testing SEPA Secure deposits on Demo environment

Check this page for ways to test the integration.