Migrate to Connect Web SDK 2.0

Finicity’s Sales Engineers will help you migrate from Connect 1.0 to Connect 2.0 to ensure all the integration settings on Finicity’s end coincide with your settings.

The Connect 2.0 migration consists in:

Configuring a Connect experience
Generating V2 Connect URL Links
Upgrading to Connect Web SDK 2.0
Receiving new Webhooks events (optional)

Generate 2.0 Connect URL APIs

There are new Connect 2.0 endpoints to generate Connect URL links, depending on which Connect type you want to use in your applications. If you don’t want to send a Connect URL through the API, you can send an email instead.

Connect application options:

Connect Full
Connect Lite
Connect Fix
Send Connect Email

Connect Full

The Full version of Connect includes the following features:

Sign in, the user’s credentials and Multi-Factor Authentication (MFA)
Search for the user’s financial institutions
Manage the user’s accounts

Key differences between Connect 1.0 and 2.0.

Previously, when generating a Connect URL, the parameter type had to be specified, such as aggregation, voa, lite, fix, and more.
Now, the parameter experience is used to refer to the type of Connect experience for the session; the logo, brand color, application name and product, such as voa, voi, and more.
Finicity Sales Engineers will configure experience to default as part of the migration process.

Sample

 curl -L -X POST 'https://api.finicity.com/connect/v2/generate' \

-H 'Accept: application/json' \

-H 'Finicity-App-Key: {{APP_KEY}}' \

-H 'Finicity-App-Token: {{APP_TOKEN}}' \

-H 'Content-Type: application/json' \

--data-raw '{

"partnerId": "{{PARTNER_ID}}",

"customerId": "{{CUSTOMER_ID}}",

"redirectUri": "https://example.com/redirectHandler",

"webhook": "https://example.com/webhookHandler",

"experience": "default"

}'

See Generate v2 Connect URL API

Connect Lite

Connect Lite is a variation of Connect Full, which has a limited set of features.

Sign in, user’s credentials and Multi-Factor Authentication (MFA)
No user account management

The Connect Web SDK isn’t a requirement when using Connect lite. But, if you want to use the SDK events, and the routes and user events, then you’ll need to integrate with the Connect Web SDK. We also recommend using our Connect Best Practices to get the most out of Connect Lite.

Sample

 curl -L -X POST

'https://api.finicity.com/connect/v2/generate/lite' \

-H 'Accept: application/json' \

-H 'Finicity-App-Key: {{APP_KEY}}' \

-H 'Finicity-App-Token: {{APP_TOKEN}}' \

-H 'Content-Type: application/json' \

--data-raw '{

"partnerId": "{{PARTNER_ID}}",

"customerId": "{{CUSTOMER_ID}}",

"redirectUri": "https://example.com/redirectHandler",

"webhook": "https://example.com/webhookHandler",

"institutionId": 101732

}'

See Generate v2 Lite URL API

Connect Fix

Use the connect fix endpoint when the following conditions occur:

The connection to the user’s financial institution is lost
The user’s credentials were updated (any number of reasons)
The user’s MFA challenge has expired

Sample

 curl -L -X POST 'https://api.finicity.com/connect/v2/generate/fix

\

-H 'Accept: application/json' \

-H 'Finicity-App-Key: {{APP_KEY}}' \

-H 'Finicity-App-Token: {{APP_TOKEN}}' \

-H 'Content-Type: application/json' \

--data-raw '{

"partnerId": "{{PARTNER_ID}}",

"customerId": "{{CUSTOMER_ID}}",

"redirectUri": "https://example.com/redirectHandler",

"webhook": "https://example.com/webhookHandler",

"institutionLoginId": 1011648032

}'

See Generate V2 FIX Connect URL API

Send Connect Email

Rather than sending a Connect URL through the API, you can send an email to the consumer that includes a Connect link. The email includes a button that opens the Connect application.

The key differences between Connect 1.0 and 2.0.

Previously, when generating a Connect URL, the parameter type had to be specified, such as aggregation, voa, lite, fix, and more.
Now, the parameter experience is used to refer to the type of Connect experience for the session, such as the logo, brand color. application name and product, such as voa, voi, and more.
Finicity Sales Engineers will configure experience to default as part of the migration process.

Sample

 curl -L -X POST 'https://api.finicity.com/connect/v2/send/email' \

-H 'Accept: application/json' \

-H 'Finicity-App-Key: {{APP_KEY}}' \

-H 'Finicity-App-Token: {{APP_TOKEN}}' \

-H 'Content-Type: application/json' \

--data-raw '{

"partnerId": "{{PARTNER_ID}}",

"customerId": "{{CUSTOMER_ID}}",

"consumerId": "{{CONSUMER_ID}}",

"redirectUri": "https://example.com/redirectHandler",

"experience": "default",

"email": {

"to": "bob@example.com",

"supportPhone": "800-555-5555",

"subject": "Verify your income",

"firstName": "Bob",

"institutionName": "Acme Lending",

"institutionAddress": "222 Winnipeg Drive SLC UT, 84109",

"signature": [

"Cindy Mayfield",

"Senior Loan Officer",

"Direct 123-456-7890"

]

}

}'

See Send V2 Connect Email API

Upgrade to Connect Web SDK 2.0

The Connect Web JavaScript tag to access the SDK library has changed. Use the following tag.

Sample

 <script src="https://connect2.finicity.com/assets/sdk/finicity-connect.min.js"></script>

New Connect 2.0 Events

The new Connect 2.0 events provide additional payload information.

See Connect 2.0 SDK and Route Events

Modified Parameter and Methods

The redirectUri parameter cannot be used if you embed Connect in an iFrame.

The following methods have been renamed in Connect 2.0.

connectIframe is now launch
destroyIFrame is now destroy

Webhooks

All webhooks on the Webhook Events List page are compatible with all of the Connect 2.0 SDKs with the exception of two webhooks. The following webhooks are used exclusively in Connect 2.0 for the Account Management feature.

Accounts Deleted
Institutions Login Deleted

Note: The Account Management feature isn’t required for the initial Connect 2.0 integration. You can disable the feature as needed.

Accounts Deleted

The accountsDeleted event indicates that the specified accounts were deleted for the customer

Sample

 {

"customerId": "1008650161",

"eventType": "accountsDeleted",

"eventId": "1594221522744-83455a87160c45b897058b04",

"payload": {

"accounts": [

"1024371952"

]

}

}

Institution Login Deleted

The institutionLoginDeleted webhook event indicates that all of the accounts under the specified institutionLoginId were deleted for the customer.

Sample

 {

"customerId": "1008650161",

"eventType": "institutionLoginDeleted",

"eventId": "1594221557396-19ef569f7fbfa65488283b81", "payload":

{

"institutionLoginId": "1011648058"

}

}