Introduction

There is reference for PC eKYC Connector.
The connector is a part of PC Platform and allows to process on-boarding for your Application with photos and videos provided by a User.

In usual case only mobile app communicates with PC eKYC Connector and provides all of the data for analysis and KYC process.
All of required methods to interact with PC eKYC Connector are included in PC Mobile SDK, class PCRemodeId.

Application back-end interacts with PC eKYC Connector to receive and approve/decline KYC results, e.g. User's information collected by Connector. Based on those results, the Application creates user's account.

General flow description

Principles

eKYC process means user's remote identification, based on data collected with mobile application.

In general, it looks like following:

A user collects data about himself:
- 1 short video for liveness detection
- ID document photo (in the case of RF maindoc this is double-page spread of the 2nd and 3rd pages)
PC eKYC Connector makes a set of analyses:
- checks if there is alive user (not a photo from Facebook) - liveness
- verifies that the person with the video and photo in the identity documents are identical - biometry checks
- recognizes data in ID document - OCR
- verifies recognized data with 3-rd party sources (for example, police databases, government services, etc) - validation

At this moment KYC already works with:

Russian police database through inter-agency electronic communication system (Astral-Platform)
Russian federal tax service API (FNS API)
Russian ESIA (unified identification and authorization system)
Sberbank SberID

Workflow

PC eKYC Connector processes work flow as shown in Figure-1 bellow (clickable).

Astral-Platform workflow

Russian ESIA workflow

FNS API workflow

Sberbank SberID workflow

Workflow steps (by the schema)

An Application should provide to a Mobile App PC eKYC Connector address and App personalization extra to start KYC session with PC Mobile SDK. This data can be provided via QR-code, as simple data set or can be hard-coded inside the Mobile App
Mobile App calls PC Mobile SDK's function openSession
Based on this call PC Mobile SDK creates KYC session and returns session-id and set of sources, required to make KYC analyses. This set contains list of required photos and videos
With received set Mobile App creates media sources to be analyzed during KYC - photos and videos
Mobile App calls PC SDK's function uploadMedia to upload medias to the server
After document recognition (OCR), OCR results will be sent to Mobile App to be verified by a user. Mobile App should call PC SDK's function getSessionStatus and in case of status is OCR_SUCCESS, then call getOCRResults, show OCR results to a user and call approveOCRResults or declineOCRResults
If on step 8 status is OCR_FAILED or user has declined OCR results, then Mobile App should call getRequiredSources function, create new required media sources and call uploadMedia to upload medias to the server once again
KYC analyses depends on eKYC analyser type, but in general case it consist of liveness checks, biometry checks, OCR and document validation
If liveness checks or biometry checks will fail, then analyse status will be changed to ANALYSIS_FAILED
After BIOMETRY_SCUCCESS status received Mobile App should call PC SDK's function getVerifiersList to get list of verifiers - methods to verify user's identity
After user has chosen verifier, verification will be launched. If it fails, then the analyse status will not be changed to ANALYSIS_FAILED and kyc_session status remains VERIFYING_OCR_RESULTS. User will receive push notification about new status. Mobile App should call PC SDK's function getSessionStatus, check current verifier status, and if it fails, may offer to the user to choose new verifier or try again with the current
If user wants to cancel session, then Mobile App should call declineSession PC SDK's function. In this case session will be marked as DECLINED_BY_USER and switched to status ANALYSIS_FAILED
After verification KYC process marked as ANALYSED_SUCCESSFULLY, and session results will be sent to Application back-end to be approved
Application will receive all of the analyses results, OCR results and verification results. Based on this information Application can create user's account or decline a results. If Application declines the results, then session will be marked as DECLINED
After Application's approve Mobile App personalization process will be started. At this step PC eKYC Connector will communicate with PC Server and will create/update PC User and will receive PC User's personalization data. After this session status will be PCKEY_READY
Mobile App should call PC SDK's function getSessionStatus and, if status is not PCKEY_READY - error occurred
Mobile App should call getPCUser and start storing process by PC guide. Mobile App personalization finished
After sending PC User's data to Mobile App, PC eKYC Connector will inform the Application about personalization is ready and will send PC User's ID to be linked with a user's account in the Application.

Session statuses

eKYC session can have one of the following statuses

