Account Verification Integration

This page describes how to incorporate New Account Verification into your application.

New Account Verification checks your user’s personal information and verified identification documents, and then generates a vCrypt token during the account opening process. The service then returns a final decision about the risk associated with opening the new account.

This page includes the following information:

  • Prerequisites - Make sure you have the items defined in the Prerequisites section in place before implementing Account Verification.

  • Integration - Follow the step-by-step instructions in the Integration section to add Account Verification to your application.

Prerequisites

In order to implement Account Protect you must incorporate the following elements into your application:

  • Security - Set up encrypted data transmission and obtain your API credentials:
    • Encrypted Data Transmission - Your application must use TLS 1.2 or greater to protect information sent between your systems and Vesta.
    • API Credentials - Your API account name and password are available in vPortal. They are used to authenticate your requests to the Account Protect API.
  • Behavioral Analytics - Implement the Data Collector SDK as described in the Developer Resources section of this site. The Data Collector SDK sends user behavior data to Vesta and drives the vCrypt token generation and ID verification processes. You will need your Data Collector user ID, which is provided by Vesta during onboarding.
  • Device Fingerprinting - Implement Device Fingerprinting in your mobile or web app to collect data about the device used to access your services.
  • Account Protect API - Implement the Account Protect REST API as described in the Vesta API documentation. API requests must come from your system’s back end and cannot be sent from your user’s browser.
  • Webhook URLs - If your application uses webhooks to receive responses from Vesta, you must define the webhook URL during onboarding.

Vesta provides sandbox and production environments for developing and deploying your application. Sandbox credentials are available in vPortal, and production credentials are supplied once your application has passed the certification process.

Integration

The steps below describe how to incorporate Account Protect into your application’s New Account Verification workflow:

1. Request a Session ID

As soon as your app launches, send a POST request to the GetSessionTags endpoint of the Account Protect API.

Include the following information in the body of the request:

  • AccountName - Your API account name.
  • Password - Your API account password.
  • TransactionID - A unique identifier for this session. Generate this value on your system to track the session.

The resource returns webSessionID and OrgID values that you will use in subsequent steps.

See the GetSessionTags resource definition for details.

2. Initialize Data Collector

During app initialization, call the Data Collector start(); method.

The start(); method takes the following parameters:

  • Application - An instance of the current application.
  • webSessionID - The webSessionID value returned by the GetSessionTags resource.
  • LoginID - Your Data Collector user ID that was generated by Vesta during onboarding.

See the Data Collector SDK documentation for your platform for details about initializing Data Collector.

3. Generate a Device Fingerprint

Generate a Device Fingerprint to send detailed information about the customer’s device to Vesta. The specific steps depend on whether you are building a mobile or web app.

Mobile

The Device Fingerprinting integration generates the device fingerprint automatically. See the Device Fingerprinting Integrations page for details. Proceed with the next step.

Web

Pass the webSessionID and OrgID values that you obtained from the GetSessionTags response in step 1 to the HTML that you added to your site when you implemented Device Fingerprinting. Then run the code.

The sample code below shows where you must add the ID values, but you must use the correct HTML for your region, which is available on the Device Fingerprinting - Web Integration page:

<!-- Begin fingerprinting tags below -->

<p style="background:url(https://{regional-url}/DF/fp/clear.png?org_id="{OrgID}"&session_id="{WebSessionID}"&m=1)"></p>

<img src="https://{regional-url}/DF/fp/clear.png?org_id="{OrgID}"&session_id={WebSessionID}"&m=2" alt=""/>

<script src="https://{regional-url}/DF/fp/check.js?org_id="{OrgID}"&session_id="{WebSessionID}" type="text/javascript"></script>

<!-- End fingerprinting tags -->

You must generate a Device Fingerprint before the user submits new account information. It can take up to five seconds to generate a Device Fingerprint; therefore, ensure that the script is the last piece of the new account page to load, and disable the Submit button until the the page has loaded completely.

4. Send Vesta the New Account Information

Send a POST Request to the NewAccount API endpoint with account information in the body of the request. Use a form to collect the account details, and send the API request when your user clicks the submit button. See the NewAccount resource definition for details.

The response will include an EventID and an EventStatusText value.

  • EventID - A unique identifier for the event. Store the EventID value so that you can reference it when reviewing the final account status returned by Account Protect.
  • EventStatusText - Identifies whether you should Deny or Challenge the new account creation.
    • Deny - Vesta does not recommend opening the new account. Go to step 6 to notify Vesta of your decision by using the Disposition endpoint.
    • Challenge - Vesta recommends verifying the user’s identity. Proceed with the next step so that Vesta can run the ID Verification and vCrypt Tokenization services.

The NewAccount operation does not require a unique identifier for the account. If you do not generate a unique identifier for the account until the account is officially opened, use the UpdateConsumerAccount operation to send Vesta the account identifier once the account is created.

5. Notify your user to follow the ID Verification and vCrypt Token Generation steps

Display a screen that notifies your user that they will need to verify their ID and create a vCrypt token.

Your user will receive an SMS from the ID verification service. They must click the link in the SMS, download and install the ID verification app, and follow the instructions.

When ID verification is complete, your user will receive a notification on their device that requests permissions for biometric data. Your user must grant permissions and follow the instructions to create a vCrypt Token.

Once the ID verification and vCrypt tokenization processes are complete, Account Protect will generate a final status for the account.

6. Obtain the Final Status Via Webhook or API Request

Use one of the following methods to obtain Vesta’s final decision about the risk associated with the new account:

  • Webhook - Vesta sends the final status to the webhook URL that you provided during onboarding.

  • API Request - Send a POST request to the GetAccountEventStatus. Include the EventID that you obtained in step 3.

The final status will include an EventStatusText field with one of the following values:

  • Decline - Vesta does not recommend opening the account. Proceed with the next step to notify Vesta of your final decision.
  • Accept - Vesta has determined that the account is likely valid. Securely store the user’s account information and allow the user to access the features of the account. Proceed with the next step to notify Vesta of your final decision.

7. If needed, send Vesta the new account ID

If you decide to open the account, and if you did not include an account ID in the NewAccount request, send a POST request to the UpdateConsumerAccount endpoint with the account ID in the body of the request.

8. Notify Vesta of Your Decision

Send a POST request to the UpdateEventDisposition endpoint to tell Vesta whether you decided to open or deny the new account.

Since Vesta provides risk information, the final decision about whether to open the account is up to you. Notifying Vesta of the account status helps Vesta improve its fraud detection services. If in the future, you decide to close a previously opened account due to fraud concerns, send an additional request to the Disposition endpoint.