Docs
Developer Hub

Facematch service

Use this merit to run a facial biometrics comparison using faces from different sources

Suggest Edits

Overview

The Facematch feature empowers merchants to conduct face comparisons from multiple sources, including an ID document, a live camera picture, a government facial database, or even your own facial database. This comparison leverages cutting-edge facial biometrics algorithms to ascertain whether the faces belong to the same user or if there is an attempt at impersonation.

By utilizing advanced facial recognition technology, the Facematch feature ensures robust verification and enhances security measures, protecting against potential fraudulent activities and identity impersonation. This capability provides businesses with a reliable and efficient means of confirming the authenticity of user identities.

Get Started

Availability

There are 5 sources you can use to run the Facematch merit:

  • Biometric Verification: 🌎 Available globally
  • ID Document: 🌎 Available globally
  • Video Agreement: 🌎 Available globally
  • Merchant's own database: 🌎 Available globally
  • Government database:
    • Argentina
    • Brazil
    • Indonesia
    • Nigeria
  • Available for Direct Link, Web/Mobile SDKs, and API

Features

  • You can choose two photo sources and we will run a facematch.
  • Based on the threshold set by you we will approve or reject the user.

Setup

Step 1: Setup a Metamap

To create a new Metamap in the dashboard, follow these steps:

  1. Go to the "Metamaps" section and click the blue button to build a new Metamap.
  2. In the Metamap builder, navigate to the left pane, and under the 'Fraud' category, locate the Facematch merit block.
  3. Drag and drop the Facematch merit block into the central pane labeled "User's Experience."
  4. Feel free to utilize the Facematch merit block in combination with any other desired merit blocks.

Your customized Metamap will have the following structure:

Set up the Facematch sources

In the right pane of the interface, you can select the sources from where you want to gather the faces to be compared. You can create any combination of face sources, choosing from the following ones, as long as the sources are available and aligned with your specific business requirements.

From Biometric verification

When selecting 'from Biometric Verification', the platform will capture the user's live face from the Biometric Verification, irrespective of the chosen biometric method.

From a User Document

When choosing from a User Document, the platform will extract the face from the Document Verification. If multiple document steps are added, you can specify from which document you want to extract the face.

From Video Agreement

When opting for Video Agreement, the platform will capture the user's live face from the Video Agreement merit block.

Fetched from Government Database

When choosing 'fetched from Government Database,' the platform will prompt you to add the Government ID Verification merit block. In the Facematch settings, you will find the supported facematch Gov Checks, and you can enable a Gov Check from there. Once enabled, it will be automatically added to the Government ID Verification merit block.

Fetched from Merchant's own Database

When opting for 'fetched from Merchant's own Database,' you can securely share an image file containing the face you wish to compare with.

Setup facematch thresholds

Each face comparison will yield a score indicating the level of similarity between the compared faces. A higher score signifies greater similarity. You have the flexibility to fine-tune the facematch thresholds according to your risk and automation preferences. This allows you to reject or manually review cases based on your specific criteria.

Step 2: Integrate

Facematch will seamlessly operate for all available sources, requiring no additional integration effort, except for Merchant's own Database.

Integrating Facematch using Merchant's own Database

In order to use your own file in the facematch process you need to follow the following steps at verification time:

  1. Enable a public link to the file containing the face you want to compare. This can be a temporary link that lasts only the required time to run the facematch process.
  2. Hash the public file URL with your MetaMap client secret using SHA-256 algorithm.
  3. When creating the verification process, send in the Metadata object the following tags:
    1. userPhotoLink: The public file URL
    2. userPhotoLinkHash: The hashed string obtained in step 2

This way the platform will take the shared user photo and compare it with the other photo source you selected.

To use your own photo file in the facematch process during verification, please follow these steps:

  1. Enable a public link to the file containing the face you want to compare. You can generate a temporary link that will remain valid only for the required time to run the facematch process.
  2. Hash the public file URL with your MetaMap client secret using the SHA-256 algorithm.
  3. When creating the verification process, include the following tags in the Metadata object:
    1. userPhotoLink: The public file URL.
    2. userPhotoLinkHash: The hashed string obtained in step 2.