Status	Num value	Description
UNDEFINED	0	Status is undefined
CREATED	1	Session was created and ready to receive media sources to be analysed
READY_TO_CHECK	2	All of required media sources are uploaded, session is ready to start analyses
ANALYSING	3	Analyses has been started
ANALYSING_BIOMETRY	4	Liveness and biometry analyses are in progress
BIOMETRY_ANALYSE_FAILED	5	Liveness or biometry checks failed
BIOMETRY_ANALYSE_SUCCESS	6	Liveness and biometry checks are success
ANALYSING_OCR	7	OCR is in progress
OCR_FAILED	8	OCR failed, document fields are not recognized
OCR_SUCCESS	9	OCR success, waiting for user's approve or decline
OCR_APPROVED_BY_USER	10	OCR results are approved by a user
OCR_REJECTED_BY_USER	11	OCR results are declined by a user
REQUESTING_VERIFIER	12	Mobile App fetched verifiers list
VERIFYING_OCR_RESULTS	13	Document verification is in progress
VERIFICATION_DECLINED_BY_USER	14	User declined verification
VERIFICATION_FAILED	15	Verification failed
VERIFICATION_SUCCESS	16	Verification success
ANALYSED_SUCCESSFULLY	17	All of the analyses completed successfully
ANALYSIS_FAILED	18	Analyses failed, KYC session can not be proceeded
WAITING_FOR_APPROVE	19	Analyses results was sent to an Application, waiting for the Application decision
APPROVED	20	Session has been approved by the Application
DECLINED	21	Session has been declined by the Application
PCKEY_READY	22	PC User has been successfully retrieved from PC Server to personalize Mobile App
PCKEY_RETRIEVING_FAILED	23	Failed to get PC User from PC Server
FINISHED	24	Session finished successfully

KYC session statuses flow is presented on Figure 2 (clickable)

Statuses will be changed automatically by PC eKYC Connector during processing flow.

KYC session statuses marked with orange color mean KYC session failed.

KYC session statuses marked with green color describes the state of a concrete verifier. Statuses marked with blue describe KYC session status. Statuses will be changed automatically by PC eKYC Connector during processing flow.

Types of sources to be analysed

Source Type	Description
VIDEO_LIVENESS_SCAN	Video with user's eyes and smile scan for Oz Forensics analyser. Can be captured with Oz Liveness SDK
PHOTO_PASSPORT_PAGES_2_3	Photo of passport, pages 2 and 3 at one photo

PC eKYC Connector for Application backend

Application backend interacts with PC eKYC Connector for 4 points:

