KYC Netheos

The provider used by Xpollens is Netheos. This documentation is available here: https://integration-api.ekeynox.net/docs/integration/latest/en/intro/

KYC Workflow

KYC Status definition

The KYC status represents the progress of the user's KYC. This status includes the state of progress on all due diligences.

KYC State Diagram

KYC Sequence diagram

Note
Wokflow parameterization has to be made upstream during the environment parameterization. Partner choice is then taken into account by XPollens for global workflow parameterization. The XPollens recommandations by order of preference are as follow :

1- Electronic signature + Identity (in fallback)
2- Electronic signature alone (in this case the user has no choice but to use the selfie)
3- Identity alone (not recommended)

Note
⚠ XPollens recommend to use the Identity workflow only in fallback when the user is not able to complete the Electronic signature workflow

Remark
Steps 6 and 7 are optionnal and depends on partner implementation

APIs, callbacks and technical items

`POST /api/v3.0/user/{appUserId}/kyc/demand`

Description

This API is dedicated to the new KYC solution. It enables the creation of the KYC demand with a specific workflow.

Prerequisite

Prerequisites to call this endpoint are :

User must exist.
KYC demand doesn't exit.

Body parameter

{
  "workflowCode": "string"
}

Parameters

Name	In	Type	Required	Description
appUserId	path	string	true	User identifier of partner Format Min 9 characters, max 30 characters Accepted characters 0-9 a-z A-Z_-.!() Example ABCDEFGHI or A1B2C3d4f5g678901234567890123
CorrId	header	string	false	Correlation Id
body	body	CreateKycDemand	true	Information needed to provided

