# Mastercard Data Connect Components Examples source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccexamples/index.md The following sections dive deeper into the requests and expected responses for the Mastercard Data Connect Components endpoints. ## Configuration Objects (Optional) {#configuration-objects-optional} There are instances where it is important to specify a desired behavior during the user's journey through login, such as specifying which accounts you would like Mastercard to activate. To enable this, a Configuration object may be created. API Reference: `POST /connect-components/configurations` An example of a configuration object that can be used to filter accounts is as follows: **Request** ```curl curl --location --request POST 'https://api.finicity.com/connect-components/configurations' --header 'Finicity-App-Key: ' --header 'Accept: application/json' --header 'Finicity-App-Token: ' --data-raw '{ "filterAccounts": ["checking", "savings"] }' ``` **Expected Response** ```json { "id": "7b0d390d-1b51-4f5e-8e7b-d68c866ea257" } ``` The configuration id returned can then be provided to the OAuth or legacy institution login steps. ## Institution Logins - OAuth {#institution-logins---oauth} For financial institutions for which Mastercard maintains a direct connection, the calling application will leverage a tokenized OAuth flow. This flow begins by requesting an OAuth URL. The URL that is returned represents the location where the financial institution hosts the user login page. This URL must not be modified prior to displaying to the end-user. API Reference: `POST /connect-components/institutions/{institution_id}/oauth-urls` An example of a request for OAuth URL is as follows: **Request** ```curl curl --location --request POST 'https://api.finicity.com/connect-components/institutions/:institutionId/oauth-urls' --header 'Finicity-App-Key: ' --header 'Accept: application/json' --header 'Finicity-App-Token: ' --data-raw '{ "customerId": "4321234", "configurationId": "7b0d390d-1b51-4f5e-8e7b-d68c866ea257", // Optional "redirectURI": "https://your-app/oauth/redirect" "serviceAgreement": { "language": "en", "acceptedDate": "2024-11-28T18:25:32+00:00" } }' ``` **Expected Response** ```json { "id": "c315dc0d-fa08-488c-9601-77dea69acaeb", "url": "https://bank.example.com/oauth/login", "eventStreamId": "8859489f-12aa-4fd3-bcf5-ba0249e643a3" } ``` Once a URL is provided, there are several ways to present the contents to the user. * **Option 1: Pop Up** In this scenario, the OAuth login page is presented to the user via a newly opened popup window (i.e., window.open). This is the appropriate flow in cases where multiple open windows is acceptable, such as in a desktop web browser. In this flow, the calling application will stay active in the background, with the web SDK listening for events. For this scenario, there are two relevant events: `loggedIn` and `success`. * Logged In Event - This event is triggered once the user has completed the login flow with their financial institution. At this point, the calling application may close the popup window. * Success Event - This event is triggered when account discovery has completed and will contain the accountId, institutionId, institutionLoginId, and customerId associated with the login. See [Events](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#events) in the Data Connect Components Web SDK documentation for more information. * **Option 2: Redirection** In this scenario, the context in which the calling application is present will be replaced with the financial institutions login page (that is, `window.location.replace(...)`). This may be the appropriate approach in situations where having multiple open windows is not possible, such as in an embedded WebView element. The redirection flow presents a challenge not present in the pop-up flow. In this case, there is no web SDK instance open and available for events. Instead, when a user has completed the login with their financial institution, they will be redirected back to the redirectURI specified during the request to generate an OAuth URL. It will be the responsibility of the calling application to ensure that the web SDK is loaded in this newly redirected page. The web SDK will be needed for listening for the success event at the end of the flow. For this scenario, only the `success` event is emitted, with the redirection acting in place of the `loggedIn` event: * Success Event - This event is triggered when account discovery has completed and will contain the `accountId`, `institutionId`, `institutionLoginId`, and `customerId` associated with the login. See [Events](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#events) in the Data Connect Components Web SDK documentation for more information. ## Institution Logins - Legacy {#institution-logins---legacy} For legacy connections, that is connections that do not yet leverage tokenized access, a `legacyLoginForm` object must be obtained from Mastercard. API Reference: `POST /connect-components/institutions/{institution_id}/login-forms` Assuming the customer previously picked an institution with id: 1024, the `legacyLoginForm` object can be obtained as follows: **Request** ```curl curl --location --request POST 'https://api.finicity.com/connect-components/institutions/1024/login-forms' --header 'Finicity-App-Key: ' --header 'Accept: application/json' --header 'Finicity-App-Token: ' --data-raw '{ "customerId": "4321234", "configurationId": "7b0d390d-1b51-4f5e-8e7b-d68c866ea257", "customerViewedAcceptedTermsPolicies": "true" }' ``` **Expected Response** ```json { "id": "c315dc0d-fa08-488c-9601-77dea69acaeb", "eventStreamId": "8859489f-12aa-4fd3-bcf5-ba0249e643a3", "elements": [{ "id": "a41305f9-6a03-452a-af2f-e53f2be165b5", "label": "Username", "sortOrder": 0 }, { "id": "a2830724-c1df-4fee-904d-4535502f9d6e", "label": "Password", "sortOrder": 1 }] } ``` ## Form Elements {#form-elements} Each item in the `elements` property in the login form response represents a single `` element for a customer to interact with. It's important to note that the names and quantity of form elements returned depends entirely on the selected financial institution. For most institutions, two elements should be expected (one to capture a username and one to capture a password), but this is not always the case. Care should be taken to account for any variations. ### Rendering {#rendering} To present the elements to the user, Mastercard has provided a web SDK with custom web components. These web components provide a framework-agnostic way to encapsulate logic needed for these form elements, and give developers complete control over how and when to present these elements to a customer. To render the above example, a total of four elements would be needed: a single ``, two `` elements, and some means to submit the form, such as a ` ``` Of course, the above form only provides the absolute minimum needed to log a customer into their bank, but the form should be expanded upon to provide a rich, branded experience. **Expanded Example** ```html