to receive analyses results
to approve or decline session (is an user's account created or not)
to receive PC User's ID in Mobile App to link it with user's account
to get detailed information about processed/processing sessions

Receive analyses results

{
  "device_info": {
    "app": {
      "appName": "PayControl",
      "packageName": "org.paycontrol.app",
      "appVersionName": "5.0.133",
      "appVersionCode": 133
    },
    "wifi": {
      "macAddress": "CA:4E:D9:B7:6F:4A",
      "localIp": "0.0.0.0",
      "userAgent": "Mozilla\/5.0 (Linux; Android 10; SM-G985F Build\/QP1A.190711.020; wv) AppleWebKit\/537.36 (KHTML, like Gecko) Version\/4.0 Chrome\/84.0.4147.111 Mobile Safari\/537.36__Dalvik\/2.1.0 (Linux; U; Android 10; SM-G985F Build\/QP1A.190711.020)",
      "SSID": "<unknown ssid>"
    },
    "memory": {
      "totalExternalMemorySize": "116230434816",
      "totalInternalMemorySize": "116251406336",
      "hasExternalSDCard": 1,
      "totalRAM": "7560708"
    },
    "sim": {
      "networkCountryIso": "ru",
      "phoneType": "GSM",
      "simCount": 2,
      "simCountryIso": "ru",
      "roaming": 0,
      "IMSI": "",
      "simOperatorName": "МТС",
      "mmsUrl": "http:\/\/wap.samsungmobile.com\/uaprof\/SAMSUNGUAPROF.xml",
      "imei": "",
      "mmsAgent": "SAMSUNG-ANDROID-MMS\/SM-G985F",
      "simSerial": "",
      "networkOperatorName": "MTS RUS"
    },
    "sensor": {
      "minDelay": 2000,
      "vendor": "STM",
      "name": "LSM6DSO Acceleration Sensor",
      "maxRange": 78.45320129394531,
      "type": 1,
      "version": 15932,
      "resolution": 0.002394201699644327
    },
    "location": {
      "latitude": "55,7889697",
      "accuracy": "32,00",
      "longitude": "37,5027807"
    },
    "device": {
      "screenWidth": 1080,
      "radioVersion": "G985FXXU3ATG4,G985FXXU3ATG4",
      "locale": "ru",
      "manufacturer": "samsung",
      "buildHost": "SWDI3411",
      "buildVersionCodeName": "REL",
      "osVersion": "10",
      "defaultBrowser": "com.sec.android.app.sbrowser",
      "bootloader": "G985FXXU3ATG4",
      "root": 0,
      "fingerprint": "samsung\/y2sser\/y2s:10\/QP1A.190711.020\/G985FXXU3ATG4:user\/release-keys",
      "model": "SM-G985F",
      "hardware": "exynos990",
      "product": "y2sser",
      "simulator": 0,
      "buildBrand": "samsung",
      "buildTime": 1594083860000,
      "buildUser": "dpi",
      "screenHeight": 2192,
      "timeZone": "Europe\/Moscow",
      "cpu": "BogoMIPS=52.00;CPU implementer=0x53;CPU architecture=8;CPU variant=0x1;CPU revision=0;Features=fp asimd evtstrm aes pmull sha1 sha2 crc32 atomics fphp asimdhp cpuid asimdrdm lrcpc dcpop asimddp;processor=7;CPU part=0x004",
      "defaultSms": "com.samsung.android.messaging",
      "deviceID": "11641a4d96de8017",
      "certificates": [],
      "serial": "unknown",
      "displayVersion": "QP1A.190711.020.G985FXXU3ATG4",
      "name": "Galaxy S20+",
      "sdkVersion": 29,
      "screenDensity": "other",
      "device": "y2s",
      "board": "exynos990",
      "releaseBuildVersion": "10"
    }
  },
  "analyses_results": {
    "ocrResults": {
      "filename": "PHOTO_PASSPORT_PAGES_2_3_1bf88891-c997-40f4-a7ec-1ae06376b16c.jpg",
      "success": true,
      "document": "ru_passport",
      "selfie": false,
      "confidence": 98.1,
      "sign": null,
      "stamp": null,
      "bad_detections": {
        "number": false,
        "dateofbirth": false,
        "address": true,
        "dateofissue": false,
        "sex": false,
        "name": false,
        "issuecode": false,
        "placeofissue": false
      },
      "field_texts": {
        "number": "0101123456",
        "dateofbirth": "01.01.1990",
        "address": "гор сергиев посад московская обл",
        "dateofissue": "02.02.2010",
        "sex": "ж",
        "name": "иванова маргарита сергеевна",
        "issuecode": "123456",
        "placeofissue": "гу мвд россии по московской области"
      },
      "message": "Successful detection",
      "file_num": 0,
      "status": "FINISHED"
    },
    "validationResults": {
      "response": {
        "error_description": null,
        "invalidity_reason": "None",
        "error_code": 0,
        "comment": null,
        "id": null,
        "state": "READY",
        "invalidity_date": null,
        "status": "Valid"
      },
      "get_passport_extended_result_result": {
        "error_message": null,
        "code": 0
      },
      "status": "FINISHED"
    },
    "biometryResults": {
      "biometry": {
        "results_data": {
          "max_confidence": 1,
          "min_confidence": 0.969320953
        },
        "error_code": 0,
        "resolution_status": "SUCCESS",
        "resolution": "SUCCESS"
      },
      "folderId": "164d7ce8-8a26-43bf-9b7a-ef175058b77b",
      "quality": {
        "error_code": 0,
        "resolution_status": "SUCCESS",
        "resolution": "SUCCESS"
      },
      "status": "FINISHED"
    }
  },
  "verifier": 
  {
    "verifier_status": "VERIFICATION_SUCCESS",
    "name": "FNS"
  },
  "analyser_type": "OzKaluga",
  "session_id": "382024e4-885b-49e3-ae55-eb20fa640467",
  "created_at": 1597319020842,
  "app_extra": {
    "email": "sample-user@sample.com"
  },
  "status": 19
}

URL to send analyses results to an Application should be configured in PC eKYC Connector settings.

After analyse status will be changed to ANALYSED_SUCCESSFULLY or ANALYSIS_FAILED, PC eKYC Connector will make a HTTP POST call with analyses results:

Field	Description
device_info	Information about a User's device, collected with PC Mobile SDK
analyser_type	Analyser type
session_id	KYC session ID
created_at	Timestamp of session creation
app_extra	object provided by Mobile App to PC Mobile SDK as Application extra for account creating
status	numeric representation of session status - pay your attention if analyses were success or failed
analyses_results	Result's content depends on used eKYC analyser

Result's content depends on used eKYC analyser. Sample contains results for OzKaluga analyser that

makes liveness and biometry analyses with Oz Forensics solution

Get verifiers list

Get verifiers list

endpoint: {{pc-ekyc-connector-api}}/{{session_id}}/get_verifiers
method: GET

Response sample

{
    "answer_type": "verifiers",
    "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        },
        "verifiers": [
            "KALUGA",
            "SBER_ID",
            "ESIA",
            "FNS"
        ]
    },
    "answer_version": 3
}