Example responses 400 Response
{
  "message": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	None
400	Bad Request	Bad Request : - The appUserId field is required. - The WorkflowCode field is required. - The User's KYC demand already exists - WorkflowCode does not exist in referential	ErrorResponse
404	Not Found	Not Found	ErrorResponse
405	Method Not Allowed	Operation not allowed	ErrorResponse
500	Internal Server Error	Server Error	ErrorResponse

Schemas

CreateKycDemand

{
  "workflowCode": "string"
}

Properties

Name	Type	Required	Restrictions	Description
workflowCode	string	true	none	workflowCode Worflow of the KYC process. Possible values: - Electronic_Sign - Identity

ErrorResponse

{
  "message": "string"
}

Error Properties

Name	Type	Required	Restrictions	Description
message	string	true	none	none

`GET /api/v2.0/users/{appUserId}/kyc/demand`

Description

This API retrieves the KYC demand that contains the KYC diligences received and their status.

Prerequisite

The KYC demand must exists.

Callback type 4 - `#04 - KYC demand`

Description

Callback received in case of status change in the KYC demand

Workflow change

During user onboarding it is possible for the user to switch from the Electronic_Signature workflow to the Identity workflow (this way only, it is not possible to switch from Identity to Electronic_Signature). This is possible as long as the user has not completed the Selfie+ID step in the Electronic_Signature workflow. To handle the switch of workflow, partner should call the PUT /api/v3.0/users/{appUserId}/kyc/demand by specifying the new workflow in the payload.

Exemple

PATCH /api/v3.0/users/{appUserId}/kyc/demand
{
     "workflowCode" : "Identity"
}

Conversely, it is impossible to switch from the Identity workflow to the Electronic_Signature workflow.

Due diligence Workflow

Due Diligence types

For the Electronic_Signature workflow, the due diligences expected are :

1- Identity document & selfie
2- Electronic signature

For the Identity workflow, the due diligences expected are :

1- Identity document
2- Sepa Credit Transfer IN (this sepa transfer could be an instant payment, a standard one)

For these two workflows, when configuring your environment, you can choose to accept one or more of the following forms of identification:

ID card
passport
resident permit

Identity checks are subject to SLAs: 5 minutes maximum in 90% of cases.

Due Diligence state diagram

Diligence Status (webview mode):

Diligence Status (API mode):

Each time the status of a due diligence changes, a callback 4 is sent.

Due Diligence sequence diagram : case electronic_sign

Best scenario: due diligences validated

Note
The strong authentification code expires after 10 minutes. A second SMS is sent after the first expires.

Due Diligence sequence diagram : case identity

Two important pieces of information about workflow:

the identity document can be sent either via the webview or the API
the cgu must be signed by API

Best scenario: due diligences validated

Due Diligence SCT IN

The minimum and maximum amount of the Sepa Credit Transfer (as a diligence) is set when the environment is created. Usally, the minimum amout is 1€ and the maximum amount 1000€.

In order to be accepted, the issuer of the SCT must be the same person as the account holder. To achieve this, the account from which the transfer is made must be in the customer's first and last name. Depending on the degree of consistency between the two names, the stagecoach may be validated, manually reviewed by an operator or rejected.

This due diligence process takes much longer, with the SCT taking around 2 working days to be transmitted from the issuing bank to Xpollens.

Due Diligence sequence diagram : refused

Due diligence ID refused : issue during the identity document checks

The WebViewUrl remains the same for the next attempt(s).

KO quality
Poor quality of document
Document badly framed
Missing document page
Expired document
Restricted country
Document type not allowed
Poor quality of biometry

Error when providing an identity document via API. (Workflow: Identity)
Document is too large
The document is empty
The lines of the MRZ (identity documents) are not valid.
The document could not be read (corrupted file)
Image is too blurry
Image is not contrasted enough
Image is too small (does not contain enough pixels)
The image is too big (contains too many pixels)
Processed image is binarised, but the server does not accept them
The font of the text in an image is too small to be read.
The document received does not match the expected one.
The type of document received is not recognized.
The image processing system did not respond.
No text found in the document
Participant's name not found in document
The date of the document was not found.
The document is too old.
The country of issue of the document is not allowed.
The document has expired.
MRZ lines not found in the identity document
The first name of the MRZ does not match the name on the face of the identity document.
Document number of the ZRM does not match the number on the face of the identity document
The date of birth of the MRZ does not match the date of birth on the face of the identity
Document expiry date could not be read (only for identity documents)
The same file has already been submitted: same participant and same file or same type of document requested and same data read
Expiration date is not consistent with the MRZ

Due diligence ID refused: inconsistency between the data declared and the data on the identity document

Use the PUT /api/v2.0/users/{appUserId} to modify the wrong data.

Error codes

Inconsistency between the data declared and the information on the identity document
Inconsistent birthDate between ID document and user’s information
Inconsistent fullName between ID document and user’s information
Inconsistent birthName between ID document and user’s information
Inconsistent lastName between ID document and user’s information
Inconsistent firstName between ID document and user’s information
Data inversion: birthName and lastName
Inconsistent civility between ID document and user’s information
Data inversion: firstName and lastName

Due diligence ID refused: diligence type undefined

In some cases, the Netheos robot is unable to recognise the type of identity document sent to it (e.g. the user sends an image containing the front and back of their identity document). The diligence status changes to "refused", and callback 4 is sent as follows:

{
    "Payload": {
        "type": "4",
        "status": "Incomplete",
        "appUserId": "68968-1694163949661",
        "kycLevel": "High",
        "workflowCode": "Electronic_Sign",
        "receivedDiligences": [
            {
                "diligenceType": "UNDEFINED",
                "status": "Refused",
                "attachments": [
                    {
                        "FileName": "name1.jpg",
                        "AttachmentKey": "xxx"
                    },
                    {
                        "FileName": "name2.jpg",
                        "AttachmentKey": "yyy"
                    }
                ]
            },
            {
                "diligenceType": "SELFIE",
                "status": "Refused",
                "attachments": [
                    {
                        "FileName": "name3.jpg",
                        "AttachmentKey": "zzz"
                    }
                ]
            }
        ],
        "expectedDiligences": [
            {
                "type": "Identity",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "ID_CARD",
                    "PASSPORT",
                    "RES_CARD"
                ]
            },
            {
                "type": "Complementary",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "SCTIN",
                    "DELEGATED_COMPLEMENTARY_DILIGENCE",
                    "ESIGN"
                ]
            }
        ]
    },
}

Due diligence SCT IN refused: inconsistency between the data declared and the data on the identity document