By clicking submit, you agree to our Terms and Conditions and Privacy Policy

Forgot your password? Click here to reset it.

``` Note: The url to reset a password can be found on the `institution` object returned from the previous institution search call as `urlForgotPassword`. ## Submit Credentials {#submit-credentials} Because Mastercard retains full control of the contents of the `` elements, there is no direct way to submit those fields. Instead, calling the `submit()` method on the `` element will take care of that process and ensure that credentials never end up in the wrong hands. Below is an example of how to submit credentials: ```js // Based on the Expanded Example above const submitButton = document.querySelector('#submit-credentials'); const mastercardForm = document.querySelector('mastercard-form'); submitButton.addEventListener('click', () => { mastercardForm.submit(); }); ``` Once submitted, the SDK will emit appropriate events for `success`, `error`, or `mfaChallenge`. Each event will contain information needed for proceeding. For example, an MFAChallenge event will contain the information needed for rendering an MFA challenge form to the user. An error event will contain a code and message indicating the nature of the error encountered. A success event will contain basic account information, which can be used to make calls to additional Mastercard APIs. Any UI changes needed as part of this flow will need to be handled directly by the calling application. That is to say, the Data Connect Components SDK will not make any changes to UI as part of this flow. ## Errors {#errors} When an error is encountered during the login flow, this error will be captured and made available. The error will contain the needed information to guide the user in resolving the error, if resolvable. This includes cases where the user entered invalid credentials, for example. ## Multi-Factor Authentication {#multi-factor-authentication} When attempting to fetch account information for a customer, a financial institution may send back a multi-factor challenge that the customer must complete to continue the flow. ### Notification of an MFA Challenge {#notification-of-an-mfa-challenge} When an MFA Challenge is raised, an mfaChallenge event will be emitted and will contain the data needed for rendering said challenge, similar to how the credentials form elements for legacy connections work. ### MFA Challenge Types {#mfa-challenge-types} #### TFA_TEXT {#tfa_text} This challenge type will present a single input box to the customer and is commonly used for things like One-Time Passwords. **Expected Response:** ```json [ { "id": "3ea29b1a-0c2c-4052-a3e1-0cdb856163e8", "eventStreamId": "da03e052-915b-4ddc-9098-1ecbcc757bea", "mfaType": "TFA_TEXT", "prompt": "Enter name of your first pet.", "choiceIds": [ "28bc340a-3b84-4dd1-85eb-cfacf8e0a0e9" ] } ] ``` #### TFA_CHOICE {#tfa_choice} The `TFA_CHOICE` object represents a multiple choice question and answer selection, such as "Which of the following addresses has the primary account owner lived at in the past five years." **Expected Response** ```json [ { "id": "3ea29b1a-0c2c-4052-a3e1-0cdb856163e8", "eventStreamId": "da03e052-915b-4ddc-9098-1ecbcc757bea", "mfaType": "TFA_CHOICE", "prompt": "Which high school did you attend?", "choiceIds": [ "372e703a-70db-4cf1-8b1f-23be24c50d74", "eeecb2b8-c55a-4ce1-9fd0-ae560a363adb", "1c012d39-ebf3-46ea-a5fe-b6460400520b", "b4e727df-cf8d-42d3-bfe9-8456c0178077" ] } ] ``` #### TFA_MULTI {#tfa_multi} This challenge type will present the customer with multiple images to select from. **Expected Response** ```json [ { "id": "3ea29b1a-0c2c-4052-a3e1-0cdb856163e8", "eventStreamId": "da03e052-915b-4ddc-9098-1ecbcc757bea", "mfaType": "TFA_MULTI", "prompt": "Choose your favorite sport.", "choiceIds": [ "55684c30-ff18-4b2a-a7ab-7ed6d3fa3fc0", "2a395968-0610-44e7-a379-96d4bfbcd0d3", "2847e882-882e-4c18-8c89-309673dc730d", "52fcac64-0d3d-4e7f-aa0b-36d6be003b62" ] } ] ``` #### TFA_IMAGE {#tfa_image} A `TFA_IMAGE` challenge will present a captcha-style image that the customer will need to decipher. The prompt for this challenge is an image, with a single choice element being a text box to enter the deciphered image text into. **Expected Response** ```json [ { "id": "2f7069e5-751d-47c4-9f41-4f00089c0c56", "prompt": "", "mfaType": "TFA_IMAGE", "choiceIds": [ "89427fa8-1383-43b0-87c0-6df9d9709247" ] "eventStreamId": "38d75027-cc9e-4aaa-b828-86cace5bf2df" } ] ``` #### TFA_IMAGE_PROMPT {#tfa_image_prompt} This challenge type presents an image prompt in addition to a text prompt. This is the only MFA challenge type that contains the `promptImage` property. **Expected Response** ```json [ { "id": "3ea29b1a-0c2c-4052-a3e1-0cdb856163e8", "eventStreamId": "da03e052-915b-4ddc-9098-1ecbcc757bea", "mfaType": "TFA_IMAGE_PROMPT", "prompt": "Choose the correct response.", "promptImage": "", "choiceIds": [ "28bc340a-3b84-4dd1-85eb-cfacf8e0a0e9", "88fbb54f-5013-430b-9be8-46a0472464ca", "d86461aa-31eb-4eb0-a1d1-39595f4fc170", "4456f8d3-b546-4da6-bd52-075c8cfe2970" ] } ] ``` ## Submitting MFA Responses {#submitting-mfa-responses} The MFA Response flow will work the same as the legacy credential flow. Simply select the form element and call the `.submit()` method. At this point, either another `mfaChallenge` event will be emitted, or a success event. ## MFA Failures {#mfa-failures} In cases where a user fails to provide the correct MFA response, or an error occurs during the MFA flow, an error event will be emitted, similar to how other errors in the Data Connect Components flow operate. ## Initiate Reconnection (Data Connect Fix for Components) {#initiate-reconnection-data-connect-fix-for-components} For accounts that have an [Aggregation Status Code](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) that can be fixed by Data Connect Fix, use Initiate Reconnection. API Reference: `POST /connect-components/customers/{customer_id}/institution-login-ids/{institution_login_id}/reconnections` **Request** ```curl curl --location --request POST 'https://api.finicity.com/connect-components/customers/6021877507/institution-login-ids/6018508414/reconnections' --header 'Finicity-App-Key: ' --header 'Accept: application/json' --header 'Finicity-App-Token: ' --data-raw '{}' ``` **Expected Response** ```json { "id": "8d9d8f5e-2c5f-4f49-bf9b-276a7df0367f", "eventStreamId": "208a1170-875e-4656-85d0-27dfc3ee7137", "elements": [ { "id": "26410b1f-0347-4d57-bb03-f44d00e785e2", "label": "username", "sortOrder": 0 }, { "id": "f2ce62c2-877f-4c26-9935-d1ab6084e6d0", "label": "password", "sortOrder": 1 } ] } ```