A Mobile App shoud request from PC eKYC Connector actual list of verifiers after OCR and biometry checks. This list should be provided to a user to choose one to use.

Start verification of user's identity

Start validation

endpoint: {{ekyc_api}}/verifiers/sberid/start_validation?session_id={{session_id}}
endpoint: {{ekyc_api}}/verifiers/astral_platform/start_validation/?session_id={{session_id}}
endpoint: {{ekyc_api}}/verifiers/esia/start_validation?session_id={{session_id}}
endpoint: {{ekyc_api}}/verifiers/fns/start_validation/?session_id={{session_id}}

method: GET

Response sample

{
    "answer_type": "result_only",
    "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        }
    },
    "answer_version": 3
}

To start validation of user's identity (OCR results) Mobile App should send request without parameters.

Response contains result_only object.

Decline session

Decline session

endpoint: {{ekyc_api}}/{{session_id}}/verification_declined
method: PUT

Response sample

{
    "answer_type": "result_only",
    "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        }
    },
    "answer_version": 3
}

This request is to cancel verification process for the session.

After this request kyc_session status will be changed to VERIFICATION_DECLINED_BY_USER, and then to ANALYSIS_FAILED

Response contains result_only object.

Approve or Decline session

Approve session

endpoint: {{pc-ekyc-connector-api}}/{{session_id}}/approve
method: POST

Decline session

endpoint: {{pc-ekyc-connector-api}}/{{session_id}}/decline
method: POST

To approve or decline a session Application should call appropriate method.

Сalls do not contain parameters

Receive PC User's ID

After Mobile App has received PC User's personalization data, PC eKYC Connector makes a HTTP POST call the Application to provide PC User's ID to be linked with created user's account

Call sample

{
    "session_id": "382024e4-885b-49e3-ae55-eb20fa640467",
    "app_extra": {
        "email": "sample-user@sample.com"
    },
    "pc_user_id": "ekyc-278fc0e8-3902-4a6e-9f38-4891a60765ab",
    "status": 20
}

Sessions information and management

Get Session Status

endpoint: {{pc-ekyc-connector-api}}/{{session_id}}/get_session_status
method: GET

Response sample

{
    "answer_type": "session_status",
    "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        },
        "session_status": {
            "updated_at": 1609194451818,
            "pc_system_id": "e55d3d79-327e-4c23-b152-967a57258d57",
            "created_at": 1604764602907,
            "status": 1
        }
    },
    "answer_version": 3
}

This method helps to get current session status.

Response contains following object.

Field	Description
status	numeric representation of session status
created_at	timestamp, when the session has been created
updated_at	timestamp, when the session has been updated last time
pc_system_id	pc-system-id, linked with the session, e.g. which pc-system-id will be used to create PC User

Get Session Status History

endpoint: {{pc-ekyc-connector-api}}/get_status_history
method: GET

Response sample