Error
The beneficiary's name is different from the transmitter's name

Fraud suspicion

APIs, callbacks & technical items

WebView integration

Parent Page integration (mandatory)

The Netheos Web Page can be displayed using the webviewUrl or url?token=token URL. But as the partner will have to handle some specific javascript event, it is mandatory to implement the following code in the parent page to display the URL :

<iframe id="signbook" scrolling="no" frameBorder="no" width="100%" allow="microphone; camera"></iframe>
<script src="https://integration-api.ekeynox.net/contract/signbook/v3/script/signbook.js"></script>
<script type="text/javascript">
    window.onload = function () {
        var signbook = new NthSignbook({
            iframeSelectorId: 'signbook',
            url: 'https://api.ekeynox.net/contract/signbook/signbook.html',
            options: {
                renderMode: 'pretty'
            },
            token: '20140917_7HJOLUbtlKET2iQwBGtN7QkkzFgg2r'
        });
    }
</script>

Note See the full Netheos Documentation here : https://integration-api.ekeynox.net/docs/integration/latest/integration_signbook_v3/

Javascript Events handling

Identity check events

When identity check is completed (10 min max), an "identity" type event will be sent to the main page.

Exemple :

event = {
   type: "identity",
   state: "WAITING",
   ok: true
}

This event should be handled as in the exemple below :

window.addEventListener('message', function(evt){
    var msg = JSON.parse(evt.data);
    if (msg && msg.type === 'identity') {
        console.log('message: ',msg);
    }
}, false);

Electronic Signature Event handling

The same way, once an electronic signature is performed, a clientFileEvent will be sent with accepted status.

Upload ID document by API

The Identity workflow can also be processed by API. It will require to send the ID Documents using the post /api/v2.0/users/{appUserId}/kyc/attachments API.

Note In this case, it is not neccessary to handle the webview URL provided in callback 48.

Note 2 Ìdentity workflow requires an addionnal identity verification diligence. The additionnal diligence supported by XPollens in an incoming money transfer originating from an account owned by the user (name, firstname, .. are checked at the receipt of the money transfer by XPollens)

Callbacks type 4

Each time the status of a due diligence changes, a callback 4 is sent. This callback is composed of expectedDiligences and receivedDiligences, so you can see the progress of the items sent.

KYC Status Pending, no due diligence sent

Body parameter

        "type": "4",
        "status": "Pending",
        "appUserId": "appUserId-1",
        "kycLevel": "High",
        "workflowCode": "Electronic_Sign",
        "expectedDiligences": [
            {
                "type": "Identity",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "ID_CARD",
                    "PASSPORT",
                    "RES_CARD"
                ]
            },
            {
                "type": "Complementary",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "SCTIN",
                    "DELEGATED_COMPLEMENTARY_DILIGENCE",
                    "ESIGN"
                ]
            }
        ]

Note possibleDiligenceSubTypes as expectedDiligences depend on the environment parameterization.

KYC Status "Incomplete", the identity document and the selfie have been sent

Body parameter

        "type": "4",
        "status": "Incomplete",
        "appUserId": "appUserId-1",
        "kycLevel": "High",
        "workflowCode": "Electronic_Sign",
        "receivedDiligences": [
            {
                "diligenceType": "ID_CARD",
                "status": "To_Review_Manually",
                "attachments": [
                    {
                        "FileName": "ID_CARD_FRONTSIDE",
                        "AttachmentKey": "d84c3525-d037-4e81-8b95-668c4de2340f"
                    },
                    {
                        "FileName": "ID_CARD_BACKSIDE",
                        "AttachmentKey": "96306caa-cc48-4aa4-8403-6055d92b629f"
                    },
                ]
            },
            {
                "diligenceType": "SELFIE",
                "status": "To_Review_Manually",
                "attachments": [
                    {
                        "FileName": "SELFIE_1",
                        "AttachmentKey": "dc840307-de7d-419b-b05d-222bda4ec0d4"
                    },
                ]
            }
        ],
                "expectedDiligences": [
            {
                "type": "Complementary",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "SCTIN",
                    "DELEGATED_COMPLEMENTARY_DILIGENCE",
                    "ESIGN"
                ]
            }
        ]
    },

