title: Generate Data Connect URL
There are multiple options when it comes to generating a Data Connect URL for your customers to use. We cover the choices here, what functionality they provide, and when best to use them.
Data Connect Full
The Data Connect Full experience gives you all of the features available, and includes the ability to cater for joint borrowers within a single Data Connect session.
Features
- Terms and Conditions
- Search for the user’s Financial Institutions
- Sign-in (for multiple users in the case of joint borrowers)
- Select and manage one or more accounts
Data Connect Lite
Data Connect Lite is a minimalistic implementation of the Data Connect experience, providing a limited set of features. Data Connect Lite is a useful option if you want to handle the selection of Financial Institution and Account(s) in your own user experience.
Features
- Terms and Conditions
- Sign-in
Data Connect Fix
The Data Connect Fix option can be used to address the following scenarios:
- The connection to the user’s Financial Institution is lost.
- The user’s credentials were updated.
- The user’s MFA challenge has expired. Use Data Connect Fix →
Send Data Connect Email
The Send Data Connect Email option can be used to send an email with a Data Connect URL. This allows the user to complete their Data Connect session at a later stage.
The email contains a button which sends the user to a Full Data Connect flow when they click on it, and can also be used to generate a Data Connect URL suitable for joint borrowers.
How It Works
Data Connect allows customers to grant Finicity, a Mastercard company, authorization to access their financial data using their account credentials. This financial data is then made available to Partners utilizing the different Products that use Data Connect,
The Data Connect experience parameter allows you to configure parts of the Data Connect UI and functionality, see the Configure the Data Connect Experience section for more information. The redirectUri specifies where the customer will be redirected to once they have completed authentication at their Financial Institution and permissioned access to their accounts.
These endpoints require Authentication.
[!TIP]
If you are interested in using the Data Connect Transfer flow for setting up Deposit Switches or Bill Pay Switches, see the Deposit Switch and Bill Pay Switch documentation.
Session time-out
Data Connect URLs are valid for 2 hours after being generated. Once the customer opens the Data Connect experience, the session is valid for 1 hour after authentication. The Data Connect experience will display an alert after 5 minutes of inactivity (this is extended to 10 minutes if the customer is adding OAuth accounts to allow for time to interact with the bank’s website), and the session will terminate after 2 further minutes of inactivity.
Webhooks
When you are calling an API for generating a Data Connect URL you will be required to send a URL for receiving Data Connect Webhooks. These are notifications that are sent to the webhook URL when different events occur during the Data Connect flow, see Data Connect Webhook events for a list of these.
[!TIP]
For testing purposes you can use commonly used online tools like webhook.site, requestbin.com, beeceptor.com, or other tools that will receive webhooks and post the content for you to review (note that this is not an official endorsement for any of these services). In production you must use your own secure webhook service.
[!NOTE]
If we get a 200 HTTP response from your webhook listener server, the webhook event is registered as a success. For any non-200 HTTP status code (failed event), we will resend the webhook.
Our retry logic will function for 3 days with an exponential back-off, meaning we will try multiple times within the first few minutes followed by a retry every hour for 72 hours. The exact instances of each retry within the first few minutes are as follows: 12ms, 72ms, 432ms, 2592ms, 15552ms, 93312ms.
[!NOTE]
Chase bank (JPMorgan Chase) has removed support for certain types of WebView traffic. For more information see the Chase Developer documentation
Software Development Kits (SDKs)
Once you have generated a Data Connect URL you’ll need to provide a front end experience for your customers to grant permissions on their financial accounts. The web and mobile SDKs provide you with encapsulated tools to make this easy. See Integrating with Data Connect.
Data Connect Full Flow
The following is an example of a Data Connect Full flow (for simplicity, webhook events are not shown in this diagram):
Financial Institution End User Partner image/svg+xml MastercardUser initiates the flow1Call POST/ connect/v2/generate2Response containing the Data Connect URL3Serve Data Connect URL4Searches and selects FI5Establishes link to FI6Display FI authentication screen7Authenticates FI8Successful FI authentication9Account selection screen (Checking , Savings etc. )10Account(s) selected11Summary/Review screen12Customer Clicks Submit13Display success screen14Return to partner application15 Financial Institution End User Partner image/svg+xml Mastercard
Data Connect Full (including for Joint Borrower)
Data Connect Full provides all the screens needed for the complete user experience. The Data Connect Full experience provides screens to allow the user to find and select their FI, sign-in, agree to the terms and conditions and privacy policy, and then select the account(s) that they want to connect to Open Finance.
You might already be familiar with the Generate Data Connect URL endpoint if you followed the Quick Start Guide.
Generate Data Connect URL
POST /connect/v2/generate
To generate a user experience which also covers joint borrowers, use the following endpoint:
Generate Data Connect URL – Joint Borrower
POST /connect/v2/generate/jointBorrower
Data Connect Lite
Data Connect Lite gives you the flexibility to build your own screens to allow the user to select the FI and account, with Mastercard hosting the Terms and Conditions and sign-in screens only.
In order to use Data Connect Lite you need to supply an institutionId. To facilitate this you can perform a search using the institutions endpoint given a search term from your customer. Once you have a customer select an institution from the list you will have the institutionId needed in the Data Connect Lite endpoint.
Get Institutions
GET /institution/v2/institutions
Once you have the institutionId for the institution concerned, pass it to the following endpoint in order to generate a sign-in screen which is appropriate to the FI. The user will also be prompted to accept the terms and conditions and privacy agreement before sign-in.
Generate Lite Data Connect URL
POST /connect/v2/generate/lite
Data Connect Fix
Data Connect Fix can be used when a problem occurs such as the connection to the user’s FI being lost. You will need the institutionLoginId relating to the user account in question (you can get this value using the Account Aggregation endpoints such as Get Customer Account by ID).
Not all connection issues can be resolved using Data Connect Fix. The Aggregation Status Code returned when you call one of the Account Aggregation endpoints will indicate what is causing the issue, and whether using Data Connect Fix will help.
The Data Connect Fix URL can be presented to the user to allow them to re-establish the connection with the FI.
Generate Fix Data Connect URL
POST /connect/v2/generate/fix
Send Data Connect Email
Instead of obtaining a Data Connect URL and displaying that link to the user directly, you can also generate an email containing a link which is sent to the user. The email includes a button which opens the Data Connect application.
You can specify the email’s subject, the name and company from which the email originates, the signature, and the customer’s name. Once sent, the Data Connect URL will be valid for 3 days, so the user has time to perform the Data Connect session when convenient to them.
Send Data Connect Email
POST /connect/v2/send/email
A second version of this endpoint is provided for joint borrowers:
Send Data Connect Email – Joint Borrower
POST /connect/v2/send/email/jointBorrower
Resources
- Status Codes display when something interrupts the process of the Data Connect application. The error code number and description can help you know what the issue is and how to resolve it.
- Data Connect Events are events sent from the Data Connect app through the SDK to your web and mobile apps.