{
    "answer_type": "status_history",
    "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        },
        "status_history": [
            {
                "created_at": 1606992814588,
                "status": 1
            },
            {
                "created_at": 1606992816453,
                "status": 3
            },
            {
                "created_at": 1606992816490,
                "status": 4
            },
            {
                "created_at": 1606992823124,
                "status": 6
            },
            {
                "created_at": 1606992823243,
                "status": 7
            },
            {
                "created_at": 1606992825204,
                "status": 8
            }
        ]
    },
    "answer_version": 3
}

This request should be used to get information about session's status changes step by step.
It can help to understand, which statuses were passed by the session and at what time.

Response is an array of statuses with timestamp of status change.

Get Sessions List

endpoint: {{pc-ekyc-connector-api}}/get_sessions
method: POST

Request sample

{
    "date_from": "2020-12-31 23:59:59.0 +0300",
    "date_to": "2021-12-31 23:59:59.0 +0300",
    "statuses":[5,8,13,16],
    "is_deleted":true
}

Response sample

{
    "answer_type": "sessions",
    "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        },
        "sessions": [
            {
                "is_deleted": 1,
                "updated_at": "2021-01-13 15:38:56.510 +0000",
                "session_id": "2ab290b9-2116-46b1-886c-69e932d1409e",
                "created_at": "2020-12-28 12:39:36.527 +0000",
                "status": 8
            },
            {
                "is_deleted": 1,
                "updated_at": "2021-02-02 15:58:12.444 +0000",
                "session_id": "f54f9041-de11-472e-9e1f-5fe1c9b681f6",
                "created_at": "2020-12-28 18:48:29.74 +0000",
                "status": 16
            }
        ]
    },
    "answer_version": 3
}

Response for this request contains session statuses for all sessions corresponded to request.

Request params:

Field	Description
date_from	start date and time to find sessions
date_to	end date and time to find sessions
statuses	array of numeric representation of session statuses to be found
is_deleted	show or hide deleted sessions, if `false` then only active sessions will be found

Response contains array of objects, described in Get Session Status response.

Clear Sessions

This method should be used to mark session as deleted and to remove analyses sources from a storage.

endpoint: {{pc-ekyc-connector-api}}/clear_sessions
method: POST

Request sample

{
    "days": 365,
    "statuses": [5,8,13,16]
}

Request params:

Field	Description
days	session's age in days, only older sessions will be cleared
statuses	array of numeric representation of session statuses to be cleared

Response contains result_only object.

Clear Session

This method should be used to mark one session as deleted and to remove analyses sources from a storage.

endpoint: {{pc-ekyc-connector-api}}/{{session_id}}
method: DELETE

Response Sample

{
  "answer_type": "cleaned_session",
  "answer": {
    "result": {
      "error_message": "Success",
      "error_code": 0
    },
    "cleaned_session": {
      "is_deleted": 1,
      "updated_at": "2021-08-11 16:19:20.9 +0300",
      "files": [
        {
          "date": "2021-08-11 16:18:55.5 +0300",
          "size": 2492571,
          "name": "PHOTO_PASSPORT_PAGES_2_3_PHOTO_PASSPORT_PAGES_2_3_606c678d-b1d7-4cfa-8355-f485bde8d20a.jpg",
          "type": "image/jpeg"
        },
        {
          "date": "2021-08-11 16:18:56.5 +0300",
          "size": 4370928,
          "name": "VIDEO_LIVENESS_SCAN_VIDEO_LIVENESS_SCAN_60068f04-8130-43b3-806c-2795c89fe101.mp4",
          "type": "video/mp4"
        }
      ],
      "session_id": "215363fc-b283-4b43-96eb-aeb9282ea7de",
      "created_at": "2021-08-11 16:18:35.131 +0300",
      "status": "ANALYSING_OCR"
    }
  },
  "answer_version": 3
}

DELETE request with empty body

Response params:

Field	Type	Description
is_deleted	Integer	Is session sensitive information is deleted from data base
updated_at	String, (`yyyy-MM-dd HH:mm:ss.S Z`)	date of updating session
created_at	String, (`yyyy-MM-dd HH:mm:ss.S Z`)	date of session creation
session_id	String	session id
status	String	`kyc_session` status
files	Array of objects	array of files meta data
date	String, (`yyyy-MM-dd HH:mm:ss.S Z`)	file creation date
size	Long	file size in bytes
name	String	file name
type	String	The return value of this method is the string form of the value of a Multipurpose Internet Mail Extension (MIME) content type as defined by RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. The string is guaranteed to be parsable according to the grammar in the RFC.

