# Data Connect Events source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md Note: For details of webhook events after generating a [report](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) through Data Connect, see [Report Events (Data Connect)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-dc/index.md) ## accountsDeleted {#accountsdeleted} | Name | Mastercard Data Connect Support | Description | |-----------------|---------------------------------|-----------------------------------------------------------------| | accountsDeleted | Data Connect Full | Sent when the specified accounts were deleted for the customer. | * JSON ```JSON { "customerId": "7043507659", "eventType": "accountsDeleted", "eventId": "1744671850866-f9b8ef21c571b7d0e80c2c3d", "payload": { "accounts": [ "7077265539" ], "institutionId": "101732" } } ``` ## added {#added} | Name | Mastercard Data Connect Support | Description | |-------|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | added | Data Connect Full / Data Connect Lite / Data Connect Fix (OAuth Institutions) | Sent after the customer lands on the eligible accounts page, and selects the account(s) they want to submit for their loan. The accounts are saved in the account's resource associated with the customer. | Note: If the institution supports OAuth connection, the `oauth` parameter value is true. For legacy connections this parameter is omitted or false. * JSON ```JSON { "customerId": "29272504", "eventType": "added", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732", "accounts": [ { "id": "30318", "number": "8000008888", "realAccountNumberLast4": "8888", "accountNumberDisplay": "8888", "name": "Auto Loan", "balance": -812.16, "type": "loan", "status": "active", "customerId": "29272504", "institutionId": "101732", "balanceDate": 1660295817, "createdDate": 1660295817, "lastUpdatedDate": 1660317422, "currency": "USD", "institutionLoginId": 4327, "displayPosition": 1, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Auto Loan", "marketSegment": "business" }, { "id": "30319", "number": "2000005555", "realAccountNumberLast4": "5555", "accountNumberDisplay": "5555", "name": "Home Mortgage", "balance": -812.16, "type": "mortgage", "status": "active", "customerId": "29272504", "institutionId": "101732", "balanceDate": 1660295817, "createdDate": 1660295817, "lastUpdatedDate": 1660317422, "currency": "USD", "institutionLoginId": 4327, "displayPosition": 7, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Home Mortgage", "marketSegment": "business" }, { "id": "30320", "number": "2000004444", "realAccountNumberLast4": "4444", "accountNumberDisplay": "4444", "name": "Roth IRA", "balance": 812.16, "type": "investment", "status": "active", "customerId": "29272504", "institutionId": "101732", "balanceDate": 1660295817, "createdDate": 1660295817, "lastUpdatedDate": 1660317422, "currency": "USD", "institutionLoginId": 4327, "displayPosition": 3, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Roth IRA", "marketSegment": "business" } ], "oauth": true } } ``` Tip: The `accounts` array provided in the webhook message provides details of each account which the end user has added via Data Connect (they may add more than one account). Each object within the `accounts` array will include an `institutionId` and `institutionLoginId` value, as well as other values such as the account ID and other information about the account. The webhook JSON also includes an `institutionId` value at the root of the message, before the `accounts` array. This represents the ID of the financial institution (FI) which was used to generate the Data Connect session. In certain situations, it is possible that the Data Connect session was used to add multiple accounts, potentially including accounts relating to more than one FI. We therefore recommend that you rely on the `institutionId` or `institutionLoginId` value returned within each element of the `accounts` array when requesting any further data about the account(s) that have been added. ## adding {#adding} | Name | Mastercard Data Connect Support | Description | |--------|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | adding | Data Connect Full / Data Connect Lite | Sent when a customer enters their sign-in information at a financial institution and selects which accounts Data Connect can access to verify their financial information. | Note: If the institution supports OAuth connection, the `oauth` parameter value is true. For legacy connections this parameter is omitted or false. * JSON ```JSON { "customerId": "29272504", "eventType": "adding", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732", "oauth": "true" } } ``` ## credentialsUpdated {#credentialsupdated} | Name | Mastercard Data Connect Support | Description | |--------------------|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | credentialsUpdated | Data Connect Full / OAuth **not** supported / Fix | Sent when the customer updates their sign-in information for a selected institution. The `mfa` field indicates whether the credential challenge was followed by a sequential true or false MFA challenge question. | * JSON ```JSON { "customerId": "29272504", "eventType": "credentialsUpdated", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732", "mfa": false } } ``` ## depositSwitchUpdate {#depositswitchupdate} | Name | Mastercard Data Connect Support | Supported Processes | Description | |---------------------|---------------------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | depositSwitchUpdate | Connect Transfer | Payroll Deposit Switch | Sent during the Connect Transfer flow (for deposit switching). The `switchId` field can be used later to obtain further details of a specific switch. The `switchStatus` field indicates the current state of progress (e.g., "completed", "failed") The `failureReason` field is only used in case of error, to indicate the problem encountered (e.g., "account-unusable", "bad credentials", etc.). The Connect Transfer user experience will show a suitable message to the end user so these `failureReason` values are just for information. | * JSON ```JSON { "customerId": "7020614888", "eventType": "depositSwitchUpdate", "eventId": "1728492399880-aa3fc8a4c7a0a5441f44ca2b", "payload": { "switchId": "6706b36911c92b37335b0287", "switchStatus": "completed", "createdDate": "2024-10-09T16:46:33Z", "authenticated": true, "provider": { "id": "5f0f23d0acd6870007be180d", "name": "Amazon Fulfillment" }, "distributions": [ { "type": "total", "bankIdentifier": "110000000", "accountNumberEndsWith": "3963" } ] } } ``` ## discovered {#discovered} | Name | Mastercard Data Connect Support | Description | |------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | discovered | Generate Data Connect Full / OAuth **not** supported | Sent after the customer has successfully signed in to an institution. All the customer's eligible accounts to permission are included in this event. The accounts in the payload of the subsequently added event are a subset of the accounts in the discovered event. If no accounts were discovered, then an empty array is sent. | * JSON ```JSON { "customerId": "29272504", "eventType": "discovered", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "accounts": [ { "id": 30318, "number": "8000008888", "name": "Auto Loan", "balance": -812.16, "type": "loan", "status": "pending", "institutionLoginId": 7013387278 }, "...", "..." ], "mfa": null, "institutionId": "101732" } } ``` ## documentUpload {#documentupload} | Name | Mastercard Data Connect Support | Description | |----------------|------------------------------------|---------------------------------------------------------| | documentUpload | Data Connect Full with MVS enabled | Sent after the user uploads a document in Data Connect. | * JSON ```JSON { "customerId": "6024675884", "eventType": "documentUpload", "eventId": "1681848508579-fbe4108b3b5f35bc3b32b594", "payload": { "assets": [ { "assetId": "dddd3961-cf13-4b0f-aa5c-f13e5ad2d87b-1323611256", "label": "lastPayPeriod" } ] } } ``` ## done {#done} | Name | Mastercard Data Connect Support | Description | |------|-----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | done | Data Connect Full / Data Connect Lite / Data Connect Fix / Connect Transfer | The **done** event is sent after the customer completes all necessary data connection requirements for the experience and the session ends. This could happen when the user ends the session by clicking **Submit** , exiting Data Connect via the **'X'** after connecting accounts, or letting the session time out after connecting accounts. The `eventTrigger` field will show the reason for the ending of the session (values can be `userSubmit`, `timeout`, `userExit`, or `userForceClose`). | * JSON ```JSON { "customerId": "29272504", "eventType": "done", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": {}, "eventTrigger": "userSubmit" } ``` ## institutionLoginDeleted {#institutionlogindeleted} | Name | Mastercard Data Connect Support | Description | |-------------------------|---------------------------------|----------------------------------------------------------------------------------------------------| | institutionLoginDeleted | Data Connect Full | Sent when all the accounts under the specified `institutionLoginId` were deleted for the customer. | * JSON ```JSON { "customerId": "6024675884", "eventType": "institutionNotFound", "eventId": "1681847896630-ff76b283cb9e47709583880b", "payload": { "query": "asld;kfjasdf", "supportedCountries": [ "US" ] } } ``` ## institutionNotFound {#institutionnotfound} | Name | Mastercard Data Connect Support | Description | |---------------------|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | institutionNotFound | Data Connect Full | Sent when the user searches for an institution that is not on our list. Data Connect provides the description for the `query` field. | * JSON ```JSON { "customerId": "29272504", "eventType": "institutionNotFound", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "query": "FinBank", "supportedCountries": [ "US" ] } } ``` ## institutionNotSupported {#institutionnotsupported} | Name | Mastercard Data Connect Support | Description | |-------------------------|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | institutionNotSupported | Data Connect Full / Data Connect Lite / Data Connect Fix | Sent when the user selects an institution that isn't certified. This applies to any call except for aggregation, fix, and voi-pp. | * JSON ```JSON { "customerId": "29272504", "eventType": "institutionNotSupported", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732" } } ``` ## institutionSupported {#institutionsupported} | Name | Mastercard Data Connect Support | Description | |----------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------| | institutionSupported | Data Connect Full / Data Connect Lite / Data Connect Fix | Sent when a user selects a financial institution from a search query that is certified for the product. | * JSON ```JSON { "customerId": "29272504", "eventType": "institutionSupported", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732" } } ``` ## invalidCredentials {#invalidcredentials} | Name | Mastercard Data Connect Support | Description | |--------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | invalidCredentials | Data Connect Full / Data Connect Lite / Data Connect Fix | Sent when the user enters incorrect sign-in information for the selected institution when using a legacy connection. This webhook is not sent for OAuth connections since this part of the user flow will be handled by the FI, not the Data Connect application. | * JSON ```JSON { "customerId": "29272504", "eventType": "invalidCredentials", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732" } } ``` ## mfa {#mfa} | Name | Mastercard Data Connect Support | Description | |------|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | mfa | Data Connect Full / Data Connect Lite | Sent when the user enters correct sign-in information for an institution and a Multi-Factor Authorization (MFA) challenge question displays when using a legacy connection. This webhook is not sent for OAuth connections since this part of the user flow will be handled by the FI, not the Data Connect application. | * JSON ```JSON { "customerId": "29272504", "eventType": "mfa", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732" } } ``` ## mfaUpdated {#mfaupdated} | Name | Mastercard Data Connect Support | Description | |------------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | mfaUpdated | Data Connect Fix | Sent when the user completed the MFA challenge question for an institution when using a legacy connection. This webhook is not sent for OAuth connections since this part of the user flow will be handled by the FI, not the Data Connect application. | * JSON ```JSON { "customerId": "29272504", "eventType": "mfaUpdated", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732" } } ``` ## ping {#ping} | Name | Mastercard Data Connect Support | Description | |------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ping | Data Connect Full / Data Connect Lite / Data Connect Fix / Connect Transfer | Sent when the Generate Data Connect URL APIs are called to verify that the webhook listener URL you provided is accessible. Your endpoint must return a 200 response or the Generate Data Connect URL call fails. | * JSON ```JSON { "eventType": "ping", "payload": {} } ``` ## processing {#processing} | Name | Mastercard Data Connect Support | Description | |------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | processing | Data Connect Full / Data Connect Lite / Data Connect Fix | **OAuth**: Sent after the user selects their accounts from an OAuth connection, and then gets redirected back to Data Connect. | * JSON ```JSON { "customerId": "29272504", "eventType": "processing", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "102176" } } ``` ## started {#started} | Name | Mastercard Data Connect Support | Description | |---------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | started | Data Connect Full / Data Connect Lite / Data Connect Fix / Connect Transfer | Sent when the Data Connect application is loaded and the landing web page is displayed. | * JSON ```JSON { "customerId": "29272504", "eventType": "started", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": {} } ``` ## unableToConnect {#unabletoconnect} | Name | Mastercard Data Connect Support | Description | |-----------------|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | unableToConnect | Data Connect Full / Data Connect Lite | Sent when a financial institution is unavailable (unknown reasons) and a connection isn't possible. **Error codes**: 102, 500, 900, 903, 904, 901, 910, 915, 916, and 920. | * JSON ```JSON { "customerId": "29272504", "eventType": "unableToConnect", "eventId": "1660148602272-c7cb9456479bdce2befc3424", "payload": { "institutionId": "101732", "code": 500 } } ```