Migrate to Connect Web SDK 2.0

The 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 of upgrading the following features.

Contact your Sales Account Team to schedule an appointment to migrate.

Generate 2.0 Connect URL APIs

There are three Connect 2.0 endpoints to generate different types of Connect URL links. However, if you don’t want to send a Connect URL through the API, you can send an email instead.

  • 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://connect.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"
}'

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://connect.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
}'

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://connect.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
}'

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 which opens Connect.

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://connect.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://examople.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"
]
}
}'

Update 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/finicityconnect.min.js"></script> 

New Connect 2.0 Events

The new Connect 2.0 events provide additional payload information.

See Connect 2.0 SDK, Route, and User 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 existing Connect Webhooks are compatible with all 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"
}
}