MachineSense - KYC/NFC

KYC with NFC: Digital to digital (100% ID-auth)

Introduction
User experience inside the app
Session-init call
Session-init response
Web-hook response

Introduction

Differing from the SCAN-method, where the document is scanned by the camera, the NFC-method is digital-to-digital and includes fully cryptographically verified document authenticity. This is the most secure method of KYC, and it is the only method that can be used for 100% ID-authentication, without worrying about document forgeries.

MachineSense NFC-based KYC is a process where the document is read digitally, by use of NFC technology. Data is verified on several levels (authorization, local hashes and issuing-country certificates), and the results are sent to our customers/partners.

In order to use MachineSense NFC-based KYC, your end-user needs to have a mobile phone with NFC technology and downloaded MachineSense NFC reader app. This app is available for both Android and iOS, and is downloadable from the respective app-stores.

The process is as follows:

You ask your end-user, on your website, to download MachineSense (or white labeled) app.
You start the process by calling session-init (asking for init-code from our server). Init-code received will be 4-digit alphanumeric.
Your end-user types in this init-code when prompted (on the initial app-screen).
User is then guided through all the steps needed for the process (you have control over this process by setting required steps and responses in your partner-account on MachineSense portal).
Data from end-user's id-document is read digitally, checked cryptographically and sent extra encrypted (custom PKI on top of HTTPS) to our servers; it is then verified and sent to you.
Your back-end sends back the confirmation to the MachineSense server that data is received.
MachineSense reader app displays a message that process is finished and (optionally) redirects to a page that you've specified in account settings.

Your users can find MachineSense reader app here:
Reader app on Apple
Reader app on Android
Reader app APK to download directly and try (for testing and development only; need to allow applications from unknown sources on your Android)

Top of the Page

User experience inside the app

As mentioned, end-users can download MachineSense reader app from the app-stores.
However, sometimes you might want to skep the app-stores and provide your users with a direct link to the app. This will, unfortunately, work only in Android, since Apple does not allow direct links to apps. For example, you can provide your employees and/or partners with a privately hosted (native) app, to identify when entering the premises or performing some actions.

However app is obtained, the process within it (user-experience) is quite simple, intuitive and straightforward (and same in both cases):

First app screen asks user to type in the 4-character session-init key. After calling our servers, you display that key to your user, and he/she types it in.
Next screen is the so-called "consent" screen. It is not about accepting consent-documents (although you can and should provide those as well, even before this process has started in the app), but confirming the ownership of the document by typing three key pieces of information: document number, date of birth and expiration date.
This is a very important step, since it is the only way to confirm that the document is in possession of the person who is trying to identify with it.
MachineSense reader app makes this process simpler, easier and quicker for users by allowing the scanning of the MRZ section of the document which, among other data, also contains those three pieces of information. After scanning, this is automatically filled-in.
Next step is the actual reading of the document. User is asked to place the document on the back of the phone, and the reading process starts.
This process is very quick, and it is done in a background process, so that the user can continue to hold the phone in the same position, without any action needed.
User is presented with a progress bar, and after the process is finished, the app automatically moves to the next step.
Last operational step is presenting a message "Please wait while your data is being processed and submitted."
After this, the app automatically redirects to the page that you've specified in your account settings (or in the call to our API, if you've specified it there).
If "success/failure/redirect" page was not specified, the app will display a message "Thank you for using our services. Please return to the website where you started the process."
Redirection or messages will appear only after receiving OK from your server after the webhook call.

Session-init Call

(Call from your server to our API.)

When you know that your end-user has downloaded the mobile app from a store, you may initiate the KYC process by calling our API. This is done by sending a POST request to our API server, with the following parameters:

POST nfc/v1/session_init

Parameters / body:

            {
               "api_key": "string",
               "ref": "string",
               "method": "enroll",
               "send_scan": [array of strings], 
               "options": {
                     "force_mrz_consent": false,
                     "num_images_liveness": int,
                     "webhook": URL, 
                     "redirect_URL": URL
               }
            }

Parameters explained:

"api_key" = (mandatory) Your developer key found in your Settings
"ref" = (optional, default="") Any string you wish to send back to yourself, that you will receive with the later response to your webhook.
"method" = (mandatory) MachineSense method required. Can be one of [enum list]
"send_scan" = (optional, default=[]) If you wish to receive also scans/images (in b64 format). Possible values are:
- Empty array or unspecified = no scans / images
- "selfie" = selfie image
- "docface" = document face image
"options" (optional, overriding settings on your account-admin for NFC reading)

