Authentication

To start using vConnect v4, ValidiFI will create new credentials that will be used only for vConnect v4. Please contact ValidiFI Support to have a new vConnect widget application created for your v4 integration.

URL

vConnect v3 uses a unique domain that is separate from our API. To simplify integration, vConnect v4 uses the standard test/sandbox URL:

Please reference the Moving to Production section for the production URL.

IP Restriction

As with all ValidiFI endpoints, the test environment is not IP restricted.

The production environment is IP restricted. Please contact ValidiFI to ensure that your public IP address is added to the whitelist.

vConnect API Endpoint

Please see https://apidocs.ribbit.ai for API documentation.

Here is the payload to send to the v4 API endpoint. The data provided is similar to v3, but the format/structure is different.

• clientId and clientSecret must use vConnect credentials. Do not use your API credentials.
• customerId is the customer or application reference ID from your system.
• firstName, lastName, emailAddress, phoneNumber, and address (and its child elements) are required.
  • businessName is only required when the referenced account is primarily used by the client for small business expenses.
• loanTerms value must be one of the following strings: daily_oblig, weekly_oblig, biweekly_oblig, monthly_oblig
  • We recommend that you hard code your portfolio median or average for the loanTerms, fullAmount, and amount fields.
• webhookURL is optional. If provided, it should be a fully qualified URL of your server. All events will be sent client-side and as webhooks to your webhook URL.
• notificationType can automatically send a link to the customer.
  • 0: No notification
  • 1: Link provided via SMS to the phone number in customer.phoneNumber field
  • 2: Link provided via email to the address in customer.emailAddress field

Integrate vConnect

The API endpoint will return a session token. Pass this token to your front-end to initialize vConnect. Here are a few steps to help you upgrade your vConnect v3 JavaScript to v4.

Replace the old script tag with the following init parameters:

<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' 
});

CONNECT.open();

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

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

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

Events

You should handle the following events:

• Launch (method: onLaunch() )
  • This event tells you when vConnect is ready to display to your customer.
  • This event replaces the version 3 ready event
• Complete (method: onComplete() )
  • This event will tell you when vConnect has completed. It will contain data that you may need to continue your process, such as an account token or inquiry id.
  • This single event replaces the following version 3 events: onEnrollmentSuccess, onRiskInquirySuccess, onFailedRiskInquiry, onClose
• BrowserLaunch
  • This event should be handled so that, when the user clicks a link that should open in a new browser tab, you can control how the browser tab is launched. This will be necessary for banks requiring oAuth authentication (e.g. Chase Bank), where the user is directed to the bank’s website for sign-in.
  • This event replaces (and acts identical to) the version 3 onBrowserLaunch event.

Results

All results from CONNECT function the same as version 3.

If you were receiving an accountToken previously, you will still receive an accountToken in the complete event of vConnect v4.

If you were receiving an inquiryId previously (from vInsightSync or BankVERIFY+), you will still receive an inquiryId in the complete event of vConnect v4.

You can use the accountToken and inquiryId in the same manner as you did with v3.

Move to Production

For a production deployment, target the prod subdomain.

IP Restriction

The production environment is IP restricted. Please contact ValidiFI Support to ensure that your public IP addresses are added to the whitelist.