Account Monitoring Integration

This page describes how to incorporate Account Monitoring into your application.

Account Monitoring reviews behavior and device specifics associated with login and account update actions. The service returns a decision about the risk associated with the action so that you can decide whether to deny the action, verify the user’s identity, or allow the action to proceed.

This page includes the following information:

  • Prerequisites - Make sure you have the items defined in the Prerequisites section in place before implementing Account Monitoring.
  • Login Integration - Login monitoring watches login events, and if needed, issues a multifactor identification challenge. Follow the step-by-step instructions to add login monitoring to your application.
  • Account Update Integration - Account update monitoring watches for changes to a user’s account information such as address, contact information, or password changes. If needed the service issues a multifactor identification challenge. Follow the step-by-step instructions to add account update monitoring 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 passwordless multifactor verification features of Account Monitoring. 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.

Login Integration

The steps below describe how to incorporate Account Protect into your application’s login 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 - You API account password.
  • TransactionID - A unique identifier for this session. Generate this value on your system to track the session.

The resource will return 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 in step 1.
  • 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 login information. It can take up to five seconds to generate a Device Fingerprint; therefore, ensure that the script is the last piece of the login page to load, and disable the Log In button until the the page has loaded completely.

4. Send Vesta the Account Information

After your user enters a username and password and clicks the login button, send a POST request to the LoginAttempt endpoint with the account details in the body of the request. See the LoginAttempt resource definition in the Account Protect API documentation 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 decision returned by Account Protect.
  • EventStatusText - Identifies whether you should Accept, Decline, or Challenge the new account creation:
    • Accept - Allow the user to log in to the account.
    • Decline - Vesta does not recommend allowing the user to access the account. Notify the account owner of a potential fraudulent login attempt and provide a way to update and verify the account information.
    • Challenge - Vesta recommends issuing a multifactor identification challenge. Proceed with the next step.

5. Notify your user to follow the identification challenge steps

Display a screen stating that the user must follow the identity verification instructions.

The user’s device will issue a notification with instructions for verifying their identity. Account Protect will verify the user’s identity, and provide a final 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.

If Vesta is able to confirm the user’s identity, allow the user to log in.

Otherwise, Vesta does not recommend allowing the user to access the account. Notify the account owner of a potential fraudulent login attempt and provide a way to update and verify the account information.

6. Notify Vesta of the results

Send a POST request to the UpdateEventDisposition endpoint to notify Vesta about whether the login attempt was completed successfully or failed for some reason. The disposition is used to improve our fraud detection capabilities for your services.

Account Update Integration

The steps below describe how to incorporate Account Protect into your application’s account update 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 will return 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 in step 1.
  • 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:

<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c"%>

<!-- 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 updated 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 account update page to load, and disable the Submit button until the the page has loaded completely.

4. Send Vesta the Account Update Information

After your user enters updated account information and clicks a Submit button, send POST requests to one or more of the following endpoints, depending on the information that is being updated:

  • ChangeAddress - If the user updates address information, send a POST request with the new address information in the request body.
  • AddAddress - If the user adds a new shipping or billing address, send a POST request with the address and account identifiers 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.
  • AddPaymentMethod - Use this operation when the user saves a new payment method on their account. You must include the credit/debit card number, token, or BIN plus last 4 digits of the card number in the body of the request. Vesta will return a risk decision for this event.
  • RewardsRedeem - Use this operation to obtain a risk decision and initiate identity verification when a customer attempts to redeem rewards as part of your loyalty program.

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. See the Account Protect API documentation for details.

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, and do not perform step 5.
  • Decline - The change is likely fraudulent. Vesta does not recommend updating the account information. Notify your user of potential fraudulent account activity, and do not perform step 5.
  • Challenge - The user’s identity should be verified. Proceed with the next step to verify the user’s identity using the device’s biometric information.

5. Notify your user to follow the identification challenge steps

Display a screen stating that the user must follow the identity verification instructions.

The user’s device will issue a notification with instructions for verifying their identity. Account Protect will verify the user’s identity, and provide a final 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 endpoint with the EventID that was returned by the initial Account Protect API request.

If Vesta is able to confirm the user’s identity, update the user’s account information.

Otherwise, Vesta does not recommend allowing the user to update the account. Notify the account owner of a potential fraudulent activity and provide a way to update and verify the account credentials.

6. Notify Vesta of the results

Send a POST request to the UpdateEventDisposition endpoint to notify Vesta about whether the login attempt was completed successfully or failed for some reason. The disposition is used to improve our fraud detection capabilities for your services.