By following these steps, the platform will be able to access the shared user photo and perform the facematch with the other selected photo source.

Integrate using Direct Link

Add Metadata object as parameter to the Direct Link URL.

https://signup.getmati.com/?merchantToken={{clientId}}&flowId={{flowId}}&metadata={"userPhotoLink":"{{publicFileURL}}","userPhotoLinkHash":"{{hashedString}}"}

Integrate using SDK

Web SDK

Add Metadata object to the Web SDK script

<script src="https://web-button.getmati.com/button.js">
  </script><mati-button
id="mati_button"
clientid="{{clientId}}"
flowId="{{flowId}}"
metadata='{
		"userPhotoLink": "{{publicFileURL}}",
		"userPhotoLinkHash": "{{hashedString}}"
}'
 />

Android SDK

Add userPhotoLink and userPhotoLinkHash parameters in the Metadata object as explained here.

iOS SDK

Add userPhotoLink and userPhotoLinkHash parameters in the Metadata object as explained here.

Integrate using API

Creating the verification flow instance

When calling the Start Verification API endpoint add the Metadata object in the request body.

{  
  	"flowId": "{{flowId}}",  
    "metadata": {
        "userPhotoLink":"{{publicFileURL}}",
        "userPhotoLinkHash":"{{hashedString}}"
        }
}

Step 3: Facematch results

Dashboard

The dashboard will display the score, indicating the level of similarity between the compared faces, and it will also show the images used in the Facematch process for your reference.

Webhooks

To ensure proper functionality, you must configure your webhooks and handle the webhook responses that will be sent to your designated webhook URL.

For this Facematch service you will receive a webhook with a facematch-service-validation step id. This webhook contains the score obtained from the facial comparison under the facematchScore tag as well as links to the biometric media files. Find samples for successful and unsuccessful results in the following box:

{
  "metadata": {
    "userPhotoLink": "https://storage.domain.com/user-photo.png",
    "userPhotoLinkHash": "f401b1177a08dc5faf75885bcca98ef88c482478bbc74580f48015c3d43e4303"
  },
  "resource": "https://api.getmati.com/v2/verifications/64c984419e1654001be12079",
  "step": {
    "status": 200,
    "id": "facematch-service-validation",
    "data": {
      "facematchScore": "100.000",
      "sources": [
        {
          "type": "merchantDatabase",
          "url": "https://storage.domain.com/user-photo.png"
        },
        {
          "type": "biometrics",
          "url": "https://media.getmati.com/file?location=eyJhbGciOiJIUzI1NiIsInR5...",
          "isSpriteSet": false
        }
      ]
    },
    "error": null
  },
  "eventName": "step_completed",
  "flowId": "64c93fa13cb8e83001c2941dd",
  "timestamp": "2023-08-01T22:17:03.645Z"
}

{
  "metadata": {
    "userPhotoLink": "https://storage.domain.com/other-user-photo.png",
    "userPhotoLinkHash": "85f21bb0ddc85a87d603d4562660d2639aa73e19448438595b0600f35959381a"
  },
  "resource": "https://api.getmati.com/v2/verifications/64a9864f8db6b0001b4b68c8",
  "step": {
    "status": 200,
    "id": "facematch-service-validation",
    "data": {
      "facematchScore": "29.913",
      "sources": [
        {
          "type": "merchantDatabase",
          "url": "https://storage.domain.com/other-user-photo.png"
        },
        {
          "type": "biometrics",
          "url": "https://media.getmati.com/file?location=eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
          "isSpriteSet": false
        }
      ]
    },
    "error": {
      "type": "StepError",
      "code": "differentPerson",
      "message": "There are different persons on photos"
    }
  },
  "eventName": "step_completed",
  "flowId": "64c93fa13cb8e83001c2941dd",
  "timestamp": "2023-08-01T22:26:11.955Z"
}

Updated over 1 year ago