KYC Status "Complete", all due diligences are validated

When all due diligence has been completed, the KYC status changes to "Completed".

"Payload": {
        "type": "4",
        "status": "Complete",
        "appUserId": "appUserId-1",
        "diligences": [
            {
                "reason": "",
                "diligenceType": "ID_CARD",
                "status": "Validated"
            },
            {
                "reason": null,
                "diligenceType": "SELFIE",
                "status": "Validated"
            },
            {
                "reason": null,
                "diligenceType": "ESIGN",
                "status": "Validated"
            }
        ]
    },

KYC Status "Refused"

The identity document status and the selfie status are not always the same. The identity document is checked in several stages:

the data on the post kyc/demand and the card are automatically checked. If an error occurs here, the status of the ID document is changed to refused, regardless of the selfie.
automatically, checks are carried out on the quality of the document, the legibility of the photo, etc.
manually, an operator completes the check. If a refusal occurs during these last two phases, the status of the stagecoach will be identical.

Each time a diligence is refused, a reason is added to the callback.

  "Payload": {
        "type": "4",
        "status": "Incomplete",
        "appUserId": "appUserId-1",
        "kycLevel": "High",
        "workflowCode": "Electronic_Sign",
        "receivedDiligences": [
            {
                "reason": "",
                "diligenceType": "ID_CARD",
                "status": "Refused",
                "attachments": [
                    {
                        "FileName": "ID_CARD_FRONTSIDE",
                        "AttachmentKey": "d84c3525-d037-4e81-8b95-668c4de2340f"
                    },
                    {
                        "FileName": "ID_CARD_BACKSIDE",
                        "AttachmentKey": "96306caa-cc48-4aa4-8403-6055d92b629f"
                    },
                ]
            },
            {
                "diligenceType": "SELFIE",
                "status": "Validated",
                "attachments": [
                    {
                        "FileName": "SELFIE_1",
                        "AttachmentKey": "dc840307-de7d-419b-b05d-222bda4ec0d4"
                    }
                ]
            }
        ],
      "expectedDiligences": [
            {
                "type": "Identity",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "ID_CARD",
                    "PASSPORT",
                    "RES_CARD"
                ]
            },
            {
                "type": "Complementary",
                "expectedCount": 1,
                "possibleDiligenceSubTypes": [
                    "ESIGN"
                ]
            }
        ]
    },

Callback 48 - WebView URL

The new callback 48 will contain required information to display the KYC Web View URL to the user. The format of the new callback is the following :

POST /{callback48Url}

Remark
The webviewUrl is the concatenation of the url value and token value with the following format: url?token= token
The WebViewUrl contained if the callback #35 is deprecated.

FAQ

FAQ1: Is the webview display customisable?

R: Partially: https://integration-api.ekeynox.net/docs/integration/latest/integration_signbook_v3/#parametrage-de-lapparence-du-facematch-video

FAQ2: Do I have to send the second and third first names?

R: Yes, separated by spaces.

FAQ3: Are all telephone numbers accepted?

R: Yes, provided that the operator is not blacklisted.

FAQ4: when can I display my customer's iban?

R: The iban should only be displayed:

as part of the Eletronic-sign workflow, the user is validated (userRecordStatus validated).
as part of the Identity workflow, the identity check part is validated.

How to test

This annexe describes available mocks on test environment for test and integrate the KYC functionnality. Each mocked test case is based on the provided email adress for the user :

Radical.email+alias_code+autre_alias@email.fr

Alias allows the partner to simulate one or more behaviour. Alias ordering is not relevant At the minimum, the alias for the live check must be present.

Available mocks

