Configuring Onfido v3
Note
Passfort supports Onfido Classic. Onfido Studio is not yet supported.
Onfido is a data provider you can use to run these checks:
ID verification (Passfort collects documents)
ID verification (service collects documents)
Passfort also supports Onfido v1 and v2, however, we recommend that you migrate to Onfido v3 as soon as possible in order to take advantage of the additional features that v3 brings. These include:
Additional configuration options
Improved MRZ verification
Learn more about configuring Onfido v1 and 2.
ID verification (Passfort collects documents)
How it works
This is the default behavior for a variant of the ID verification (Passfort collects documents) check with Onfido as the data provider.
You upload the individual's document to Passfort. Passfort submits the document to Onfido who checks for signs of forgery and extracts the customer’s name, date of birth, and, where possible, nationality from the document.
You can upload these documents for the Verify identity task:
Biometric state ID
Driver's license
National health insurance card
Passport (including the Irish Passport Card)
Residence permit
State ID
Tax ID
Visa
Voter ID
The document must be between 32KB and 10MB. The following file types are accepted: JPG, PNG, and PDF.
Onfido performs image quality checks and the following security checks on documents:
Age validation
Police record
Compromised document
Visual authenticity
To see the checks performed on selfies, see the description of the Check facial similarity configuration option.
Passfort cross-references the details recorded in the individual’s profile, such as name, date of birth, and, if available, nationality, with the extracted data provided by Onfido.
An image of the document is displayed in the check results.
The check passes when all three criteria are met:
The document details obtained from Onfido match the details in the profile.
Onfido confirms the document is authentic by confirming the status of the check is Clear.
Onfido confirms that any additional checks have passed, such as police checks or selfie checks.
If the individual’s details do not match Onfido's data, the check fails.
Because cross-referencing the individual’s details is an action performed in Passfort and not in Onfido, it’s possible for the check to pass in Onfido but fail in Passfort.
Note that Onfido may set the status of the check to Consider, with a sub-status of Caution, Suspected, or Rejected, even if the individual components of the check, like Image Integrity, Data Validation, have passed. If Onfido sets the status to Consider, Passfort fails the check.
For more information about how Onfido determines the status, see their help documentation.
When you view the Full results of the check, you can see a result under Document type called Found document of correct type in image. This is a Passfort-specific result that indicates whether the document type you've selected when running the check matches the document type that was submitted.
If the individual’s profile doesn’t have data for the required fields, an error is displayed.
This check variant is supported for all countries.
This check variant cannot be run on the Verify address task. Onfido does not extract the individual’s address from the document so it’s not possible to use this check to confirm proof of address. For more information about how Onfido handles this check, see Onfido’s documentation. To get step-by-step instructions for running this check, see Verify a document.
Configuration options
Check facial similarity?: When this option is selected, Onfido compares a selfie provided by the individual to the photo in the individual’s identity document. An image of the selfie is displayed in the check results so you can see it. Onfido performs image quality checks and the following security checks for selfies: Face comparison; Visual authenticity.
With ID verification (Passfort collects documents), only selfie checks are supported. To enable liveness checks, you must use ID verification (service collects documents). For more information about how Onfido handles this configuration option, see Onfido’s documentation.
Testing your configuration
Once the check variant is configured, follow these steps in your demo environment to test whether it's working as expected.
To get a PASSED result, check that the ID is authentic and the document details in the demo environment match the profile details.
Create an individual profile with these details:
First name: Alex
Surname: Wheeler
Date of birth: 01 January 2000
Expected result: DOCUMENT_ALL_PASS
To get a FAILED result, use the example where the DOB entered is different from the details in the demo environment.
Create an individual profile with these details:
First name: Ashley
Surname: Williams
Date of birth: 30 June 1980
Expected result: DOCUMENT_DOB_FIELD_DIFFERENT
What we’ll need
Let us know that you’d like to add a variant of the ID verification (Passfort collects documents) check with Onfido and which configuration options you’d like to use. We’ll set it up for you.
We’ll need your Sandbox API token, Live API token and Webhook token. Learn how to get your tokens.
Profile fields
These are the profile details matched with the document details extracted by Onfido:
Name | Description |
First name(s) ( *Required | The individual’s first and, if applicable, middle names. |
Surname ( *Required | The individual’s last name. |
Date of birth ( *Required | The individual’s date of birth. |
Email address ( Optional | The individual's email address. |
If you’re running the check via the API, the ID verification check also uses the following field from the ID check’s documents
:
Key name | Description |
*Required | The document’s unique identifier in Passfort. |
ID verification (service collects documents)
When you're using version 3 of Onfido's API, the check behavior is as follows.
How it works
This is the default behavior for a variant of the ID verification (service collects documents) check with Onfido (API v3) as the data provider.
The individual submits their documents to Onfido who checks for signs of forgery and extracts the individual’s name, date of birth, and, where possible, gender and nationality from the documents.
To learn which document types you can use for this check, see Onfido's supported document types.
When Onfido collects the customer's documents, they create an applicant ID. This can be used to retrieve any previous checks.
Passfort will never fail the check because of an unrecognized document. If Passfort cannot recognize the document, the document type will be classified as Miscellaneous. Note that if Onfido cannot recognize the document, the check will fail. To see the checks performed on selfies and liveness videos, see the description of the Facial similarity check option.
Passfort cross-references the details recorded in the individual’s profile, such as name, date of birth, and, if available, nationality, with the extracted data provided by Onfido.
If the profile has a customer reference, it is sent to Onfido. The Onfido profile is tagged with the customer reference.
The check passes when all three criteria are met:
The document details obtained from Onfido match the details in the profile.
Onfido confirms the document is authentic by confirming the status of the check is Clear.
Onfido confirms that any additional checks have passed, such as police checks, selfie checks, or liveness checks.
If the individual’s details do not match Onfido's data, the check fails.
An image of the document is displayed in the check results, along with the overall result, such as Pass or Fail, and the reason why the overall result was returned. If the check fails, the Onfido sub-results, such as Clear or Consider, are displayed so you can see exactly why the check has failed.
To get a detailed breakdown of the check results in the portal, click Additional information tab shows the Onfido applicant ID and the Onfido results for every category, regardless of whether the check passed or failed.
. TheBecause cross-referencing the individual’s details is an action performed in Passfort and not in Onfido, it’s possible for the check to pass in Onfido but fail in Passfort.
Note that Onfido may set the status of the check to Consider, with a sub-status of Caution, Suspected, or Rejected, even if the individual components of the check, like Image Integrity, Data Validation, have passed. If Onfido sets the status to Consider, Passfort fails the check.
For more information about how Onfido determines the status, see their help documentation.
When you view the Full results of the check, you can see a result under Document type called Found document of correct type in image. This is a Passfort-specific result that indicates whether the document type you've selected when running the check matches the document type that was submitted.
For the ID verification (service collects documents) check, the result will always be Valid.
If the individual’s profile doesn’t have data for the required fields, an error is displayed.
This check variant is supported for all countries.
This check variant cannot be run on the Verify address task. Onfido does not extract the individual’s address from the document so it’s not possible to use this check to confirm proof of address. For more information about how Onfido handles this check, see Onfido’s documentation. To get step-by-step instructions for running this check, see Verify a document.
Configuration options
You can use the following configuration options:
API region: Choose which Onfido region you're using.
Facial Similarity Check: Choose Selfie, Video, or Video with fallback. Onfido compares a selfie or liveness video to the photo in the individual’s identity document. The selfie or the liveness video is displayed in the check results so you can see it. Onfido performs image quality checks and the following security checks for selfies: Face comparison; Visual authenticity.
When Selfie is selected, Onfido's
facial_similarity_photo
report type is used. When Video is selected, Onfido'sfacial_similarity_video
report type is used. When Video with fallback is selected, Onfido'sfacial_similarity_video
report type is used if a video is available (regardless of whether the check passes or fails); otherwise,facial_similarity_photo
is used.If you have this configuration option set to Video, you should set the
uploadFallback
property tofalse
in your Onfido SDK configuration. Otherwise, Onfido will try to upload a selfie when liveness is not supported by the browser, and the check will error.Only allow these document types (SDK only): Select one or more of the document types to run a check against. If no document type has been selected, Onfido will accept any of them by default.
Choose Onfido SDK Language: Choose one of six languages to display in the user interface. The language selected affects all Onfido instructions throughout the SDK journey.
Custom welcome screen (SDK only): Enter text to show on the introduction screen of the SDK. The introduction screen displays a summary of the steps the user will pass through.
Retrieve the most recent reports instead of running a new check: Retrieve historical results from Onfido without instructing a new check. Selecting this option ignores the facial similarity check configuration option and if there are multiple Onfido checks on the applicant, only the most recent check result will be retrieved.
Note
The SDK options only apply when using the Onfido SDK in forms and customer requests sent through Passfort.
Testing your configuration
Once the check variant is configured, follow these steps in your demo environment to test whether it's working as expected.
To get a PASSED result, check that the ID is authentic and the document details in the demo environment match the profile details.
Create an individual profile with these details:
First name: Alex
Surname: Wheeler
Date of birth: 01 January 2000
Expected result: DOCUMENT_ALL_PASS
To get a FAILED result, use the example where the DOB entered is different from the details in the demo environment.
Create an individual profile with these details:
First name: Ashley
Surname: Williams
Date of birth: 30 June 1980
Expected result: DOCUMENT_DOB_FIELD_DIFFERENT
What we'll need
This is the same as ID verification (Passfort collects documents) for Onfido.
Profile fields
These are the profile details matched with the document details extracted by Onfido:
Name | Description |
First name(s) ( *Required | The individual’s first and, if applicable, middle names. |
Surname ( *Required | The individual’s last name. |
Date of birth ( *Required | The individual’s date of birth. |
Gender ( Optional | The individual's gender. Leave unset for non-binary genders. |
Getting your Onfido tokens
To get your Sandbox API token and Live API token:
Access your tokens on the Onfido dashboard:
Copy the token for the Live environment.
Copy the token for the Sandbox environment.
Send us the Live token from Step 2 and the Sandbox token from Step 3.
Only one Live token and Sandbox token can be used in your Passfort configuration. If you have multiple Live or Sandbox tokens, choose one from each type.
To get your Webhook token:
Go to Onfido dashboard:
on theClick
.In the URL field, add the webhook URL.
This is https://onfido-dot-core-gearbox-112418.appspot.com/webhook for institutions in the EU environment.
This is https://69408cd-dot-onfido-uae-dot-core-gearbox-112418.appspot.com/webhook for institutions in the UAE environment.
Under Receive data from, select .
Select the
and notifications.Click
. The new webhook is created.Copy the
for the new webhook and send it to us.