Flow WebView

Description

Flow Webview is a way to integrate the biometric service into the client-side application using a ready-made solution in the form of a WebView library.

Using this method of integration assumes obtaining a session from the created flow and subsequently redirecting the end user to our server.

Note

Currently, the integration happens entirely on the client-side. As an example, Flutter will be considered here.

Stages:

1. Creating a Flow

The first thing you need to do is to create a Flow in your personal account. To do this, go to this link.

Once the flow has been created it is necessary to use its API KEY in the second step. You can find the API KEY on the list of created flows page .

Simplified example of the table of personal account flows:

Flow name	API KEY	Technologies
Flow for everyone	TTpme201NiUMBA...	LD, F2F
Flow for individuals	Efy202XKbVAWRu...	LD, ED, F2F
Flow for legal entities	UuuH4V1XC-M9je...	LD, DR, F2F

Note

The following examples will use the first flow from the table above: "Flow for everyone".

Also, a shortened API KEY length is used for clarity. Its actual length is 47 characters or more.

2. Session Creation

To work with the service you need to create a session. To do this, you need to send a POST-request to create a session, using the API KEY of the created flow. Read more about sessions here.

Requests to our service use only data in JSON format. Response data from the service will be presented in the same format.

Request URL:

https://kyc.biometric.kz/api/v1/flows/session/create/

Request format	Request method
JSON	POST

API KEY must be passed in the request body:

Field name	Type	Obligatorily	Description
api_key	String	Yes	API KEY of the created flow in the personal cabinet

Request examples:

cURLPythonJavaScriptTypeScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
"api_key": "YOUR_FLOW_API_KEY"
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
  "api_key": "YOUR_FLOW_API_KEY",
})
headers = {
  'Content-Type': 'application/json',
}

response = requests.request(
  "POST",
  url=url,
  headers=headers,
  data=payload,
)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY' // flow api key

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    body: JSON.stringify({
        api_key: apiKey
    })
})
.then(response => response.json())
.then(data => {
    const { session_id, technologies } = data
})

const apiKey: string = 'YOUR_FLOW_API_KEY' // flow api key

interface SessionResponseData {
    session_id: string,
    technologies: string[]
}

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    body: JSON.stringify({
        api_key: apiKey
    })
})
.then(response => response.json())
.then(data => {
    const { session_id, technologies }: SessionResponseData = data
})

The response will be JSON with the following fields:

• session_id - one-time session identifier to pass the flow;
• technologies - an ordered set of flow technologies.

Response example:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LDHP", "F2F"]
}

3. Session Metadata

When creating a flow, certain metadata can be included to facilitate a more flexible and dynamic process, as well as to simplify the verification procedure.

API KEY and metadata must be sent in the request body. The value for metadata is an object that includes an object with the technology name (face2face, edocument) consisting of metadata for the technology.

Field Name	Type	Required	Description
api_key	String	Yes	The API KEY of the created flow in the personal cabinet
metadata		No	Session metadata

Metadata for Face2Face technology:

Field Name	Type	Required	Description
face2face		No	Metadata for Face2Face technology
photo1	String	No	Photo used for matching in base64 format

Metadata for E-Document technology:

Field Name	Type	Required	Description
edocument		No	Metadata for E-Document technology
iin		No	IIN field
phone		No	Subject's phone number field
value	String	No	Field values
changeable	Boolean	No	Ability for the user to change the data
skip_input	Boolean	No	Skip user data input (Move to OTP code input step)

General metadata:

Field Name	Type	Required	Description
general		No	General metadata
interchangeable_tech	Array	No	List of interchangeable technologies

Note

If metadata is absent, the flow will proceed by default.

3.1. Metadata for Face2Face

If a user's face photo is available, it can be included in the session metadata. This helps simplify and shorten the verification process and prevent errors that might occur during user verification. The metadata field must be sent in the request body.

Important to Note

Face2Face technology metadata will only work for the following flows:

• Liveness + Face2Face
• E-Document + Face2Face
• Document Recognition + Face2Face

Field Name	Type	Required	Description
face2face		No	Metadata for Face2Face technology
photo1	String	No	Photo used for matching in base64 format

Request URL:

https://kyc.biometric.kz/api/v1/flows/session/create/

Request Format	Request Method
JSON	POST

Request Examples:

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "face2face": {
            "photo1": "base64"
        }
    }
}'

import requests
import json
import base64

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

with open('path/to/your/image.jpg', 'rb') as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "face2face": {
            "photo1": encoded_image,
        },
    },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY';
const imageFilePath = 'path/to/your/image.jpg'; // Path to your image

const fs = require('fs');
const path = require('path');

const imageBase64 = fs.readFileSync(path.resolve(imageFilePath), { encoding: 'base64' });

const payload = {
    api_key: apiKey,
    metadata: {
        face2face: {
            photo1: imageBase64
        }
    }
};

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
    const { session_id, technologies } = data;
})

The response will be a JSON with the following fields:

• session_id - a one-time session identifier for passing the flow;
• technologies - an ordered set of flow technologies.

