Introduction

• As a description of the following paragraphs: a brief introduction of what each front-end process page does.
• On the right side next to the images: a brief description of every customizable element of the process.

Anything not mentioned below cannot be customized, such as the content of the texts.

Welcome page

This is what the user sees when lands on Phyon from the customer’s informative system.

There is the chance here, for the user, to open an external URL, useful to show a privacy disclaimer or terms of use, or anything else the customer wants. 

Switch-to-mobile 

Two options for the user who starts from a desktop to switch to a mobile device equipped with camera.

SMS or QR code.

The SMS sender name can be customized, but not the content of the message, as told before.

Document selection

Where the user selects the first document to scan for the identification.

This list of available documents to show here is customizable at configuration time as well as, the entire visibility of the page.

Only one selection is admitted to continue.

Documents order recap

Recap of the documents to provide for the detection.

The one selected before + one (eventually) defined at configuration time.

And the exact order of the sides required, each one indicated by his own number.

First document, how to scan

Description of the document and side to provide at the device camera in the next detection step.

First document acquisition

In this step, the user, guided by the tips in the top of the screen, can automatically detect and scan his main document without pressing any button.

Second document, how to scan

Description of the document and side to provide at the device camera in the next detection step.

Second document acquisition

In this step, the user, guided by the tips in the top of the screen, can automatically detect and scan his secondary document without pressing any button.

Face acquisition, how to scan

Description of how to provide the user face, the right way, in front of the device camera in the next detection step.

Liveness face acquisition

In this step, the user, guided by the tips at the top of the screen, can automatically detect and scan his own face without pressing any button and performing any action.

Switch-to-desktop

At this point, for the user who started the process from desktop, is time to return there.

Otherwise, the user who started directly from mobile will continue on his device and won’t see this screen

OCR and Data Entry

This page can be visible or not (by defining it at process configuration time).

The user has the chance to check and integrate or correct (again, only if defined so at configuration time) data extracted from the user’s documents.

The mandatory data to be fulfilled to proceed are: name, surname, date of birth, citizenship, documents number, documents expiry date.

Greetings page

The Phyon Identification process is now completed.

The user resumes the experience on the customer’s informative system UI and the outcome of the back-end identification results and data are sent to the customer via callback.

• User: a prospect consumer which wants to register to Client services
• Client: the customer's application consuming this API
• Phyon: Saas solution providing the identification service

Phyon Identification API uses X.Y.Z as version numbering, where:

• X: stands for a major version - new features that break the existing API
• Y: stands for a minor version - new features in a backward-compatible way
• Z: stands for a patch - fixing bugs

The following changes are considered as backward incompatible:

• If any path is removed or the HTTP verb is changed
• If any request parameter is removed
• If any new request parameter is required or an existing one set as required
• If any request attribute is removed
• If any response attribute is removed
• If any enum value is removed

New fields can be added to the current API version, at any time without preliminary warning with subsequent documentation added afterward. However, already documented fields cannot be modified or removed. Please rely solely on them.

The following diagram shows the sequence of interactions between Client and Phyon.

Introduction

In order to start a Phyon Identification process you have to set correctly some payload fields of applications API

Context

CustomerApplicationId

Unique identifier for the application for the client. Uniquely identifies requests belonging to the same “logical” conversation.

Organization

Organization identifier. (This value will be provided to the client)

OrganizationUserId

This field allows requesting a custom front-end layout for the process. To use the default front-end layout, this field has a constant value equal to -1. (In case of a custom layout value will be provided to the client)

Scenario

Scenario code.
Domain values:

• STD_DOCUMENT_ACQUISITION_SELFID (Identification scenario)
• STD_EXPORT_DATA (Export data scenario)

Scenario version

Constant value.
Value: “1.0.0”

Process

Process code.
Domain values:

• STD_DOCUMENT_ACQUISITION_SELFID___IT (Identification process)

Process version

Constant value.
Value: “1.0.0”

SubjectDocumentType

DocumentTypeCode

Domain values:

• LATE_BINDING_DOCUMENT (placeholder for user document selection)

The user document selection be skipped by replacing it and indicating up to two document typeCodes directly.

For the “Try it out” feature available on the API Reference page, and ccordingly to the document selected during the process, the typeCode value will assume specific domain default values:

• ITA_HEALTH_CARD (Italian health card. Second document to scan)
• ITA_ID_CARD (Italian identity card)
• ITA_ID_ECARD (Italian electronic identity card)
• ITA_ID_ECARD_OLD (Italian old electronic identity card)
• ITA_PP_CARD (Italian passport)
• ITA_DL_CARD (Italian driving license)
• GENERIC_PP_CARD_CLASS (generic booklet)
• GENERIC_ID_CARD_CLASS (generic card)

Some examples of additional custom process domain values available after a dedicated process configuration:

