Authentication

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

URL

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

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

IP Restriction

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

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

CONNECT 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 CONNECT 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 CONNECT

The API endpoint will return a session token. Pass this token to your front-end to initialize CONNECT. Here are a few steps to help you upgrade your CONNECT 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 CONNECT 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 CONNECT is ready to display to your customer.
  • This event replaces the version 3 ready event
• Complete (method: onComplete() )
  • This event will tell you when CONNECT 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 CONNECT v4.

If you were receiving an inquiryId previously (from BankLOGIN+ or BankVERIFY+), you will still receive an inquiryId in the complete event of CONNECT 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 RIBBIT Support to ensure that your public IP addresses are added to the whitelist.