Identity verification with ConnectPay provider

If you do not have an identity verification (IDV) provider or do not have the possibility to manage your client data, you can use the ConnectPay solution for ID verification.

You can find the IDV endpoint here. As a results of this request, we will provide the link. This link will redirect your client to the ConnectPay-branded IDV provider’s page. After verification is done, you will receive a notification about the status.

You can find the ConnectPay supported providers list in the endpoint description.

Use this endpoint to do IDV for private clients or corporate client representatives.

Identity verification with ConnectPay provider steps:

1. Request identify verification redirect link via endpoint POST Initiate IDV session. You can specify UI language value in request as well, if not specified, default value is English. With a successful response, you get a redirect link, ConnectPay created personid, and IDV status. The link provided is valid for 30 days. After this time, a new IDV session needs to be created.
2. With the received link, ask the client to perform identity verification.
3. After successful IDV, the client will be redirected back or to successUrl if provided.
   1. If IDV fails, then the client will be redirected back or to failureUrl if provided.
   2. If IDV is dropped without ending the flow, the client will be redirected back or to dropUrl if provided.
4. The Platform must receive the application status IDV_APPROVED:
   1. via webhook IDV status change notification. You can find information here on how to subscribe to ConnectPay webhooks
   2. or via endpoint GET IDV status
5. If the Platform received the status IDV_DECLINED or IDV_TOKEN_EXPIRED then need to start again from the first step
6. When the Platform has client IDV with the status IDV_APPROVED and ConnectPay created personid that is provided in GET IDV status or IDV status change notification, the Platform needs to provide additional details about the client to open an account. Depending on the client type (private or corporate), the Platform must call POST Initiate personal application or POST Initiate business application.

Possible identity verification statuses

The status of an ID verification may change after manual review. This process can take up to 20 min. To ensure your system reflects the most up-to-date states, it is important to implement webhook notifications to receive real-time status updates. Also, same ID verification event can have 2 webhook notifications. E.g. system automatically approved IDV, so ID status will be IDV_APPROVED, after manual review it is noticed that document/face photo is not acceptable, ID status is changed to IDV_DECLINED. If system response and manual review status are same, then follow-up webhook notification is not sent.

This process does not block application submission, it can be submitted and auto-approved after first IDV_APPROVED status is received. Follow-up IDV_DECLINED notification will create IBAN account block until a person performs another attempt for ID verification. For retry – same Initiate IDV Session API is used with same externalReference.

Supported document types

During IDV verification these document types might be used:

• Passports. This is a default selection for all possible countries.
• ID cards. We support documents issued in EEA only.
• Residence permit. Only Lithuanian issued document is supported.
• Driver license. We support documents issued in EEA and after 2013 Jan 19th (new European format type).

Important! In order to use driver license as acceptable document person.citizenshipCountryCode should be sent in Person onboarding API request. Without this value such identifications will be declined.

IDV Decline Handling & Parameter Requirements

To ensure clear, granular visibility into Identity Verification (IDV) failures, the GET IDV Status API returns detailed decline mapping parameters in the response payload. These fields allow support teams and automated systems to immediately diagnose onboarding friction without manual lookups

Response Fields

• idvDeclineReason (enum): Identifies the exact cause of verification failure.
• idvDeclineDescription (string): A human-readable description explaining the specific decline reason.
• isRetryable (boolean): Indicates whether the issue can be resolved by a user retry (true) or if it requires manual investigation and support escalation (false).

Mapping Reference

The system enforces the following mappings, descriptions, and retry rules: