Skip to main content

Verification Transactions

The Verified platform can verify the actual identity of a user engaging in high-risk, high-value activities by comparing the results of a biometric MFA request to the reference biometric credential that is stored for their account. This process is also known as a verification transaction.

Logical Sequence​

1 - Start Verification Process​

When your platform workflows determine that a user is attempting to engage in high-risk, high-value activities, or other various fraud risk signals are activated, you can use Verified to initiate a verification transaction to confirm that the actual account holder is attempting to complete this activity.

2 - Verify User Biometry​

After you have captured the result of a verification transaction, you can use this data to compare against the reference biometric credential stored in the Verified platform. The platform will provide 1:1 facial matching analysis and confirm or deny the identity of the user, which you can then use in your workflow.

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: Authorization API

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 Verification Transaction​

In your backend, call the BeginForeignAuthorization API endpoint.

Reference the AccountNumber for a user. If you are utilizing Verified's selfie transaction capability, this would be the value you provided during the Create Account step.

Example request body:

{
  "Name":"Verify_Identity",
  "TimeoutSec": 3600,
  "PhoneNumber": "",
  "Email": "",
  "TransportType": 0,
  "FacialImageAccountNumber":"MyAccount",
  "CheckLiveness": true
}

The Name parameter refers to the transaction template you wish to use.

TransportTypeDescription
0Inline
1SMS
2Email

You need to store the following parameters from the response:

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

Response body

{
  "OneTimeSecret": "os5GkOMmH4+a+FGyRQvY3Q==",
  "TransactionId": "3c835202-4182-84a6-083d-2f11f572b0e2",
  "Status": 0,
  "Message": "Transaction is pending for authorization.",
  "StartDate": "2021-10-14T02:23:47.397Z",
  "EndDate": null,
  "ConfirmationLevel": 0,
  "ConfirmationAdditionalData": null
}

3 - Display UI for Data Capture​

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

4 - Get Verification Transaction Result​

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

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

5 - Analyze Transaction Result​

If the status changes to 1 "Accepted", the user has verified the transaction successfully, and we've recorded user's consent.

In any other case of non-pending transaction status, the authentication has failed - the user could have ignored the request to authenticate (expired status), rejected the authentication, or failed to complete the authentication successfully.

Please see the Transaction Statuses help page for more information.

Successful example:

{
  "TransactionId": "ab4c9702-6d0e-44b1-c829-44628c11472b",
  "Status": 1,
  "Message": "Foreign transaction is authorized, accepted by user 'MyAccount'.",
  "StartDate": "2021-10-18T22:14:38.413Z",
  "EndDate": "2021-10-18T22:14:57.193Z",
  "ConfirmationLevel": 0,
  "ConfirmationAdditionalData": null
}

Failure examples:

Biometric authentication failed

{
  "TransactionId": "4cb05a40-03ef-a2dd-5cfc-5f64ba84bf7b",
  "Status": 2,
  "Message": "Transaction is not authorized, biometric credential verification failed for user 'MyAccount'.",
  "StartDate": "2021-10-15T15:42:44.353Z",
  "EndDate": "2021-10-15T15:45:23.92Z",
  "ConfirmationLevel": 0,
  "ConfirmationAdditionalData": null
}

User declined transaction

{
  "TransactionId": "068f8998-c4a6-6598-095d-2d0a8dc01eae",
  "Status": 2,
  "Message": "Foreign transaction is not authorized, rejected by user 'MyAccount'.",
  "StartDate": "2021-10-18T22:54:23.263Z",
  "EndDate": "2021-10-18T22:54:26.013Z",
  "ConfirmationLevel": 0,
  "ConfirmationAdditionalData": null
}