Get Analyses Sources

Method returns analyses sources: pictures, video, etc.

endpoint: {{pc-ekyc-connector-api}}/{{session_id}}/get_sources
method: GET

The request doesn't contain params.

Analyses sources will be returned as binary stream - zip-archive.

In case of error - result_only JSON-response will be returned.

Production management

endpoint: {{pc-ekyc-connector-api}}/actuator/
method: GET

PC eKYC Connector provides to system administrator management endpoint /actuator/. Endpoint is secured by basic authentication and can be accessed only from internal network. Basic authentication credentials can be set in additional application.properties file or from system environment variables. For more information please see reference documentation: spring boot actuator

eKYC for Mobile Apps

PC Mobile SDK reference for eKYC described in corresponding sections in iOS and Android docs.

See PCKYCManager class reference.

If Oz Forensics solution is used to make a liveness and biometry analyses, then we recommend to use Oz Forensics Liveness SDK to make a liveness video.
You can find it by the link ozforensics.com/ru/demokit

OCR Manual Check

In some rare cases, for example, if a user takes a photo of a document with glares or text data on document is poorly readable, it may be useful to help user with OCR recognition by manual verification of OCR results.

Endpoint is secured by basic authentication and can be accessed only from internal network.

In general, it looks like following:

A user tries a few times to go through eKYC process and, if he fails, operator can manually check photo of a ID and compares OCR results to find and fix potential mistakes:
- operator opens portal on url: http(s)://{{ekyc_api_url}}/ocr_operator
- logs in via basic authentication
- types user's kyc_session_id into the search field
- clicks on a search button
PC eKYC Connector finds and loads to web page OCR results and uploaded ID photo (if exists):
- operator takes a look on user's OCR results and ID photo
- operator searches mistakes in OCR
- if mistakes are found, then operator hits edit button
- operator fixes data
- operator checks if everything is correct and clicks submit button
PC eKYC Connector changes kyc_session OCR data to corrected version and notifies the user via push to Mobile App:
- user receives push and checks if everything is correct
- user approves OCR results
PC eKYC Connector receives from mobile App OCR_APPROVED_BY_USER and continues to work with session.

Operator processes work flow as shown in Figures bellow (clickable).

Get user OCR results

Edit user OCR results

Submit changes to PC eKYC Connector

PC eKYC Connector application settings

Settings sample

#Server Settings
server:
  port: 8081
  tomcat:
    accesslog:
      enabled: true
    basedir: tomcat
  accesslog:
    directory: logs

#Datasource settings
spring:
  datasource:
    hikari:
      connection-timeout: 20000
      maximum-pool-size: 45
    url: jdbc:postgresql://someurl:5432/kyc
    username: username
    password: password


#KYC settings
pc-ekyc:
  #Application Settings
  app-settings:
    upload-dir: /opt/ekyc/uploads
    analyser: DbrainAnalyser
    app-urls.e55d3d79-387e-4c23-b152-967a57258d57: https://application-system-url-1
    app-urls.d4901088-1a07-4321-8b32-e5c78d0cdfaa: https://application-system-url-2

    #PC Settings
    pc:
      user-id-prefix: kyc-api4-
      url: http://paycontrol-url:8080/pc-api
      pusher-url: http://pusher-url:8080/pc-pusher-api/send_push_message
      key-params:
        autosign-enabled: true
        collect-events: true
        collect-device-info: true
        collect-device-location: true
        collect-device-SIM-info: true
        keyflag-deny-renew-pubkey: true
        keyflag-deny-store-with-os-protection: false
        remote-update-enabled: false
        with-finger-print: true
        scoring-enabled: true
        pass-policy: 0
        nfc-policy: 1

  #Oz Settings
  biometry:
    oz:
      login: login
      password: password
      url: https://api-d.oz-services.ru
  #Verifiers
  verifiers:
    #ESIA settings
    esia:
      client-id: PCEKYC
      scope: openid fullname id_doc
      base-url: https://esia-portal1.test.gosuslugi.ru/
      auth-code-url: https://esia-portal1.test.gosuslugi.ru/aas/oauth2/ac
      redirect-url: https://pc-external-url/pc-client-api/kyc/verifiers/esia/set_auth
      deeplink-url: paycontrol://
      store-name: truststore/TrustStoreTLS
      store-pass: asdg4rdf
      jwt-store-name: truststore/TrustStoreJWT
      jwt-store-password: 24334dddaaF
      keys:
        alias: my-company-name
        password: pass1234
    #SBERID settings
    sberid:
      client-id: ead83447-2a18-4ea0-b34c-59d8bd219740
      client-secret: bd1624ag-986f-424e-8932-7a53c15e125c
      auth-endpoint: https://api.sberbank.ru:8443/prod/tokens/v2/oidc
      api-endpoint: https://api.sberbank.ru:8443/prod/sberbankid/v2.1/userinfo/v3
      p12-name: keystore/my-company-email.p12
      p12-password: storepass
      redirectUrl: https://pc-external-url/pc-client-api/kyc/verifiers/sberid/set_auth
      deeplink-url: paycontrol://
    #FNS
    fns:
      url: https://api-fns.ru/api/
      api-key: f570f1115cc9578b0167af23g04d6afd611ce090

  #OCR settings
  ocr:
    #Kaluga Settings
    kaluga-astral:
      url: http://stunnel:8000/
      api-key: 8cpd053a1j6e4r09hdl914c1cb17a0414
    #dbrain
    dbrain:
      url: https://latest.dbrain.io/
      api-key: 8cpd053a1j6e4r09hdl914c1cb17a0414


