Pular para o conteúdo principal

Liveness - Rest PKI Core

  • Checks that a real person is present on the other side of the screen, detecting fraud attempts with photos, videos or masks.
  • It does not identify the person (who they are): it only attests the presence of a live human being.
  • The photo captured from the user can be retrieved at the end of the session.

Creating the session​

To create a liveness session, use the StartLivenessSessionAsync method of the client libs, passing a StartLivenessSessionRequest.

This method makes a POST request to /api/bio/sessions/liveness (Swagger).

Parameters (StartLivenessSessionRequest)​

ParameterRequired?TypeDescription
ReturnUrlConditional*StringURL to redirect the user to after the biometric check. (see details)
TrustedOriginConditional*StringURL of your site where the widget is embedded. (see details)
PlatformPreferenceNoEnumSets the platform preference and the QR code behavior. (see details)
SubjectIdentifierNoStringExternal identifier of the user. (see details)
FaceCaptureProviderNoEnumSets the biometric provider. (see details)
CaptureIdentificationDocumentNoBoolIf enabled, the user must capture an ID document right after the liveness check.
tip

*You must pass at least one of the two parameters (see the difference between ReturnUrl and TrustedOrigin):

  • ReturnUrl (for the redirect flow)
  • TrustedOrigin (for the widget)

Optional parameters can be left blank (null) and are filled in automatically with the system defaults.

note

Older samples use the FaceLivenessProvider parameter, which is obsolete: use FaceCaptureProvider. Rest PKI Core only takes FaceLivenessProvider into account when FaceCaptureProvider is not given.

Response example​

{
  "sessionType": "Liveness",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionUrl": "string"
}

Frontend integration​

Once your backend has obtained the sessionUrl from the API, forward it to your frontend. From there, the flow follows the interface you chose:

  • Embedded flow (widget): your application passes the URL to the JavaScript component, which starts the capture inside your page.

  • Redirect flow: your application sends the user to the URL received, where the capture takes place.

tip

If you are unsure how to implement each model, see Frontend flows.

Completing the session​

To complete a liveness session, use the CompleteLivenessSessionAsync method of the client libs, passing a CompleteBioSessionRequest.

This method makes a POST request to /api/bio/sessions/liveness/completion (Swagger).

This method is the final step. The ticket can be used only once.

tip

Call the completion only at the end of the process, sending the ticket you received to validate the result and close the session.

Response example​

{
  "faceLivenessStatus": {
    "provider": "FaceTecLiveness3d",
    "success": true,
    "attemptCount": 0
  },
  "idCaptureStatus": {
    "success": true,
    "matchedFace": true,
    "matchedFaceLevel": 0
  },
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}

Field details​

  • faceLivenessStatus:
    • provider: provider of the biometric service.
    • success: whether the liveness check succeeded.
    • attemptCount: number of attempts made by the user.
  • idCaptureStatus:
    • success: whether the document capture succeeded.
    • matchedFace: whether the person's face matched the photo on the document.
    • matchedFaceLevel: similarity level between the face and the document (MatchLevel).
  • sessionId: unique identifier of the session.
  • success: overall result of the session.
  • resultDataAvailable: if true, you can fetch the photos collected in the session.

Checking the session status​

You can check the current state of a session at any time using its sessionId. This is useful to monitor whether the user has started the session, or whether it has expired, even before it is completed.

tip

Use GetLivenessSessionStatusAsync to follow the progress of an active session by its sessionId.

The response of this endpoint is exactly the same as the response example of CompleteLivenessSessionAsync.

View as Markdown