vConnect Widget

Integrates directly into your front-end so you can safely and securely verify and enroll accounts

Widget Integration Guide

v4.0

vConnect is a front-end user interface for all of ValidiFI's products and services. It can be used from our hosted environment or embedded into your website or mobile app.
This guide outlines the integration of vConnect into your platform. For details on our fully hosted solutions, click here.

You are viewing documentation for vConnect Version 4

v.4

v.3

Here's how it works

Call our API to initiate the vConnect widget
Load our JavaScript interface into your front end
Your user will connect their bank account using our intuitive user interface
Capture IDs by listening to events
Use the captured IDs to call our API to make payments, get account details, or see verification results

Configure vConnect

vConnect is fully customizable, from it's behavior, layout, coloring, wording, and decisioning.

Before integrating, please check out your customization options here!

Initiate vConnect

vConnect is initiated by calling our API

Environment

URL

Test

https://sandbox.RIBBIT.ai/v4/CONNECT/Session

Production

https://prod.RIBBIT.ai/v4/CONNECT/Session

Your credentials are different between test and production, and are also different for our API
Make sure you are using Widget Credentials

You must white-list your IP address when calling production endpoints

You will want to provide as much PII (personally identifiable information) as possible. The more information provided, the more accurately we are able to decision on the account

All fields are required for accurate results

Avoid submitting dummy or placeholder values in place of legitimate values, as this will have adverse affects on your future results

POST https://{environment}.RIBBIT.ai/v4/CONNECT/Session

{
    "token" : {
       "clientId" : "Your ValidiFI Client ID",
       "clientSecret" : "Your ValidiFI Client Secret"
    },
    "customer" : {
       "customerId" : "The unique Customer ID from your system",
       "firstName" : "John",
       "lastName" : "Smith",
       "emailAddress" : "test@noemail.com",
       "phoneNumber" : "1112223333",
       "address" : {
          "addressLine1" : "123 Main St",
          "city" : "Oxford",
          "state" : "OH",
          "zip" : "12345"
        }
    },
    "terms" : {
       "fullAmount" : 500,
       "amount" : 100,
       "loanTerms" : "biweekly_oblig"
    },
    "settings" : {
       "webhookURL" : "https://your.webhook.url/api (optional)",
       "bankId" : "1234567",
       "transactionHistoryDays" : 93
    },
    "notificationType" : 0
}

There are more parameters you can add to customize behavior, and additional customer data fields to submit additional customer data. For a full list of parameters, including detailed descriptions of all parameters listed above, click here.

token

Your Client ID and secret is an identifier and security key that identifies your application.
Do not expose these keys to the public
You can obtain your Client ID and Secret from the vConnect Home Page.
The vConnect Credentials are separate from your API credentials

customer

Provide the customerId that you use in your system to identify the customer. This may be an application or loan id if customer id is not available.
For accurate results, you must provide the customer's name, address, phone number, and e-mail address
Providing fake or placeholder data will adversely affect your future scoring!

terms

amount: The average (median) portfolio payment amount. For single transactions (not loans), use the transaction amount.

fullAmount: The full amount of the debt, or the average (median) full amount for the portfolio.

loanTerms: The repayment schedule / terms of the loan, or the average (median) terms offered in the portfolio. Available choices are daily_oblig, weekly_oblig, biweekly_oblig, or monthly_oblig

These fields are required.

notificationType

A link to your ValidiFI-hosted vConnect application can be sent directly to your customer. Send one of the following integers:

0: No notification
1: Link provided via email to the address in customer.emailAddress field
2: Link provided via SMS to the phone number in customer.phoneNumber field

settings

Custom settings can be provided to vConnect to alter it's behavior:

webhookURL - The URL to send events back to (your API). For details, see the section on vConnect Events.
bankID - The bankID of the bank to load. If provided, vConnect will automatically select the provided bank and lock the user into that bank. For details, see: vConnect Bank Lookup.
transactionHistoryDays - The number of days of transaction history that vInsights should consider. Default is 93.