Alias	Decription
LC_ACCEPTED	Accepted Live Check
LC_FRAUD	Rejected Live Check / Reason code "Fraud Suspicion"
LC_EXPIRED	Rejected Live Check / Reason code "Other reason"
LC_DOC_EXPIRED	Rejected Live Check / Reason Code : "Expired Document"
LC_DOC_QUALITY	Rejected Live Check / Reason Code : "Document Quality is insufficient"
LC_BIO_QUALITY	Rejected Live Check / Reason Code : "Liveness Quality is insufficient"
LC_DOC_RECEIPT	Rejected Live Check / Reason Code : "Présence du récépissé seul"
LC_DOC_MISSING	Rejected Live Check / Reason Code : "Recto or Verso of id document is missing"
LC_DOC_FRAMED	Rejected Live Check / Reason Code : "Truncated Document"
LC_DOC_UNSUPPORTED	Rejected Live Check / Reason Code : "Not supported Document"
LC_DOC_UNAUTHORIZED	Rejected Live Check / Reason Code : "Document country not supported"
LC_OTHER	Rejected Live Check / Reason Code : "Other reason"

KYC Netheos

KYC Workflow​

KYC Status definition​

KYC State Diagram​

KYC Sequence diagram​

APIs, callbacks and technical items​

POST /api/v3.0/user/{appUserId}/kyc/demand​

GET /api/v2.0/users/{appUserId}/kyc/demand​

Callback type 4 - #04 - KYC demand​

Workflow change​

Due diligence Workflow​

Due Diligence types​

Due Diligence state diagram​

Diligence Status (webview mode):​

Diligence Status (API mode):​

Due Diligence sequence diagram : case electronic_sign​

Best scenario: due diligences validated​

Due Diligence sequence diagram : case identity​

Best scenario: due diligences validated​

Due Diligence SCT IN​

Due Diligence sequence diagram : refused​

Due diligence ID refused : issue during the identity document checks​

Due diligence ID refused: inconsistency between the data declared and the data on the identity document​

Due diligence ID refused: diligence type undefined​

Due diligence SCT IN refused: inconsistency between the data declared and the data on the identity document​

Fraud suspicion​

APIs, callbacks & technical items​

WebView integration​

Parent Page integration (mandatory)​

Javascript Events handling​

Identity check events​

Electronic Signature Event handling​

Upload ID document by API​

Callbacks type 4​

KYC Status Pending, no due diligence sent​

KYC Status "Incomplete", the identity document and the selfie have been sent​

KYC Status "Complete", all due diligences are validated​

KYC Status "Refused"​

Callback 48 - WebView URL​

FAQ​

FAQ1: Is the webview display customisable?​

FAQ2: Do I have to send the second and third first names?​

FAQ3: Are all telephone numbers accepted?​

FAQ4: when can I display my customer's iban?​

How to test​

Available mocks​

KYC Workflow

KYC Status definition

KYC State Diagram

KYC Sequence diagram

APIs, callbacks and technical items

`POST /api/v3.0/user/{appUserId}/kyc/demand`

`GET /api/v2.0/users/{appUserId}/kyc/demand`

Callback type 4 - `#04 - KYC demand`

Workflow change

Due diligence Workflow

Due Diligence types

Due Diligence state diagram

Diligence Status (webview mode):

Diligence Status (API mode):

Due Diligence sequence diagram : case electronic_sign

Best scenario: due diligences validated

Due Diligence sequence diagram : case identity

Best scenario: due diligences validated

Due Diligence SCT IN

Due Diligence sequence diagram : refused

Due diligence ID refused : issue during the identity document checks

Due diligence ID refused: inconsistency between the data declared and the data on the identity document

Due diligence ID refused: diligence type undefined

Due diligence SCT IN refused: inconsistency between the data declared and the data on the identity document

Fraud suspicion

APIs, callbacks & technical items

WebView integration

Parent Page integration (mandatory)

Javascript Events handling

Identity check events

Electronic Signature Event handling

Upload ID document by API

Callbacks type 4

KYC Status Pending, no due diligence sent

KYC Status "Incomplete", the identity document and the selfie have been sent

KYC Status "Complete", all due diligences are validated

KYC Status "Refused"

Callback 48 - WebView URL

FAQ

FAQ1: Is the webview display customisable?

FAQ2: Do I have to send the second and third first names?

FAQ3: Are all telephone numbers accepted?

FAQ4: when can I display my customer's iban?

How to test

Available mocks