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.
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.
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
OrgID values that you will use in subsequent steps.
GetSessionTags resource definition for details.
2. Initialize Data Collector
During app initialization, call the Data Collector
start(); method takes the following parameters:
Application- An instance of the current application.
webSessionID- The webSessionID value returned by the
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.
The Device Fingerprinting integration generates the device fingerprint automatically. See the Device Fingerprinting Integrations page for details. Proceed with the next step.
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:
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
EventID- A unique identifier for the event. Store the
EventIDvalue so that you can reference it when reviewing the final account status returned by Account Protect.
EventStatusText- Identifies whether you should
Challengethe 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
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.
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
EventIDthat 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