Skip to main content

Selfie Transactions

The Verified platform can perform biometric identity verification if it has some reference for comparison, also known as a reference biometric credential. This most commonly takes the form of a selfie, and therefore this process is referred to as a selfie transaction.

Logical Sequence

1 - Obtain a selfie

There are 2 options for obtaining a user's selfie:

  • Option 1 - prompt the user to take a selfie by calling the BeginGetForeignBiometry API endpoint.
  • Option 2 - if your user already performed onboarding and identity verification with another provider, and you have captured the user's selfie from that session, you can instruct Verified to store it as the user's reference biometric credential.

caution

You should invoke this flow only when you are certain the correct user is present, i.e. logged into your application or otherwise confirmed through a KYC process.

2 - Bind credential to user account

Once your platform has captured the user's selfie, instruct Verified to save it for future using a combination of the following process:

  • Call the CreateAccount API endpoint to create a reference for your user's MFA record in the Verified platform. You'll need to refer to this account when asking for biometric verification later.
  • Attach reference biometric credential to the account.

tip

When you are done with these basics, consider implementing account lifecycle management functions, such as allowing the user to update their selfie or re-register. We have robust CRUD operations available for account objects and stored reference biometric credentials via the Administration Service. This same information is available in the Identity Portal under the "Verified Enrolled Users" section.

Postman Sample

For your convenience we have provided sample Postman collections demonstrating the API sequence. Within the collection, the numbered requests correspond directly to the numbered sections below. Download the collection here.

API Sequence

OpenAPI specs can be downloaded here: Administration Service

Sequence Diagram

1 - Authenticate

In your backend, authenticate your access and store the AccessToken and RefreshToken from the response. Before every subsequent API call, implement logic to check if the token is expired and renew it if needed.

2 - Initiate Selfie Transaction

In your backend, call the BeginGetForeignBiometry API endpoint.

Example request body:

{
"CheckLiveness": true,
"TimeoutSec": 3600,
"PhoneNumber": "",
"Email": "",
"TransportType": 0,
"IntroductionText": ""
}
TransportTypeDescription
0Inline
1SMS
2Email

You need to store the following parameters from the response:

  • OperationId: to track status and use in embedded UI integrations
  • OneTimeSecret: to use in embedded UI integrations

Example response body:

{
"OneTimeSecret": "TbAeETwpOxbvKy7rWCeOcQ==",
"TempId": null,
"OperationId": "113e838b-be34-53e9-c52f-3cc45b2d10ce",
"Status": 0,
"Message": null,
"StartDate": "2021-10-13T15:59:25.06Z",
"EndDate": null
}

3 - Display UI for Data Capture

Use the OperationId and OneTimeSecret to build a transaction URL for one of our convenient, prebuilt UI options.

4 - Get Selfie Transaction Result

In your backend, check if the user has provided the response.

  • You can poll by OperationId for the transaction result using the EndGetForeignBiometry API endpoint.
  • The code should exit the polling loop when the status is not equal to 0, indicating that the operation is not pending.

When the status equals 1 "Accepted", the response will return a TempId. This is where Verified securely stores the data provided by the user. Verified does not store this information for longer than 72 hours.

Example response body:

{
"OneTimeSecret": "TbAeETwpOxbvKy7rWCeOcQ==",
"TempId": "be6e89db-d709-4636-b708-b526c37018a1",
"OperationId": "113e838b-be34-53e9-c52f-3cc45b2d10ce",
"Status": 1,
"Message": "Operation has been accepted by the user.",
"StartDate": "2021-10-13T15:59:25.06Z",
"EndDate": "2021-10-13T16:03:33.01Z"
}
tip

You can also register a webhook using the UpdateCustomerWebhookSettings API endpoint so we can notify your backend when the user is finished.

5 - Create Account

In your backend, create a Verified account using the CreateAccount API endpoint. You'll need to provide an AccountNumber and DisplayName. You can choose anything that makes sense for your system. AccountNumber must be unique, but DisplayName does not. Use something you can easily link to the specific user for the AccountNumber.

  • Ideally, you should setup an "MFA Account GUID" in your system that you would use. This way, the Verified platform has only the info it needs instead of storing identifiable information.
  • A simpler, albeit less safe example: create AccountNumber that is equal to Username, so that MFA can be used without creating additional records anywhere in your system.

Example request body:

{
"AccountNumber": "MyAccount",
"DisplayName": "MyAccount",
"CustomDisplayName": "MyAccount",
"Description": "My Test Account 1",
"Custom": true
}

caution

Avoid using spaces and special symbols in AccountNumber since this value is used in the URL path in subsequent calls.

6 - Create a Reference Biometric Credential

In your backend, create a reference biometric credential using one of the following methods:

Option 1
Use the CreateAccountProofedBiometricCredential API endpoint. Provide the AccountNumber in the URL from step 5 and TempId in the JSON body from step 4.

Example request body:

{
"TempId": "be6e89db-d709-4636-b708-b526c37018a1"
}

Option 2
Use the CreateAccountBiometricCredential API endpoint and supply the data you captured from the user.

Example request body:

{
"ExternalId": null,
"Description": "Main account biometric credential",
"CredentialType": 1,
"DataType": 1,
"Data": "dJS6ku0zWI3mXYgsMRv3ayLLX6V91em2gt0AVQ15tr0=",
"IsProofed": false,
"SourceCredentials": [],
"DeletedDate": null
}

That's it! Now your user can now enjoy the benefits of seamless biometric second factor authentication.