#Log settings
logging:
  level:
    tech.paycon: info

Variable	Description	Default
Server Settings
server.port	Web server port	8081
tomcat.accesslog.enabled	Enabling tomcat embedded web server access logs	true
tomcat.basedir	Basedir for tomcat	tomcat
server.accesslog.directory	Tomcat logs directory	logs
Datasource settings
spring.datasource.hikari.connection-timeout	Connection timeout for data base connection pool service Hikari (ms)	20000
spring.datasource.hikari.maximum-pool-size	Maximum size of connection pool	15
spring.datasource.url	Database url	none
spring.datasource.username	database username	none
spring.datasource.password	database user password	none
KYC application settings
pc-ekyc.app-settings.upload-dir	Basedir for uploaded user media	300000
pc-ekyc.app-settings.analyser	PC eKYC Connector analyser which may contain different collection of verifiers	DbrainAnalyser
pc-ekyc.app-settings.app-urls.{{system-id}}	Map/dictionary(key=>value data structure) which contains pc system-id as key and application system url as value	none
pc-ekyc.app-settings.pc.user-id-prefix	PC user-id-prefix	kyc
pc-ekyc.app-settings.pc.url	PC url	none
pc-ekyc.app-settings.pc.pusher-url	PC Pusher url	none
pc-ekyc.app-settings.pc.key-params.*	PC user `key_params` see key_params	none
Oz settings
pc-ekyc.biometry.oz.login	Oz Forensics API login	none
pc-ekyc.biometry.oz.password	Oz Forensics API password	none
pc-ekyc.biometry.oz.url	Oz Forensics API base url	none
Verifiers settings
ESIA
pc-ekyc.verifiers.esia.client-id	Mnemonic system name from ESIA platform credentials	none
pc-ekyc.verifiers.esia.scope	Scope of user data	openid fullname id_doc see ESIA ref. doc
pc-ekyc.verifiers.esia.base-url	ESIA API base url	none
pc-ekyc.verifiers.esia.auth-code-url	URL for user authorization see ESIA ref. doc	none
pc-ekyc.verifiers.esia.redirect-url	PC external url	{{pc-external-url}}/pc-client-api/kyc/verifiers/esia/set_auth
pc-ekyc.verifiers.esia.deeplink-url	Deeplink schema of mobile app	paycontrol://
pc-ekyc.verifiers.esia.store-name	Relative path to truststore	truststore/TrustStoreTLS
pc-ekyc.verifiers.esia.store-pass	truststore password	none
pc-ekyc.verifiers.esia.jwt-store-name	truststore for JWT	truststore/TrustStoreJWT
pc-ekyc.verifiers.esia.jwt-store-password	truststore JWT password	none
pc-ekyc.verifiers.esia.keys.alias	Alias name of container for HDIMAGE Crypto Pro keystore	none
pc-ekyc.verifiers.esia.keys.password	Container password	none
SBERID
pc-ekyc.verifiers.sberid.client-id	client id see SBERID ref. doc	none
pc-ekyc.verifiers.sberid.client-secret	secret id see SBERID ref. doc	none
pc-ekyc.verifiers.sberid.auth-endpoint	Authorization endpoint see SBERID ref. doc	none
pc-ekyc.verifiers.sberid.api-endpoint	API endpoint see SBERID ref. doc	none
pc-ekyc.verifiers.sberid.p12-name	Relative path to p12-container	keystore/my-company-email.p12
pc-ekyc.verifiers.sberid.p12-password	p12-container password	none
pc-ekyc.verifiers.sberid.redirect-url	PC external url	{{pc-external-url}}/pc-client-api/kyc/verifiers/sberid/set_auth
pc-ekyc.verifiers.sberid.deeplink-url	Deeplink schema of mobile app	paycontrol://
FNS
pc-ekyc.verifiers.fns.url	FNS API url	none
pc-ekyc.verifiers.fns.api-key	FNS API key	none
OCR settings
Astral Platform settings
pc-ekyc.ocr.kaluga-astral.url	Kaluga Astral Platform url	none
pc-ekyc.ocr.kaluga-astral.api-key	Kaluga Astral Platform API key	none
D-brain settings
pc-ekyc.ocr.kaluga-astral.url	D-brain url	none
pc-ekyc.ocr.kaluga-astral.api-key	D-brain API key	none
Logging settings
logging.leve.tech.paycon	Logging level	info