• GENERIC_ID_ECARD (electronic identity card with mrz)
• GENERIC_PP_CARD (passport with mrz)
• AT_ID_ECARD (Austrian electronic identity card)
• AT_DL_CARD (Austrian driving license)
• AT_DL_CARD_OLD (Austrian old driving license)
• AT_PP_CARD (Austrian passport)
• DE_ID_ECARD (German electronic identity card)
• CZK_ID_ECARD (Czech electronic identity card)
• CZK_ID_ECARD_OLD (Czech old electronic identity card)
• SVK_ID_ECARD (Slovak electronic identity card)
• IRL_DL_ECARD (Ireland driving license)
• IRL_PP_CARD (Ireland passport booklet)
• IRL_PP_ECARD (Ireland electronic passport card)
• CH_ID_ECARD (Swiss electronic identity card)
• CH_DL_ECARD (Swiss driving license)
• CH_PP_ECARD (Swiss electronic passport card)

…these are only a few examples, Phyon currently supports 176 countries worldwide.

Introduction

When a user completes a web session, Phyon process communicates to the client application in two ways:

• Through a callback on back-end side for the process result (Success or Failure)
• Through a post-message on front-end side for the process end in order to allow proceeding with client workflow

Back-End

There are two types of back-end callback

• Process result - A callback to notify the outcome at the end of the process
• Export Archive – A callback to upload the archive with all data collected at the end of the export

For both types, you have to expose an endpoint protected with basic authentication.

Process Result – Payload fields

Context
Refer to paragraph 3.1.

OcrResults

This field contains form data validated by the user.

Depending on acquired documents, the DocumentFields – FieldType could have these values:

• Name
• Surname
• BirthDate
• Citizenship
• CardNumber
• ExpiryDate
• PlaceOfBirth
• ProvinceOfBirth
• CountryOfBirth
• CountryOfBirthCodeCrif
• Gender
• TaxCode
• AddressLocality
• AddressStreet
• AddressStreetZipcode
• IssuingAuthority
• IssuingPlace
• IssuingDate
• IssuingCountry
• DocumentNumber
• AddressProvince
• ChosenDocIssuingDate
• ChosenDocIssuingAuthority
• ChosenDocExpiryDate
• ChosenDocCardNumber
• ChosenDocIssuingPlace
• ChosenDocDocumentNumber

OcrDocumentResults

This field contains data read by the OCR service for each document.

The DocumentFields – FieldType could have these values:

• LastName
• FirstName
• DateOfBirth
• PlaceOfBirth
• ProvinceOfBirth
• DocumentNumber
• CountryOfBirth
• CountryOfBirthCodeCrif
• IssuingCountry
• IssuingPlace
• IssuingAuthority
• IssuingDate
• CardExpirationDate
• Gender
• TaxCode
• AddressLocality
• AddressStreet
• Nationality
• CardNumber
• AddressProvince
• AddressStreetAddressType
• AddressStreetStreetName
• AddressStreetStreetNumber
• AddressStreetPlace
• AddressStreetProvince
• AddressStreetZipcode
• DocumentClassCode
• IssuingState
• PersonalNumber
• DateOfEmission
• ExpiryDate
• Signed
• Warnings

AdditionalData

ACQUISITION_METHOD

The code could have these values:

• LIVE_DOCUMENT_ACQUISITION
• FILE_UPLOAD

COMPARISON_RESULT

The code could have these values:

• OK
• KO

Status

The code could have these values:

• COMPLETED
• COMPLETED_WITH_ERROR

Export Archive - Files Naming Convention

There are the following naming conventions for files contained in the archive:

• Image file name
  • [SUBJECT_DOCUMENT_TYPE]_[CUSTOMER_APPLICATION_ID]_yyyyMMddHHmmssSSS.pdf
• Callback file name contained in Archive file
  • CALLBACK_[CUSTOMER_APPLICATION_ID]_yyyyMMddHHmmssSSS.pdf

Front-End

After Phyon application initialization, the client has to embed in its application Phyon Front-End, typically using an iFrame.

In this scenario, the "urlToRedirect" present in the API application response has to be used as "src" (source attribute) in the iFrame definition.

iFrame Sample

    
    <iframe src="{{urlToRedirect}}" allow="camera; microphone;"></iframe>

Post-Message

At the end of the process, Phyon Front-End will communicate through post-message.

In order to handle this message, it can be defined as an event listener.

    
    window.addEventListener("message", (event) => { console.log(event.data); }, false);
    

At the end of the process is possible to redirect the User into a different specified URL as reported in the first of the examples below.

Integration Back Office Panel

After the live Self onboarding completion, the data collected and stored during the user journey can also be sent to a backoffice panel if enabled.

This feature allows the performing of human-based checks on top of those already made during the onboarding process execution.

• Identification (STD_DOCUMENT_ACQUISITION_SELFID) sample payload download
• Export data (STD_EXPORT_DATA) sample payload download
• Callback Process Result – Sample download
• Callback Export Archive – Sample download

Hereby is reported the currently supported set of browsers and versions. The most recent older versions (and upward) are considered working as well, subject to the presence of a valid WebRTC protocol support. A newer version will be anyway verified and confirmed from time by time:

• Compatibility matrix download