Onboarding

This page describes how to set up your web or mobile application to begin using Account Protect:

  • Requirements - The Requirements section provides an overview of the security and implementation details you will need to incorporate in your application to use Account Protect.

  • Security - The security section provides information about obtaining the credentials required to access the Account Protect services.
  • Implementation - The implementation section provides step-by-step instructions for incorporating Account Origination, Account Update, and Login protection in your application.

Requirements

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

  • API Credentials - Your API account name and password are are available in vPortal. They are used to authenticate your requests to the Account Protect API.
  • Encrypted Data Transmission - Your application must use TLS 1.2 or greater to protect information sent between your systems and Vesta.
  • Behavioral Analytics - Implement the Data Collector SDK as described in the Developer Resources section of this site.
  • Account Protect API - Implement the Account Protect REST API as described in the Vesta API documentation. You will access different API resources depending on the Account Protect workflow that your are building.

Security

Vesta generates API credentials, which you must use to authenticate calls from your system to Vesta’s APIs. All data sent to Vesta must be encrypted using TLS 1.2 or greater, which ensures your organization’s security and your customer’s privacy.

API Credentials

When you sign up for Account Protect, Vesta generates your API credentials and gives you access to the Vesta customer portal. You will use your API credentials to authenticate all of your requests to Vesta’s APIs. Log in to vPortal and navigate to the Account Info page to obtain your API Credentials, as shown below:

vesta_creds

Implementation

The sections below describe how to incorporate Account Protect into you application’s New Account Opening, Account Update, and Login workflows. Account Protect requires implementation of the following Vesta backend services:

  • Behavioral Analytics - Use the Vesta Data Collector SDK or Javascript methods to add Behavioral Analytics to your application. In addition to tracking behavioral data, the Data Collector SDK drives the ID Verification and vCrypt Tokenization services.
  • Account Protect API - Use the Account Protect REST API to send user information and obtain risk assessments about the account or action.

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.

Development Overview

The sections below describe how to incorporate Behavioral Analytics, ID Verification, and vCrypt Tokenization services into your application. Each of these services is required as part of the Account Protect implementation. Depending on your development platform, code is available in the Developer Resources section of this site.

Behavioral Analytics

Vesta uses a session ID to track a customer’s shopping behavior to assess whether they are committing fraud. Our Behavioral Analytics tools rely on our Data Collector integrations, which are discussed in detail in the Developer Resources section of this site. The steps below describe how to implement Behavioral Analytics. All of the required code is provided by Vesta:

  1. Follow the instructions for including the Data Collector libraries in your application. The instructions are specific to your development platform.
  2. Add code that initializes Data Collector by running the stat(); method when your application launches. The start(); method will return a WebSessionID and an OrgID. Initializing Data Collector also drives the ID Verification and vCrypt Token Binding services described in the sections below.
  3. Add code to each screen in your application that accepts the WebSessionID and OrgId as attributes. The code passes the IDs to Vesta to create a history of your customer’s behavior.
  4. Add field tagging and event code to your application to track button clicks and data entry in your application.

ID Verification

ID Verification is triggered by the Data Collector during the account opening process. You will need to add a screen to your application that alerts the user that ID Verification is required.

The ID Verification service sends an SMS to your user to begin the process. Your user will download and install the ID Verification app and follow the instructions in the app.

When the user has completed the ID Verification process, the results will be available via webhook or API request.

vCrypt Token Binding

vCrypt Token creation is triggered when you initialize the Data Collector SDK when a customer first accesses your application.

If your user’s device does not already have an associated vCrypt token, the vCrypt Token service will launch during Account Opening. Your user will receive a notification that requests access to the devices biometric data.

Add a screen to your application notifying the user to complete the vCrypt Token generation process. The results of the token generation will be returned to a webhook URL. Add a screen to your application that notifies the user of the results of the token creation.

If your user’s device does have an associated vCrypt token, it will be accessed as part of the multifactor authentication procedure during the login and account update workflows.

Account Protect REST API

Send requests to the Account Protect REST API endpoints to initiate the Account Protect services when your user performs any of the protected activities. You must send requests to the API from your server. Vesta APIs will not accept requests from your user’s browser.

For the workflows described below, you will use the following operations:

  • NewAccount - Initiates new account opening verification.
  • LoginAttempt - Initiates login verification.
  • ChangeAddress - Initiates address update verification.
  • ChangeEmail - Initiates email update verification.
  • ChangePhoneNumber - Initiates phone number update verification.
  • GetAccountEventStatus - Returns the final decision about any of the protected activities.

The Account Protect REST API provides additional operations that support more sophisticated workflows. See the API Specifications for details.

Workflows

The sections below describe how to implement Account Protect as part of the following workflows: Account Opening, Account Update, and Login.

Account Opening

The account opening workflow verifies your user’s personal information and ID documents, and creates a vCrypt Token for additional security. The process returns a customer due diligence report and a decision (allow, deny, or challenge) related to the new account.