Response

{
    "sessionToken" : "GUID",
    "customerId" : "GUID",
    "url" : "string",
    "expiration" : "datetime"
}

sessionToken

Capture the sessionToken and send it to your front-end to initialize vConnect
The sessionToken is the unique identifier for this session. It is a 36-character GUID, and is used to initialize vConnect or to reference activity within this session

customerId

The customerId references the unique customer data associated with this session. The customerId will be the customerId supplied to vConnect during the initial API call, unless no customerId was provided - in which case the customerId will be a new GUID.

url

This URL can be used by your customer to access the vConnect experience from our server. This URL is the URL that will be sent to the customer when you select notificationType = 1 (Email) or 2 (SMS).
For most integrations, you will not need this URL. If you want to send your customer a link to vConnect, hosted on our servers, and not use our built-in SMS or Email relay, then use this URL.

expiration

After the expiration date, the vConnect will no longer be valid. You will need to create a new session to continue.

Add vConnect to your User Interface

The API endpoint will return a sessionToken. Pass this token to your front-end to initialize vConnect.

Include this script tag:

<script src="https://cdn.ribbit.ai/widgets/v4/ribbit-connect.min.js"></script>

Then initialize vConnect with the following init parameters:

const CONNECT = new RIBBITConnect({ 
    target: 'ribbit-container',
    token: session_token,
    environment: 'Test',
    // Add optional parameters here. See below
});

CONNECT.open();

All Init Parameters

Name	Type	Default	Description
target*	string		ID of the element within the <body> which will contain vConnect
token*	string		Token recieved from /CONNECT/session/ endpoint
environment	string	Production	Declare as "Test" during integration to use the ValidiFI test environment. Remove or declare as "Production" when moving to production
language	string	en	Wording and display language can be modified Contact ValidiFI Support to discuss customizations
fullscreen	boolean	false	vConnect defaults to displaying as a vertical, mobile-sized floating element
inline	boolean	false	Whether or not vConnect should display inline (default is popup)
settings	object		Additional settings (see below)

* required

Settings

Name	Type	Default	Description
resize	boolean	false	If resize=true, vConnect resizes itself to fit its child content. Might be useful if inline=true
closeButton	boolean	false	Display an "x" close button on the top right of vConnect, allowing the user to directly initiate the `CONNECT.close()` method and the "exit" event
mobileWidth	int	650	If the width of the vConnect target element is reduced below this count of display pixels, vConnect will switch to fullscreen for a seamless mobile experience
canOpenNewWindows	boolean	true	Whether or not the vConnect interface can manage opening new browser windows. Used to handle OAuth and if a user clicks on any links. If this is not handled, you must handle the onLinkOpen event.

You can then capture events on the client side with the following:

CONNECT.onExit(eventData => { 
    CONNECT.close();
});

CONNECT.onComplete(eventData => { 
    console.log(eventData);
});

Listen for Events

When any action occurs within vConnect, we report these actions through events. By handling these events, you can capture the data returned and update your UI. Version 4 passes all events through a generic onMessage message handler, which includes the event name and the body or message where applicable.

The most common events are listed below. To see all events, click here

Complete

onComplete()

This event will tell you when vConnect has completed all enrollments and verifications and is ready to close. onComplete contains data that you may need to continue your process, such as an account token or inquiry id.

The following data is returned in this event when applicable

Account Token

Save this ID and use it any time you need to create a payment, get updated balance, or get transaction history

Verification Inquiry ID and Type

The success event contains an inquiry ID and inquiry type (BankLOGIN+ (vInsights) or BankVERIFY+). Save this ID and use it to see the details of the successful account verification, including attributes and scores. vInsights will be returned as "BankLOGIN+".

Account Information

Details such as account name, last 4 digits, and bank name can be used in your UI once vConnect has completed