Example response:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LDHP", "F2F"]
}

3.2. Metadata for E-Document

If user data such as IIN, phone number, or presence in the Mobile Citizen Database is available, it can be sent to the input form when passing the EDocument technology. This helps simplify and shorten the verification process and prevent errors that might occur during user data entry. The metadata field must be sent in the request body.

Note

The skip_input field defaults to false (the data entry step is not skipped). The changeable field defaults to true (the user can change the data entry field values).

Field Name	Type	Required	Description
edocument		No	Metadata for E-Document technology
iin		No	IIN field
phone		No	Subject's phone number field
value	String	No	Field values
changeable	Boolean	No	Ability for the user to change the data
skip_input	Boolean	No	Skip user data input

Request URL:

https://kyc.biometric.kz/api/v1/flows/session/create/

Request Format	Request Method
JSON	POST

Case №1:

Note

Skipping the user data entry step is only possible if:
1) value for iin and phone is provided
2) changeable for iin and phone is provided with a value of false
3) skip_input is provided with a value of true

The user data entry step will be skipped. The user will be redirected to the OTP code input step from 1414.

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": false,
            },
            "phone": {
                "value": "<subjects_phone>",
                "changeable": false,
            },
            "skip_input": true
        }
    }
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": False,
            },
            "phone": {
                "value": "<subjects_phone>",
                "changeable": False,
            },
            "skip_input": True
        },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

```js const apiKey = 'YOUR_FLOW

_API_KEY'; // Your flow API key const subjectsIIN = '123456789012'; // Example user's IIN const subjectsPhone = '+1234567890'; // Example user's phone number

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: apiKey,
        metadata: {
            edocument: {
                iin: {
                    value: subjectsIIN,
                    changeable: false,
                },
                phone: {
                    value: subjectsPhone,
                    changeable: false,
                },
                skip_input: true
            }
        }
    })
})
    .then(response => response.json())
    .then(data => {
        const { session_id, technologies } = data;
    })
```

Case №2:

At the data entry step, the user will see the values passed in the metadata fields, without the ability to change the IIN.

Note

The default value for changeable is true.
The default value for skip_input is false.

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": false,
            },
            "phone": {
                "value": "<subjects_phone>",
            }
        }
    }
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": False,
            },
            "phone": {
                "value": "<subjects_phone>",
            },
        },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY'; // Your flow API key
const subjectsIIN = '123456789012'; // Example user's IIN
const subjectsPhone = '+1234567890'; // Example user's phone number

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: apiKey,
        metadata: {
            edocument: {
                iin: {
                    value: subjectsIIN,
                    changeable: false,
                },
                phone: {
                    value: subjectsPhone,
                }
            }
        }
    })
})
    .then(response => response.json())
    .then(data => {
        const { session_id, technologies } = data;
    })

Case №3:

At the data entry step, the user will see the values passed in the metadata fields, with the ability to change the IIN and phone number.

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
            },
            "phone": {
                "value": "<subjects_phone>",
            }
        }
    }
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
            },
            "phone": {
                "value": "<subjects_phone>",
            },
        },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY'; // Your flow API key
const subjectsIIN = '123456789012'; // Example user's IIN
const subjectsPhone = '+1234567890'; // Example user's phone number

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: apiKey,
        metadata: {
            edocument: {
                iin: {
                    value: subjectsIIN,
                },
                phone: {
                    value: subjectsPhone,
                }
            }
        }
    })
})
    .then(response => response.json())
    .then(data => {
        const { session_id, technologies } = data;
    })

The response will be a JSON with the following fields:

• session_id - a one-time session identifier for passing the flow;
• technologies - an ordered set of flow technologies.

Example response:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LDHP", "ED", "F2F"]
}

4. Integration into the application

Below is a code snippet for initializing WebView in Flutter. The query parameter web_view=true should be passed into the link.

Example URL: https://remote.biometric.kz/flow/6737a660-208a-401a-a2cf-2b45a326002a?web_view=true

The session 6737a660-208a-401a-a2cf-2b45a326002a is provided here as an example, and in your case, you should pass your own session.

Example code

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: WebViewExample(),
    );
  }
}

class WebViewExample extends StatefulWidget {
  @override
  WebViewExampleState createState() => WebViewExampleState();
}

class WebViewExampleState extends State<WebViewExample> {
  late WebViewController _controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('WebView Example'),
      ),
      body: WebView(
        initialUrl: 'https://remote.biometric.kz/flow/session_id',
        javascriptMode: JavascriptMode.unrestricted,
        onWebViewCreated: (WebViewController webViewController) {
          _controller = webViewController;
        },
        onPageStarted: (String url) {
          // Track the page loading start
          if (url == 'https://remote.biometric.kz/finished') {
            _showFinishedMessage();
          }
        },
      ),
    );
  }

  void _showFinishedMessage() {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('Process finished!'),
      ),
    );
  }
}

After all logic is completed, a redirect will occur inside our web application to the page:

https://remote.biometric.kz/finished

In your application, you should catch this redirect to proceed with your own logic. In the example above, this is implemented using onPageStarted.