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:

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
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
Long term
- If your system stores the bank details of customers received from XGateway, please make sure to properly process KYC status reversal, which may happen.

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 OR 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 processing
`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#

Prefer callbacks over polling; they are signed and retried. For high-risk operations, confirm state via API (see the risks and details on the Callbacks Handling page). API responses are the source of truth.

To confirm the callback is valid, please use the API endpoint.

Testing SEPA Secure deposits on Demo environment#

Check testing SEPA secure deposits page for ways to test the integration.