Close behavior is completely customizable

vConnect can be customized to be a permanent, non-closing object in your UI, or to be a pop-up modal over your current content

Check your settings for a full list of options

CONNECT.onComplete = function(details) {
    console.log(details);
        // Put your code here to save the account token or verification data
        // Put code here to update your UI (green checkmark, displaying account details, etc.)
}

Webhooks

Instead of listening for events client-side, we can send the events to your server.
To use this option, send your URL in the webhookURL field when initializing vConnect.
When an event is fired, we will send you a webhook with the following data
If we do not receive a success (200) from your endpoint, we will retry once per hour, up to 24 attempts, before the webhook times out.

{
    "sessionToken": "vConnect Session Token",
    "eventDate": "2022-01-01T12:00:00.0000000Z",
    "eventName": "complete",
    "customerId": "Customer or Reference ID",
    "merchantId": 12345,
    "connectComplete": true,
    "connectType": "BankLOGIN",
    "inquiryId": "vInsights InquiryID",
    "inquiryType": "BankLOGIN+",
    "account": {
        "bankId": 12345,
        "bankName": "Full Bank Name",
        "accountNickname": "Sample Checking Account",
        "accountType": "Checking",
        "accountToken": "00000000-xxxx-xxxx-xxxx-000000000000",
        "last4Digits": "1234"
    }
}

Full Example

Call the vConnect endpoint from your back-end POST https://sandbox.RIBBIT.ai/v4/CONNECT/Session

{
    "token" : {
       "clientId" : "Your ValidiFI Client ID",
       "clientSecret" : "Your ValidiFI Client Secret"
    },
    "customer" : {
       "customerId" : "The unique Customer ID from your system",
       "firstName" : "John",
       "lastName" : "Smith",
       "emailAddress" : "test@noemail.com",
       "phoneNumber" : "1112223333",
       "address" : {
          "addressLine1" : "123 Main St",
          "city" : "Oxford",
          "state" : "OH",
          "zip" : "12345"
        }
    },
    "terms" : {
       "fullAmount" : 500,
       "amount" : 100,
       "loanTerms" : "biweekly_oblig"
    },
    "settings": {
        "webhookURL" : "https://your.webhook.url/api (optional)"
    },
    "notificationType" : 0
}

The result will bring back a sessionToken that should be passed to the front-end.

Front-end HTML page

    <html>
      <head>
        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
      </head>
      <body>
        <div id="vConnect"></div>
        <script src="https://cfsclientcdn01.blob.core.windows.net/
          widgets/v4/ribbit-connect.min.js"></script>
        <script>
          // initialize widget
          const CONNECT = new RIBBITConnect({
            target: 'connect', // ID of HTML element
            token: token_from_API
          });

          // open CONNECT
          CONNECT.open();

          CONNECT.onBrowserLaunch(url => {
              // handle new tab (e.g. OAuth login)
              window.open(url);
          });

          CONNECT.onComplete(eventData => {
            // save inquiry ID
            console.log(eventData)
          });

          CONNECT.onExit(eventData => {
              CONNECT.close();
          });
        </script>
      </body>
    </html>

Next Steps

Now that vConnect is integrated into your front-end, you will want to do something with it's results.
Choose an option:

Get Decisioning Information, including Scores and Attributes

vConnect automatically runs insights on the linked accounts. Click here to find out how to get these results.

Use a vInsights or BankVERIFY+ inquiryId and call our API

Advanced Startup Options

See details on launching vConnect and all available options

Events and Webhooks

Full list of all events and how to handle them, and instructions on using webhooks to receive events

All Done?

Testing Procedures

Details on how to test different scenarios for all products

Moving to Production

Find out what happens next before moving into production

Still need help?

Get a hold of us!

Send us a ticket with your questions to support@ValidiFI.com

We can answer your questions over e-mail or schedule a meeting with your team

Developer Docs