Complete the steps below to implement the account opening workflow in your application:

  1. If you are using webhooks, you must define a webhook URL during the onboarding process that you will use to receive status messages about the account risk.

  2. Incorporate Behavioral Analytics into your application. See the Data Collector page in the Developer Resources section of this site for details.

  3. Perform the following actions when your app initializes:

    • Initialize the Data Collector SDK by calling the start(); method.

    • Send a POST request to the GetSessionTags endpoint of the Account Protect API. You must send the request from your backend server. The resource will return a session ID that will be used to track your user’s behavior.

  4. When your user wants to create a new account, display a form that collects the new account information such as username, email address, and phone number. See the NewAccount operation definition in the Account Protect API specifications for a list of new account information that Vesta needs to verify the user’s identity.

  5. When your customer clicks a button to submit new account information, Send a POST request to the NewAccount endpoint of the Account Protect API.

    You must include the new account information in the body of the request. The resource will return 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.

    If the EventStatusText value is Deny, Vesta does not recommend opening the new account. Notify Vesta of your decision by using the Disposition endpoint, as described in the final step below.

    If the EventStatusText value is Challenge proceed with the next step so that Vesta can run the ID Verification and vCrypt Tokenization services.

  6. 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.

  7. Obtain the final status via webhook or API request:

    • Webhook - Vesta sends the final status to the webhook URL that you provided during onboarding.
    • API Request - Send a POST request to the GetAccountEventStatus.

    The final status will include an EventStatusText value that defines whether you should Accept, Decline, or Challenge the new account creation.

    If the value is Decline, Vesta does not recommend opening the account.

    If the value is Accept, securely store the user’s account info and allow the user to access the features of the account.

  8. Notify Vesta whether you accepted the new account by sending a POST request to the Disposition endpoint. If the account status changes in the future, send an additional request to the Disposition endpoint to update Vesta. Notifying Vesta of the account status helps Vesta improved its fraud detection services.

Login

The login workflow use Behavioral Analytics and multifactor authentication to verify you user’s identity when attempting to access your applications services.

Complete the steps below to implement the login workflow in your application:

  1. If you are using webhooks, you must define a webhook URL during the onboarding process that you will use to receive status messages about the account risk.

  2. Incorporate Behavioral Analytics into your application. See the Data Collector page in the Developer Resources section of this site for details.

  3. Perform the following actions when your app initializes:

    • Initialize the Data Collector SDK by calling the start(); method.

    • Send a POST request to the GetSessionTags endpoint of the Account Protect API. You must send the request from your backend server. The resource will return a session ID that will be used to track your user’s behavior.

  4. Perform the following actions when your customer clicks a login button after filling out the username and password fields:

    • Send a POST request to the LoginAttempt endpoint with login info in the body of the request. Vesta will analyze the data and return a decision and return a EventID and EventStatusText values:

      • EventID - A unique identifier for the event. Store the EventID value so that you can reference it when reviewing the final status returned by Account Protect.
      • EventStatusText - Identifies whether you should Accept, Decline, or Challenge the login attempt.

      If the decision is Accept, allow the user to log in to the account.

      If the decision is Decline, Vesta does not recommend allowing the user to access the account. Notify the account owner of a potential fraudulent log in attempt and provide a way to update and verify the account information.

      If the decision is Challenge, proceed with the next step.

  5. Display a screen stating that the user must follow the identity verification instructions by using biometric sensors on the device.

    The user’s device will issue a notification with instructions for verifying the biometric info. Account Protect will verify the user’s identity, and provide a decision via webhook or API operation:

    • Webhook - Vesta sends the final status to the webhook URL that you provided during onboarding.
    • API Request - Send a POST request to the GetAccountEventStatus with the EventID that was returned by the initial Account Protect API request.

Account Update

The account update workflow protects you users from account takeover fraud by verifying the user’s identity when suspicious changes are made to account information.

Complete the steps below to implement the account update workflow in your application:

  1. If you are using webhooks, you must define a webhook URL during the onboarding process that you will use to receive status messages about the account risk.

  2. Incorporate Behavioral Analytics into your application. See the Data Collector page in the Developer Resources section of this site for details.

  3. Perform the following actions when your app initializes:

    • Initialize the Data Collector SDK by calling the start(); method.

    • Send a POST request to the GetSessionTags endpoint of the Account Protect API. You must send the request from your backend server. The resource will return a session ID that will be used to track your user’s behavior.

  4. Implement the Login steps defined in the Login section of this page.

  5. Once your user has logged in and selected an option to update account information, display a form that collects updated information.

  6. When your user clicks a button to submit updated account information, send requests to the appropriate Account Protect API endpoints:

    • ChangeAddress - If the user updates address information, send a POST request with the new address information in the request body.
    • ChangeEmail - If the user updates the email address associated with the account, send a POST request with the previous and new email address information in the request body.
    • ChangePhoneNumber - If the user updates the account phone number, send a POST request with the previous and new phone number in the request body.

    You must send a separate request for each type of information that is updated. Requests to the Account Protect API must be sent from your backend server and not from your user’s web browser.

    Account Protect will return an EventStatusText value for each change request:

    • Accept - The change does not appear to be fraudulent. Update the user’s account information as normal.
    • Decline - The change is likely fraudulent. Vesta does not recommend updating the account information. Notify your user of potential fraudulent account activity.
    • Challenge - The user’s identity should be verified. Proceed with the next step to verify the user’s identity using the devices biometric information.
  7. Your user’s device will display a notification with instructions about how to use biometric data to verify the user’s identity.

    Account Protect will verify the user’s biometric data and return a final decision via webhook or API request:

    • Webhook - Vesta sends the final status to the webhook URL that you provided during onboarding.
    • API Request - Send a POST request to the GetAccountEventStatus with the EventID that was returned by the initial Account Protect API request.

    The final decision will include an EventStatusText value. If the status is Accept, apply the updates to the user’s account.