More about externalized configuration

PC eKYC Connector installation

PC eKYC connector is the executable Java jar file with embedded tomcat web-server inside. It can be run on any existing platform:

MS Windows
any posix-system
any OS-level virtualization system (as Docker for example)

Also Postgres database availability is required.

Requirements:

Technology name	version
Java JRE	>= 11
Postgres	>= 8.4
Crypto Pro JCP	2.0 with `A` index (in case ESIA verifier is enabled)

Crypto Pro settings

System command to find out JCP license type:

<JRE>/bin/java -cp JCP-1.0.jar ru.CryptoPro.JCP.tools.License -required

Response sample

OS type: Client OS
Required license: the license for usage on one workstation

System command should be executed in directory: {projectDirectory}\libs, where JCP-1.0.jar file is located.

System command to set JCP license:

<JRE>/bin/java -cp "JCP-1.0.jar:*" ru.CryptoPro.JCP.tools.License -serial "{license-serial-number}" -company "{Company-name}"

Configuring Crypto Pro container for work with PC eKYC Connector

In case you have your key-container from CA in pfx-file format, you should convert your pfx-file to Crypto Pro HDIMAGE container type. For this purpose, it is most convenient to use Crypto Pro CSP version 5 or above. After converting pfx to HDIMAGE store type, Crypto Pro CSP will create special folder with six files with key postfix.:

case posix like systems in /var/opt/cprocsp/keys/{username}/
case MS Windows in C:\Users\{user}\AppData\Local\Crypto Pro\

You should copy that folder to system which on PC eKYC connector will be running with proper path

Also two truststore must be created through JCP control pane: 1. first with TLS GOST certificate of a ESIA server 2. second for checking JWT-token signature with another certificate of ESIA server

When converting pfx to HDIMAGE store type remember container alias name! This value must be set in PC eKYC Connector property pc-ekyc.verifiers.esia.keys.alias

PC eKYC Connector Reference

Introduction

General flow description

Principles

Workflow

Astral-Platform workflow

Russian ESIA workflow

FNS API workflow

Sberbank SberID workflow

Workflow steps (by the schema)

Session statuses

Types of sources to be analysed

PC eKYC Connector for Application backend

Receive analyses results

Get verifiers list

Start verification of user's identity

Decline session

Approve or Decline session

Receive PC User's ID

Sessions information and management

Get Session Status

Get Session Status History

Get Sessions List

Clear Sessions

Clear Session

Get Analyses Sources

Production management

eKYC for Mobile Apps

OCR Manual Check

Get user OCR results

Edit user OCR results

Submit changes to PC eKYC Connector

PC eKYC Connector application settings

PC eKYC Connector installation

Crypto Pro settings

Configuring Crypto Pro container for work with PC eKYC Connector

Third party services documentation