"force_mrz_consent" = (optional, default=false) If true, user might be asked to type in the consent data (which can also be found on MRZ) if, for example, scanning of MRZ has failed to provide correct consent data. If false, user will always be asked to scan the MRZ until consent-data read successfully.
"num_images_liveness" = (optional, default=1) Number of images to be taken for liveness detection. Does not require any action from the end-user, images are taken in a background process.
"webhook" = (optional) If you wish to override the default webhook result-return URL that you've specified in your account settings (in format: https://example.org/mywebhook).
"redirect_URL" = (optional) If you wish to override the default redirect URL that you've specified in your account settings (in format: https://example.org/myredirect).

Top of the Page

Session-init Response

After calling Session-init, you will get this response, with the Init-Code that you should present to your end-user on your web-site or other place where you are initiating the KYC process.

Code: 200

Default response:

            {
               "result": "Ok",
               "code": 0,
               "message": "string",
               "data": {
                  "init_code": "string"
               }
            }

Response explained:

"result" = "Ok" or "Err" (error)
"code" = 0 or error code (int)
"message" = If result "Err" - textual description (string)
"data" = JSON object with data

"init_code" = 4-character init-code to be presented to the end-user. Example: "E4zY".

Top of the Page

Web-hook Response

After processing the data from NFC-source (ID-document), sending it from MachineSense mobile reader app and verifying on MachineSense servers, you will receive a webhook response on the URL that you've specified in your account settings (and that you can override by sending "webhook" parameter in Session-init call).

Code: 200

Default response:

            {
               "result": "Ok",
               "code": 0,
               "message": "string",
               "ref": "string",
               "data": {
                  "name": "string",
                  "nationality": "string",
                  "document_number": "string",
                  "document_type": "string",
                  "date_of_birth": "string",
                  (...)
               }
               "face_match": float,
               "face_match_confidence": float,
               "liveness_confidence": float,
               "liveness_confidence_array": [Array of floats],
               "doc_face_image": "string",
               "doc_face_vector": [Array of numbers],
               "selfie_image": "string",
               "selfie_vector": [Array of numbers]
            }

Response explained:

"result" = "Ok" or "Err" (error)
"code" = 0 or error code (int)
"message" = If result "Err" - textual description (string). Errors here can be of several types: "Document not supported", "Session expired", "Document reported lost or stolen", "Invalid or tampered data", etc.
"ref" = If you've sent "ref" parameter in Session-init call, you will receive it back here.
"data" = JSON object with data from the document. All the data that could be found and verified, including person's name, date of birth, document type, document number, document expiration date, etc. For details on possible data-entries, please consult the ICAO 9303 document. The International Civil Aviation Organization (ICAO) is a United Nations agency that is standardizing use of travel- and other id-documents.
"face_match" = Biometric distance between face on the document-photo and selfie. Value between 0 and 1. Smaller the value, greater the match.
"face_match_confidence" = Confidence of the face match. Value between 0 and 100 (percentage). Larger the value, greater the match.
"liveness_confidence" = Confidence of the liveness detection. Value between 0 and 100 (percentage). Larger the value, more likely it's a real person.
"liveness_confidence_array" = Array of confidence values for each of the images taken for liveness detection. You can take either the average of these values, or the lowest value (which is the most conservative approach) or the highest value (which is the most relaxed).
"doc_face_image" = If you've sent "send_scan" parameter in Session-init call, and specified (among other)"docface".
"doc_face_vector" = Enrolment (biometric) vector from the document face image. Comes as an array of numbers representing facial characteristics.
"selfie_image" = If you've sent "send_scan" parameter in Session-init call, and specified (among other) "selfie".
"selfie_vector" = Enrolment (biometric) vector from the selfie image. Comes as an array of numbers representing facial characteristics.

Top of the Page

Web-hook Confirmation

After receiving the webhook response, you should send back a confirmation to our servers that you've received the data. This is done by sending a POST request to our API server, with the following parameters:

POST nfc/v1/webhook_confirmation

Parameters / body:

            {
               "api_key": "string",
               "init_code": "string",
               "recv": "OK"
            }

Parameters explained:

"api_key" = (mandatory) Your developer key found in your Settings
"init_code" = (mandatory) Init-code that you've received in the Init-Call.
"recv" = (mandatory) "OK" or "ERR". If "OK", it means you received the data OK, that the process is finished and the app will either redirect to your specified URL or display a message
If "ERR", the app will display a message "There was an error in the process. Please return to the website where you started the process and follow further instructions."
If you don't send this confirmation, the app will wait for timeout (specified in your account settings) and after expiry display the message "There was an error in the process. Please return to the website where you started the process and follow further instructions."