--- title: Open Finance US service_id: open-finance-us auth_type: OpenBanking source_url: - html: https://developer.mastercard.com/open-finance-us/documentation/ - md: https://developer.mastercard.com/open-finance-us/documentation/index.md api_specification(s): - https://static.developer.mastercard.com/content/open-finance-us/swagger/openbanking-us.yaml --- Overview: Open Finance US is our suite of API-based services that enables secure, consumer-permissioned access to financial data and decisioning to power payments, money management, and lending use cases. Core capabilities include account aggregation with tiered data access, real-time or cached account balances, account owner verification with optional identity insights, transaction data enrichment, and bank account validation via microdeposits (Account Validation Assistant). We also provide predictive risk tools such as Payment Success Indicator for assessing NSF risk and Consumer Foresight for spend insights, benchmarking, and forecasting, alongside lending analytics and reports. The service helps reduce payment risk and improve approvals by combining real-time balance checks with predictive NSF scoring and explanatory attributes (PSI), and by validating routing/account details when users can’t or won’t link accounts (AVA). For lending, we evaluate account balances and cash flows, generate Payment History and Statement reports, and support small and medium business credit assessment. For personalization and PFM, Consumer Foresight delivers category-level historical trends, peer benchmarks, and future spend forecasts. Operationally, Client Hub surfaces financial institution connection health and invoice history, while Connect customization and UX guidance help deliver accessible, user-friendly consent and linking experiences. Note: some capabilities are premium or billable (for example, Get Available Balance live/cached, Consumer Foresight, and Statement Report), and PSI is for non-FCRA use cases with an FCRA variant available. - [Mastercard Open Finance US](https://developer.mastercard.com/open-finance-us/documentation/index.md) - [API Reference](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) - [Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/index.md) - [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) - [Invoice History](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/invoice-history/index.md) - [Institution Status](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/institution-status/index.md) - [Accessing the Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md) - [Client Hub Use Cases](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md) - [Customize Data Connect](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-customize-connect/index.md) - [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) - [Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/index.md) - [Integrating with Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md) - [Data Connect Errors](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-errors/index.md) - [SDK Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md) - [Data Connect Components Flows](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md) - [Non-SDK Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/index.md) - [iOS Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/index.md) - [Migrating to Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/migration/index.md) - [Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/index.md) - [Mastercard Data Connect Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/index.md) - [Web Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md) - [Android Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/index.md) - [Using Webviews via the Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/index.md) - [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) - [Using the Web SDK via Package Manager](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md) - [Using the Data Connect iOS SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md) - [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) - [Data Connect Components UX Guidelines](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md) - [Institution Settings](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md) - [Secure Web Containers on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/websdk-ios/index.md) - [Non-SDK Integration Guide for iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-ios/index.md) - [Data Connect Components Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md) - [React Native Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/react-native-sdk/index.md) - [Mastercard Data Connect Components Examples](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccexamples/index.md) - [Mastercard Data Connect Components Webhooks](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebhooks/index.md) - [Non-SDK Integration Guide for Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-android/index.md) - [React Native App Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/react-native/index.md) - [Using the Web SDK via CDN](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/web-sdk-cdn/index.md) - [Using the Data Connect Android SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md) - [Using Webviews with the Web SDK on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/ios-webviews/index.md) - [Data Connect iOS SDK Migration Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk-migration/index.md) - [Secure Web Containers on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/websdk-android/index.md) - [Data Connect Web SDK Migration Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/websdk-migration/index.md) - [Using Webviews with the Web SDK on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/android-webviews/index.md) - [Mastercard Data Connect User Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md) - [Mastercard Data Connect Route Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-route-events/index.md) - [Connect Web SDK Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-websdk-events/index.md) - [Data Connect Android SDK Migration Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk-migration/index.md) - [Customizing Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) - [Consent Management](https://developer.mastercard.com/open-finance-us/documentation/consent-management/index.md) - [Customer Records](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md) - [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) - [Full Error List](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) - [Most Common Error Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/most-common/index.md) - [Formats and Best Practices](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/index.md) - [Request Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/request-errors/index.md) - [Account Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/account-errors/index.md) - [Institution Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/institution-errors/index.md) - [Error Remediation Categories](https://developer.mastercard.com/open-finance-us/documentation/errors/error-remediation-categories/index.md) - [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) - [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md) - [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/bill-pay-switch/index.md) - [Accessibility Guidelines](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/accessibility-guidelines/index.md) - [Open Finance US for Account Opening and Funding](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/account-opening-and-funding/index.md) - [Open Finance US for Lending](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/index.md) - [Open Finance US for Payments](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/index.md) - [Automated Clearing House (ACH)](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ach/index.md) - [Account Validation Assistant](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md) - [Data Connect Enhancements and Features](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/index.md) - [Account Opening and Funding](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/account-opening/index.md) - [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-assets/index.md) - [Building a User-friendly FI Search Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/fi-search-experience/index.md) - [Returning User Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/returning-user-experience/index.md) - [Data Connect Fix Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/recall-experience-connect-fix/index.md) - [App to App Authentication Toolkit](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/app-to-app-auth-best-practices/index.md) - [Verification of Income and Employment](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-income-and-employment/index.md) - [Financial Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md) - [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md) - [Supported Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) - [Migrate Customers](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/migration-customers/index.md) - [Register Applications](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md) - [Glossary](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md) - [Testing and Integration](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/index.md) - [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) - [Using the Postman Collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) - [Generating an API Client Library](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/generating-an-api-client-library/index.md) - [API Basics](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md) - [Partnership Models](https://developer.mastercard.com/open-finance-us/documentation/participant-model/index.md) - [Partner Linked Access](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/index.md) - [Partner Direct Model](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md) - [Guide for Partners (Clients) - Recipient](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/index.md) - [Guide for Processors - Requestor](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/processor/index.md) - [Managing Affiliates](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/managing-customers/index.md) - [Client Steps](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/client-steps/index.md) - [Onboarding Affiliates](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md) - [Example - Using Dwolla as Payment Processor](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/example-dwolla/index.md) - [Manage Access Keys](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/manage-access-keys/index.md) - [Processor Steps](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/processor/processor-steps/index.md) - [Open Finance Products](https://developer.mastercard.com/open-finance-us/documentation/products/index.md) - [Pay](https://developer.mastercard.com/open-finance-us/documentation/products/pay/index.md) - [Lend](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) - [Manage](https://developer.mastercard.com/open-finance-us/documentation/products/manage/index.md) - [Deposit Switch and Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) - [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) - [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) - [Small Business](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/index.md) - [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) - [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) - [Verification of Assets (VOA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) - [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) - [Feedback Loop](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md) - [PSI Non-FCRA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md) - [Verification of Assets and Income (VOAI)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) - [Transaction Consumer Reporting Agency (TACRA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/tacra/index.md) - [Small Business Credit Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) - [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) - [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md) - [Asset Prequalification](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/prequal/index.md) - [Products Overview](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md) - [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) - [PSI FCRA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md) - [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) - [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) - [Statement Aggregation CRA (SACRA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/statements/index.md) - [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) - [Verification of Employment - Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) - [Account Statements](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) - [Consumer Foresight](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md) - [Verification of Income and Employment - Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md) - [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md) - [Verification of Income and Employment - Paystub (with TXVerify)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) - [Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) - [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md) - [Data Enrichment API](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/api/index.md) - [Loan Payment Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md) - [How PSI Works](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/how-psi-works/index.md) - [Connect Transfer Mobile SDKs](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) - [Mortgage Implementation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) - [Batch Processing](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/batch/index.md) - [Payment Enablement Bundle](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) - [Recurring Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md) - [Verification of Employment - Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-transactions/index.md) - [Permissible Purpose Codes](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) - [Payment Risk Insights (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) - [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) - [Balance Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) - [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) - [Account ACH Details with RTP/FedNow](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) - [Account Validation Assistant](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md) - [Cash Flow Analytics (Consumer)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md) - [Payment Risk Insights (Consumer)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/payment-risk-insights/index.md) - [Cash Flow Analytics (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/cash-flow-analytics-sb/index.md) - [Historical Data Sharing](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/historical-data-sharing/index.md) - [Data Refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) - [Understanding Account Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/understanding-account-data/index.md) - [Understanding Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/understanding-transaction-data/index.md) - [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) - [Reference Application](https://developer.mastercard.com/open-finance-us/documentation/reference-app/index.md) - [Release History](https://developer.mastercard.com/open-finance-us/documentation/release-history/index.md) - [API Status](https://developer.mastercard.com/open-finance-us/documentation/status/index.md) - [Support](https://developer.mastercard.com/open-finance-us/documentation/support/index.md) - [Tutorials](https://developer.mastercard.com/open-finance-us/documentation/tutorials/index.md) - [Pay by Bank Tutorial](https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md) - [Tenant Screening Tutorial](https://developer.mastercard.com/open-finance-us/documentation/tutorials/tenant-screening/index.md) - [Use Cases](https://developer.mastercard.com/open-finance-us/documentation/usecases/index.md) - [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) - [Payment Enablement](https://developer.mastercard.com/open-finance-us/documentation/usecases/payment-enablement/index.md) - [Account Opening](https://developer.mastercard.com/open-finance-us/documentation/usecases/ob-account-opening/index.md) - [Small Business Solutions](https://developer.mastercard.com/open-finance-us/documentation/usecases/small-business-solutions/index.md) - [Personal Finance Management](https://developer.mastercard.com/open-finance-us/documentation/usecases/personal-finance-management/index.md) - [Webhook Notifications](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) - [Open Banking Webhook Management System (OBWMS)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md) - [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md) - [Mastercard Data Connect Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) - [Custom Event Data](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-custom/index.md) - [Report Events (Data Connect)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-dc/index.md) - [Report Events (API)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-api/index.md) - [MVS Events List](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-mvs/index.md) - [Data Connect Events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md) *** # Mastercard Open Finance US source: https://developer.mastercard.com/open-finance-us/documentation/index.md Mastercard Open Finance US enables simple and secure financial data sharing for consumer and small business applications. Our API-based services can power payments, money management, and lending use cases. Open Finance solutions in the United States are provided by Finicity, a Mastercard company. #### API Basics {#api-basics} Onboarding, authentication and managing projects. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md) #### Quick Start Guide {#quick-start-guide} Learn key concepts and send your first API request. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) #### Use Cases {#use-cases} High-level descriptions of how you can use Open Finance APIs for common scenarios. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/usecases/index.md) ## Open Finance Products {#open-finance-products} #### Pay {#pay} APIs to enable payments: * Get [ACH details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) * Verify [account ownership](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) * Validate [account details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md) * Check [available balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) * Predict [payment success](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) * Switch [deposits and bill payments](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md)
[Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/index.md) #### Manage {#manage} APIs for data: * [Account](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) and [transaction](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) details * [Transaction notifications](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) * [Financial statements](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) * Insights into: * [Transaction types](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) * [Recurring transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md) * [Consumer spending](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md) * [Loan payments](https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md)
[Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/index.md) #### Lend {#lend} APIs for credit decisioning [reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md): * [Transactions and statements](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#transactions-and-statements) * [Assets and balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#assets-and-balances) * [Income and employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) * [Cash flow](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#cash-flow)
Designed for use cases like personal loans, credit card issuance, auto finance and [mortgages](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md). [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) #### Small Business {#small-business} APIs for small and medium business finance: * Get [sales analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) for retail locations * Support lending decisions with [payment risk insights](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) * Analyze [cash flow](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/cash-flow-analytics-sb/index.md) for a business
[Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/index.md) Tip: Not sure which product is best for your needs? Email our sales team at [OFin.contactsales@mastercard.com](mailto:OFin.contactsales@mastercard.com). ## Open Finance Technologies {#open-finance-technologies} #### Data Connect {#data-connect} Mastercard Data Connect enables your customers to connect their bank accounts and share data. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) #### User Experience Design Guide {#user-experience-design-guide} Recommended best practices for how to present the Open Finance user experience in your application. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) #### Webhooks {#webhooks} Webhooks deliver real-time event notifications for Data Connect, TxPUSH and report generation. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) ## Get Building {#get-building} #### API Reference {#api-reference} Full documentation for all Open Finance endpoints. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) #### Tutorials {#tutorials} Detailed guidance on implementing solutions for "Pay by Bank" and tenant screening. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/tutorials/index.md) #### Reference App {#reference-app} A sample application built in ReactJS to help you explore the Open Finance APIs and Data Connect. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/reference-app/index.md) #### Error Handling {#error-handling} Troubleshoot issues that can arise during interactions with Open Finance services. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) #### Test Profiles {#test-profiles} Details of test customer profiles you can use to validate your application. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) #### Glossary {#glossary} Learn about the terminology used by Mastercard Open Finance. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md) AI coding agents can use [llms-full.txt](https://developer.mastercard.com/open-finance-us/documentation/llms-full.txt) (this documentation in Markdown) and the [OpenAPI specification](https://static.developer.mastercard.com/content/open-finance-us/swagger/openbanking-us.yaml). --- # API Status source: https://developer.mastercard.com/open-finance-us/documentation/status/index.md The current status of the Open Finance API services can be viewed at the link below. Use this page to check whether there are any known issues with any of the services or connections to FIs. You can also use the tab at the top of the page to see the status of other Mastercard APIs. --- # Partnership Models source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/index.md As the possibilities and use cases for open finance grow, customers are increasingly seeking innovative ways to integrate into Mastercard's Open Finance capabilities with simpler, faster and frictionless onboarding experiences. [Mastercard's Engage program](https://www.mastercard.us/engage/#/en/home/open-banking) offers different partnership models to implement Open Finance services with ease for you and your affiliated partners. These models are not mutually exclusive, and can be used separately or together to meet your business objectives. * [Partner Linked Access](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/index.md) --- This model is designed to serve more fintechs and merchants that require Mastercard's Account Opening and Payment services without having to maintain Payments Card Industry (PCI) and Personal Identifiable Information (PII) compliance, which can introduce friction during integration. In the Partner Linked Access model, there are two partners involved who both need to integrate with Mastercard---a Direct Partner (fintech or merchant or a payment institution), and a linked third-party (e.g., processor), who offers additional payment processing functionality. Once integrated, the Direct Partner shares the consented third-party access token with the linked third-party to retrieve the consented consumer data from Mastercard Open Finance and process the payment on the customer's behalf. This simplifies your data compliance responsibilities, reduces friction and opens up various payment-related opportunities, such as account funding, peer-to-peer payments, person-to-merchant payments, and more. * [Partner Direct Model](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md) --- In this model, the Direct Partner acts as a distributor of Mastercard's Open Finance services to their affiliated partners. The Direct Partner performs a one-time integration with any of the Mastercard's Open Finance solutions and once integrated, the Direct Partner can quickly scale their solution by leveraging the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/) to onboard their affiliated partners. This ease-of-onboarding amplifies the outreach to more customers with differentiated offerings such as loan origination, financial management services, account opening, payment initiation services and more. --- # API Reference source: https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md API Specification: `https://static.developer.mastercard.com/content/open-finance-us/swagger/openbanking-us.yaml` --- # Tutorials source: https://developer.mastercard.com/open-finance-us/documentation/tutorials/index.md The tutorials section contains guides on how to implement common scenarios using the Open Finance APIs. Where a scenario can be implemented in multiple ways, we highlight trade-offs (performance, number of calls, fraud/risk coverage) to help you choose the best pattern for your application. ### List of Tutorials {#list-of-tutorials} | Tutorial | Description | |------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------| | [Pay by Bank](https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md) | Implement a secure "Pay by Bank" payment method, including identity verification and fraud mitigation. | | [Tenant Screening](https://developer.mastercard.com/open-finance-us/documentation/tutorials/tenant-screening/index.md) | Screen prospective tenants: verify income, assets, and rental payment history using Lend reports. | --- # Testing and Integration source: https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/index.md This section provides resources and guidance for integrating with Mastercard Open Finance APIs and testing your implementation. * [Using the Postman Collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) - Explore and test the Open Finance APIs using our Postman collection * [Generating an API Client Library](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/generating-an-api-client-library/index.md) - Generate type-safe client libraries from the API specification * [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) - Learn how to use test banks (FinBanks) and test payroll providers to test different use case scenarios --- # API Basics source: https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md ## Environments {#environments} Open Finance provides Sandbox and Production environments. ### Sandbox {#sandbox} The Sandbox environment is designed for development and testing using mock data. A Sandbox project gives you access to the Open Finance Test Drive plan. Test Drive is a non-billable, unlimited plan that provides access to all Open Finance API endpoints. To set up a Sandbox project and start using the APIs, follow the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md). The Sandbox environment includes a variety of test institutions that you can use for testing. These institutions simulate different banking scenarios that might be useful for your development and testing processes. For more information on test data, see [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). ### Production {#production} Once you've thoroughly tested your application in the Sandbox environment and are confident that it's working as expected, you can request an upgrade to Production. See [Moving to Production](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#moving-to-production) for details. ## Authentication {#authentication} To use the Open Finance REST APIs, you will need the following: * **Partner ID** - The Partner ID is a unique identifier for a specific set of credentials, including the secret and appKey. All requests sent to Mastercard Open Finance must include a token for accessing Open Finance APIs. To create a token, you are required to provide the PartnerID along with the corresponding secret and appKey. * **Secret** and **App Key** - Credentials required to authenticate your API calls. Tip: Your Production and Sandbox environments have different Partner IDs. You can also create multiple Partner IDs within an environment for different use. Make sure you are using the correct Partner ID. To get the credentials for a project, select it in the [Dashboard](https://developer.mastercard.com/dashboard) then select **Credentials** at left. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/sandboxcreds.png) All requests sent to Mastercard Open Finance must include a `Finicity-App-Token` HTTP header. Use your Partner ID and Secret with the following endpoint whenever you need to generate a new access token: API Reference: `POST /aggregation/v2/partners/authentication` Note: Access tokens are valid for two hours. As a best practice, generate a new token when the current token is older than 90 minutes to avoid expiration during API calls. * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/partners/authentication' \ --header 'Content-Type: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --data-raw '{ "partnerId": "{{partnerId}}", "partnerSecret": "{{partnerSecret}}" }' ``` * Expected response: ```json { "token": "YBh22Sb9Es6e66Q7lWdt" } ``` ### Troubleshooting {#troubleshooting} #### "Too Many Requests" Error {#too-many-requests-error} If you receive a "too many requests" error, this may indicate that the App Key is incorrect. The error occurs because the App Key controls the rate limit, and invalid keys have a rate limit of 0. If the Partner ID or Partner Secret is wrong, you will receive an "Invalid Credentials" error instead. #### Account Lockout After Failed Authentication {#account-lockout-after-failed-authentication} After 5 attempts to call **Create Access Token** with an incorrect Secret, API access for the Partner ID used will be locked. You will receive a 24302 error for all subsequent API calls. Contact [Open Finance support](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) to get assistance unlocking your account. ### Delete Partner ID {#delete-partner-id} To delete a Partner ID and the associated Secret and App Key, select **Delete credential** from the pulldown menu at right. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/delete-ucd-credential.png) Once you delete the credentials, you can no longer use them to access the APIs. When deleting a set of credentials, ensure there's another set of active credentials. ### Modify Partner Secret {#modify-partner-secret} To rotate your secret, call the Modify Partner Secret endpoint. Keep in mind that you will need to update your integration with the new API secret to ensure your app continues to process requests successfully. Note: Your partner (API) secret does not expire, however, to maintain the security of your API account, we recommend that you rotate (update) your API secret at least once every 12 months. API Reference: `PUT /aggregation/v2/partners/authentication` ### OBWMS Authentication {#obwms-authentication} To use the [Open Banking Webhook Management System (OBWMS)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md), you will also need to add and download a **Mastercard signature verification key** from your project dashboard. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/create-sig-key-obwms.png) Tip: Not all services within Mastercard US Open Finance use the OBWMS system for webhooks. Open Finance services and products are being migrated to the new webhook management system gradually. The documentation will indicate where OBWMS is used and how to verify the webhooks in each case. See [Webhook Notifications](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) for more information and a list of which services use their own webhook notifications or OBWMS. ## Moving to Production {#moving-to-production} To request Production access, click the **Request Production access** button on the Summary page. When you request an upgrade to the Production environment, you can choose to request a **Test Drive Premium (non-billable)** plan or a **Production (billable)** plan. Note: Access to these plans will only be approved if a contract between you and Mastercard has been executed. Work with your Sales Representative or Client Success Manager to upgrade to Production. Contact [OFin.contactsales@mastercard.com](mailto:OFin.contactsales@mastercard.com) for more information. ### Test Drive Premium Plan {#test-drive-premium-plan} Test Drive Premium is a free, 30-day limited-duration plan that grants you access to all Open Finance API endpoints. After the 30-day period, you will automatically be transitioned to the Production (billable) plan. This plan allows you to test your integration with live financial data before fully moving to the Production plan. ### Production (Billable) Plan {#production-billable-plan} This is a billable plan that provides access to the Open Finance API endpoints specified in your contract with Mastercard, limiting data retrieval to those endpoints only. API calls made on this plan are subject to billing based on the terms of your agreement with Mastercard. This plan should not be used for testing purposes. After you select a suitable plan and click **Proceed**, the credentials required to access the API in the Production environment are created. Make a note of the Partner ID and share it with your Mastercard Representative. These credentials will only be active and ready to use in Production after Mastercard reviews and approves your Production access request. ### Additional Production Credentials {#additional-production-credentials} You can also request additional Production credentials using the **Add Partner ID** button. ## View API Usage {#view-api-usage} Click **Usage** (at left, under **Details**) to gain valuable insights into the usage of the API and traffic for each endpoint specific to a Partner ID. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/mcd-usage.png) ## Access Client Hub {#access-client-hub} The Client Hub provides a web-based interface to manage some key Open Finance operations. You can use it to: * check financial institution status * view Lend report history * customize Data Connect * order Lend reports without using the API
Click **Access Client Hub** from the pulldown menu at the right of the credentials panel to go to the Client Hub. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/select-mcd-hub.png) For more information, see [Client Hub Guide](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/index.md). ## Edit Project Details {#edit-project-details} To edit project details, click **Settings** (at left, under **Manage**). You can update the following details in a project: * Project's name * Details of the company on behalf of which the project is created * You can update the client company details for an Open Finance project created on behalf of a client. However, you cannot change an Open Finance project created for yourself into one created for a client, or vice versa. ## Team Management {#team-management} You can invite team members to your Open Finance project to ensure that all the members are notified of the project activities. You must be an *Admin (Owner)* to add or remove a team member in the project. To learn more about how you can use the Team Management feature, see the [Team Management](https://developer.mastercard.com/platform/documentation/managing-your-account/team-management/) section of our [Mastercard Developers Platform](https://developer.mastercard.com/platform/documentation/) documentation. ## See Also {#see-also} [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) --- # Webhook Notifications source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md Webhooks allow you to receive real-time notifications when specific events occur, eliminating the need for constant polling. They are ideal for staying informed about customer activity, transaction updates, and other time-sensitive events. Note: Future US Open Finance products will use the new [Open Banking Webhook Management System (OBWMS)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md) which provides a centralized system for subscribing to and receiving webhooks from the various Open Finance services. OBWMS will provide greater consistency in webhook handling across all the services it supports. Existing services will be migrated to the Open Banking Webhook Management System during 2026. Webhooks are used for the following: * [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) --- Data Connect webhooks allow you to track a customer's user journey during the Data Connect application flow. Note that if you use the Data Connect SDK you can use SDK events to track user progress instead of using webhooks. * [Mastercard Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebhooks/index.md) --- webhooks for Connect Components will be available through the upcoming [OBWMS](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md) centralised webhook system. As with regular Data Connect, if you use the SDK, you can opt to use SDK events rather than webhooks to track user progress. * [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md) --- report webhooks allow you to be notified when a report begins generation, when it is complete, and if a failure occurred. * [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) --- TxPUSH allows you to register a TxPUSH Listener service to receive notifications whenever there are updates to account or transaction data for a specific customer's account. Tip: For testing purposes, you can use tools like webhook.site or beeceptor.com that receive webhooks and post the content for you to review (note that this is not an official endorsement of any of these services). In production, you **must** use your own secure webhook service. ## Allowed IP Addresses {#allowed-ip-addresses} To ensure webhook notifications reach your webhook listener server, you must add the following Mastercard IP addresses to your firewall's allowlist: 34.215.116.35/32 34.215.234.87/32 34.214.37.223/32 34.210.53.158/32 35.165.2.59/32 52.89.52.36/32 52.36.72.121/32 52.41.241.61/32 52.88.106.209/32 52.35.98.213/32 44.233.213.239/32 54.190.254.33/32 44.231.77.153/32 44.231.235.170/32 167.89.103.115/32 35.83.215.192/32 52.42.34.141/32 52.7.205.11/32 44.194.229.176/32 44.198.219.8/32 34.230.230.32/32 3.229.4.109/32 34.224.176.228 3.216.96.164/32 107.23.193.111/32 52.200.68.99/32 44.219.246.198/32 68.142.133.160/27 68.142.142.160/27 68.142.128.64/27 --- # Client Hub source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/index.md The Client Hub portal offers you the flexibility to manage some of your key Open Finance operations via a user-friendly interface. It allows you to monitor the health of financial institutions and simplifies billing reconciliation by displaying a record of reports generated for customers through a dashboard. While you can perform these tasks using the Open Finance APIs (for example, retrieve the list of reports generated for a customer by calling [Get List of Reports by Customer](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetReportsByCustomerId), or check the status of a Financial Institution by calling [Get Institution by ID](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetInstitution)), the Client Hub makes managing these tasks more accessible for a non-technical audience through its interface. ### How It Works {#how-it-works} ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub-dashboard2.png) Client Hub provides the following key features: | Feature | Description | |-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Institution Status](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/institution-status/index.md) | This page lists thousands of US financial institutions, displaying their connection statuses as either online, investigating, and offline. Institutions that are investigating a connection or are offline, display error codes to help you understand the reason for the connection status. This insight helps you to quickly communicate what action if any, a partner must take to resolve connectivity issues. Refer to the [Client Hub Use Cases](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md#monitor-institution-status) to learn how Institution Status feature can help you. | | [Invoice History](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/invoice-history/index.md) | This page displays a record of every report that you have run for a customer. For example, when you request a verification report for [assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md), [income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) or [employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) for a customer using the Open Finance APIs, a record is automatically generated in the Invoice History page of the Client Hub. You can also download the list of reports as a CSV file and manually sort the data to help you with billing reconciliation. Billing reconciliation involves cross-checking the list of reports recorded on the Client Hub with the corresponding invoices across various locations or branches in your organization to verify the charges incurred for a customer are accurate. Refer to [Client Hub Use Cases](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md) to understand how the Invoice History feature can help you. | | [Customize Data Connect](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-customize-connect/index.md) | Customize Data Connect allows you to tailor the appearance and behavior of the Data Connect application's interface to better align with your application's branding and user experience requirements. For detailed guidance on each customization option and to see the changes in real-time, refer to [Customizing Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md). | | [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) | The Order Reports tool enables you to request [Lend reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) (Verification of Assets, Income, Employment, and others) without building a direct API integration. The tool can email customers to prompt them to provide access to their data. | ## Client Hub Help {#client-hub-help} If you need help with Client Hub, you can contact us through the [Mastercard Connect support portal](https://www.mastercardconnect.com/-/sign-in). * **Support Case:** If something on Client Hub is not working correctly, raise a new support case. Please provide as much context and information as possible, including screenshots. * **New Feature:** If there is an unsupported feature or enhancement you want in the Client Hub, raise a new feature request. Please provide context about what you are trying to accomplish. * **New Institution:** If you would like us to add a particular bank or credit union to our supported financial institutions, please provide details so we can attempt to establish a connection for future customers. **See also**: * [Accessing the Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md) * [Client Hub Use Cases](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md) --- # Glossary source: https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md Common terminology in the Mastercard Developers documentation. ## Access Token {#access-token} After a Partner ID and Partner Secret are authenticated using the Partner Authentication API, an access token key is returned. The token is valid for two hours, after which a new token must be generated. As a best practice, generate a new token when the current token is older than 90 minutes. The token is required in the header of every API call to access the Open Finance platform. See [Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). ## Account Aggregation {#account-aggregation} The process of gathering a customer's account data in real-time after they have permissioned their accounts in the Data Connect app. Customer account records have key account indicators to help you identify account information and organize the account data within your applications. Customer accounts are refreshed daily. You can also subscribe to TxPUSH notifications, which sends notifications to the event listener when there are changes to an account. See [Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md). ## Account ID {#account-id} A number representing a financial account owned by a customer ID. The account ID is a unique number associated with each type of account the customer owns at a financial institution: checking, savings, money market, and more. All data is linked to the customer ID, unless the customer removes their account, or it gets deleted. ## Applications {#applications} Applications are web or mobile applications developed by our partners. You must register each of your applications with Mastercard so that customers can identify your application name and logo when using the [Data Connect Application](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). ## App Key (Finicity-App-Key) {#app-key-finicity-app-key} When you create a project on Mastercard Developers, you'll receive a Partner ID, Partner Secret, and App-Key for the Sandbox environment. The App Key is associated with the application you registered with Mastercard. The `App-Key` is a required parameter in the header of every call to access data for the Open Finance platform. See [Sign Up](https://developer.mastercard.com/account/sign-up) for a Mastercard account and [Create a Project](https://developer.mastercard.com/dashboard). ## App Registration (OAuth) {#app-registration-oauth} Partners must register their applications to access financial institutions using an OAuth connection. If a partner has multiple applications, use the Set Customer App ID API to assign all apps to an existing client. The assigned apps can then access financial institutions using OAuth connections. See [Register Applications](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md). ## Certified Institutions {#certified-institutions} Financial institutions (FI) are certified based on their accessibility to the Open Finance platform and ability to seamlessly retrieve account data while ensuring consistent performance. The benefit of Certified FI connections is they maintain their system's health status, which helps you leverage our products and consume quality data for your business needs. FIs can also certify (support) specific products, such as Account Balance, Verification of Income (VOI), and more. If a product isn't supported, then all product related APIs are blocked from fetching any data. See [Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md). ## Consumer {#consumer} Consumers are records associated with your customers. Since Mastercard is a FCRA reporting agency, all customer data collected and shared with a third party must have a consumer ID associated with a customer's unique ID. A consumer persists as the owner of any reports that are generated for a customer ID, even after the customer ID is deleted from the system. This allows customers to dispute their financial reports as needed with other FCRA entities. See [Consumers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) and [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md). ## Customer {#customer} Customers are end users granting Mastercard Open Finance access to their financial accounts. Customers go through the Data Connect or MVS apps to connect to their financial institutions and [Permission](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md#permissioning) their accounts. All of the customer's financial data is linked to their unique customer ID. See [Customers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers). ## Customer ID, Testing {#customer-id-testing} A unique ID associated with a testing customer ID. Testing customers can only access the financial data from [FinBanks](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md#finbanks) using the testing profiles on the [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) page. This allows you to test your applications in a live Open Finance environment before moving your project to production. To create your first test customer, see [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md). ## Data Connect {#data-connect} A simple and secure user interface called within your own applications or services. The Data Connect app allows customers to connect to their financial institutions and permission the accounts they consent to share. Mastercard Open Finance APIs can then access the financial and transactional data for a customer. See [Data Connect Application](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). ## Data Connect Events {#data-connect-events} Notifications sent to the event listener that you set up through the Web or Mobile SDKs. You can choose which type of events you want to receive. Web SDK Events help monitor the Data Connect app, such as when it's loaded, canceled, or successfully completed. User Events provide visibility into a customer's actions when using the Data Connect app, and Route Events provide visibility into customers navigating through the Data Connect app. See [Data Connect Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/index.md). ## Data Connect Experience {#data-connect-experience} A set of features available to change the look and behavior of the Data Connect app. This flexibility lets you configure different types of experiences, tailored to fit your branding and customer base. The `experience` parameter passed into the Generate Data Connect URL API loads your customized features when the Data Connect app starts. See [Configure the DataConnect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md). ## Data Connect Session {#data-connect-session} A session starts when a customer opens the Data Connect app on their mobile device or through a computer browser. The Data Connect app guides the user through connecting to their financial institutions and permissioning their accounts. You can set up [Data Connect Events](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md#data-connect-events) to monitor the Data Connect app throughout the session. After the customer submits their data, the Data Connect session ends. ## FinBanks {#finbanks} A set of testing financial institutions (mock banks) that allows you to simulate data transactions at a live financial institution, using a testing customer ID. A few new data transactions are added to FinBanks daily to allow for different data test results. You must upgrade to a paid plan before you can add real customer IDs at a live financial institution. See [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). ## Government-Sponsored Enterprise (GSE) {#government-sponsored-enterprise-gse} Government sponsored agencies such as Freddie Mac and Fannie Mae. The Mortgage Verification Services product gathers information from single or joint borrowers through the Income, Payroll, or Paystub apps. All reports for a consumer applying for a loan are linked to the `portfolioID-version-port` parameter, which is the reference ID in the Loan Product Advisor (LPA) or Desktop Underwriter (DU) submission to the GSE. See [Sending Reports to Government Sponsored Enterprises](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md#sending-reports-to-government-sponsored-enterprises). ## Partner {#partner} A company or individual who owns a Mastercard Developers account and has created at least one Open Finance project. Every project receives a unique Partner ID, Partner Secret, and App Key, which is used to authenticate your credentials and identify your applications. ## Partner Linked {#partner-linked} Client-partners and third party-processors are given consented third party access (Partner Linked) to access consented data. Customers give consent to their accounts using the Data Connect Application. Third parties are given a consent receipt token, which acts as a key to accessing customer consented data on our Open Finance platform for a limited time. This allows processors the ability to complete their processing services, such as getting the customer's ACH routing data to process a payment on their behalf. See [Partner Linked Access](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/index.md). ## Permissioning {#permissioning} The Data Connect and Mortgage Verification Service (MVS) apps allow consumers to connect to their financial institutions and permission their checking, savings, and other accounts they consent to share. This allows third parties to access financial data from the consumer's consented accounts. Consumers can manage which accounts they want to share through their online banking website. ## Sandbox {#sandbox} An environment where you create a new Open Finance project to test your applications. You'll have access to testing financial institutions, [FinBanks](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md#finbanks), and profiles for various use case scenarios. You can also integrate with the Open Finance APIs in a live environment. See [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) and [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). ## Test Drive {#test-drive} By default, when you create an account on Mastercard Developers (Sandbox environment) you are on the Test Drive plan. You can test your applications with all Open Finance APIs on our platform free of charge, using a testing customer ID. You must upgrade to a paid plan before you can access data at a live financial institution. See [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). ## Test Profiles {#test-profiles} A variety of different use case scenarios used to test your applications on the Open Finance platform in a live environment. There are profiles to test sign-in authentication at financial institutions (FinBanks), bank accounts, OAuth connections, payroll and paystubs, and MVS. See [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). --- # Error Handling source: https://developer.mastercard.com/open-finance-us/documentation/errors/index.md To help you with effective error handling, the errors have been classified into categories based on when they occur during the use of Mastercard's Open Finance solutions. [Error Lists](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md#error-lists) [Data Connect Alerts](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md#data-connect-alerts) ## Error Lists {#error-lists} ### Full Error List {#full-error-list} A comprehensive list of error codes in numerical order. [View Full Error List](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) ### Error Remediation Categories {#error-remediation-categories} Description of the different types of errors and how to handle them generally. [View Remediation Categories](https://developer.mastercard.com/open-finance-us/documentation/errors/error-remediation-categories/index.md) ### Most Common Errors {#most-common-errors} A list of the most common aggregation and user errors. [View Most Common Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/most-common/index.md) ### Mastercard Data Connect Errors {#mastercard-data-connect-errors} A summary of the errors that can occur during the user journey through the Data Connect experience. [View Mastercard Data Connect Errors](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-errors/index.md) ### Account Errors {#account-errors} Errors that occur during the end-user account selection, account permissioning and account authentication journey. [View Account Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) ### Institution Errors {#institution-errors} Errors that occur when connecting to Financial Institutions. [View Institution Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/institution-errors/index.md) ### Request Errors {#request-errors} Errors generated for API requests across all endpoints under Mastercard Open Finance services. [View Request Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/request-errors/index.md) ## Data Connect Alerts {#data-connect-alerts} When a customer encounters an error while in the Data Connect flow, Data Connect displays an error message and code in the app. The Data Connect Alert messages are listed in the descriptions of the applicable error codes in this documentation. The following image is typical of how an alert looks to a customer. The title, error message, and error code change according to the error. ![103](https://static.developer.mastercard.com/content/open-finance-us/uploads/103-1.png) --- # Use Cases source: https://developer.mastercard.com/open-finance-us/documentation/usecases/index.md The use cases section provides you with an overview of the different solutions offered by Mastercard Open Finance. Find out about the APIs that power these solutions and help our partners succeed. Each use case also guides you through a standard sequence of API calls to implement a solution. ### List of Use Cases {#list-of-use-cases} | Use Case | Description | |---------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| | [Personal Finance Management](https://developer.mastercard.com/open-finance-us/documentation/usecases/personal-finance-management/index.md) | Provide a consolidated view of your customers' finances in a single space to help your customers manage their wealth better. | | [Account Opening](https://developer.mastercard.com/open-finance-us/documentation/usecases/ob-account-opening/index.md) | Enable a seamless account opening and onboarding experience for your customers. | | [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) | Make confident lending decisions and offer a hassle-free lending experience for your customers. | | [Small Business Solutions](https://developer.mastercard.com/open-finance-us/documentation/usecases/small-business-solutions/index.md) | Onboard and underwrite small business customers using real-time account data and analytics. | | [Payment Enablement](https://developer.mastercard.com/open-finance-us/documentation/usecases/payment-enablement/index.md) | Provide a seamless payment experience for your customers. | --- # Open Finance Products source: https://developer.mastercard.com/open-finance-us/documentation/products/index.md Before you try any of the Open Finance products you will need to have already completed the following: * [Generated your credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) for accessing the services. * Understood how to [authenticate](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) and receive an access token. * Connected your customer (real or testing) accounts through [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). ## Pay Products {#pay-products} #### Account ACH Details {#account-ach-details} Retrieve a customer's ACH (Automated Clearing House) details for account opening or payment initiation. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) #### Verification of Account Owner {#verification-of-account-owner} Verify the account owner's details. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) #### Account Balance {#account-balance} Retrieve a customer's available account balance. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) #### Account Validation Assistant {#account-validation-assistant} Bank account validation using microdeposits. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md) #### Payment Enablement Bundle {#payment-enablement-bundle} Fetch data relating to various individual Pay products using a single endpoint which bundles together data from other services as needed. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) #### PSI {#psi} Provide a score based on real-time account balance and historical account activities to evaluate the likelihood a given payment amount will settle successfully. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md) #### Deposit Switch {#deposit-switch} Allow consumers to switch their direct deposits from one bank account to another. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md) #### Bill Pay Switch {#bill-pay-switch} Allow consumers to switch their recurring automatic payments from one bank account to another. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md) ## Manage Products {#manage-products} #### Transaction Aggregation {#transaction-aggregation} Receive nightly aggregations of a customer's financial transactions. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) #### Account Aggregation {#account-aggregation} Manage the accounts that customers have added. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) #### TxPUSH {#txpush} Subscribe to receive notifications whenever there are updates to account or transaction data for a specific customer's account. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) #### Statements {#statements} Retrieve customer bank statements in PDF format. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) #### Loan Payment Details {#loan-payment-details} Retrieve the information needed to move money to a non-routable liability account. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md) #### Data Enrichment {#data-enrichment} Improve the clarity and usability of transaction data by categorizing transactions, identifying merchants, locations, logos, and websites. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) #### Recurring Analytics {#recurring-analytics} Retrieve categorized recurring transaction details for a customer, across multiple accounts. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md) ## Lend Products {#lend-products} #### Verification of Assets (VOA) {#verification-of-assets-voa} Retrieve up to twelve months of a customer's transaction history. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) #### Verification of Income (VOI) {#verification-of-income-voi} Get a confidence score that ranks a customer's income streams. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) #### Cash Flow Analytics {#cash-flow-analytics} A report that analyses credit and debit cash flow of a consumer or small business. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md) #### Balance Analytics {#balance-analytics} A report that analyses the bank account balances of a customer. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) #### Reports List {#reports-list} Full list of Lend report products. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) ## Small Business Products {#small-business-products} #### Small Business Credit Analytics {#small-business-credit-analytics} Provides retail sales metrics and benchmarks for a specified merchant location. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) #### Payment Risk Insights Report {#payment-risk-insights-report} Provides a risk score for a business based on payment history of connected accounts. [Learn more →](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) --- # Customer Records source: https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md This section covers the customer and consumer records that are required to use Open Finance services. * [Customers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) - Create and manage customer records to access data from financial institutions * [Businesses](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses) - Create a business record for a customer * [Consumers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) - Create consumer records associated with a customer to generate and view loan reports ## Customers {#customers} In order to use most Open Finance APIs, you'll need to create a customer record. This record allows you to view a customer's account information and other types of data from the financial institutions (FIs) that they connect. When a customer logs into their bank and permissions their accounts, the financial data is associated with their `customerId`. If you delete the `customerId` field, the link to their account gets deleted as well. ### Customer Account Types {#customer-account-types} ###### For Testing {#for-testing} To begin testing Open Finance services using our mocked bank provider you need to create a test customer. [Create a test customer →](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers) ###### For Upgraded Accounts {#for-upgraded-accounts} Upgraded paid accounts must add an *active* customer record in order to access data from live financial institutions. [Create an active customer →](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) ###### Business Customers {#business-customers} Partners must register their customers as businesses if their customer is a business entity. [Create a business record →](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses) ### Test Customers {#test-customers} Create a customer record to use with our mocked financial institution, FinBank. You might have already completed this step if you followed the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md). Note: You can create up to 500 testing customers per Partner ID. If you reach this limit, you will receive a 42000 error. Delete unused testing customers from your environment. API Reference: `POST /aggregation/v2/customers/testing` You can omit the `applicationId` from the request when generating testing customers. * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/customers/testing' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "username": "customerusername1" }' ``` * Expected response: ```json { "id": "1005061234", "username": "customerusername1", "createdDate": 1607450357 } ``` ### Active Customers {#active-customers} Upgraded paid accounts can also add active customers to use at live financial institutions. You can use either active or testing customers with the Finbank [test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). ###### Creating an Active Customer {#creating-an-active-customer} API Reference: `POST /aggregation/v2/customers/active` Tip: The `phone` parameter, although optional, is recommended if available. If the customer is required to use the Connect experience as a returning user, the phone number can be pre-populated in the Connect experience, making the OTP flow much smoother. See the [Returning User Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/returning-user-experience/index.md) section in the Experience Design Guide for details of the flow that returning users will see. Warning: The `username` parameter used when creating a customer record must be unique, and consist of between 6 and 255 characters in any combination of: * Upper case, lower case, or numeric characters * The following non-alphanumeric special characters: `! @ . # $ % & * _ - +` Use of other special characters (such as `í` or `ü`) may result in an error. We recommend avoiding the use of email addresses for usernames. * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/customers/active' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "username": "{{username}}", "firstName": "{{firstname}}", "lastName": "{{lastname}}", "phone": "{{phone}}", "email": "{{email}}" }' ``` * Expected ```response: json { "id": "1035061235", "username": "{{username}}", "createdDate": 1607450357 } ``` ###### Operations for Retrieving and Managing Active Customers {#operations-for-retrieving-and-managing-active-customers}
Get Customer by ID: API Reference: `GET /aggregation/v1/customers/{customerId}` Modify Customer by ID (you must specify either the first name, the last name, or both in the request): API Reference: `PUT /aggregation/v1/customers/{customerId}`
Delete Access to Customer by ID: API Reference: `DELETE /aggregation/v1/customers/{customerId}`
Get (all) Customers: API Reference: `GET /aggregation/v1/customers`
Use the `userName` query parameter to obtain a specific customer, or use the `search` parameter to search for all customer records with the specified text in the customer name (anywhere in either of their `firstName` or `lastName` fields). For example, the following will return the first 25 customers with the text `John` in either of the `firstName` or `lastName` fields: GET 'https://api.finicity.com/aggregation/v1/customers?search=John&start=1&limit=25' If the response includes true for the `moreAvailable` value then you can get the next page of results by calling the same query again with an appropriate value for the `start` query parameter. ### Retrieve Customer Authorization Period {#retrieve-customer-authorization-period} The duration for which you can access a customer's data using Mastercard's Open Finance services will vary depending on the financial institution. You can call the `GET /customers/institution-logins/{institution_login_id}/authorization-details` endpoint with the specific `InstitutionLoginID` to determine the customer's authorization period for a specific financial institution. The response includes the customer's authorization start and end date, helping you prompt the customer to reauthenticate before their authorization expires, avoiding any disruptions in service or data access. API Reference: `GET /customers/institution-logins/{institution_login_id}/authorization-details` #### Using the institutionLoginId {#using-the-institutionloginid} When a customer links their account via [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) and authorizes Mastercard Open Finance to access their financial data, an `institutionLoginId` is generated. The `institutionLoginId` is created during the [Add Accounts event](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md#addaccounts). If [webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md#added) are configured, you will receive a notification with a response including the `institutionLoginId`. #### Steps to Check a Customer's Authorization Period for a Financial Institution: {#steps-to-check-a-customers-authorization-period-for-a-financial-institution} 1. Create a [customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and link them to at least one account via [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). 2. The `institutionLoginId` is generated during the Data Connect flow when the user [adds an account](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md#addaccounts). If [webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md#added) are configured, you will receive a notification with the response including the `institutionLoginId`. Alternatively, you can use the [Refresh Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#RefreshCustomerAccounts) endpoint to fetch the latest account data, including the `institutionLoginId`. 3. Call the [Get Customer Authorization Details](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) endpoint with the `InstitutionLoginID`. 4. Look for the `authorizationEndDate` in the response, which tells you the exact date and time when the consent will expire. You can prompt the customer to re-authenticate to renew their consent before it expires, ensuring uninterrupted access to their data. #### Testing {#testing} To test the `GET /customers/institution-logins/{institution_login_id}/authorization-details` endpoint, use the [OAuth Connection Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). ## Businesses {#businesses} A Business record must be created for any customer that is a business. The business record is used to store information related to the business, while the customer record stores information related to the individual owner. The Business must have a `customerId` associated with it, as this is a required field when creating a business record. A `consumerId` must be associated with the business if the owner is personally liable for any business loans. For more information see [creating a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#creating-a-consumer). A consumer record must be created before creating a business if `personallyLiable: true` - otherwise the service will return an error 409. This allows for the retention of data for the required period of time under the Fair Credit Reporting Act (FCRA).
### Creating a Business Record for a Customer {#creating-a-business-record-for-a-customer} API Reference: `POST /business-services/customers/{customer_id}/businesses` * Command: ```sh curl --location --request POST 'https://api.finicity.com/business-services/customers/{customer_id}/businesses' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "name": "ABC Tires Inc", "personallyLiable": true, "address": { "addressLine1": "434 W Ascension Way", "addressLine2": "Suite #200", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123" }, "phoneNumber": { "countryCode": "141", "phoneNo": "7992222" }, "url": "https://www.finicity.com/", "email": "myname@example.com", "type": "Nonprofit", "taxId": "A1234561Z" }' ``` * Expected ```response: json { "name": "ABC Tires Inc", "personallyLiable": true, "address": { "addressLine1": "434 W Ascension Way", "addressLine2": "Suite #200", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123" }, "phoneNumber": { "countryCode": "141", "phoneNo": "7992222" }, "url": "https://www.finicity.com/", "email": "myname@example.com", "type": "Nonprofit", "taxId": "A1234561Z", "businessId": "1112", "createdDate": "2022-04-12T11:51:23", "modifiedDate": "2022-04-12T11:51:23" } ``` ### Operations for Retrieving and Managing Active Business Customers {#operations-for-retrieving-and-managing-active-business-customers} A `customerId` is required to get business information for a specific customer. A `businessId` is required to update and get business records. API Reference: `GET /business-services/customers/{customer_id}/businesses` API Reference: `PUT /business-services/businesses/{business_id}` API Reference: `GET /business-services/businesses/{business_id}` ## Consumers {#consumers} In order to be able to generate and view [Lend reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) for CRA use cases, you will need to create a consumer record. For more information on permitted use cases, see [Permissible Purpose Codes](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md). Unlike a customer record, a consumer record cannot be deleted. Reports created for the consumer are retained for six years. Note: Consumer IDs have a one-to-one relationship with a customer ID. Alert: If you are using consumer lending products for small business purposes (for example, if a Transaction Credit Reporting Agency (TACRA) report is used as part of the decisioning process), you must ensure that a consumer record exists, even if the "consumer" in this case is a business. See the [Consumer Records and Small Business Lending](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumer-records-and-small-business-lending) section below. ### Creating a Consumer {#creating-a-consumer} Warning: **Reseller Partners** When creating a consumer record, end user information must be provided by Partners that are resellers. This is due to FCRA regulatory requirements. The create consumer call will fail with error code 1201 when end user information has not been sent in the request parameters. Please contact your Customer Success Manager with any questions. Use the [Create Consumer for the Customer](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#CreateConsumer) endpoint to create a consumer record associated with a given customer record. If a consumer already exists for the customer, an HTTP 409 (Conflict) response is generated. API Reference: `POST /decisioning/v1/customers/{customerId}/consumer`
Required fields for a consumer record are described in this table. All other fields are optional. | Requirement | Fields | |-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Required fields | `firstName` `lastName` `state` | | Conditionally required fields | At least one of `ssn` or `birthday` (`year`, `month`, and `dayOfMonth`). Send both if available, as this improves matching accuracy when handling consumer disclosure, dispute, and freeze requests. At least one of `phone` or `email`. | | Mortgage use cases | `ssn` is required for [GSE data submission](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md#sending-reports-to-government-sponsored-enterprises). | * Command: ```sh curl --location --request POST 'https://api.finicity.com/decisioning/v1/{{customerid}}/1005061234/consumer' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "firstName": "{{firstname}}", "lastName": "{{lastname}}", "address": "{{address}}", "city": "{{city}}", "state": "{{state}}", "zip": "{{zip}}", "phone": "{{phone}}", "ssn": "{{ssn}}", "birthday": { "year": {{year}}, "month": {{month}}, "dayOfMonth": {{dayOfMonth}} }, "email": "{{email}}", "suffix": "{{suffix}}", "endUser": { "name": "{{name}}", "address": "{{address}}", "city": "{{city}}", "state": "{{state}}", "zip": "{{zip}}", "phone": "{{phone}}", "email": "{{email}}", "url": "{{url}}" } }' ``` * Expected ```response: json { "id": "0bf46322c167b562e6cbed9d40e19a4c", "createdDate": 1607450357, "customerId": 1005061234 } ``` ### Consumer Records and Small Business Lending {#consumer-records-and-small-business-lending} Whenever consumer lending products such as Verification of Income (VOI) or Transaction Credit Reporting Agency (TACRA) are used for small business lending decisions, it is necessary to create a consumer record. You can still create a consumer record using appropriate business details in place of the personal details normally used when creating a consumer. This applies even if there is no personal liability. Where a business owner is personally liable, the consumer record should include details of that person. We recommend using the following business details to create a suitable consumer record for small business lending purposes: 1. Use the business's 9 digit Employer Identification Number (EIN) in place of the social security number (SSN) usually passed as the `ssn` parameter. Do not include any formatting such as hyphens when passing an EIN here. 2. Use the business name as the `firstName` parameter. 3. Use the business type (`LLC`, `LLP`) as the `lastName` parameter. 4. Use the date that the report is ordered for the required `birthday` parameter. For example: ```JSON { "firstName": "ABC Plumbing", "lastName": "LLC", "address": "434 W Ascension Way", "city": "Murray", "state": "UT", "zip": "84123", "phone": "1-801-984-4200", "ssn": "123456789", "birthday": { "year": 2023, "month": 7, "dayOfMonth": 25 }, "email": "admin@example.com" } ``` ### Operations for Retrieving and Managing Consumers {#operations-for-retrieving-and-managing-consumers} API Reference: `GET /decisioning/v1/customers/{customerId}/consumer` API Reference: `GET /decisioning/v1/consumers/{consumerId}` ## Next Steps {#next-steps} * To learn more about the Data Connect user experience, which allows your customers to consent access to their accounts, read about [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). * For the full list of testing profiles available, refer to [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). --- # Release History source: https://developer.mastercard.com/open-finance-us/documentation/release-history/index.md Notable changes to the US Open Finance documentation are listed below (in reverse chronological order). | Date | Description | |-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 08 Jun 2026 | **New Feature** : A new [Payment Risk Insights](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GeneratePaymentRiskInsightsReport) endpoint is now available which can generate both [consumer](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/payment-risk-insights/index.md) and [small business](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) reports. Previously, only small business reports were supported. | | 05 Jun 2026 | We've updated the documentation on how to use the [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) tool within Client Hub to reflect changes to how you can request reports and manage users. | | 21 May 2026 | **New Feature** : Partners using the [Partner Direct model](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md) to onboard an affiliate partner now have the option to duplicate an existing Data Connect experience ID via a new endpoint. Once you have an experience ID which is suitable, you can duplicate that experience as many times as you need in order to [create new experience IDs for your affilates](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md#create-an-experience-for-your-affiliate-customers). Each duplicate experience can be modified further after it is created if necessary. | | 05 May 2026 | We've updated the title of the [Recurring Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md) page in this documentation (formerly Recurring Transactions) to better reflect the name of the product in our sales catalog. The Recurring Analytics product allows you to identify a customer's patterns of recurring payments, by categorizing recurring transactions associated with multiple accounts owned by the customer. | | 17 Apr 2026 | **New Feature** : [Consumer Foresight](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md) now supports a new endpoint, [Generate Non CRA Foresight Analytics Report Using 1st/3rd Party Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateForesightAnalyticsFirstThirdPartyNonCraReport), which can use third-party data permissioned via Data Connect, first-party data submitted via [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md), or both. The previous endpoint remains available as a legacy option. | | 16 Apr 2026 | **New Feature** : The React Native [Connect Transfer SDK](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) has been updated with support for [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md), which was previously only supported by the iOS and Android Connect Transfer SDKs. The new version has updated dependencies and requirements. Refer to [React Native Installation and Use](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#react-native-installation-and-use) for details. | | 02 Mar 2026 | **New Feature** : The [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) tool within Client Hub can now be used for [Report Reissue](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#report-reissue), allowing a secure and auditable, no-code access for third-party entities to retrieve consumer reports directly from the Order Reports system. This provides lenders and their partners with a method for sharing consumer reports between authorized third parties (such as investors, mortgage insurers, QC agencies, and loan management systems)---minimizing repetitive file exchanges, lowering risk, and facilitating more seamless cooperation throughout the loan process. | | 26 Feb 2026 | To avoid potential problems with transaction IDs being re-used across different customers, the transaction data returned by the [Transaction Data Services](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) endpoints and [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) now include a `uniqueTransactionId` value derived by combining the regular transaction ID with the account ID. This unique ID can be safely used to later identify a particular transaction without needing to check the account ID separately. | | 08 Jan 2026 | **New Feature** : [Recurring Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md) is a new service to identify a customer's recurring payments. You can request information for multiple accounts owned by the same customer with a single API call and retrieve a list of recurring transactions, with categories like "Streaming Service" or "Bills \& Utilities". | | 19 Dec 2025 | We've added a new [Small Business](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/index.md) section featuring [Small Business Credit Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) (previously a standalone API and now available as part of Open Finance). The Payment History report has been moved to Small Business and is now called [Payment Risk Insights](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md). | | 20 Nov 2025 | We've added a new [Tutorials](https://developer.mastercard.com/open-finance-us/documentation/tutorials/index.md) section with guides on how to implement common scenarios using the Open Finance APIs, including alternative flows so you can choose the best pattern for your application. Our first tutorials cover [Pay by Bank](https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md) and [Tenant Screening](https://developer.mastercard.com/open-finance-us/documentation/tutorials/tenant-screening/index.md). | | 31 Oct 2025 | We've added documentation on how to use the [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) tool within Client Hub, which allows Lend reports to be generated manually. This can be used for testing, as a temporary solution while building an application, or for certain no-code use cases without needing a full API integration. | | 20 Oct 2025 | **New Feature** : The [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) feature in Client Hub now provides options to alter the color of the text used on CTA buttons, and to skip report generation if you do not want reports to be generated automatically when the user completes the experience. | | 22 Sep 2025 | Updated [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) endpoints are now available. The new endpoints provide a score for the risk of unauthorized return. The existing NSF risk score is now optional. | | 19 Sep 2025 | **New Feature** : [Feedback Loop](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md) is a new way for you to securely share payment outcome data with Mastercard to improve product performance, enabling reduced payment failures and more accurate risk scores. Feedback Loop currently supports [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) and [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md), with support for more products to come. | | 16 Sep 2025 | We've re-organized and improved the [Lend](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) documentation. Report pages are now more detailed and are grouped under [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md). | | 02 Sep 2025 | We've renamed Mastercard Open Banking to Mastercard Open Finance. This new name better reflects the full range of financial solutions we offer---extending beyond banking to support a more inclusive, connected financial ecosystem. The existing functionality remains the same and you don't have to change anything with your existing projects (if you create a new project on Mastercard Developers, look for Open Finance instead of Open Banking when selecting the API service). | | 11 Aug 2025 | **New Feature** : The [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) feature in Client Hub now provides the option to edit a logo image after uploading, allowing you to change the size and position of the image. | | 07 Aug 2025 | **New Feature** : A [Connect Transfer Mobile SDK](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) for React Native is now available, enabling Deposit Switch functionality for React Native apps. | | 18 Jul 2025 | **New Feature** : The [Payment Enablement Bundle](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) consolidates several individual API services into a single combined endpoint capable of returning variable responses based on your input parameters. Using PEB can simplify your development work and reduce the number of API requests needed by returning data for any or all of the following: Account Simple Details, Account Owner Verification, Account Balance, and Account ACH Details. | | 02 Jul 2025 | **New Feature** : The [Data Connect Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md) is now available via our Content Delivery Network (CDN). This provides an alternative way to use the SDK without installing via npm. | | 18 Jun 2025 | **New Feature** : We've improved support for partners who need to [integrate Data Connect without using our SDKs](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/index.md). For mobile apps developed without our SDKs, you must ensure you set the new `isHostedInMobileApp` flag to true when [generating your Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). We've also taken the opportunity to re-organise the [Integrating with Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md) pages to better illustrate the SDK versus non SDK integration options. | | 21 May 2025 | **New Beta Feature** : [Consumer Foresight](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md) provides tailored consumer insights against various spend categories, generated using the consumer's permissioned Open Banking data as well as anonymized transactional data from the Mastercard network. This feature is in Beta and will incur an additional cost. Contact your Sales representative or Account Manager to learn more and join the pilot group. | | 07 May 2025 | **New Feature** : The [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) feature in Client Hub will now attempt to automatically convert logo images provided in raster formats such as PNG into the required SVG vector format. Results using this method may vary, we recommend providing SVG files where possible. | | 11 Apr 2025 | **New Feature** : [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md) empowers consumers to update their payment information (ACH or Card on file) for recurring bills and subscriptions, making it easier to switch financial providers. Bill Pay Switch uses TrueAuth device-based authentication and so is currently only suitable for mobile applications. In addition to the developer documentation we also provide [sample UX flows and best practices in our Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/bill-pay-switch/index.md). | | 08 Apr 2025 | **New Feature** : [Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/index.md) provides pre-built embeddable components that allow you more control and flexibility over your customer's Data Connect experience. By leveraging Data Connect Components, you can design and test your user experiences to have the voice, brand, flow and feel that best meets your needs. Data Connect Components is the first US Open Banking feature to use our new [Open Banking Webhook Management System (OBWMS)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md), which provides a unified system for subscribing to and receiving webhooks from the various Open Banking services. New services will use this system for webhooks and existing Open Banking products and services will migrate from the old webhook system to the new one during 2025/2026. | | 26 Mar 2025 | **New Feature** : [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) can enhance your internally held (first party) financial account transaction data by categorizing transactions, identifying the entities and platforms involved, location data, logos, and website URLs. This helps improve the usability of transaction data for various applications, such as personal financial management tools and online banking platforms. | | 13 Mar 2025 | **New Feature** : The [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) feature in Client Hub now provides a 'Single Use URL' option. This feature will only allow a user to use a link a single time. This is to prevent users from generating multiple reports through one Data Connect session, or adding multiple accounts when only one is needed (this setting will not override the `singleUseUrl` parameter passed to the Generate Connect URL API). | | 25 Feb 2025 | **New Feature** : Our new [Account Owner Verification Matching](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) feature enables customers to request account details for an account holder from an institution, with a matching confidence score compared to information provided by the user's connected financial institution. | | 4 Feb 2025 | **New Feature** : [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) provides a score based on the real-time account balance and historical account activities to evaluate the likelihood a given payment amount will settle successfully in a given time period. | | 29 Jan 2025 | The [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) now includes UX recommendations and best practices advice for how to present the [AVA flow](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md) in your application. | | 27 Jan 2025 | The [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md) documentation provides details of how our new [Connect Transfer mobile SDKs](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) can be used to integrate Deposit Switch into native mobile applications. The Connect Transfer mobile SDKs provide native iOS and Android versions of the Atomic user experience, which is not supported by the regular Data Connect mobile SDKs. The Connect Transfer SDKs also support TrueAuth authentication of the end user with the payroll provider. | | 12 Dec 2024 | We've made a change to the billing logic for [Account Statements](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md). You are now billed when you call the endpoint which downloads a PDF asset relating to a statement, not when you call the endpoint which returns details of the available statements. This change also means that you can check what statements are available without charge before generating a [Statement Report](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/statements/index.md) for Lending purposes. | | 8 Nov 2024 | **New Feature** : The [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) feature in Client Hub lets you configure the Data Connect application's user experience on your own. Generate an Experience ID and tailor the application to align with your brand and user requirements. | | 7 Nov 2024 | **Developers API (Onboarding API) Key Management Update** : You can now create new Developers API keys and access existing ones directly from your [Account](https://developer.mastercard.com/account/profile) page. You no longer need to create projects to get your API keys. **No Impact on Existing Keys**: Current API keys and integrations remain unaffected. | | 11 Oct 2024 | **New Feature** : Our new [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md) feature enables customers to connect with payroll providers and set up payroll deposits with ease. In addition to the [developer documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#how-it-works) we also provide [sample UX flows and best practices in our Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md). | | 02 Oct 2024 | We've added details of our [SDK Deprecation Policy](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md#sdk-deprecation-policy) which will apply to Open Banking Data Connect SDKs (mobile and web) from Q4 2024. We strongly recommend that partners update to the latest version of our SDKs as soon as possible to avoid potential disruption. Deprecated SDKs will continue to function but will not receive support. | | 23 Aug 2024 | **New Feature** : We now support [Fast AO](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#fast-aov), which can cache Account Owner details during the Data Connect process for quicker account owner verification. This is not suitable for all partners and is not supported for all FIs. Speak with your Account Manager to determine if Fast AO is right for your use case. We've also updated [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) with tokenized account number (TAN) information and [Consumers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) with details for reseller partners when creating a consumer record. | | 03 Jul 2024 | **New Feature** : You can now retrieve a customer's authorization period for a specific financial institution via the [GET /customers/institution-logins/{institution_login_id}/authorization-details](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#retrieve-customer-authorization-period) endpoint. We've also updated the [Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md), [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md), [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md), and [App registration](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md) documentation. | | 14 Jun 2024 | We've updated the [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) with further UX recommendations and best practices advice for how to present the Data Connect flow in your application, including advice on [app to app implementation](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/app-to-app-auth-best-practices/index.md) and how to build a [user-friendly FI search experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/fi-search-experience/index.md). | | 06 Jun 2024 | We've introduced [TxPUSH webhook notifications](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md#txpush-webhook-notification) for you to receive account updates. | | 22 May 2024 | **New Feature** : We've updated the documentation for [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) with a new V3 endpoint that includes RTP details if available. | | 17 May 2024 | We've made several enhancements to the project dashboard to improve your overall experience: * We've designed a new Summary page that consolidates key information in one place, allowing you to view critical details at a glance. * [Streamlined access to production](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#moving-to-production) - You can now choose between Test Drive Premium or Production, when requesting production access. This update clarifies which options are billable and details the benefits of each plan, ensuring a smoother transition from testing to deployment. * [Edit project details](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#edit-project-details) - You now have the ability to edit your project details even after the initial project creation step. This change provides more control over the project's lifecycle and aims to align with your evolving business needs. **Updates to onboarding APIs:** * **New Feature** : We've introduced a new endpoint to help you update your project details on Mastercard Developers - [PUT /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#updateProject). * Removed deploymentCountries field from the [POST /projects](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/?view=api#createProject) endpoint as we no longer require you to provide us the project's host location. For full list of changes, see [Mastercard Developers API's Release History](https://developer.mastercard.com/mastercard-developers-api/documentation/release-history/). | | 16 May 2024 | We've updated the documentation for [Balance Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) and [Cash Flow Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md) with new V2 endpoints which work for both FCRA and non-FCRA use cases. | | 24 Apr 2024 | **New Feature** : It is now possible to query the experience ID relating to your registered application if you have set up a [configured Data Connect experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) for your app. The new [Get Experience IDs](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md#retrieve-experience-ids) endpoint can be used to find any experience ID associated with your app at run-time. | | 19 Apr 2024 | We've added some new test personas that you can use when testing your app. These personas have different levels of income, access to different banking products, and realistic data. You can use these personas to simulate different user journeys and interactions with your app. These new detailed personas are provided in addition to the existing test profiles which you can continue to use for testing particular scenarios. See [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) for details. | | 11 Apr 2024 | We've improved our [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) section to serve as a comprehensive guide for all the errors you might encounter while using Mastercard's Open Banking solutions: * Errors have been broadly categorized into Account, Institution, and Request errors based on when they occur during the use of our Open Banking solutions. * Errors have been further classified into themes to provide you with an easier understanding of error contexts and effective troubleshooting. | | 28 Mar 2024 | We've re-structured the Data Connect SDK documentation into a new [Integrating with Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md) section which discusses each of the Data Connect SDKs (Web, iOS, Android, and React Native). This documentation now provides details of how you can implement app to app authentication on mobile platforms either with the mobile SDKs or by using the Web SDK and displaying web content within secure web containers or webviews. | | 06 Mar 2024 | The new [Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/index.md) portal offers an easy-to-use interface to monitor the health of financial institutions and simplify your billing reconciliation process. | | 19 Feb 2024 | As a [direct partner](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md), you can now use the Mastercard Developers Dashboard to [onboard](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md#onboard-using-mastercard-developers-dashboard) and [manage](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/managing-customers/index.md#manage-using-the-mastercard-developers-dashboard) your affiliate customers. **Breaking Change** : To comply with data regulations, we've introduced a breaking change in the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/) that now requires you to update your integration. The [POST /projects](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/) endpoint has been updated to include: * `commercialCountries` (required) - A list of countries where the project's customers are located * `deploymentCountries` (optional) - A list of countries where this project is hosted. | | 09 Feb 2024 | The [Data Connect React Native](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/react-native-sdk/index.md) SDK v2.0 is now available which supports app to app authentication. The Data Connect React Native SDK provides an easy way for you to integrate Mastercard Open Banking Data Connect into your React Native mobile application, providing another option in addition to our native iOS and Android Data Connect SDKs. | | 08 Feb 2024 | **New Feature** : The new [Business Services APIs](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses) provide details on how you can create and manage business records associated with customers. | | 14 Dec 2023 | We've provided a sample React application which allows you to explore examples of the Open Banking APIs can be implemented in your applications. The sample source code is available on GitHub. See the [Reference App](https://developer.mastercard.com/open-finance-us/documentation/reference-app/index.md) section for details. | | 23 Nov 2023 | The [Lend Statements documentation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/statements/index.md) now provides a detailed explanation of how to generate Statement Reports, with a sequence diagram illustrating the API calls involved. | | 20 Nov 2023 | The new [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) provides UX recommendations and best practices advice for how to present the Data Connect flow in your application. | | 8 Nov 2023 | We've added a [Use Cases](https://developer.mastercard.com/open-finance-us/documentation/usecases/index.md) section which describes the API flows involved in various Open Banking applications. | | 17 Oct 2023 | We've updated the way in which the [API Reference](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) is displayed, with separate sections for API [Endpoints](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md?view=api) and [Models](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md?view=model) (structures). | | 16 Oct 2023 | You can now browse a table showing the current state of the [Supported Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md). The table lists the Financial Institutions (FIs) which have gone through our certification process, showing which products each FI supports. | | 25 Aug 2023 | The [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) documentation has been updated and a note about Chase Webview support has been added to the [Generate Data Connect URL - Webviews](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#webviews) section. | | 18 Aug 2023 | The Data Connect Full user experience has been updated so that the first screen the customer lands on shows the terms and conditions and privacy agreement. Because this screen appears before the FI selection screen, the user only has to interact with it once, rather than each time they select an FI. The new flow is described in the [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows) section, and there is a new [Data Connect route event](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-route-events/index.md) associated with the new landing screen. | | 11 Aug 2023 | Introduced [Partner Direct Model](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md) for direct partners of Mastercard Open Banking services to seamlessly onboard their affiliate customers through [Mastercard Developers API](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md). The [Android SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/index.md) and [iOS SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/index.md) documentation now includes details on app to app authentication support for iOS and Android. | | 22 Jun 2023 | Updated the warning note about upgrading the Mastercard Open Banking Android SDK to the [Android SDK documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md), and improved the Testing section of the [Account Validation Assistant (AVA)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md) documentation. | | 02 Jun 2023 | Added warning note about upgrading to the latest version of the Mastercard Open Banking Android SDK to the [Android SDK documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md), in order to maintain support for Custom Tabs. | | 19 May 2023 | **New Feature** : We've added a new feature, [Account Validation Assistant (AVA)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md). This provides bank account validation by allowing partners to verify their customers bank account details using microdeposits before initiating payments. | | 15 May 2023 | The [Verification of Account Owner](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) documentation now includes details of a new option which allows you to obtain Ekata identity insights data. This option is in Beta and will incur an additional cost. Contact your Sales representative/Account Manager to learn more and join the pilot group. | | 02 May 2023 | We've updated the [Lend Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) documentation to include a "How It Works" section with a sequence diagram. The Generate VOE Payroll and Generate VOIE Payroll Reports requests now include `marketSegment` and `purpose` parameters. We've also updated the [Financial Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md) page to include descriptions of the Get Institution Branding by ID and Get Certified Institutions With RSSD endpoints. | | 06 Apr 2023 | The Data Connect Full, Lite, and Fix experiences can all now be displayed in a webview within a native application, rather than in a browser. A new request parameter `isWebView` has been added to the relevant [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) endpoints, which you must specify when using webviews. We've also re-worked the Generate Data Connect URL documentation and included details of the [Send Data Connect Email](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#send-data-connect-email) endpoint. | | 05 Apr 2023 | We've added a list of the [FIs which currently have OAuth connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md#oauth-fi-connections). | | 06 Mar 2023 | Updated [Verification of Account Owner](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) documentation. The new V3 version of this API is recommended for all users. | | 23 Feb 2023 | Added documentation for [Partner Linked Access](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/index.md). This allows you to collect consent from your customer to enable a third party (such as a payment processor) to retrieve customer data from Mastercard Open Banking. The third party will only have access to the specific data which the customer grants consent for. | | 22 Feb 2023 | Significant re-organisation of [Product](https://developer.mastercard.com/open-finance-us/documentation/products/index.md) pages. All products are now grouped into either [Lend](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md), [Manage](https://developer.mastercard.com/open-finance-us/documentation/products/manage/index.md), or [Pay](https://developer.mastercard.com/open-finance-us/documentation/products/pay/index.md). As part of this work the [Manage](https://developer.mastercard.com/open-finance-us/documentation/products/manage/index.md) pages relating to data access ([Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md), [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md), and [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md)) have been improved, and [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) are introduced. | | 01 Feb 2023 | Added documentation for [Balance Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) and [Cash Flow Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md). | | 15 Nov 2022 | Initial version of this documentation published to Mastercard Developers. | --- # Financial Institutions source: https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md Mastercard Open Finance empowers your organization to make effective decisions around which Financial Institutions (FIs) and connections you should leverage throughout your product's flow. Our endpoints are flexible, allowing you to search for a known FI's status and information or to view all information pertaining all supported institutions. These services provide important information such as the status and availability of institution connections, the type of institution connection (legacy vs OAuth), and a list of what products are supported for specific FIs. This is especially important for premium endpoints as not all FIs have support for premium products. By customizing your experience to only show FIs that are available and capable of supporting your specific product needs, you can ensure that your customers have an excellent experience without unnecessary noise or friction. To view a full list of FIs that are available as well as their supported products, visit our [Supported Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) page. If an FI appears to be unsupported or not available, submit a ticket for the specific FI to be added to our platform. The process of adding a new institution typically includes: * *Assessment*---We conduct a thorough assessment of the institution's compatibility with our platform and their ability to provide quality account data. * *Integration*---We align the institution's systems with our standards, which is a detailed process. * *Development*---We code and align the new institution's systems to ensure seamless data flow and compliance. * *Testing*---We thoroughly test the integration to ensure seamless and consistent performance. * *Compliance*---We certify that the institution complies with regulatory requirements. * *Ongoing Maintenance*---After certification, we actively monitor the integration for changes in success rates. ## Institution Operations {#institution-operations} Use the Get Institution APIs to: * Search for and obtain information regarding a specific FI connection. * Retrieve a list all supported FIs and their supported products. The response provides the FI's specific detailed information. * Determine the connection type of a specific institution. Some institutions have an OAuth direct integration, which allows customers to log into their financial institution directly to control account permissioning or disconnect from the FI. An institution has an OAuth integration if that institution returns with the parameter `oauthEnabled: true`. API Reference: `GET /institution/v2/institutions` API Reference: `GET /institution/v2/institutions/{institutionId}`
API Reference: `GET /institution/v1/institutions/routingNumber/{routing_number}` If you only need the branding information for an FI you can use the following: API Reference: `GET /institution/v2/institutions/{institutionId}/branding` ## Certified Institutions {#certified-institutions} We work with as many financial institutions as possible to become certified. FIs are certified based on their accessibility from the Open Finance platform, and whether they meet the criteria of being able to seamlessly add consumers and retrieve quality account data with performance consistency. Some FIs aren't certified due to their inability to meet the qualifying standards criteria. It's also possible that some certified FIs aren't certified for specific products. If a product isn't supported, then all related APIs for that specific product are prevented from returning data. The benefit of Certified FI connections is their healthy state, which helps you leverage our products and consume quality data for your business needs. ### List of Certified FIs {#list-of-certified-fis} Use this endpoint to return a list of all certified FIs and their supported products. To return a list of certified FIs for a specific product, change the `type` field to a product name from the list. API Reference: `GET /institution/v2/certifiedInstitutions` If you want the response data to include RSSD ID values for the FIs, use the following: API Reference: `GET /institution/v2/certifiedInstitutions/rssd` The RSSD ID is a unique identifier assigned to financial institutions by the Federal Reserve. ### Product Matrix {#product-matrix} This table maps the values sent back in the `institutions` structure of the Get Certified Institutions response to the products available. A value of `true` for each of these fields indicates that the FI supports that product. | Value | Product | |------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | **transAgg** | [Transaction Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) | | **ach** | [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) | | **stateAgg** | [Statements](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) | | **voi** | [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) | | **voa** | [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) | | **aha** | [Account History Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) | | **availBalance** | [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) | | **accountOwner** | [Account Owner](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) | | **loanPaymentDetails** | [Loan Payment Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md) | | **studentLoanData** | [Student Loan Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md#student-loan-data) | ## Resources {#resources} Within the Mastercard Data Connect experience you can control which financial institutions appear for your customers; refer to [Institutions Settings](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md) in the Data Connect section for more information. --- # Support source: https://developer.mastercard.com/open-finance-us/documentation/support/index.md Here we provide details of how you can get support, along with Frequently Asked Questions and other material. We provide two levels of support: * For specific product help with Mastercard Open Finance, we provide a full Support Case Management (SCM) tool via the Mastercard Connect website. * For general enquiries and help with the Mastercard Developers website and API access, use the ["Get Help" button on this page](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#get-help-with-mastercard-developers). ## Get Help With Mastercard Open Finance {#get-help-with-mastercard-open-finance} Mastercard Connect is the secure global platform where Mastercard business customers come to onboard, enroll, service, and grow their business with Mastercard. The Support Case Management (SCM) tool within Mastercard Connect is used to create and track support cases created in SCM with the Mastercard Open Finance support team. Note: Access to the SCM tool on Mastercard Connect is only available once a contract between you and Mastercard has been executed. Please work with your Sales Representative or Client Success Manager, or contact [OFin.contactsales@mastercard.com](mailto:OFin.contactsales@mastercard.com) for more information. ### Create a Support Case in SCM {#create-a-support-case-in-scm} To create a new Support Case: 1. Sign into 2. Select **Support Case Management** from the menu. 3. Go to **Support Cases** and click on the **Go to support cases** button (alternatively, you can access support cases through the Help Center by clicking on the **Help** icon). 4. On the **Support Cases** page you can create a new case, or track the progress of an existing case. To create a new case, click on the **Create new case** button. * Enter a suitable summary (a brief description of the issue) in the first text box. * Select Open Banking (US and Australia) as the category so your query goes to the correct team (select **Other** and **Open Banking** , then **US and Australia** ). ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/OFin-SCM-create-case.png) * Add details of the issue in the Description field. * Under the **US and Australia information** heading, select the **Issue Type** (for example, **Request a new feature** or **New support case** ). ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/OFin-SCM-create-case-us-aus-info.png) * When you've entered all the information required, click on the **Create Case** button. ## Get Help With Mastercard Developers {#get-help-with-mastercard-developers} You can contact us for technical support for issues relating to the Mastercard Developers Platform by clicking on the "Get Help" button:
Once logged in to Mastercard Developers you can get help with issues such as API access keys, information on other API products on the Mastercard Developers platform, and other related matters. Note that this service will not be able to provide in-depth product support for Mastercard Open Finance. Tip: You can also talk to other developers on the [Mastercard Developers Forums](https://forum.developer.mastercard.com/s/). ## Frequently Asked Questions {#frequently-asked-questions} Before contacting us, check our list of FAQs. We've grouped these in different themes. ### General {#general} Mastercard Open Finance has two levels of test access: * The Sandbox version allows access to all endpoints using testing customers and mock Financial Institution data. * Production (Non-Billable) is also a testing environment but uses active customers and real Financial Institution data. A testing customer is used for testing purposes and can only be used with Mastercard Open Finance test profiles and test bank (Finbank). An active customer mimics the workflow of the production environment, however no charges are incurred. When the account is moved to Production any active customer existing in the schema will then become a billable customer. In the Mastercard Open Finance system, there are two different types of customers: "testing" and "active". Testing customers can interact with our testing institution, Finbank, but cannot interact with live institutions. Testing customers are to be used for development and ongoing regression testing and will not be used in production. Conversely, active customers (also referred to as billable customers) represent end users on your platform. They can interact with live institutions but will throw an error if you try to add data from a testing institution. Each customer type has its own endpoint for creation. Note that if you are not on a Production (non-billable) or one of the Production-level plans, you will not have the ability to create active customers. Sandbox is the free tier used for testing and you will not have access to live FI data. Sandbox allows partners to test and use our APIs using Finbank or Finbank Profiles located on our documentation under Test the APIs. Production is a paid tier and allows partners to access live FI data, i.e. Chase and Wells Fargo, using an "active customer" (also referred to as billable customers) which represents end users on a partner platform. 500 testing customers. If this limit is hit, it is suggested to delete testing customers from the environment. After the customer's initial report is generated and during the credit-decisioning process, you can refresh the reports using the APIs rather than re-engaging the customer. Financial Institution data reports have unlimited free refreshes within 60 days. There is a one-to-one relationship between a customer record and a consumer record. While the customer record can be deleted after use, a consumer record cannot. As Mastercard Open Finance is a Credit Reporting Agency, we are required to retain report records associated with a consumer ID for six years, in order to support potential disputes of inaccurate information. ### Auth \& Configuration {#auth--configuration} A Mastercard Open Finance Auth Token is valid for up to two hours (120 minutes) and is required to access all of the Mastercard Open Finance endpoints. Best practice is to use a single token for all endpoint requests and assign a timestamp for each token. Check the current timestamp before making any requests and if the token is older than 90 minutes, generate a new token. This typically implies the app key is wrong. It will say too many requests because the app key controls the rate limit, and the rate limit of any invalid key is 0. If the Partner ID or Partner Secret is wrong, an "Invalid Credentials" error will be thrown instead. A Mastercard Open Finance token is required to access any of the APIs and is passed as a header. See [Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). After 5 attempts to call **Create Access Token** with an incorrect Secret, API access for the Partner ID used will be locked. You will receive a 24302 error for all subsequent API calls. Please contact [Open Finance support](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) to get assistance unlocking your account. ### Mastercard Data Connect {#mastercard-data-connect} Yes, Mastercard provides SDKs for both web and mobile (iOS and Android). See [Integrating with Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md). Yes. During your onboarding to Production the product delivery team will work with you to configure the financial institutions you want to display. See [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) and [Institutions Settings](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md). Yes, this will be configured with the product delivery team during your onboarding to Production. You can also temporarily change these settings when you generate a Data Connect URL. See [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) and [Institutions Settings](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md). Mastercard's Open Finance Solutions generic branding will be used, and a standard transaction aggregation will be performed. No. The Experience parameter can be omitted. The absence of this parameter will cause Data Connect to default to using Mastercard's generic branding and performing a standard transaction aggregation. Yes, the old account would still be shown to the user after being closed. However, Mastercard Open Finance would not be able to aggregate data from the old account as it has been closed at the Financial Institution. Yes. It is possible to customize the Data Connect experiences to support multiple Mastercard Open Finance solutions. Reach out to your Account Manager for assistance customizing your Data Connect experience. See [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md). ### Financial Institutions {#financial-institutions} Mastercard Open Finance provides FI Certification status information via the [Get Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#certified-institutions) API. You can also check the status manually on the [Supported Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) page. ### Products {#products} The GET Account Owner endpoint returns the following values: **Account Owner(s) names as listed by the Financial Institution** Mastercard Open Finance will pass a Name string that reflects the name(s) on the account In some cases, slight differences can appear between data returned by Mastercard Open Finance Account Owner service and data provided by a legitimate user. A user might omit their middle name in an application, or provide a shortened version of their legal name. There are several techniques a client can implement to reduce the chance of these mismatches, including substring matching, string cleaning to remove data such as initials and suffixes, or applying a fuzzy matching algorithm, for which many open-source implementations are available. **Address on file for the given account** The easiest form of address matching is the matching of city names, regions, and postal codes, after ensuring that you have transformed these into the same format that you have obtained from your user (for example, making sure that any zip code is in a 5-digit format rather than a 9-digit format). Street addresses can be compared using the same techniques as described in the "Name" section to avoid any mismatches caused by slight inconsistencies. Mastercard Open Finance outputs reports in the following formats: JSON, XML, PDF. The Accept header is used to indicate the type of media or resource used in the response. A "shadow" transaction occurs when a transaction is originally found during an account aggregation, but in a subsequent aggregation, the transaction is not found. Therefore, it is unknown whether the transaction is still legitimate because it is possible that the financial institution (FI) may have determined that the transaction was invalid and removed it from the FI's data source. Alternatively, the FI may have altered the transaction to be substantially different from the original transaction. These modifications or deletions can cause transactions to duplicate in the Mastercard Open Finance data or persist after being removed from the institution's data source. Mastercard identifies these transactions by designating them with a "shadow" status. Developers may choose how to handle the shadow status, but we generally recommend treating them as having been deleted from the data source. **Note:** In some cases that result in a shadow status, there may be a new active transaction representing the new transaction state. There is no need to link these transactions together as the current transactions at the FI represent the latest transaction state. No, account details can be used for recurring payments on a given account. Only if an account materially changes might it be necessary to re-verify. Mastercard Open Finance would recommend the use of our Account Balance Check product to have higher confidence in the availability of funds prior to processing a payment. No. A client only needs to validate an account on the first interaction. If the client already has an account number for a given Account ID, they may only need to retrieve the balance for the account prior to processing any payment to see if funds are available. ### Metrics Dashboard {#metrics-dashboard} The API metrics dashboard provides a unified, real-time view of your integration's health, performance, and usage. It acts as a comprehensive monitoring and business intelligence tool. The dashboard visualizes key metrics such as API call volume, latency, and error rates, and offers detailed logs for every request, response, and webhook event. 'My API Success Rate' is calculated using just the API traffic for a particular partner ID (or group of partner IDs if you select a project). It shows you how just the API calls you are making are performing. The Dashboard shows this alongside the 'Platform API Success Rate' which is based on traffic from all partners for the same API endpoints. This allows you to see how the requests you are making compared to all other partners on the platform who are making the same API calls. Active accounts represent bank accounts that the platform is connected to and retrieving data from. This is not the same as active end users (account holders) as an end user can have multiple accounts. Every API call you make will return a response and included in every response is a "response code" that indicates if the call was successful or not. The platform collects these success codes for every API request made and calculates a percentage of the successful calls against the total number of calls being made. It does this across different intervals depending on how you are filtering the data: * For a Dashboard showing the last hour of data, it will calculate the API success rate every 5 minutes. * For the last 24 hours of data, it will calculate the API success rate every 60 minutes. * For the last 7 days of data, it will calculate the API success rate every 6 hours. * For the last 30 days of data, it will calculate the API success rate for each day (24 hours). When you add a new partner ID to a project it can take up to 10 minutes for that new partner ID to be picked up by the Dashboard metric calculations. If you refresh the Dashboard within 10 minutes of adding the partner ID, the calculations may not have completed yet and there won't be any data to be rendered. Wait for 10 minutes and when you refresh the Dashboard it will be visible. Some of the API products you call are actually made up of collection of API calls e.g. the Verification of Income Report will call the Get Transactions API behind the scenes in order to generate the report. The Dashboard tracks every API call that is made either directly by the partner, or indirectly to fulfil the requirements of another product API. Sometimes when you call an endpoint like "Get Transactions" it will pull the data from our database cache. This is much faster than making a direct call to the Financial Institution every time. When data is returned from the cache it means there was no direct call to the Financial Institution and so that endpoint won't be listed under it in the dashboard. There are two possible reasons why your API success rate may be different to the value displayed in the dashboard: 1. The dashboard does not yet include API calls that encountered an error at the API Gateway i.e. before the API call made it to the Open Banking product service. If you filter out API calls that were rejected by the API Gateway your API success rate should align with the dashboard. 2. The dashboard does not include a small number of API calls. If you filter out the following short list of APIs your API success rate should align with the dashboard: * /connect * /connect-components * /connect/v2/experiences * /connect/experiences * /connect/v1/certifiedInstitutions * /institution/v1 * /institution/v2 * /applications * /applications/({application_id}/institutions * /customers/institution-logins/{institution_login_id})/authorization-details * /curator/v2/experiences * /connection-status * /payroll-connector * /dcr * /analytics/balance * /analytics/cashflow * /analytics/payment-history * /analytics/business * /analytics/data * /payments/paymentIndicator * /transfer/webhooks * /transfer * /business-services The Dashboard tracks every error code returned and groups them into one of four categories: * **Financial Institution**: errors returned by the Financial Institution when the platform tried to request data. These could be related to expired tokens, end users revoking access to their account, maintenance windows, etc. * **Platform**: errors returned by the US Open Banking API services. These could be related to a timeout when making a call to one of the API endpoints, an expired access token, etc. * **Customer**: errors related to issues that the calling client can correct. These could be related to malformed request payloads, expired tokens, calling an API in the wrong order, etc. * **Other**: errors that don't belong to the previous three categories. We endeavor to identify any errors in the Other category and move them to the correct category. The Billable report in the Client Hub only includes billable API calls. The Mastercard Developers dashboard includes billable and non-billable API calls. The "Direct" category represents connections to Financial Institutions that use OAuth. The "Legacy" category represents connections to Financial Institutions that don't use OAuth and these are typically slower. The "Blended" category groups all the Financial Institutions together and calculates median and P90 response times for all of them. --- # Quick Start Guide source: https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md ###### Time to Complete: **30 minutes** {#time-to-complete-30-minutes} Follow this guide to: * Introduce yourself to the Mastercard Data Connect application and the foundational Open Finance APIs * Get access to high-quality test data from our Sandbox environment ## Create a Sandbox Project {#create-a-sandbox-project} 1. [Log in](https://developer.mastercard.com/account/log-in) or [sign up](https://developer.mastercard.com/account/sign-up) to Mastercard Developers and select **Create New Project**. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/create-mc-project.png) 2. Provide **Project Details**: a. Enter a name for your project. b. Choose if you want to create a project for yourself or for a client. Select **No** if this project is for yourself or select **Yes** to create the project on behalf of a client. If you are creating a project on behalf of a client, see [Partner Direct Model](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md) and learn how you can [onboard your affiliate customers](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md). c. Select **Open Finance** from the **Select your API service** drop-down list. d. From the **Commercial Countries** drop-down list, select the country where the end users of this application will be located. You cannot update Commercial Countries after this step. Ensure you select the appropriate country before you click **Proceed**. e. Click **Proceed**. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/onboarding-select-project-openfinance.png) ## Generate Your Credentials {#generate-your-credentials} 1. Provide **Service Details**: a. Enter a description for your Sandbox credentials. b. Click **Create Project**. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/onboarding-select-us-creds-openfinance.png) 2. In the **Credentials** section at left, click **Sandbox** to view the Sandbox credentials: `Partner ID`, `Secret`, and `App Key`. These credentials are required to call the APIs. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/sandboxcreds.png) Note: If you need to use multiple environments for testing, for example, one test environment for developers and another for User Acceptance Testing (UAT), you can request additional Sandbox credentials with the **Add Partner ID** button. ## Welcome Your First Customer {#welcome-your-first-customer} Follow the steps below to create a test customer and share some test accounts with Mastercard Open Finance. The corresponding **Customer ID** will be needed for retrieving account and financial data. Tip: As an alternative to running the commands in the steps below, you can download and run the [setup script](https://github.com/Mastercard/open-banking-us-openapi/tree/main/bin). There are versions for [bash](https://github.com/Mastercard/open-banking-us-openapi/blob/main/bin/setup.sh) and [Powershell](https://github.com/Mastercard/open-banking-us-openapi/blob/main/bin/setup.ps1). For bash run: `./setup.sh {partnerId} {partnerSecret} {appKey}` For Powershell run: `./setup.ps1 {partnerId} {partnerSecret} {appKey}` You can also use pre-defined requests available in the "*Quick Start* " folder of the [Postman collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md). Don't forget to select the *Test Drive* environment (top right) and update the `partnerId`, `partnerSecret` and `appKey` variables.
### Step 1 - Create Access Token {#step-1---create-access-token} Note: Requests to the Open Finance US APIs must originate from an IP address in the United States, United Kingdom, Canada or Australia. All requests sent to Mastercard Open Finance must include a `Finicity-App-Token` HTTP header. Use your Partner ID and Secret with the following endpoint whenever you need to generate a new access token: API Reference: `POST /aggregation/v2/partners/authentication` Note: Access tokens are valid for two hours. As a best practice, generate a new token when the current token is older than 90 minutes to avoid expiration during API calls. * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/partners/authentication' \ --header 'Content-Type: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --data-raw '{ "partnerId": "{{partnerId}}", "partnerSecret": "{{partnerSecret}}" }' ``` * Expected response: ```json { "token": "YBh22Sb9Es6e66Q7lWdt" } ``` ### Step 2 - Add Test Customer {#step-2---add-test-customer} Create a "testing" customer record you can use with FinBank test profiles: API Reference: `POST /aggregation/v2/customers/testing` You can omit the `applicationId` from the request when generating testing customers. * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/customers/testing' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "username": "customerusername1" }' ``` * Expected response: ```json { "id": "1005061234", "username": "customerusername1", "createdDate": 1607450357 } ``` Take a note of the "id" value returned. It's the **Customer ID** you will use next. ### Step 3 - Generate Mastercard Data Connect URL {#step-3---generate-mastercard-data-connect-url} The next step is to generate a Data Connect URL which you can present to the customer in your application. This enables the customer to start a Data Connect session and grant Mastercard Open Finance access to their accounts and financial data. API Reference: `POST /connect/v2/generate` * Command: ```sh curl --location --request POST 'https://api.finicity.com/connect/v2/generate' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' \ --header 'Finicity-App-Key: {{appKey}}' \ --data-raw '{ "partnerId": "{{partnerId}}", "customerId": "{{customerId}}" }' ``` * Expected response: ```json { "link": "https://connect2.finicity.com?customerId=1005061234&origin=url&partnerId=2423653942467&signature=91f44ab969a9c7bb2568910d92501eb13aa0b7fd4fd56314ab8ebb4f1880fa83×tamp=1651326873996&ttl=1651334073996" } ``` ### Step 4 - Sign In to a Test Financial Institution and Submit Accounts {#step-4---sign-in-to-a-test-financial-institution-and-submit-accounts} To simulate what a customer would experience when connecting their accounts with a real financial institution, you can connect to our mock bank called "Finbank." 1. Open the URL generated at the previous step 2. Click **Next** to agree to the Terms and Conditions and the Privacy Policy 3. Search for *FinBank Profiles - A* 4. When asked for a username and password, type *profile_03* for both 5. Select all accounts, and then click **Save** and **Submit**
This is the expected flow an end user would see when linking their accounts with Data Connect: ![Data Connect flow](https://static.developer.mastercard.com/content/open-finance-us/uploads/dconnect-flow.gif) ### Step 5 - Refresh Customer Accounts {#step-5---refresh-customer-accounts} Before you can retrieve account transactions, you must do an initial aggregation. Call the following endpoint: API Reference: `POST /aggregation/v1/customers/{customerId}/accounts` * Command: ```sh curl --location -g --request POST 'https://api.finicity.com/aggregation/v1/customers/{{customerId}}/accounts' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' \ --header 'Finicity-App-Key: {{appKey}}' \ --data-raw '{}' ``` * Expected response: ```json { "accounts": [ { "id": "6020488409", "number": "232323", "realAccountNumberLast4": "2323", "accountNumberDisplay": "2323", "name": "ROTH", "balance": 11001.0, "type": "roth", "aggregationStatusCode": 0, "status": "active", "customerId": "6012118342", "institutionId": "102105", "balanceDate": 1665157710, "aggregationSuccessDate": 1665157711, "aggregationAttemptDate": 1665157711, "createdDate": 1665157660, "lastUpdatedDate": 1665157664, "currency": "USD", "institutionLoginId": 6009863353, "detail": {}, "displayPosition": 5, "accountNickname": "ROTH", "marketSegment": "personal" }, { "id": "6020488411", "number": "121212", "realAccountNumberLast4": "1212", "accountNumberDisplay": "1212", "name": "My 401k", "balance": 265000.0, "type": "investmentTaxDeferred", "aggregationStatusCode": 0, "status": "active", "customerId": "6012118342", "institutionId": "102105", "balanceDate": 1665157710, "aggregationSuccessDate": 1665157711, "aggregationAttemptDate": 1665157711, "createdDate": 1665157660, "lastUpdatedDate": 1665157664, "currency": "USD", "institutionLoginId": 6009863353, "detail": { "marginBalance": 0.0, "availableCashBalance": 2000.0, "currentBalance": 265000.0, "vestedBalance": 225000.0, "currentLoanBalance": 25000.0 }, "displayPosition": 4, "accountNickname": "My 401k", "marketSegment": "personal" }, { "id": "6020488412", "number": "101010", "realAccountNumberLast4": "1010", "accountNumberDisplay": "1010", "name": "Personal Investments", "balance": 100000.0, "type": "investment", "aggregationStatusCode": 0, "status": "active", "customerId": "6012118342", "institutionId": "102105", "balanceDate": 1665157710, "aggregationSuccessDate": 1665157711, "aggregationAttemptDate": 1665157711, "createdDate": 1665157660, "lastUpdatedDate": 1665157664, "currency": "USD", "institutionLoginId": 6009863353, "detail": { "marginBalance": 0.0, "availableCashBalance": 1000.0, "currentBalance": 100000.0, "vestedBalance": 100000.0, "currentLoanBalance": 0.0 }, "displayPosition": 3, "accountNickname": "Personal Investments", "marketSegment": "personal" }, { "id": "6020488414", "number": "22222203", "realAccountNumberLast4": "2203", "accountNumberDisplay": "2203", "name": "Savings", "balance": 22327.3, "type": "savings", "aggregationStatusCode": 0, "status": "active", "customerId": "6012118342", "institutionId": "102105", "balanceDate": 1665157710, "aggregationSuccessDate": 1665157711, "aggregationAttemptDate": 1665157711, "createdDate": 1665157661, "lastUpdatedDate": 1665157664, "currency": "USD", "lastTransactionDate": 1665157710, "institutionLoginId": 6009863353, "detail": { "availableBalanceAmount": 0.0 }, "displayPosition": 2, "accountNickname": "Savings", "oldestTransactionDate": 1649851200, "marketSegment": "personal" }, { "id": "6020488416", "number": "111111", "realAccountNumberLast4": "1111", "accountNumberDisplay": "1111", "name": "Checking", "balance": 9357.24, "type": "checking", "aggregationStatusCode": 0, "status": "active", "customerId": "6012118342", "institutionId": "102105", "balanceDate": 1665157710, "aggregationSuccessDate": 1665157711, "aggregationAttemptDate": 1665157711, "createdDate": 1665157661, "lastUpdatedDate": 1665157664, "currency": "USD", "lastTransactionDate": 1665157710, "institutionLoginId": 6009863353, "detail": { "availableBalanceAmount": 0.0 }, "displayPosition": 1, "accountNickname": "Checking", "oldestTransactionDate": 1646136000, "marketSegment": "personal" } ] } ``` ## Fetch Some Data {#fetch-some-data} Now you can retrieve some recent customer transactions using the `getAllCustomerTransactions` endpoint which returns all the transactions for a particular customer between the dates you specify. You will need to pass your required start and end dates in the query as Unix epoch timestamps (also known as Unix time or epoch time). These are integer values representing the number of seconds since midnight on 1 January 1970. If you are not familiar with this format, see [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/index.md#handling-epoch-dates-and-times). For testing purposes, you can use a site like [Epoch Converter](http://www.epochconverter.com/) to convert between standard dates and Unix timestamps. API Reference: `GET /aggregation/v3/customers/{customerId}/transactions` * Command: ```sh curl --location --request GET 'https://api.finicity.com/aggregation/v3/customers/{{customerId}}/transactions?fromDate={{fromDate}}&toDate={{toDate}}&includePending=true&sort=desc&limit=25' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' ``` * Expected response: ```json { "found": 64, "displaying": 25, "moreAvailable": "true", "fromDate": "1349701444", "toDate": "1665234244", "sort": "desc", "transactions": [ { "id": 13212489147, "amount": 1208.15, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "REMOTE ONLINE DEPOSIT #", "memo": "1", "postedDate": 1665144000, "transactionDate": 1665144000, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Remote Online", "category": "Income", "bestRepresentation": "REMOTE ONLINE DEPOSIT", "country": "USA" } }, { "id": 13212489182, "amount": 1216.2, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Mad Science Research PR PAYMENT", "memo": "PPD ID: 1234567899", "postedDate": 1664884800, "transactionDate": 1664884800, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Mad Science Research", "category": "Paycheck", "bestRepresentation": "MAD SCIENCE RESEARCH PR PAYMENT PPD ID", "country": "USA" } }, { "id": 13212489179, "amount": 1500.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "JABERWOCKY CREDIT N.A. JABERWOCKY", "memo": "PPD ID: 1234567893", "postedDate": 1664712000, "transactionDate": 1664712000, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "jaberwocky credit jaberwocky ppd id", "category": "Income", "bestRepresentation": "JABERWOCKY CREDIT JABERWOCKY PPD ID", "country": "USA" } }, { "id": 13212489172, "amount": 1834.49, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "ROCKET SURGERY PAYROLL", "memo": "PPD ID: 1234567892", "postedDate": 1664625600, "transactionDate": 1664625600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Rocket Surgery", "category": "Paycheck", "bestRepresentation": "ROCKET SURGERY PAYROLL PPD ID", "country": "USA" } }, { "id": 13212489185, "amount": 1197.33, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Mad Science Research PR PAYMENT", "memo": "PPD ID: 1234567899", "postedDate": 1663588800, "transactionDate": 1663588800, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Mad Science Research", "category": "Paycheck", "bestRepresentation": "MAD SCIENCE RESEARCH PR PAYMENT PPD ID", "country": "USA" } }, { "id": 13212489150, "amount": 0.03, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "INTEREST PAYMENT", "postedDate": 1663502400, "transactionDate": 1663502400, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "interest payment", "category": "Interest Income", "bestRepresentation": "INTEREST PAYMENT", "country": "USA" } }, { "id": 13212489145, "amount": 50.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Credit Return: Online Payment 49", "memo": "12345679 To ABC Roofers", "postedDate": 1663329600, "transactionDate": 1663329600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Online", "category": "Credit Card Payment", "bestRepresentation": "CREDIT RETURN ONLINE PAYMENT TO ABC ROOFERS", "country": "USA" } }, { "id": 13212489158, "amount": 1834.49, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "ROCKET SURGERY PAYROLL", "memo": "PPD ID: 1234567892", "postedDate": 1663243200, "transactionDate": 1663243200, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Rocket Surgery", "category": "Paycheck", "bestRepresentation": "ROCKET SURGERY PAYROLL PPD ID", "country": "USA" } }, { "id": 13212489131, "amount": 1888.58, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Mad Science Research PR PAYMENT", "memo": "PPD ID: 1234567899", "postedDate": 1662379200, "transactionDate": 1662379200, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Mad Science Research", "category": "Paycheck", "bestRepresentation": "MAD SCIENCE RESEARCH PR PAYMENT PPD ID", "country": "USA" } }, { "id": 13212490135, "amount": 620.0, "accountId": 6020605021, "customerId": 6012188750, "status": "active", "description": "Withdrawal", "postedDate": 1662120000, "transactionDate": 1662120000, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "withdrawal", "category": "Uncategorized", "bestRepresentation": "WITHDRAWAL", "country": "USA" } }, { "id": 13212489169, "amount": 4942.25, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "ROCKET SURGERY PAYROLL", "memo": "PPD ID: 1234567892", "postedDate": 1662033600, "transactionDate": 1662033600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Rocket Surgery", "category": "Paycheck", "bestRepresentation": "ROCKET SURGERY PAYROLL PPD ID", "country": "USA" } }, { "id": 13212489137, "amount": 141.2, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Cash Redemption", "postedDate": 1661774400, "transactionDate": 1661774400, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Redemption", "category": "Credit Card Payment", "bestRepresentation": "CASH REDEMPTION", "country": "USA" } }, { "id": 13212489146, "amount": 5000.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "HEALTH CARE ABC CLAIM", "memo": "PPD ID: 1234567891", "postedDate": 1661688000, "transactionDate": 1661688000, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Health Care Abc", "category": "Health & Fitness", "bestRepresentation": "HEALTH CARE ABC CLAIM PPD ID", "country": "USA" } }, { "id": 13212489149, "amount": 400.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Credit Return: Online Payment 50", "memo": "12345670 To Mary Greatfriend", "postedDate": 1661428800, "transactionDate": 1661428800, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Online", "category": "Credit Card Payment", "bestRepresentation": "CREDIT RETURN ONLINE PAYMENT TO MARY GREATFRIEND", "country": "USA" } }, { "id": 13212489144, "amount": 1198.26, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Mad Science Research PR PAYMENT", "memo": "PPD ID: 1234567899", "postedDate": 1661169600, "transactionDate": 1661169600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Mad Science Research", "category": "Paycheck", "bestRepresentation": "MAD SCIENCE RESEARCH PR PAYMENT PPD ID", "country": "USA" } }, { "id": 13212489164, "amount": 0.04, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "INTEREST PAYMENT", "postedDate": 1661083200, "transactionDate": 1661083200, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "interest payment", "category": "Interest Income", "bestRepresentation": "INTEREST PAYMENT", "country": "USA" } }, { "id": 13212489177, "amount": 1901.33, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "ROCKET SURGERY PAYROLL", "memo": "PPD ID: 1234567892", "postedDate": 1660564800, "transactionDate": 1660564800, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Rocket Surgery", "category": "Paycheck", "bestRepresentation": "ROCKET SURGERY PAYROLL PPD ID", "country": "USA" } }, { "id": 13212489165, "amount": 300.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "REMOTE ONLINE DEPOSIT #", "memo": "1", "postedDate": 1660564800, "transactionDate": 1660564800, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Remote Online", "category": "Income", "bestRepresentation": "REMOTE ONLINE DEPOSIT", "country": "USA" } }, { "id": 13212489138, "amount": 30.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "REMOTE ONLINE DEPOSIT #", "memo": "1", "postedDate": 1660478400, "transactionDate": 1660478400, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Remote Online", "category": "Income", "bestRepresentation": "REMOTE ONLINE DEPOSIT", "country": "USA" } }, { "id": 13212489171, "amount": 13.74, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "BIGBOX DEBIT CRD ACH TRAN 0003", "memo": "12345678901 POS ID: 1234567896", "postedDate": 1660219200, "transactionDate": 1660219200, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Crd Ach", "category": "Shopping", "bestRepresentation": "BIGBOX DEBIT CRD ACH TRAN POS ID", "country": "USA" } }, { "id": 13212489161, "amount": 1140.11, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "Mad Science Research PR PAYMENT", "memo": "PPD ID: 1234567899", "postedDate": 1659960000, "transactionDate": 1659960000, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Mad Science Research", "category": "Paycheck", "bestRepresentation": "MAD SCIENCE RESEARCH PR PAYMENT PPD ID", "country": "USA" } }, { "id": 13212489148, "amount": 1744.6, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "ROCKET SURGERY PAYROLL", "memo": "PPD ID: 1234567892", "postedDate": 1659355200, "transactionDate": 1659355200, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Rocket Surgery", "category": "Paycheck", "bestRepresentation": "ROCKET SURGERY PAYROLL PPD ID", "country": "USA" } }, { "id": 13212489187, "amount": 300.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "REMOTE ONLINE DEPOSIT #", "memo": "1", "postedDate": 1659009600, "transactionDate": 1659009600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Remote Online", "category": "Income", "bestRepresentation": "REMOTE ONLINE DEPOSIT", "country": "USA" } }, { "id": 13212489160, "amount": 150.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "REMOTE ONLINE DEPOSIT #", "memo": "1", "postedDate": 1659009600, "transactionDate": 1659009600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Remote Online", "category": "Income", "bestRepresentation": "REMOTE ONLINE DEPOSIT", "country": "USA" } }, { "id": 13212489156, "amount": 140.0, "accountId": 6020605022, "customerId": 6012188750, "status": "active", "description": "REMOTE ONLINE DEPOSIT #", "memo": "1", "postedDate": 1659009600, "transactionDate": 1659009600, "createdDate": 1665248277, "categorization": { "normalizedPayeeName": "Remote Online", "category": "Income", "bestRepresentation": "REMOTE ONLINE DEPOSIT", "country": "USA" } } ] } ``` ## Continue Your Integration {#continue-your-integration} You now have everything you need to explore the Open Finance APIs further. Here are some tools to help you with your integration: * **[Using the Postman Collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md)** - Explore and test the Open Finance APIs using our Postman collection * **[Generating an API Client Library](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/generating-an-api-client-library/index.md)** - Generate type-safe client libraries from the API specification for Java, C#, JavaScript, Python, and more ## Next Steps {#next-steps} * For the full list of testing profiles available, refer to [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). * Explore our [Reference App](https://developer.mastercard.com/open-finance-us/documentation/reference-app/index.md) to see a simple React application which uses many of the APIs mentioned above, including Data Connect. * To learn more about Data Connect, how to configure Data Connect for your application, and how to receive Data Connect session events, read [Data Connect Application](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). * Consult the [Use Cases](https://developer.mastercard.com/open-finance-us/documentation/usecases/index.md) section for advice about the different solutions offered by Open Finance US and the APIs typically involved in different scenarios such as Account Opening or Lending. The [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) expands on this to show typical UX flows and recommendations about how to present Data Connect within your application. Tip: If you have any questions or need assistance, please [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). --- # Reference Application source: https://developer.mastercard.com/open-finance-us/documentation/reference-app/index.md The Reference Application is a sample app built in React which allows you to explore examples of how Mastercard Data Connect and other Open Finance US APIs can be implemented into your applications. The Reference Application allows you to create test customers and also seek permission to access test account data from one or more of their test accounts. ## Get the Source Code {#get-the-source-code} The Reference Application source code is available on GitHub: ## Compatibility {#compatibility} You will need the following: * Node (v14+) * ReactJS (v18.2.21) The application is built using the ReactJS framework. ReactJS requires Node version 14+. We recommend that you use one of NodeJS's LTS releases or one of the [more general recent releases](https://github.com/nodejs/Release). A Node version manager such as [nvm](https://github.com/creationix/nvm) (Mac and Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows) can help with this. ## Installation {#installation} Before using the application, you will need to set up a project on your local machine. The following commands will help you to get the latest code and install the required dependencies on your machine. ```shell git clone https://github.com/Mastercard/open-banking-reference-application.git cd open-banking-reference-application npm i ``` See the [GitHub readme](https://github.com/Mastercard/open-banking-reference-application/blob/main/README.md) for further information. --- # Experience Design Guide source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md The Experience Design Guide was created to provide you, our partner, with our best user experience recommendations and cutting edge resources for implementation. You will find white label Figma flows to improve the speed, quality, and cost of implementation and scale. This guide is intended for you if you are a product owner, designer, or developer who wants to add Mastercard Open Finance US to your application. It shows examples to illustrate how to connect your customers' financial data using Mastercard Open Finance US. Open Finance solutions in the United States are provided by Finicity, a Mastercard company. ![Introduction](https://static.developer.mastercard.com/content/open-finance-us/uploads/introduction.png) ## What Is Mastercard Data Connect? {#what-is-mastercard-data-connect} The Data Connect application enables your customers to connect to their Financial Institutions (FIs) and permission the accounts they want to share. Open Finance simplifies the process of accessing financial data and increases security.
![What is Mastercard Data Connect?](https://static.developer.mastercard.com/content/open-finance-us/uploads/what_is_connect.png) ## How Is Data Connect Used? {#how-is-data-connect-used} Your application displays Data Connect to your customer, who uses it to find their FI, log in, and permission the accounts they want to share. After the customer reviews and submits their financial data, the Data Connect session ends and the customer returns to your application flow. This guide provides best practices for onboarding and successful account connection experiences for the following use cases: ![Payments](https://static.developer.mastercard.com/content/open-finance-us/uploads/pymt.svg) ### Open Finance US for Payments {#open-finance-us-for-payments} Verify the account owner, bank account number, routing details, and account balance before the customer initiates movement of funds. [Learn more](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/index.md) ![Lending](https://static.developer.mastercard.com/content/open-finance-us/uploads/lending.svg) ### Open Finance US for Lending {#open-finance-us-for-lending} Increase efficiency, reduce cost, and improve the lending experience using our Mortgage Verification Service (MVS) for mortgage lenders. [Learn more](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/index.md) ![Account](https://static.developer.mastercard.com/content/open-finance-us/uploads/accnt.svg) ### Open Finance US for Account Opening and Funding {#open-finance-us-for-account-opening-and-funding} Verify ownership, check account numbers, routing numbers, and account balances for a better customer onboarding experience. [Learn more](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/account-opening-and-funding/index.md) Note: Developers and product owners should also read our [Use Cases](https://developer.mastercard.com/open-finance-us/documentation/usecases/index.md) section, which covers the APIs that are used in these scenarios in more detail. Once the customer has used the Data Connect experience to give permission for Open Finance to access their accounts, you as a partner are able to use our APIs to obtain the details needed in each use case (for example, the account ACH details or account balance, the customer's name and address as held by the FI, reports which can be used to verify the customer's income, and so on). ## Data Connect Enhancements and Features {#data-connect-enhancements-and-features} Use our best practices and tips to create a best-in-class Open Finance US experience using Data Connect. ![Payments](https://static.developer.mastercard.com/content/open-finance-us/uploads/code2.svg) ### For Developers {#for-developers} Find information about Data Connect's back-end technology and code to understand how to integrate Open Finance US into your environment. [View documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) ![Lending](https://static.developer.mastercard.com/content/open-finance-us/uploads/figma2.svg) ### For Designers {#for-designers} Find the product experiences and best practices for Data Connect Full and Data Connect Lite's product enhancements and features (App to App and Financial Institution Search). [View designs](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/index.md) Tip: If you have questions or need assistance with your customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). Next: [Open Finance US for Payments](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/index.md) --- # Mastercard Data Connect source: https://developer.mastercard.com/open-finance-us/documentation/connect/index.md The Mastercard Data Connect application (Data Connect app) allows your customers to connect to their Financial Institutions (FIs) and permission the accounts they want to share. This gives Mastercard the authorization to access the customer's financial data and share it with a third party. Customers can manage their shared accounts through the Data Connect app, or through their Financial Institution's website if available. ## How It Works {#how-it-works} Your app displays the Data Connect app to your customers. They go through a Data Connect experience to find their Financial Institution, log in, and permission the accounts they want to share. After the customer reviews and submits their financial data, the Data Connect session ends and the customer returns to your application flow. ![How Mastercard Data Connect works within the Open Finance system](https://static.developer.mastercard.com/content/open-finance-us/uploads/mcdev-open-finance-dataconnect-flow.svg) 1. Connect your environment to our Open Finance API platform. 2. Generate a Data Connect URL and add it to your application. 3. The customer follows the URL and goes through the Data Connect application flow. 4. The customer connects to their Financial Institutions and permissions their accounts. Tip: If the Financial Institution has a direct (OAuth) connection, then the login screen is hosted by the Financial Institution itself. Where the Financial Institution hosts the login screen, it might also show an account selection screen, or in some cases it will automatically add all the eligible accounts, rather than present a selection screen. ## Data Connect Flows {#data-connect-flows} Data Connect provides two main experience types: * [Data Connect Full](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-full) - provides the full UX flow with a wide range of customisation features; includes the ability to cater for joint borrowers within a single Data Connect session. * [Data Connect Lite](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-lite) - provides a minimal UX with a limited set of features; your own app implements the UX for the customer to select Financial Institutions and accounts.
You can also use: * [Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-fix) - provides an experience to fix broken FI connections * [Data Connect Email](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#send-data-connect-email) - sends a Data Connect URL to a customer by email so they can use it later ### Data Connect Full {#data-connect-full} The following UX screens show the default Data Connect Full experience flow. Note: The Data Connect experience can be configured to provide a different UX flow for different product types. For example, the UX can prompt the user to upload a paystub or connect a payroll account if you are implementing a Lend report. You can also change branding and other options. See [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) for details. ![An example flow of the Data Connect application](https://static.developer.mastercard.com/content/open-finance-us/uploads/image007_ConnectFull_1.png) 1. Accept the Terms and Conditions and the Privacy Policy agreement. 2. Search Financial Institutions. 3. Connect to a Financial Institution. 4. Log in to the Financial Institution. 5. Select the accounts to share financial data. 6. Review your connected accounts and the account details. 7. Review the accounts you selected to share with Mastercard. 8. After the data is successfully submitted the Data Connect session ends. ### Data Connect Lite {#data-connect-lite} If you want to create your own Financial Institution search and account selection screens, you can use Data Connect Lite instead of Data Connect Full. Data Connect Lite enables you to own more of the experience for a seamless UX. With Data Connect Lite the screens shown will be as follows: ![An example flow with Data Connect Lite](https://static.developer.mastercard.com/content/open-finance-us/uploads/connect_lite_img_3.png) 1. You provide your own screen where the customer can search for and select a Financial Institution. 2. Once the customer selects a Financial Institution, you call Data Connect Lite (with the ID of the selected institution) and Data Connect launches with the Terms and Conditions and Privacy Policy agreement screen. 3. The customer can then log in to the Financial Institution. 4. Control then returns to your application where you can show your own screens for account selection and confirmation.
For guidance on best practices for designing a user experience, see the [Data Connect section](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/index.md) of our [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md). Warning: Once a customer adds an account through Data Connect, the account remains associated with their customer record. If the customer later closes that account at their financial institution and subsequently re-enters Data Connect to add a new account at the same institution, the previously closed account is still visible in their account list. However, Mastercard Open Finance is not able to aggregate data from closed accounts. While the account record persists, any attempts to refresh or retrieve data from a closed account fail because the account is no longer accessible at the financial institution. Note: We also provide a special version of the Data Connect experience, Connect Transfer, which enables customers to also connect to payroll providers or merchants/service providers. This is useful for the following: * Enable customers to easily switch their payroll deposit to a new account (Deposit Switch). * Enable customers to switch recurring automatic payments to a new account (Bill Pay Switch).
For example, you can use Deposit Switch to enable a new banking customer to easily authorize the payment of their salary into their new bank account. With Bill Pay Switch, the customer can also move their recurring payments (for example, their Netflix subscription, Amazon or Apple account, or other regular bill payments). These are separate products which are not supported by the regular Data Connect application and SDKs. See the [Deposit Switch and Bill Pay Switch documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) for details. ## Next Steps {#next-steps} * Integrate using one of our Data Connect SDKs (for mobile and web), or using webviews. See [Integrating with Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md). * Generate a Data Connect URL for your application. See [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). * If you are interested in using Connect Transfer for Deposit Switch or Bill Pay Switch, see [Deposit Switch and Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md). --- # Consent Management source: https://developer.mastercard.com/open-finance-us/documentation/consent-management/index.md ## Understanding User Consent {#understanding-user-consent} User Consent refers to explicit permission granted by a customer (end user), typically through [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), for Mastercard Open Finance to access the customer's financial account data and share it with a third party. Customers retain the ability to review, update, or revoke this access at any time. Data Connect offers a user experience that enables customers to connect to their financial institutions and permission access to the data they want to share. For further details, refer to the [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) documentation. If the customer decides not to share their consented financial data any longer, they can either revoke the entire consent or remove a specific financial institution. Upon revocation of consent, Open Finance will discontinue collecting the customer's data associated with that consent. Warning: After consent is revoked, you will no longer be able to retrieve any data or reports based on that data. ## Consent Records {#consent-records} A consent record documents the details of a consent. Each consent record includes information about the following: * **Accounts shared:** institution details with specific accounts the customer selected * **Data types:** the type of data to be accessed (transactions, balances, identity, and so on) * **Consent access timestamp:** the duration for which the data recipient will have access to the data * **Connection status:** whether the financial institution connection is active or inactive Note: Consent records are available from 28 June 2023. ## Consent Management Endpoints {#consent-management-endpoints} You can use these endpoints to retrieve consent records and revoke consent on behalf of a customer. ### Retrieving Consent Records {#retrieving-consent-records} API Reference: `GET /data-sharing-consents` API Reference: `GET /data-sharing-consents/{consent_receipt_id}` ### Revoking Consent {#revoking-consent} API Reference: `DELETE /data-sharing-consents/{consent_receipt_id}` API Reference: `DELETE /data-sharing-consents/{consent_receipt_id}/institutionLogins/{institution_login_id}` These endpoints may not be suitable for all partners. Contact your sales representative for more information. --- # Partner Linked Access source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/index.md Consented third party access (Partner Linked) allows you to collect consent from your customer to enable a third party (such as a payment processor) to retrieve customer data from Mastercard Open Finance. The third party will only have access to the specific data which the customer grants consent for. To provide this access, you will need to show the Data Connect user experience to your customer so they can provide consents for accessing their banking data. You can then obtain a third party access key (known as a consent receipt) which you will share with the third party. This consent receipt acts as a key allowing the third party to access specified Mastercard Open Finance APIs for a limited period in order to carry out the consented process (for example, to obtain the customer's ACH routing data in order to process a payment on their behalf). The following actors are involved: | Actor | Description | |--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Client / Partner ("Recipient") | Merchant, Fintech, or other application which presents the Open Finance connect experience to their customers. The client application obtains permission from the end user to allow access to their banking data for specific purposes and generates an access token which can be shared with the processor to allow third party access. | | Processor ("Requestor") | A third party which provides services to enable additional functionality for the client application, for example for payment processing. The processor requires an access token from the client which allows the processor to access specific types of Open Finance data which the end user has given consent for. | | Customer | Customers are end users granting Mastercard Open Finance access to their financial accounts. The customer consents to their banking data being shared for the intended purpose (for example, to make a payment). | The client must specify which supported products the processor can access, from the following list of products which are supported for partner linked access: | Product | Description | |-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) | The names and addresses of an account owner from a financial institution. | | [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) | The latest available and cleared account balances for an account. | | [Get Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) | The real account number and routing number details for an ACH payment. | | [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) | The real account number and routing number details for an ACH payment. | Note: Not all institutions provide the same support for our pay services. To help you find supported products by institution, see [Financial Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md). The following pages explain the overall process and also the steps required of the client / partner and the third party / processor in order to integrate the relevant APIs into their systems. * [Client / partner integration steps](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/index.md) * [Processor integration steps](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/processor/index.md) --- # Partner Direct Model source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/index.md As a Direct Partner, you can use Mastercard's Open Finance APIs and embed these APIs into your solutions and offer them to your affiliates (customers such as merchants/fintechs who use your services). This ease of integration allows you to quickly scale to more customers with differentiated offerings. Leverage [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/) or the [Mastercard Developers Dashboard](https://developer.mastercard.com/dashboard) to seamlessly onboard your affiliates and scale your solutions. ### Benefits to Direct Partner: {#benefits-to-direct-partner} * Single integration with all Mastercard Open Finance and payment services * Faster path to scale your solutions * Build profitable, unique services * Deliver consistent brand standards * Design best practices with customizable user experiences * Dedicated delivery support during integration and beyond ### Benefits to Affiliates of Direct Partner: {#benefits-to-affiliates-of-direct-partner} * Offer innovative solutions to your end customers with embedded experiences designed to fit your needs * Support customer trust and security through the Mastercard brand * Lower the technical barrier to market entry with the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/) * Faster go-to-market with differentiated offerings ## Actors in the Partner Direct Model {#actors-in-the-partner-direct-model} | Actor | Description | |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Direct Partner | A financial institution, payment institution, fintech or retail merchant who is in a direct commercial relationship with Mastercard and acts as an enabler of solutions to its affiliates who indirectly consume Mastercard's Open Finance services. | | Affiliate of Direct Partner | A merchant, fintech, or other application provider that consumes the services of Mastercard's Direct Partners and presents the Open Finance Data Connect experience to their end-users (customers) to permission use of their data. | | Customer | Consumers or small businesses that grant Mastercard Open Finance access to their financial accounts and consent to their account data being used by the Affiliate for a specific service (for example, to make a payment, financial management or loan origination). | ![partner direct model](https://static.developer.mastercard.com/content/open-finance-us/uploads/partner-direct-model_1.png) ## Next Steps {#next-steps} Learn how to use the Mastercard Developers API or the [Mastercard Developers Dashboard](https://developer.mastercard.com/dashboard) to [onboard](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md) and [manage your affiliates](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/managing-customers/index.md). --- # Institution Status source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/institution-status/index.md ## Institution Status {#institution-status} The Mastercard Open Finance platform supports connections to thousands of financial institutions. This tool allows you to monitor the current health status of each institution available. You can view all the institutions page by page or you can search for a specific institution using the search. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/activityCardSeeMore.png) By default, there are 25 institutions listed per page. You can select to view 5, 10, or 50 institutions per page to help you locate institutions more quickly. To narrow your search down even more, select a specific timeframe. By default, the list displays the institution status for the last 24 hours. Other options include viewing the last 7 or last 30 days. ### Health Statuses {#health-statuses} There are many different reasons why a connection to a financial institution fails. The following are a few examples of different connection statuses. To help you learn more about the reason for connection failures, the investigating and offline status details display error codes for you to reference. See [Error Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md). The institutions can have the following statuses: * Green - Online * Yellow - Investigating * Red - Offline #### Online {#online} City National Bank's status is online and working as expected. All customers can connect to this institution. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/onlineStatusWorkingOk.png) #### Investigating {#investigating} ##### Investigating Unspecified Error {#investigating-unspecified-error} Citibank's status is investigating an unspecified error code. The engineers are looking into the matter. Customers can try to connect to the institution in 2-3 days. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/investigatingStatus.png) ##### Investigating Specific Error {#investigating-specific-error} Mountain Valley Bank's status changed from online to investigating at 01/23/24 8:00 PM. The details show that the reason the connection failed is due to Error Code 998. The financial institution engineers are looking into the problem. Customers can try to reconnect in 2-3 business days. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/investigatingError998.png) #### Offline {#offline} Mountain Valley Bank's status is offline. However, the details show the reason is due to a different error code condition. The financial institution engineers are looking into the problem. You can continue to monitor this institution and when it comes back online, you can then notify your customers that the connection service has been restored. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/offlineError995.png) ##### Interruptions {#interruptions} Anyone monitoring the institution statuses can see that there has been a lot of connectivity interruptions at the Mountain Valley Bank(CO). To view each of the different statuses by hour throughout the day, click one of the lines. Each status provides the details of the status and what error code if any is the cause of the problem. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/lotsofInterruptionsService.png) **See also**: * [Invoice History](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/invoice-history/index.md) --- # Accessing the Client Hub source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md The Client Hub is available from the [Mastercard Developers project dashboard](https://developer.mastercard.com/dashboard). Warning: You cannot use the [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) tool if you log in via Mastercard Developers. See [Accessing the Client Hub for Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#accessing-the-client-hub-for-order-reports) for alternative options. After you [create an Open Finance project](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#create-a-sandbox-project), you can find the **Access Client Hub** option in the pulldown menu at the right of the project credentials view. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/newdashaccessclienthub.png) Each set of credentials, whether in the Sandbox or Production environment, provides access to a unique instance of the Client Hub. This means when you use a specific set of credentials to execute an API call -- such as generating a [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) -- the resulting record of this report will only appear in the Invoice History of the Client Hub instance accessed via the **Access Client Hub** button of these credentials. For example, if you generate a [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) report using a given set of Sandbox credentials, you'll find the report's record only when you enter the Client Hub using the **Access Client Hub** button associated with those credentials. Similarly, generating a [Verification Of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) report using a set of Production credentials will make its record visible only within the Invoice History of the Client Hub instance accessed from the **Access Client Hub** button associated with those Production credentials. Tip: If at any time you want to go back to the project dashboard on Mastercard Developers, click the **Back to Projects** link located at top-right of the Client Hub dashboard. --- # Customize Data Connect source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-customize-connect/index.md ## Customize Data Connect {#customize-data-connect} Customize Data Connect allows you to tailor the appearance and behavior of the Data Connect application's interface to better align with your application's branding and user experience requirements. To learn more, see [Customizing Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md). **See also**: * [Accessing the Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md) * [Client Hub Use Cases](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md) --- # Personal Finance Management source: https://developer.mastercard.com/open-finance-us/documentation/usecases/personal-finance-management/index.md Personal Finance Management APIs empower you to connect with your customers to deliver clean, categorized and aggregated account data, helping them gain better financial control. Leverage our APIs to retrieve up to 24 months of account and transaction data and provide your customers a consolidated view of their finances in a single app. Provide not just data but analytics and insights to help your customers manage their wealth better. ### Customers Using This Solution {#customers-using-this-solution} Quicken's Simplifi product uses categorized, consumer-permissioned data to personalize financial recommendations. It gives users a big picture view of their finances and lets them choose how they track their money, set spending plans, pay bills, and channel money into rainy-day funds.   ## How It Works {#how-it-works} After a customer consents access to their accounts, all the account and transaction data is retrieved using our APIs. The results can then be used in your financial apps to help your customers improve their finances through monitoring, budgeting, analytics and more. Call the following APIs to provide your customers consolidated data from all their accounts in one place: * Regardless of the API you want to call, you will first need to generate a URL to launch the [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) application that allows your customers to link their accounts and provide you the permission to access their financial data through Mastercard Open Finance. The Data Connect application is the only way you can allow your customers to link their accounts and is mandatory for integrating with any Mastercard Open Finance APIs. * [Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) allow your app to receive notifications about Data Connect events and to listen for when reports have been generated. * You can call the appropriate [Refresh Customer Accounts endpoint](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) to refresh the latest account and transaction data for a customer. This is an optional step as this call is in addition to the periodic refresh Mastercard performs to update data from accounts added by customers. * [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-full-details-afd-and-account-limited-aggregation-ala) to get all accounts owned by the given customer. * [Get Customer Account Statement](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) to retrieve customer's bank statements. * [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#transaction-aggregation-tau-and-account-transaction-details-atd) to get all transactions available for this customer within the given date range, across all accounts.
This solution uses the following services: #### Transaction Data {#transaction-data} Get all transactions available for a customer, across all accounts.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) #### Account Aggregation {#account-aggregation} Get real-time account data, refreshed daily.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) #### Account Statements {#account-statements} Retrieves the customers Financial Institution (FI) statements.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) Diagram usecase_pfm ## Next Steps {#next-steps} ![Quick Start Guide](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_quickstart.png) ### Quick Start Guide {#quick-start-guide} Get started with using Mastercard Open Finance APIs in less than 30 minutes.

[Get Started →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) ![API Reference](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_apireference.png) ### API Reference {#api-reference} Find detailed explanation of all resources available through Mastercard Open Finance API.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) ![Postman](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_postman.png) ### Postman {#postman} Run the Postman Collection to start using Open Finance API without the need to write any code.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#4-run-the-postman-collection) --- # Invoice History source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/invoice-history/index.md ## Invoice History {#invoice-history} The Invoice History page displays a record of all the reports generated for your customers. For example, every time you generate a [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md), [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) or a [Verification of Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) for a customer using the Open Finance APIs, a record is automatically generated in the Invoice History page of Client Hub. These records provide all the details to help you with billing reconciliation. Note: Only API calls made to [Lend](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) products (for report generation) will be added to the invoice history in the Client Hub interface. You can view report records by month for up to 24 months. You can sort the records per column by ascending or descending order. Reports can have up to 5 custom fields. You can also move the columns around, arranging them in the order you want. The CSV file downloads the data columns in the order they are displayed on the invoice history. After you download this file, you can then use this downloaded file as key data source and append additional internal data to support your billing reconciliation process. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/invoiceHistoryReportRecord.png) Let's say a financial manager wants to view data for a customer named Crystal Hunter. You can see in the Invoice History page that a report was run for Crystal on three different occasions. If you click the **Customer** column, the report list appears in ascending (A to Z) or descending (Z to A) alphabetical order of the customer's name and groups all three instances of Crystal's reports. If you wanted to view Crystal's `customerId` and `consumerId` then you can open the menu and select which columns to show or hide on the invoice history table. Note: The options to show/hide and move columns within the table does not remain in the order you put them if you log out of the Client Hub or refresh the browser page. The table defaults back to the order of when you first logged into Client Hub. Tip: Make sure you select which columns to show/hide **before** you move columns in the table. If you move columns, and then decide to show another column, all columns in the table will default back to the order of the show/hide menu options. The Report ID column shows the type of report run and the report ID. The Report ID is a unique number associated with the `customerId` and the `consumerId` and is masked showing only the last four digits to help protect customer's personal and financial information. ### Populate Invoice History {#populate-invoice-history} To populate the Invoice History data: 1. Use the Postman Collection as specified in the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md). 2. When making calls to the endpoints via the Postman collection, ensure that you use the appropriate set of credentials - `partnerId`, `appkey` and `secret` that match the Client Hub instance you intend to access. 3. Invoice History creates a record when you generate any of the following reports using the API: * [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateVOAReport) * [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateVOIReport) * [Prequalification (CRA) Report](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GeneratePrequalificationCRAReport) * [Prequalification (Non-CRA) Report](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GeneratePrequalificationNonCRAReport) * [Generate Cash Flow Report - Business](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateCashFlowBusinessReport) * [Generate Cash Flow Report - Personal](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateCashFlowPersonalReport) * [Transactions Report](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateTransactionsReport) * [Statement Report](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateStatementReport) * [Verification of Income and Employment - Payroll](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#RefreshVOIEPayrollReport) * [Verification of Employment Reports - Payroll](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateVOEPayrollReport) * [Verification of Employment Reports - Transaction Report](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateVOETransactionsReport)
To view the list of reports generated, go to Invoice History of the Client Hub instance accessed from the **Access Client Hub** button associated with the credentials used for the report generation. **See also**: * [Customize Data Connect](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-customize-connect/index.md) * [Client Hub Use Cases](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md) --- # Formats and Best Practices source: https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/index.md This section describes the best way to format queries, including spaces and special characters, and how to work with dates and times. ## Handling Spaces and Special Characters in Queries {#handling-spaces-and-special-characters-in-queries} Request URLs must be URL-encoded. In practice this means that spaces in URL query values must be replaced with `+` and the `@` symbol must be replaced with `%40`. * Correct -- `?search=New+York+City&start=1&limit=10` * Incorrect -- `?search=New York City&start=1&limit=10` HTTP will truncate the second version of the query at the space after the word "New", so you will receive 25 records (the default limit) matching only the word "New". ## Handling Epoch Dates and Times {#handling-epoch-dates-and-times} Mastercard Open Finance supports either Unix epoch timestamps or [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date and time format. The format used varies between API endpoints. Refer to the documentation for each endpoint for details. A Unix epoch timestamp is a long value representing the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), with negative values for dates and times before 1970. * An epoch value is represented in seconds and can be positive or negative. * Timestamps in Java and Javascript are in milliseconds. * To convert from Java to epoch, divide the Java time by 1000. * To convert from epoch to Java, multiply the epoch time by 1000. [Epoch Converter](http://www.epochconverter.com/) has a page with a simple utility for converting quickly between readable dates and epoch timestamps. --- # Request Errors source: https://developer.mastercard.com/open-finance-us/documentation/errors/request-errors/index.md Request errors are generated for API requests across all endpoints under Mastercard Open Finance services, including Pay, Lend, and Manage products. | Error Codes | Error Theme | Description | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|---------------------------------------------------------------------------------------| | [265](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#265) [1007](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#1007) [10046](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#10046) [10047](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#10047) [12015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#12015) [13002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#13002) [13004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#13004) [14001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14001) [14003](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14003) [14006](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14006) [14008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14008) [20000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20000) [20001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20001) [20017](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20017) [20027](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20027) [24553](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#24553) [38008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#38008) [38057](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#38057) [90004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#90004) [110002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#111-02) | Item Not Found ​​ | These errors occur when the requested entity doesn't exist or cannot be found. | | [973](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#973) [978](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#978) [981](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#981) [2005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#2005) [10001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md) [10005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10005) [10010](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10010) [14023](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#14023) [20024](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#20024) [20028](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#20028) [38056](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#38056) [42002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42002) [42003](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42003) [42004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42004) | Invalid request ​​ | These errors occur when the API request is malformed or missing required information. | | [990](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) [991](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-995) [992](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) [993](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) [994](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) [995](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) [996](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#996-997-and-998) [997](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#996-997-and-998) [998](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#996-997-and-998) [1001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1001-1002-1005-and-1009) [1002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1001-1002-1005-and-1009) [1005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1001-1002-1005-and-1009) [1009](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1001-1002-1005-and-1009) [10030](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#10030) [12001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#12001) [12008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#12008) [12009](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#12009) [19000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#19000) [20014](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#20014) ​ [50050](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#50050) [110015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#111-15) | Unexpected System Issue | Errors due to temporary service disruptions or incorrect API usage. | | [977](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#977) [44000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#44000) | Maximum Limit Exceeded | The error occurs when calls made have reached the maximum limit allowed. | | [6004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#6004) [20015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20015) [20020](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20020) [20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20025) | Bad Request | Error due to an issue with the format of your request. | | [24302](https://developer.mastercard.com/open-finance-us/documentation/errors/request/api-auth-issue/index.md#24302) | API Request Authentication Issues | For your security, we've locked your account. Please reset your password to continue. | --- # Payment Enablement source: https://developer.mastercard.com/open-finance-us/documentation/usecases/payment-enablement/index.md Verify account owner, bank account number, routing details, and account balance before initiating movement of funds. Build streamlined experiences for credit-decisioning, loan funding and loan servicing by leveraging Account ACH Details, Account Balance Check, and Account Owner Verification API services. ![Avatar](https://static.developer.mastercard.com/content/open-finance-us/uploads/ob-usecase-paymentenable-header.png) ###### **Use Case** ### Payment Enablement Launch Demo ### Customers Using This Solution {#customers-using-this-solution} J.P. Morgan Payments and Mastercard partnered to create a payment enablement use case that will give billers and consumers more choice. At checkout, consumers can select "Pay by Bank," and pay bills directly from their bank account, increasing security and eliminating the need to type in account and routing numbers. This process can take the pain out of recurring payments like rent, utilities, tuition, insurance and healthcare, where ACH is the primary payment method. ## How It Works {#how-it-works} Use the following APIs to retrieve account information to set up online payments via ACH, check balance to ensure accounts have sufficient funds, verify account ownership for KYC compliance, and set up recurring payments: * Regardless of the API you want to call, you will first need to generate a URL to launch the [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) application that allows your customers to link their accounts and provide you the permission to access their financial data through Mastercard Open Finance. The Data Connect application is the only way you can allow your customers to link their accounts and is mandatory for integrating with any Mastercard Open Finance APIs. * [Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) allow your app to receive notifications about Data Connect events and to listen for when reports have been generated. * [Get Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) to retrieve the account number and routing number details for an ACH payment. You can automate the process of ACH Onboarding (retrieving and verifying a customer's bank account and routing numbers), reducing the need for the consumer to manually enter account/routing number. * [Get Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) to retrieve the names and addresses of the account owner from a financial institution. * [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md#get-available-balance) to retrieve the available and cleared account balances for a single account in real-time from a financial institution.
This solution uses the following services: #### Account ACH Details {#account-ach-details} Get ACH (Automated Clearing House) details for account opening or payment initiation. [Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) #### Account Balance {#account-balance} Provide available account balance information for your customers.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) #### Account Owner Verification {#account-owner-verification} Get account owner information from a financial institution.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) Diagram usecase_paymentenablement Learn more about the consumer experience for this use case: [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/index.md) Understand the ideal consumer experience for Payment enablement. ## Next Steps {#next-steps} ![Quick Start Guide](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_quickstart.png) ### Quick Start Guide {#quick-start-guide} Get started with using Mastercard Open Finance APIs in less than 30 minutes.

[Get Started →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) ![API Reference](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_apireference.png) ### API Reference {#api-reference} Find detailed explanation of all resources available through Mastercard Open Finance API.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) ![Postman](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_postman.png) ### Postman {#postman} Run the Postman Collection to start using Open Finance API without the need to write any code.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) --- # Mastercard Data Connect Webhooks source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md Webhook events are sent during a Mastercard Data Connect session as the customer interacts with the application. You can track progress through a session, get information about customer usage, and receive notifications when certain processes are complete. You will need to define a public RESTful web service that is accessible from the Mastercard platform. Tip: For testing purposes, you can use tools like webhook.site or beeceptor.com that receive webhooks and post the content for you to review (note that this is not an official endorsement of any of these services). In production, you **must** use your own secure webhook service. When you call an API to [generate a Data Connect url](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md), pass the URL of your listener in the `webhook` parameter of your request. Event messages will be sent from Mastercard Data Connect to your listener. For details of the events for Data Connect, see [Data Connect Events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md). For details of the events after generating a [Lend 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) Warning: The webhook system described on this page does not support [Mastercard Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/index.md). Components webhooks will be available through the upcoming [OBWMS](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md). Currently, you can get Components event notifications through the [Data Connect Components Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md). ### Event Body {#event-body} All events include a wrapper that contains metadata. The event data is within the `payload` key. If you specified custom events via the `webhookData` parameter when [generating a Data Connect url](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md), you will receive the [custom event data](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-custom/index.md) back in the `webhookData` key. The following example shows the format of the event. * JSON ```JSON { "customerId":"12345678", "consumerId":"ed81281fcec7ec557aa7d292a3188b75", "eventType":"started", "eventId":"1495468585434-0e73d1719173766fe4dfe1a8", "payload":{ "event data will be here" }, "webhookData": { "custom event data will be here" } } ``` ### Prevent Spoofing {#prevent-spoofing} If you're using webhooks for sensitive or critical information, we recommend that you verify the signature of the webhook. ### Tips for Best Practice: {#tips-for-best-practice} 1. Create a SHA-256 HMAC of the request body using your Partner Secret as the key. 2. Compare it to the signature included on the X-Finicity-Signature header. If the two are equal then the request is valid, otherwise, it is spoofed. 3. Store the `eventId` and ignore webhooks with an ID that have already been processed to prevent replay attacks. The X-Finicity-Signature header gets added to every event sent. Here is an example of signature verification in NodeJS: ```javascript const crypto = require('crypto'); const partnerSecret = '{{PARTNER_SECRET}}'; router.use('/webhook-handler', (request, res) => { const body = request.body; const signature = crypto .createHmac('sha256', partnerSecret) .update(JSON.stringify(body)) .digest('hex'); if (request.get('x-finicity-signature') !== signature) { throw new Error('Spoofing detected, rejecting webhook'); } }); ``` Tip: 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. --- # Report Webhooks source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md There are two ways to receive information about a report via webhook notifications, depending on how the report is generated. * **API request:** - when you generate a report using an API request, notifications are sent to the webhook URL you specified using the `callbackUrl` request parameter. * **Data Connect** : when a report is generated through [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), notifications are sent to the webhook URL specified when you generated the [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). You will receive notifications about events in the report lifecycle. Events are different depending on how the report was generated. For details, see: * [Report Events (API)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-api/index.md) or * [Report Events (Data Connect)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-dc/index.md).
### Setting up a Report Listener {#setting-up-a-report-listener} Here are some basic steps to follow when you want to set up an endpoint to receive webhook events on your server. 1. Add an inbound endpoint to receive webhook events, for example, `/reportlistener`. 2. Set the `content type` of the body to match the accept header used in the Generate Report call. 3. Set the security on your endpoint to allow the HTTPS protocol. 4. Test the endpoint locally to simulate external calls to your application. We recommend testing with the URL: . 5. Process the test request on a separate thread and return an HTTP 200 success response. Example code: * Java * Javascript ```java @PostMapping(value = "/yourCallback", accepts = "application/xml") ``` ```javascript app.post('/yourCallback', bodyParser.raw({type:'application/json'}), (req, resp) => {}; ``` Note: Since report webhooks are sent only once, we recommend processing the webhook data on a different thread as soon as it is received. --- # Institution Errors source: https://developer.mastercard.com/open-finance-us/documentation/errors/institution-errors/index.md An institution error is returned when a connection to a financial institution is impacted. These errors can occur during planned maintenance or unknown maintenance windows, or when a new or existing connection is disrupted. They can impact data refreshes or live data requests during the time when a connection is impacted. Mastercard Data Connect alerts allow up to 5 attempts for the end user after which the session will end. Alerts generated by the Data Connect application are intended solely for informational purposes and may change without notice. Data Connect alerts should not be used for programmatic purposes. | Error Codes | Error Theme | Description | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------| | [900](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#900) [901](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#901) [903](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#903) [904](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#904) [916](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#916) | ​​New Connection In Progress ​ | A new connection to a financial institution is being created. | | [101](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#101) \| [102](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#102) ​​[104](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#104) \| [105](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#105) [418](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#418-and-419) \| [419](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#418-and-419) [575](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#575) \| [580](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#580) [905](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#905) \| [906](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#906) [907](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#907) \| [908](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#908) [910](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#910) \| [911](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#911) [970](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#970) \| [971](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#971) [2018](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#2018) | Existing Connection Interruptions | Existing connection to a financial institution is down. | | [920](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) \| ​​[921](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) [922](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) \| [923](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) [924](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) \| [925](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) [926](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) \| [928](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) [929](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) \| [950](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#950) [960](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#960) \| [972](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#972) [973](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#973) \| [975](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#975) [976](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#976) [1415](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#1415) [2032](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#2032) [14020](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#14020) [14006](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14006) | Connection not supported | Error when connection to a financial institution is not supported. | | [945](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#945) ​​[948](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#948) | Connection Migration In Progress | Occurs when an account is migrated from legacy to OAuth connection but requires customer to provide their consent again. | | [20007](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/accounts-not-migrated/index.md#20007) ​​[20009](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/accounts-not-migrated/index.md#20009) | Account Migration Error | Occurs when accounts cannot be migrated from legacy to OAuth connections. | | [111](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [114](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [115](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [116](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [118](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [119](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [120](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [121](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [122](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [123](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [124](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [125](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [126](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [127](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [128](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [129](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [130](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [133](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [136](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [138](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [145](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [151](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [155](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [156](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [159](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [164](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [166](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [167](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [168](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#data-mismatch-errors) \| [170](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [178](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [180](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [184](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [198](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [417](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#417) \| [500](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#500) [525](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#525) \| [951](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [953](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) \| [954](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [979](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) \| [980](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) \| [983](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [11000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#11000) | Other Connection Issues | List of other connection issues you may encounter. | --- # Most Common Error Codes source: https://developer.mastercard.com/open-finance-us/documentation/errors/most-common/index.md This section lists the most common system errors and user errors that you are likely to encounter through your integration with Mastercard Data Connect. The tables list the errors, ranked in order of occurrence, along with the associated error message. Click the error code for more information about the error and how to address it. ## Aggregation Error Codes {#aggregation-error-codes} | Error Code | Remediation Category | HTTP Status | Error Message | |---------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [14001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14001) | Verify Account or Data State | 404 | Customer not found. | | [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) | Data Connect Fix | 500 | Invalid login credentials. Prompt the user for a new password or have them reset it. | | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | Retry Later | 500 | The account is currently being aggregated. Call the [Get Customer Account](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccounts) endpoint periodically to view the account status. The refresh operation is complete when `aggregationStatusCode` is 0 and `aggregationSuccessDate` is greater than or equal to `aggregationAttemptDate`. | | [38003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38003) | Verify Account or Data State | 404 or 500 | Customer doesn't have given account. | | [38007](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#38007) | Verify Account or Data State | 500 | Missing or incorrect MFA answer. One of your security questions (for example, name of your first pet) has expired and needs to be answered. | | [38006](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38006) | Verify Account or Data State | 404 or 500 | Customer does not have any accounts associated with `institutionId`. | | [947](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#947) | Data Connect Fix | 500 | Your token is invalid or has expired. Please re-authenticate.​ | | [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) | Data Connect Fix | 500 | Missing or incorrect MFA answer. One of your security questions (for example, name of your first pet) has expired and needs to be answered. | | [44000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#44000) | Retry Later | 202 | This error indicates that you have reached your maximum API usage plan limit. The number of requests you have made has exceeded the threshold set for your current usage plan.​ | ## User Error Codes {#user-error-codes} | Error Code | Remediation Category | HTTP Status | Error Message | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) | Data Connect Fix | 500 | Invalid login credentials. Prompt the user for a new password or have them reset it. | | [973](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#973) | Re-Authenticate or Provide Additional Information | 500 | The user is not authorized for the requested resource or online access. | | [170](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a support ticketopens in a new tab is the recommended action. | | [38008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#38008) | Invalid Input | 404 | Account details not found. | | [102](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#102) | Retry Later | 500 | Invalid login credentials. Prompt the user for a new password or have them reset it. | | [960](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#960) | Verify Account or Data State | 500 | Electronic Statement is not available for the requested account. | | [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [187](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#187) | Re-Authenticate or Provide Additional Information | 500 | Missing or incorrect MFA answer. One of your security questions (for example, name of your first pet) has expired and needs to be answered. | | [978](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#978) | Invalid Input | 500 | The requested resource is not applicable/supported for this product. | | [38057](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#38057) | Verify Account or Data State | 500 | Money Transfer details not found. | --- # Error Remediation Categories source: https://developer.mastercard.com/open-finance-us/documentation/errors/error-remediation-categories/index.md Each error code includes a recommended remediation, which is provided in the documentation. These recommendations outline suggested actions you can take when an error is encountered during either the user flow or an aggregation call. To get the most value from these remediations, we recommend aligning your internal remediation flows with our standardized remediation categories. This means that when an error is returned with remediation category "A," your application should route the user into your corresponding category A remediation flow. This allows your system to reliably handle unexpected or less-frequent errors by leveraging consistent category-level logic. In addition to implementing the category-based flows, you should also review the [Most Common Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/most-common/index.md) page and build dedicated remediation flows for those specific error codes. These common error codes represent the highest-frequency scenarios and benefit from tailored handling rather than generic category logic. You should also keep track of the most common error codes you encounter, as they may not exactly match the Most Common Errors page. | Category | Description and Guidance | |---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Data Connect Fix | Errors that Data Connect Fix can help resolve. **Important:** Data Connect Fix only applies to this category of errors, not to errors in other remediation categories. For more information, see [Using Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#using-data-connect-fix). | | Retry Later | Errors that are the result of a temporary issue at the financial institution or platform. There is no action that you need to take nor is there any action that you can take. The user must try again at some time in the future after the issue has been resolved by the financial institution. | | Re-Authenticate or Provide Additional information | Errors that require the end user to re-enter their credentials, re-authorize a connection, or provide additional details to proceed. | | Invalid Input | Errors that include malformed data, incorrect app keys, or expired sessions, among other bad input. You need to correct the invalid data for the workflow to continue. | | Verify Account or Data State | Errors that occur when the account or entity referenced no longer exists, cannot be found, or has other issues. You need to verify the identifiers or connections to enable the work flow. | | Report or Escalate for Investigation | Escalation errors that result from unexpected or unknown system issues where remediation cannot be determined. | | Retry Now | Errors due to incorrect input or a technical issue that can be resolved when the user immediately retries the action. | --- # Supported Institutions source: https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md The following table lists the Financial Institutions (FIs) that have gone through our certification process, showing which products each FI supports. Use the search box to find particular FIs. The list shown here is updated regularly to reflect the state of each FI. Users with an [Open Finance Production plan](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#production) can view the OAuth enabled status of FIs in the table below after logging in. Tip: This list might not match the list returned when calling the [Get Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#GetInstitutions) API endpoint yourself. This is because some FIs require additional onboarding with each partner. We recommend calling the API regularly in your application to obtain the latest data appropriate to you and your customers. --- # Lend source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md Mastercard Open Finance's Lend products offer premium API services that provide access to data and reports, enabling improved credit decisioning and financial information verification for consumer use cases. These products are powered by customer-permissioned data - such as bank and payroll account information - shared through [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). The Lend products support a wide range of use cases, including mortgage lending, personal loans, credit card issuance, auto lending, tenant screening, and more. Finicity, a Mastercard company, is a registered Consumer Reporting Agency (CRA) within Mastercard. Our products comply with the requirements of the Fair Credit Reporting Act (FCRA). ## Contents {#contents} * [Products Overview](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md) --- introduction to Lend products. * [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) --- how to generate Lend reports. * [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) --- how to list, retrieve and reissue reports. * [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) --- full details of all Lend reports with implementation and testing notes. * [Permissible Purpose Codes](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) --- required FCRA purpose codes and when to supply them. * [Mortgage Implementation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) --- mortgage-specific guidance, including sending reports to Fannie Mae/Freddie Mac. ## Product Delivery {#product-delivery} There are three ways you can use Lend products: * **Direct API Integration** -- you can build your own integration to our APIs using this documentation. You can be assigned a Technical Solution Engineer to help you during your implementation project. * **Existing Ecosystem Platform** -- Lend integrates with many existing lending platforms. Check with your Account Executive to confirm if Lend supports the platform you use. There are basic steps needed to enable our products in these platforms. We also provide training resources and user guides for our largest platform partners: * [MVS Encompass](https://www.finicity.com/mvs-encompass-training-resources/) * [MVS Simple Nexus](https://www.finicity.com/mvs-simplenexus-training-resources/) * **Mastercard Order Reports** -- a tool within the Mastercard Open Finance [Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/index.md) that enables you to order and view reports by sending Data Connect emails to consumers. See [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) for details. ## See Also {#see-also} * [Small Business](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/index.md) --- includes products to enable small business lending * [Tenant Screening Tutorial](https://developer.mastercard.com/open-finance-us/documentation/tutorials/tenant-screening/index.md) --- how to use Lend reports to verify income, assets and rental payment history for a prospective tenant --- # Pay source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/index.md Finicity Pay includes premium and non-premium API services to connect to customer accounts, verify the account owner, and to retrieve the routing and account numbers and account balance information from financial institutions (FI) before initiating payments. Premium services are billable per successful API call. Note: Before calling premium endpoints, check to see that the financial institution (FI) for the customer's account is certified to provide services such as ACH. * Call the Get [Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#certified-institutions) API a couple of times a day and cache the results. * Call the [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) API to retrieve the `institutionId` from the account record. * Check if the account's `institutionId `is certified for the premium service from the Get Certified Institutions results you cached earlier. * If the FI is supported, call the API and retrieve the premium service information. ## Premium Services {#premium-services} * [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) * [Account Validation Assistant](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md) * [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) * [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) * [Payment Enablement Bundle](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) * [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) * [Deposit Switch and Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md)
## Feedback Loop {#feedback-loop} [Feedback Loop](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md) enables you to share payment outcome data for Pay products so Mastercard can continuously refine risk models and reduce payment failures across the network. Feedback Loop currently supports sharing data from: * [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) * [Payment Success Indicator](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) ## See Also {#see-also} * [Pay by Bank Tutorial](https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md) - how to use Pay APIs to implement direct payment from a customer's bank account, including verifying account details, balance and ownership and checking for fraud. --- # Data Connect Errors source: https://developer.mastercard.com/open-finance-us/documentation/connect/connect-errors/index.md This section summarizes errors which can occur during different stages of the user journey through the Data Connect experience. For a summary of the user flow, see the [Data Connect Flow](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-data-connect-flow) section (more detailed flows for particular scenarios are also available in the [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md)). For a full list of all the possible errors, see the [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) section. ## Errors While Connecting to the FI and Selecting or Reviewing Accounts {#errors-while-connecting-to-the-fi-and-selecting-or-reviewing-accounts} The screens shown to the user during the Data Connect flow are as follows: 1. Accept the Terms and Conditions and the Privacy Policy agreement. 2. Search Financial Institutions. 3. Connect to a Financial Institution. 4. Log in to the Financial Institution. 5. Select the accounts to share financial data. 6. Review the connected accounts and the account details. The following tables provide a summary of the errors which can typically arise during these steps. Click on the links for the error numbers for details of each error and what you can do to resolve the issue. * **Errors While Selecting and Logging in to the FI** The following errors can be encountered during steps 1 to 4: | HTTP Status Code | Error Theme | Error Codes | |------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 500 | Account Not Found | [909, 913, 914, 946, 952, 955, 38006, 38003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md) | | 500/409 | Incomplete Authorization | [185, 187, 931, 938, 940, 3003, 3004, 10814, 12003, 38007, 50024, 50025](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md) | | 500 | Additional Information Needed | [936, 959, 961, 106, 107, 108, 109, 38053](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md) | | 500 | Invalid Account | [949](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/949/index.md) | | 500 | Invalid Token | [947, 4034](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md) | | 500 | Connection Not Supported | [920, 921, 922, 923, 924, 925, 926, 927, 928, 929, 950, 960, 972, 973, 975, 976, 1403, 1415, 2032, 4041, 10008, 10106, 14020, 14006](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md) | | 500 | Data Sync in Progress | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | | 500 | Invalid Credentials | [103, 45002, 24303, 110039](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md) | | 500 | Item Not Found | [265, 1007, 12015, 13002, 13004, 14001, 14002, 14003, 14006, 14008, 20000, 20001, 20003, 20017, 20027, 24553, 38008, 38057, 90004, 10046, 10047, 110002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md) | | 500, 4xx, 401 | Unexpected login error | [179, 1008, 2040](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md) | | 500 | New Connection in Progress | [900, 901, 902, 903, 904, 915, 916](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md) | | 500 | Existing Connection Interruptions | [101, 102, 104, 105, 418, 419, 575, 579, 580, 905, 906, 907, 908, 910, 911, 970, 971](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md) | | 500 | Other Connection Issues | [979](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors), [980](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors), [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors), [983](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors), [110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 136, 137, 138, 139, 141, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors), [168, 169](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#data-mismatch-errors), [170, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 186, 188, 189, 190, 191, 192, 193](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors), [194](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#194), [195, 196](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors), [197](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#197), [198, 201](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors), [417](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#417), [500](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#500), [525](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#525), [341, 342, 343, 344, 345, 951, 953, 954](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors), [11000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#11000) | | 400/500 | Unexpected System Issue | [990, 991, 992, 993, 994, 995, 996, 997, 998, 1000, 1001, 1002, 1004, 1005, 1009, 1010, 1011, 1012, 14030, 10030, 12001, 12008, 12009, 19000, 20014, 50050, 110015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md) | | 401, 404, 503, 403, 500, 400 | Invalid Request | [973, 978, 981, 2005, 10000, 10001, 10005, 10010, 14023, 20002, 20024, 20028, 38054, 38056, 42002, 42003, 42004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md) | | 500 | Bad Request | [20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20025) | | 500 | API Request Authentication Issues | [24302](https://developer.mastercard.com/open-finance-us/documentation/errors/request/api-auth-issue/index.md#24302) | | 500 | Maximum Limit Exceeded | [977](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md) | * **Errors While Selecting and Reviewing Accounts** The following errors can be encountered during steps 5 and 6: | HTTP Status Code | Error Theme | Error Codes | |--------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 500/404 | Account Not Found | [909, 913, 946, 952, 955, 38003, 38006](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md) | | 404 | Item Not Found | [14001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14001) | | 500/409 | Incomplete Authorization | [931, 938, 940, 185, 187, 10814, 12003, 38007, 50024, 50025](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md) | | 500 | Additional Information Needed | [936, 959, 961, 106, 107, 108, 109, 38053](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md) | | 500 | Invalid Token | [947, 4034](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md) | | 401, 500 | Connection Not Supported | [920, 921, 922, 923, 924, 925, 926, 927, 928, 929, 950, 960, 972, 973, 975, 976, 2032, 1403, 4041, 10008, 10106, 14020, 201000, 1415](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md) | | 401, 500 | Expired Session | [974, 194, 331, 1408, 1440, 502, 503, 504, 10022, 10023](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md) | | 500, 503, 404, 403 | Invalid Request | [973, 978, 981, 2005, 10000, 10001, 10005, 10010, 14023, 20002, 20024, 20028, 38054, 38056, 42002, 42003, 42004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md) | | 500 | Other Connection issues | [417, 500, 525, 979, 982, 111, 112, 113, 114, 116, 117, 119, 122, 123, 124, 125, 126, 127, 128, 129, 130, 133, 136, 138, 145, 151, 155, 156, 164, 167, 168, 170, 178, 180, 184, 198, 11000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md) | | 500 | Existing Connection Interruptions | [101, 102, 104, 105, 905, 906, 907, 908, 909, 910, 911, 970, 2018, 418, 419, 575, 579, 580](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md) | | 4xx | Unexpected login error | [179, 1008, 2040](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md) | | 500 | Bad Request | [20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20025) | | 400/500 | Unexpected System Issue | [10030](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#10030) | | 500, 401 | Consent Authorization | [2001, 2003, 2006, 2017, 2024, 2026, 2028, 2030, 2031, 2035, 2036, 2037, 2038, 2039, 10013, 12005, 24019](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md) | | 500 | New Connection In Progress | [900, 901, 902, 903, 904, 915, 916](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md) | ## Other Data Connect Errors {#other-data-connect-errors} The possible errors can be categorized as follows: * **OAuth connections** enable Financial Institutions to authenticate customers securely without storing or transmitting usernames and passwords. OAuth connections speed up data access, enhance API security, and enable customers to manage account permissions. Customers can disconnect at any time and seamlessly access their accounts even after changing credentials. The following errors relate to OAuth connections: | HTTP Status Code | Error Theme | Error Codes | |------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 500 | Additional Information needed from the end user | [38053](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#38053) | | 500, 404 | Connection Not Supported | [920, 921, 922, 923, 924, 925, 926, 927, 928, 929, 950, 960, 972, 973, 975, 976, 2032, 1403, 1415, 10106, 14006, 14020, 4041, 10008, 201000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md) | | 401, 500 | Consent Authorization | [2003, 2031, 2006, 2017, 2024, 2026, 2028, 2030, 2035](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md) | | 401 | Unexpected login error | [179, 1008, 2040](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md) | | 400, 403 | Invalid Request | [973, 978, 981, 2005, 10000, 10001, 10005, 10010, 14023, 20002, 20024, 20028, 38054, 38056, 42002, 42003, 42004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md) | | 409, 500 | Account Migration Error | [20007, 20009](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/accounts-not-migrated/index.md) | | 500 | Item Not Found | [14006](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14006) | | 400/ 500 | Unexpected System Issue | [10030](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#10030) | 500 \| Expired Session \| [974, 194, 331, 1408, 1440, 502, 503, 504, 10022, 10023](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md) 500 \| Bad Request \| [20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20025) 500 \| Existing Connection Interruptions \| [2018](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#2018) 500 \| Other Connection Issues \| [500](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#500) 500 \| Connection Migration in Progress \| [945, 948](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md) * **Errors that can occur while using Data Connect Fix** The table below lists common errors that might be encountered when using the Data Connect Fix flow, which enables the user to sign-in and update their credentials or perform a new MFA challenge. | HTTP Status Code | Error Theme | Error Codes | |--------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 500 | Account Update Failed | [324](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/324/index.md), [403](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/403/index.md) | | 500/409 | Incomplete Authorization | [931, 938, 940, 185, 187, 12003, 10814, 38007, 50024, 50025](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md) | | 500 | Additional Information Needed | [936, 959, 961, 106, 107, 108, 109](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md) | | 500 | Invalid Credentials | [103, 45002, 24303, 110039](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md) | | 500 | Bad Request | [20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20025) | | 500 | Connection Not Supported | [920, 921, 922, 923, 924, 925, 926, 927, 928, 929, 950, 960, 972, 973, 975, 976, 2032, 1403, 1415, 10106, 14006, 14020, 4041, 10008, 10106, 14006, 201000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md) | | 500 | Data Sync in Progress | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | | 404, 500 | Item Not Found | [14001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14001), [14006](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14006) | | 202 | Maximum Limit Exceeded | [977, 44000, 44002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md) | | 401, 4xx, 500 | Expired Session | [974, 194, 331, 1408, 1440, 502, 503, 504, 10022, 10023](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md) | | 503, 400, 404, 403 | Invalid Request | [10005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10005), [20024](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#20024), [42002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42002), [42003](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42003) | | 500 / 400 | Unexpected System Issue | [10030](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#10030) | | 500 | Unexpected login error | [179, 1008, 2040](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md) | | 500 | Other Connection Issues | [500](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#500), [525](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#525), [155, 156, 167](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors), [11000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#11000) | | 500 | New Connection in Progress | [900, 901, 902, 903, 904, 915, 916](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md) | | 500 | Existing Connection Interruptions | [101, 102, 104, 105, 905, 906, 907, 908, 909, 910, 911, 970, 2018, 418, 419, 575, 579, 580](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md) | * **Errors that can occur while refreshing customer accounts** The following errors can occur during account refresh or while dealing with expired sessions, timeouts, session cancellations, encountering unknown errors, connection issues, date stamping, student loan issues, payment routing processing errors, username not available and partner requests. | HTTP Status Code | Error Theme | Error Codes | |------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 500 | Bad Request | [6004, 20015, 20020, 20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md) | | 500 | Connection not supported | [950](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#950) | | 500 | Existing Connection Interruptions | [575](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#575) | | 404 | Invalid Request | [973, 978, 981, 2005, 10000, 10001, 10005, 10010, 14023, 20002, 20024, 20028, 38054, 38056, 42002, 42003, 42004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md) | | 401, 500 | Consent Authorization | [2001, 2003, 2006, 2017, 2024, 2026, 2028, 2030, 2031, 2035, 2036, 2037, 2038, 2039, 10013, 12005, 24019](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md) | | 404, 500 | Item Not Found | [265, 1007, 12015, 13002, 13004, 14001, 14002, 14003, 14006, 14008, 20000, 20001, 20003, 20017, 20027, 24553, 38008, 38057, 90004, 10046, 10047, 110002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md) | | 500 and 400 | Unexpected System Issue | [990, 991, 992, 993, 994, 995, 996, 997, 998, 1000, 1001, 1002, 1004, 1005, 1009, 1010, 1011, 1012, 14030, 10030, 12001, 12008, 12009, 19000, 20014, 50050, 110015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md) | | 500 | Other Connection issues | [951, 954](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | | 500 | Invalid Token | [947, 4034](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md) | --- # Institution Settings source: https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md ## Financial Institution Search List {#financial-institution-search-list} You can change the financial institutions (FIs) search list that displays in a Data Connect session using the `institutionSettings` parameter in the body of the request for the [Generate Data Connect URL APIs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). For OAuth connections, you can manage whether you want early adoption of a new OAuth connection or later adoption during the final migration. **Example** : If your partner ID is registered at an OAuth institution, then set `institutionSettings: autoreplace` so that only OAuth institutions return. If you decide to go back to a legacy connection, then override the `institutionSettings` parameter when you generate a Data Connect URL link to display the legacy institutions. ### Client Institution Settings {#client-institution-settings} Set your environment with different institution settings to change the results of the institutions that display in the search list. * [hidden](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md#hidden-hide-financial-institutions) - Hide a specific institution(s) from the search list. * [visible](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md#visible-change-hidden-financial-institution-to-visible) - Display new connections include testing environments. * [replace](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md#replace-override-legacy-financial-institutions) - Replace legacy institutions with new connections. When OAuth connections are launched, this setting is automatically updated. * [autoreplace](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md#autoreplace-legacy-financial-institutions) - This determines if a customer is using legacy institutions. Accounts connected with a legacy institution won't see new OAuth FIs replacing the legacy institutions. If no legacy accounts exists, then new OAuth FIs display. Note: Contact your Mastercard sales engineer (SE) to help you set the institution settings. ## Institution Settings {#institution-settings} In the [Generate Data Connect URL APIs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md), use the `institutionSettings` parameter to temporarily override the [Client Institution Settings](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md#client-institution-settings) per Data Connect session. ```JSON { "partnerId": "1445585709680", "customerId": "1005061234", "institutionSettings": { "5": "hidden", "1407": "hidden", "102224": "autoreplace" } } ``` ### hidden: Hide Financial Institutions {#hidden-hide-financial-institutions} Hide an individual institution or a set of institutions for a specific Data Connect session. ```JSON { "institutionSettings": { "5": "hidden", "1407": "hidden" } } ``` ### visible: Change Hidden Financial Institution to Visible {#visible-change-hidden-financial-institution-to-visible} When new OAuth connections become available, you can internally test the connection by making the FI visible in Data Connect's search list for institutions. If the OAuth connection is new and the legacy connection is still available, then two FIs with the same name will display in the search list. ```JSON { "institutionSettings": { "102224": "visible" } } ``` ### replace: Override Legacy Financial Institutions {#replace-override-legacy-financial-institutions} When a new OAuth institution goes live, eventually all of your customers will automatically migrate to the new OAuth connection. If you want to opt-in for early adoption of the OAuth connection, and override all legacy FIs per a Data Connect session, then pass `institutionSettings: replace` in the body of the request call to the [Generate Data Connect URL APIs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). ```JSON { "institutionSettings": { "102224": "replace" } } ``` ### autoreplace: Legacy Financial Institutions {#autoreplace-legacy-financial-institutions} When set for a new OAuth institution, if a customer already has accounts from previous legacy institutions, the new OAuth institution does not display. This enables legacy customers to carefully migrate to the new OAuth connection before it is displayed. Customers without legacy institutions display the new OAuth institutions in the search list. ```JSON { "institutionSettings": { "102224": "autoreplace" } } ``` --- # Data Connect Components source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/index.md Mastercard Data Connect Components gives you the most control and customization across all our Data Connect integration options. It's ideal if you need to build a highly tailored solution and are comfortable managing both the initial setup and ongoing maintenance. If you're unsure whether this is the right approach for your use case, speak to your Customer Success Manager (CSM)---they can help you decide on the best option (for example, the customization options discussed in the [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) section may be more suitable for you). Data Connect Components are pre-built embeddable components that allow you more control and flexibility over your customer's Data Connect experience. By leveraging Data Connect Components, you can design and test your user experiences to have the voice, brand, flow and feel that best meets your needs. This removes the requirement to structure the Data Connect experience as defined by Mastercard. With Data Connect Components you can host and create a user journey that provides a more seamless experience inside your web application. **Easy customization** The browser-based SDK contains native web components that can be embedded into your HTML just like any other element. These pre-built components handle the heavy lifting, such as creating the sandboxed iframes and loading contents for the financial login forms and MFA challenges. **Wide range of functionalities** Our Data Connect Components server provides the functionality needed for managing the user journey, supporting a wide range of interactions with the Open Finance APIs. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components_ux_customize_intro_june2025.png) **Styling** Using CSS you can style the web components to meet your brand and experience needs. ## Overview {#overview} Data Connect Components takes the customization of Data Connect Full and Lite to the next level. With Data Connect Components, partners own and build all the screens. In contrast, only portions of the journey are owned by the partner in Data Connect Lite and only some [configurations](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) for Mastercard hosted Data Connect Full are available. **Data Connect Components** ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components-overview-1.png) **Data Connect Lite** ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components-overview-2-june2025.png) **Data Connect Full** ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components-overview-3-june2025.png) In order to implement Data Connect Components, you will need to understand our requirements, UX best practices, and how the flow works technically. This will provide you and your team with the foundation to implement a successful flow for your end users while partnering with Mastercard. ## Requirements {#requirements} Before you can get started building your Data Connect experience using Data Connect Components, you need to go through a legal review of the user experience to ensure all Mastercard requirements are met. This includes sharing screens of the user journey. Please coordinate with your Mastercard representative to begin this process. There are a few requirements that you, as a Mastercard Open Finance Partner, must ensure are met: * Mastercard's role must be clearly stated to the end user. * Mastercard's Terms and Privacy Notice must be presented to, and accepted by, the end user. * Mastercard's brand must be represented appropriately. * The user's login credentials must not touch a Partner's servers. Note: All flows and screens need to be reviewed and signed off by Mastercard Legal and UX Design prior to go live. Work with your Mastercard account representative to get the necessary approvals. Until the approvals have been given, you will not be able to access the Data Connect Components APIs other than for testing and accessing test data. To view the specifics of each of these requirements see the [UX Requirements](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md#ux-requirements) section of the [Data Connect Components UX Implementation Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md). Outside of these requirements, Partners are free to design and build their flows as they see fit. ## Using Data Connect Components {#using-data-connect-components} Data Connect Components provides a web SDK and associated REST API endpoints. We also provide details of how to implement Data Connect Components in a React Native app: * [Data Connect Components Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md) * [React Native App Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/react-native/index.md) * [Data Connect Components Webhooks](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebhooks/index.md)
The following page outlines UX design considerations when working with Data Connect Components: * [Data Connect Components UX Guidelines](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md)
For more details of the various user flows, see: * [Data Connect Components Flows](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md)
If you are migrating from Data Connect Full or Data Connect Lite to using Data Connect Components, see our Migration Guide: * [Migrating to Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/migration/index.md) --- # Configure the Data Connect Experience source: https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md You can configure the UI and functional aspects of the Mastercard Data Connect user experience using the [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) feature on Client Hub. If you create a custom experience you can configure: * number of accounts and account types the user can link (account filtering) * Open Finance [product type](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md#product-types) - this changes the Connect Full UX to prompt the user to provide the correct financial data (for example, prompting them to upload a paystub) and is also required for account filtering * UI options such as branding and back/exit buttons * whether the Data Connect URL can be used once or multiple times * whether Lend reports are automatically generated
The options available depend on whether you're using Data Connect Full/Lite/Fix or sending a Data Connect email - see [Configuration Options](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md#configuration-options) on this page. Tip: If you need help with customizing the Data Connect experience, you can [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md) and collaborate with a sales engineer. ## Experience ID {#experience-id} Whether you configure your experience on [Customize Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) or with the assistance of the Mastercard support team, you will receive a unique experience ID. You can use this ID in the `experience` parameter when [generating a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). The generated URL will then load your configured version of the Data Connect experience. You can create multiple experiences to support different use cases or scenarios within your application. For example, you might configure separate experiences for lending workflows, payment verification, or personal finance management, each with appropriate branding and settings. Note: The `experience` parameter is optional. If you do not provide an experience ID when generating a Data Connect URL, the default Mastercard Open Finance branding will be used and a standard transaction aggregation will be performed. Note: Ensure you [register your application](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md) before you request an `experience`. Your application registration is critical to map the experience to your application. ## Configuration Options {#configuration-options} The following table shows which options for configuring the Data Connect experience are available. | Name | Description | Data Connect Full | Data Connect Lite | Data Connect Fix | Data Connect Email | |--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|-------------------|------------------|--------------------| | Brand Color | The brand color that is used for primary buttons and the loader within Data Connect. | ✔ | ✔ | ✔ | ✔ | | Brand Logo | Display a logo in Data Connect. Format allowed: SVG files. | ✔ | | | ✔ | | Brand Icon | Display an icon on the Share data page. | ✔ | ✔ | ✔ | ✔ | | Email Logo | Display a logo in Data Connect emails sent to consumers. Format allowed: PNG files. | | | | ✔ | | Email Templates | Configure the body, subject, and button text for Data Connect emails sent to customers. | | | | ✔ | | Popular Financial Institutions | Display the most common financial institutions (up to 8 tiles) on the Bank Search page. | ✔ | | | ✔ | | Reports | The credit decisioning reports sent after a Data Connect session successfully completes. | ✔ | | | ✔ | | Single Use URL | By default, a Data Connect URL can be used multiple times. Set this to `true` if you want to prevent multiple reports from being run from one Data Connect URL or email. **Note** : The `singleUserUrl` value passed in the Generate Data Connect URL API call overrides the value set via the experience. | ✔ | ✔ | ✔ | ✔ | | Enable Fix | Enables the Data Connect Fix flow for the Data Connect application instead of requesting it through the Generate Fix Data Connect URL API endpoint. | ✔ | | | ✔ | | Disable Account Management | When enabled, the customer is unable to edit or delete the accounts they've added to Data Connect, **Tip**: Useful in Personal Finance Management use cases where account management is handled elsewhere within the application. | ✔ | | | ✔ | | Disable Account History | When enabled, the customer cannot see any of their accounts previously added in a Data Connect session. | ✔ | | | ✔ | | Account Selection Type | Specify whether the customer can select only one account (radio button), or multiple accounts (checkboxes) in a Data Connect session. **Tip**: Useful for setting up an ACH flow. | ✔ | | | ✔ | | Hide Exit Button | Hide the Exit button on all Data Connect pages. | ✔ | ✔ | ✔ | ✔ | | Hide Back Button | Hide the Back button on all Data Connect pages. | ✔ | ✔ | ✔ | ✔ | | Account Type Filtering | Allow only certain types of accounts to be shown to the customer for selection (checking accounts, savings accounts, and so on). **Note**: If you are using Data Connect Lite, you must set a product type to enable account type filtering, and ensure that if the customer selects no suitable accounts, the application handles Data Connect returning an empty array in the added event (typically this would be handled by displaying a message or screen saying no sharable accounts were found). | ✔ | ✔ | | | Note: You can set which financial institutions to display on the **Find your bank** screen in the Data Connect app. See [Institution Settings](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md). ## Product Types {#product-types} When you configure a Data Connect experience, you set a product type that determines the financial data the customer is prompted to provide. See [Customizing Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) for [how to set a product type](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#product-type). Some product types are linked to a Lend or Small Business report and can optionally generate the report when the customer completes the experience. See [the Lend documentation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-data-connect) for details. The following product types are available: | Product Type | Description | Report | |--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| | ACH | Returns details for a single account, including posted balance, account number, and routing number. | | | Aggregation | Daily account aggregation with an initial 180-day transaction pull for all accounts for a single customer. | | | Balance Analytics Business CRA | Balance verification through business representative-permissioned bank account data. Generates a Balance Analytics report for CRA purposes. | Balance Analytics | | Balance Analytics Business FTC | Balance verification through business representative-permissioned bank account data. Generates a Balance Analytics report for FTC compliant purposes. | Balance Analytics | | Balance Analytics Business Non CRA | Balance verification through business representative-permissioned bank account data. Generates a Balance Analytics report for non-CRA purposes. | Balance Analytics | | Balance Analytics Personal CRA | Balance verification through customer-permissioned bank account data. Generates a Balance Analytics report for CRA purposes. | Balance Analytics | | Balance Analytics Personal Non CRA | Balance verification through customer-permissioned bank account data. Generates a Balance Analytics report for non-CRA purposes. | Balance Analytics | | Bill Pay Switch | Enables partners to switch payroll details in a mobile app. | | | Cash Flow Analytics Business CRA | Cash flow verification through business representative-permissioned bank account data. Generates a Cash Flow Analytics report for CRA purposes. | Cash Flow Analytics | | Cash Flow Analytics Business FTC | Cash flow verification through business representative-permissioned bank account data. Generates a Cash Flow Analytics report for FTC compliant purposes. | Cash Flow Analytics | | Cash Flow Analytics Business Non CRA | Cash flow verification through business representative-permissioned bank account data. Generates a Cash Flow Analytics report for non-CRA purposes. | Cash Flow Analytics | | Cash Flow Analytics Personal Non CRA | Cash flow verification through customer-permissioned bank account data. Generates a Cash Flow Analytics report for non-CRA purposes. | Cash Flow Analytics | | Cash Flow Personal | Cash flow verification through customer-permissioned bank account data. Generates a Cash Flow Analytics report. | Cash Flow Analytics | | MVS Basic | Mortgage Verification Service (MVS) basic asset, income, and employment waterfall experience. The customer connects their bank and payroll accounts. Generates a VOIE - Payroll report (if data is found) and a VOAI - Transactions report. | VOIE - Payroll, VOAI | | MVS Basic Paystub | MVS basic paystub experience. The customer connects their bank account and uploads their most recent paystub. Generates a VOIE - Paystub (with TXVerify) report and a VOAI - Transactions report. | VOIE - Paystub (with TXVerify), VOAI | | MVS Full | MVS full waterfall experience for asset, income, and employment verification through customer-permissioned transactions, payroll, and paystub data. The customer connects their bank and payroll accounts, then uploads a paystub if additional employment verification is needed. Generates a VOIE - Payroll report, a VOAI report, and a VOIE - Paystub (with TXVerify) report if required. | VOIE - Payroll, VOAI, VOIE - Paystub (with TXVerify) | | MVS IE | MVS income and employment waterfall experience. The customer connects their payroll accounts, then connects bank accounts and uploads a paystub if additional employment verification is needed. Generates a VOIE - Payroll report and a VOIE - Paystub (with TXVerify) report if required. | VOIE - Payroll, VOIE - Paystub (with TXVerify) | | MVS IE Basic | MVS income and employment basic waterfall experience. The customer connects their payroll accounts, then connects bank accounts if additional employment verification is needed. Generates a VOIE - Payroll report and a VOAI report if required. | VOIE - Payroll, VOAI | | Payment History Business CRA | Analyzes transactions to predict risk for future payments through business representative-permissioned bank account data. Generates a Payment Risk Insights report for CRA purposes. | Payment Risk Insights | | Payment History Business FTC | Analyzes transactions to predict risk for future payments through business representative-permissioned bank account data. Generates a Payment Risk Insights report for FTC compliant purposes. | Payment Risk Insights | | Payment History Business Non CRA | Analyzes transactions to predict risk for future payments through business representative-permissioned bank account data. Generates a Payment Risk Insights report for non-CRA purposes. | Payment Risk Insights | | Payroll Deposit Switch | Enables customers to connect to their payroll provider to switch their direct deposit distribution into a new or existing account at a financial institution. | | | Pre Qual Voa | Asset verification for prequalifications through customer-permissioned bank account data. Generates an Asset Prequalification report. | Asset Prequalification | | Transactions CRA | Account aggregation for multiple accounts providing a snapshot of account history for up to 6 months. Available in JSON, XML, and PDF formats. This report provides FCRA-compliant CRA coverage. | TACRA | | VOA | Asset verification through customer-permissioned bank account data. Generates a Verification of Assets (VOA) report. | VOA | | VOA History | Asset and income verification through customer-permissioned bank account data. Generates a Verification of Assets and Income (VOAI) report. | VOAI | | VOE Payroll | Employment verification through customer-permissioned payroll account data. Generates a Verification of Employment - Payroll report. | VOE - Payroll | | VOE Transactions | Employment verification through customer-permissioned bank account data. Generates a Verification of Employment - Transactions report. | VOE - Transactions | | VOI | Generates a Verification of Income (VOI) report for all accounts for a single customer. The report includes up to 24 months of transaction history (credits and deposits only). Reports are available for unlimited refresh within 60 days of the original report creation. | VOI | | VOIE Payroll | Income and employment verification through customer-permissioned payroll account data. Generates a Verification of Income and Employment - Payroll report. | VOIE - Payroll | | VOIE Paystub | Income and employment verification through paystub data. The customer uploads their paystub, which is then digitized. Generates a VOIE - Paystub report. | VOIE - Paystub | | VOIE Paystub Tx Verify | Income and employment verification through customer-permissioned transaction and paystub data. Customers connect to the bank account where they deposit their pay and upload their paystub. Generates a VOIE - Paystub (with Transaction Verify) report. | VOIE - Paystub (with TXVerify) | ## Retrieve Experience IDs {#retrieve-experience-ids} Retrieve all the relevant experiences associated with your application by calling the [Retrieve Experience](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetAllExperience) endpoint. This endpoint returns the unique identifier for each `experience` linked to your application name - `appName` (the application name you provide when registering your application using the [App Registration API](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#RegisterApp)). Optionally, you can filter experiences by specific products such as ACH, AO, ABC, using `productCode` as a query parameter. The `productCode` values must correspond to the products outlined in your contract with Mastercard. API Reference: `GET /connect/experiences` --- # Manage source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/index.md Next-gen business solutions driven by expanded data access allowing for a complete view of a customer's permissioned financial accounts. Normalized, real-time data is standardized across data fields, vocabulary, naming conventions, and application of rules, resulting in a modernized ecosystem digital-hungry customers deserve. Note: Before calling any product or service, check to see that the financial institution (FI) for the customer's account is certified for that product or service. * Call the Get [Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#certified-institutions) API daily and cache the results. * Call the [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-full-details-afd-or-account-limited-aggregation-ala) API to retrieve the `institutionId` from the account record. * Check if the account's `institutionId` is certified for the premium service from the Get Certified Institutions results you cached earlier. * If the FI is supported, proceed to call the product or service. ## Data Access {#data-access} * [Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) --- account data, refreshed daily. * [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) --- customer transaction data. * [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) --- subscribe to receive notifications whenever there are updates to account or transaction data for a specific customer's account. * [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) --- understand the different levels of access provided for account aggregation and transaction data. ## Products {#products} * [Account Statements](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md) --- retrieve a customer's FI statements as a PDF file. * [Loan Payment Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md) --- retrieve the information needed to move money to a non-routable liability account. * [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) --- improve the clarity and usability of transaction data by categorizing transactions, identifying merchants, locations, logos, and websites. * [Consumer Foresight](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md) --- (Beta) generate a tailored consumer insights report against various spending categories, for a given customer. * [Recurring Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md) --- identify and categorize a customer's recurring transactions, allowing you to analyze patterns of recurring payments. --- # Account Errors source: https://developer.mastercard.com/open-finance-us/documentation/errors/account-errors/index.md To aid you in understanding error context and more effectively troubleshoot problems, Mastercard Open Finance errors have been categorized into **themes** . This section covers account-level errors and aggregation status codes. For a list of all the Mastercard Open Finance error codes, see the [Full Error List](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) ## Account Errors {#account-errors} Account-level errors occur during the following scenarios: * **First-time login** : When an end user logs into the partner's application and attempts to add or link their accounts for the first time, the [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) session engages in several processes, such as financial institution discovery, account selection, account permissioning, and authentication flow. Data Connect automatically displays alerts so the end user can take recommended actions and resolve errors that may occur during any of these events. * **Adding/linking another account** : When an end user returns to add or link another account, the [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) alerts (error messages in the user interface) guide the end user to take recommended actions to complete all required events for a successful Data Connect session. * **Partner-initiated requests**: If an end user is not present on the partner's application and the partner API call returns an error, the error directs the partner to take the recommended action and resolve errors where applicable. * **Scheduled or manual data refresh** : Mastercard schedules data refreshes (aggregation) to ensure end users' transactional data is current. This updated data is accessible via our APIs or directly pushed to partners enrolled in [TXpush](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md). If a data refresh fails, Mastercard updates the `aggregationStatusCode` to a non-zero value that indicates the nature of the failure, and where applicable, [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) alerts appear when the end user returns to a Data Connect session. The user can then take recommended actions and resolve the errors. ## Aggregation Status Codes {#aggregation-status-codes} As accounts are aggregated during automated data refresh, an aggregation status code is returned via the `aggregationStatusCode` field in the Account Aggregation endpoints. An `aggregationStatusCode` represents the status or outcome of an aggregation process. * An `aggregationStatusCode` of **0** denotes that a successful aggregation of the account(s) has occurred. ```JSON { "accounts": [ { "id": "6049480293", "number": "2000004444", "accountNumberDisplay": "4444", "name": "Roth IRA", "balance": 525.18, "type": "investment", "aggregationStatusCode": 0, "status": "active", "customerId": "6027530414", "institutionId": "101732", "balanceDate": 1685020689, "aggregationSuccessDate": 1685020728, "aggregationAttemptDate": 1685020728, "createdDate": 1685020611, "currency": "USD", "lastTransactionDate": 1685020689, "institutionLoginId": 6023453620, "detail": { "marginAllowed": true, "cashAccountAllowed": true, "vestedBalance": 1250.00, "currentLoanBalance": 4500.00, "loanRate": 3.00 }, "displayPosition": 3, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Roth IRA", "oldestTransactionDate": 1667736000, "marketSegment": "personal" }, { "id": "6049480311", "number": "1000002222", "realAccountNumberLast4": "2222", "accountNumberDisplay": "2222", "name": "Savings", "balance": 525.18, "type": "savings", "aggregationStatusCode": 0, "status": "active", "customerId": "6027530414", "institutionId": "101732", "balanceDate": 1685020689, "aggregationSuccessDate": 1685020737, "aggregationAttemptDate": 1685020737, "createdDate": 1685020619, "currency": "USD", "lastTransactionDate": 1685020689, "institutionLoginId": 6023453620, "detail": { "availableBalanceAmount": 525.18, "periodInterestRate": "4.5", "openDate": 1639206000 }, "displayPosition": 6, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Savings", "oldestTransactionDate": 1667736000, "marketSegment": "personal" }, { "id": "6049480317", "number": "1000001111", "realAccountNumberLast4": "1111", "accountNumberDisplay": "1111", "name": "Checking", "balance": 525.18, "type": "checking", "aggregationStatusCode": 0, "status": "active", "customerId": "6027530414", "institutionId": "101732", "balanceDate": 1685020689, "aggregationSuccessDate": 1685020740, "aggregationAttemptDate": 1685020740, "createdDate": 1685020621, "currency": "USD", "lastTransactionDate": 1685020689, "institutionLoginId": 6023453620, "detail": { "availableBalanceAmount": 525.18, "periodInterestRate": "4.5", "openDate": 1639206000 }, "displayPosition": 5, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Checking", "oldestTransactionDate": 1667736000, "marketSegment": "personal" } ] } ``` * Other `aggregationStatusCode` signifies an error state. ```JSON { "accounts": [ { "id": "6049960514", "number": "2000004444", "accountNumberDisplay": "4444", "name": "Roth IRA", "balance": 529.20, "type": "investment", "aggregationStatusCode": 185, "status": "active", "customerId": "6027787614", "institutionId": "101732", "balanceDate": 1685366419, "aggregationAttemptDate": 1685366452, "createdDate": 1685366419, "currency": "USD", "institutionLoginId": 6023673450, "detail": {}, "displayPosition": 3, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Roth IRA", "marketSegment": "personal" }, { "id": "6049960518", "number": "1000002222", "accountNumberDisplay": "2222", "name": "Savings", "balance": 529.20, "type": "savings", "aggregationStatusCode": 185, "status": "active", "customerId": "6027787614", "institutionId": "101732", "balanceDate": 1685366419, "aggregationAttemptDate": 1685366452, "createdDate": 1685366419, "currency": "USD", "institutionLoginId": 6023673450, "displayPosition": 6, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Savings", "marketSegment": "personal" }, { "id": "6049960519", "number": "1000001111", "accountNumberDisplay": "1111", "name": "Checking", "balance": 529.20, "type": "checking", "aggregationStatusCode": 185, "status": "active", "customerId": "6027787614", "institutionId": "101732", "balanceDate": 1685366419, "aggregationAttemptDate": 1685366452, "createdDate": 1685366419, "currency": "USD", "institutionLoginId": 6023673450, "displayPosition": 5, "financialinstitutionAccountStatus": "OPEN", "accountNickname": "Checking", "marketSegment": "personal" } ] } ``` Warning: We recommend that you listen for and catch non-zero aggregation status codes, and invoke [Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#using-data-connect-fix) where appropriate. For errors which are not fixable in this way, see the [Full Error List](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) section for further suggestions. In some cases you may need to submit a support request. The following table lists the different error states that may occur during the aggregation process. | Status Codes | Theme | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [909](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#909) ​​[913](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#913)​​ [914](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#914)​​ [946](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#946)​​ [952](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#952) [38003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38003) | Account Not Found | Bank account cannot be found at the financial institution. | | [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) [187](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#187) [931](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#931) [938](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#938) [940](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#940) [971](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#971) [12003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#12003) | ​​Incomplete Authorization ​ | Inadequate response to security questions from the end user. | | [106](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#106) [108](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#108) [109](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#109) [936](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#936)​​ [959](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#959) [961](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#961) [981](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#981) [38053](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#38053) ​ | Additional Information needed from the end user | Additional information required from the end user during an add account event. | | [168](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#data-mismatch-errors) [169](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#data-mismatch-errors) | Duplicate account | An account in the return data matches multiple requested accounts. Have the customer keep one account and delete the duplicate(s) in Data Connect. | | [945](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#945) | OAuth migration (account migrated but not consented) | Prompt the end user to re-authenticate via Data Connect Fix. If Data Connect fix isn't integrated, have the customer delete the account and add it again under the same bank with the OAuth connection indicated in the 'Institution Search' list. | | [946](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#946) | Account not found (account may have been closed) | Prompt the end user to authenticate the right account via Data Connect Fix. If Data Connect fix isn't integrated, have the customer delete the account and then find and add an active account in Data Connect. | | [947](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#947) [4034](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#4034) | Invalid Token | Token expired or refresh required, token associated with the end user account has expired or is invalid. | | [948](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#948) | OAuth migration (account migrated but not authenticated) | Prompt the end user to re-authenticate via Data Connect Fix. If Data Connect fix isn't integrated, have the customer delete the account and add it again under the same bank with the OAuth connection indicated in the 'Institution Search' list. | | [951](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [953](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [979](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [980](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) [983](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Connection Error | Connection is interrupted temporarily due to an unexpected error. ​ | | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | Data Sync in Progress | The account is currently being aggregated. Call the Get Customer Account endpoint periodically to view the account status. The refresh operation is complete when` aggregationStatusCode` is 0 and `aggregationSuccessDate` is greater than or equal to `aggregationAttemptDate`.​ | | [949](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/949/index.md) | Invalid Account | Accounts are in error status and can not be recovered in any way. Delete these accounts. | | [924](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) [972](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#972) [976](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#976) | Unsupported Product​ | This error could occur when an institution does not support aggregation or some of the Open Finance products.​​ | | [975](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#975) | User Unauthorized | This error is caused when the end user is not authorized to access their accounts due to security reasons. | | [977](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#977) | Maximum Limit Exceeded | The number of requests to a particular financial institution exceeds the set rate limit. | | [978](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#978) | Unsupported Product | This error can occur when the operation you are attempting to perform or the data you are trying to access is not available within the scope of your current contract with Mastercard. | | [991](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Unexpected System Error | An error occurred in our internal system. | | [1007](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#1007) | Empty Date Range | No transactions found within the specified date range during transaction aggregation. | | [2001](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2001) [2003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2003) [2006](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2006) [2017](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2017) [2024](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2024) [2026](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2026) [2028](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2028) [2030](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2030) [2031](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2031) [2035](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2035) [2036](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2036) [2037](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2037) [2038](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2038) [12005](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#12005) | Consent Authorization | Occurs when the end user consent authorization is not available. ​ | | [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) [24303](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#24303) | Invalid Credentials | Occurs when the end user credentials are invalid. | | [324](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/324/index.md) [910](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#910) [418](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#418-and-419) [419](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#418-and-419) [907](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#907) [970](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#970) | Account Update Failed | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action.​ For already added accounts this means that the customer's account information has changed at the financial institution. | | [102](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#102) | Connection Interrupted | The bank may have updated its website or server. These changes can disrupt the connection between your app and the bank, requiring changes/updates to restore the original connection. | | [179](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md#179) [1008](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md#1008) [2040](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md#2040) | Unexpected Login Error | Occurs when the financial institution website returns an unexpected login error. | | [130](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [147](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [148](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [170](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [173](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [176](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [181](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [190](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) [417](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#417) [900](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#900) [901](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#901) [903](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#903) [904](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#904) [906](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#906) [907](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#907) [950](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#950) [973](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#973) [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Additional Support Required | Submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | --- # Generating an API Client Library source: https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/generating-an-api-client-library/index.md Once you have explored the APIs and are ready to consume the Open Finance APIs directly from your application code, you can speed things up by leveraging the API specification to generate a client library. This approach provides type-safe API calls and reduces the amount of boilerplate code you need to write. View on GitHub ## Prerequisites {#prerequisites} Before generating a client library, you should: 1. [Generate your credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) (Partner ID, Partner Secret, and App Key) 2. Install [OpenAPI Generator](https://openapi-generator.tech/docs/installation) ## Generate the Client Library {#generate-the-client-library} 1. Download [openbanking-us.yaml](https://static.developer.mastercard.com/content/open-finance-us/swagger/openbanking-us.yaml) (1MB) 2. Generate an Open Finance API client library using [OpenAPI Generator](https://openapi-generator.tech/docs/installation) and the development framework of your choice (see also: [Generators List](https://openapi-generator.tech/docs/generators/)): * Java * C# * Javascript * Python ```sh openapi-generator-cli generate -g java -i *.yaml -o api_client ``` ```sh openapi-generator-cli generate -g csharp-netcore -i *.yaml -o api_client ``` ```sh openapi-generator-cli generate -g javascript -i *.yaml -o api_client ``` ```sh openapi-generator-cli generate -g python -i *.yaml -o api_client ``` ## Adding Authentication {#adding-authentication} Add some code to automatically attach the `Finicity-App-Token` and `Finicity-App-Key` HTTP headers to requests (see example [here](https://github.com/Mastercard/open-banking-us-openapi/blob/main/tests/src/test/java/com/mastercard/openbanking/client/test/OpenBankingAuthInterceptor.java#L16)): * Java * C# * Javascript * Python ```java // An example of okHttp3 interceptor handling Mastercard Open Finance authentication. public class OpenBankingAuthInterceptor implements Interceptor { private final AuthenticationApi authenticationApi; private final String partnerId; private final String partnerSecret; private final String appKey; private String token; private LocalDateTime tokenExpiryTime; public OpenBankingAuthInterceptor(String partnerId, String partnerSecret, String appKey) { this.partnerId = partnerId; this.partnerSecret = partnerSecret; this.appKey = appKey; this.authenticationApi = new AuthenticationApi(); } @NotNull public Response intercept(@NotNull Chain chain) throws IOException { try { // Always add "Finicity-App-Key" var request = chain.request(); var requestBuilder = request .newBuilder() .addHeader("Finicity-App-Key", this.appKey); var url = request.url().toString(); if (url.contains("/authentication")) { // No "Finicity-App-Token" header needed for /authentication return chain.proceed(requestBuilder.build()); } if (this.tokenExpiryTime == null || this.tokenExpiryTime.isBefore(LocalDateTime.now())) { this.refreshToken(); } // Add access token to the "Finicity-App-Token" header requestBuilder = requestBuilder .addHeader("Finicity-App-Token", this.token); return chain.proceed(requestBuilder.build()); } catch (Exception e) { throw new IOException(e.getMessage()); } } private void refreshToken() throws ApiException { this.token = createToken(); this.tokenExpiryTime = LocalDateTime.now().plusMinutes(90); } private String createToken() throws ApiException { return authenticationApi.createToken(new PartnerCredentials() .partnerId(partnerId) .partnerSecret(partnerSecret)).getToken(); } } ``` ```csharp // Create a FinicityApiClient.cs file that extends the partial ApiClient from ApiClient.cs namespace Org.OpenAPITools.Client { public partial class ApiClient { private readonly string _partnerId; private readonly string _partnerSecret; private readonly string _appKey; private string _token; private DateTime _tokenExpiryTime; public ApiClient(string partnerId, string partnerSecret, string appKey) { _baseUrl = GlobalConfiguration.Instance.BasePath; _appKey = appKey; _partnerId = partnerId; _partnerSecret = partnerSecret; } partial void InterceptRequest(IRestRequest request) { // Always add "Finicity-App-Key" request.AddHeader("Finicity-App-Key", _appKey); var url = request.Resource; if (url.Contains("/authentication")) { // No "Finicity-App-Token" header needed for /authentication return; } if (_tokenExpiryTime < DateTime.Now) { RefreshToken(); } // Add access token to the "Finicity-App-Token" header request.AddHeader("Finicity-App-Token", _token); } private void RefreshToken() { _token = CreateToken(); _tokenExpiryTime = DateTime.Now.AddMinutes(90); } private string CreateToken() { var credentials = new PartnerCredentials(_partnerId, _partnerSecret); var authenticationApi = new AuthenticationApi { Client = this }; return authenticationApi.CreateToken(credentials).Token; } } } ``` ```javascript // Credentials const PARTNER_ID = "{{partnerId}}" const PARTNER_SECRET = "{{partnerSecret}}" const APP_KEY = "{{appKey}}" // Token let expiry = null let token = null // Create the API client const createClient = function (openAPIClient) { // Use a promise to ensure the token has been added before sending the request return new Promise((resolve) => { let client = openAPIClient.ApiClient.instance; let authApi = new AuthenticationApi(client) // Add the Finicity-App-Key header for every request client.applyAuthToRequest = function (request) { const _end = request._end; request._end = function () { request.req.setHeader('Finicity-App-Key', APP_KEY); _end.call(request); }; return request; }; // If the token doesn't exist or has expired, refresh it let tokenPromise = function refreshToken() { return new Promise((resolve) => { if (expiry === null || expiry < new Date()) { authApi.createToken(new PartnerCredentials(PARTNER_ID, PARTNER_SECRET), (error, data, response) => { if (!error) { expiry = new Date(); token = data.token; resolve(); } }); } else { resolve() } }) } // Apply the token to the request headers tokenPromise().then(() => { client.applyAuthToRequest = function (request) { const _end = request._end; request._end = function () { request.req.setHeader('Finicity-App-Key', APP_KEY); request.req.setHeader('Finicity-App-Token', token); _end.call(request); }; return request; }; resolve(client); }) }) }; ``` ```python import datetime from functools import wraps import openapi_client from openapi_client.api.authentication_api import AuthenticationApi from openapi_client.api.connect_api import ConnectApi from openapi_client.models.connect_parameters import ConnectParameters class ApiClient(object): # Credentials partner_id = "{{partnerId}}" partner_secret = "{{partnerSecret}}" app_key = "{{appKey}}" # API Client api_client = None # Token details token = None expiry = None @classmethod def __init__(self): conf = openapi_client.Configuration() conf.verify_ssl = False conf.ssl_ca_cert = None conf.assert_hostname = False conf.cert_file = None api_client = openapi_client.ApiClient(conf) self.add_authentication(self=self, api_client=api_client) self.api_client = api_client def add_authentication(self, api_client): api_client.rest_client.request = self.authenticate(self, api_client.rest_client.request) def authenticate(self, func): @wraps(func) def call_api_function(*args, **kwargs): kwargs['headers']['Finicity-App-Key'] = self.app_key if self.expiry is None or self.expiry < datetime.datetime.now(): self.refresh_token(self) kwargs['headers']['Finicity-App-Token'] = self.token return func(*args, **kwargs) return call_api_function def refresh_token(self): current_date = datetime.datetime.now() expiry_date = current_date + datetime.timedelta(minutes=90) self.expiry = expiry_date request_body = { 'partner_id': self.partner_id, 'partner_secret': self.partner_secret } auth_response = AuthenticationApi(self.api_client).create_token(partner_credentials=request_body) self.token = auth_response.token ```
## Using the Client Library {#using-the-client-library} Configure your `ApiClient` instance and use one of the `*Api` classes (see example [here](https://github.com/Mastercard/open-banking-us-openapi/blob/main/tests/src/test/java/com/mastercard/openbanking/client/test/BaseTest.java#L44)): * Java * C# * Javascript * Python ```java var apiClient = Configuration.getDefaultApiClient(); apiClient.setDebugging(true); apiClient.setConnectTimeout(240000); apiClient.setReadTimeout(240000); apiClient.setHttpClient( apiClient.getHttpClient() .newBuilder() .addInterceptor(new FinicityAuthInterceptor("{{partnerId}}", "{{partnerSecret}}", "{{appKey}}")) .build()); // Generate a Data Connect URL var api = new ConnectApi(apiClient); var params = new ConnectParameters() .customerId(CUSTOMER_ID) .partnerId(PARTNER_ID); var connectUrl = api.generateConnectUrl(params); var link = connectUrl.getLink(); ``` ```csharp var apiClient = new ApiClient("{{partnerId}}", "{{partnerSecret}}", "{{appKey}}"); // Generate a Data Connect URL var connectApi = new ConnectApi { Client = apiClient }; var connectParameters = new ConnectParameters(PartnerId, CustomerId); var connectUrl = connectApi.GenerateConnectUrl(connectParameters); var link = connectUrl.Link; ``` ```javascript let client = await createClient(OpenAPIClient); // Generate a Data Connect URL let connectApi = new ConnectApi(client) let connectParameters = new ConnectParameters(CUSTOMER_ID, PARTNER_ID) let connectResponse api.generateConnectUrl(connectParameters, (error, data, response) => { connectResponse = response done(); }); done(); ``` ```python customer_id = "{{customerId}}" api_client = ApiClient() connect_parameters = ConnectParameters( partner_id=api_client.partner_id, customer_id=customer_id) # Generate a Data Connect URL response = ConnectApi(api_client.api_client).generate_connect_url(connect_parameters=connect_parameters) print("Data Connect URL: ", response.link) ```
You are now ready to use Mastercard Open Finance in your application. ![Data Connect URL from IntelliJ](https://static.developer.mastercard.com/content/open-finance-us/uploads/intellij-test.png) ## See Also {#see-also} * [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) * [Using the Postman Collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) * [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) * [API Reference](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) --- # Using the Postman Collection source: https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md The Mastercard Open Finance Postman collection provides a quick and convenient way to explore and test the Open Finance APIs. You can use it to try out API calls, inspect responses, and generate code snippets for your application. View on GitHub ## Prerequisites {#prerequisites} Before using the Postman collection, you should: 1. [Generate your credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) (Partner ID, Partner Secret, and App Key) 2. [Create a test customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) ## Getting Started {#getting-started} 1. Click Run in Postman 2. Fork the collection so that you can try it online (you can also choose to import a copy of the collection if you have the Postman client application set up already). 3. Select the *Test Drive* environment (top right) and update the `partnerId`, `partnerSecret`, `appKey` and `customerId` variables. 4. Click **Send** on individual requests, or **Run collection** 5. Explore the **Pre-request Script* and *Tests** tabs, and update the collection as you wish 6. Generate [code snippets](https://learning.postman.com/docs/sending-requests/generate-code-snippets/) you can use in your application ![Postman workspace](https://static.developer.mastercard.com/content/open-finance-us/uploads/postman-request.png) ## See Also {#see-also} * [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) * [Generating an API Client Library](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/generating-an-api-client-library/index.md) * [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) * [API Reference](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) --- # Accessibility Guidelines source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/accessibility-guidelines/index.md Mastercard firmly believes that app and web experiences should be accessible for everyone. Mastercard's design system is committed to following and complying with accessibility best practices.
## Why It Matters {#why-it-matters} * Accessibility is about designing and developing digital experiences that meet the varying needs of individuals, organizations, and governments internationally. This section combines information from **Web Content Accessibility Guidelines (WCAG)** and the **A11y Project**. * One billion people (15% of the population) experience some form of disability * Seeing: Visual impairments (covers 80% of accessibility issues) * Hearing: Auditory impairments * Interacting: Motor impairments * Learning: Cognitive impairments * Vestibular disorders and seizures: Balance impairments ## Why We Care {#why-we-care} We need to make it easy for **everyone** to do business with Mastercard. * Accessibility is part of compliance---it is a legal requirement in many regions of the world * Accessibility is part of our addressable market---one in seven of our potential customers has some form of disability * Accessibility demand is increasing---companies are increasingly asking for or including accessibility compliance into contracts with Mastercard
## Expectations for Accessibility Compliance {#expectations-for-accessibility-compliance} As Mastercard moves toward accessibility compliance, we are working with internal teams and an external third-party expert to understand our current state. All Open Finance US product components comply with [WCAG 2.1, Level AA.](https://www.w3.org/TR/WCAG21/) * Keyboard accessibility * Proper color contrast ratios (4.5:1) * Alt tags for images implemented * Defined navigation and heading structures * Accessibility-coded data (and layout) tables * Proper field labels * Accessible dynamic content handling * Skip to the main content function Achieving compliance requires everyone working together in designing, developing and testing. Look at the ways that we are compliant. We strongly suggest that you follow the guidelines provided by WCAG 2.1.
## Color Contrast {#color-contrast} ### Color {#color} s Mastercard components are designed to comply with WCAG 2.1, Level AA accessibility standards. When using our components to create white label products, designers still need to exercise due diligence to ensure that the components are used correctly along with color contrast minimum requirements.
#### What Color Contrast Standards Do We Follow? {#what-color-contrast-standards-do-we-follow} Success Criterion 1.4.3: Contrast (Minimum) Level AA [source link](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) The visual presentation of text and images of text has a contrast ratio of **at least 4.5:1**, except for the following: * **Large text**: The contrast ratio for large-scale text and images of large-scale text is at least 3:1. * **Incidental**: There is no contrast requirement for text or images of text when they are: part of an inactive user interface component, purely aesthetic, not visible to anyone, or are part of an image that contains significant other visual content. * **Logotypes** : There is also no contrast requirement for text that is part of a logo or brand name. ### How Do We Test for Color Contrast? {#how-do-we-test-for-color-contrast} From a design perspective, we use a plugin within Figma called Contrast that checks the color contrast ratios of text and graphics. [Link to plugin](https://www.figma.com/community/plugin/748533339900865323/contrast) ![Why test](https://static.developer.mastercard.com/content/open-finance-us/uploads/contrast_img_11.png) ![Why test](https://static.developer.mastercard.com/content/open-finance-us/uploads/contrast_img_12.png) ## Keyboard {#keyboard} ### Keyboard Accessibility {#keyboard-accessibility} **Common keyboard interactions** include using the **tab key** to select different interactive elements on a page and using the **enter key** or the **spacebar** to activate an in-focus element. Use the [WCAG](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) guidelines to make your user experience more accessible.
### Focus Indicators {#focus-indicators} The tab key navigates through all interactive elements on a page in the order they appear in the HTML document. A default visual indicator is provided by the web browser in use. The display is a border around the focused element. When an element is in focus, it can be further activated using the keyboard. ## Modals and SDKs {#modals-and-sdks} A modal, or modal dialog, is an overlay window that opens on top of the current primary content or screen. It places focus on itself, usually making the background inactive ("inert") --- in other words, visually grayed out or dimmed. It can be dismissed by using a close or X button, by tapping away from the on-focus area, or by pressing an appropriate "cancel" CTA. ![Why test](https://static.developer.mastercard.com/content/open-finance-us/uploads/modals_img.png) ### Why Are Modal Interactions Typically Inaccessible? {#why-are-modal-interactions-typically-inaccessible} Modal interactions are often considered inaccessible. The most common issues are: * Poor communication of intention (semantics) for assistive technologies - is it a dialog or just another paragraph? * Improper handling of focus control, allowing the user to access content intended to be blocked. * Dialogs are not announced to assistive technologies. * Unclear indication of which content is blocked from interaction. * Insufficient contrast between the dialog container and the outlying content. For example, a faded background or alpha channel blending may not be sufficient contrast (see [WCAG 2.1 Contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)). Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) --- # Data Connect Enhancements and Features source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/index.md Mastercard Data Connect has features to enhance the user experience and drive increased conversions from its robust app-to-app connectivity. These features enable seamless data exchange, allowing applications to communicate effortlessly and offering a unified user journey. Using financial institution search best practices can significantly enhance conversion rates for Data Connect by: * Emphasizing financial institution branding importance * Optimizing dead-end search queries * Offering relevant, clear content for guidance By offering efficient navigation and user-friendly interfaces, Data Connect leverages search optimization to foster customer satisfaction, drive higher conversions, and ensure sustained product growth. The following sections describe best practices and user experiences for supporting app to app authentication (so the customer can authenticate with their FI's app then return seamlessly to your app), building a user-friendly Financial Institution search and enhancing convenience for returning users: [View best practices for App to App](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/app-to-app-auth-best-practices/index.md) [View best practices for Financial Institution Search](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/fi-search-experience/index.md) [View best practices for the Returning User Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/returning-user-experience/index.md) Note: For developers, here is the API documentation: [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) Tip: If you have questions or need assistance with your customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [App to app authentication best practices](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/app-to-app-auth-best-practices/index.md) --- # Small Business Solutions source: https://developer.mastercard.com/open-finance-us/documentation/usecases/small-business-solutions/index.md Leverage real-time business account data, Cash Flow Analytics, and predictive insights to seamlessly onboard and underwrite small business (SMB) customers. ## How It Works {#how-it-works} These solutions are designed for organizations that work directly with small businesses or provide services to companies that do. They support a variety of use cases, primarily onboarding, credit/fraud risk, and business financial management. * For most use cases, you will first need to generate a URL to launch the [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) application, which allows businesses to link their accounts and give you permission to access their financial data through Mastercard Open Finance. Data Connect is the only way for your customers to link their accounts and is mandatory for integrating with any Mastercard Open Finance APIs. * [Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) enable your app to receive notifications about Data Connect events and report generation progress.
The sections below illustrate common ways different types of organizations use Mastercard Open Finance APIs for small business use cases and are not intended to be exhaustive or limiting. ## Issuers {#issuers} Issuer use cases often involve analyzing cash flows, transaction activity, and historical balances (with a small business's consent) to assess creditworthiness and predict the likelihood of future payment risk. Below are examples of products commonly used by small business issuers to access consolidated, owner-permissioned financial data across linked business accounts. These APIs are modular and can be used independently or in combination with each other: * [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) confirms that the individual attempting onboarding is an owner or authorized signer on the business account. * [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) confirms routing and account numbers and helps open/fund accounts after the account owner's identity and the account have been verified. * [Payment Risk Insights](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) provides a risk score that can be used to determine the probability that a business will experience a payment risk event in the near future when making a payment. * [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md) provides the ability for businesses to switch their recurring automatic payments from their incumbent account into a new/existing account at a Financial Institution. * [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) confirms a business's revenue using up to 24 months of its bank transaction data. * [Small Business Credit Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) provides access to near real-time transaction-based insights to build a more complete view of business performance and creditworthiness. ### Example Scenario {#example-scenario} This sequence diagram shows how you could combine the products above for a small business credit card issuance use case. Diagram sb-usecase-1 ## Merchant Service Providers {#merchant-service-providers} After a small business consents to share account data, cash flows, transaction activity, and historical balances, this information can be analyzed to assess onboarding risk, funding reliability, and the likelihood that payments will succeed. The APIs listed below are examples of products commonly used by merchant service providers (MSPs) to access consolidated, owner-permissioned financial data across linked business accounts. These APIs are modular and can be used independently or in combination with each other: * [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) confirms that the individual attempting onboarding is an owner or authorized signer on the business account. * [Account ACH Details with RTP/FedNow](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) collects and verifies the business's accounts and routing numbers. * [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) verifies the current account balance(s) of the business. * [Transaction Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) provides transaction details for each transaction associated with a connected account. * [Cash Flow Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/cash-flow-analytics-sb/index.md) surfaces cash-flow health and trends to assess a business's capacity to pay and volatility. * [Payment Risk Insights](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) provides a risk score that can be used to determine the probability that a business will experience a payment risk event in the near future when making a payment. * [Small Business Credit Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) provides access to near real-time transaction-based insights to build a more complete view of business performance and creditworthiness. ### Example Scenario {#example-scenario-1} This sequence diagram shows how you could combine the products above for an MSP decisioning use case. Diagram sb-usecase-2 ## Next Steps {#next-steps} ![Quick Start Guide](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_quickstart.png) ### Quick Start Guide {#quick-start-guide} Get started with using Mastercard Open Finance APIs in less than 30 minutes.

[Get Started →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) ![API Reference](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_apireference.png) ### API Reference {#api-reference} Find detailed explanation of all resources available through Mastercard Open Finance API.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) ![Postman](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_postman.png) ### Postman {#postman} Run the Postman Collection to start using Open Finance API without the need to write any code.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) --- # Open Banking Webhook Management System (OBWMS) source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md Webhooks allow you to receive real-time notifications when specific events occur, eliminating the need for constant polling. They are ideal for staying informed about customer activity, transaction updates, and other time-sensitive events. * [Overview of OBWMS](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#overview-of-obwms) * [Getting Started](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#getting-started) * [Webhook Structure](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#webhook-structure) * [Message Verification](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#message-verification) * [Delivery Considerations](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#delivery-considerations) ## Overview of OBWMS {#overview-of-obwms} The Open Banking Webhook Management System (OBWMS) is a new standard for managing webhook subscriptions in Mastercard Open Finance. It provides a unified, consistent approach to creating and managing webhook subscriptions. Over time, all Mastercard Open Finance webhooks will conform to this standard. Currently, only a subset of webhooks use OBWMS. OBWMS will provide a comprehensive API for managing real-time event notifications, enabling you to subscribe to specific events, ensuring you only receive relevant updates. Warning: The endpoints for subscribing to and testing webhooks via OBWMS are being developed as a standalone service, not tied to US Open Finance. Documentation for these endpoints will be provided soon. In the meantime, the information presented here is meant to provide an overview of how OBWMS subscriptions work. For details of the specific events that are available for subscription, refer to the documentation for each Open Finance product that uses OBWMS. ## Getting Started {#getting-started} ### Obtaining a Mastercard Signature Verification Key {#obtaining-a-mastercard-signature-verification-key} Before creating webhook subscriptions, you need to ensure you have added a **Mastercard signature verification key** to your project in your project dashboard on Mastercard Developers. This key is required to authenticate and validate webhook messages. See the [API Basics](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) documentation for more details of how to create all the necessary credentials and [keys](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#obwms-authentication) when working with your project. If you don't have a Mastercard signature verification key, make sure you add one and download it. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/create-sig-key-obwms-openfinance.png) ### Setting up a Listener {#setting-up-a-listener} To receive OBWMS webhook events, you must provide an HTTPS endpoint capable of accepting **HTTP POST** requests. Your listener should be lightweight, resilient, and able to acknowledge receipt quickly. You pass this endpoint URL when creating a webhook subscription. Tip: For testing purposes, you can use tools like webhook.site or beeceptor.com that receive webhooks and post the content for you to review (note that this is not an official endorsement of any of these services). In production, you **must** use your own secure webhook service. #### Listener Best Practices {#listener-best-practices} * **Respond immediately with a 2xx status** Your endpoint should return HTTP 200 or 204 immediately upon receipt, before performing signature verification or other processing. Responding early ensures OBWMS does not retry unnecessarily. * **Avoid detailed error responses** If the payload is malformed or unexpected, log the issue internally but do not return detailed error information. * **Avoid redirects** Any 3xx response (including 307 or 308) is treated as a failure and retried. Ensure the listener URL resolves directly to an endpoint that can process the webhook. * [Additional Tips and Best Practices for Receiving Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#additional-tips-and-best-practices-for-receiving-webhooks) ### Creating a Subscription {#creating-a-subscription} To receive webhook events, you must create a subscription, in which you specify the details of the events they would like to receive and the endpoint it should be sent to. A new subscription API is currently under development. For subscription support, please reach out to your account representative. ## Webhook Structure {#webhook-structure} ### Message Headers {#message-headers} OBWMS event messages include the following message headers: **Content-Type:** Indicates the format of the data within the webhook body. This is always set to "application/json". **X-Mastercard-Signature:** This header contains a unique hash of the webhook payload. Uniqueness is provided by combining the message payload with the timestamp of signature generation. See [Verifying the Message Signature](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md#verifying-the-message-signature) for more information. **X-Mastercard-Signature-Timestamp:** This header indicates the time, in milliseconds, of when the signature was calculated. This is used to help prevent replay attacks. **X-Mastercard-Signature-Algorithm:** This header indicates the hashing algorithm used for generating the message hash for the webhook. Currently, this service only supports "SHA256withECDSA." **X-Mastercard-Signature-Version:** This header indicates which version to use when calculating the message signature. This header is provided for forward-compatibility as new algorithms are added. **X-Mastercard-Webhook-Message-Id:** A unique identifier (UUID) for each webhook event/message. This identifier remains the same across retry attempts, allowing consumers to reliably detect and handle duplicate deliveries. **X-Mastercard-Signature-Verification-Key:** The unique fingerprint of the signature key used when calculating the value of the X-Mastercard-Signature header. If multiple signing keys have been registered for use within the webhook system, this header is essential for determining which signing key is being used. Tip: When received, HTTP headers may be presented as lowercase strings. The above documentation is capitalized for readability. ### Message Body {#message-body} The body of the webhook event contains the data generated by the webhook, as a string. The receiving application is responsible for reading the Content-Type HTTP header and parsing the webhook data accordingly. Each webhook event type contains its own unique structure. Consult the documentation for the desired webhook event for more information regarding its particular structure. The webhook structure is based on the CloudEvents 1.0 specification. When receiving a webhook, you can expect these standard fields to be provided at the beginning of each webhook message: | Event field | Type | Description | |-------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | string | Identifies the event. This is unique for each distinct event. If an event with the same ID is received, you can assume it is a duplicate (for example, an event could potentially be re-sent because of a network issue). | | `time` | RFC 3339 | Timestamp of the event. | | `type` | string | The type of event. | | `source` | string | This is the Mastercard OBWMS, which is `openfinance.mastercard`. | | `specversion` | string | The CloudEvents specification version that the message complies with. | | `datacontenttype` | application/json | Media type for the event payload. | | `subscriberid` | string | The ID of the partner subscribing to the event (in other words, your partner ID). | | `correlationid` | string | An optional attribute for correlating this event with related events, requests, or workflows. This can be useful for end-to-end tracing, business process correlation, or tracking request lineage. | | `data` | object | The event payload. The format is defined by the `datacontenttype`. | Individual services provide their own specific message data relating to the particular event concerned via the `data` object. ## Message Verification {#message-verification} Several steps should be taken when verifying webhooks received. Firstly, the `X-Mastercard-Webhook-Message-Id` header may be checked against a list of previously received webhooks to guard against replay attacks. ### Verifying the Message Signature {#verifying-the-message-signature} To verify the identity of the sender (Mastercard), it is important that the receiving application perform a hashing of the webhook body, concatenated with the value of `X-Mastercard-Signature-Timestamp`, and comparing it to the value of `X-Mastercard-Signature`. The value of `X-Mastercard-Signature-Algorithm` indicates which algorithm to use when generating the message hash. In pseudo-code, this can be expressed as: messageHash = hashingFunction(webhook-message + "." + webhook-timestamp) The default signature verification key is generated using SHA256 with ECDSA and the public key can be downloaded via the Mastercard Developer Portal. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/view-sig-key-openfinance.png) With that information, the following code snippet is an example of how message verification may be performed. ```js // Nodejs const crypto = require('node:crypto'); const HASH_ALGORITHM = 'sha256'; // Loaded at startup, or selected based on X-Mastercard-Signature-Verification-Key header const PUBLIC_KEY = process.env.PUBLIC_KEY; /** * @param {string} signature - Provided via X-Mastercard-Signature header * @param {string} webhookMessage - Webhook body * @param {number} timestamp - Provided via X-Mastercard-Signature-Timestamp * @returns {boolean} */ function isValidWebhook(signature, webhookMessage, timestamp) { const verify = crypto.createVerify(HASH_ALGORITHM); verify.write(`${webhookMessage}.${timestamp}`); verify.end(); return verify.verify(PUBLIC_KEY, signature, 'hex'); } ``` ### Verifying Timestamps {#verifying-timestamps} The threshold for valid timestamps is determined by the receiving application. To mitigate replay attacks, you should validate webhook timestamps and discard those with unreasonably old timestamps. ## Delivery Considerations {#delivery-considerations} All webhook requests are sent using HTTP POST. The application receiving the webhook is expected to respond within 30 seconds with an HTTP 200 or 204 to indicate successful receipt of the webhook. All other HTTP status codes are considered errors and the message is re-queued for delivery. Importantly, any status code indicating a redirection (for example, HTTP 307 or 308) is rejected and re-queued. ### Message Retry {#message-retry} Failed messages are retried over a 24-hour period using an exponential backoff. The following table describes the retry intervals under near ideal conditions, that is, no network latency and optimal webhook service settings. | Retry Delivery Attempt | Next attempt after | Interval until next attempt | |------------------------|--------------------|-----------------------------| | 1 | 6 seconds | 42 seconds | | 2 | 48 seconds | 4 minutes 30 seconds | | 3 | 5 minutes | 29 minutes 8 seconds | | 4 | 34 minutes | 3 hours 8 seconds | | 5 | 3 hours 42 minutes | 20 hours 17 seconds | | 6 | 24 hours | - | ### Additional Tips and Best Practices for Receiving Webhooks {#additional-tips-and-best-practices-for-receiving-webhooks} #### Close Connections Early {#close-connections-early} Webhooks can create spikes in HTTP calls to receiving applications. If not handled properly, these spikes can exhaust available TCP sockets, creating bottlenecks on the network. We recommended that the receiving application respond to the webhook message (with an HTTP 200, 202, or 204 response) *immediately upon receipt*, before any processing is performed on the webhook payload (this includes signature validation). #### Fail Silently {#fail-silently} A key in reducing abuse to endpoints exposed for webhooks is to remove any unnecessary response information. In the case of webhooks, the sender only needs to know if the payload was received, not if the data was processable. Returning status codes such as HTTP 400 when a webhook does not follow an expected format does not provide any actionable information to legitimate webhook senders but allows a potential attacker to further refine their attacks. Any errors, such as unexpected payloads, should be logged but not returned on endpoints designed to receive webhooks. In cases where the receiving application is under heavy load and cannot process more requests, it is advised that the application return a 4xx error code, such as HTTP 429 Too Many Requests, which causes the webhook sender to reschedule the webhook for a later time. See the above chart for information regarding the retry intervals. #### Queue Messages Internally {#queue-messages-internally} In cases where a large volume of webhooks is expected, it may be desirable to queue received messages for process using something like RabbitMQ. This can reduce the chance of webhooks failing to be received as servers become congested with webhook traffic. If queueing is to be used, it is advised that all webhook messages are verified before being placed into the queue to prevent invalid or malicious webhook payloads accidentally being processed. #### Check for Expected Algorithms {#check-for-expected-algorithms} The information provided via the webhook headers should be treated as informational only. Information such as the algorithm being used should be compared against an expected list prior to processing the webhook and should never be used directly. ```js // Bad const verify = crypto.createVerify(headers['X-Mastercard-Signature-Algorithm']); // Good if (headers['X-Mastercard-Signature-Algorithm'] === 'SHA256withECDSA') { const verify = crypto.createVerify('SHA256withECDSA'); } ``` --- # Small Business source: https://developer.mastercard.com/open-finance-us/documentation/products/small-business/index.md Mastercard Open Finance's Small Business services provide support for credit decisioning when lending to businesses. ## Services {#services} * [Small Business Credit Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md) --- provides transaction-based metrics for a specified merchant location * [Payment Risk Insights (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) --- provides a risk score for a business based on payment history of connected accounts * [Cash Flow Analytics (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/cash-flow-analytics-sb/index.md) --- analyzes credits and debits in connected accounts to surface cash-flow health and trends for a business --- # Test Profiles source: https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md On this page, you will learn how to use our test banks (FinBanks) and test payroll provider (FinPayroll). You will get access to a wide variety of profiles and data to test different types of use case scenarios. Test profiles are enabled by starting a Mastercard Data Connect (Connect) session and by logging in with specific customer credentials. To understand how to create customers and Data Connect URLs, we recommend you read the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) first. We provide the following personas and profiles: * [Test Personas](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#test-personas) * [Sign-in Authentication Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#sign-in-authentication-profiles) * [Bank Account Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) * [Balance Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#balance-profiles) * [OAuth Connection Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles) * [Payroll Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles) * [Paystub Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#paystub-profiles) * [MVS Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#mvs-profiles) * [Account Opening Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#account-opening-profiles) * [Payment Risk Insights Report Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profiles) * [Payment Success Indicator Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-success-indicator-profiles) * [Transactions Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#transactions-profiles) ## Test Personas {#test-personas} When developing an Open Finance application, it is important to test your API integration with different types of users. This will help you ensure that your app works well for various scenarios and meets the needs and expectations of your target audience. To facilitate your testing process, we provide you with a set of testing personas. Each persona represents an example of a user who might use your app. These personas have different levels of income, access to different banking products, and realistic data. You can use these personas to simulate different user journeys and interactions with your app. For example, you can test how your app handles authentication, consent, data sharing, payments, and other features. You can also compare the results and feedback from different personas to identify any issues or areas for improvement. Below you will see five test personas. You can use these personas through the [Mastercard Data Connect Application](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) to grant permission to access their accounts by following these steps: 1. Create a test customer. 2. Create and open a Data Connect URL. 3. Click **Next** to agree to the Terms and Conditions, and Privacy Policy. 4. Search for the bank specified for each test persona below (for example, **FinBank Profiles A**). 5. When asked for a username and password, use the username and password for each persona as shown below.
You can use **FinBank Profiles -- A** or **FinBank Profiles -- B** . Both function the same. This enables you to test scenarios where a customer has accounts located at different banks. For example, they could have their checking account at **FinBank Profiles A** and their savings account at **FinBank Profiles B**. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-persona-sue-wealthy.png) Sue is working as a Product Manager with a good steady income, a mortgage, and multiple investment accounts. She has a loan account and leases a car. Sue travels a few times a year. She has typical expenses like groceries, clothes, entertainment, gym membership, car expenses, and she has a pet. | Username | Password | Bank | |-------------|-------------|---------------------------------------| | sue_wealthy | profile_700 | FinBank Profiles A FinBank Profiles B | ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-persona-francis-business.png) Francis runs a successful medium-sized local restaurant. The restaurant is turning a profit after all its expenses. The restaurant has multiple checking accounts needed to run the business with revenue from in-store sales as well as online services like DoorDash. Additionally, the restaurant has some loan accounts to cover purchases that Francis has made for new or replacement equipment. | Username | Password | Bank | |------------------|-------------|---------------------------------------| | francis_business | profile_701 | FinBank Profiles A FinBank Profiles B | ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-persona-joe-gig.png) Joe is a Creative Designer, Photographer and Video Editor. He works on a range of short and longer term contracts and does not have a steady consistent income. He gets paid for each job via Zelle. Joe does not have a mortgage, he rents instead. He has typical expenses like groceries, clothes, entertainment, household, and car expenses. He has some savings and no investments. | Username | Password | Bank | |----------|-------------|---------------------------------------| | joe_gig | profile_702 | FinBank Profiles A FinBank Profiles B | ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-persona-river-paycheck.png) River works in construction. He rents an apartment and has typical expenses like groceries, clothes, entertainment, household and car expenses. He has some savings but no investments, no loans and no credit cards. In some months, River's expenses exceed his income. | Username | Password | Bank | |----------------|-------------|---------------------------------------| | river_paycheck | profile_703 | FinBank Profiles A FinBank Profiles B | ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-persona-alex-student.png) Alex is working full-time with a good salary but she is still paying off her student loan. She makes regular monthly repayments, but she still has over $30,000 to pay off. Alex has typical expenses like groceries, clothes, entertainment, household, and car expenses. She has limited savings and she has started an investment account. | Username | Password | Bank | |--------------|-------------|---------------------------------------| | alex_student | profile_704 | FinBank Profiles A FinBank Profiles B | ## Sign-In Authentication Profiles {#sign-in-authentication-profiles} Use these profiles to test different authentication and error scenarios when adding customer accounts. The discovery and activation responses can contain several different multi-factor authentication (MFA) challenge questions, depending on the customer's sign-in information. 1. Create a test customer. 2. Create and open a Data Connect URL. 3. Click **Next** to agree to the Terms and Conditions, and Privacy Policy. 4. Search for **Finbank**. 5. Select any bank. 6. When asked for a username and password, use user IDs and passwords from the table below. | Username | Password | MFA Type | Testing Details | |-----------------|---------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | demo | go | (none) | Success | | demo | Codes: 123,125,127, 128, or 130 | (none) | Service will fail with the error code given in the password. | | invalid_user | go | (none) | Returns Error 103: Invalid Credentials. | | tfa_text | go | Text-based MFA | If the answer to the MFA challenge is mfa, then the response is another MFA challenge. | | tfa_image | go | Image captcha | Any MFA answer is accepted. | | tfa_choice | go | Multiple text options | If the answer to the MFA challenge is fail, the call fails with code 187 (Invalid MFA). | | tfa_multi | go | Same as MFA with image choice (style 1) | Any MFA answer is accepted. | | demo | imagechoice | MFA with image choice (style 1) | Any MFA answer is accepted. | | demo | imagechoice2 | MFA with image choice (style 2) | Any MFA answer is accepted. | | discovertimeout | go | (none) | Calls to Add All Accounts and Discover Accounts will take more than 180 seconds, for testing the client app's asynchronous handling. | | activatetimeout | go | (none) | Calls to [Refresh Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) and [Load Historic Transactions for Customer Account](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#load-historic-transactions) take more than 180 seconds to test the app's asynchronous handling. | ## Bank Account Profiles {#bank-account-profiles} Bank account profiles consist of various combinations of account types, such as checking, savings, 401k, and more. You can use **FinBank Profiles -- A** or **FinBank Profiles -- B**. Both function the same, so this enables you to test scenarios where one customer has two accounts located at a different bank. 1. Create a test customer. 2. Create and open a Data Connect URL. 3. Click **Next** to agree to the Terms and Conditions, and Privacy Policy. 4. Search for FinBank **FinBank Profiles -- A** or **FinBank Profiles -- B**. 5. When asked for a username and password, use user IDs and passwords from the table below. Note about profiles: * Profiles 2-8 were created from real financial institution data, but without personal identification information (PII). * Profiles 2-9 are for general testing of our products. | Username | Password | Account Types | Supported Products | |----------|------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------| | Any | profile_02 | Savings, IRA, 401k, Credit Card | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_03 | Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners) | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_04 | Checking, 403B, 529, Rollover, Mortgage | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_05 | Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners) | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_06 | Checking, Retirement, KEOGH, 457, Credit Card | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_07 | Checking, Stocks, CD, Investment TaxDeferred, Employee Stock | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_08 | Checking, Primary Savings, Money Market, 401A, Line of credit | ach, aha, ao, state_agg, trans_agg, voa, voi | | Any | profile_09 | Checking, Savings, Checking Failed Report. Errors returned in the report include 102, 103, 185. | ach, ao, voa (failed report), voi (failed report) | ## Balance Profiles {#balance-profiles} Use these profiles to test the [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) service. Each profile returns a different account balance, including positive, negative, and small amounts, so you can verify how your application handles each scenario. 1. Create a test customer. 2. Create and open a Data Connect URL. 3. Click **Next** to agree to the Terms and Conditions, and Privacy Policy. 4. Search for the FI shown in the table below. 5. When asked for a username and password, use one of the username and password pairs from the table below.
To test how your application handles a balance retrieval failure, use the `tfa_multi` account and link the savings or checking account. | Username | Password | Balance\* | Financial Institution | |--------------|--------------|-------------------------------------------------|--------------------------------------------| | profile_1151 | profile_1151 | $4.90 | FinBank Profiles -- A | | profile_1153 | profile_1153 | ($33.97) | FinBank Profiles -- A | | profile_1154 | profile_1154 | $3,977.79 | FinBank Profiles -- A | | profile_1155 | profile_1155 | $915.64 | FinBank Profiles -- A | | tfa_multi | go | Failure (error 185 "MFA challenge encountered") | FinBank (link savings or checking account) | \*Brackets denote a negative balance. ## OAuth Connection Profiles {#oauth-connection-profiles} The profiles below are convenient to test OAuth connections between Finicity and financial institutions who have set up direct connections. You must register for **FinBank OAuth** to gain access to the OAuth Connection profiles. Contact your account manager to help you get registered. 1. Create a test customer. 2. Create and open a Data Connect URL. 3. Click **Next** to agree to the Terms and Conditions, and Privacy Policy. 4. Search for **FinBank OAuth**. 5. When asked for a username and password, use one of the userId and password values from the table below. | Username | Password | Account Types | Supported Products | |------------|------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------| | profile_02 | profile_02 | Savings, IRA, 401k, Credit Card | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_03 | profile_03 | Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners) | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_04 | profile_04 | Checking, 403B, 529, Rollover, Mortgage | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_05 | profile_05 | Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners) | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_06 | profile_06 | Checking, Retirement, KEOGH, 457, Credit Card | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_07 | profile_07 | Checking, Stocks, CD, Investment Tax-Deferred, Employee Stock | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_08 | profile_08 | Checking, Primary Savings, Money Market, 401A, Line of credit | ach, aha, ao, state_agg, trans_agg, voa, voi | | profile_09 | profile_09 | Checking, Savings, Checking Failed Report. Errors returned in the report include 102, 103, 185. | ach, ao, voa (failed report), voi (failed report) | ## Payroll Profiles {#payroll-profiles} Use these profiles to test products that contain payroll data. 1. Create a consumer with the SSN and DOB from the table below. 2. Launch the Data Connect experience. 3. For direct API payroll search experiences, enter the same SSN when prompted in the Data Connect experience. 4. For credentialed payroll login experiences, launch the credentialed payroll popup, search for the payroll provider you would like to test, and enter the payroll credentials below as prompted in the login experience. Note: If you are using an [active customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) in your testing, rather than a [test customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers), you should connect a payroll account through the **Platformtronic** test payroll provider. This guidance applies if you are using mortgage ecosystem platforms such as nCino or ICE for your testing. | Borrower Name | SSN / DOB (MM-DD-YYYY) | Description | Email / Payroll username | Payroll password / MFA | |--------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|------------------------| | Homer Loanseeker | 999601111 07-04-1970 | 1 active employment; salary, base | [homer_loanseeker@argyle.com](mailto:homer_loanseeker@argyle.com) homer_loanseeker | passgood 9081 | | Jess Sea | 999001147 07-05-1980 | 1 active employment; salary, base | [jess_sea@argyle.com](mailto:jess_sea@argyle.com) jess_sea | passgood 9082 | | Ann Sea | 999009066 07-06-1986 | 1 active employment; commission only | [ann_sea@argyle.com](mailto:ann_sea@argyle.com) ann_sea | passgood 9083 | | Suzi Builder | 999606666 07-07-1995 | 2 active employments; salary, base + overtime | [suzi_builder@argyle.com](mailto:suzi_builder@argyle.com) suzi_builder | passgood 9084 | | Alice Firstimer | 991919991 12-27-1992 | 1 active employment; salary, base + overtime | [alice_firsttimer@argyle.com](mailto:alice_firsttimer@argyle.com) alice_firsttimer | passgood 9085 | | Lorraine Purchaser | 999565678 05-02-1985 | 1 active employment; hourly, base | [lorraine_purchaser@argyle.com](mailto:lorraine_purchaser@argyle.com) lorraine_purchaser | passgood 9086 | | Patrick Purchaser | 999121234 09-09-1987 | 1 active employment; hourly, base | [patrick_purchaser@argyle.com](mailto:patrick_purchaser@argyle.com) patrick_purchaser | passgood 9087 | | Andy Freddie | 990300003 08-06-1990 | 1 active employment; salary, base + bonus + overtime + commissions, 1 terminated employment | [andy_freddie@argyle.com](mailto:andy_freddie@argyle.com) andy_freddie | passgood 9088 | | Dad Freddie | 991000010 08-02-1970 | 1 active employment; salary, base + bonus | [dad_freddie@argyle.com](mailto:dad_freddie@argyle.com) dad_freddie | passgood 9089 | | Patrick Freddie | 990500005 08-09-1980 | 1 active employment; base, semi-monthly, salary | [patrick_freddie@argyle.com](mailto:patrick_freddie@argyle.com) patrick_freddie | passgood 9090 | | Amy Freddie | 990400004 08-07-1980 | 1 active employment; base + bonus, bi-weekly, salary | [amy_freddie@argyle.com](mailto:amy_freddie@argyle.com) amy_freddie | passgood 9091 | | Suzi Freddie | 990700007 08-06-1990 | 2 active employments; base; semi-monthly, monthly | [suzi_freddie@argyle.com](mailto:suzi_freddie@argyle.com) suzi_freddie | passgood 9092 | | Mom Freddie | 990110011 08-04-1970 | 2 active employments; base + bonus + overtime + commissions, bi-weekly | [mom_freddie@argyle.com](mailto:mom_freddie@argyle.com) mom_freddie | passgood 9093 | | Alice Freddie | 990080008 08-05-1990 | 1 terminated employment; base, semi-monthly | [alice_freddie@argyle.com](mailto:alice_freddie@argyle.com) alice_freddie | passgood 9094 | | John Freddie | 990100001 08-01-1970 | 1 active employment w/ payroll; base + bonus + commission + overtime + weekly. Child support, military, VA benefits, alimony. Note: Only base, bonus, commission, and overtime are on the payroll report. | [john_freddie@argyle.com](mailto:john_freddie@argyle.com) john_freddie | passgood 9095 | | Nomoni Freddie | 123456788 01-01-2000 | No payroll data (test 404 error) | [nomoni_freddie@argyle.com](mailto:nomoni_freddie@argyle.com) nomoni_freddie | Any string 9096 | | Nomula Frannie | 123456787 01-01-2000 | No payroll data (test 404 error) | [nomula_frannie@argyle.com](mailto:nomula_frannie@argyle.com) nomula_frannie | Any string 9097 | ## Paystub Profiles {#paystub-profiles} Use these profiles to test Lend products that contain paystub data. 1. Download the relevant zip file to access a folder with a suite of test paystubs and use the paystub with the most recent (not future) date. 2. If you're using a product that contains paystub and bank data, make sure to connect a bank account through the **FinBank Profiles -- A** test institution and use one of the userId and password values from the table below. Note: If you are using an [active customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) in your testing, rather than a [test customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers), you should connect a bank account through the **FinBank Billable** (or **FinBank OAuth Billable**) test institution. | Borrower Name | Banking UserId / Banking Password | Description | Paystub | |--------------------|-----------------------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | Jess Sea | profile_2513 | 1 active employment; salary, base | [Jess-Sea.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Jess-Sea.zip) (1MB) | | Ann Sea | profile_2514 | 1 active employment; commission only | [Ann-Sea.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Ann-Sea.zip) (671KB) | | Alice Firstimer | profile_1019 | 1 active employment; salary, base + overtime | [Alice-Firstimer.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Alice-Firstimer.zip) (717KB) | | Lorraine Purchaser | profile_1020 | 1 active employment; hourly, base | [Lorraine-Purchaser.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Lorraine-Purchaser.zip) (742KB) | | Patrick Purchaser | profile_1021 | 1 active employment; hourly, base | [Patrick-Purchaser.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Patrick-Purchaser.zip) (740KB) | | David Burton | profile_1027 | 1 active employment; split direct deposit | [David-Burton.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/David-Burton.zip) (3MB) | | Andy Miller | profile_1018 | 1 active employment; salary, base | [Andy-Miller.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Andy-Miller.zip) (711KB) | | Andy Freddie | profile_2511 | 1 active employment; salary, base + bonus + overtime + commissions | [Andy-Freddie.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Andy-Freddie.zip) (1MB) | | Dad Freddie | profile_540 | 1 active employment; salary, base + bonus | [Dad-Freddie.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Dad-Freddie.zip) (736KB) | | Suzi Freddie | profile_2512 | 2 active employments; base; semi-monthly, monthly | [Suzi-Freddie.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Suzi-Freddie.zip) (739KB) | ## MVS Profiles {#mvs-profiles} Use these profiles to test Mortgage Verification Service (MVS) products. 1. Create a consumer with the SSN and DOB from the table below. 2. For direct API payroll search experience, enter the same SSN when prompted in the Data Connect experience. 3. For credentialed payroll login experiences, launch the credentialed payroll popup, search for the payroll provider you would like to test, and enter the payroll credentials as shown above in the [Payroll Profiles table](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles) when prompted in the login experience. 4. For products with paystub data, download the zip file to access a folder with a suite of test paystubs and use the paystub with the most recent (not future) date. 5. If you're using a product that contains paystub and bank data, make sure to connect a bank account through the **FinBank Profiles -- A** test institution and use one of the userId and password values from the table below. 6. The profiles with [GSE](https://developer.mastercard.com/open-finance-us/documentation/glossary/index.md#government-sponsored-enterprise-gse) names listed have been set up to match Freddie Mac and Fannie Mae test profile requirements for end to end testing of GSE solutions. Note: If you are using an [active customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) in your testing, rather than a [test customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers), you should connect a bank account through the **FinBank Billable** (or **FinBank OAuth Billable**) test institution, and credentialed payroll accounts through the Platformtronic test payroll provider. This also applies if you are using mortgage ecosystem platforms such as nCino or ICE for your testing. | Consumer Name | SSN / DOB (MM-DD-YYYY) | Description | Banking UserId / Banking Password | Paystub | GSE | | | |--------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|---------|---|---| | Homer Loanseeker | 999601111 07-04-1970 | 1 active employment; salary, base | profile_2509 | (n/a) | Fannie | | | | Jess Sea | 999001147 07-05-1980 | 1 active employment; salary, base | profile_2513 | [Jess-Sea.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Jess-Sea.zip) (1MB) | Fannie | | | | Ann Sea | 999009066 07-06-1986 | 1 active employment; commission only | profile_2514 | [Ann-Sea.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Ann-Sea.zip) (671KB) | Fannie | | | | Suzi Builder | 999606666 07-07-1995 | 2 active employments; salary, base + overtime | profile_2510 | (n/a) | Fannie | | | | Alice Firstimer | 991919991 12-27-1992 | 1 active employment; salary, base + overtime | profile_1019 | [Alice-Firstimer.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Alice-Firstimer.zip) (717KB) | Fannie | | | | Lorraine Purchaser | 999565678 05-02-1985 | 1 active employment; hourly, base | profile_1020 | [Lorraine-Purchaser.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Lorraine-Purchaser.zip) (742KB) | Fannie | | | | Patrick Purchaser | 999121234 09-09-1987 | 1 active employment; hourly, base | profile_1021 | [Patrick-Purchaser.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Patrick-Purchaser.zip) (740KB) | Fannie | | | | Andy Freddie | 990300003 08-06-1990 | 1 active employment; salary, base + bonus + overtime + commissions, 1 terminated employment | profile_2511 | [Andy-Freddie.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Andy-Freddie.zip) (1MB) | Freddie | | | | Dad Freddie | 991000010 08-02-1970 | 1 active employment; salary, base + bonus | profile_540 | [Dad-Freddie.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Dad-Freddie.zip) (736KB) | Freddie | | | | Patrick Freddie | 990500005 08-09-1980 | 1 active employment; base, semi-monthly, salary | (n/a) | (n/a) | Freddie | | | | Amy Freddie | 990400004 08-07-1980 | 1 active employment; base + bonus, bi-weekly, salary | (n/a) | (n/a) | Freddie | | | | Suzi Freddie | 990700007 08-06-1990 | 2 active employments; base; semi-monthly, monthly | profile_2512 | [Suzi-Freddie.zip](https://static.developer.mastercard.com/content/open-finance-us/uploads/test-profiles/Suzi-Freddie.zip) (739KB) | Freddie | | | | Mom Freddie | 990110011 08-04-1970 | 2 active employments; base + bonus + overtime + commissions, bi-weekly | (n/a) | (n/a) | Freddie | | | | Alice Freddie | 990080008 08-05-1990 | 1 terminated employment; base, semi-monthly | (n/a) | (n/a) | Freddie | | | | John Freddie | 990100001 08-01-1970 | 1 active employment w/ payroll; base + bonus + commission + overtime + weekly. Child support, military, VA benefits, alimony. Note: Only base, bonus, commission, and overtime are on the payroll report. | profile_2260 | (n/a) | Freddie | | | | Nomoni Freddie | 123456788 01-01-2000 | No payroll data (test 404 error) | (n/a) | (n/a) | Freddie | | | | Nomula Frannie | 123456787 01-01-2000 | No payroll data (test 404 error) | (n/a) | (n/a) | Freddie | | | ## Account Opening Profiles {#account-opening-profiles} Use these profiles to test various scenarios for account opening use cases: Note: If you are requesting account owner with [identity insights](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta) in your testing, note that the Finbank Oauth institution must be used. | Owner Name(s) | Banking UserId / Banking Password | Description | Products | Supported Institution(s) | |---------------------------------------|-----------------------------------|---------------------------------------------------------------------------|--------------|-------------------------------------------------------------| | Jess Sea | profile_02 | Savings, IRA, 401k, Credit Card | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | Ann Sea | profile_03 | Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners) | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | Alice Firstimer | profile_04 | Checking, 403B, 529, Rollover, Mortgage | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | Lorraine Purchaser | profile_05 | Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners) | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | Patrick Purchaser | profile_06 | Checking, Retirement, KEOGH, 457, Credit Card | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | David Burton | profile_07 | Checking, Stocks, CD, Investment Tax-Deferred, Employee Stock | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | Andy Miller | profile_08 | Checking, Primary Savings, Money Market, 401A, Line of credit | ach, ao | FinBank Profiles -- A, FinBank Profiles -- B, Finbank OAuth | | Homer Loanseeker | profile_7000 | Checking, primary owner | ach, ao, ao+ | Finbank OAuth | | Homer Loanseeker, Lorraine Loanseeker | profile_7002 | Checking, joint owners | ach, ao, ao+ | Finbank OAuth | | Patrick Freddie, Lorraine Freddie | profile_7003 | Checking, Savings; joint owners | ach, ao, ao+ | Finbank OAuth | ## Payment Risk Insights Report Profiles {#payment-risk-insights-report-profiles} Use the following information to test the Payment Risk Insights Report: 1. Create a [test customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers). 2. Create and open a [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). 3. Search for **FinBank Profiles -- A** in the Data Connect UI. 4. When asked for a username and password, use one of the profiles from the table below. In each case the username and password are identical. The profiles below generate reports with different risk levels. All profiles work with **FinBank Profiles -- A**. | Username/Password | Risk Level | |-------------------|-------------------------------------| | profile_1151 | High | | profile_1154 | High | | profile_1164 | Medium-High | | profile_1162 | Medium-High | | profile_1156 | Medium | | profile_1165 | Medium | | profile_1725 | Low | | profile_2511 | Low | | profile_09 | Failed report (invalid credentials) | ## Payment Success Indicator Profiles {#payment-success-indicator-profiles} The profiles below have been set up to allow you to test responses for different Payment Success Indicator (PSI) scenarios. The profiles have different balances and account histories and will generate different PSI scores for different settlement amounts and settlement days. These profiles will work with **Finbank Profiles - A**. 1. Create a test customer. 2. Create and open a [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) (we recommend that you provide a webhook URL to Data Connect, so you can receive data about the customer bank account relating to the profile chosen in the Data Connect UI). 3. Search for **FinBank Profiles -- A** in the Data Connect UI. 4. When asked for a username and password, use usernames and passwords from the table below. Note that in each case the username and password are identical. 5. You can then use the account data captured by your webhook listener when you logged in using the test profile to obtain the necessary data to use in a PSI call (you will need the `customerId` and `accountId`, then you can try different values for `settlementAmount` and `settleByDate`.) As an alternative to using a webhook, you can call [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) to find the appropriate account ID. The following table lists the test profiles, their current balance, and the `scoreIndicator` value which will be returned when you specify a `settlementAmount` of either $10, $100, $1000, or $5000, in your PSI call. Note: `settleByDate` is a dynamic input. If you input any date between today (the date of the request) and day 2 (given in the `settleByDate` parameter), you will receive 3 days of PSI NSF scores. If you specify a `settleByDate` between 2 or 9 days in the future from the request date, you will receive data for the number of days that you requested (up to a maximum of 10 days of NSF scores). | Username/ Password | Balance\* | $10 | $100 | $1000 | $5000 | |--------------------|-----------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | profile_1154 | $3,977.79 | NSF Return: Low Risk (Days 0-8), Medium Risk (Day 9) Unauthorized Return: Low Risk | NSF Return: Low Risk (Days 0-3), Medium Risk (Days 4-9) Unauthorized Return: Low Risk | NSF Return: Medium Risk (Days 0-9) Unauthorized Return: Low Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: Medium Risk | | profile_1155 | $915.64 | NSF Return: Medium Risk (Days 0-9) Unauthorized Return: Low Risk | NSF Return: Medium Risk (Days 0-9) Unauthorized Return: Low Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: Medium Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: Medium Risk | | profile_1156 | $1,123.22 | NSF Return: Low Risk (Days 0-9) Unauthorized Return: Low Risk | NSF Return: Medium Risk (Day 0), Low Risk (Days 1-9) Unauthorized Return: Low Risk | NSF Return: High Risk (Day 0), Medium Risk (Days 1-9) Unauthorized Return: Medium Risk | NSF Return: High Risk (Day 0), Medium Risk (Days 1-9) Unauthorized Return: High Risk | | profile_1157 | ($158.17) | NSF Return: High Risk (Days 0-9) Unauthorized Return: High Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: High Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: High Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: High Risk | | profile_1158 | ($23.24) | NSF Return: High Risk (Days 0-9) Unauthorized Return: Medium Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: Medium Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: High Risk | NSF Return: High Risk (Days 0-9) Unauthorized Return: High Risk | \*Brackets denote a negative balance. ## Transactions Profiles {#transactions-profiles} Use these profiles to test scenarios involving transaction history, such as using [Recurring Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md). 1. Create a test customer. 2. Create and open a Data Connect URL. 3. Search for a financial institution supported by the profile you want to use, for example **FinBank Profiles -- A**. 4. When prompted, enter the username and password from the table. Note that you will need to contact your Mastercard account manager to enable **Finbank OAuth** if you want to use the OAuth profiles. | Username | Password | Description | Supported Institution(s) | |--------------|--------------|---------------------------------------------------------------------------------------|-------------------------------------------------------------| | profile_1000 | profile_1000 | No transactions | FinBank Profiles -- A, FinBank Profiles -- B | | profile_1500 | profile_1500 | Subscription transactions in various categories | FinBank Profiles -- A, FinBank Profiles -- B, FinBank OAuth | | profile_1501 | profile_1501 | Subscription transactions in various categories | FinBank Profiles -- A, FinBank Profiles -- B, FinBank OAuth | | profile_1502 | profile_1502 | Subscription transactions in various categories | FinBank Profiles -- A, FinBank Profiles -- B, FinBank OAuth | | profile_1503 | profile_1503 | Subscription transactions in various categories | FinBank Profiles -- A, FinBank Profiles -- B, FinBank OAuth | | profile_1725 | profile_1725 | Three accounts with \~5k transactions per account | FinBank Profiles -- A, FinBank Profiles -- B | | profile_1726 | profile_1726 | One checking account with \~15k transactions; suitable for Consumer Foresight testing | FinBank OAuth | | profile_2130 | profile_2130 | One transaction on the 5th of each month | FinBank Profiles -- A, FinBank Profiles -- B | ## See Also {#see-also} * [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) * [Using the Postman Collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) * [Generating an API Client Library](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/generating-an-api-client-library/index.md) * [API Reference](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) --- # OAuth Connections source: https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md ## What Is an OAuth Connection vs a Legacy Connection? {#what-is-an-oauth-connection-vs-a-legacy-connection} An OAuth connection is a direct integration with an institution where the customer can directly log in to their financial institution (FI) and the customer's login credentials are handled entirely by their FI. Information is obtained through direct API integrations with the banking institution, which enforces the accuracy and security of the data being received. Legacy connections require credentials to be captured and utilized by Mastercard in order to obtain financial data. When a new OAuth connection to an institution is announced, it is important to begin working through the migration process so that you can migrate to the new connection type and leverage the enhanced features and connectivity. If you need assistance with this process, please contact Mastercard for support. ## What Are the Benefits of Moving From a Legacy Connection to an OAuth Connection? {#what-are-the-benefits-of-moving-from-a-legacy-connection-to-an-oauth-connection} One of the driving factors for moving from the legacy connection to an OAuth connection is the ability to authorize and authenticate accounts using access tokens. This eliminates the need for FIs to pass or store usernames or passwords when sending or receiving account information. Other benefits include: * Increased connection speeds to access and retrieve more real-time consumer data. * Improved security access to our APIs as you develop your own applications. * Customers manage their own accounts to grant permissions (access) to only the accounts they want to share. * Customers can disconnect from the FI at any time. * Customers can easily access their accounts in your application even when they change their sign-in credentials. **Example**: Currently, if a user changes the username or password on their account, they would also have to update their credentials in your application, to reflect the change and not break the connection. If the FI was using an OAuth connection and the user changed their credentials, they'd still have access to their accounts in your application as long as the access token was valid. ## Migrate to OAuth {#migrate-to-oauth} Every time a new FI contract with an OAuth connection is announced as available, you should begin the process of migrating to the new connection. Whenever you migrate from an FI with a legacy connection type to its new OAuth connection type, the primary expected impact to your customers is that they will have to sign-on and re-authorize their accounts in order to engage the new connection. Throughout the entire migration process, you can also expect the following: * We work with you throughout each migration milestone. * We coordinate our efforts with yours to transition your customers from the old to the new OAuth connection. * We ensure original account data from the old connection isn't omitted or duplicated. ## Notify Your Customers {#notify-your-customers} When OAuth is close to going live, we'll send approved messages for you to pass on to your customers. There are many media outlets you can use to keep customers updated when they should expect to re-authenticate their accounts. Notification options include: * Your websites. * Login screens. * In your mobile application on the Add Account or Refresh Account screens. * The screen before Mastercard Data Connect starts from your mobile application. * Broadcast emails. ## Migration Process {#migration-process} 1. A new FI contract with an OAuth connection is announced in our monthly newsletter 2. The OAuth connection is active and available for use. OAuth connections have different statuses for you to verify which institutions are ready: * Beta: No clients outside of our beta users have access to this OAuth connection * Validated: All new user traffic is directed to the connection * Migrating: All customer traffic is in the process of being migrated to the new OAuth connection. Note: Customers lose connection to their accounts as part of the migration process and need to reauthenticate to re-engage the connection. * Online: The migration is complete. The OAuth connection is live, and the legacy connection is retired. 3. Migrate your customer accounts to the new OAuth connection. 4. The previous Legacy connection retires. Note: You only have to register your applications one time, and for all future FIs announced with OAuth connections, you do not need to register again. Otherwise, if you are a new client, see our documentation on [registering an application](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md). ## OAuth FI Connections {#oauth-fi-connections} Use the Get Institutions endpoint to find a list of all of our currently supported OAuth institutions. NOTICE TO FINICITY CLIENTS/PARTNERS UTILIZING FIDELITY OAuth CONNECTION: In accordance with its agreement with Fidelity, Finicity notifies you that Third Party Data Providers (described below) may require you to enter into a separate license agreement to receive "market data" including but not limited to Holdings, Marketvalue Transactions, Vestings, and/or Symbol Statement PDF API data. Third Party Data Providers include, but are not limited to, stock exchanges, bond ratings, credit ratings, and financial instrument reference data companies, who may have a proprietary interest in information embedded in Fidelity customers' data. A Third Party Data Provider may contact Finicity or may contact you directly regarding the use of such market data and a separate license agreement. **See also**: * [Register Applications](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md) * [Migrate Customers](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/migration-customers/index.md) --- # Bill Pay Switch source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/bill-pay-switch/index.md ## What Is Bill Pay Switch? {#what-is-bill-pay-switch} Through the Open Finance experience, Bill Pay Switch (BPS) enables customers to switch recurring automatic payments from an incumbent account into a new or existing account at a financial institution. BPS enables customers to update their payment information (ACH or Card on File) for recurring bills and subscriptions by making it easier to switch financial providers. Warning: This product may not be used for purposes subject to the Fair Credit Reporting Act. ## Why Is It Important? {#why-is-it-important} **Make Switching Banks Effortless with BPS** Switching banks has long been a hassle---especially when it comes to updating recurring payments for subscriptions, memberships, and vendors. Payments are sticky by nature, creating friction that discourages customers from moving their primary banking relationships. BPS removes this barrier. With a single, secure session, customers can log in to multiple merchants and update their payment details seamlessly---no manual updates, no headaches. But the value of BPS goes far beyond convenience. * **Drive Customer Retention and Primacy** BPS helps financial institutions retain customers and increase wallet share by reducing switching friction and enabling deeper, longer-term engagement. * **Built for Compliance and Trust** Fully aligned with Open Finance regulations, BPS ensures that institutions stay compliant while offering a user experience that builds trust. * **Seamless Integration with Open Finance Tools** When paired with services like Account Validation and Data Connect add accounts, BPS becomes a powerful solution for account onboarding, funding, and long-term customer engagement. * **Revolutionary Security with On-device Authentication** BPS is powered by Atomic's TrueAuth technology, which removes the need for financial institutions to collect customer credentials. This not only enhances data security but also simplifies integration and eliminates the need for direct partnerships with payroll providers.
**Benefits for customers may include:** * **BPS makes switching banks simple and hassle-free:** Instead of updating each payment method manually, customers can efficiently manage all their recurring payments through a user-friendly dashboard and checklist. The solution supports both Card on File and ACH payment method updates while leveraging Return User Experience (RUX) design, allowing customers to seamlessly pick up where they left off. * **BPS puts security and ease at the forefront:** TrueAuth provides native support for biometric authentication methods like FaceID and TouchID, ensuring a smooth and secure experience. By integrating with other Open Finance services, BPS also enhances overall financial management, making it easier for consumers to onboard new accounts, fund them, and access competitive banking solutions. * **BPS removes the barriers to switching banks:** BPS empowers consumers to take control of their financial choices without the hassle, enabling them to select the best banking provider for their needs while ensuring a frictionless and modern experience. ## UX Flow Example and Best Practices {#ux-flow-example-and-best-practices} Tip: Access the [Figma file](https://www.figma.com/design/3skK7lbsVEufKauMc9K6Z0/Bill-Pay-Switch-%E2%80%A8UX-with-Best-Practices?node-id=1-6688&t=ntOcGeaenYlJU6wb-4) for this experience to duplicate and customize in your own environment. For the best viewing experience of app to app, click the **full screen mode** option or **zoom** using the controls located on the right.

Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). ## How It Works {#how-it-works} For details of how to initiate the new Connect Transfer flow and obtain details of the bill pay switches once created, see the [developer documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md). Note: **Is customization available?** Limited customizations are applicable in the current version of Bill Pay Switch.
Next: [Mastercard Data Connect Enhancements and Features](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/index.md) --- # Open Finance US for Account Opening and Funding source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/account-opening-and-funding/index.md Account opening should take seconds, but issues like manual uploads and micro-deposits add delays. This is why Mastercard launched an enhanced Open Finance for Account Opening solution. This innovation integrates account owner verification with identity insights into a single API to help you meet your customers' needs for security and transparency and introduces new ways to instantly verify account ownership creating a better onboarding experience. ![Payments](https://static.developer.mastercard.com/content/open-finance-us/uploads/demo2.svg) ### Demo {#demo} View the interactive prototype of the Open Finance Account Opening and Funding experience. [Open demo for Account Opening and Funding](https://www.figma.com/proto/8OjsuSyU4OzGfrebyyKvo2/Account-Opening-and-Funding---Demos?page-id=170%3A31389&type=design&node-id=721-8123&viewport=569%2C57%2C0.13&t=YvzHJMxDVn4qFt0j-1&scaling=scale-down&starting-point-node-id=721%3A8123&show-proto-sidebar=1&mode=design&fuid=1316298999584552659) ![Lending](https://static.developer.mastercard.com/content/open-finance-us/uploads/figma2.svg) ### Figma File {#figma-file} Find the end-to-end product experience for Account Opening and Funding scenarios to duplicate and customize in your own environment. [Access Figma file for Open Finance US](https://www.figma.com/design/YU5IzH4kghkelrF044fKBO/Open-Banking-US-for-Account-Opening-and-Funding?node-id=0-1) Note: Developers and product owners should also read our Use Case section [Account Opening and Funding](https://developer.mastercard.com/open-finance-us/documentation/usecases/ob-account-opening/index.md) which covers the webhooks and APIs that you will use. ## Account Opening and Optional Funding After an Account Has Been Created - Data Connect Full {#account-opening-and-optional-funding-after-an-account-has-been-created---data-connect-full} To view the UX journey, use **full screen mode** or **zoom** controls. Please allow a few seconds for the screens to load. ## Account Opening With Required Account Funding - Data Connect Full {#account-opening-with-required-account-funding---data-connect-full}
## Account Opening With Optional Account Funding - Data Connect Full {#account-opening-with-optional-account-funding---data-connect-full}
Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md) --- # Integrating with Data Connect source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md There are two flexible integration paths after [generating Mastercard Data Connect URLs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) --- SDK-based and non-SDK implementations. Both approaches offer full support for all available Data Connect iterations and are designed to meet a range of partner needs and technical environments. Once you've obtained your partner credentials and are ready to generate Data Connect links, you'll need to choose between these two options: * **SDK Integration:** The SDK simplifies integration by managing the user journey and tracking key details throughout the process. * **Non-SDK Integration:** If your environment does not support SDK usage, the non-SDK option provides equivalent functionality. In this approach, you'll be responsible for managing the user journey using [webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) and other tools. Tip: If you are interested in using the Connect Transfer flow for setting up Deposit Switches or Bill Pay Switches, see the [Deposit Switch and Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) documentation. ## SDK vs Non-SDK {#sdk-vs-non-sdk} To help you select the approach that best fits your implementation, the comparison tables below highlight the key features, tradeoffs, and integration considerations for each option. **SDK Features** | Feature / Consideration | SDK | Non-SDK | |-------------------------|-------------------------------------------------------------------------|-------------------------------------------------------------------------| | Platform Coverage | Requires a supported tech stack (for example, Flutter is not supported) | Works with any tech stack --- platform-agnostic | | OAuth Flow | OAuth popup managed by SDK | Partner is responsible for managing the OAuth popup in app or browser | | Session Management | Managed automatically by SDK using event handlers | Partner must manage session manually using webhooks | | User Event Tracking | Captured via SDK with granular, near real-time events | Captured via webhooks; less granular and may introduce slight delays | | Integration Complexity | Easier setup with built-in handling of user flow and events | More control, but higher complexity---especially syncing webhooks to UI | **Integration Requirements** | Requirement | SDK | Non-SDK | |-----------------------|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Installation | Web SDK requires installation | No SDK installation needed | | Connect URL Usage | URL is passed to SDK during initialization | URL is generated directly by partner backend and launched by partner application | | Redirect Handling | SDK manages redirection and transition | Partner must provide `redirectUri`; Data Connect redirects there after OAuth | | Mobile Considerations | SDK handles mobile automatically if supported | Partner must set `isHostedInMobileApp = true` for mobile support | | User Event Handling | Tracked automatically via SDK | Partner must subscribe to and handle [Data Connect webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) manually | **Additional Considerations** Unlike many SDKs that involve large codebases, our Data Connect SDKs are lightweight. Their primary function is to manage user journey data. * Use the SDK solution when you: * want minimal integration effort and faster time to market. * are using a supported front-end framework or tech stack. * want granular, near real-time user journey data.
* Use the non-SDK solution when you: * have security restrictions on using SDKs. * are working in an unsupported environment (such as Flutter). * don't need built-in user journey tracking.
**Next Steps** Once you've selected the implementation approach that best fits your use case, explore the detailed guides for each approach: * [SDK Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md) * [Non-SDK Integration](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/index.md) ## App to App Authentication {#app-to-app-authentication} App to app authentication is a feature within Data Connect that allows mobile users to permission access to their data by signing in with their financial institution's (FI) mobile app if it is downloaded on the device they are using. The user can sign in utilizing the applicable biometric login features for the FI. If the app is not downloaded, the customer is directed to login through the FI's website on a browser window. The following highlights the flow for customers, showing how they can use their facial identification (biometric recognition is device dependent) to log in to their bank and permission access to their account: ![App to App](https://static.developer.mastercard.com/content/open-finance-us/uploads/chase-app-to-app-visual_1.png) See our [App to App authentication toolkit](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/app-to-app-auth-best-practices/index.md) in the Experience Design Guide for more details. ### How to Test App to App Authentication {#how-to-test-app-to-app-authentication} Your implementation of the App to App Authentication flow can be tested using our Finbank test app. This is available for testing on both iOS and Android via the links below. The Finbank test app is not available via the app store. * The iOS Finbank test app is available via Apple's Testflight service: Sign up to Testflight if you have not already done so. Note that the app is renewed every 90 days on Testflight. Each time the app expires, you need to visit Testflight to get the updated version. * The Android Finbank test app is available here: Note that the Android app is only available in the US and India. Once the Finbank app is on the mobile testing device, you can ensure the universal link you implemented works correctly by going through your Data Connect experience and using Finbank OAuth test institution (102176) within the flow. You can expect the following: * Instead of being directed to the browser to log in to Finbank OAuth, Data Connect redirects the flow to the Finbank app on your device. * If your app-to-app setup is correct, Data Connect redirects the flow to the Finbank app instead of to the Finbank website in your default browser. * After successfully adding your accounts, Data Connect redirects the flow back to your app.
Finbank OAuth test profiles used for testing can be found in the [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles) section. --- # Pay by Bank Tutorial source: https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md Mastercard Open Finance solutions enable you to provide a "Pay by Bank" solution for common payment and money transfer scenarios where ACH is the primary payment method. You can enable your customers to "Pay by Bank" directly from their bank account, increasing security and eliminating the need to type in account and routing numbers. This page covers the Open Finance services which can be combined to implement a [Payment Enablement](https://developer.mastercard.com/open-finance-us/documentation/usecases/payment-enablement/index.md) use case. For any ACH payment acceptance or funds transfer use case, we recommend you do the following: * verify account **payment details** to originate an account to account payment (ACH, RTP, FedNow). * verify account **balances** to check that the user has sufficient funds for the transaction. * verify account **ownership** to confirm the user has the right to access the funds in the connected account. * carry out additional **fraud checks** to further de-risk the transaction (optional).
## Verifying Account Details and Balance {#verifying-account-details-and-balance} The [Payment Enablement Bundle (PEB)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) service enables you to retrieve multiple types of payment-related data using a single endpoint. For most payment enablement use cases, we recommend that you verify account payment details and balance at the same time using the PEB endpoint below. This bundled approach reduces the number of API calls required and simplifies integration. API Reference: `GET /aggregation/v1/paysuite/customers/{customerId}/accounts/{accountId}` To verify account details and balance, use the `include` query parameter to select: * **`paymentInstruction`** : to return account payment details *(required per NACHA web-debit rules)*. * **`balanceDetails`**: to return account available, pending and cleared balances.
We recommend setting `balance_cache_interval` at 30 minutes (default) or greater for optimal performance. ### Alternative Flow: Standalone Endpoints {#alternative-flow-standalone-endpoints} Instead of using PEB, you can make separate calls to these standalone endpoints: * [Account ACH Details (ACH)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) * [Account Balance Check (ABC)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) Tip: Some financial institutions, such as Chase and PNC Bank, return a [Tokenized Account Number](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#tokenized-account-numbers-tan) (TAN) in place of the real account number and routing number. A TAN is specific to each application and therefore provides extra security. ## Verifying Account Ownership {#verifying-account-ownership} Some clients --- especially those in regulated or high-risk sectors --- require account owner verification (AOV) prior to a payment method being created. Account Owner Verification (AOV) enables you to confirm the identity of the account holder, helping reduce fraud. There are multiple options to validate account ownership, including optional matching and additional identity insights. We recommend using the AOV [Account Owner Match](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) endpoint to match the user's name (and any other information) against the holders associated with the connected account(s). API Reference: `POST /account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}` Additional identity insights to further mitigate fraud are also available through this endpoint. Tip: For business accounts, pass the business name in the `first_name` field. The API concatenates and normalizes name components to improve match accuracy. ### Alternative Flow: Single PEB Request {#alternative-flow-single-peb-request} If you prefer getting all information in a single request, you can use the PEB endpoint with **`accountIdentity`** in the `include` query parameter. Note that account owner matching and identity insights are not currently available within PEB, but can be provided through the standalone [Account Owner endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta). Note: If you do not use Account Owner Matching, you must perform ownership verification against user-provided information by comparing returned data with user-provided information. ## Additional Fraud Checks {#additional-fraud-checks} Preventing fraud and failed payments is central to open finance enablement. Mastercard provides multiple ways for you to reduce exposure, which can be combined or layered depending on your risk tolerance. ### Payment Success Indicator (PSI) {#payment-success-indicator-psi} [Payment Success Indicator (PSI)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) provides a predictive score of payment success. By calling PSI before initiating an ACH, you can: * get a real-time likelihood of success/failure. * reduce reliance on manual fraud checks. * prevent exposure to schemes like kiting or insufficient funds. Warning: PSI is not currently available in PEB. If you are using PSI, avoid using the PEB `balanceDetails` option to avoid duplicate billable events. Note: An integration to [Account Balance Check (ABC)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) is recommended in the event that PSI fails (for example, if no recent transaction history is available). You can do this with a standalone balance integration or a [PEB](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) request with `balanceDetails` in the `include` parameter. ### Account Owner Verification With Identity Insights {#account-owner-verification-with-identity-insights} For identity-related fraud prevention, you can use [Account Owner Verification with Identity Insights (AOV+)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta). This adds: * deeper verification of account owner details. * risk signals and scores associating their account data with Connect session data. * stronger defenses against identity theft and synthetic identities. Warning: AOV+ is not currently available in PEB. If you are using AOV+, avoid using the PEB `accountIdentity` option to avoid duplicate billable events. ### Transaction Data \& Client Fraud Intelligence {#transaction-data--client-fraud-intelligence} You can pull transaction data directly from the FI using Mastercard's APIs. The [Transaction Aggregation and Account Transaction Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#account-transaction-details-atd-or-transaction-aggregation-tau) services provide up to 180 days of historical data, and with [Load Historic Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#load-historic-transactions) you can access data from up to 24 months ago (depending on the account type and whether the financial institution has made this level of historic data available.) See [Transaction Data (TAU)](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) for full details. You can apply your own fraud intelligence models to this data. This enables: * identifying indicators of account stability (e.g. payroll, recurring bills). * detecting red flags (overdrafts, NSF, inconsistent behavior). * spotting check-kiting patterns, where fraudsters deposit funds, initiate ACH orders, then drain the account before settlement. ## Summary of Services {#summary-of-services} The table below summarises the Open Finance services that are useful for common payment enablement scenarios. | Task | Service | Notes | |--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | Verify account payment details | [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) | | | Verify account payment details | [Payment Enablement Bundle (PEB)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) | Using paymentInstruction option | | Verify account balances | [Account Balance Check (ABC)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) | | | Verify account balances | [Payment Enablement Bundle (PEB)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) | Using balanceDetails option | | Verify account ownership | [Account Owner Match (AOV)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) | Account Owner Verification endpoint, optional Identity Insights (beta) | | Verify account ownership | [Account Owner Details (AOV)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) | Account Owner Verification endpoint, optional Identity Insights (beta) | | Verify account ownership | [Payment Enablement Bundle (PEB)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md) | Using accountIdentity option | | Fraud checks | [Payment Success Indicator (PSI)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) | Do not use with PEB balanceDetails to avoid duplicate billing | | Fraud checks | [Account Owner with Identity Insights (AOV+)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta) | Do not use with PEB accountIdentity to avoid duplicate billing | | Fraud checks | [Transaction Data (TAU)](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) | | ## More Integration Tips {#more-integration-tips} ### Qualifying Customer Accounts {#qualifying-customer-accounts} You may wish to confirm that payment details are available before requesting account balances or ownership info (or vice versa). In this case, you may choose to instead call the direct endpoints individually in a sequence that best works for your user journey: * [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) * [Account Balance Check (ABC)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) * [Account Owner Verification (AOV)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) ### Recurring Payments {#recurring-payments} After setting up the initial payment method, we recommend that you verify the account balance before initiating each recurring payment. You can verify the account balance with [Payment Enablement Bundle (PEB)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md), as part of the enhanced [Payment Success Indicator (PSI)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) or from the standalone [Account Balance Check (ABC)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) endpoint. ### Requesting Data for Multiple Accounts {#requesting-data-for-multiple-accounts} The below PEB endpoint can be used to request information for a customer across all active accounts at a specified financial institution: API Reference: `GET /aggregation/v1/paysuite/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts` ### Partial Data Returns {#partial-data-returns} Requests may not always return all the requested information due to limitations in coverage of financial institutions or account types. Design your solution for partial data returns. If account owner or balances are unavailable, ensure your flow can proceed with account payment details alone or prompt the user for manual verification. --- # Open Finance US for Payments source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/index.md Next generation payment solutions focus on being more inclusive and offering a wider range of options (such as using accurate real-time data, analytics, scoring, and insights from consumer authorized financial data) to digitally transform the payment experience. Below are the demo links and Figma files for Mastercard Data Connect's Payments best practices. ![Payments](https://static.developer.mastercard.com/content/open-finance-us/uploads/demo2.svg) ### Demo {#demo} View the interactive prototype of the Payments experience using Automated Clearing House (ACH) and Account Opening. [Open demo for Open Finance US for Payments](https://www.figma.com/proto/nuk4jk0aBjtxF1t1A7TjqN/ACH-Details-Demos?page-id=170%3A31389&type=design&node-id=170-32471&viewport=435%2C-39%2C0.13&t=kb0X5o16dwcIS72P-1&scaling=scale-down&starting-point-node-id=170%3A32471) ![Lending](https://static.developer.mastercard.com/content/open-finance-us/uploads/figma2.svg) ### Figma File {#figma-file} Find the end-to-end product experience for ACH and Account Opening to duplicate and customize in your own environment. [Access Figma file for Open Finance US](https://www.figma.com/design/pqrT4uBCEsbL53GXSxh6g0/Open-Banking-US-for-Payments?node-id=0-1) Note: Developers and product owners should also read our Use Case sections on [Account Opening](https://developer.mastercard.com/open-finance-us/documentation/usecases/ob-account-opening/index.md) and [Payment Enablement](https://developer.mastercard.com/open-finance-us/documentation/usecases/payment-enablement/index.md) which cover the webhooks and APIs that you will use. ## User Journeys {#user-journeys} Find links below for the user journeys displaying how Data Connect functions for Payment scenarios. [Automated Clearing House (ACH) \[Data Connect Full and Lite\]](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ach/index.md) [Account Validation Assistant \[Data Connect Full and Lite\]](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md) [Account opening and funding](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/account-opening/index.md) Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Automated Clearing House (ACH)](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ach/index.md) --- # Open Finance US for Lending source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/index.md Mastercard's Open Finance consumer lending solutions are transforming the experience for lenders and their customers. With a rich set of real-time data, analytics, scores, and insights, lenders can make smarter decisions and increase inclusion. Lenders can also incorporate bureau data for smarter credit decisioning. Access and use of bureau data enables better decisions, more competitive terms, and less time to closing. Below are the demo links and Figma files for Mastercard Data Connect's Lending best practices. ![Payments](https://static.developer.mastercard.com/content/open-finance-us/uploads/demo2.svg) ### Demo {#demo} View the interactive prototype of the Lending experience using Verification of Assets and Income. [Open demo for Open Finance US for Lending](https://www.figma.com/proto/awRdtkTcmM8M8K0OecFazX/Verification-of-Assets---Demo?page-id=2%3A4775&type=design&node-id=171-42576&viewport=226%2C242%2C0.06&t=CE0z7cps8nLsi4Kn-1&scaling=min-zoom&starting-point-node-id=171%3A42576&mode=design&fuid=1316298999584552659) ![Lending](https://static.developer.mastercard.com/content/open-finance-us/uploads/figma2.svg) ### Figma File {#figma-file} Find the end-to-end product experience for Verification of Assets and Income to duplicate and customize in your own environment. [Access Figma file for Open Finance US](https://www.figma.com/design/IFeJZsZKnQccdztXSSzySp/Open-Banking-US-for-Lending?node-id=0-1) Note: Developers and product owners should also read our Use Case sections on [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) and [Small Business Solutions](https://developer.mastercard.com/open-finance-us/documentation/usecases/small-business-solutions/index.md), which cover the webhooks and APIs. ## User Journeys {#user-journeys} Find links below for the user journeys displaying how Data Connect functions for Lending scenarios. [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-assets/index.md) [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-income-and-employment/index.md) Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-assets/index.md) --- # Client Hub Use Cases source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/client-hub-use-cases/index.md Learn how you can use the Client Hub to monitor health of financial institutions and perform billing reconciliation. ## Monitor Institution Status {#monitor-institution-status} Let's say a customer reports they are unable to connect to Navy Federal Credit Union. To evaluate the status of the financial institution's connection, access the Client Hub and click **Activity \> Institution status**. Enter **Navy** into the search bar and select a timeframe of **7 days**. The search locates Navy Federal Credit Union showing it is offline. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/navyFederalCreditUnionSearch.png) The financial institution is working to determine the cause of the connection failure. Customers can check back within 2-3 days to try their connection again. Partners can also continue to monitor the institution's status and notify the customer when it is back online. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/navy-fi-offline.png) ## Billing Reconciliation Using Invoice History {#billing-reconciliation-using-invoice-history} Let's say a financial manager wants to cross-check the list of reports recorded on the Client Hub for a customer with the corresponding invoices across various locations or branches to verify the charges incurred for a customer are accurate. You can create an Open Finance project and invite the financial manager and any other team members to view the project. The financial manager can then access the project and click the **Access Client Hub** to view the Invoice History records in Client Hub. Following are step-by-step instructions for an administrator on how to provide access to the Client Hub to a financial manager or a required team member: 1. Log in to [Mastercard Developers](https://developer.mastercard.com/account/log-in). 2. Click on your Open Finance **Project**. a. In the navigation menu on the left, click **Team**. b. Click **Invite a Team Member**. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/developerTeamInvite.png) 3. Enter the email address of the recipient you are giving access to the project. a. Choose **Read-only**. b. Click **Invite**. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/inviteATeamMemberReadOnly500.png) 4. After the invite has been sent, the Team page updates the member list and the invite status. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/teamInviteSent.png) 5. The recipient (financial manager) will receive an email letting them know they have access to the project to view the Client Hub. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/teamInviteClientHub.png) The financial manager can then [sign up](https://developer.mastercard.com/account/sign-up) for a new account or log into [Mastercard Developers](https://developer.mastercard.com/account/log-in) and click on the project they have been given access to. They can then access the Client Hub by selecting the appropriate project credentials, finding the overflow menu (the three dots on the right hand side) and then clicking **Access Client Hub** . See the [Accessing the Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md) page for details. The financial manager can then go to **Invoice History** and download the information in a CSV file and manually sort the number of reports run per customer ID. The CSV file downloads the data columns in the order they are displayed in Invoice History. The financial manager can then use this data to reconcile the charges to the appropriate user or loan or cost center. **See also**: * [Accessing the Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md) --- # Order Reports source: https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md The Client Hub Order Reports tool provides no-code access to Lend reports without the need to build an API integration. You can also use Order Reports for testing or as a temporary solution while building an integration. The features you can access depend on your account configuration and user role. The user who creates the first account for a partner organization automatically receives the Admin role. See [Managing Users](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#managing-users) on this page for details of the available user roles. * [Accessing the Client Hub for Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#accessing-the-client-hub-for-order-reports) * [Requesting a Report](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#requesting-a-report) * [Customizing Request Emails](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#customizing-request-emails) * [Report Reissue](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#report-reissue) * [Personal Profile Settings](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#personal-profile-settings) * [Company Profile Settings](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#company-profile-settings) * [Managing Users](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#managing-users) ## Accessing the Client Hub for Order Reports {#accessing-the-client-hub-for-order-reports} Warning: You cannot use Order Reports if you log in via a Mastercard Developers account. If your organization has an existing account, contact your account Admin to create your user role. For questions about plans, contact our [Sales Team](https://www.mastercard.com/us/en/demo-request.html). ### Creating a New Account {#creating-a-new-account} To access the Order Reports tool, sign up at the [Client Hub](https://www.finicityreports.com/create-account/) site. 1. Enter the requested information. Your email address becomes your username. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/create-account_.png) 2. Select "Lending" from the dropdown on the **Business Industry** page. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/select-lending_.png) 3. Select "Order Reports Service" from the dropdown on the **Use Cases** page. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/select-or_.png) 4. Provide any further requested information and select an FCRA permissible purpose. After creating your account, you can access the Client Hub. ### Single Sign-On {#single-sign-on} Single Sign-On (SSO) integration is available for Client Hub partners on a case-by-case basis. We currently support **SAML 2.0 compliant** Identity Providers (IDP) only, and all users must share the same company email domain. SSO provides: * Increased security * Better control over authentication and login experience * Ability to restrict traffic to specific IP addresses through your IDP
For SSO-integrated partners, users enter their username during authentication. The Client Hub recognizes the email domain and redirects to your assigned SSO identity provider (such as Okta or Google Authenticator) for verification. After verification, a response returns to the Client Hub and authentication is approved. Contact your account representative if you want to add SSO integration to your Client Hub account. ## Requesting a Report {#requesting-a-report} Users with the appropriate role (Admin, Loan Officer, Requestor) can generate new report requests for customers by clicking **Add Report** at the top of the [Report Dashboard](https://www.finicityreports.com/reports) page. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/report-dashboard.png) You can also search for a specific report or act on existing report requests. When you request a report, the customer is automatically emailed with a request to grant permission to share the required data through Mastercard Data Connect. You can customize the presentation and branding of messages sent to customers by editing your [Company Profile](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#company-profile). ### Test Profiles {#test-profiles} Mastercard provides test customer profiles to help you evaluate report creation and simulate real use cases (various report types, account types, failures, and more). For a comprehensive list of test profiles, see [Test the APIs](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). To submit a report request using test profile information: 1. **Identify a test profile:** Choose one that corresponds to the report type you want to test. Most profiles support various report types and may not explicitly mention the specific report you're evaluating. 2. **Create a report request:** In the Client Hub, select Order Reports from the navigation menu and click the **+** button. 3. **Choose a report:** Select the Report Type that aligns with your test profile. 4. **Enter test profile info:** Using the test profile information, complete the Borrower Details section. * Some report types (Payroll, Paystub, Mortgage, and others) may require specific information in the Borrower Details to test a valid report scenario. Ensure the information in this form (Name, SSN, DOB, and others) matches what is listed for your selected test profile. If not listed under the profile, you can enter any value. * Enter an email address you can access to test the customer interaction through a test profile. 5. **Submit the report request:** A message with a link to complete the report is sent to the email address you provided. 6. **Locate the report request email:** Access the email where the report request was sent and click the button to start the report process. A new browser window opens to start the customer permission process (Mastercard Data Connect). 7. **Connect to a Finbank account:** In the Data Connect window, search for "finbank" and identify the preferred test institution that aligns with your test profile. * For Paystub report requests, upload the provided paystub at this point. * For Payroll only report requests, skip this step. 8. **Complete report steps:** Follow the on-screen instructions to complete the report and validate the results in the Client Hub. This creates a completed report that you can view or download from the Client Hub report dashboard. Additional steps might be required through third-party platforms (such as submitting a report to a housing GSE for mortgage origination). See the [Lend reports documentation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) for each report for more information. ### Report Details {#report-details} All fields in this section are required, although custom fields may have default values or be designated optional. Data entered in custom field sections cannot be used in the report Search feature. To learn more about Custom Fields, see [Invoice History](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/invoice-history/index.md). * **Report Type:** The report generated from the request (see the next section for report descriptions) * **Start Date:** The starting date for the report request * **Reference ID:** Any unique identifier you want to use to identify the report request, such as an application number or loan number * **From Email:** The email domain that the report request is sent from; the default is `noreply@finicity.com`, but if you have a custom domain configured, you can update this to your preference * **Custom Fields:** These fields display, become required, or contain default values based on the custom options you have set ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/report-details-lg.png) #### Report Types {#report-types} The Order Reports feature provides access to many distinct types of reports based on user-permissioned data. The options available to you may only include a subset of the following list, based on your Mastercard Open Finance services agreement. Client Hub provides detailed descriptions for each report type during the report request flow. These details help users clearly understand the scope, data coverage, and purpose of each report, making it easier to select the most appropriate product for their business needs. ##### Where to Find Report Details {#where-to-find-report-details} When requesting a report in Client Hub: 1. Navigate to **Request Report**. 2. In **Step 1 -- Report Details** , select a **Report Type**. 3. Click **Details** next to any report type to view: 1. Report description 2. Key data elements included 3. Supported use cases 4. Additional reference links (where available) ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/request-report-det.png)
![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/request-report.png) * **Verifications of Assets (VOA):** Provides bank-validated insight into a customer's current financial assets, including up to 12 months of transaction history with credits and debits. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) * **Verification of Income (VOI):** Provides verification of a customer's income streams (both active and inactive) based on up to 24 months of bank transaction data; each income stream is ranked and includes a confidence score. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) * **Verification of Income and Employment -- Payroll:** Provides insight into a customer's current and prior income and employment through data directly from the payroll source. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md) * **Verification of Assets and Income -- Transactions:** Provides verification of a customer's income streams (both active and inactive) based on up to 24 months of bank transaction data; each income stream is ranked and includes a confidence score. Also includes up to 12 months of transaction history with credits and debits. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * **Verification of Income and Employment -- Paystub (with TXVerify):** Digitally extracts pay statement data and cross-verifies the data with income transactions directly from the customer's financial institution. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) * **Prequalification Report (CRA):** Provides bank-validated insight into a customer's current financial asset balances. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/prequal/index.md) * **Asset Summary Report (Non CRA):** No longer supported -- deprecated in 2023 * **Cash Flow Business (Non CRA):** No longer supported -- deprecated in 2023 * **Cash Flow Personal (CRA):** Provides inflow, outflow, and cash flow information including up to 24 months of transaction history * **Verification of Income and Employment -- Paystub:** Digital extraction of pay statement data * **MVS -- Basic (Asset, Income and Employment):** Waterfall experience to collect all data for asset, income and employment verification through payroll and transaction data. The customer connects to their bank accounts and payroll data. Generates a VOIE - Payroll (if data found) report and a VOAI - Transactions report. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) * **MVS -- Basic Paystub (Asset, Income and Employment):** Waterfall experience to collect all data for asset, income and employment verification through paystub and transaction data. The customer connects to their bank accounts and uploads paystub(s). Generates a VOIE - Paystub (with TXVerify) and a VOAI - Transactions report. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) * **MVS -- IE (Income and Employment):** Waterfall experience to collect all information necessary for income and employment verification in a single customer experience. The customer first connects their payroll data; if additional employment is needed, they connect to their direct deposit account(s) and upload their most recent paystub. Generates a VOIE - Payroll (if data found) and a VOIE - Paystub (with TXVerify) report (if required). [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) * **MVS -- Full (Asset, Income and Employment):** Waterfall experience to collect all information necessary for assets, income, and employment verification in a single customer experience. The customer first connects to their bank account(s) and payroll data. If the customer has additional employment to report, they upload their most recent paystub. Generates a VOIE - Payroll (if data found) report, a VOAI report, and a VOIE - Paystub (with TXVerify) report (if required). [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) * **Cash Flow Analytics:** Cash Flow Analytics (CFA) analyzes up to 24 months of credits and debits in connected accounts to surface cash-flow health and trends - such as inflows, outflows, net cash flow, seasonality, and NSF events - to assess capacity to pay and volatility. For business and personal use cases (CRA or non-CRA), CFA returns model-ready attributes over the desired time intervals. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md) * **Balance Analytics:** Balance Analytics (BA) provides insights into a customer's account balances over time, helping assess liquidity, trends, and potential risk for lending and portfolio decisions. BA analyzes up to 24 months of transaction history (as available) and returns attributes such as minimum, maximum, and average balances over the desired time intervals. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) * **Payment Risk Insights:** The Payment Risk Insights report retrieves up to 24 months of transaction history from connected accounts, and calculates a risk score based on a business's financial history. The risk score can be used to determine the probability that a business will experience a payment risk event, such as Non-Sufficient Funds/Overdraft or missed recurring payments, in the near future when making a payment. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) An SBCA report is accessible under **Merchant Lookup** in the navigation bar: * **Small Business Credit Analytics:** Small Business Credit Analytics (SBCA) provides underwriters with access to near real-time transaction-based insights to build a more complete view of business performance and creditworthiness, helping them underwrite more businesses and reduce risk. [Learn More](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md)
You can also access the following reports via refresh: * **Verification of Employment (VOE) --- Payroll:** Provides insight into a customer's current and prior employment through data directly from the payroll source. Available via "Refresh" for a completed VOIE -- Payroll report. * **Verification of Employment (VOE) -- Transactions:** Verifies the customer's employment by identifying customer's recent direct deposits without the income amounts. Available via "Refresh" for a completed VOAI - Transactions report or VOIE - Paystub (with TXVerify) report. ### Borrower, Business, and Personal Guarantor Details {#borrower-business-and-personal-guarantor-details} Depending on the report type, you will be asked to populate Borrower, Business and Personal Guarantor Details. All fields in this section are required. Use an active email address for the customer so they can receive and act upon the report request. The Social Security Number (SSN) provided here is hidden from all users for security reasons. For business entities, a Tax Identification Number (Tax ID) is required to generate the report and is likewise masked and not visible to users. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/borrower-details-lg.png) ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/personal-guarantor-details.png) #### Submit a Report Request {#submit-a-report-request} After entering all required and optional information, click **Submit Request** to send the account connection request to a customer. This sets the report to Pending status until the customer fulfills the steps for that report request. The report request link is only accessible for 72 hours after being sent. After that, your request will show as "Expired" and you must resend the request. You can customize the request email that customers receive -- see [Customizing Request Emails](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#customizing-request-emails) on this page for details. Note: You can change customer information on a pending report request while the report has Pending status, but you cannot alter it after the request is fulfilled. You can change custom field information with a refresh request on a completed report. ### Report Dashboard {#report-dashboard} After creating a report request, it appears on the Report Dashboard alongside a complete, historical view of all requested reports. You can search and sort report records by the columns displayed: * **User:** The Client Hub user who requested the report. This column is only visible to users with the Admin role. * **Reference #:** The identifier used to track the loan. This could be a loan number or any other value determined by your organization. * **Borrower Name:** The entity to whom a report request has been sent. This is who permissions the use of their banking or other data to create the requested report. * **Report Type:** The report product requested for the customer - for example, Verification of Income (VOI) or Verification of Assets (VOA). * **Date Requested:** The date on which the report was most recently requested. * **Time Remaining:** For a Pending record, this is the time remaining until the report request expires. Otherwise, this field is marked as not applicable (N/A). ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/report-history.png) ### Report Status {#report-status} All records on the dashboard include a Status value, indicating the current step of that report request. The status updates as the customer takes action to fulfill the request until the request expires. A report request link is only active for 72 hours from the send date. After that time, you need to re-send the report or create a new request. * **Pending:** The email has been sent to the customer, but the link has not been clicked. * **In Progress:** The customer clicked on the link and completed the request. * **Complete:** Your report is ready for use. * **Unsuccessful:** A report could not be returned with the permissioned data. The request must be re-sent, and the customer may try again with different or new financial institutions. * **Expired:** The link has expired. Re-send the report or create a new request. ### Take Action on a Report {#take-action-on-a-report} You can take several actions on report requests depending on their status: * **View:** Review a copy of the most recently completed report in your browser * **Download**: Save a PDF copy of the most recently completed report to your device. * **Delete**: Remove a pending or completed report. Deleting a completed report will also permanently delete the customer's credentials, where applicable. * **Resend Request**: Send a new report request to the customer using the same information as the selected request. This will require the customer to permission accounts as if this was a brand-new request. * **Edit Customer**: Update the customer details and custom field entries for a pending report request. * **Refresh Report**: Create a new report with up-to-date data using the same accounts as the selected request. * **Edit and Refresh Report**: Update the custom field entries and create a new report with up-to-date data using the same accounts as the selected request. ## Customizing Request Emails {#customizing-request-emails} After you send a report request, the customer receives an email informing them of the steps they need to take to provide access to their data. The email template varies slightly between report types but follows a similar outline: 1. Identifies the email recipient (from report request) 2. States the overall purpose of the request 3. Outlines the actions required by the request recipient 4. Reassures the secure practices of handling customer data 5. Provides sender information (user and company details) 6. Includes a call to action button The email template (Subject and Body) can be customized for each report type. Each report type associated with your account is identified with an experience ID. If you wish to customize the template for an experience ID, please work with your account representative to provide the email Subject (plain text format) and Body (HTML format). You can use these dynamic parameters: * `{{> common_brandLogo}}` * Banner containing company logo * `{{> common_greeting}}` * Borrower name * `{{> common_supportPhone}}` * Inserts "Please call us at (111) 555-1234 with any questions" (where the phone number is the one provided in your Company Profile) * `{{> common_signature}}` * Company name * Report requestor first and last name * Report requestor email for borrower notifications * `{{> common_buttonLink defaultButtonText="Get Started"}}` * Set button text to the text provided at the end Note that customized email templates are subject to approval by Mastercard (User Experience and Legal), and we reserve the right to require updates prior to releasing any new email content. Also consider: 1. The HTML email template may or may not contain links to external sources. 2. While default templates support English, Spanish and French language translations, multi-language custom email templates are not supported through Order Reports (API only). 3. Future email templates updates will be subject to review. 4. We strongly recommend testing and reviewing any new email template changes prior to launch. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/email-template.png) ## Report Reissue {#report-reissue} [Report Reissue](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md#report-reissue) provides secure and auditable, no-code access for third-party entities to retrieve consumer reports directly from Order Reports system. It provides lenders and their partners with a method for sharing consumer reports between authorized third parties (such as investor, mortgage insurers, QC agencies, and loan management systems)---minimizing repetitive file exchanges, lowering risk, and facilitating more seamless cooperation throughout the loan process. This table describes the key benefits of Report Reissue: | Benefit | Description | |----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Scalable access | Support large numbers of third-party users and high-volume report retrieval with self-service report reissue options without manual intervention. | | Strengthened data security | Provide read-only access through controlled channels, reducing risk and improving protection of sensitive consumer data. | | Auditability | Maintain a clear, reliable trail of every access and retrieval event---supporting compliance requirements and simplifying internal audits. The reissued report PDF includes the name of the entity and timestamp of retrieval. The reissuing entity receives a report ID to facilitate the reissue request from the original requestor. | | Seamless integration | Flexible options to reissue reports via our no-code report reissue portal to enable investors, mortgage insurance providers, quality control teams, and other partners to access the reports they need at the exact point they need them. A JSON option is available as well. Please visit the Developer Portal for more information. | ### Report Reissue Details {#report-reissue-details} * **Reissue:** Each report can be retrieved up to two times within a single charge, providing access to both JSON and PDF formats under a single billing event. * **Time frame:** Reports may be reissued up to 180 days after their original creation date. * **PDF Reader:** Reports are delivered in PDF format and require a PDF reader to view. * **Report ID:** The lender provides the report ID. * **Data Refresh:** Reissuing a report does not update the data. If the data refresh is required, it must be initiated by the original requester. ### Accessing the Client Hub for Order Reports {#accessing-the-client-hub-for-order-reports-1} If your organization has an existing account, contact your account admin to create your user role. For questions about plans, contact our Sales Team ([OFin.contactsales@mastercard.com](mailto:OFin.contactsales@mastercard.com)). #### Setting up Report Reissue in the Client Hub {#setting-up-report-reissue-in-the-client-hub} 1. To access the Order Reports tool, sign up at the [Client Hub](https://www.finicityreports.com/create-account/). See [Creating a New Account](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md#accessing-the-client-hub-for-order-reports) for more information. 2. Contact our Sales Team ([OFin.contactsales@mastercard.com](mailto:OFin.contactsales@mastercard.com)) to ensure you are contracted for the Report Reissue product. 3. Ask your Mastercard account representative to add Report Reissue functionality to your Client Hub account. ### How It Works {#how-it-works} 1. Go to . 2. In the portal, navigate to the **Order Reports** section. 3. Click **Reissue Report** , located in the upper-left corner of the **Report Dashboard**. 4. Enter the **Report ID** and **Permissible Purpose** . Note: The report can only be reissued with Permissible Purpose code 31. 5. Once the report is successfully retrieved, the PDF is available in the **Download** section. ## Personal Profile Settings {#personal-profile-settings} You can access your [Personal Profile](https://www.finicityreports.com/profile) by clicking on the person icon at the top right of the Client Hub. This section enables you to update the personal information provided when you originally signed up for the account or activated your user account. * First and last name * Phone number * Sign-on Email (username for login) * Email for borrower notifications
For Order Reports, this information is used as a signature when you request a report from a customer. You can also choose whether to receive notifications of reports completed by your customers. ### Change Password {#change-password} You may also update your password on this page. When choosing a new password, please note that a new password must: * be at least twelve characters in length * contain an uppercase letter * contain a lowercase letter * contain a number * contain a special character * not contain sequences of three or more repeated characters ## Company Profile Settings {#company-profile-settings} You can access your [Company Profile](https://www.finicityreports.com/company) by selecting **Settings \> Company Profile** at the top right of the Client Hub. Communications generated through the Client Hub (such as Order Reports requests) can be customized to include your company information, colors, and logos to make them look like they are coming directly from your company, rather than a third party. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/company-details_.png) You can customize your company name, address, city, state, zip, phone number and URL. You can also upload your logo, pick a general color, or provide an HTML hexadecimal value to match your brand's color. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/company-logo.png) ### Custom Domain {#custom-domain} The default email address used in report requests is `noreply@finicity.com`. If your company operates a custom email domain, we recommend that you configure your account to allow for report request notifications to be sent from that domain. Click **Setup Custom Domain** towards the bottom of the Company Profile page to go to the [Validate Custom Email Domain](https://www.finicityreports.com/validate-custom-domain) page. Add your custom domain to the field provided -- this generates the CNAME, S1/S2 and other information to be added to the DNS server of your email hosting provider. Please work with your email server admin or IT department to add the appropriate information from this section to your hosting provider. If required for your configuration, we can create a custom DKIM for your company. After customizing, we recommend that you send out a test email to ensure the customizations are displayed as expected. For both custom and default domain, the default username for a report request email to be sent from is "noreply@". If you have configured a custom domain, you can also customize the username value when requesting a report. Currently there is no way to change the default username for all reports at once - you must update them one by one. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/custom-emailname_.png) ### Custom Report Fields {#custom-report-fields} You can add up to five customized fields to your report requests. Click **Setup Custom Fields** at the bottom of the Company Profile page to go to the [Custom Report Fields](https://www.finicityreports.com/add-custom-fields) page. These fields can be auto-populated with a default value. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/custom-fields_.png) ## Managing Users {#managing-users} If you are an Admin, you can access the [User Management](https://www.finicityreports.com/users) page using **Settings \> Manage Members** at the top right of the Client Hub. You can view the list of users with access to your organization's account, including each user's name, status (pending or active), and role. ### User Roles {#user-roles} * **Admin:** able to access all settings, including access to manage members and edit Company settings. They can also see reports requested by all users. Your account can have multiple admins. * **Developer:** able to access and edit Company settings (for example, DNS settings) and view the institution statuses page but not able to request or view reports. * **Loan Officer:** able to access reports, request new reports and refresh active reports that they created only. * **View Only:** able to view all reports and requests, but not generate or update a new report request. * **Report Manager:** able to access reports, request new reports and refresh active reports created by any user. * **Requestor:** able to resend reports, refresh reports, and file support cases. This table details the functions available to each user role. | **User Roles** | **Manage Members** | **Company Profile** | **Request Reports** | **View Requests** | **Edit Reports** | **Refresh Reports** | |--------------------|--------------------|---------------------|---------------------|-------------------|------------------|---------------------| | **Admin** | Y | Y | Y, All | Y, All | Y, All | Y, All | | **Developer** | N | Y | N | N | N | N | | **Loan Officer** | N | N | Y, Own | Y, Own | Y, Own | Y, Own | | **View Only** | N | N | N | Y, All | N | N | | **Report Manager** | N | N | Y, All | Y, All | Y, All | Y, All | | **Requestor** | N | N | Y, Own | N | Y, Own | Y, Own | Note: Some user roles can only view/edit/refresh their own report requests, whereas other user roles can access all report requests. ### Inviting New Users {#inviting-new-users} You can add a new user with the **Invite** button on the [User Management](https://www.finicityreports.com/users) page. You must assign each new user a role. There is no limit to the number of users you may add to your account or for any single role. #### Invite an Individual User {#invite-an-individual-user} 1. Log in to Client Hub. 2. Navigate to **Settings** → **Manage Members**. 3. Select the **Invite** option. 4. Enter the required user details: 1. First name 2. Last name 3. Phone number 4. Email address 5. Role 5. Select the **Invite User** button. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/add-new-user.png) The invited user will receive an email with instructions to create a password and access Client Hub. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/account-setup.png) #### Invite Multiple Users {#invite-multiple-users} If you need to add multiple users at once, select the **Bulk Invite** option to upload a CSV file with information for up to 100 users. The invited user receives an email with instructions to create a password and access Client Hub. This is the format to use: ```csv first,last,phone,email,role John I,Smith,(888) 888-8888,John.Smith+1@example.com,VIEW_ONLY John II,Smith,(888) 888-8888,John.Smith+2@example.com,ADMIN John III,Smith,(888) 888-8888,John.Smith+3@example.com,OFFICER John IV,Smith,(888) 888-8888,John.Smith+4@example.com,REQUESTOR John V,Smith,(888) 888-8888,John.Smith+5@example.com,DEVELOPER John VI,Smith,(888) 888-8888,John.Smith+6@example.com,MANAGER ``` Once the CSV file has been uploaded, the specified users will receive an email inviting them to create a password and log in. #### After the Invitation Is Sent {#after-the-invitation-is-sent} * Each invited user receives an email invitation. * The user selects **Get Started** and completes password setup. * Once completed, the user is added under the same Partner ID as the inviter and can log in to Client Hub. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/welcome.png) Note: * Invitations must be accepted for access to be activated. * Verify user email addresses before sending invitations to avoid delays. * User access and permissions are determined by the assigned role. ### Exporting the User List {#exporting-the-user-list} 1. Log in to Client Hub. 2. Navigate to **Settings** → **Manage Members**. 3. Select **Export** from the User Management page. A file containing the current user list is downloaded. The exported file includes user details such as: * First name * Last name * Email address * Role * User status This export can be used for: * User access audits * Internal reporting * Reviewing assigned roles and statuses ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/client-hub/user-management.png) **See also**: * [Invoice History](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/invoice-history/index.md) * [Institution Status](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/institution-status/index.md) --- # Account Opening source: https://developer.mastercard.com/open-finance-us/documentation/usecases/ob-account-opening/index.md Verify ownership, check account numbers, routing numbers and account balances to provide a better onboarding experience for your customers: ![Avatar](https://static.developer.mastercard.com/content/open-finance-us/uploads/ob-usecase-accountopen.png) ###### **Use Case** ### Account Opening Launch Demo #### 14 Accounts {#14-accounts} The average consumer maintains 14 financial accounts across different financial service providers.
###### Aite-Novarica {#aite-novarica} #### 93% {#93} of consumers use technology to move money; bill payments (82%) and banking (80%) are leading use cases.
###### Mastercard Research {#mastercard-research} #### 81% {#81} of U.S consumers have connected financial accounts, and most of them are doing it to make P2P or bill payment transactions. ###### Mastercard Research {#mastercard-research} ##### Account Opening Program for Mastercard Issuers {#content} Issuers can opt into the Open Finance for Account Opening Program to secure and streamline the digital account opening process for Mastercard consumer and small business debit cards and general-purpose reloadable Mastercard consumer prepaid products. Participating Issuers will have access to Mastercard Open Finance's Account Owner Verification, Account Detail Verification and Account Balance Check solutions, providing confidence in who their customers are, reducing content abandonment and inactivity, and decreasing non-sufficient fund (NSF) returns.
Under the program, these Open Finance services are provided as a free core benefit to Mastercard issuers when they are used to support digital account opening of an eligible Mastercard account. Issuers who wish to participate in the Open Finance for Account Opening Program must sign an enrollment form. Download the form [here](https://w201.mastercardconnect.com/gcccic001/homememb/library/shared/Forms_Library/Forms/doc/0322.docx) ## How It Works {#how-it-works} After a customer consents access to their accounts, leverage our APIs to verify account ownership, retrieve transaction data, check account details and balance. Use this data to enable a faster account set-up, onboarding and funding process for your customers. Call the following APIs to ensure you have the required data to provide a secure and seamless account opening experience for your customers: * Regardless of the API you want to call, you will first need to generate a URL to launch the [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) application that allows your customers to link their accounts and provide you the permission to access their financial data through Mastercard Open Finance. The Data Connect application is the only way you can allow your customers to link their accounts and is mandatory for integrating with any Mastercard Open Finance APIs. * [Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) allow your app to receive notifications about Data Connect events and to listen for when reports have been generated. * [Get Customer Account by ID](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-full-details-afd-or-account-limited-aggregation-ala) to return basic information of a customer account. * [Get Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) to return the real account number and routing number details for an ACH or real-time (RTP) payment. * [Get Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) to retrieve the names and addresses of the account owner from a financial institution. * [Match Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) to retrieve the names and addresses of the account owner from a financial institution with a matching confidence score. * [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md#get-available-balance) to retrieve the latest available and cleared account balances for a single customer account. Note: If a project is enrolled in the core benefit program, the eligible products used to issue a Mastercard debit card will be provided for free. Once enrolled, please be sure to send the "Meta-Data" header field with a value of "program=OBAO" on all eligible requests in order to receive the billing discount. Enrollment prior to making the request is required for the data request to be completed successfully. This solution uses the following services: #### Account Owner {#account-owner} Instantly verify account ownership for better onboarding experience.

[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) #### ACH Details {#ach-details} Get ACH (Automated Clearing House) details for account opening or payment initiation.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) #### Account Balance {#account-balance} Provide available account balance information for your customers.

[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) Diagram usecase_account_opening Learn more about the consumer experience for this use case: [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/account-opening-and-funding/index.md) Understand the ideal consumer experience for Account Opening ## Next Steps {#next-steps} ![Quick Start Guide](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_quickstart.png) ### Quick Start Guide {#quick-start-guide} Get started with using Mastercard Open Finance APIs in less than 30 minutes.

[Get Started →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) ![API Reference](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_apireference.png) ### API Reference {#api-reference} Find detailed explanation of all resources available through Mastercard Open Finance API.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) ![Postman](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_postman.png) ### Postman {#postman} Run the Postman Collection to start using Open Finance API without the need to write any code.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) --- # Deposit Switch source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md ## What Is Deposit Switch? {#what-is-deposit-switch} Customers are expecting digital-first solutions more than ever. With Mastercard's Deposit Switch (powered by Atomic, a partner of Mastercard), financial institutions can accelerate direct deposit acquisition by enabling customers to easily switch their payroll deposit to a new account. Doing so digitizes manual processes and helps foster account primacy and customer engagement. Deposit Switch lets customers skip the paper process and automatically change or set up their direct deposit by digitally connecting to their payroll system in real time from an app or website. Warning: This product may not be used for purposes subject to the Fair Credit Reporting Act. ## Why Is It Important? {#why-is-it-important} Today, customers using a traditional method to set up or switch direct deposit accounts encounter a process full of friction. For example, they must complete paperwork, manually enter account information (including account and routing number), wait for human resources to receive and process their request, and wait until the deposit is in their account. In addition, this arduous process increases the likelihood of fraudulent information sharing. By using payroll direct deposit, consumers take advantage of their account funding options and solidify their banking relationships. In fact, setting up direct deposit was the most in-demand mobile account opening feature according to a 2022 survey of new checking accounts. ### Benefits for Financial Institutions: {#benefits-for-financial-institutions} * Grow direct deposits and primary relationships via Deposit Switch that automates the process for setting up recurrent account funding. * Increase lifetime customer value. Direct deposits are a major driver of account growth and profitability. Customers who switch their direct deposit have higher engagement rates with other products and services. * Increase conversions and reduce abandonment rates with Deposit Switch. * Incorporate deposit switching alongside the entire Mastercard Open Finance suite of account opening solutions for ease of discovery and adoption. ### Benefits for Customers: {#benefits-for-customers} * Provides automated direct deposit switching, which is one of the highest in-demand account funding options for US mobile account openings. * Enables them, in most cases, to make changes without going through a human resources department. * Gives them confidence knowing their paychecks are directed to the correct account safely and securely. ## UX Flow Example and Best Practices {#ux-flow-example-and-best-practices} Tip: Access the [Figma file](https://www.figma.com/design/uYMCQNbIfasiOp8rwYDZlE/Deposit-Switch?node-id=0-1) for this experience to duplicate and customize in your own environment. For the best viewing experience of app to app, click the **full screen mode** option or **zoom** using the controls located on the right.

## How It Works {#how-it-works} For details of how to initiate the new Connect Transfer flow and obtain details of the deposit switches once created, see the [developer documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md). Note: **Is customization available?** Limited customizations are applicable in the current version of Deposit Switch. * Supported Browsers: iOS: Automatic Redirect: Safari Redirect Button: Chrome, Edge, Firefox * Android: Automatic Redirect: Chrome, Edge, Native Browser Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/bill-pay-switch/index.md) --- # Mortgage Lending source: https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md As a mortgage lender, use our Mortgage Verification Service (MVS) to increase efficiency, reduce costs, and improve the lending experience for you and your borrowers. MVS integrates seamlessly into your workflow and helps you verify a borrower's assets, income, and employment information -- giving you access to information you need to make confident lending decisions. ![Avatar](https://static.developer.mastercard.com/content/open-finance-us/uploads/ob-usecase-lending-header.png) ###### **Use Case** ### Mortgage Lending Launch Demo With hundreds of mortgage lenders using this solution, Mastercard has positioned itself as the industry's top choice for a one-stop shop for assets, income and employment solutions. Because Open Finance data is multi-purpose, more and more lenders are finding innovative ways to apply the benefits of the solution. ## How It Works {#how-it-works} ### Overview {#overview} Through the [Mastercard Data Connect application](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), mortgage lenders can place the consumer Open Finance data account linking experience into their workflow; either directly embedded into their online loan application, as a task in a borrower portal, or via an email to the borrower. Once the data is permissioned by the consumer, the verification reports are created and made available to the lender for underwriting review. ### Implementation {#implementation} Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) and [Mortgage Implementation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) for technical details. ### Automated Underwriting System Support {#automated-underwriting-system-support} Our MVS reports are supported by Fannie Mae's Desktop Underwriter (DU) and Freddie Mac's Loan Product Advisor (LPA) Automated Underwriting Systems (AUS) and through the Day 1 Certainty (D1C) and Asset and Income Modeler (AIM) programs. Please work with your Fannie Mae/Freddie Mac reps for more information on how to use these products within their systems, and feel free to reach out to your Mastercard account manager with questions about Mastercard products. ## Products {#products} The following products are commonly used for Mortgage Lending: * [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) * **Note for mortgage use**: Regardless of how much transaction history is requested by the lender when generating the report, up to twelve months of full transaction history is provided to Freddie Mac and Fannie Mae for automated assessments when you submit the report to the corresponding Automated Underwriting System (AUS). * [Verification of Assets and Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * **Note for mortgage use**: Regardless of how much transaction history is requested by the lender when generating the report, up to twenty-four months of full transaction history is provided to Freddie Mac and Fannie Mae for automated assessments when you submit the report to the corresponding AUS. * [Verification of Income and Employment -- Paystub (with TXVerify)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) * **Note for mortgage use**: Adding a single paystub to an MVS asset report (VOAI or VOA) can significantly increase the success of finding deposit income in the bank data. You can use a previously collected paystub or use the Data Connect experience to engage the borrower. For best results with the Fannie Mae and Freddie Mac Automated Underwriting Systems, please ensure the consumer has a VOAI (ideal) or VOA report included in their portfolio. * [Verification of Employment -- Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-transactions/index.md) * **Note for mortgage use**: Often used to fulfill pre-closing verification of employment needs. If the consumer connected their bank accounts during the loan application process (via the VOAI or VOA products), the VOE - Transactions product can be ordered at closing without re-engaging the borrower as long as the accounts are still connected and consent is active. * [Verification of Income and Employment -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md) * **Note for mortgage use**: This report attempts to link to Payroll data providers to confirm income and employment and provides all necessary income and employment URLA data. * [Verification of Employment -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) * **Note for mortgage use**: Often used to fulfill pre-closing verification of employment needs. If the consumer connected their payroll accounts during the loan application process (via the VOIE -- Payroll product), the VOE -- Payroll product can be ordered at closing without re-engaging the borrower as long as the accounts are still connected and consent is active. Note: Some of the above products can be bundled into one price as part of an "MVS Report Bundle" product. The products are still ordered separately but are billed as one bundle. Talk to your account representative for more information. ## Next Steps {#next-steps} ![Quick Start Guide](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_quickstart.png) ### Quick Start Guide {#quick-start-guide} Get started with using Mastercard Open Finance APIs in less than 30 minutes.

[Get Started →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) ![API Reference](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_apireference.png) ### API Reference {#api-reference} Find detailed explanation of all resources available through Mastercard Open Finance API.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) ![Postman](https://static.developer.mastercard.com/content/open-finance-us/uploads/usecases_nextsteps_postman.png) ### Postman {#postman} Run the Postman Collection to start using Open Finance API without the need to write any code.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) --- # Generate Data Connect URL source: https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md 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.

[Use Data Connect Full →](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) **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. [Use Data Connect Lite →](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-lite) **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 →](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#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. [Use Send Data Connect Email →](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#send-data-connect-email) ### How It Works {#how-it-works} Data Connect enables customers to grant authorization to access their financial data using their account credentials. This financial data is then made available to partners using [Data Connect products](https://developer.mastercard.com/open-finance-us/documentation/products/index.md). The Data Connect `experience` parameter enables you to configure parts of the Data Connect UI and functionality. See the [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) 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](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). Tip: If you are interested in using the Connect Transfer flow for setting up Deposit Switches or Bill Pay Switches, see the [Deposit Switch and Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) documentation. #### Session Time-Out {#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 displays 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 terminates after 2 further minutes of inactivity. #### Webhooks {#webhooks} When you are calling an API for generating a Data Connect URL you are required to send a URL for receiving [Data Connect Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md). These are notifications that are sent to the `webhook` URL when different events occur during the Data Connect flow, see [Data Connect Webhook events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md) for a list of these. Tip: For testing purposes, you can use tools like webhook.site or beeceptor.com that receive webhooks and post the content for you to review (note that this is not an official endorsement of 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), Mastercard resends 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. The exception to this is the `ping` event sent when the Generate Data Connect URL is first called. If we do not get a 200 response to this event, the Data Connect URL is not created and the API call fails. Note: Chase bank (JPMorgan Chase) has removed support for certain types of WebView traffic. For more information see the [Chase Developer documentation](https://developer.chase.com/products/aggregation-consent/guides/launching-the-oauth-flow-in-a-secure-container/) #### Software Development Kits (SDKs) {#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](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md). #### Data Connect Full Flow {#data-connect-full-flow} The following is an example of a Data Connect Full flow: Diagram connect-flow-simplified ### Data Connect Full (Including for Joint Borrower) {#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. To use a customized Data Connect experience, provide the experience ID as `experience` in the request body. See [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) for details. API Reference: `POST /connect/v2/generate` To generate a user experience that also covers joint borrowers, use the following endpoint: API Reference: `GET /connect/v2/generate/jointBorrower` ### Data Connect Lite {#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 Get Institutions endpoint given a search term from your customer. Once the customer selects an institution from the list, you will have the `institutionId` needed in the Data Connect Lite endpoint. API Reference: `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 that is appropriate to the FI. The customer is then prompted to accept the terms and conditions and privacy agreement before sign-in. To use a customized Data Connect experience, provide the experience ID as `experience` in the request body. For Data Connect Lite, this is mainly used to specify which account types the customer can select. See [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) for details. API Reference: `GET /connect/v2/generate/lite` ### Data Connect Fix {#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](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) endpoints such as Get Customer Account by ID). Not all connection issues can be resolved using Data Connect Fix. The [Aggregation Status Code](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) returned when you call one of the Account Aggregation endpoints will indicate what is causing the issue, and whether [using Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#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. API Reference: `POST /connect/v2/generate/fix` ### Send Data Connect Email {#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. API Reference: `POST /connect/v2/send/email` A second version of this endpoint is provided for joint borrowers: API Reference: `POST /connect/v2/send/email/jointBorrower` ## Resources {#resources} * [Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) are displayed 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](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/index.md) are events sent from the Data Connect app through the SDK to your web and mobile apps. --- # Full Error List source: https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md This section includes a comprehensive list of all Open Finance errors, the remediation category for resolving the issue, the HTTP status, and the associated error message. Click the link to get details on the error's cause, troubleshooting steps, and how to remedy the error. ## Error Codes {#error-codes} | Error Code | Remediation Category | HTTP Status | Error Message | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [101](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#101) | Retry Later | 500 | There is currently a problem with the connection to this financial institution and it's being worked on. Please try again later. | | [102](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#102) | Retry Later | 500 | Problem connecting to the institution. Wait a few minutes and try again. Submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) if the issue persists.​ | | [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) | Data Connect Fix | 500 | Invalid login credentials. Prompt the user for a new password or have them reset it.​ | | ​[104](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#104) | Retry Later | 500 | An error has occurred in the script while parsing the institution's website. Please retry again and if the problem persists, [escalate the issue](https://support.finicity.com/knowledge/articles/201750879/en-us?brand_id=85319&return_to=%2Fhc%2Fen-us%2Farticles%2F201750879#escalation) through the API. | | [105](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#105) | Retry Later | 500 | Institution's website is unavailable or intermittently available. Please retry again and if the problem persists, [escalate the issue](https://support.finicity.com/knowledge/articles/201750879/en-us?brand_id=85319&return_to=%2Fhc%2Fen-us%2Farticles%2F201750879#escalation) through the API. | | [106](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#106) | Retry Later | 500 | User action required at financial institution. Prompt the user to login to their account directly at the institution's website and verify if the account is active and accessible, the transactions are visible and can be downloaded in the desired format. If after doing this the account still fails, then the account details, including account nickname and/or number, needs to be verified that it has not changed. If the problem persist then institution scripts needs to be updated. | | [107](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#107) | Retry Later | 500 | Institution script timed out. Please wait a few minutes and try again. Please retry again and if the problem persists, [escalate the issue](https://support.finicity.com/knowledge/articles/201750879/en-us?brand_id=85319&return_to=%2Fhc%2Fen-us%2Farticles%2F201750879#escalation) through the API. | | [108](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#108) | Re-Authenticate or Provide Consent | 500 | User action required at financial institution. Prompt the user to login to their account directly at the institution's website and follow the instructions there. This typically means that there is an unexpected notice for the customer at the website such as when the customer has to accept new terms or has been invited to participate in a program like e-statements. | | [109](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#109) | Re-Authenticate or Provide Consent | 500 | User action required at financial institution. Prompt the user to login to their account directly at the institution's website and follow the instructions there. This typically means that the customer institution is requiring that they change their security information like password or security questions. | | [110](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [111](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [112](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [113](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [114](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [115](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [116](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [117](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [118](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [119](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [120](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [121](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [122](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [123](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [124](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [125](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [126](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [127](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [128](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [129](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [130](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [131](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [132](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [133](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [134](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [135](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [136](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [137](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [138](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [139](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [140](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [141](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [142](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [143](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [144](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [145](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [146](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [147](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [148](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [149](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [150](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [151](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [152](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [153](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [154](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [155](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [156](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [157](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [158](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [159](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [160](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [161](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [162](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [163](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [164](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [165](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [166](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [167](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [168](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#data-mismatch-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [169](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#data-mismatch-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [170](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [171](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#171) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [172](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [173](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [174](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [175](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [176](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [177](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [178](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [179](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#179) | Retry Later | 500 | There are too many connections to the financial institution currently for the customer. It may help to have the customer log out of the financial institution website on any device they may have it open on. Otherwise trying again later when the additional connections have dropped automatically could help. If the issue persists submitting a support ticket is the recommended action. | | [180](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [181](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [182](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [183](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [184](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) | Data Connect Fix | 500 | Missing or incorrect MFA answer. One of your security questions (e.g. name of your first pet) has expired and needs to be answered. | | [186](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [187](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#187) | Re-Authenticate or Provide Additional Information | 500 | Missing or incorrect MFA answer. One of your security questions (e.g. name of your first pet) has expired and needs to be answered. | | [188](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [189](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [190](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [191](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [192](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [193](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [194](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#194) | Re-Authenticate or Provide Additional Information | 500 | Invalid MFA question. The MFA question doesn't match with the customer records. | | [195](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [196](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [197](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#197) | Re-Authenticate or Provide Additional Information | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [198](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [200](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [201](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [203](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [204](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#204) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [265](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#265) | Report or Escalate for Investigation | 500 | Owner information not available.​ | | [324](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/324/index.md) | Data Connect Fix | 500 | During the add account process an error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action.​ For already added accounts this means that the customer's account information has changed at the financial institution. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action to fix this issue. | | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | Retry Later | 500 | The account is currently being aggregated. Call the [Get Customer Account](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccounts) endpoint periodically to view the account status. The refresh operation is complete when `aggregationStatusCode` is 0 and `aggregationSuccessDate` is greater than or equal to `aggregationAttemptDate`.​ | | [331](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#331) | Re-Authenticate or Provide Additional information | 400 | The customer has taken too long to answer an MFA question. This error typically will not appear as we will prompt them to try again before the time runs out. The customer has 5 minutes to answer an MFA question. | | [341](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Re-Authenticate or Provide Additional Information | 400 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [342](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Re-Authenticate or Provide Additional Information | 400 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [343](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [344](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Re-Authenticate or Provide Additional Information | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [345](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Re-Authenticate or Provide Additional Information | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [403](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/403/index.md) | Verify Account or Data State | 500 | During the add account process an error occurred in the financial institution connection. Submitting a support ticket is the recommended action.​ For already added accounts this means that the customer's account information has changed at the financial institution. Submitting a support ticket is the recommended action to fix this issue.​ | | [417](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#417) | Retry Later | 500 | Error on transaction page. | | [418](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#418-and-419) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [419](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#418-and-419) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [500](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#500) | Retry Later | 500 | An unknown issue has interrupted our communication with your bank. Please try again. (500)​ | | [502](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#502) | Invalid Input | 500 | Invalid function. | | [503](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#503) | Retry Later | 500 | During getting URL, A timeout occurred while waiting for a response from the port specified. | | [504](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#504) | Retry Later | 500 | Error Connecting Account - Please Try Submitting Again. (504) | | [525](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#525) | Retry Later | 500 | During posting the parameter, a timeout occurred while waiting for a response from the port specified.​ | | [579](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#579) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [580](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#580) | Retry Later | 500 | Temporary connection issue for the financial institution. Wait a few minutes and try again. Submit a support ticket if the issue persists. | | [900](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#900) | Retry Later | 500 | This attempt has been logged. The connection to this financial institution is currently in the second phase of the creation process. Please attempt to log-in (up to 5 attempts in a row if possible) in order to store all the additional authentication information needed, then try again in 2-3 days. | | [901](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#901) | Retry Later | 500 | The connection to this financial institution is currently being created. Try again later. | | [902](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#902) | Retry Later | 500 | The connection to this financial institution is currently being created. Try again later. | | [903](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#903) | Retry Later | 500 | This attempt has been logged. The connection to this financial institution is currently in the second phase of the creation process. Please try again in 2-3 days. Each attempt will store information needed by engineering to continue to fix the connection. | | [904](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#904) | Retry Later | 500 | OTP handling created for new FI. New attempt needed to store cookie or whitelisting properly. | | [905](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#905) | Retry Later | 500 | If user specific issue or FI partially broken or FI completely broken and it is existing. Programmed to gather login credentials questions on attempt. | | [906](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#906) | Retry Later | 500 | If user specific issue or FI partially broken or FI completely broken and it is existing. Programmed to gather login credentials questions on attempt. | | [907](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#907) | Retry Later | 500 | If user specific issue or FI partially broken or FI completely broken. Existing code with OTP logging macro to gather HTML page info.​ This message will be updated to say, "There is a break in the connection between the user and the financial institution. Mastercard has logged the issue."​ | | [908](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#908) | Retry Later | 500 | Code used to indicate an FI is broken and currently being worked on. Can place this code while working on script to avoid unneeded tickets being submitted. E.g. Login URL hit is not possible through script or any type of posting is not possible. Login URL reloading multiple times OR FI is completely broken and need valid credentials to work further. | | [909](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#909) | Retry Later | 500 | An error occurred with the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [910](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#910) | Retry Later | 500 | Code used to indicate an FI is broken and currently being worked on. Can place this code while working on script to avoid unneeded tickets being submitted. E.g. Login URL hit is not possible through script or any type of posting is not possible. Login URL reloading multiple times OR FI is completely broken and need valid credentials to work further. | | [911](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#911) | Retry Later | 500 | An error occurred in the institution script. No accounts returned from script, due to a user specific issue or FI partially broken or FI completely broken and it is existing.​ | | ​​[913](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#913) | Verify Account or Data State | 500 | Account closed at the financial institution. | | [914](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#914) | Verify Account or Data State | 500 | We don't see the account. | | [915](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#915) | Retry Later | 500 | Institution not working for a specific user or group of users. We are gathering additional authentication information in order to enable the institution connection. The end user should attempt to log in up to 5 attempts in a row if possible to store all the additional authentication information needed since this is related to an MFA type where security question information needs to be stored.​ | | [916](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-ip/900-901-903-904-916/index.md#916) | Retry Later | 500 | Institution not working for a specific user or group of users. We are gathering additional authentication information in order to enable the institution connection. The end user should attempt to log in up to 5 attempts in a row if possible to store all the additional authentication information needed since this is related to an MFA type where security question information needs to be stored.​ | | [920](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | FI currently not supported, due to issue on FI. | | [921](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | Security Type not supported. Example Authenticate through mobile app, Cyber Token​. | | [922](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | When a Security code is present on FI that required matched with security device code or required to enter on security device (Not mobile) - Authenticator​. | | [923](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | Your financial institution is currently not supported. | | [924](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) | Retry Later | 500 | Google Captcha Not Supported​ | | [925](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) | Retry Later | 500 | Motion Captcha​.​ | | [926](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | Our financial institution is currently not supported. (926)​.​ | | [927](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | Aggregation/ Production IPs blocked by FI.​​ | | [928](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#924-925-and-928) | Retry Later | 500 | Aggregation Not Supported At FI e.g. FI has blocking temporarily.​​ | | [929](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#920-921-922-923-926-927-and-929) | Retry Later | 500 | Your financial institution is currently not supported. (929)​.​​ | | [931](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#931) | Re-Authenticate or Provide Additional Information | 500 | End user must refresh accounts and answer OTP every time they want updated data. | | [936](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#936)​ | Re-Authenticate or Provide Additional Information | 500 | The end user has a language preference other than English. This could potentially cause issues with the integration for this specific institution. Have the end user change their language preferences to English for their accounts in order to get the best experience.​ | | [938](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#938) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. | | [940](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#940) | Report or Escalate for Investigation | 500 | Broadcast Message like High security to be accepted to proceed OR completely stopped. | | [945](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#945) | Invalid Input | 500 | The account is migrated but not consented on OAuth. | | [946](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#946)​ | Data Connect Fix | 500 | The token has been accepted but no record has been returned from the institution for the request. This may be due to account closure. You can re-authenticate by going through [Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and/or a [refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) request. If that fails, submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm).​ | | [947](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#947) | Data Connect Fix | 500 | Your token is invalid or has expired, Please re-authenticate. | | ​[948](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#948) | Re-Authenticate or Provide Additional Information | 500 | The account has been migrated to OAuth and is waiting for the customer to authenticate. | | [949](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/949/index.md) | Re-Authenticate or Provide Additional Information | 404 | Accounts are in error status and can not be recovered in any way. Delete these accounts. | | [950](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#950) | Invalid Input | 500 | We do not currently support the requested report type for the selected institution. | | [951](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [952](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#952) | Verify Account or Data State | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [953](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [954](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [955](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#955) | Verify Account or Data State | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [959](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#959) | Re-Authenticate or Provide Additional Information | 500 | Financial institution requesting updated contact information.​ | | [960](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#960) | Verify Account or Data State | 500 | Electronic Statement is not available for the requested account. | | [961](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#961) | Re-Authenticate or Provide Additional Information | 500 | Enrollment Required for Paperless Statement/Activate Electronic Statement.​ | | [970](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#970) | Re-Authenticate or Provide Additional Information | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [971](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#971) | Re-Authenticate or Provide Additional Information | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [972](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#972) | Report or Escalate for Investigation | 500 | This request is not allowed for Aggregator. | | [973](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#973) | Re-Authenticate or Provide Additional Information | 500 | The user is not authorized for the requested resource or online access. | | [974](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#974) | Re-Authenticate or Provide Additional Information | 401 | Error during initial connection of accounts to the financial institution.​ | | [975](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#975) | Report or Escalate for Investigation | 500 | Bank has blocked access to resources for the user concerning security reasons. Please contact your Bank.​ | | [976](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#976) | Verify Account or Data State | 500 | Requested resource does not exist.​ | | [977](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#977) | Report or Escalate for Investigation | 500 | Service has reached the maximum limit or expired. | | [978](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#978) | Invalid Input | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [979](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [980](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [981](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#981) | Verify Account or Data State | 500 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [983](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-connection-errors) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [990](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [991](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [992](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [993](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [994](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [995](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#990-991-992-993-994-and-995) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [996](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#996-997-and-998) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [997](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#996-997-and-998) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [998](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#996-997-and-998) | Report or Escalate for Investigation | 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1007](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#1007) | Invalid Input | 500 | No transaction records found with specified date range while Aggregation. | | [1008](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md#1008) | | 4xx | Invalid Request for Boost-In-A-Box (BIAB) discovery process as request came for different profile with an existing OAuth customer. | | [1009](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1010](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1011](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1012](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [1403](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#1403) | Report or Escalate for Investigation | 500 | No eligible account was found for the end user. | | [1408](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#1408) | Retry Later | 4xx | The institution is undergoing scheduled maintenance. The institution is experiencing temporary technical problems. | | [1415](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#1415) | Invalid Input | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action.​ | | [1440](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#1440) | Retry Later | 4xx | Data Connect time out.​ | | [2001](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2001) | Invalid Input | 400 | Looks like your PDF is password protected. Unlock and upload the file again. | | [2003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2003) | Re-Authenticate or Provide Additional Information | 401 | An error occurred in the financial institution connection. | | [2005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#2005) | Invalid Input | 400 | An error occurred in the financial institution connection. Submitting a support ticket is the recommended action. | | [2006](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2006) | Retry Later | 500 | Consent was not provided. | | [2017](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2017) | Re-Authenticate or Provide Additional Information | 401 | The end user cancelled the consent request. | | [2018](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#2018) | Retry Later | 500 | An error occurred in the institution script. No accounts returned from script.​ | | [2024](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2024) | Retry Later | 401 | Error during initial connection of accounts to the financial institution. | | [2026](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2026) | Retry Later | 401 | The session to acquire consent has timed out. | | [2028](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2028) | Re-Authenticate or Provide Additional Information | 400 | The end user cancelled the consent request. | | [2030](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2030) | Re-Authenticate or Provide Additional Information | 500 | The end user didn't complete the enrollment flow. | | [2031](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2031) | Re-Authenticate or Provide Additional Information | 401 | The consent request session timed out. | | [2032](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#2032) | Verify Account or Data State | 500 | No eligible account was found for the end user. | | [2035](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2035) | Report or Escalate for Investigation | 401 | We are having problems connecting to your financial institution now. Please wait a moment and try again. | | [2036](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2036) | Report or Escalate for Investigation | 401 | We are having problems connecting to your financial institution now. Please wait a moment and try again.​​ | | [2037](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2037) | Re-Authenticate or Provide Additional Information | 401 | We are having problems connecting to your financial institution now. Please wait a moment and try again.​​ | | [2038](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2038) | Retry Later | 401 | We are having problems connecting to your financial institution now. Please wait a moment and try again.​​ | | [2039](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#2039) | Re-Authenticate or Provide Additional Information | 401 | To effectively use the product you are connecting, please provide all required consents - Profile Information/Statement. | | [2040](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/unexpectedloginerror/unexpectedloginerror/index.md#2040) | Retry Later | 401 | Error during initial connection of accounts to the financial institution.​ | | [3003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#3003) | Verify Account or Data State | 404 | Institution Login Id is not found. | | [3004](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#3004) | Verify Account or Data State | 404 | Institution Login Id details are not found. | | [4034](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#4034) | | 400 | Access tokens must be managed at the institution's website. | | [4041](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#4041) | Report or Escalate for Investigation | 500 | No eligible account was found for the end user. | | [5030](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/5030/index.md) | Re-Authenticate or Provide Additional Information | 400 | Unable to generate a report. The customer must have at least one account of type checking, savings, moneyMarket, cd, or investment. | | [6004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#6004) | Verify Account or Data State | 500 | Operation 'Request-type' is not supported by 'FI-Name'. | | [10000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10000) | Report or Escalate for Investigation | 500 | General System Error | | [10001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10001) | Invalid Input | 401 | Invalid credentials​. | | [10005](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10005) | Re-Authenticate or Provide Additional Information | 400 | Missing parameter. | | [10008](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#10008) | Verify Account or Data State | 500 | No eligible account was found for the end user. | | [10010](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#10010) | Re-Authenticate or Provide Additional Information | 500 | Subscriber is not authorized​. | | [10013](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#10013) | Invalid Input | 401 | Access Consent has expired for the current product of the account. | | [10022](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#10022) | Retry Later | 500 | Invalid (Finicity-App-Token). | | [10023](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/expiredsession/expiredsession/index.md#10023) | Retry Later | 401 | Invalid (Finicity-App-Token). | | [10030](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#10030) | Report or Escalate for Investigation | 500 | Unexpected system error​. | | [10046](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#10046) | Retry Later | 500 | The PDF statement could not be retrieved. | | [10047](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#10047) | Invalid Input | 500 | The PDF statement could not be retrieved. | | [10106](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#10106) | Invalid Input | 500 | No eligible account was found for the end user. | | [10814](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#10814) | Re-Authenticate or Provide Additional Information | 500 | Missing or incorrect MFA answer. One of your security questions (e.g. name of your first pet) has expired and needs to be answered. | | [11000](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#11000) | Report or Escalate for Investigation | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [12001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#12001) | Report or Escalate for Investigation | 500 or 503 | An unexpected error has occurred​. | | [12003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#12003) | Re-Authenticate or Provide Additional Information | 409 or 500 | MFA/OTP Encountered​. | | [12005](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#12005) | | 401 | Access Consent has expired for the current product of the account. | | [12008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#12008) | Invalid Input | 500 | Error while parsing payment routing response​. | | [12009](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#12009) | Invalid Input | 500 | Error while processing payment routing. | | [12015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#12015) | Invalid Input | 500 | Not found. | | [13002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#13002) | Invalid Input | 500 | Asset not found. | | [13004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#13004) | Report or Escalate for Investigation | 404 | File upload error​. | | [14001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14001) | Verify Account or Data State | 404 | Customer not found. | | [14002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14002) | Verify Account or Data State | 404 | Aggregation connect partner not found​. | | [14003](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14003) | Verify Account or Data State | 500 | Aggregation connect partner not found​. | | [14006](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14006) | Report or Escalate for Investigation | 404 | Institution not found. | | [14008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#14008) | Invalid Input | 404 | All dates must be epoch timestamps. | | [14019](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/consentauth/consentauthorization/index.md#14019) | Verify Account or Data State | 401 | Duplicate `loginField` entries.​ | | [14020](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#14020) | Verify Account or Data State | 400 | This service is not supported for payroll institutions.​ | | [14023](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#14023) | Invalid Input | 404 | Invalid Customer ID​. | | [14030](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#1000-1001-1002-1004-1005-1009-1010-1011-1012-and-14030) | Report or Escalate for Investigation | 400 or 500 | We have encountered an error in our internal system. Please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). | | [19000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#19000) | Retry Later | 500 | Account Owner Extraction service internal error. | | [20000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20000) | Verify Account or Data State | 500 | Account Routing Number not found.​ | | [20001](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20001) | Verify Account or Data State | 500 | Real account number not found​.​​ | | [20002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#20002) | Verify Account or Data State | 409 | Pay statement already exists for a given Asset ID.​​ | | [20003](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20003) | Retry Later | 500 | Create Pay Statement error​.​​ | | [20007](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/accounts-not-migrated/index.md#20007) | | 409 | Accounts for the `institutionLoginId` in the request are not allowed to migrate to new institution. | | [20009](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/accounts-not-migrated/index.md#20009) | | 500 | Accounts could not be migrated​. | | [20014](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#20014) | Report or Escalate for Investigation | 500 | Unable to refresh. | | [20015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20015) | Verify Account or Data State | 500 | Operation is not supported by financial institution. | | [20017](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20017) | Invalid Input | 500 | Customer search failed. | | [20020](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20020) | Invalid Input | 500 | Unsupported file type. | | [20024](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#20024) | Invalid Input | 404 | Invalid Routing Number​. | | [20025](https://developer.mastercard.com/open-finance-us/documentation/errors/request/badrequest/index.md#20025) | Report or Escalate for Investigation | 404 | Operation is not supported by financial institution. | | [20027](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#20027) | Verify Account or Data State | 500 | Real account number and Routing Number not found​. | | [20028](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#20028) | Verify Account or Data state | 404 | Invalid Real Account Number​. | | [20029](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#unknown-technical-errors) | Retry Later | 500 | An error occurred in the financial institution connection. Submitting a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) is the recommended action. | | [24302](https://developer.mastercard.com/open-finance-us/documentation/errors/request/api-auth-issue/index.md#24302) | Re-Authenticate or Provide Additional Information | 500 | For your security, we've locked your account. Please reset your password to continue. | | [24303](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#24303) | Re-Authenticate or Provide Additional Information | 500 | Invalid login credentials. | | [24553](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#24553) | Invalid Input | 404 | Transaction not found. | | [38003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38003) | Verify Account or Data State | 404 or 500 | Customer doesn't have given account.​ | | [38006](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38006) | Verify Account or Data State | 404 or 500 | Customer does not have any accounts associated with `institutionId`.​ | | [38007](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#38007) | Verify Account or Data State | 500 | Broadcast Message like High security to be accepted to proceed OR completely stopped.​ | | [38008](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#38008) | Invalid Input | 404 | Account details not found. | | [38053](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#38053) | Verify Account or Data State | 500 | Error while adding OAuth account | | [38054](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#38054) | Invalid Input | 400 | Error while processing image. | | [38056](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#38056) | Invalid Input | 400 | Invalid input data​. | | [38057](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#38057) | Verify Account or Data State | 404 | Money Transfer (ACH) details not found. | | [42000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42000) | Report or Escalate for Investigation | 400 | Testing customer limit exceeded. | | [42002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42002) | Report or Escalate for Investigation | 503 | Aggregation service is temporarily unavailable. Please try again later​. | | [42003](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42003) | Report or Escalate for Investigation | 403 | Testing customer should not add real accounts​. | | [42004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/invalidrequest/index.md#42004) | Report or Escalate for Investigation | 403 | Trouble communicating with servers. Billable customer should not add testing accounts. | | [44000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#44000) | Retry Later | 202 | Invalid App key. | | [44002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#44002) | Retry Later | 202 | Aggregation service is temporarily unavailable. Please try again later. | | [45002](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#45002) | Retry Later | 500 | Invalid login credentials. Prompt the user for a new password or have them reset it.​ | | [50024](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#50024) | Verify Account or Data State | | Institution does not support OAuth. | | [50025](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#50025) | Report or Escalate for Investigation | 500 | Oops, something went wrong. Try again in a few minutes.​ | | [50050](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#50050) | Report or Escalate for Investigation | 400, 404, or 500 | Oops, something went wrong. Try again in a few minutes. | | [90004](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#90004) | Invalid Input | 404 | Available balance has not been captured yet. | | [110002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#110002) | Invalid Input | 409 | Username is not available​. | | [110015](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#110015) | Report or Escalate for Investigation | 500 | Unexpected system error​. | | [110039](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#110039) | Re-Authenticate or Provide Additional Information | 500 | Invalid login credentials. Prompt the user for a new password or have them reset it.​ | --- # Tenant Screening Tutorial source: https://developer.mastercard.com/open-finance-us/documentation/tutorials/tenant-screening/index.md Mastercard Open Finance solutions assist with multiple steps of the tenant screening flow, enabling you to verify recurring income, check current balances and identify rental payment history before approving a rental application. For any tenant screening use case, we recommend you take the following steps: * verify an applicant's recurring **income** sources and amounts to ensure an applicant can afford a potential rent payment. * verify an applicant's current **balances** to ensure they have sufficient funds to cover a security deposit, first/last month rent requirements, etc. (optional) * verify an applicant's **transaction history** to confirm their rental history and measure payment consistency (optional)
Additionally, if you also wish to facilitate monthly rental payments via account to account payments reference the [Pay by Bank Tutorial](https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md) for more information. Note that while this tutorial explains how to get started with a tenant screening solution implementation, it assumes you have already gone through the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md). You will note that the additional steps explained below modify the primary experience highlighted in that guide to optimize for this specific use case. Additional information for the most common tenant screening products can be found in the [Lend](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) product section. ## Creating a Consumer {#creating-a-consumer} The most commonly used tenant screening products fall within the scope of Federal Credit Reporting Agency (FCRA) protections and regulations. After you have created a `customerId` on our platform, you must then create a a consumer record before you can generate and view CRA reports. Unlike a customer record, a consumer record cannot be deleted. A copy of the report created for a consumer will be available for six years. Unless stated otherwise, all Lend products require a consumer record. There is a one-to-one relationship between a customer record and a consumer record. Prior to connecting accounts or generating a report, use the below endpoint to create a `consumerId` on our platform: API Reference: `POST /decisioning/v1/customers/{customerId}/consumer` Reference the following for more in depth information about the specifics to [create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record. Note: When creating a consumer record, end user information must be provided by partners that are resellers. This is due to FCRA regulatory requirements.
## Mastercard Data Connect {#mastercard-data-connect} The next step is to have the customer grant permission to connect their data. This is done through the Mastercard Data Connect application. Data Connect supports linking bank accounts, payroll accounts, and uploading paystubs depending on the Data Connect experience used. See [the Data Connect documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) to learn more about the Data Connect experiences and how you can use them. Data Connect Full experiences are commonly used for Lend products. Below is a list of Data Connect Full experiences. The Financial Institution (FI) certification and other settings are configured for best results for the report type(s) mentioned. Use the self-service [Data Connect customization tool](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) within Client Hub or contact your Mastercard Account Manager for help configuring your Data Connect experience. Tip: If a product is not available within the Data Connect customization tool, you can use the basic Aggregation Data Connect experience type to have the customer connect bank accounts, then you can directly generate the report yourself via the API. Reference the Alternative Flows section below for more detail. To enable Data Connect, either embed a [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) into your experience, or [send a Data Connect email](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#send-data-connect-email) to the customer. For best results, in the on-ramp to Data Connect, prepare the customer by letting them know the benefits of digitally connecting their accounts and remind them what account types to connect. Once in Data Connect, the customer is prompted to link their accounts. If you have a use case where there are multiple customers applying for a loan jointly, you can use our [Data Connect Full -- Joint Borrower](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) flow. Multiple customer IDs and consumer IDs can be tied together to one Data Connect experience. Bank accounts are connected and linked to the customer/consumer record tied to the customer designated as the "primary" borrower. Payroll accounts are connected individually per borrower. For more information, see the [Data Connect application documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), and the [UX implementation best practices](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md). Note: We highly recommend including a `callbackUrl` in your Generate Data Connect URL request so we can send a webhook event informing you when report generation is complete to your [webhook listener](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-dc/index.md).
## Generating a Report {#generating-a-report} Your Mastercard Data Connect experience should be configured to automatically generate your preferred report or [Product Type](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#product-type) as soon as the customer completes the account connection flow. If you have configured a webhook listener, you will know the report is ready when a webhook notification with the `eventType` of `done` is sent. This will include the `customerId` and `id` for any generated reports. Store the report ID value as you will need it to get the report. ## Get Report(s) {#get-reports} All reports can be fetched once they are ready using the same Get Report endpoints. You need the ID of the report that was returned when you generated the report. Most reports can be retrieved in JSON or PDF formats. We recommend using the [Get Report by Report ID](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md#get-report-by-report-id) endpoint, which enables you to retrieve a report with the report ID alone without providing a customer or consumer ID. For other options, see [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). API Reference: `POST /decisioning/v3/reports/{reportId}`
### Verifying Income {#verifying-income} The [Verification of Income (VOI)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) report analyzes both active and inactive income streams, and then ranks them with a confidence score. It retrieves up to 24 months of validated banking data for an individual customer, based on the accounts they have permissioned to access. The following example shows a successful JSON response when requesting a VOI report: ```json { "id": "u4hstnnaewetr-voi", "customerId": 1000006677, "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "consumerDetails": { "id": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "firstName": "John", "middleName": "Doe", "lastName": "Jane", "address": "123 Marple Street", "city": "Anytown", "state": "PA", "zip": "17101", "phone": "5551234567", "ssn": "1234", "email": "john.doe@example.com" }, "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "sfb7xp4wer", "type": "voi", "status": "success", "createdDate": 1588350269, "customerType": "active", "title": "Mastercard Open Banking Verification of Income", "startDate": 1572625469, "endDate": 1588350269, "days": 200, "seasoned": true, "portfolioId": "dyr6qvqd2erw-1-port", "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1577986990, "name": "Checking", "type": "checking", "aggregationStatusCode": 0, "incomeStreams": { "id": "dens28i3vsch-voi1", "name": "none", "status": "ACTIVE", "estimateInclusion": "MODERATE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 14 }, "netMonthly": [ { "month": 1522562400, "net": 2004.77, "gross": 2400 } ], "netAnnual": 110475.7, "projectedNetAnnual": 0, "estimatedGrossAnnual": 0, "projectedGrossAnnual": 151609, "averageMonthlyIncomeNet": 9206.31, "averageMonthlyIncomeGross": 11300, "incomeStreamMonths": 18, "transactions": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck" } ] }, "balance": 714.16, "averageMonthlyBalance": 720.75, "transactions": [], "availableBalance": 714.16, "currentBalance": 714.16, "beginningBalance": 714.77, "miscDeposits": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck" } ] } }, "income": [ { "confidenceType": "MODERATE", "netMonthly": [ { "month": 1522562400, "net": 2004.77, "gross": 2400 } ], "averageMonthlyIncomeNet": 9206.31, "averageMonthlyIncomeGross": 11300, "incomeEstimate": { "netAnnual": 1000.12, "projectedNetAnnual": 1500.23, "estimatedGrossAnnual": 2000.12, "projectedGrossAnnual": 2500.23 } } ] } ``` How to read a VOI PDF report: [VOI_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOI_Report_HTR.pdf) (2MB) ### Balance Analytics {#balance-analytics} The [Balance Analytics (BA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) report provides insights into a customer's account balances over time, helping assess liquidity, trends, and potential risk for lending and portfolio decisions. BA analyzes up to 24 months of transaction history (as available) and returns attributes such as minimum, maximum, and average balances over the desired time intervals. The following example shows a successful JSON response when requesting a VOA report: ```json { "id": "u4hstnnak45g", "customerId": 1000006677, "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "consumerDetails": { "id": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "firstName": "John", "middleName": "Doe", "lastName": "Jane", "address": "123 Marple Street", "city": "Anytown", "state": "PA", "zip": "17101", "phone": "5551234567", "ssn": "1234", "email": "john.doe@example.com" }, "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "sfb7xp439w", "type": "voa", "status": "success", "createdDate": 1588350269, "constraints": { "accountIds": [ "1000535275", "1000535276" ], "fromDate": 1577986990, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true }, { "label": "loanType", "value": "car", "shown": false }, { "label": "vendorID", "value": "1613aa23", "shown": true }, { "label": "vendorName", "value": "PSC Finance", "shown": false } ], "showNsf": false }, "customerType": "active", "title": "Mastercard Open Banking Verification of Assets", "startDate": 1572625469, "endDate": 1588350269, "days": 180, "seasoned": false, "consolidatedAvailableBalance": 2345, "portfolioId": "dyr6qvqd2yhb-1-port", "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1588350276, "name": "Checking", "type": "checking", "availableBalance": 501.24, "aggregationStatusCode": 0, "balance": 501.24, "balanceDate": 1588350276, "averageMonthlyBalance": 501.02, "totNumberInsufficientFundsFeeDebitTxAccount": 0, "totNumberInsufficientFundsFeeDebitTxOver2MonthsAccount": 0, "totNumberDaysSinceMostRecentInsufficientFundsFeeDebitTxAccount": 120, "transactions": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "investmentTransactionType": "dividend", "normalizedPayee": "Finicity", "institutionTransactionId": "100000000", "category": "Paycheck", "bestRepresentation": "FINICITY INC PAYROLL" } ], "details": { "interestMarginBalance": -50000, "availableCashBalance": 1500, "vestedBalance": 300000, "currentLoanBalance": 0, "availableBalanceAmount": 1000, "marginBalance": 100, "currentBalance": 1000 }, "position": [ { "id": 637054, "currency": "USD", "symbol": "MCD", "securityName": "Common Stock", "units": 5, "marketValue": 1403.55, "currentPrice": 280.71, "securityType": "Stock" } ], "asset": { "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 } } }, "assets": { "type": "checking", "availableBalance": 1000, "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 } } ``` How to read a Balance Analytics PDF report: [Balance_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Balance_Analytics_HTR.pdf) (3MB) ### Verifying Transaction Histories {#verifying-transaction-histories} The [Transaction Consumer Reporting Agency (TACRA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/tacra/index.md) report provides details on up to 24 months of credit and debit transaction histories, without the account owner's information. You can also specify report constraints, such as which `accountIds` to include in the report, the `fromDate` and `toDate` for transaction filtering, and `includePending` parameters. The following example shows a successful JSON response when requesting a TACRA report: ```json { "id": "1000075473", "title": "Mastercard Open Banking Transactions Report", "customerType": "testing", "customerId": 1000018865, "consumerId": "a925b07c9e028c680ad9c1d18d2e7199", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "type": "transactions", "status": "success", "createdDate": 1594678007, "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "constraints": { "accountIds": [ "1000075473" ], "fromDate": 1578952809, "toDate": 1594677609, "includePending": true, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true }, { "label": "loanType", "value": "car", "shown": false }, { "label": "vendorID", "value": "1613aa23", "shown": true }, { "label": "vendorName", "value": "PSC Finance", "shown": false } ], "findTransaction": [ { "findTransactionDescriptionMemo": "Payment to PSC Finance", "findTransactionAmountFrom": -100.01, "findTransactionAmountTo": 200, "findTransactionCategory": [ "Payment", "Transfer" ] } ] }, "startDate": 1579348800, "endDate": 1594382400, "days": 174, "seasoned": false, "portfolioId": "wqbh0r2kbv5g-4-port", "institutions": [ { "id": 102105, "name": "FinBank Profiles - A", "urlHomeApp": "http://www.bank.example.com", "accounts": [ { "id": 1000075473, "number": "5015", "name": "Super Checking", "type": "checking", "availableBalance": 1000, "aggregationStatusCode": 0, "balance": 1000, "balanceDate": 1594676289, "transactionsCount": 2, "transactions": [ { "id": 100001490719, "amount": -99, "postedDate": 1594382400, "description": "ACH Withdrawal AMERICA FIRST CR", "normalizedPayee": "America First Cr", "institutionTransactionId": "0000000000", "category": "Transfer", "memo": "Payment to PSC Finance" }, { "id": 100001490897, "amount": 199.7, "postedDate": 1594123200, "description": "Payment to PSC Finance", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Payment", "memo": "TMOBILE debit" } ] } ] } ] } ``` Sample TACRA PDF report: [TACRA_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/TACRA_Example_Report.pdf) (2MB) #### Alternative Flow {#alternative-flow} Rather than having Data Connect auto-generate your report, you may prefer to generate the report creation at a later time. To do so, you can send the below request(s) for your customer: **Verification of Income (VOI):** API Reference: `POST /decisioning/v2/customers/{customerId}/voi`
**Balance Analytics (BA):** API Reference: `POST /decisioning/v2/customers/{customerId}/reports/balance-analytics/userTypes/{userType}`
**Transactions, CRA (TACRA):** API Reference: `POST /decisioning/v2/customers/{customerId}/transactions`
We also recommend listening for report webhook events for this scenario as a notification will sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). Finally, use the [Get Report by Report ID](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md#get-report-by-report-id) endpoint to obtain the report when ready using the `reportId`. ## Summary of Services {#summary-of-services} The table below summarizes the Open Finance services that are useful for common tenant screening scenarios. | Data Connect Product Type | Report(s) Generated | Included Data and Analytics | |--------------------------------------------------------------------------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------| | Verification of Income (VOI) | VOI | Deposit Income Streams, Account Ownership, Accounts Summary, Transaction History (up to 24 months) | | Verification of Assets (VOA) | VOA | Assets Summary, Non-Sufficient Funds Summary, Account Ownership, Accounts Summary, Transaction History (up to 12 months) | | Balance Analytics (BA) | Balance Analytics | Balance Analytics, Account Ownership, Transaction History (up to 24 months), Accounts Summary, Time Interval Type | | Verification of Income \& Employment with Credentialed Payroll (VOIE-Credentialed Payroll) | VOIE - Payroll | Employment Summary, Income Summary | | Verification of Assets \& Income (VOAI) | VOAI - Transactions | Deposit Income Streams, Non-Sufficient Funds Summary, Account Ownership, Accounts Summary, Transaction History (up to 24 months) | | Transactions (TACRA) | Transaction CRA | Transaction History (up to 24 months) | ## More Integration Tips {#more-integration-tips} ### Report Refresh {#report-refresh} Any report generation request for the same customer after the initial report is considered a refresh and returns updated data. A refresh is executed without re-engaging the customer via a client-initiated API call. To directly generate or refresh a report, use the report generation endpoint specific to that report - see [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md). The response includes the status of the report generation and a report ID which can be used to track the associated report webhooks and to get the report later. Refreshed reports default to the same parameters as the original report, unless specified otherwise. ### Order Reports Tool {#order-reports-tool} Our no-code Order Reports tool enables you to send Data Connect emails directly to consumers and view the generated reports without completing a direct integration. See [the Order Reports documentation](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) for details of how to access and use the tool. ### Test Profiles {#test-profiles} Test the APIs by connecting data using our test institutions and test accounts: see [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). Ensure the test profile you select contains account types that are supported by the report you will be ordering. --- # Managing Affiliates source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/managing-customers/index.md Alert: To use the Partner Direct Model via an API, you need to sign up for the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/). Users who do not have the permission to access the Mastercard Developers API will be directed to a page where they can request access. This section explains the various actions you can perform while managing your customers (how to get project details, add or delete credentials, and delete a project). You can either use the Mastercard Developers API or the Mastercard Developers Dashboard. ## Manage Using the Mastercard Developers API {#manage-using-the-mastercard-developers-api} To retrieve details of all projects available on your project dashboard, including the status of credentials, call [GET project/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/?view=api#getProjects). For example, you can call this endpoint to find out the status of your production access request for a project. Ensure you have the specific `project_id` that uniquely identifies your project. This `project_id` is shared with you when you create a project. Alternatively, you can find the `project_id` in the URI when accessing the specific project on the [Mastercard Developers Dashboard](https://developer.mastercard.com/dashboard). Once you onboard your affiliates, you can add a new set of credentials (`partnerId`, `secret`, and `appKey`) to their project by calling [POST /projects/{project_id}/credentials](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/?view=api#addCredentialToProject). To delete a project credential, call [DELETE /projects/{project_id}/credentials/{credential_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/?view=api#deleteProject). Once you delete a credential, they become inactive immediately and you can no longer use it to access the APIs. When deleting a credential, ensure your project has another active credential. Call [PUT /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/?view=api#updateProject) to update the following details in a project: * Project's `name`. * Name of the `company` on behalf of which the project is created. * `commercialCountries` - A list of countries where the service's customers are located. This field represents the countries where you can engage in business and is used to determine whether you are eligible to use a specific service or API in a geographic location. Note: A client `company` cannot be updated once it has been verified. To learn more about company verification, see the [Company Verification](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/managing-your-account/company-verification-via-connect-linking/) section of the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/). There may be times you need to delete an affiliate partner. For example, the affiliate partner may have been created in error or they no longer work with you. Call [DELETE /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) using the `project_id` designated to the customer. Alert: Deleting a project will immediately deactivate the customer's `partnerId` and other credentials. The affiliate customer will no longer be able to access Mastercard's Open Finance APIs. Mastercard Developers will send an email confirming that the requested customer has now been deleted. ## Manage Using the Mastercard Developers Dashboard {#manage-using-the-mastercard-developers-dashboard} To view the project details, go to the [project dashboard](https://developer.mastercard.com/dashboard) and click the required project to view its details. To add additional production credentials, click **Request Additional Credentials**. To delete credentials, click **Actions** next to the credentials and select **Delete Credentials**. Once you delete the credentials, you can no longer use them to access the APIs. When deleting a set of credentials, ensure there's another set of active credentials. 1. Go to the [project dashboard](https://developer.mastercard.com/dashboard). 2. Access the affiliate customer's project. 3. In the Project Management section, click **Delete Project**. --- # Guide for Processors - Requestor source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/processor/index.md As a third party processor you will be able to access particular Open Finance APIs in order to obtain consented data about an Open Finance partner's customer bank accounts. To do so you need the Open Finance partner to obtain a consent receipt and send it to you through some secure channel. This consent receipt allows you to obtain the appropriate information you need - for example, to fetch the necessary ACH routing details for a customer's bank account so that you can process a payment. * [Processor (recipient) steps](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/processor/processor-steps/index.md) --- # Payment Success Indicator source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md Note: This documentation has been updated to describe the latest PSI endpoints which add support for an unauthorized return score. For details of the legacy endpoints, see [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md). Payment Success Indicator (PSI) enables you to reduce failed account-to-account payments by delivering two predictive risk scores through a unified API endpoint. One score assesses the likelihood of non-sufficient funds (NSF), and the second score evaluates the risk of unauthorized returns. By leveraging PSI, you can improve payment success rates, reduce return costs and enhance the overall consumer experience. ## Contents {#contents} * [How PSI Works](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/how-psi-works/index.md) - overview of versions and risk scores * [PSI Non-FCRA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md) - technical details for non-FCRA version * [PSI FCRA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md) - technical details for FCRA version * [Historical Data Sharing](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/historical-data-sharing/index.md) - sharing payment outcome data (required) * [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md) - documentation for older endpoints ## Benefits {#benefits} With PSI, you can: 1. Proactively reduce failed payments by assessing the risk of non-sufficient funds or unauthorized returns before submitting a transaction. 2. Embed a seamless, real-time risk check directly into your payment flow via a unified API. 3. Optimize payment timing, routing, or method by using predictive insights to improve success rates and enhance customer satisfaction. ## Use Cases {#use-cases} PSI helps US partners manage and reduce ACH return rates, specifically for R01 (non-sufficient funds) and R10 (unauthorized fraud) return codes, which are regulated by [NACHA](https://www.nacha.org/content/about-us) and subject to compliance thresholds. Exceeding these thresholds can lead to fines or restrictions with ACH processing. Common use cases include: * **Account Funding \& Wallets:** Reduce failed deposits by verifying risk before initiating ACH funding or wallet top-ups and transfers. * **Bill Payments \& Subscriptions:** Improve recurring payment success for utilities, telecom, and other service providers. * **Ecommerce \& Digital Transactions:** Reduce fraud and return rates on high-risk transactions. * **Financial Services**: Support secure loan repayments, disbursements, and brokerage transfers. * **Insurance \& Healthcare:** Ensure timely premium payments, reimbursements, and patient payments by avoiding return scenarios. * **Government \& Public Services:** Enable reliable ACH disbursements for benefits and tax-related payments. --- # Account Statements source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-statements/index.md The Account Statements service retrieves a customer's Financial Institution (FI) statements. These statements contain transaction summaries, balances, and additional details available in PDF format. The information retrieved depends on what is made available by the FI. Some FIs provide consolidated statements, where details for multiple accounts will be returned in the same document if the customer has more than one account with the FI. There are two ways to retrieve statements: By customer and account ID: : * Use the [Get Customer Account Statement](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccountStatement) endpoint to retrieve a statement by customer ID and account ID. By asset ID (beta - limited FI support): : * Use the [Get Customer Account Multiple Statement Details](/documentation/api-reference/##GetCustomerAccountMultipleStatement) endpoint to retrieve a list of available statements for a customer, identified by asset IDs. Then use an asset ID with the [Get Asset by Customer and ID](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetAssetByCustomerID) endpoint to retrieve a statement in PDF format. Note: Retrieving statements is a billable service, where a charge is incurred for each successfully retrieved statement PDF. You can retrieve the list of available statements and their corresponding asset IDs without incurring any charge. A charge is only made when you successfully download a PDF statement. Tip: To retrieve a statement successfully, verify the account has aggregation status 0 before initiating statement retrieval. If the account has any other aggregation status code, the request will fail. ## Use Cases {#use-cases} * **Accounting** - To ensure the accuracy of accounts for reporting. * **Pre-lending underwriting** - Ensures lenders have an accurate view of a borrower's profile to ensure a high chance of success with an underwriter. ## How It Works {#how-it-works} This section explains how to retrieve statements using the **Get Customer Account Statement** endpoint. 1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials). 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token). 3. Create a customer and link them to at least one account with Data Connect. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer). * You can use any of the test [Bank Account Profiles](https://developer.mastercard.com/open-finance-us/documentation/test-the-apis/index.md#bank-account-profiles) that is listed as supporting `state_agg` to create a test customer with multiple available statements - for example, **profile_08**. * Note the `id` of the customer - this is the `customerId` you will use below. 4. You can use the [Get Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCertifiedInstitutions) endpoint to check if the FI supports retrieving statements using an FI name for the `search` parameter (for example, "finbank" for the test FI in Sandbox) and `stateAgg` as the `type` parameter. If retrieving statements is supported, the response will have a `stateAgg` value of `true`. 5. Call [Refresh Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#refresh-customer-accounts) with the `customerId` to perform an initial aggregation and see a list of their accounts. * This returns the `aggregationStatusCode` of the accounts which must be `0` to retrieve a statement. * Note the `id` of a valid account - this is the `accountId` you will use in the next step. 6. Call [Get Customer Account Statement](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccountStatement) with the `customerId` and `accountId`. * Using the `index` parameter you can request older statements: an `index` value of `1` returns the most recent statement, `2` returns the statement from the previous month and so on. The maximum supported value is `24`. * The recommended timeout period for requesting statements is 180 seconds. 7. The requested statement is returned as a PDF. * Note that successful calls to this endpoint are billable in production. Diagram statements ## APIs {#apis} Warning: All the endpoints below can return HTTP status code 203 when the response contains an MFA challenge question in JSON format. For most use cases, you should treat this as a failure. ### Retrieve Statements by Customer and Account ID {#retrieve-statements-by-customer-and-account-id} This is the recommended method to retrieve statements using a customer ID and account ID. Successful calls to this endpoint are billable. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/statement`
### Retrieve Statements by Asset ID (beta) {#retrieve-statements-by-asset-id-beta} Warning: This method currently supports a limited range of FIs compared to the **Get Customer Account Statement** endpoint above. Even if **Get Certified Institutions** reports that retrieving statements is supported for an FI, the **Get Customer Account Multiple Statement Details** endpoint may not provide statements. In this case, you will receive a 500 error. We are currently working to expand the range of supported institutions. Call the following endpoint to obtain details of the available statements (including the dates they cover) and asset IDs for the statement PDFs you can download. Calls to this endpoint are free of charge. API Reference: `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/statement` Once you have obtained the ID of a statement you want to fetch, call the following endpoint (passing the relevant asset ID) to download the PDF asset required. Successful calls to this endpoint are billable. API Reference: `GET /aggregation/v1/customers/{customerId}/assets/{assetId}`
--- # Integration source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/index.md Mastercard Data Connect Components consists of a web SDK which provides a collection of custom web components that can be used to build login forms for legacy institutions, initiate OAuth authentication flow for institutions, and render Multi-Factor Authorization challenges encountered during legacy institution login. There are also a small number of REST API endpoints which are used to create a login form or OAuth URL, or to initiate a reconnection (Data Connect Fix) flow. These endpoints return elements that are used with the SDK web components. Optionally, you can also create a configuration object that can be used within the login flow to specify that, for example, only certain account types will be shown. We also provide details of how to implement Data Connect Components within a React Native app, and how to implement webhooks. * [Web integration using the Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md) * [React Native integration](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/react-native/index.md) * [Using webhooks with Data Connect Components](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebhooks/index.md) * [Examples](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccexamples/index.md) --- # MVS Events List source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-mvs/index.md ## employerFound {#employerfound} | Name | Mastercard Data Connect Support | Description | |---------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | employerFound | Generate Data Connect Full / Fix / Data Connect Full -- Joint Borrowers | Sent when employment records matching the customer's Social Security number (SSN) and date of birth (DOB) are found in the payroll providers. | * JSON ```JSON { "customerId": "1013916100", "consumerId": "06a46d02b9851829ca53946be1da8200", "eventType": "employerFound", "eventId": "1602696485261-d299df6440556091e1d0531c", "payload": { "numEmployers": 1 } } ``` ## employerNotFound {#employernotfound} | Name | Mastercard Data Connect Support | Description | |------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------| | employerNotFound | Generate Data Connect Full / Fix / Data Connect Full -- Joint Borrowers | Sent when the customer's SSN and DOB don't match any employment records from the payroll provider. | * JSON ```JSON { "customerId": "1013916100", "consumerId": "06a46d02b9851829ca53946be1da8200", "eventType": "employerFound", "eventId": "1602696485261-d299df6440556091e1d0531c", "payload": { "numEmployers": 1 } } ``` ## payrollAccountsAdded {#payrollaccountsadded} | Name | Mastercard Data Connect Support | Description | |----------------------|-------------------------------------------------------------------|--------------------------------------------------------------------------------------| | payrollAccountsAdded | Generate Data Connect Full / Data Connect Full -- Joint Borrowers | Sent when the user completes the credentialed payroll account connection experience. | * JSON ```JSON { "customerId": "1013916100", "consumerId": "06a46d02b9851829ca53946be1da8200", "eventType": "payrollAccountsAdded", "eventId": "1602696485261-d299df6440556091e1d0531c", "payload": { "payrollAccountIds": [ "0193d0ab-9473-3e6d-58d2-039d6dafda45" ] } } ``` ## payrollError {#payrollerror} | Name | Mastercard Data Connect Support | Description | |--------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | payrollError | Generate Data Connect Full / Fix / Data Connect Full -- Joint Borrowers | Sent when an error occurs while making a request to the payroll connector service. The error code and message are included in the response payload. | Error Codes: * 400: The consumer record doesn't match the Social Security number (SSN) and date of birth (DOB) passed to Data Connect. * 500: An unexpected error has occurred. * JSON ```JSON { "customerId": "1013916100", "consumerId": "06a46d02b9851829ca53946be1da8200", "eventType": "payrollError", "eventId": "1602696010692-ac29d9e8e1dbeee869e1b46d", "payload": { "error": 400, "message": "Please provide valid ssn and date of Birth for customer 1013916100" } } ``` ## payrollSearch {#payrollsearch} | Name | Mastercard Data Connect Support | Description | |---------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | payrollSearch | Generate Data Connect Full / Fix / Data Connect Full -- Joint Borrowers | Sent when the customer enters their SSN and DOB to search for their payroll information. | * JSON ```JSON { "customerId": "1013916100", "consumerId": "06a46d02b9851829ca53946be1da8200", "eventType": "employerFound", "eventId": "1602696485261-d299df6440556091e1d0531c", "payload": { "numEmployers": 1 } } ``` --- # Deposit Switch and Bill Pay Switch source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md Deposit Switch and Bill Pay Switch use a special version of the Data Connect experience called Connect Transfer. This enables consumers to easily give permission to switch regular deposits or payments to a different bank account, reducing the friction of changing accounts. * [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md) -- enable consumers to easily switch their payroll deposit to a new account. * [Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md) -- enable consumers to switch recurring automatic payments to a new account. The Connect Transfer flow allows the consumer to connect to payroll providers (for Deposit Switch) or merchants / service providers (Bill Pay Switch), as well as to their bank account, so they can give all the necessary permissions simply and easily. For example, you can use Deposit Switch to allow a new banking customer to easily authorise the payment of their salary into their new bank account. With Bill Pay Switch, the customer can also move their recurring payments (for example, their Netflix subscription, their Amazon or Apple account, or other regular bill payments). For Connect Transfer we supply iOS, Android and React Native SDKs (the regular Data Connect SDKs do not support the Connect Transfer functionality): * [Connect Transfer Mobile SDKs](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) -- learn how to integrate into your mobile apps.
Note: Deposit Switch can be implemented either for mobile (using our Connect Transfer SDKs for mobile) or web (using our Web SDK). Bill Pay Switch is currently only available for mobile applications. This is due to the TrueAuth device-based login used for authentication during the Bill Pay Switch flow. We also recommend that you view the following sections of our [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) for more details of the user flow and user experience and design tips. * [Experience Design Guide section on Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md) * [Experience Design Guide section on Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/bill-pay-switch/index.md) --- # Account Aggregation source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md Account Aggregation Services provide account information like balance, account type and account name. After an account is added to the system, basic account data is immediately available. To access more detailed data and transaction history, you must do an initial aggregation [refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) on the account. This first-time aggregation operation retrieves up to 6 months of transaction data from the financial institution for traditional accounts (possibly longer for certain liability account types where the history of data is supported by the financial institution). Note: It is recommended to pull data daily to maintain up-to-date account information. Alternatively, you can subscribe to [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) notifications, which allows Mastercard to send changes to account data to your webhook listener. ## Use Cases {#use-cases} * Budgeting apps. * Analyzing a customer's cash flow. * Rounding up the customer's transactions by small amounts to add to savings or to make contributions to charity. ## How It Works {#how-it-works} The accounts that a customer grants access to during the Mastercard Data Connect flow determine what data you can access. The account data returned depends on the account type of the `accountId` referenced in the API call. 1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials). 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token). 3. Create [a customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and [link them to at least one account via Connect](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-3---generate-mastercard-data-connect-url). See the different [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) and account types available to test with. 4. You can now use the Account Aggregation Services below for that customer. ## Account Aggregation Services {#account-aggregation-services} After a customer has added accounts in [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), the account data can be retrieved using the Account Aggregation Services. Depending on the amount of data needed, Mastercard offers various data access options. There are two different payment models: * Data Access Tiers - a pay-per-use model where you are charged for the level of access you use for each customer: * Tier 1: Account Simple Details (ASD) - basic account information * Tier 2: Account Full Details (AFD) - expanded account information including balances and available credit * Tier 3: Account Transaction Details (ATD) - adds transaction data; see [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) for details * Standalone services - conventional subscription options: * Account Limited Aggregation (ALA) - expanded account information equivalent to Account Full Details (Tier 2 above) * Transaction Aggregation (TAU) - adds transaction data; see [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) for details
See the [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) page for more information about the different data access tiers available. Tip: You must use the correct endpoints for account aggregation and refresh, depending on whether you use Data Access Tiers or standalone services. See [Data Refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) for details of the correct data refresh endpoints. ### Account Simple Details (ASD) {#account-simple-details-asd} The ASD (Data Access Tier 1) option provides limited account data for a single customer, refreshed daily. #### **Get Customer Account by ID (Simple)** {#__get-customer-account-by-id-simple__} Use Get Customer Account by ID (Simple) to retrieve data from a specific account. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/simple` #### **Get Customer Accounts (Simple)** {#__get-customer-accounts-simple__} Use Get Customer Accounts (Simple) to retrieve data from all of a customer's accounts. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/simple` #### **Get Customer Accounts by Institution ID (Simple)** {#__get-customer-accounts-by-institution-id-simple__} Use Get Customer Accounts by Institution ID (Simple) to retrieve data from all of a customer's accounts by institution ID. API Reference: `GET /aggregation/v1/customers/{customerId}/institutions/{institutionId}/accounts/simple` #### **Get Customer Accounts by Institution Login ID (Simple)** {#__get-customer-accounts-by-institution-login-id-simple__} Use Get Customer Accounts by Institution Login ID (Simple) to retrieve data from all of a customer's accounts by institution login ID. API Reference: `GET /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts/simple` Use Get Customer Account by ID (Simple) to retrieve data from a single customer account, or Get Customer Accounts (Simple) to retrieve data from all of a customer's accounts. Accounts can be filtered by institution using the Get Customer Accounts by Institution (Simple) endpoint, or by institution login-set using the Get Customer Accounts by Institution Login ID (Simple) endpoint. These variations enable a customizable user experience and greater account organization. ### Account Full Details (AFD) or Account Limited Aggregation (ALA) {#account-full-details-afd-or-account-limited-aggregation-ala} AFD (Data Access Tier 2) and ALA (standalone) both provide complete account data for a customer. This includes all the data provided in the Tier 1 ASD service, as well as expanded information relevant to the account type, which may vary by institution. #### **Get Customer Account by ID** {#__get-customer-account-by-id__} Use Get Customer Account by ID to retrieve data from a specific account. API Reference: `GET /aggregation/v2/customers/{customerId}/accounts/{accountId}` #### **Get Customer Accounts** {#__get-customer-accounts__} Use Get Customer Accounts to retrieve data from all of a customer's accounts. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts` #### **Get Customer Accounts by Institution ID** {#__get-customer-accounts-by-institution-id__} Use Get Customer Accounts by Institution ID to retrieve data from all of a customer's accounts by institution ID. API Reference: `GET /aggregation/v1/customers/{customerId}/institutions/{institutionId}/accounts` #### **Get Customer Accounts by Institution Login ID** {#__get-customer-accounts-by-institution-login-id__} Use Get Customer Accounts by Institution Login ID to retrieve data from all of a customer's accounts by institution login ID. API Reference: `GET /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts` Use Get Customer Account by ID to retrieve data from a single customer account, or Get Customer Accounts to retrieve data from all of a customer's accounts. Accounts can be filtered by institution using the Get Customer Accounts by Institution ID endpoint, or by institution login-set using the Get Customer Accounts by Institution Login ID endpoint. These variations enable a customizable user experience and greater account organization. ## Delete Accounts {#delete-accounts} Removal of accounts is made easy with two endpoints. Delete Customer Account will remove a specified account from aggregation while Delete Customer Accounts by Institution Login ID will remove the specified set of accounts relating to a particular FI login ID. #### **Delete Customer Account** {#__delete-customer-account__} API Reference: `DELETE /aggregation/v1/customers/{customerId}/accounts/{accountId}` #### **Delete Customer Account by Institution Login ID** {#__delete-customer-account-by-institution-login-id__} API Reference: `DELETE /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}` --- # Custom Event Data source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-custom/index.md There are two different objects you can use to receive information while the customer is interacting in a Mastercard Data Connect or Joint Borrower session on a mobile app or web pages. * [webhookData Object](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-custom/index.md#webhookdata-object) * [webhookHeaders Object](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-custom/index.md#webhookheaders-object) ### webhookData Object {#webhookdata-object} If you pass the `webhookData` object in the [Generate Data Connect URL APIs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md), you'll receive the object back in the body for all other Data Connect event types. **Example:** Pass the `webhookData` object in a Generate Data Connect URL call to receive the `started` event notification. * JSON ```JSON "webhookData": { "unquiqueCustomerId": "123456789", "uniqueRequestId": "234567890" } ``` * JSON ```JSON { "customerId":"1005061234", "consumerId":"86238nvnw7269e224a4e3de12352d87d", "eventType":"started", "eventId":"1495468585434-0e73d1719173766fe4dfe1a8", "payload":{}, "webhookData": { "unquiqueCustomerId": "123456789", "uniqueRequestId": "234567890" } } ``` ### webhookHeaders Object {#webhookheaders-object} Passing the `webhookHeaders` object provides similar custom return behavior for every webhook event. However, it returns the results in the header instead of the body of the event. * JSON ```JSON "webhookHeaders": { "webhookServerKey": "sadf67ewrkh", "webhookCustomerSignature": "91l;kj234924987lj" } ```
* JSON ```JSON { "partnerId": "PARTNER_ID", "customerId": "CUSTOMER_ID", "type": "aggregation", "webhookData": { "unquiqueCustomerId": "123456789", "uniqueRequestId": "234567890" }, "webhookHeaders": { "webhookServerKey": "sadf67ewrkh", "webhookCustomerSignature": "91l;kj234924987lj" } } ``` For details of the events for Report webhooks see [Data Connect Report Events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-dc/index.md).
--- # Report Events (Data Connect) source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-dc/index.md Data Connect report webhook notifications are sent for reports generated via Data Connect. Note: When a report is generated through [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), notifications are sent to the webhook URL specified when you generated the [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). ## done {#done} | Name | Mastercard Data Connect Support | Description | |------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | done | Generate Data Connect Full / Fix / Data Connect Full -- Joint Borrowers | Sent after all pending reports are completed. If you request more than one report, the payload is an array of information for each report requested. | * JSON ```JSON { "customerId": "5019498180", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "eventType": "done", "eventId": "1639513582789-f1b8ba9bc325dfbe78aa09d4", "payload": [ { "portfolioId": "2z2ght9p54kt-1-port", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "customerId": 5019498180, "eventName": "done", "id": "ue9s2g6je4j9", "type": "voa", "consumerSsn": "6666", "status": "success" }, { "portfolioId": "2z2ght9p54kt-3-port", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "customerId": 5019498180, "eventName": "done", "id": "8tu59in6s3xy-voi", "type": "voi", "consumerSsn": "6666", "status": "success" }, { "portfolioId": "2z2ght9p54kt-2-port", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "customerId": 5019498180, "eventName": "done", "id": "bj0ru3yy55yz-voi", "type": "voi", "consumerSsn": "6666", "status": "success" } ], "eventTrigger": "userSubmit" } ``` ## failed {#failed} | Name | Mastercard Data Connect Support | Description | |--------|-------------------------------------------------------------------|---------------------------------------------| | failed | Generate Data Connect Full / Data Connect Full -- Joint Borrowers | Sent after a report has failed to generate. | * JSON ```JSON { "id":"reportId", "eventName": "failed", "consumerId": "conId", "consumerSsn": "conSSN", "type": "reportType", "status": "failure", "customerId": 123, "portfolioId": "asdf-1-port" } ``` ## generating {#generating} | Name | Mastercard Data Connect Support | Description | |------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| | generating | Data Connect Full with MVS enabled | Sent when the verification report starts generating. If you request more than one report, the payload is an array of information for each report. | * JSON ```JSON { "customerId": "5019498180", "eventType": "generating", "eventId": "1639513249775-192b6cf1aa025e1b5a1255c2", "payload": [ { "id": "ue9s2g6je4j9", "portfolioId": "2z2ght9p54kt-1-port", "customerType": "testing", "customerId": 5019498180, "requestId": "35fuuudwh8", "requesterName": "AcmeLending", "createdDate": 1639513248, "title": "Verification of Asset and Income - Transactions", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "consumerSsn": "6666", "constraints": {}, "type": "voa", "status": "inProgress", "reportId": "ue9s2g6je4j9" }, { "id": "8tu59in6s3xy-voi", "portfolioId": "2z2ght9p54kt-3-port", "customerType": "testing", "customerId": 5019498180, "requestId": "zvhz6sqfs9", "requesterName": "Acmelending", "createdDate": 1639513248, "title": "Verification of Income", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "consumerSsn": "6666", "type": "voi", "status": "inProgress", "source": "Connect", "reportId": "8tu59in6s3xy-voi" }, { "id": "bj0ru3yy55yz-voi", "portfolioId": "2z2ght9p54kt-2-port", "customerType": "testing", "customerId": 5019498180, "requestId": "1uv91guu71", "requesterName": "AcmeLending", "createdDate": 1639513248, "title": "Verification of Income and Employment", "consumerId": "093e1794ca8a646ce9901edcd43160a1", "consumerSsn": "6666", "type": "voi", "status": "inProgress", "source": "Connect", "reportId": "bj0ru3yy55yz-voi" } ], "eventTrigger": "userSubmit" } ``` ## inProgress {#inprogress} | Name | Mastercard Data Connect Support | Description | |------------|-------------------------------------------------------------------|-----------------------------------------------------------------------| | inProgress | Generate Data Connect Full / Data Connect Full -- Joint Borrowers | Sent when a report is being generated and has an `inProgress` status. | * JSON ```JSON { "id":"reportId", "eventName": "inProgress", "consumerId": "conId", "consumerSsn": "conSSN", "type": "reportType", "status": "inProgress", "customerId": 123, "portfolioId": "asdf-1-port" } ``` --- # Transaction Data source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md The Transaction Data Services provide account transaction data. Options vary depending on the length of transaction history required, and data refresh schedule. Newly added customer accounts require a successful [refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) before transaction data will be available. The refresh will occur automatically during Mastercard's overnight batch process, or a manual refresh can be performed by using the refresh endpoints. Ensure you use the correct refresh endpoint depending on whether you are using data access tiers or not. Although Transaction Aggregation data refreshes daily, you may sometimes need more recent data. Transaction Aggregation can be refreshed using the endpoints described in [Data Refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md). After initiating the refresh endpoint, use Transaction Aggregation to retrieve any new transactions. Ensure accounts are correctly aggregating with an `aggregationStatusCode` equal to 0 and a recent `aggregationSuccessDate` timestamp. Refresh may be unsuccessful if an account is not indicated as ready for aggregation. ## How It Works {#how-it-works} The accounts that a customer grants access to during the Mastercard Data Connect flow determine what data you can access. The transaction data returned depends on the account type of the `accountId` referenced in the API call. 1. Generate the required credentials to call the API. See [Create a Sandbox Project](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#create-a-sandbox-project). 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token). 3. Create [a customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and [link them to at least one account via Connect](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-3---generate-mastercard-data-connect-url). See the different [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) and account types available to test with. 4. You can now use the Transaction Data Services below for that customer. ## Transaction Data Services {#transaction-data-services} After a customer has added accounts in Data Connect, transaction data can be retrieved using one of two Transaction Data Services. * If you are using Data Access Tiers, you can use the Account Transaction Details (ATD) service (Tier 3) * If you prefer a standalone service, you can subscribe to Transaction Aggregation (TAU) The transaction details in the response, including Mastercard transaction categorization data, may vary depending on the account type and institution. Warning: To accurately identify a specific transaction, best practice is to ensure you use the unique transaction ID (`uniqueTransactionId`) which is returned as part of the transaction data, rather than the simple transaction ID value (`id`). This avoids any potential problems caused by the same transaction ID being used with more than one customer (you could also ensure such problems do not occur by ensuring you check both the `id` and `accountId` values.) ### Account Transaction Details (ATD) or Transaction Aggregation (TAU) {#account-transaction-details-atd-or-transaction-aggregation-tau} ATD (Data Access Tier 3) and TAU (standalone) both provide historical transaction data for up to 180 days in addition to the full account data included in AFD (Tier 2) or ALA (standalone). The transaction data is refreshed daily with the previous 15 days to accommodate any changes made to transactions reported earlier by the financial institutions. This standard 15 day transaction refresh window is called the Transaction Lookback Period, and may be longer for certain liability account types. #### Get Customer Account Transactions {#get-customer-account-transactions} Use Get Customer Account Transactions to retrieve transaction data from one of a customer's accounts. API Reference: `GET /aggregation/v4/customers/{customerId}/accounts/{accountId}/transactions` #### Get Customer Transaction by Unique ID {#get-customer-transaction-by-unique-id} Use Get Customer Transaction by ID to retrieve data from a specific transaction. API Reference: `GET /aggregation/customers/{customerId}/transactions/{uniqueTransactionId}` #### Get All Customer Transactions {#get-all-customer-transactions} Use Get All Customer Transactions to retrieve transaction data from all of a customer's accounts, within a specified date range. This endpoint supports paging up to 1,000 records per request. If the value of `moreAvailable` in the response is `true`, the next page of results can be retrieved by increasing the value of the start parameter in the next request. API Reference: `GET /aggregation/v3/customers/{customerId}/transactions` The transaction response is sorted based on the following hierarchy of date availability: | Logic | Sorting Value | |---------------------------------------------------------|-----------------| | transactionDate is provided | transactionDate | | transactionDate is not provided, postedDate is provided | postedDate | | transactionDate and postedDate are not provided | effectiveDate | There is no maximum window between fromDate and toDate; however, the transactions that are returned after the initial aggregation are limited by the standard 180 day aggregation window, the financial institution, and the max 1,000 records. A minimum time period of 15 days, or otherwise matching the length of the Transaction Lookback Period, is recommended to pick up any changes to previously reported transactions. To extend the standard 180 day aggregation window, use the Load Historic Transactions endpoint, and then use the Get Customer Transactions All endpoint again. Best practice is to pull Transaction Aggregation data daily to maintain current data. Another option is to subscribe to [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) notifications, which allows Mastercard to send changes to Transaction Aggregation data to the Partner's event listener. If you are caching transaction data use the transaction ID along with the `accountId` or `customerId` when querying cached data. This avoids any potential problems caused by the same transaction ID being used with more than one customer. It is common for traditional financial institutions to alter transaction data as far back as 15 days, to resolve balance changes, pending status, transaction errors, etc. #### Load Historic Transactions {#load-historic-transactions} This service provides historical transaction data for up to 24 months, depending on the account type and whether the financial institution has made this level of historic data available. This service does not include a daily refresh or TxPUSH notifications; however, data may be refreshed by calling the endpoint again. API Reference: `POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions/historic` After using the endpoint, use [Get Customer Account Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#get-customer-account-transactions) or [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#get-all-customer-transactions) to retrieve the data. --- # Register Applications source: https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md Applications are computer programs developed for web or mobile devices by you, our Partners. You must register each of your applications so that customers can identify your application name and logo in the process flow of [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). The permissions that a customer gives when permissioning access to an account are specific to your application and to the specific financial institution (FI). Alert: If you have a single application that needs to be registered, you do not need to use the Application Registration API described below. Instead, simply contact your Customer Success Manager to manage this process for you. If you are planning on registering multiple applications, use the Application Registration API, and contact your Customer Service Manager or Systems Engineer if you need additional help. After your applications are registered, they are registered with all current legacy FIs and any current or future OAuth FIs as they become available. Since some FIs take longer than others to register, we recommend that you start registering your applications as soon as possible. ## How It Works {#how-it-works} 1. Generate the required credentials to call the APIs. See [Generate Your Credential](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials). 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token). 3. Call `POST /aggregation/v1/partners/applications` with a `appName`, `appDescription` and other required fields to initiate the registration process and return a `preAppId` 4. To check the status of your submitted application, call `GET /applications` with a `preAppId`. 5. To modify any details regarding your application, call `PUT /aggregation/v1/partners/applications/{preAppId}` with a `preAppId` as a query parameter and the updated details in the payload. 6. To check the status of your application's registration with a financial institution, call `GET /applications/{application_id}/institutions` 7. To assign specific customers to an application, call `POST /aggregation/v1/partners/applications` with `customerID` and `applicationID`. ## Application APIs {#application-apis} Use the APIs to register new applications to access FIs with OAuth connections. You can also modify your registered applications, get application details and check the status of your applications. ### Application Registration {#application-registration} API Reference: `POST /aggregation/v1/partners/applications` ### Get Application Details {#get-application-details} To check the status of your app registrations on Mastercard's Open Finance platform, use the following endpoint. All of the query parameters are optional. The response contains a list of all the pre-apps and applications. API Reference: `GET /applications` ### Modify App Registration {#modify-app-registration} You can update a registered application with the following endpoint. API Reference: `PUT /aggregation/v1/partners/applications/{preAppId}` ### Get App Registration Status {#get-app-registration-status} To check the status of your application with a particular Financial Institution, use the following endpoint. If you don't specify an FI then the status of your application with every FI is returned. API Reference: `GET /applications/{application_id}/institutions` ### Set Customer Application ID {#set-customer-application-id} If you have registered more than one application for your partner ID, use [Set Customer Application ID](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md#set-customer-application-id) to map your customers to the apps they are allowed to use. [Add Testing or Active Customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) uses `applicationId` to assign customers to specific applications, controlling which applications your customers have permissions to use. Tip: Most partners only integrate Mastercard Open Banking into one application. We recommend that you speak to us before attempting to create multiple applications so we can advise you on best practices. Warning: You must assign an application ID to all existing customers, or they will fail to aggregate successfully. API Reference: `PUT /aggregation/v1/customers/{customerId}/applications/{applicationId}` **See also**: * [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md) * [Migrate Customers](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/migration-customers/index.md) --- # Mortgage Implementation source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md Many Lend products are built to purpose for mortgage use cases, including Uniform Residential Loan Application (URLA) data population and Government Sponsored Enterprise (GSE) acceptance. Learn more on our [Mortgage Lending Use Case](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) page. Our Mortgage Verification Service (MVS) includes support for the following mortgage verification needs through customer permissioned bank and/or payroll account data: -- **Asset Verification** * [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) * Transaction history defaults to two months to meet GSE asset underwriting requirements but can be adjusted when generating the report. Regardless of how much transaction history is requested by the lender when generating the report, up to twelve months of full transaction history is provided to Freddie Mac and Fannie Mae to allow them to run the desired asset, income, cash flow and rental payment assessments when you submit the report to the corresponding Automated Underwriting System (AUS). * [Verification of Assets and Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * Transaction history defaults to two months to meet GSE asset underwriting requirements but can be adjusted when generating the report. Regardless of how much transaction history is requested by the lender the income streams will show the full history and up to 24 months of full transaction history is provided to Freddie Mac and Fannie Mae to allow them to run the desired asset, income, cash flow and rental payment assessments when you submit the report to the corresponding Automated Underwriting System (AUS).
-- **Income and Employment Verification** * [Verification of Assets and Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * 24 months of full transaction history is provided to Freddie Mac and Fannie Mae for optimal income assessment results when you submit the report to the corresponding Automated Underwriting System (AUS). * For pre-closing verification of employment a VOE -- Transactions report can be ordered free of additional charge within a certain number of days of ordering a VOAI report. * [Verification of Income and Employment -- Paystub (with TXVerify)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) * Adding a single paystub to an MVS asset report (VOAI or VOA) can significantly increase the success of finding deposit income in the bank data. You can use a previously collected paystub or use the Mastercard Data Connect experience to engage the borrower. For best results with the Fannie Mae and Freddie Mac Automated Underwriting Systems, please ensure the consumer has a VOAI (ideal) or VOA report included in their portfolio. * [Verification of Income and Employment -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md) * This report provides all necessary income and employment URLA data, including the income broken down into standard URLA categories; Base, Bonus, Commission, Overtime, and Other.
-- **Pre-Closing Verification of Employment** * If income and employment was originally verified using a Deposit Income product (VOA, VOAI, or VOIE-Paystub) then use the [Verification of Employment - Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-transactions/index.md) report to reverify employment prior to closing * If income and employment was originally verified using a Payroll Income product (VOIE -- Payroll) then use the [Verification of Employment - Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) report to reverify employment prior to closing.
See [MVS_Reports_Guide.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/MVS_Reports_Guide.pdf) (76KB) for a consolidated summary of this information. ### Bundling {#bundling} * Some of the above products can be bundled into one price as part of an "MVS Report Bundle" product. The products are still ordered separately but are billed as one bundle. Talk to your account representative for more information. * Some Data Connect Full experiences are set up such that multiple reports can be ordered from one Data Connect experience. Look for [Data Connect Full Experiences](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#data-connect-full-experiences) with "mvs" in their name. ## Sending Reports to Government Sponsored Enterprises {#sending-reports-to-government-sponsored-enterprises} Our MVS reports are supported by Fannie Mae's Desktop Underwriter (DU) and Freddie Mac's Loan Product Advisor (LPA) Automated Underwriting Systems (AUS). MVS reports are fully Day 1 Certainty (D1C) approved at Fannie Mae and Asset and Income Modeler (AIM) approved at Freddie Mac. Contact your Fannie Mae/Freddie Mac reps for more information on how to use these products within their systems, and feel free to reach out to your Mastercard account manager with questions about Mastercard products. When submitting the loan to the AUS, the lender will use the consumer's portfolio ID as the reference ID. The AUS will then use the portfolio ID to retrieve the report data directly from Mastercard. ### Portfolio ID Usage {#portfolio-id-usage} Every consumer that is created and has reports generated is assigned a portfolio ID which is included in all the reports ordered for that consumer. The portfolio ID is used to link all other reports generated for the same consumer. Every time the same consumer's reports are refreshed, or a new report is generated, the portfolio ID version number increases by one. The portfolio ID without the version number will always give you the latest version of all the reports within the portfolio. Tip: When submitting the portfolio ID to AUS, we recommend sending the portfolio ID without the version number. #### Portfolio ID Example {#portfolio-id-example} During the loan fulfillment process for a single consumer, a lender generates a Verification of Assets and Income (VOAI) report, refreshes that report, and then orders a Verification of Employment (VOE) -- Transactions report at closing. The portfolio ID version numbers are stored as follows: * `wuvvu8qgaxh0-1-port` (VOAI) * `wuvvu8qgaxh0-2-port` (VOAI Refresh) * `wuvvu8qgaxh0-3-port` (VOE - Transactions) In this case, when submitting the portfolio to the AUS, the portfolio ID without the version number (`wuvvu8qgaxh0-port`) should be used. #### Portfolio APIs {#portfolio-apis} You can use the below endpoints to retrieve the reports associated with a portfolio ID. API Reference: `GET /decisioning/v1/portfolios/{portfolioId}` API Reference: `GET /decisioning/v1/customers/{customerId}/portfolios/{portfolioId}` API Reference: `GET /decisioning/v1/consumers/{consumerId}/portfolios/{portfolioId}` ## Testing {#testing} Refer to [Test Profiles -- MVS Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#mvs-profiles) for a list of all the MVS test profiles. Each profile is set up with a combination of one or more of the following: * a Banking User ID/Password (for products that use transaction data) * a link to download test paystubs (for products that use paystub data) * payroll account login details for products that use payroll data (payroll login details are listed separately - see [Payroll Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles)).
Note that most profiles are set up to match specific GSE (Fannie Mae/Freddie Mac) test profiles, so that when you are doing full end to end testing, you can be sure to use a test profile that will match the other information (credit, identity, etc.) for the loan. --- # Products Overview source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md The Lend products provide reports for various types of financial data: * [Transactions and Statements](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#transactions-and-statements) * [Assets and Balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#assets-and-balances) * [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) * [Cash Flow](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#cash-flow) Note: [Payment Risk Insights](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) will soon be updated to support consumer use cases. The consumer report will follow the same structure as the Small Business report. ## Transactions and Statements {#transactions-and-statements} ### Overview {#overview} Using Mastercard Open Finance, customers can log in to their financial accounts and grant access to information such as transaction data or bank statements. When a customer gives permission to access their raw transaction data, we aggregate all the transactions from across their accounts and clean, normalize, and categorize them into one of [120 categories](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md?view=model#Categorization). For each transaction, an entity name, such as a payroll provider, employer, or merchant name, is identified from the transaction description that can help identify the transaction's source. At this point, the data is ready to be analyzed and fashioned into attributes relevant to credit underwriting, tenant screening, financial management, and many other use cases. If your workflows require copies of bank statements, a customer can permission statement collection directly from their financial institution, saving both sides the time and hassle of finding, downloading, and emailing pages and pages of documents. This product can also help reduce risk of fraud by providing the statement straight from the source. ### Benefits {#benefits} * Flexibility -- build any desired attribute from the transaction data provided * Low cost -- products are competitively priced * Timeliness -- data is retrieved quickly direct from the financial institution and is up-to-date ### Relevant Products {#relevant-products} * [Transaction CRA](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/tacra/index.md) * [Statement Aggregation CRA](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/statements/index.md) ## Assets and Balances {#assets-and-balances} ### Overview {#overview-1} Using Open Finance, customers can log in to their financial accounts and grant access to transaction data to allow insights into their assets and balances. Asset reports include both debit and credit transaction data aggregated from the customer's accounts. The reports also include account owner details and asset summaries over different time periods. Balance reports also include both debit and credit transaction data and account owner details. They are differentiated from Asset reports through the inclusion of attributes customizable over different time periods that allow a deeper look at balance details. Using these products improves the customer experience by removing the need for manual bank statement collection, and improves the lender experience by providing data that can be ingested for real-time decisions. ### Benefits {#benefits-1} * Flexibility -- build additional insights from the transaction and attribute data provided * Low cost - products are competitively priced * Timeliness -- data is retrieved quickly direct from the financial institution and is up to date ### Relevant Products {#relevant-products-1} * [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) * [Verification of Assets and Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * [Asset Prequalification](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/prequal/index.md) * [Balance Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) ## Income \& Employment {#income--employment} ### Overview {#overview-2} Using Open Finance, customers can log in to their financial accounts and grant access to transaction data and payroll data, or upload paystubs, to allow insights into their income and employment. Open Finance provides two primary methods for income and employment verification -- deposit-based and payroll-based. ### Deposit-based Income \& Employment Verification {#deposit-based-income--employment-verification} Deposit income and employment products evaluate credit transaction data aggregated from the customer's accounts. Deposits are grouped into streams of like transactions and evaluated using industry-leading income classification models. Assessing a number of factors, the models assign a confidence score indicating the degree to which a stream likely represents income. A cadence of deposits is also determined, which helps determine if a stream is still actively receiving deposits, and when the next deposit can be expected. ### Payroll-based Income \& Employment Verification {#payroll-based-income--employment-verification} Payroll income and employment products evaluate data aggregated from the customer's payroll provider. The customer searches for their payroll provider and logs in using their credentials, very similar to the process for providing access to their bank data. Because the data comes from the payroll source, it has all the employment related data points you would need: employer name, employment status, etc. Note: Mastercard also provides a Paystub-Enhanced Deposit Income product that increases the success rate and confidence of identifying the customer's full income information. Mastercard collects the customer's paystub, digitizes it, and matches it to the connected bank accounts. This allows for a more accurate gross income calculation, earnings breakdown, and income identification. See [VOIE -- Paystub w/ TXVerify](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) for more information. Using deposit-based and payroll-based income and employment products improves the customer experience by removing the need for manual income document collection and sharing. These products improve the lender experience by removing the need to call employers to verify employment status and providing secure and validated data that can be ingested for real-time decisions. ### Benefits {#benefits-2} * Reach -- 93% of US employees direct deposit their pay into a bank account^[1](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#fn:1)^{#fnref:1} * Low cost -- products are competitively priced vs traditional income and employment verification offerings * Timeliness -- data is retrieved quickly direct from the financial institution or payroll providers and is up to date ### Relevant Products {#relevant-products-2} * [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) * [Verification of Assets and Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * [Verification of Employment -- Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-transactions/index.md) * [Verification of Employment -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) * [Verification of Income and Employment -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md) * [Verification of Income and Employment -- Paystub (with TXVerify)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) ## Cash Flow {#cash-flow} ### Overview {#overview-3} Using Open Finance, consumers and businesses can permission their bank account transaction data to allow deeper insight into their financial health. Cash flow opens the door for more consumers, especially thin file/no file, and small businesses to get access to needed credit. Cash Flow reports include both debit and credit transaction data and account owner details. They include a variety of attributes customizable over different time periods that allow a deeper look at cash flow details such as NSFs, inflows, outflows, and net cash flow. Balance data works hand in hand with cash flow data. Payment Risk Insights reports also include debit and credit transaction data and account owner details. They are differentiated from Cash Flow reports through the inclusion of additional attributes such as income, spending assessments, and the Payment Risk Score, which predicts the risk of an NSF occurring in the near future based on an analysis of transaction data. ### Benefits {#benefits-3} * Reach -- using cash flow in underwriting allows financial institutions to navigate limitations of traditional bureau data, including timeliness, a limited view into financial health, determining ability to pay, and bias against certain segments of the population * Financial inclusion -- approximately 50 million Americans are thin file or no file, a segment that continues to be refreshed as younger consumers enter the credit space, and a sizeable population often blocked from traditional credit products; cash flow data also helps small business credit applicants who frequently struggle to get access to the credit they need * Low cost -- products are competitively priced * Timeliness -- data is retrieved quickly direct from the financial institution and is up to date ### Relevant Products {#relevant-products-3} * [Cash Flow Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md) * [Balance Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) * [Payment Risk Insights](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) *** ** * ** *** 1. Source: American Payroll Association, Getting Paid in America, 2022 [↩︎](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#fnref:1) {#fn:1} {#fn:1} --- # Payment Enablement Bundle source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md The Payment Enablement Bundle (PEB) consolidates several individual API services into a single combined endpoint capable of returning variable responses based on input parameters. PEB is designed to help you build streamlined experiences for different payment use cases, such as direct ACH payments, recurring payments, secure account opening, credit-decisioning, loan funding, and loan servicing. Integrating with the Payment Enablement Bundle minimizes your development workload and reduces the number of API requests required when requesting data from multiple services. A single call to PEB can optionally return data from any or all of the following API services, depending on input parameters: * [Account Simple Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-simple-details-asd) * [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) * [Account Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) * [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) Tip: Fast ACH and Fast AO are encouraged when using Payment Enablement Bundle. Please contact your Client Success Manager to evaluate if FastACH and Fast AO are compatible with your integration use case. ## Get Payment Enablement Data {#get-payment-enablement-data} ### Prerequisites {#prerequisites} * Generate the required credentials to call the API. * Generate an [Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token). * Create a [test customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers). * Generate a [Mastercard Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and link customer accounts. Note: For you to successfully call the Payment Enablement endpoint, please work with your Client Success Manager to enable the following for your Partner ID: * Payment Enablement Bundle * Account Balance Call the Payment Enablement Bundle endpoint and specify the relevant values in the `include` query parameter for the API to return the data you need. Account simple details will always be included in your request regardless of your input in the request. | Query Parameter Value | Description | |------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `include=accountIdentity` | Calls the Account Owner Verification endpoint and retrieves the account owner details for an account holder from an institution. | | `include=balanceDetails` | Calls the Account Balance endpoint and retrieves the latest available and cleared account balances for a customer. Use the `balance_cache_interval` field (in minutes) to control whether to return a cached balance or fetch a real-time balance from the financial institution. We recommend setting `balance_cache_interval` at 30 minutes or greater for optimal performance (this means that live data will only be fetched if the cached data is more than 30 minutes old). | | `include=paymentInstruction` | Calls the Get Account ACH Details endpoint and retrieves a customer's ACH details (routing number and account number) for a specified account. Includes a TAN flag that indicates if the Financial Institution leverages a Tokenized Account Number (TAN) for payment initiation. If the account is verified manually using our microdeposit service Account Validation Assistant (AVA), the account is using the real account number and will never be represented by a TAN. | | `include=accountIdentity,balanceDetails,paymentInstruction` or `include=` (query parameter value is empty) | Calls Account Owner Verification, Account Balance and Get Account ACH Details. When you do not include any query parameter value, you will receive all four data elements (Account Simple Details, Account Owner Details, Balance and ACH Details) in the API response, which will result in three billable events. | Diagram peb ### Fetch Data by Institution Login ID {#fetch-data-by-institution-login-id} * This endpoint returns all accounts associated with the `institutionLoginId` provided. `institutionLoginId` is a unique identifier for the customer's institution login credentials. To learn more about `institutionLoginId`, see [Understanding Key Account Identifiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/understanding-account-data/index.md#understanding-key-account-identifiers). * Include the optional query parameters - `accountIdentity`, `balanceDetails`, and `paymentInstruction` - according to the data you wish the API to return. The response includes all the data you have requested and will be charged per account and per query parameter value (`accountIdentity`, `balanceDetails` and `paymentInstruction`). * We recommend setting `balance_cache_interval` at 30 minutes or greater for optimal performance. API Reference: `GET /aggregation/v1/paysuite/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts` ### Fetch Data by Account ID {#fetch-data-by-account-id} * This endpoint returns account details for a single account based on the `accountId` provided . `accountId` is a Mastercard assigned unique identifier for the account and is used for account data retrieval. To know more about `accountId`, see [Understanding Key Account Identifiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/understanding-account-data/index.md#understanding-key-account-identifiers). * Include the optional query parameters - `accountIdentity`, `balanceDetails`, and `paymentInstruction` - according to the data you wish the API to return. The response includes all the data you have requested and will be charged per account and per query parameter value (`accountIdentity`, `balanceDetails` and `paymentInstruction`). * We recommend setting `balance_cache_interval` at 30 minutes or greater for optimal performance. API Reference: `GET /aggregation/v1/paysuite/customers/{customerId}/accounts/{accountId}` ## Testing {#testing} Refer to the Bank Account Profiles listed in the [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) section to test the Payment Enablement Bundle. ### Using the PEB Postman Collection {#using-the-peb-postman-collection} To test the Payment Enablement Bundle without writing any code, import the PEB Postman Collection to explore and test the endpoints. 1. To get started using the Postman collection: * Create a [Postman account](https://identity.getpostman.com/signup?addAccount=1), and you can optionally download the [Postman desktop application](https://www.postman.com/downloads/). * Make sure you have a valid `partnerId`, `partnerSecret`, and `appKey`. See [Prerequisites](https://developer.mastercard.com/open-finance-us/documentation/products/pay/payment-enablement-bundle/index.md#get-payment-enablement-data) to learn how to get these credentials. * Run the requests in the **Quick Start** folder of the [Mastercard Open Finance Postman collection](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md) (review the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) if necessary). 2. Download [openbanking-us-peb.postman_collection.json](https://static.developer.mastercard.com/content/open-finance-us/swagger/openbanking-us-peb.postman_collection.json) (25KB) and [openbanking-us-peb.postman_environment.json](https://static.developer.mastercard.com/content/open-finance-us/swagger/openbanking-us-peb.postman_environment.json) (660B). 3. In Postman, click **Import** and import *openbanking-us-peb.postman_collection.json* and *openbanking-us-peb.postman_environment.json*. 4. Click **Environments** and update the Mastercard Open Finance PEB US APIs Environment with your `partnerId`, `partnerSecret`, `appKey`, and the `customerId`. ![Add environment variables](https://static.developer.mastercard.com/content/open-finance-us/uploads/peb-environment-postman_1.png) 5. Click **Collections** to view the endpoints and send requests. Make sure Mastercard Open Finance PEB US APIs Environment (located on the top right) is selected when you send requests. ![Send Request](https://static.developer.mastercard.com/content/open-finance-us/uploads/send-peb-request_1.png) ## Billing {#billing} The following table lists the billing details for Payment Enablement Bundle: | API | Billing | |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | Account Simple Details | Available by default and is free to use. | | Request includes `accountIdentity` | Billable for each successful API call. You must include the Account Owner Verification endpoint in your product enrollment request. | | Request includes `balanceDetails` | Billable for each successful API call. You must include the Account Balance endpoint in your product enrollment request. | | Request includes `paymentInstruction` | Billable for each successful API call. You must include the Get Account ACH Details endpoint in your product enrollment request. | For any billing questions, contact your Sales Representative or Client Success Manager. --- # Non-SDK Integration source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/index.md The Non-SDK integration path is designed for partners whose security requirements do not allow for external SDKs, or whose tech stack is not compatible with our SDKs. This approach provides full functionality across all of the same platforms that our SDKs support. To implement Data Connect without an SDK, the following are required: * Include a suitable `redirectUri` when [generating the Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md), and also set `isHostedInMobileApp` as true for mobile applications. * Handle OAuth completion via redirect, using the `redirectUri`. In the Non-SDK model, all user interactions and session states must be tracked via Data Connect webhooks. * You must subscribe to individual webhook events relevant to your integration. * Webhooks provide essential insight into account linking, session completion, and error states. See [Data Connect Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) and [Data Connect Webhook Events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md) for more details. ## Web Integration (via iframe) {#web-integration-via-iframe} Warning: Support for this integration style is not available by default. Discuss with your Customer Success Manager or Solution Engineer so that they can make the necessary changes to Data Connect behavior for your application. If your application can't use the Mastercard Data Connect Web SDK, Data Connect can now be embedded using an iframe: * Create and manage an iframe in your app. * Set the Data Connect URL as the iframe `src` attribute. * Ensure `redirectUri` is included in the Data Connect URL. This allows the user to return to your app once the account connection flow is complete. * After Data Connect completes, the user will be redirected to your specified `redirectUri`, along with the following query parameters: * `code`: Numeric status code for session completion (for example: 200). * `reason`: Text explanation of the session status. This approach gives you flexibility when SDK integration is not possible. However, it requires manual management of iframe behavior and session state. ## Mobile Integration (iOS and Android) {#mobile-integration-ios-and-android} When embedding Data Connect within a native mobile app without using the SDK: * Pass a `redirectUri` to regain control after the user completes the Data Connect flow. * Prefer Universal Links for iOS and App Links for Android. * Avoid using deep links as `redirectUri` values. * Expect two redirects to the same `redirectUri`: * After the user completes their FI flow * After the user submits their connected accounts to Connect * Set `isHostedInMobileApp` as true for mobile applications.
The implementation details will depend on whether the user has their FI app installed, and whether you launch Data Connect in a Webview and the FI app in a secure container (Safari View Controller for iOS or Chrome Custom Tab for Android), or if both Data Connect and the FI authentication will be via secure containers. See the following for further detail: * [Non-SDK Integration Guide for iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-ios/index.md) * [Non-SDK Integration Guide for Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-android/index.md) --- # SDK Integration source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md Tip: **Why we recommend using our Data Connect SDKs** Using one of the provided SDKs for your Mastercard Data Connect integration is recommended for the following reasons: 1. Using the SDKs can significantly reduce the development effort, and provides the cleanest integration. 2. The SDKs manage the OAuth re-direction for you. 3. Error messaging/event handling is built in, so you do not need to implement webhooks to receive Data Connect events. 4. The SDKs are compliant with any restrictions imposed by FIs (for example Chase does not allow their consent URL to be launched from within insecure webviews). We regularly update our SDKs to support these requirements. 5. The user journey when using our SDKs is correct and has been validated and tested. If you implement the experience without using the SDKs, you'll need to take care to avoid any anomalous behavior that we do not support. Using the SDKs means this is not a concern. We provide the following SDKs to help you embed the Data Connect user experience anywhere you want within your applications. * [Web Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md) --- The Data Connect Web SDK enables you to embed the Data Connect user experience into an iFrame or add it into a popup window. The Data Connect Web SDK also provides events to help you monitor the progress of a user within the flow. You can install the SDK into your project via npm, or just reference it as needed via our CDN (using the ESM, UMD, or IIFE module formats). * [iOS Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/index.md) --- The Data Connect iOS SDK is a compiled binary in XCFramework format, which allows you to easily integrate our SDK into your development projects. This section also explains how you can display Data Connect and the FI authentication inside a secure web container (Safari view controller) on iOS, without using the Data Connect iOS SDK. * [Android Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/index.md) --- The Data Connect Android SDK is distributed as a compiled binary in Maven Central which allows you to easily integrate our SDK into your development projects. This section also explains how you can display Data Connect and the FI authentication inside a secure web container (Chrome custom tab) on Android, without using the Data Connect Android SDK. * [React Native Applications](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/react-native-sdk/index.md) --- The Data Connect React Native SDK provides an easy way for you to integrate Mastercard Open Finance Data Connect into your React Native application for cross-platform development on both iOS and Android. For mobile applications, we recommend using one of the Data Connect mobile SDKs. You can also display the Data Connect experience inside a webview within your mobile app (optionally, the Data Connect Web SDK can be used with this approach). * [Using Webviews via the Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/index.md) --- Webviews enable you to display web content within a native mobile application, without needing to launch a full browser experience. Data Connect Full, Lite and Fix can all be displayed within Webviews via the Web SDK. ## SDK Deprecation Policy {#sdk-deprecation-policy} Starting Q4 2024, Mastercard began adhering to the following deprecation policy. We strongly recommend updating to the latest version of our SDKs as soon as possible to avoid potential disruptions. Deprecated SDKs do not receive support. ### Terminology {#terminology} Each version of an SDK has a status of Active, Inactive, or Deprecated: | Status | Description | |------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Active | This is the most recent major version of our SDK and is fully supported. This is the recommended version for use. Active status SDKs receive minor updates and patches as needed. | | Inactive | When a new major version is released, the previous major version becomes inactive. Inactive SDKs do not receive updates. After nine months of inactive status, inactive SDKs are deprecated. | | Deprecated | Deprecated versions may contain bugs, security vulnerabilities, or lack compatibility with newer platforms, which could result in disruptions to your application. Update to the latest version promptly to avoid disruptions. | For example, the lifecycle of an SDK could be as follows (the dates and version numbers used here are purely illustrative and do not relate to any particular SDK): * January 1, 2025: Version 1.0.0 is released (Active). * June 1, 2025: Version 1.1.0 is released (1.1.0 is the most up to date Active SDK). * February 1, 2026: Version 2.0.0 is released (2.0.0 becomes Active, 1.x.x become Inactive). * May 1, 2026: Version 2.1.0 is released (2.1.0 is the most up to date Active version, all versions in 1.x.x are still Inactive). * November 1, 2026: Nine months after becoming Inactive, all 1.x.x Versions are Deprecated.
### Recommendations {#recommendations} We recommend signing up for email notifications within the SDK repositories you use on the GitHub website. By selecting the [custom option in your GitHub notification settings](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#about-custom-notifications), you can receive updates when new releases occur. Additionally, you can monitor our change logs on GitHub to ensure your SDK remains up-to-date. Here are links to each of our SDK repositories on GitHub: * [Web SDK GitHub repository](https://github.com/Mastercard/connect-web-sdk) * [iOS SDK GitHub repository](https://github.com/Mastercard/connect-ios-sdk) * [Android SDK GitHub repository](https://github.com/Mastercard/connect-android-sdk) * [React Native SDK GitHub repository](https://github.com/Mastercard/connect-react-native-sdk)
For any questions or support, please [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#get-help). ## Callback Events {#callback-events} The iOS, Android, and React Native SDKs provide the following events via their callback interface. | Event | Description | |----------|---------------------------------------------------------------------------------------------------------------------------------------------| | onLoad | Sent when the Data Connect web page is loaded and ready to display. | | onDone | Sent when the user successfully completes the Data Connect application. | | onCancel | Sent when the user cancels the Data Connect application. | | onError | Sent when there is an error during the Data Connect application. | | onRoute | Sent when the user navigates to a new route or screen in Data Connect. | | onUser | Sent when a user performs an action. User events provide visibility into what action a user could take within the Data Connect application. | ## Resources {#resources} * Learn more about the Data Connect specific events that get sent to the SDK's event listener. See [Data Connect Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/index.md). * See the list of [Webhook events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) that your service can listen for while a customer uses the Data Connect experience. --- # Customizing Data Connect source: https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md Customize Data Connect enables you to tailor the appearance and behavior of the Data Connect application's interface to suit your branding and user experience requirements. You can enable or disable features and filter account types, allowing you to streamline the experience to focus on essential elements for your application. This customization improves the overall user experience by aligning the application with your customers' preferences. After your experience is configured on Customize Data Connect, an experience ID is created that you can pass in the `experience` parameter when [generating a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). The generated URL will then load your customized version of the Data Connect experience. ## Step 1: Access Customize Data Connect on Client Hub {#step-1-access-customize-data-connect-on-client-hub} 1. **Log in** to your [Mastercard Developers account](https://developer.mastercard.com/account/log-in). 2. **Access your Open Finance project**: * If you already have an Open Finance project, proceed to step 3 * If you do not have an Open Finance project yet, you will need to [create a new project](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#create-a-sandbox-project) 3. **Access Client Hub**: * To access [Client Hub](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/accessing-client-hub/index.md) in a test environment: * Go to the Sandbox credentials section in your project * Click the overflow menu (three dots), then click **Access Client Hub** to open the Client Hub application * To access Client Hub in a production environment: * Go to the Production credentials section in your project * Click the overflow menu (three dots), then click **Access Client Hub** to open the Client Hub application 4. **Navigate to Customize Connect**: * On Client Hub, navigate to **Customize Connect** ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/clienthub-customizeconnect.png) ## Step 2: Create or Modify a Data Connect Experience {#step-2-create-or-modify-a-data-connect-experience} * To create a new experience, click **Add New** and provide an Experience Name. * To modify an existing experience, click the experience and start editing. Note: **Auto Save**: When customizing the Data Connect experiences, your changes are automatically saved. The auto-save functionality ensures that any adjustments you make are instantly applied and retained without needing to manually save your work. ## Step 3: Configure the Data Connect Experience {#step-3-configure-the-data-connect-experience} The following are the key aspects of Data Connect you can customize: ### Product Type {#product-type} The Product Type drop-down list allows you to select the product for which you want to customize the Data Connect Experience. The drop-down will display only the products that are available to your organization based on your existing contract. If a specific product type does not appear in the list, it may mean that it is not currently included in your contract or was unintentionally omitted. If you have questions about product availability, reach out to your Customer Success Manager (CSM), who can ensure the drop-down reflects the products available to you. Once you've selected the appropriate product type, click **Create** to proceed with customizing your Data Connect Experience. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/create_new_connect_experience_1.png) ### Configure Landing Page {#configure-landing-page} You can customize the landing page that users see at the start of the experience. * Provide your company name. It appears as: "\[Company Name\] uses Finicity, a Mastercard company..." This field is prepopulated from your company profile. Check it and edit if needed. * Select the text of the Call To Action (CTA) button that users must click to proceed to the next step. * Click **\>** to move to the next screen. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/company_name_customize_connect_2.png) ### Financial Institutions {#financial-institutions} This page enables you to personalize the screen where users can search and choose from a list of available Financial Institutions (FIs). You can customize how the institutions are displayed, such as by prioritizing certain FIs or changing the appearance of the list. Mastercard recommends using the **Automatic (recommended)** option, which displays the default list of Financial Institutions based on user data. You can drag the Financial Institution tiles to reorder your top 8 FIs. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/recommended_FI_list_1.png) If you want to add an FI that's not featured in the recommended list, you can do so by specifying the financial institutions in the **Find a bank to feature** search box. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/search_FI_not_featured.png) ### Account Selection {#account-selection} You can customize the screen where your customers are required to select specific accounts they want to link with your application. #### Number of Accounts {#number-of-accounts} This option allows you to configure whether the end user will be able to select and link only a single account (radio button UI) or select and link multiple accounts (checkbox UI). ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/single_multiple_accounts_1.png) #### Available Account Types {#available-account-types} You can customize which account types are available for users to select. This can be useful if your application requires users to connect specific types of accounts, such as checking accounts for banking apps or investment accounts for financial planning tools. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/account_type_selection_1.png) If the **Use recommended accounts** option is checked, the following account types will be selected by default, based on the product type you selected in the [Create new experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#step-2-create-or-modify-a-data-connect-experience) dialog: | # | Product Type | Account Types | |----|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | Aggregation | All account types are selected. | | 2 | Asset Summary | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 3 | Cash Flow Business | All account types are selected. | | 4 | Cash Flow Personal | All account types are selected. | | 5 | DCR | Checking, Savings, Money Market | | 6 | History | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 7 | MVS Basic | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 8 | MVS Basic Paystub | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 9 | MVS Full | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 10 | MVS IE | Checking, Savings, Money Market | | 11 | MVS IE Basic | Checking, Savings, Money Market | | 12 | Pre Qual VOA | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 13 | Ultrafico | Checking, Savings, Money Market | | 14 | VOA | Checking, Savings, Money Market, CD, Unknown, UGMA, UTMA, 529, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 15 | VOE Payroll | All account types are selected. | | 16 | VOE Transactions | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 17 | VOI | Checking, Savings, Money Market | | 18 | VOIE Payroll | All account types are selected. | | 19 | VOIE Paystub | All account types are selected. | | 20 | VOIE Paystub Tx Verify | Checking, Savings, Money Market | | 21 | Transactions CRA | All account types are selected. | | 22 | VOI Transactions CRA | All account types are selected. | | 23 | ACH | Checking, Savings, CD, Money Market (Only Visible When Product Is ACH) | | 24 | Balance Analytics Personal | Checking, Savings, Money Market, CD, Unknown, Investment, Investment Tax Deferred, Employee Stock Purchase Plan, IRA, 401k, Roth, 403b, Rollover, Keogh, 457, 401a, Brokerage Account, Education Savings, Non Taxable Brokerage Account, Pension, Roth 401k, SEP IRA, Simple IRA, Thrift Savings Plan, Health Savings Account, Profit Sharing Plan, Variable Annuity | | 25 | Cash Flow Analytics Personal | All account types are selected. | | 26 | Cash Flow Analytics Business | All account types are selected. | #### Auto Select All Accounts {#auto-select-all-accounts} If you choose the **Auto select all accounts** option, all the available accounts are automatically selected for the user during the account linking process. This feature is especially useful for applications that need access to all of the user's accounts without requiring the user to manually select each one. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/auto-select-accounts_1.png) You also have the option to use the **Skip Account selection** feature. This feature bypasses the Account Selection page and takes the user directly to the Account Review page, where they can review the accounts selected to share with Mastercard. Users can still add or remove accounts from the preselected accounts on the Account Review page. This setup is beneficial if you want to simplify the user experience by reducing the number of steps required to link accounts, especially when your application does not require user interaction in selecting accounts. ## Step 4: Customize the Look and Feel {#step-4-customize-the-look-and-feel} You can: * [add your own logo](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#add-a-logo) on Data Connect. * choose a [brand color](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#brand-color). * change the behavior of the [back button](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#back-button) and [exit button](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#exit-button). * specify whether the Data Connect URL can be used only once ([Single Use URL](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#single-use-url)). * specify whether to generate a report automatically ([Skip Report](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#skip-report)).
To alter these settings, navigate to the required experience and open Settings by clicking the gear icon at top right. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/logo_gear_2.png) The Settings window opens with a preview of the screens of your experience, with the settings to the right. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/customize-connect-settings_1.png) Tip: You may need to scroll down to see all the options. ### Add a Logo {#add-a-logo} Click the toggle switch next to **Logo** . Choose a file to upload. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/upload-logo-detail-aug2025.png) #### Logo Upload Requirements {#logo-upload-requirements} Before uploading your logo, ensure it meets the following requirements: 1. **File Format:** Vector images in SVG format are required. If you do not have an image file in the right format, you can try uploading a file in another format such as PNG and the site will attempt to automatically convert it for you. Results using this method may vary. 2. **Maximum File Size:** The logo file must not exceed 100KB. 3. **Maximum Height:** The logo must be suitable to be used with a maximum height of 80px. If you upload a PNG or other bitmap image, it should not be larger than this. #### Edit the Logo {#edit-the-logo} Once uploaded, you can edit the logo to change the size and position of the image. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/upload-logo-edit-tool.png) ### Brand Color {#brand-color} Enter the hex code for your desired brand color in the **Hex** field under Brand color. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/brand-color_2.png) This color will be used for CTA buttons, search box outline, search box text, and loading spinner. Below the brand color, you can choose if the CTA text color is black or white, to ensure the text is legible with your brand color. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/cta-color.png) ### Back Button {#back-button} Use the toggle switch to hide or display the back button in Data Connect. This removes the back button from all Data Connect screens. Note that this only turns off the back button in the Data Connect screens. Customers can still use the browser back button. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/backicon_customizeconnect.png) ### Exit Button {#exit-button} Use the toggle switch to hide or display the exit button in Data Connect. This removes the exit button from all Data Connect screens. Note that this only turns off the exit button in the Data Connect screens. Customers can still close the browser. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/exitbutton_customizeconnect.png) After applying the required customizations, click **Menu \> Experiences** to return to the main menu. This displays the page listing the experiences you've created. ### Single Use URL {#single-use-url} This feature only enables a customer to use a link a single time. This is to prevent customers from generating multiple reports through one Data Connect session, or adding multiple accounts when only one is needed. The exact behavior depends on the Account Selection setting: * For a multiple account selection use case, if a user tries to use the same URL twice they will start a new Data Connect session. The user will be able to see previously connected accounts, but a new report will not be generated. * For a single account selection use case, if a user tries to use the same URL twice they will see a screen saying that they have already successfully connected an account. Note: The `singleUserUrl` parameter passed in the [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) API call for Data Connect Full overrides the value set here. ### Skip Report {#skip-report} Some Data Connect experiences automatically generate a [Lend report](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) by default. Enable **Skip Report** if you do not want a report to be generated automatically when the user completes the experience. Use this option if you only want the experience to connect the user's account and you plan to generate a report later. ## Step 5: Preview or Share Experience {#step-5-preview-or-share-experience} To share or preview a Data Connect experience, click the Share icon. You can either copy the experience URL or share it via an email. Open the URL in a browser to verify that your changes have been applied and see the customizations in action. This URL is a demo URL, not a production URL, so none of the production events will be triggered. There is no limit to the number of demo URLs you can generate. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/share-demo_2.png) ## Step 6: Apply Customizations {#step-6-apply-customizations} Once you finish configuring the experience, an Experience ID is generated. To view the experience ID, you can do one of the following: * Open the Experience Editor, then click View IDs ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/copyexperienceid.png) * Copy the experience ID from the Experiences list ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/copyexperienceid2.png) To use a specific experience for your product, pass the experience ID in the `experience` parameter while [generating a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). ## Copy Experience {#copy-experience} Click the Copy icon associated with the experience you want to duplicate. This action will create a new experience with the same settings as the original. You can then modify any settings as necessary to fit the specific needs of the new use case. ## Delete Experience {#delete-experience} To delete an experience, click the Delete icon associated with the experience. Before deleting an experience, make sure this action doesn't impact the user experience and functionality of your application. ## Restoring a Deleted Experience {#restoring-a-deleted-experience} If you've accidentally deleted a customized experience and need to restore it, you can go to **Menu \> Recently Deleted** and click **Restore**. You have up to 30 days from the date of deletion to restore the experience. After this 30-day period, the deleted experience is permanently removed and cannot be restored. ## Tracking Activity {#tracking-activity} To track the activity related to your customized experiences, go to **Menu \> Activity Log**. **Information you can track**: The Activity Log provides detailed records of various actions related to your experiences, including: * **Date changed**: The exact date when a change was made. * **Experience name**: The name of the experience that was modified. * **Experience ID**: A unique identifier for the experience. * **User**: Track who made the change. * **Changes Made** : A description of what changes were made to the experience. Use this log to keep track of all changes, including when an experience was created, modified, or deleted. You can also click **View Details** to see more detailed information about a specific activity. --- # 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": "9017024521", "eventType": "institutionLoginDeleted", "eventId": "1776438321746-974a117798338e91ce8e13bd", "payload": { "institutionLoginId": "9009846171" } } ``` ## 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 } } ``` --- # Recurring Analytics source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/recurring-transactions/index.md Recurring (Transactions) Analytics is a service to identify and retrieve details of a customer's recurring transactions, allowing you to analyse patterns. The service currently covers recurring payments by the customer (outflows). You can request information for multiple accounts owned by the same customer with a single API call. The response contains a list of transactions with categories (for example, "Streaming Service" or "Bills \& Utilities"). Each transaction includes: * normalized payee/payer name * cadence (in days) * status * expected next transaction date * expected next transaction amount * historical amount statistics (min, max, mean and median) * number of transactions * transaction category * related transaction IDs Note: Recurring Analytics is a smart subscription service. You will be billed for each customer you generate a report for in a given month. Additional reports for the same customer in the same month are free. ## Use Cases {#use-cases} * Subscription management (identifying recurring merchant charges) - easily identify all subscription services so a customer can better understand and optimize their services * Bill payment - identify all upcoming bills and expected payment dates and amounts * Personal financial management ## How It Works {#how-it-works} 1. Generate credentials (see [Create a Sandbox Project](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#create-a-sandbox-project)). 2. Create a customer and link accounts via Data Connect (see [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer)). * For testing in Sandbox, there are several [transactions profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#transactions-profiles) available for you to use - for example, **profile_1500** which is available through Finbank Profiles A/B and Finbank OAuth. 3. Refresh accounts to retrieve the latest transaction history - transaction history goes back 6 months and is also refreshed nightly. 4. Call the [Get Recurring Transactions for Customer](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetRecurringTransactions) endpoint with a JSON body specifying one or more customer account IDs you want analyzed. API Reference: `POST /aggregation/customers/{customerId}/recurring-transactions` 5. Receive the response containing customer-level recurring outflows and per-account recurring outflows. Note: A minimum of three months of transaction history is needed to identify recurring transactions. Diagram recurring --- # Aggregation Status Codes source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md As accounts are aggregated every night or upon refresh, an aggregation status code is recorded, which is returned in the `aggregationStatusCode` field in the responses to Account Aggregation Services endpoints. For a description of the aggregation status codes and how to deal with status codes that prevent nightly batch aggregation, see [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/account-errors/index.md#aggregation-status-codes) in Account Errors. Warning: We recommend that you listen for and catch non-zero aggregation status codes, and invoke Data Connect Fix where appropriate. For errors which are not fixable in this way, see the [Full Error List](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) section for further suggestions. In some cases you may need to submit a support request. ## Using Data Connect Fix {#using-data-connect-fix} For fixable aggregation status codes, you need the `institutionLoginId` relating to the user account in question (you can get these values using the Account Aggregation endpoints such as Get Customer Account by ID). The following `aggregationStatusCodes` can normally be resolved using Data Connect Fix: * [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) * [108](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#108) / [109](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#109) * [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) / [187](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#187) * [945](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#945) / [948](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-migration-inprogress/index.md#948) * [946](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#946) * [947](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#947)
Use the following flow to resolve these issues: 1. Call [Get Customer Account by ID](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-simple-details-asd) to obtain the institutionLoginId from the response body. 2. Call the [Generate Data Connect Fix URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-fix) endpoint, passing the customerId and institutionLoginId in the request body. 3. Wait for the "done" [Data Connect webhook event](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md#done) and proceed with API calls. A refresh will be done automatically. #### Nuances With Data Connect Fix {#nuances-with-data-connect-fix} * Error code gathering via TxPush --- The [TxPush](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) service will send events when an account has been modified, which means if an aggregation error happens, an event will be sent with that error and correlating account details. * Data Connect Fix inside of Data Connect Full --- Users can sometimes fix broken accounts inside of the Data Connect Full widget. Users will see a prompt on the review account screen to reconnect their account. * Multiple [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) failures in a row --- Some accounts may have "One Time Passcode (OTP)" security on them, so that any endpoint which triggers an interaction with the bank may result in a 203 HTTP response or a 185 error code (indicating an MFA/OTP challenge). If an account continues to generate a 185 error status during batch aggregation, even after being fixed, this is also an indication of an MFA/OTP challenge/flow on the account. #### How to Test Data Connect Fix {#how-to-test-data-connect-fix} You can test the Data Connect Fix flow using certain [Finbank test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) as follows: 1. Generate a Data Connect Full URL. 2. Using the test bank Finbank, use one of the [sign-in authentication test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#sign-in-authentication-profiles) that begin with 'tfa' (`tfa_multi` for example) to recreate the error. 3. Permission an account. 4. Run a refresh. Accounts will then have a 185 status. 5. Gather the necessary information and generate a Data Connect Fix URL. 6. Follow Data Connect prompts and finish fixing accounts. A refresh will run on the accounts after Data Connect Fix successfully completes. 7. Gather customer accounts to check that accounts are in a 0 status. --- # Automated Clearing House (ACH) source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ach/index.md "ACH" or "Automated Clearing House" is a payment network built by the National Automated Clearing House Association (Nacha). An ACH is an electronic bank-to-bank payment enabled through the ACH network rather than a card network. ACH payments are also known as ACH "transfers" or ACH "transactions." The ACH network is used in the United States, but there are also International ACH Transactions (IAT). The ACH transfer involves two steps: initiating the payment and receiving the payment. Before you can initiate the transfer as the payment originator, the customer must first give approval. This typically happens by signing an ACH authorization form or through verbal agreement. During this initiation process, the customer can set up one-time payments, recurring payments, split deposits, and more.
## ACH User Journey - Data Connect Full {#ach-user-journey---data-connect-full} Tip: Access the [Figma file](https://www.figma.com/design/pqrT4uBCEsbL53GXSxh6g0/Open-Banking-US-for-Payments?node-id=1-65126&t=fxzcOZWigGMOnS4T-4) for this experience to duplicate and customize in your own environment. To view the UX journey, use **full screen mode** or **zoom** controls. Please allow a few seconds for the screens to load. ## ACH User Journey - Data Connect Lite {#ach-user-journey---data-connect-lite} Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). Note: For developers, here is the API documentation: [ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md)
Next: [Account Validation Assistant](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md) --- # Account Validation Assistant source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md Account Validation Assistant (AVA) provides bank account validation by allowing partners to verify their customers' bank account details using micro-deposits before initiating payments. AVA is supplementary to Account ACH Details and provides customers who are unable to permission access to their bank accounts a solution to verify their payment information. Although Mastercard Open Finance can verify account details for the overwhelming majority of Demand Deposit Accounts (DDA), there are scenarios where an alternative method of validation is needed to achieve full account coverage. Examples include: * The Financial Institution (FI) does not provide Account (AN) and Routing (RTN) numbers through current integrations. * The FI is new to Mastercard Open Finance. ## Account Validation Assistant - Data Connect Full {#account-validation-assistant---data-connect-full} Tip: Access the [Figma file](https://www.figma.com/design/pqrT4uBCEsbL53GXSxh6g0/Open-Banking-US-for-Payments?node-id=1-65125&t=fxzcOZWigGMOnS4T-4) for this experience to duplicate and customize in your own environment. To view the UX journey, use **full screen mode** or **zoom** controls. Please allow a few seconds for the screens to load. ## Account Validation Assistant - Data Connect Lite {#account-validation-assistant---data-connect-lite} AVA integration with Data Connect Lite is not currently available. Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). Note: For developers, here is the API documentation: [Account Validation Assistant](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md)
Next: [Account Opening and Funding](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/account-opening/index.md) --- # Building a User-friendly FI Search Experience source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/fi-search-experience/index.md Based on research insights, these are our bank and Financial Institution (FI) best practice guidelines. ## Financial Institution Branding {#financial-institution-branding} ![FI search experience 1](https://static.developer.mastercard.com/content/open-finance-us/uploads/fi-search-experience-img1.png) #### Use Branded Logos {#use-branded-logos} Make things clear and simple for customers. The onboarding flow should clarify what Open Finance does and how it works. When searching for their FI, customers tend to look for their FI's brand. Customers feel more confident and secure when their FI is represented by its own branding rather than generic branding, so Mastercard encourages using branded logos and icons when possible.
#### Show URLs in Search Results for Available Banks (Home URL) {#show-urls-in-search-results-for-available-banks-home-url} Displaying the FI's URL in search results increases a sense of confidence and security in the end user that they are selecting the correct FI.
#### Use Generic Branding When Necessary {#use-generic-branding-when-necessary} When FI branding is unavailable, we recommend using a consistent generic design for all unbranded FI results. In user testing, we learned that designs with a dark background compared to a light or white background were preferred. A dark background looks more "active and available" compared to a light background and matches the aesthetic of most FIs. ## Display Unavailable FIs {#display-unavailable-fis} Financial Institutions can be unavailable for various reasons (for example, the server is down or it is an unsupported bank). User testing supports displaying both available and unavailable FIs to provide clarity in a customer's search. We tested several designs and discovered the importance of providing clarity around the status of an unavailable FI for users by: * grouping unavailable results together and at the bottom of the search results page. * graying out the name, URL, and icon. Most users understand that grayed-out content indicates it is unavailable. * including an explanation so users understand why a FI is unavailable. ![FI search experience 2](https://static.developer.mastercard.com/content/open-finance-us/uploads/fi-search-experience-img2.png) #### Provide Clear Guidance {#provide-clear-guidance} Headlines should be clear, concise, and specific. For example, rather than using "Search", choose a more specific call-to-action such as "Search for your bank" or "Search for your financial institution."
#### Use Inclusive Design {#use-inclusive-design} * Use color contrast (see our [Accessibility guidelines](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/accessibility-guidelines/index.md#color-contrast)). * Touch targets. * Ensure that all aspects of the search bar can be navigated via a keyboard. * Provide voice and dictation services. #### Develop a Flexible Search Engine {#develop-a-flexible-search-engine} Users are highly prone to human error when typing in search bars. These approaches can result in better search results: * **Fuzzy matching techniques**, or algorithms used to match similar strings --- provide a greater error tolerance during searches. * \*\* Case insensitivity --- ensure that your search engine is not case and space sensitive greatly improves search flexibility. For example, "New York City," "new york city," "new york CITY," and "newyorkcity" should all yield the same search results. * **Predictive text** and **auto suggestions** --- this assistance can alleviate typing effort for consumers and reduce time to completion. Tip: In financial institutions, there are many **aliases** , **acronyms** , **special character combinations** , and **abbreviations** that consumers may use in their search queries. For example: * A common alias for "J.P. Morgan Chase \& Co." is "Chase". * A common acronym for Bank of America is "BofA". * A common abbreviation for Credit Union is "CU". * A common special character combination is "E\*Trade".
When developing your search experience, consider manually adding common aliases, acronyms, and abbreviations for certain FIs to improve the flexibility of the search experience. #### Best Practices for Dead-End Search Queries {#best-practices-for-dead-end-search-queries} When there are **no results found** for a search query, provide clear and actionable next steps. For example, provide related search results or recommend that users check their spelling or try using different keywords. In a dead-end case where the FI is not available, customers like being given the option to **request their FI**. If going this route, we recommend that you work with the account or customer representative to plug into the RFNI process. ![FI search experience 3](https://static.developer.mastercard.com/content/open-finance-us/uploads/fi-search-experience-img3.png) Tip: When users are in the process of requesting a bank, ensure that timeline expectations are set accordingly. Once new requests are collected and sent to Open Finance US, FIs could take several months to appear in the search results. ## Display Search Errors {#display-search-errors} #### Avoid Directing Users to a Dead End {#avoid-directing-users-to-a-dead-end} Based on our consumer testing, we learned that customers will click a search result that is clearly unavailable just out of curiosity. We recommend making unavailable results display a notification or popup message that provides the user with more context about the unavailable FI and provides suggestions or troubleshooting help. #### How to Handle a Dead End {#how-to-handle-a-dead-end} Sometimes there is no immediate resolution to an issue or error. In these situations, the end user may want to understand the situation even if they cannot do anything about it. We recommend clearly communicating the issue to the end user and explaining that there is no resolution currently. When users understand there is nothing that can be done, they may still feel frustrated but at least not confused. ![FI search experience 4](https://static.developer.mastercard.com/content/open-finance-us/uploads/fi-search-experience-img4.png) Tip: Keep in mind that some aliases can have multiple meanings and search results. For example, "MT" can be "Montana" or "Mount". Note: For developers, here is the API documentation: [FI search](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md)
Next: [Returning User Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/returning-user-experience/index.md) --- # Permissible Purpose Codes source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md As part of the FCRA regulations, a 2-digit permissible purpose code is required to specify the reason for retrieving a consumer's credit decisioning report. Pass one of the following codes as the value for the purpose parameter in the get report API call. Warning: Validation enforcing the use of a valid Permissible Purpose Code for CRA reports will be enabled on 11 August 2026. After this date, any requests with invalid or missing codes will be rejected. | Permissible Purpose | Description | Code | |---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------| | Account Review | Review account performance for consumer and small business credit accounts. The following review types include but are not limited to: Evaluate whether an account should remain open or be closed; Evaluate whether account credit limits should be increased or reduced; Decide whether to impose other account conditions or limitations. | 99 | | Eligibility for Govt Benefits | Determining eligibility for government licenses or benefits (e.g., financial advisor/securities dealer, low-income assistance) where the entity is permitted or required by law to consider an applicant's financial responsibility or status (e.g., confirming a representation of low income). | 8J | | Extension of Credit | Determining whether to extend credit and the amount, rate, terms, etc. of credit products based on borrower qualifications. Applicable for any loan type: Mortgage, Auto, HELOC (Home Equity Line of Credit), Installment, BNPL (Buy Now Pay Later), Credit Card, Merchant charge-back rates, Merchant credit lines, etc. **Not to be used for commercial (OBB) reports.** | 31 | | Extension of Credit (Mortgage) | Determining whether to extend credit and the amount, rate, terms, etc. of credit products based on borrower qualifications. Applicable for the following loan types: Mortgage and HELOC (Home Equity Line of Credit). **Not to be used for commercial (OBB) reports.** | 26 | | Tenant Screening | Assessing creditworthiness, ability to pay (income) or other factors in deciding a rental property lease application from a consumer. | 1B | | Payment Acceptance / Authorization | Determine whether a consumer's payment method may be accepted or authorized. | 1P | | Written Instructions of the Consumer - General | Various use cases; Consumer's specific written consent, obtained by the end user, is required. **Includes commercial (OBB) reports permissioned by consumers.** | 1W | | Written Instructions of the Consumer - Prequalification | Determine eligibility for offers; Consumer's specific written consent is required. | 3F | See also: * [Lend Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) * [Mortgage Implementation](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md) --- # Verification of Income and Employment source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-income-and-employment/index.md Income verification processes can be intimidating, but Mastercard Open Finance US's income verification API offers you a better path. Secure happier customers, save yourself time, and get a higher ROI for your income verification needs, including: mortgage, auto-lending, personal lending, and tenant screening. Open Finance income verification enables you to digitally verify income quickly and easily without extra documents. Additional benefits of our income and employment verification include: * Reduced friction for your mortgage-seeking customers. * Clear stipulations and return-customer creation for auto loans. * Creation of analytics-informed credit decisioning models. * Risk mitigation, broadened customer base, and financial inclusion. ## Verification of Income - Data Connect Full {#verification-of-income---data-connect-full} Tip: Access the [Figma file](https://www.figma.com/design/IFeJZsZKnQccdztXSSzySp/Open-Banking-US-for-Lending?node-id=1-4191&t=jcfNF8SU4qJrlSyC-4) for this experience to duplicate and customize in your own environment. To view the UX journey, use **full screen mode** or **zoom** controls. Please allow a few seconds for the screens to load. Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). Note: For developers, here is the API documentation: [Verification of Income](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md)
Next: [Open Finance US for Account Opening and Funding](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/account-opening-and-funding/index.md) --- # Account Validation Assistant source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md Account Validation Assistant provides bank account validation by allowing partners to verify their customers' bank account details using microdeposits before initiating payments. This is supplementary to [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md), and provides those customers who are unable to locate their Financial Institution with a way to verify their payment information. Within Data Connect, AVA is offered to the customer as a fallback when the financial institution cannot be securely linked. The customer can use AVA in either of the following scenarios (for information on testing these scenarios see [Testing AVA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#testing-ava)): * The Financial Institution is not found or has connection issues. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/AVA-fi-not-found.png) * The Financial institution is [ACH decertified](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#certified-institutions) (Mastercard cannot retrieve routing and account details directly from the Financial Institution). ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/AVA-fi-ach-decertified.png) Tip: Bank account validation is the process of verifying that bank routing and account numbers are valid before a transaction is processed, to facilitate successful payment routing. This ensures compliance with [NACHA's WEB Debit rule](https://www.nacha.org/rules/supplementing-fraud-detection-standards-web-debits). To use Account Validation Assistant, you must: * sign up to the [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) product * have the Account Validation Assistant (AVA) feature enabled * have Data Connect Full fully configured with an `experienceId` for the ACH product type - refer to [Customizing Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#step-2-create-or-modify-a-data-connect-experience) for details Note: Contact your Sales Representative/Account Manager if you need help creating a Data Connect experience to use with Account Validation Assistant. ## How It Works {#how-it-works} The customer enters their routing and account number to initiate two microdeposits. Once received, the customer has ten days to return and enter the two microdeposit amounts to verify their bank account. The customer has three attempts to verify the microdeposits. You can integrate AVA using [Data Connect Full](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). Additional screens within the Data Connect experience enable the customer to enter their bank account details. Once the microdeposits are made, you need to prompt them to check their banking website. You can then generate a special microdeposits verification Data Connect URL which enables your customer to confirm the deposit amount in order to validate the banking information. Note: Data Connect Lite integration is currently unavailable. Diagram ava-connect The [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) includes UX recommendations and best practices advice for how to present the [AVA flow](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md) in your application with Data Connect Full. ## Data Connect Full AVA Integration {#data-connect-full-ava-integration} The initial Data Connect Full session enables the customer to enter their FI details and initiates the microdeposits. Once the microdeposits are confirmed as settled, the customer then verifies the deposits through a separate Data Connect session. The following steps describe how to create the initial Data Connect Full session and confirm that the microdeposits were settled. 1. **Create a customer record.** If you do not already have a customer record for this customer, create one using the [Add Active Customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) (or [Add Testing Customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers)) endpoint. The response includes an `id` value - this is the **Customer ID** you use in the next step. 2. **Generate a Data Connect URL.** Call [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) using the customer ID. Set the `experience` parameter to the experience ID configured for the ACH product type with AVA enabled. * Optionally provide a `webhook` URL to receive microdeposit notifications, and a `redirectUri` so that the customer returns to your application when the session ends. * If you do not provide a `webhook`, you can poll the [Get Micro Entries Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#get-microdeposits-details) endpoint to check the microdeposit status instead (see step 4). 3. **Customer completes the Data Connect session.** Present the Data Connect URL to your customer. When the customer's financial institution cannot be securely linked, the AVA experience presents additional screens that allow the customer to enter their routing and account number manually. Mastercard initiates the two microdeposits to the entered account as part of this flow. No separate API call is required. 4. **Confirm the microdeposits are completed.** Before prompting the customer to verify the microdeposit amounts, confirm that the deposits have been dispatched to the financial institution. You can do this in either of these ways: * **Webhook (recommended)** - if you provided a `webhook` in step 2, Mastercard sends a `microdepositInitiated` event when the deposits are submitted, followed by a `microdepositStatus` event with `microdepositStatus: Completed` once they have been dispatched. See [Notifications](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#notifications) for example payloads. * **Polling** - call the [Get Micro Entries Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#get-microdeposits-details) endpoint and check the `status` field. Wait until the status is `Completed` before continuing.
Microdeposits can take up to three business days to settle in the customer's account. Once the status is `Completed`, prompt the customer to return to your application so that you can present the microdeposit verification URL described in [Verify Microdeposits](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#verify-microdeposits). ### Verify Microdeposits {#verify-microdeposits} The customer can verify the microdeposits were successfully completed using Data Connect once the deposits have been received. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/AVA-verify-microdeposits.png) Once the microdeposits have been posted to the customer's account, the customer can return to your application to verify the microdeposit amounts within Data Connect. You can prompt your customer to verify the microdeposits at any stage after you have confirmed that they were completed. Customers may also return of their own accord once they see the microdeposits being posted in their bank account. Tip: In order to generate the microdeposit verification URL, you will need the customer account ID. You can obtain this in either of the following ways: * Call the [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md?view=api#GetCustomerAccounts) API with the query parameter `?account_type=ava` which returns account numbers for the specified customer. For example: `GET /aggregation/v1/customers//accounts?account_type=ava` * Alternatively, the `microdepositInitiated` webhook event provides the account ID (see [Notifications](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#notifications)). The microdeposit verification URL can be generated by calling the following endpoint, where the customer can securely confirm the microdeposit amounts. API Reference: `POST /connect/v2/generate/microentry/verify` See the [AVA flow](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/ava/index.md) in the [Experience Design Guide](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md) for more detail of the user experience that will be presented to the customer for them to verify the microdeposits. Once verification is complete, you can fetch ACH routing details for the account using the [Get Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) endpoint. ### Get Microdeposits Details {#get-microdeposits-details} You can use this endpoint to get the status of a microdeposit entry using the customer's Account ID. API Reference: `GET /microentry/v1/customers/{customerId}/accounts/{accountId}` The following explains all the possible microdeposit and account status, with a recommended partner action. | Microdeposit Status | Account Status | Description | Partner Action | |---------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | Pending | Pending | Microdeposits are not yet dispatched to the Receiving Depository Financial Institution (RDFI) | Wait a few minutes and check the status again | | Completed | Pending | Microdeposits are sent to receiving financial institution for posting in customers account | Re-engage the customer to verify the deposits (Finicity will also try to verify the amounts automatically in some cases) | | Verified | Active | Microdeposits are verified automatically by Finicity or manually by the customer. This constitutes a billing event and the partner will be charged at this point | The partner calls getAccountDetails endpoint to retrieve ACH information | | Rejected | Inactive | Microdeposits are rejected by the receiving financial institution | The partner can start over the process again | | Returned | Inactive | Microdeposits are returned by the receiving financial institution | The partner can start over the process again | | Failed | Inactive | An error occurred while sending microdeposits to the customer account or the customer has exceeded 3 attempts to verify the deposit amounts | The partner can start over the process again | | Expired | Inactive | Microdeposits have remained in 'completed' state for 10 days or longer | The partner can start over the process again | ## Testing AVA {#testing-ava} To simulate the scenarios where customers would use AVA, follow these steps: | Scenario | Steps to reproduce | |--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Financial Institution is not found, decertified or has connection issues | Search for bank 'Finbank offline' or 'unicorn', then manually connect. | | The Financial institution is ACH decertified | Search for 'Finbank Decertified' bank and add an account using the credentials specified in our [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#sign-in-authentication-profiles) documentation. | Use the routing and account numbers from the table below for testing purposes to simulate the respective AVA flows. To verify microdeposits during testing, always use the amounts $0.01 and $0.02. You have up to three attempts to enter the correct microdeposit amounts. If you exceed three attempts, you'll need to restart the AVA flow. Warning: Use only testing customers and the test account numbers mentioned below during testing. If real account numbers are detected, an error code 42003 will be sent to the webhook listener. | Routing number | Account number | Scenario | |------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------| | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 5111111111 | User verification - The microdeposits must be manually verified. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 5999999999 | User verification - The microdeposits must be manually verified. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 6111111111 | Auto verification - The microdepositStatus will be automatically set to verified after an hour. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 6222222222 | Auto verification - The microdepositStatus will be automatically set to verified after an hour. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 4111111111 | Reminder - A reminder webhook will be sent to prompt the Partner to seek verification of the microdeposits. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 4999999999 | Reminder - A reminder webhook will be sent to prompt the Partner to seek verification of the microdeposits. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 2111111111 | Expired - The timeframe in which the microdeposits can be verified has expired. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 2999999999 | Expired - The timeframe in which the microdeposits can be verified has expired. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 1111111111 | Rejected - The microdeposits were rejected by the Financial Institution. | | Any valid routing number which is linked to at least one FI that is not ACH certified, for example: 011000138, 121000358



| 1999999999 | Rejected - The microdeposits were rejected by the Financial Institution. | ## Notifications {#notifications} You can receive notifications for all microdeposit status changes through the [webhook listener](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) you provided when generating the Data Connect URL. The following webhook event notifications are available for the AVA flow: Note: A `microdepositStatus` event with an empty `payload` may arrive while the deposit is being prepared, just before the `microdepositInitiated` event. You can safely ignore these events and wait for the populated `microdepositStatus` event that follows. In addition to the AVA-specific events listed below, the Data Connect session also emits a [`done`](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md#done) event when the customer closes the session. See [Connect Webhook Events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md) for the full list of Connect events. * Pending * StatusChange * Reminder * Success * Rejected * Returned * Error * VerificationError ```pending { "customerId": "6015986195", "eventType": "microdepositInitiated", "eventId": "1721812939549-8c6739f026337a93dbe2e063", "payload": { "accountId": "6030377866", "status": "Pending", "depositCount": 2, "statusDescription": "Deposits are submitted for processing", "railType": "rtp" } } ``` ```statusChange { "customerId": "6015986195", "eventType": "microdepositStatus", "eventId": "1721812941769-ca8e1e85cc3683cb43a8fc88", "payload": { "event": { "id": "ca81920d-a1b5-4c6e-b373-4d5a4c1505f8", "type": "statusChange", "class": "microdeposit" }, "accounts": [ { "id": "6030377866", "name": "Savings", "type": "moneyTransferSavings", "status": "pending", "customerId": "7021638961", "createdDate": "2024-07-24T09:22:19Z", "lastUpdatedDate": null, "microdepositStatus": "Completed", "description": "Microdeposits initiated successfully.", "microdepositCreatedDate": "2024-07-24T09:22:19Z", "microdepositLastUpdatedDate": null, "autoVerifiedAccount": null } ] } } ``` ```reminder { "customerId": "6015986195", "eventType": "microdepositStatus", "eventId": "1681208719662-57a4b9e02661510b390c00e6", "payload": { "event": { "id": "df569bba-39d6-4f9a-a321-d2d6d604c58b", "type": "reminder", "class": "microdeposit" }, "accounts": [ { "id": "6043045865", "name": "Checking", "type": "moneyTransferChecking", "status": "pending", "customerId": "6015986195", "createdDate": "2023-04-11T10:25:13Z", "lastUpdatedDate": null, "microdepositStatus": "Completed", "description": "Engage the user for microdeposit verification before the window expires in 2 days.", "microdepositCreatedDate": "2023-04-11T10:25:13Z", "microdepositLastUpdatedDate": null } ] } } ``` ```success { "customerId": "6015986195", "eventType": "microdepositVerified", "eventId": "1672853918255-8f3bcd7d8e7f5c44b0021111", "payload": { "status": "Success", "statusDescription": "Microdeposits are verified successfully", "accountId": "6030377866" } } ``` ```rejected { "customerId": "6015986195", "eventType": "microdepositStatus", "eventId": "1709221545468-26ec6400711615d32d138f6d", "payload": { "event": { "id": "0cf5ed33-e45a-43c1-b4b7-a9574f587e0b", "type": "statusChange", "class": "microdeposit" }, "accounts": [ { "id": "7034681725", "name": "Checking", "type": "moneyTransferChecking", "status": "inactive", "customerId": "7018439927", "createdDate": "2024-02-29T15:45:43Z", "lastUpdatedDate": null, "microdepositStatus": "Rejected", "description": "Microdeposits are rejected due to AM04", "microdepositCreatedDate": "2024-02-29T15:45:43Z", "microdepositLastUpdatedDate": null, "autoVerifiedAccount": null } ] } } ``` ```returned { "customerId": "6015986195", "eventType": "microdepositStatus", "eventId": "1709650152470-54befb85f22f7c2d6ca283a4", "payload": { "event": { "id": "43bbe0a1-1f4c-48b1-a50d-738ee53cad39", "type": "statusChange", "class": "microdeposit" }, "accounts": [ { "id": "7035839537", "name": "Checking", "type": "moneyTransferChecking", "status": "inactive", "customerId": "7019429790", "createdDate": "2024-03-05T14:49:10Z", "lastUpdatedDate": null, "microdepositStatus": "Returned", "description": " Microdeposits are returned by the receiving financial institution ", "microdepositCreatedDate": "2024-03-05T14:49:10Z", "microdepositLastUpdatedDate": null, "autoVerifiedAccount": null } ] } } ``` ```error { "customerId": "6015986195", "eventType": "microdepositError", "eventId": "1721814857537-236dd6e5b29d6c834e912f81", "payload": { "code": "3100001", "message": "Account Already Exist", "status": 409 } } ``` ```verificationError { "customerId": "6015986195", "eventType": "microdepositVerificationError", "eventId": "1672853442355-3078e6f48295faa884555126", "payload": { "error": { "code": "3200004", "message": "Microdeposit amounts didn't match", "status": 400, "level": "error", "user_message": "Microdeposit amounts didn't match" }, "accountId": "6030377866" } } ``` ### Notification Error Codes {#notification-error-codes} The `microdepositError` and `microdepositVerificationError` webhook events return an error code in the `payload` to indicate why the request failed. Select a tab below to see the codes that can be returned for each event. | CODE | DESCRIPTION | |---------|-------------------------------------------------------------------------------------------------------------------| | 20024 | Invalid routing number | | 42003 | Testing customer should not add real accounts | | 60009 | Invalid callbackUrl | | 3000000 | Microdeposit initiation can't be processed at this time due to technical difficulties. Please try after some time | | 3000001 | Invalid account number | | 3000002 | Invalid account name | | 3000003 | Invalid memo | | 3000010 | Unable to manually link bank account | | 3100001 | Account already exists | | 3200001 | Microdeposits initiation failed | | CODE | DESCRIPTION | |---------|-----------------------------------------------| | 3000003 | Invalid amount format | | 3200002 | Microdeposit is in `` status | | 3200003 | Microdeposit verification attempts exceeded | | 3200004 | Microdeposit amounts didn't match | | 3300001 | Too many requests. Please try after some time | ## Data Connect Lite Endpoints {#data-connect-lite-endpoints} Warning: These endpoints are for use with the Data Connect Lite flow, which is not currently available for new integrations. ### Initiate Microdeposits {#initiate-microdeposits} You must have collected all the required bank account details, including account number and routing number, before initiating microdeposits for the customer (via your application UI or other means). API Reference: `POST /microentry/v1/customers/{customerId}`
Optionally, you can provide a suitable `callbackUrl`, which AVA will use to send a notification when the status of the microdeposit changes. See [Notifications](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md#notifications) for details. If the call to Initiate Microdeposits is unsuccessful, one of the following Error Codes will be returned in the response: | CODE | DESCRIPTION | |---------|-------------------------------------------------------------------------------------------------------------------| | 20024 | Invalid routing number | | 42003 | Testing customer should not add real accounts. | | 60009 | Invalid callbackUrl | | 3000000 | Microdeposit initiation can't be processed at this time due to technical difficulties. Please try after some time | | 3000001 | Invalid account number | | 3000002 | Invalid account name | | 3000003 | Invalid memo | | 3100001 | Account already exists | | 3200001 | Microdeposits initiation failed | | 3000010 | Unable to manually link bank account | ### Verify Microdeposit Amounts {#verify-microdeposit-amounts} API Reference: `POST /microentry/v1/customers/{customerId}/accounts/{accountId}/amounts` Once verification is complete, you can fetch ACH routing details for the account using the [Get Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) endpoint. If the call to Verify Microdeposits is unsuccessful, one of the following Error Codes will be returned in the response: | CODE | DESCRIPTION | |---------|-----------------------------------------------| | 3000003 | Invalid amount format | | 3200002 | Microdeposit is in `` status | | 3200003 | Microdeposit verification attempts exceeded | | 3200004 | Microdeposit amounts didn't match | | 3300001 | Too many requests. Please try after some time | --- # Feedback Loop source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md Feedback Loop is a secure and standardized way for you to share payment outcome data for Open Finance Pay products so Mastercard can continuously refine risk models and reduce payment failures across the network. This data can be submitted securely via an AWS S3 directory with optional file-level encryption using Mastercard-provided keys. Feedback Loop currently supports the below products and will be extended to support other Open Finance products in the future. * [Payment Success Indicator (PSI)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) -- improves the accuracy of payment success predictions and reduces unauthorized fraud risk by learning from real transaction outcomes. * [Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) -- reduces payment failures by identifying and correcting data quality issues based on returned ACH payment results. Note: All data submitted through the Feedback Loop is protected using industry-standard protocols. Each partner has isolated access to a dedicated S3 directory, ensuring strict data segregation. Files are retained for 30 days post-processing and handled in accordance with Mastercard's enterprise security and compliance standards. Tip: We recommend sharing data at consistent intervals (monthly or bi-weekly) to ensure models stay current and product performance improves consistently. ### Benefits {#benefits} Sharing data through Feedback Loop helps improve outcomes for you and your customers. * **Reduce payment failures**: improved data accuracy lowers return rates, minimizes exception handling, and reduces related processing fees. * **Enhance product performance**: shared data refines Mastercard's predictive models, improving the accuracy and reliability of products such as PSI, ACH, and AO+. * **Shape future innovation**: your feedback directly informs product enhancements and the development of new solutions aligned with your needs. ## How It Works {#how-it-works} ### High-Level Workflow {#high-level-workflow} 1. Prepare a CSV data file following Mastercard's schema for the product - see [Submission Format](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#submission-format). 2. Upload the file to the designated `inbound` directory within the assigned AWS S3 directory. * File-level encryption using Mastercard-provided keys can **optionally** be applied - see [Encryption](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#encryption) on this page. 3. Mastercard retrieves, decrypts, validates, and processes the submitted data. 4. After processing, an acknowledgement file or an error report (if validation issues are detected) is made available in the `outbound` directory within the same S3 directory. Monitor this directory to retrieve output files. Diagram feedback-loop-normal ## Onboarding {#onboarding} Contact your Customer Success Manager to start using Feedback Loop. Tell your Customer Success Manager whether or not you want to enable encryption. See [Encryption](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#encryption) for details. ### S3 Configuration {#s3-configuration} To enable access to your organization's dedicated directory within our S3 bucket, Mastercard will provide you with our AWS Account ID and the S3 bucket name. Using this information, your team must: * create an AWS IAM Role in your AWS account * share the IAM Role ARN with Mastercard
This enables us to grant you access to your dedicated directory. Your dedicated prefix is: `s3:////feedback-loop/` Under this prefix we create two folders: * `inbound/` -- to upload your data files to Mastercard * `outbound/` -- to download acknowledgements and error reports from Mastercard
Our buckets have **ACLs disabled** . Do not set ACLs or send `x-amz-acl` headers in `PutObject` requests. Requests that try to read or set ACLs will be denied. Our bucket enforces SSE‑KMS. Ensure your IAM role used for transfers has the following KMS actions on Mastercard's KMS key ARN: `kms:GenerateDataKey`, `kms:Encrypt`, `kms:Decrypt`, `kms:ReEncrypt*`, `kms:DescribeKey`. If your AWS organization uses **Service Control Policies (SCPs)**, verify they allow the above actions for our AWS account and KMS key ARNs. ## Submission Format {#submission-format} This is the format for data you want to submit to Mastercard by uploading to the S3 directory. All files must be in CSV format and contain no more than 100,000 data rows per file. Each file contains a two-row header, followed by [product-specific data](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#product-specific-data-requirements). The product-specific data format depends on whether you are submitting data for Payment Success Indicator or Account ACH. Use a separate file for each product. This is an example of the beginning of a submission data file for PSI: ```csv fileName,parentPartnerId,dateTime,recordCount,startDate,endDate,product Bulk_Feedback_01012025235959.csv,123456789,2025-01-01T23:59:59:999Z,2,12/31/2024,1/1/2025,psi partnerId,customerId,payReqId,paymentId,settled,initiationAmount,initiationDate,settledDate,returnDate,returnReason 123456789,123456789,123456789,942b6870-461e-4d2e-80dd-a4672fd61b99,Y,10,12/31/2024,1/1/2025,, 123456789,123456789,123456789,572b6870-481d-7z2f-19eg-b1122gd81b45,N,10,12/31/2024,,1/1/2025,R20 ... ``` ### File Naming {#file-naming} The filename must be in the form `Bulk_Feedback_mmddyyyyHHMMSS.csv`. Warning: You must name the file correctly. Files that do not match `^Bulk_Feedback_\d{8,14}\.csv$` will not be processed. ### Header Requirements {#header-requirements} * The first row of the file must contain the header field names (comma-separated). * The second row must contain the corresponding header field values. * All required header fields must be listed in row 1, with a corresponding value provided in row 2. * Optional header fields may be omitted entirely, or listed in the header row but with no value provided. #### Header Example {#header-example} This is an example of the header rows showing only the required fields. ```csv fileName,dateTime,recordCount,product "Bulk_Feedback_01012025235959.csv","2025-01-01T23:59:59Z","2","psi" ``` #### Header Fields {#header-fields} | Field Name | Type | Description | Required | Example | |-------------------|----------|------------------------------------------------------------------------|----------|------------------------------------| | `fileName` | string | Name of the file (`Bulk_Feedback_mmddyyyyHHMMSS.csv`) | Y | `Bulk_Feedback_01012025235959.csv` | | `parentPartnerID` | integer | Only used if required to track relationships between partner companies | N | `12345` | | `dateTime` | datetime | Date \& time the file is generated (ISO 8601) | Y | `2025-01-01T23:59:59Z` | | `recordCount` | integer | Number of individual records in the file | Y | `2` | | `startDate` | datetime | Start date of transactions included (ISO 8601) | N | `2025-01-01` | | `endDate` | datetime | End date of transactions included (ISO 8601) | N | `2025-01-31` | | `product` | string | Open Finance product this file relates to (supported: `ach`, `psi`) | Y | `psi` |
### Product-Specific Data Requirements {#product-specific-data-requirements} Each product has its own schema with a defined set of required and optional fields for the product-specific data rows. Warning: `partnerId` is a required field for all products. Make sure you provide the partner ID of your **Production** project, not a Sandbox project. To find the correct partner ID, go to your [Mastercard Developers Dashboard](https://developer.mastercard.com/dashboard), select your **Production** project and go to **Credentials \> Production**. If any required fields for a given product are missing in a row, the whole submission is rejected. Ensure that all required fields are populated according to the product schema. The schemas for each product are detailed in the following sections. #### Payment Success Indicator (PSI) Fields {#payment-success-indicator-psi-fields} | Field Name | Data Type | Description | Required | Notes | |--------------------|-----------|------------------------------------------------------------|----------|---------------------------------------------------------------| | `partnerId` | integer | Production partner ID provided by Mastercard | Y | Must exist in system | | `customerId` | integer | Customer ID provided by Mastercard | Y | Must exist in system | | `payReqId` | string | ID of the payment transaction this feedback relates to | Y | Use payment request ID (`payReqId`) from earlier PSI response | | `paymentId` | string | Partner-provided identifier to track/update payment status | Y | Helps correlate multiple submissions (e.g. retries) | | `settled` | string | Indicates whether the transaction settled | Y | Values: `Y` or `N` | | `initiationAmount` | decimal | Value of the transaction | Y | Digits or decimal | | `initiationDate` | string | Date the transaction was initiated | Y | Provide actual initiation timestamp | | `settledDate` | string | Date the transaction settled | Y | Leave blank if `settled = N` | | `returnDate` | string | Date the transaction was returned (yyyy-mm-dd) | Y | Leave blank if `settled = Y` | | `returnReason` | string | Reason the transaction was returned (e.g. ACH return code) | Y | Leave blank if `settled = Y` | Example PSI input file: [PSI-BulkFeedbackLoop-Example.csv](https://static.developer.mastercard.com/content/open-finance-us/uploads/loop/PSI-BulkFeedbackLoop-Example.csv) (476B) #### Account ACH Details Fields {#account-ach-details-fields} | Field Name | Data Type | Description | Required | Notes | |----------------------|-----------|------------------------------------------------------------|----------|-----------------------------| | `partnerId` | integer | Production partner ID provided by Mastercard | Y | Must exist in system | | `customerId` | integer | Customer ID provided by Mastercard | Y | Must exist in system | | `accountId` | string | Account ID assigned by Mastercard | Y | Must match existing record | | `accountNumberLast4` | string | Last 4 digits of account number used to initiate payment | N | Example: `1234` | | `routingNumber` | string | Routing number used to initiate payment | N | Example: `091000019` | | `paymentId` | string | Partner-provided identifier to track/update payment status | Y | Useful for retries/updates | | `settled` | string | Indicates whether the transaction settled | Y | Values: `Y` or `N` | | `initiationAmount` | decimal | Value of the transaction | N | Digits or decimal | | `initiationDate` | string | Date the transaction was initiated | Y | Actual initiation timestamp | | `settledDate` | string | Date the transaction settled | N | Blank if `settled = N` | | `returnDate` | string | Date the transaction was returned (YYYY-MM-DD) | Y | Blank if `settled = Y` | | `returnReason` | string | Reason the transaction was returned (e.g. ACH return code) | Y | Blank if `settled = Y` | Example ACH input file: [ACH-BulkFeedbackLoop-Example.csv](https://static.developer.mastercard.com/content/open-finance-us/uploads/loop/ACH-BulkFeedbackLoop-Example.csv) (538B) ## Acknowledgement Format {#acknowledgement-format} This is the format of files returned by Mastercard indicating processing status and any detected errors. If `errorCount` \> `0`, one or more records in the file failed validation. Records that pass validation are still processed and ingested successfully. You should review and correct the invalid records before resubmitting them. Tip: Valid records are accepted and processed even if other records in the same file fail validation. Only invalid records need to be corrected and resubmitted -- there's no need to resubmit the entire file. See [Error Handling and Feedback](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#error-handling-and-feedback) below for details of file format error codes. If you have chosen to enable encryption, you will need to decrypt the acknowledgement file - see [Decrypting Data](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#decrypting-data). | Field Name | Type | Description | Required | Example | |------------------------|----------|------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------| | `fileName` | string | Name of the acknowledgement file | Y | `Bulk_Feedback_Acknowledgement_01012025001500.csv` | | `receivedFileName` | string | Original inbound file name | Y | `Bulk_Feedback_01012025235959.csv` | | `receivedFileDateTime` | datetime | Date/time original file was received (ISO 8601) | Y | `2025-01-01T23:59:59Z` | | `successCount` | integer | Count of successfully processed records | N | `200` | | `errorCount` | integer | Count of records with errors (0 = no errors; \>0 means some records failed validation and must be corrected and resubmitted) | N | `5` | | `totalCount` | integer | Total number of records received | N | `205` | | `fileFormatErrorCode` | string | File format error code (if applicable) | N | `ERR-101` | | `fileFormatErrorDesc` | string | Description of the file format error | N | `Missing required field: recordCount` | | `ackTimestamp` | datetime | Date/time the acknowledgement was generated (UTC ISO 8601) | Y | `2025-01-02T00:15:00Z` | Sample acknowledgement files: * Success: [Bulk_Feedback_acknowledgement_20250902124518-success.csv](https://static.developer.mastercard.com/content/open-finance-us/uploads/loop/Bulk_Feedback_acknowledgement_20250902124518-success.csv) (281B) * Errors: [Bulk_Feedback_acknowledgement_20250902161006-error.csv](https://static.developer.mastercard.com/content/open-finance-us/uploads/loop/Bulk_Feedback_acknowledgement_20250902161006-error.csv) (1KB) ## Error Handling and Feedback {#error-handling-and-feedback} This table contains the errors that may be returned by Mastercard in an acknowledgement file. If you receive validation errors, correct the affected records and resubmit them. You do not need to resubmit the entire file. Tip: Valid records are accepted and processed even if other records in the same file fail validation. Only invalid records need to be corrected and resubmitted -- there's no need to resubmit the entire file. | Error Code | Error Description | Action to be taken | |------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `450001` | File format error in file \. Unable to read or parse the file. Expected file format: CSV | Fix the error and resend the entire file. | | `450002` | Missing required field(s): \ in line \ This error can occur on multiple field names in a line item. Please verify. | Include the mandatory fields and resend the affected records. | | `450003` | \ has invalid data in line \. The \ should be numeric OR \ has invalid data in line \. The \ should not be future date. OR \ has invalid data in line \. The \ should be boolean For example: - `settled` indicator must be 'Y' or 'N' - `initiatedAmount` should be numeric and can have up to two decimal places - `settledDate` must follow YYYY-MM-DD format | Correct the field value and resend affected records. The error can occur on multiple fields in a line item, so check all fields. | | `450004` | No record found in our system for partner: \ in line \ OR No match found for partner: \, customer: \, account: \ combination in line \ The combination of `partnerId`, `customerId` and `accountId` must match a valid record | Fix the failed record and resend it. | | `450005` | Required file(s) missing - provide .bin and metadata.json files | Provide both a .bin file and a .metadata.json file in the zip archive. | | `450006` | Unable to decrypt .bin file in zip | Make sure that: - the .bin file is encrypted - the .metadata.json file is valid JSON and contains encryption key data that was provided via Mastercard Developers. | ## Encryption {#encryption} For additional security, file-level encryption may be applied using Mastercard-provided keys. Note: Encryption is **optional**. Enabling encryption is an all-or-nothing setting --- it is either enabled or disabled for all Feedback Loop uploads. Contact your Customer Success Manager if you want to enable encryption. Feedback Loop supports **symmetric AES‑256 with JWE metadata** only. PGP/GPG is not supported. To use encryption, you must have a project in Mastercard Developers with Production access and encryption key generation enabled. Tell your Customer Success Manager the project's partner ID. To find the partner ID, go to your [Mastercard Developers Dashboard](https://developer.mastercard.com/dashboard), select your **Production** project and go to **Credentials \> Production**. If encryption is enabled: * you must encrypt all your submission files. * instead of providing a single CSV, you must provide a ZIP containing an encrypted `.bin` file with JSON metadata. * acknowledgement files from Mastercard are encrypted.
| Encryption toggle | What you upload to `inbound/` | What you receive in `outbound/` | |-------------------|--------------------------------------------|-----------------------------------------------------------------| | Disabled | A single CSV (`Bulk_Feedback_*.csv`) | A single acknowledgement CSV | | Enabled | A ZIP containing `.bin` + `.metadata.json` | An encrypted ZIP with `*_success.bin` / `*_fail.bin` + metadata |
Diagram feedback-loop-encrypt ### Encryption Keys {#encryption-keys} Data must be encrypted with two keys: * the Client Encryption Key (generated by your organization). * the Mastercard Encryption Key for your Production project (provided by Mastercard).
You can create keys from the [Mastercard Developers Dashboard](https://developer.mastercard.com/dashboard). Note: Key creation is not enabled by default. If you do not see the option, ask your Customer Success Manager to enable it. Once created, you can view and download the keys from the **Credentials** section when viewing your Production project details. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/mcd-keys-prod-keys-openfinance.png) ### Encrypting Data {#encrypting-data} There are two aspects to the encryption process: * You will need to encrypt your CSV data file using an AES-256 ephemeral key. * Then you need to encrypt your AES-256 ephemeral key, IV byte array, and encryption tag using JSON Web Encryption (JWE). This should then be packaged as a metadata file in JSON format. The resulting two files should then be placed in a zip and sent to Mastercard via S3. Follow the steps below to securely send Feedback Loop data to Mastercard: 1. Prepare the submission data in a CSV file (see [Submission Format](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#submission-format) on this page). 2. Create an initial vector (IV) byte array and an ephemeral AES 256-bit key as a data encryption key. When creating this key, use the AES algorithm in GCM mode (AES/GCM/NoPadding). You can find sample code for creating both an IV byte array and an AES ephemeral key on GitHub [here](https://github.com/Mastercard/client-encryption-java/blob/main/src/main/java/com/mastercard/developer/encryption/aes/AESEncryption.java#L28). 3. Encrypt the CSV file using the ephemeral key and IV byte array from step 2, with the AES encryption algorithm in GCM mode. Name this file using the naming convention `Bulk_Feedback_mmddyyyyHHMMSS.bin`. The encryption result will also return a `tag` value that will be used in the next step. The following python example illustrates this: * Python ```python from Crypto.Cipher import AES from Crypto.Random import get_random_bytes key = get_random_bytes(32) # 32 bytes X 8 bits = 256 bits iv = get_random_bytes(16) cipher = AES.new(key, AES.MODE_GCM, nonce=iv, use_aesni=True) blocksize = 64 * 1024 * 1024 # 64 MB block with open("path/to/raw/Bulk_Feedback_mmddyyyyHHMMSS.csv", 'rb') as reader, \ open("path/to/encrypted/Bulk_Feedback_mmddyyyyHHMMSS.bin", 'wb') as writer # encrypt large file in 64 MB chunk. This is to avoid loading entire file in memory while True: block = reader.read(blocksize) if not block: break writer.write(cipher.encrypt(block)) tag = cipher.digest() ``` 4. Mastercard will need to know how to decrypt your encrypted CSV file. To do this you need to send the necessary details within a JWE. Encode the `key`, `iv`, and `tag` values as base64 encoded strings (with ASCII codec), and create a JSON metadata payload in the following format: ```json { "key": "5gO+78x1ZjKG3BzwY8AP9dovzUyrBtL/HNgrVIggEIw=", "iv": "9PYO6dNmmTuchtbpwT7ldA==", "tag": "+vEElaaYP05RMAvR42QEHw==" } ``` Encrypt this metadata with JWE Encryption. You can use the [Mastercard Client Encryption Library](https://github.com/Mastercard?&q=client-encryption) to do so. You will need to use your Client Encryption Key tied to your project when setting up the JWE configuration. * Python ```python import json from client_encryption.jwe_encryption_config import JweEncryptionConfig from client_encryption.jwe_encryption import encrypt_payload, decrypt_payload metadata = { "key": "5gO+78x1ZjKG3BzwY8AP9dovzUyrBtL/HNgrVIggEIw=", "iv": "9PYO6dNmmTuchtbpwT7ldA==", "tag": "+vEElaaYP05RMAvR42QEHw==" } payload = { "enc": metadata, } pub_cert_path = "path/to/client-encryption-key" conf = JweEncryptionConfig({ "paths": { "$": { "toEncrypt": { "enc": "enc", }, "toDecrypt": {} } }, "encryptedValueFieldName": "jwe", "encryptionCertificate": pub_cert_path }) enc = encrypt_payload(payload=payload, config=conf) jwe = enc["enc"] with open("path/to/Bulk_Feedback_mmddyyyyHHMMSS.metadata.json") as metaf: metaf.write(json.dumps(jwe)) ``` 5. The JWE created will be used in the next step. 6. Package the returned JWE into a JSON file called `Bulk_Feedback_mmddyyyyHHMMSS.metadata.json` in the following form: * Json ```json { "jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiZTI0YzAyZDU0NGIyYjExNmJhMDZlZDc2NWNjZDY1MzI3OGZkNmIxODQ2MTAxZTU0MjdlNjM2YzkwY2RlZjk0OSIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24ifQ.YbgsnILXFkVba7mU0PUQpMwsWuVASTAfTIeokghGnCgQbLpjKag75slXCQyroJ27fK0Y_Qgus05yWKYKRaP6zdP1YO5mLIm44iz-EPpz1e3v6DgkZ5MMTxeMqREPkC03cTO9OIajIw0UgbafrmfJ18izJojKerdsnMvnEKZ8_23oqMYN7CHW9Jg5HuEaqxKme0OoITJpzs4Jk-bPsvtxeWam8iNH9l77hWuf2wyTIW_qyx5J9vBXNB6_96uTCtHECttOQkk7-Tk1zYmhKqR4ZG8AOMTIE4YHFmkQoSLxU8YAuMDQFN4Xr5egoo9AlUkN7urrf37gdgUG1ldPVxgXcg.EjRNhXhJUj50-q9DB7XSkg.4fGc5xCuoySNzbMhDYUGRdEA2FfRqlV5yEdrDMlu3sz3tHycLrLJXYBaPyueCUWsi2RJpG85-nY-o689Z2TOQkfu9UZty8nyLfmFfhpUGwhcCaN-OZaXSYOxsLR2UIgbJ8VuFnml1dJ5BfswIaJF2UZXjfbA6yNHig4Jvg.aPVGN0J-JUfqzYhuQ_pkFA" } ``` 7. Package the `Bulk_Feedback_mmddyyyyHHMMSS.bin` and `Bulk_Feedback_mmddyyyyHHMMSS.metadata.json` into a zip folder using this naming convention: `Bulk_Feedback_mmddyyyyHHMMSS.zip` 8. Transfer the zip package to Mastercard via S3 (in the `/inbound` directory). Warning: Make sure you name the files as specified --- otherwise, the upload will not be processed. ### Decrypting Data {#decrypting-data} Downloading and decrypting the acknowledgement file is the reverse of the process above for sending files. You will need to download a zip, extract the JWE from the metadata file, and use the ephemeral encryption key details from the JWE to then decrypt the output file itself. There may be two output files, as any failures will be returned in a second file along with error messages. 1. Transfer the output file from the Mastercard S3 directory to your network. The file will be named with this naming convention: `Bulk_Feedback_mmddyyyyHHMMSS_output.zip` 2. Unzip the files: * `Bulk_Feedback_mmddyyyyHHMMSS.metadata.json` - This file contains the encryption metadata. * `Bulk_Feedback_mmddyyyyHHMMSS_success.bin` - This is an encrypted file which contains valid records. * `Bulk_Feedback_mmddyyyyHHMMSS_fail.bin` - This is an encrypted file which contains error details. Fix the errors and resubmit the entire file. The metadata JSON file contains two fields, `jwe` and `fingerprint`: * `jwe` contains the encrypted `key` and `iv` used during the encryption of the output files, plus the `successTag` and `failTag` extracted from encrypted output files. * `fingerprint` contains the fingerprint of the key pair used for encrypting the output files. For example: * Json ```json { "jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiZTI0YzAyZDU0NGIyYjExNmJhMDZlZDc2NWNjZDY1MzI3OGZkNmIxODQ2MTAxZTU0MjdlNjM2YzkwY2RlZjk0OSIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24ifQ.YbgsnILXFkVba7mU0PUQpMwsWuVASTAfTIeokghGnCgQbLpjKag75slXCQyroJ27fK0Y_Qgus05yWKYKRaP6zdP1YO5mLIm44iz-EPpz1e3v6DgkZ5MMTxeMqREPkC03cTO9OIajIw0UgbafrmfJ18izJojKerdsnMvnEKZ8_23oqMYN7CHW9Jg5HuEaqxKme0OoITJpzs4Jk-bPsvtxeWam8iNH9l77hWuf2wyTIW_qyx5J9vBXNB6_96uTCtHECttOQkk7-Tk1zYmhKqR4ZG8AOMTIE4YHFmkQoSLxU8YAuMDQFN4Xr5egoo9AlUkN7urrf37gdgUG1ldPVxgXcg.EjRNhXhJUj50-q9DB7XSkg.4fGc5xCuoySNzbMhDYUGRdEA2FfRqlV5yEdrDMlu3sz3tHycLrLJXYBaPyueCUWsi2RJpG85-nY-o689Z2TOQkfu9UZty8nyLfmFfhpUGwhcCaN-OZaXSYOxsLR2UIgbJ8VuFnml1dJ5BfswIaJF2UZXjfbA6yNHig4Jvg.aPVGN0J-JUfqzYhuQ_pkFA", "fingerprint": "cfb9bf8efec58af5f5231d73d7785f2eb3991c3dae8b1539a3cde9fdb6cd6dab" } ``` 3. Extract the JWE from the metadata and decrypt it to obtain the ephemeral key that was used by Mastercard to encrypt the processed file. You can use the Mastercard Client Encryption Library to do so with JWE decryption. Use the Mastercard Decryption Key associated with `fingerprint` to decrypt the `jwe` value. 4. Decrypting the JWE should produce a JSON file containing `key`, `iv`, `successTag` and `failTag`. These will be base64 encoded strings (with ASCII codec). Decode them to bytes. You will then be able to use these to decrypt the data files. 5. With AES in GCM mode and the `key` and `iv` from the previous step, decrypt the `.bin` files: * To decrypt the success file, use `Bulk_Feedback_mmddyyyyHHMMSS_success.bin` as the payload and the `success_tag` as the tag. * To decrypt the fail file, use `Bulk_Feedback_mmddyyyyHHMMSS_fail.bin` as the payload and the `fail_tag` as the tag. The following Python code example shows the decryption of the JWE and then the data files. * Python ```python import base64 enc_metadata = { "jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiZTI0YzAyZDU0NGIyYjExNmJhMDZlZDc2NWNjZDY1MzI3OGZkNmIxODQ2MTAxZTU0MjdlNjM2YzkwY2RlZjk0OSIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24ifQ.YbgsnILXFkVba7mU0PUQpMwsWuVASTAfTIeokghGnCgQbLpjKag75slXCQyroJ27fK0Y_Qgus05yWKYKRaP6zdP1YO5mLIm44iz-EPpz1e3v6DgkZ5MMTxeMqREPkC03cTO9OIajIw0UgbafrmfJ18izJojKerdsnMvnEKZ8_23oqMYN7CHW9Jg5HuEaqxKme0OoITJpzs4Jk-bPsvtxeWam8iNH9l77hWuf2wyTIW_qyx5J9vBXNB6_96uTCtHECttOQkk7-Tk1zYmhKqR4ZG8AOMTIE4YHFmkQoSLxU8YAuMDQFN4Xr5egoo9AlUkN7urrf37gdgUG1ldPVxgXcg.EjRNhXhJUj50-q9DB7XSkg.4fGc5xCuoySNzbMhDYUGRdEA2FfRqlV5yEdrDMlu3sz3tHycLrLJXYBaPyueCUWsi2RJpG85-nY-o689Z2TOQkfu9UZty8nyLfmFfhpUGwhcCaN-OZaXSYOxsLR2UIgbJ8VuFnml1dJ5BfswIaJF2UZXjfbA6yNHig4Jvg.aPVGN0J-JUfqzYhuQ_pkFA", "fingerprint": "cfb9bf8efec58af5f5231d73d7785f2eb3991c3dae8b1539a3cde9fdb6cd6dab" } jwe = enc_metadata["jwe"] fingerprint = enc_metadata["fingerprint"] # get the private key (Mastercard Encryption Key) associated with fingerprint private_key_file = "path/to/certs/keyname-mastercard-encryption-key.p12" payload = { "enc": jwe, } cfg = { "paths": { "$": { "toEncrypt": {}, "toDecrypt": { "enc.jwe": "dec", } } }, "encryptedValueFieldName":"jwe", "decryptionKey": private_key_file, "decryptionKeyPassword": "" } conf = JweEncryptionConfig(cfg) metadata = decrypt_payload(payload=payload, config=conf) key = base64.b64decode(metadata["key"]) iv = base64.b64decode(metadata["iv"]) tagSuccess = base64.b64decode(metadata["tagSuccess"]) tagFail = base64.b64decode(metadata["tagFail"]) def decrypt_file(key: bytes, nonce: bytes, enc_file: str, dec_file: str, tag: bytes): blocksize = 64 * 1024 * 1024 # 64 MB block with open(enc_file, 'rb') as reader, open(dec_file, 'wb') as writer: cipher = AES.new(key, AES.MODE_GCM, nonce=nonce, use_aesni=True) # decrypt large file in 64 MB chunk. This is to avoid loading entire file in memory while True: block = reader.read(batch_size) if not block: break writer.write(cipher.decrypt(block)) cipher.verify(tag) enc_file = f"path/to/Bulk_Feedback_mmddyyyyHHMMSS_success.bin" dec_file = f"path/to/Bulk_Feedback_mmddyyyyHHMMSS_success.csv" decrypt_file(key, iv, enc_file, dec_file, tagSuccess) enc_file = f"path/to/Bulk_Feedback_mmddyyyyHHMMSS_fail.bin" dec_file = f"path/to/Bulk_Feedback_mmddyyyyHHMMSS_fail.csv" decrypt_file(key, iv, enc_file, dec_file, tagFail) ``` --- # Consumer Foresight source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md Consumer Foresight is an API based solution designed to help banks and Fintechs personalize consumer experiences for use cases like personal financial management (PFM), marketing/product segmentation, alerts/nudges to drive better financial decisions, and other personalization use cases. The service provides tailored consumer insights for end users against 16 different spend categories. These insights can be generated using the end user's third-party permissioned Open Finance data, and/or your own first-party data submitted via [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md), as well as anonymized transactional data from the Mastercard network for benchmarking. For each category, Consumer Foresight delivers: * Historical Spending: Historical spending patterns aggregated by each spend category for a historical view of a consumer over the last 12 months. * Benchmarking: Spending benchmarked against 'like' peers, definable by location, age and income. * Forecasting: Data Science modeling predicts anticipated customer spending in each spending category for 3, 6, 9, and 12 months into the future. Note: Consumer Foresight is currently in Beta. Contact your Sales representative or Account manager to learn more. These insights are delivered on a per category basis and can be used to power more personalized experiences and messaging to end users. Note: This is a subscription service. You will be billed for each customer you generate a report for in a given month. Additional report refreshes for the same customer in the same month are free. ## Use Cases {#use-cases} * Personal financial management * Product and marketing personalization * Consumer alerts and behavior nudges * Spending health checks ## Benchmarking Options {#benchmarking-options} Consumer Foresight enables you to benchmark a consumer's spending in each category against one or more comparison groups. When you generate a report, you can use parameters to choose whether to benchmark against consumers with similar: * age * income * ZIP/postal code
You must use at least one parameter. If you use multiple parameters, the report benchmarks the consumer against each parameter, both individually and also in combination. For example, if you specify age and income, the response will include comparisons to consumers with similar age, consumers with similar income, and consumers with both similar age and income. ## Third-Party and First-Party Data {#third-party-and-first-party-data} The Consumer Foresight endpoint can use: * **third-party data**: account and transaction data authorized by the customer through Mastercard Data Connect from external institutions. * **first-party data** : customer transaction data you have provided through the Open Finance [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) service.
You can combine both sources of data into a single report. ### Supported Account Types {#supported-account-types} If you are using third-party data via Data Connect, the customer must have a checking, credit card or savings account. ## How It Works {#how-it-works} 1. Generate the required credentials to call the API. See [Create a Sandbox Project](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#create-a-sandbox-project). 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token). 3. Create a customer and link them to at least one account via Data Connect and/or submit data for them via Data Enrichment. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer). Review the different [Bank Account Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) and account types available for testing Data Connect in Sandbox - the report only works if the customer has a checking, credit card or savings account. 4. Call [Generate Non CRA Foresight Analytics Report Using 1st/3rd Party Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateForesightAnalyticsFirstThirdPartyNonCraReport) with selected input parameters. The response `id` element contains the report ID. * To use third-party data permissioned via Data Connect, provide a `customerId` in the request body. * To use first-party data you submitted via [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md), provide the `externalCustomerId` you supplied when uploading the data. * You can use third-party data, first-party data, or both in the same request. API Reference: `POST /decisioning/reports/foresight-analytics/userTypes/{userType}` 5. Call [Get Report by Report ID](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetReportById) using the report ID. Returns a JSON file with spending insights and forecasts. API Reference: `POST /decisioning/v3/reports/{reportId}` Warning: You must use **Get Report by Report ID** to retrieve reports generated with this endpoint. Other Get Report endpoints are not supported. Diagram consumer-foresight ## Reading a Consumer Foresight JSON Report {#reading-a-consumer-foresight-json-report} This section provides a detailed description of the structure and format of the Consumer Foresight JSON report. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. The JSON report is generated to provide data in a structured and machine-readable format. #### Example JSON Reports {#example-json-reports} The response contains different data depending on the selected input parameters. The following downloadable example reports show successful responses with test data. This example shows output benchmarked by postal code: [farpbfnoncra-profile-524.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/farpbfnoncra-profile-524.json) (1MB)
This example shows output benchmarked by postal code, age and income: [farpbfnoncra-multisegment.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/farpbfnoncra-multisegment.json) (167KB)
#### Consumer Foresight Attributes {#consumer-foresight-attributes} | Attribute | Definition | Type | |---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | ACCOMMODATION_SPENDING | Expenses related to accommodations such as hotels. | Transactional | | BOOKS_SPENDING | Expenses incurred for book purchases or reading. | Transactional | | CLOTHING_SPENDING | Expenses towards the purchase of clothes. | Transactional | | COMMUNICATION_SERVICES_SPENDING | Expenses incurred on phone, internet, broadband, television. | Transactional | | CONSUMER_ELECTRONICS_SPENDING | Electronics and software related expenses. | Transactional | | EATING_PLACES_SPENDING | Expenses incurred due to eating activities such as restaurants and coffee shops. | Transactional | | ENTERTAINMENT_SPENDING | Entertainment related expenses such as amusement, music and alcohol. | Transactional | | FINANCIAL_SERVICES_SPENDING | Expenses incurred due to availing financial services such as financial advisors, trade commissions and late payments. | Transactional | | FUEL_SPENDING | Expenses related to gas and fuel. | Transactional | | GROCERIES_SPENDING | Expenses towards groceries. | Transactional | | HEALTH_BEAUTY_MEDICAL_SPENDING | Expenses incurred due to personal health management activities such as gyms, dentists, hair, doctors and fitness. | Transactional | | HOME_IMPROVEMENT_SPENDING | Expenses incurred for home improvement such as furniture and supplies. | Transactional | | PHARMACY_SPENDING | Pharmacy related expenses such as the purchase of drugs and medical tests. | Transactional | | TOTAL_SPENDING | Total consumer spending for all transaction categories except for transfers, income, wealth management, and credit card payments | Transactional | | TRAVEL_SPENDING | Expenses incurred as a result of travelling such as air travel, rental cars, taxis, and other forms of transportation. | Transactional | | UTILITIES_SPENDING | Utility related expenses like bill payments. | Transactional | | DISCRETIONARY_SPENDING | This is an umbrella group that sums: ACCOMMODATION_SPENDING BOOKS_SPENDING CONSUMER_ELECTRONICS_SPENDING EATING_PLACES_SPENDING ENTERTAINMENT_SPENDING HEALTH_BEAUTY_MEDICAL_SPENDING HOME_IMPROVEMENT_SPENDING TRAVEL_SPENDING | Transactional | | NONDISCRETIONARY_SPENDING | This is an umbrella group that sums: CLOTHING_SPENDING COMMUNICATION_SERVICES_SPENDING FINANCIAL_SERVICES_SPENDING FUEL_SPENDING GROCERIES_SPENDING INSURANCE_SPENDING PHARMACY_SPENDING UTILITIES_SPENDING | Transactional | #### Time Interval Types {#time-interval-types} A report supports up to two time interval types. If a partner requests for more than two interval types, the end point gives the error: `More than 2 intervalTypes passed request.` If the time interval type is not specified, the default is MONTHLY_CALENDAR. The table shows all possible time interval types for which a partner can request a report. | Time Interval Type | Description | First (Earliest) period may be partial | First (Most recent) period may be partial | Shortest possible period length | Longest possible period length | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------| | DAILY | The report will be broken up into one period for every calendar date in the report time period. | NO | NO | 1 | 1 | | WEEKLY_CALENDAR | The report time period will be broken up into periods of seven calendar dates, with each period beginning on a Monday and ending on a Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 7 | | WEEKLY_ROLLING_7 | The report time period will be broken up into periods of seven calendar dates, counting backwards from the report end date. | YES | NO | 1 | 7 | | BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, with each period beginning on a Monday and ending on the second subsequent Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 14 | | BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date. | YES | NO | 1 | 14 | | SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly two periods per calendar month, where both the first and the last period may be partial, and periods will alternate between representing the 1st:15th of the month and the 16th: end of the month. | YES | YES | 1 | 16 | | MONTHLY_CALENDAR | The report time period will be broken up into one period per calendar month. | YES | YES | 1 | 31 | | MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by one period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 36 | | QUARTERLY_CALENDAR | The report time period will be broken up into one period per three calendar months, where both the first and last period may be partial. | YES | YES | 1 | 92 | | QUARTERLY_ROLLING_90 | The report time period will be broken up into three periods of 90 calendar dates followed by one period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 96 | | ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date. | YES | NO | 1 | 366 | | HISTORICALLY | The report time period will be represented by exactly one period. | NO | NO | 1 | Duration of report data | The JSON snippet shows an example of how a time interval type is represented. * Json ```json "constraints": { "analyticsReportData": { "timeIntervalTypes": [ "MONTHLY_CALENDAR", "ANNUALLY" ] } } ```
#### JSON report structure - Analytics section {#json-report-structure---analytics-section} Analytics will be provided at the account level, grouped by financial institution and at an aggregated customer level. The following examples show a customer with two accounts that contain transactions. * Json ```json "accounts": [ { "id": 1005572173 }, { "id": 1005572174 } ] ``` The analytics section is divided into three sections. * Transactional attributes * State attributes-not applicable to Consumer Foresight * Streams-not applicable to Consumer Foresight **Account-level analytics structure** This section is for each of the customer accounts. * Json ```json "analytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ```
**Customer-level analytics structure** * Json ```json "customerAnalytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ```
#### Transactional attributes {#transactional-attributes} Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. For example, an attribute called FUEL_SPENDING may be a classification of all transactions that we assume to be a customer paying towards fuel or gas. The following sample JSON snippets are for transactional attributes on accounts and customer levels. * The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months. * The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates. * Not all attributes are showcased. Refer to the attribute table to view all Foresight attributes. NONDISCRETIONARY_SPENDING will have aggregated data of COMMUNICATION_SERVICES_SPENDING and UTILITIES_SPENDING. * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2025-03-31", "max": -89.91, "mean": -94.115, "median": -94.115, "min": -98.32, "standardDeviation": 5.9467680297788625, "startDate": "2025-03-01", "sum": -188.23, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 278.08, "percentageDifferenceToCohort": 59.63 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-466.31" } ] } ] }, { "periods": [ { "count": 5, "endDate": "2025-03-04", "max": -87.51, "mean": -93.438, "median": -94.115, "min": -100.72, "standardDeviation": 5.9467680297788625, "startDate": "2024-03-05", "sum": -467.19, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 655.10, "percentageDifferenceToCohort": 58.37 } ] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-03-05", "endDate": "2025-03-04", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-1122.29" } ] } ] } ], "attributeName": "COMMUNICATION_SERVICES_SPENDING", "streamIds": [], "transactionIds": [ "100393337806", "100393337807", "100393337808", "100393337809", "100393337810" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -595.23 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -1190.45 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -1785.68 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -2380.9 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 3, "endDate": "2025-03-31", "max": -70.55, "mean": -107.12333333333333, "median": -102.0, "min": -148.82, "standardDeviation": 39.385716107915734, "startDate": "2025-03-01", "sum": -321.37, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 45.67, "percentageDifferenceToCohort": 12.44 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-367.04" } ] } ] }, { "periods": [ { "count": 6, "endDate": "2025-03-04", "max": -67.51, "mean": -108.713, "median": -105.115, "min": -148.82, "standardDeviation": 39.385716107915734, "startDate": "2024-03-05", "sum": -652.28, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 55.55, "percentageDifferenceToCohort": 7.85 } ] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-03-05", "endDate": "2025-03-04", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-707.83" } ] } ] } ], "attributeName": "UTILITIES_SPENDING", "streamIds": [], "transactionIds": [ "100393337811", "100393337812", "100393337813", "100393337814", "100393337815", "100393337816" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -895.54 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -1791.08 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -2686.62 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -3582.15 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 5, "endDate": "2025-03-31", "max": -70.55, "mean": -101.92, "median": -98.32, "min": -148.82, "standardDeviation": 28.900230967935187, "startDate": "2025-03-01", "sum": -509.59999999999997, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": -509.6 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "0.0" } ] } ] }, { "periods": [ { "count": 11, "endDate": "2025-03-04", "max": -67.51, "mean": -101.77, "median": -105.115, "min": -148.82, "standardDeviation": 39.385716107915734, "startDate": "2024-03-05", "sum": -1119.47, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 710.65, "percentageDifferenceToCohort": 38.83 } ] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-03-05", "endDate": "2025-03-04", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-1830.12" } ] } ] } ], "attributeName": "NONDISCRETIONARY_SPENDING", "streamIds": [], "transactionIds": [ "100393337806", "100393337807", "100393337808", "100393337809", "100393337810" "100393337811", "100393337812", "100393337813", "100393337814", "100393337815", "100393337816" ], "projectedValues": [], "streamConfidences": null } ] ``` Note: NONDISCRETIONARY_SPENDING will have aggregated data of COMMUNICATION_SERVICES_SPENDING. DISCRETIONARY_SPENDING will have aggregated data of ENTERTAINMENT_SPENDING. * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 4, "endDate": "2025-03-31", "max": -101.13, "mean": -45.93, "median": -36.98, "min": -8.63, "standardDeviation": 45.48252411641201, "startDate": "2025-03-01", "sum": -183.72, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 282.59, "percentageDifferenceToCohort": 60.6 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-466.31" } ] } ] } ], "attributeName": "COMMUNICATION_SERVICES_SPENDING", "streamIds": [], "transactionIds": [ "100393337866", "100393337868", "100393337869", "100393337871" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -538.45 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -1076.89 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -1615.34 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -2153.78 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2025-01-31", "max": -102.0, "mean": -102.0, "median": -102.0, "min": -102.0, "startDate": "2025-01-01", "sum": -102.0, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 265.04, "percentageDifferenceToCohort": 72.21 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-367.04" } ] } ] } ], "attributeName": "ENTERTAINMENT_SPENDING", "streamIds": [], "transactionIds": [ "100393337856" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -68.06 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -136.12 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -204.19 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -272.25 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2025-01-31", "max": -102.0, "mean": -102.0, "median": -102.0, "min": -102.0, "startDate": "2025-01-01", "sum": -102.0, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 265.04, "percentageDifferenceToCohort": 72.21 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "0.0" } ] } ] } ], "attributeName": "DISCRETIONARY_SPENDING", "streamIds": [], "transactionIds": [ "100393337856" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 4, "endDate": "2025-03-31", "max": -8.63, "mean": -45.93, "median": -36.98, "min": -101.13, "standardDeviation": 45.48252411641201, "startDate": "2025-03-01", "sum": -183.72, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 282.59, "percentageDifferenceToCohort": 60.6 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "0.0" } ] } ] } ], "attributeName": "NONDISCRETIONARY_SPENDING", "streamIds": [], "transactionIds": [ "100393337866", "100393337868", "100393337869", "100393337871" ], "projectedValues": [], "streamConfidences": null } ] ``` Note: NONDISCRETIONARY_SPENDING will have aggregated data of COMMUNICATION_SERVICES_SPENDING. DISCRETIONARY_SPENDING will have aggregated data of ENTERTAINMENT_SPENDING. * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 6, "endDate": "2025-03-31", "max": -101.13, "mean": 61.99166667, "median": -60.98, "min": -8.63, "standardDeviation": 35.48252411641201, "startDate": "2025-03-01", "sum": -371.95, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 94.36, "percentageDifferenceToCohort": 20.24 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-466.31" } ] } ] } ], "attributeName": "COMMUNICATION_SERVICES_SPENDING", "streamIds": [], "transactionIds": [ "100393337806", "100393337807", "100393337866", "100393337868", "100393337869", "100393337871" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -1133.67 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -2267.34 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -3401.02 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -4534.69 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 3, "endDate": "2025-03-31", "max": -148.82, "mean": -107.12333333333333, "median": -102.0, "min": -70.55, "standardDeviation": 39.385716107915734, "startDate": "2025-03-01", "sum": -321.37, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 45.67, "percentageDifferenceToCohort": 12.44 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-367.04" } ] } ] } ], "attributeName": "UTILITIES_SPENDING", "streamIds": [], "transactionIds": [ "100393337811", "100393337812", "100393337813" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -895.54 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -1791.08 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -2686.62 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -3582.15 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2025-01-31", "max": -102.0, "mean": -102.0, "median": -102.0, "min": -102.0, "startDate": "2025-01-01", "sum": -102.0, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 265.04, "percentageDifferenceToCohort": 72.21 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "-367.04" } ] } ] } ], "attributeName": "ENTERTAINMENT_SPENDING", "streamIds": [], "transactionIds": [ "100393337856" ], "projectedValues": [ { "timeUnit": "MONTHS", "timeValue": 3, "projectionValue": -68.06 }, { "timeUnit": "MONTHS", "timeValue": 6, "projectionValue": -136.12 }, { "timeUnit": "MONTHS", "timeValue": 9, "projectionValue": -204.19 }, { "timeUnit": "MONTHS", "timeValue": 12, "projectionValue": -272.25 } ], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2025-01-31", "max": -102.0, "mean": -102.0, "median": -102.0, "min": -102.0, "startDate": "2025-01-01", "sum": -102.0, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 265.04, "percentageDifferenceToCohort": 72.21 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "0.0" } ] } ] } ], "attributeName": "DISCRETIONARY_SPENDING", "streamIds": [], "transactionIds": [ "100393337856" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 9, "endDate": "2025-03-31", "max": -148.82, "mean": -77.93, "median": -84.98, "min": -8.63, "standardDeviation": 37.48252411641201, "startDate": "2025-03-01", "sum": -693.32, "comparedToCohorts": [ { "cohortType": "POSTAL_CODE", "totalDifferenceToCohort": 282.59, "percentageDifferenceToCohort": 60.6 } ] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2025-03-01", "endDate": "2025-03-31", "cohortValues": [ { "cohortType": "POSTAL_CODE", "value": "0.0" } ] } ] } ], "attributeName": "NONDISCRETIONARY_SPENDING", "streamIds": [], "transactionIds": [ "100393337806", "100393337807", "100393337866", "100393337868", "100393337869", "100393337871", "100393337811", "100393337812", "100393337813" ], "projectedValues": [], "streamConfidences": null } ] ``` **JSON fields description** | Key (Datatype) | Description | Applicable for Consumer Foresight | |---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------| | aggregatedByTimePeriods (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes | | periods (object) | Statistics of aggregated transactions over some time period. | Yes | | count (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes | | endDate (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes | | max (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes | | mean (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for a monthly time interval, mean will be shown for each month of a year. | Yes | | median (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for a monthly time interval, the median will be shown for each month of a year. | Yes | | min (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for a monthly time interval, the min will be shown for each month of a year. | Yes | | standardDeviation (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for a monthly time interval, the standardDeviation will be shown for each month of a year. | Yes | | startDate (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for a monthly time interval, the startDate will be shown for each month of a year. | Yes | | sum (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for a time interval, the sum will be shown for each month of a year. | Yes | | comparedToCohorts (object) | An array of elements comparing the customer's spending during a time period to the average customer's spending in various cohorts, such as postal code, during the same time period. | Yes | | cohortType (string) | Describes the type of cohort being compared to for this period, for example POSTAL_CODE. | Yes | | totalDifferenceToCohort (number) | Reflects the difference between the customer's spending for the period minus that of the average spending in this cohort. A positive difference value indicates that a customer has spent less than the cohort while a negative difference value indicates that a customer has spent more than the cohort. | Yes | | percentageDifferenceToCohort (number) | Reflects the percentage difference between the customer's sum value for the period and the average of the cohort. A positive percentage value indicates that a customer has spent less than the cohort while a negative percentage value indicates that a customer has spent more than the cohort. | Yes | | timeIntervalType (string) | See Time Interval Types for how each period is defined. | Yes | | cohortBenchmarkPeriods (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the spending of cohorts in the customer's zip code during that period for an attribute. | Yes | | startDate (string) | The first day of the cohort benchmark period. | Yes | | endDate (string) | The final day of the cohort benchmark period. | Yes | | cohortValues (object) | An object that contains the type and value of a cohort benchmark period. | Yes | | cohortType (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, for example POSTAL_CODE. | Yes | | value (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | Yes | | attributeName (string) | Name of a Consumer Foresight attribute for which we are reporting the numbers. Refer to Consumer Foresight Attributes. | Yes | | streamIds | List of stream IDs associated with the attribute. This field will be empty as it is not applicable for Consumer Foresight. | No | | transactionIds(object) | List of transaction IDs associated with the attribute. | Yes | | projectedValues (object) | List of projection objects, where each object indicates the projected sum value of the attribute over some coming period of time. | Yes | | timeUnit (string) | The unit of time being described, for example MONTHS. | Yes | | timeValue (number) | The number of timeUnit units for which we are projecting, for example 12. (for 12 months) | Yes | | projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | Yes | | streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. This field will be empty as it is not applicable for Consumer Foresight. | No | | streamId (string) | The stream ID we are reporting the confidence for. This field will be empty as it is not applicable for Consumer Foresight. | No | | confidence (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an attribute. This field will be empty as it is not applicable for Consumer Foresight. | No |
#### State Attributes {#state-attributes} Consumer Foresight does not currently have any state attributes. #### Streams {#streams} Consumer Foresight does not currently have any stream attributes. ## Testing {#testing} Refer to the [Transactions Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#transactions-profiles) section of Test the APIs to find suitable test profiles. To test with **profile_1726**: 1. Follow the steps in [How It Works](https://developer.mastercard.com/open-finance-us/documentation/products/manage/consumer-foresight/index.md#how-it-works) on this page to create a test customer and a Data Connect URL. 2. Open the Data Connect URL, search for **FinBank OAuth** and log in with username `profile_1726` and password `profile_1726`. 3. After connecting the account, call [Load Historic Transactions for Customer Account](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#LoadHistoricTransactionsForCustomerAccount) to load the transaction history. 4. Use **Generate Non CRA Foresight Analytics Report** and **Get Report by Report ID** to get the report. ## Legacy Endpoint {#legacy-endpoint} The legacy endpoint uses only third-party data permissioned via Data Connect and does not support first-party data submitted via Data Enrichment. It requires a `customerId` in the path rather than in the request body. API Reference: `POST /decisioning/customers/{customerId}/reports/foresight-analytics/userTypes/{userType}` You can use any [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoint to retrieve reports from the legacy endpoint. --- # Reports List source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md ## Reports {#reports} This section covers the available Lend reports. ### Available Reports {#available-reports} * [Transaction Consumer Reporting Agency (TACRA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/tacra/index.md) * [Statement Aggregation CRA (SACRA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/statements/index.md) * [Verification of Assets (VOA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md) * [Verification of Assets and Income (VOAI)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md) * [Asset Prequalification](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/prequal/index.md) * [Verification of Employment - Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-transactions/index.md) * [Verification of Employment - Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) * [Verification of Income and Employment - Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md) * [Verification of Income and Employment - Paystub (with TXVerify)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md) * [Verification of Income (VOI)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) * [Cash Flow Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md) * [Balance Analytics](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) * [Payment Risk Insights (Consumer)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/payment-risk-insights/index.md) * [Payment Risk Insights (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md) (part of the [Small Business](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/index.md) product section) --- # Payment Risk Insights (Small Business) source: https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md Note: This documentation is for Small Business use cases. For consumer use cases, see [Payment Risk Insights (Consumer)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/payment-risk-insights/index.md). ## Overview {#overview} The Payment Risk Insights report retrieves up to 24 months of transaction history from connected accounts, and calculates a risk score based on a business's financial history. The risk score can be used to determine the probability that a business will experience a payment risk event, such as Non-Sufficient Funds/Overdraft or missed recurring payments, in the near future when making a payment. #### Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months * **Payment Risk Insights Analytics:** * Monthly average income over the previous 24 months * Total deposit amount by month for all accounts and level of confidence that it represents income * Total withdrawal amount by month for all accounts * Number of NSF counts and aggregate amount per month * Recurring loan payment amounts per month * Insurance payment amount per month * Tax payment amounts per month * **Risk Score** representing the likelihood of a missed payment * **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar #### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshing a report is billable at a discounted rate. * **Supported Account Types**: Checking, Savings * **Supported Report Format:** JSON and PDF #### Use Cases {#use-cases} For partners working with small and medium businesses, there is a need to understand the likelihood of missing a payment by the business owner. The following list provides several use cases where the Payment Risk Insights Report can be employed to simplify small and medium business financial decisions. * **Onboarding and Payments** - Lenders can incorporate Payment Risk Insights Report into their onboarding flow to immediately assess the risk of a potential customer and price this risk accordingly. * **Business Financial Management** - Financial solutions providers can leverage the Payment Risk Insights Report to be able to provide insights to the small and medium sized businesses (SMBs) regarding their payment history. * **Loan Issuance** - Lenders can use the Risk Score and additional attributes in the Payment Risk Insights Report when deciding whether to approve a small business for a business loan or business credit card. * **Account Management** - Lenders can use Payment Risk Insights Report to make account management decisions such as credit limit adjustments and interest rate changes. #### Sequence Diagram {#sequence-diagram} Diagram payment-history-report ## How it Works {#how-it-works} ### Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API. * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers). * [Create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record for business use cases where the applicant is personally guaranteeing the loan. * [Create and link a business record to the customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses). * [Generate a connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows). ### Generate a Payment Risk Insights Report {#generate-a-payment-risk-insights-report} To generate or refresh a Payment Risk Insights Report use the following endpoint: API Reference: `POST /decisioning/customers/{customerId}/reports/payment-risk-insights/userTypes/{userType}` Set the `userType` path parameter to `business` for small business reports. The response includes the status of the report generation and a report ID. If you are using report webhooks (recommended), a notification is sent to the webhook listener when report generation is complete or an error occurs (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). If you are not using report webhooks, you can poll one of the [Get Report endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) every 20 seconds until the report is returned. #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * Use `timeIntervalType` to select the period at which attributes will be calculated. Defaults to Monthly Calendar. Customize the type of Payment Risk Insights report received based on inputs provided when generating the report: | **Report Type** | **User Type** (required) | **forCraPurpose** (required) | **forFtcPurpose** (optional) | **applicantIsPersonalGuarantor** (optional) | **Consumer Required?** | **Customer Required?** | **Business Required?** | |-----------------|--------------------------|------------------------------|------------------------------|---------------------------------------------|------------------------|------------------------|------------------------| | pribcra | business | true | false | true | Y | Y | Y | | pribnoncra | business | false | false | false | N | Y | Y | | pribftc | business | false | true | false | N | Y | Y | Note: The CRA version of the Payment Risk Insights Report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and you must provide a [permissible purpose](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) code when retrieving the report. Provision and use of this report is subject to all applicable obligations of the FCRA.
## Get Payment Risk Insights Reports {#get-payment-risk-insights-reports} Once the report is generated, retrieve the report using one of the [Get Report](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Reports {#example-reports} The Get Report response contains different data depending on the type of report requested. The following examples show what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. * `pribcra` (CRA) report: [example-pribcra.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/example-json/example-pribcra.json) (279KB) * `pribnoncra` (Non-CRA) report: [example-pribnoncra.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/example-json/example-pribnoncra.json) (279KB) * `pribftc` (FTC) report: [example-pribftc.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/example-json/example-pribftc.json) (279KB) ### PDF Version {#pdf-version} A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. To receive a PDF version of the report, set the `Accept` request header to `application/pdf` - otherwise, the report is returned as JSON. * Example Payment Risk Insights PDF report: [Payment_Risk_Insights_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/Payment_Risk_Insights_Example_Report.pdf) (675KB) * How to read a Payment Risk Insights PDF report: [PRI_HtR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/PRI_HtR.pdf) (9MB) ## Reading a Payment Risk Insights JSON Report {#reading-a-payment-risk-insights-json-report} This section provides a detailed description of the structure and format of the Payment Risk Insights Report JSON report. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. The JSON report is generated to provide data in a structured and machine-readable format. #### Payment Risk Insights Report Attributes {#payment-risk-insights-report-attributes} | **Attribute** | **Definition** | **Type** | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | ASSET_BALANCE | History of asset balances for the customer and their accounts. | State | | NSF_FEE_CHARGES | Fees charged to the customer by their financial institution resulting from a lack of sufficient funds or low balance to cover a purchase. | Transactional | | CASH_INFLOW | Credit transactions in a customer's account. | Transactional | | CASH_OUTFLOW | Debit / Spend transactions in a customer's account. | Transactional | | DISCRETIONARY_SPENDING | Spend towards expenses that are not required either for core business operations (in the case of a business customer) or living expenses (in the case of a consumer customer). | Transactional | | NONDISCRETIONARY_SPENDING | Spend towards expenses that are required for core business operations or living expenses. | Transactional | | INSURANCE_SPENDING | Payments made towards an insurance company. | Transactional | | TAX_PAYMENTS | Payments made towards a tax collection agency such as the IRS. | Transactional | | RECURRING_EXPENSES | Payments made towards expenses that typically recur over time. | Transactional | | DIVIDEND_INCOME | Dividend income is received as a stock shareholder's right for owning equity in a publicly traded company. | Transactional | | MISSED_RECURRING_EXPENSES | Payments toward recurring expenses that were missed by the customer during the reporting period. | State | | RECURRING_LOAN_PAYMENTS | Payments made towards loans that recur over time. | Transactional | | MISSED_RECURRING_LOAN_PAYMENTS | Payments toward loans that were missed by the customer during the reporting period. | State | | PAYMENT_RISK_SCORE | A score value between 0 and 100 that indicates the riskiness of the customer to miss an upcoming payment. Higher values indicate higher risk. The score has four levels: Low (0-25), Medium (26-50), Medium-High (51-75), and High (76-100). | State | ### Sample JSON Report {#sample-json-report} The JSON sample is an output of the PRI profile profile-2750-2756 used in the sandbox (for your own testing you can use one of the [Payment Risk Insights test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profiles) with FinBank Profiles - A): [phrbcra-profile-2750-2756.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/phrbcra-profile-2750-2756.json) (266KB) ### Time Interval Types {#time-interval-types} A report supports up to two time interval types. If a partner requests for more than two interval types, then the end point gives the error `More than 2 intervalTypes passed request.` If the time interval type is not specified, the default is MONTHLY_CALENDAR. The table shows all possible time interval types for which a partner can request a report. | Time Interval Type | Description | First (Earliest) period may be partial | First (Most recent) period may be partial | Shortest possible period length | Longest possible period length | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------| | DAILY | The report will be broken up into one period for every calendar date in the report time period. | NO | NO | 1 | 1 | | WEEKLY_CALENDAR | The report time period will be broken up into periods of seven calendar dates, with each period beginning on a Monday and ending on a Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 7 | | WEEKLY_ROLLING_7 | The report time period will be broken up into periods of seven calendar dates, counting backwards from the report end date. | YES | NO | 1 | 7 | | BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, with each period beginning on a Monday and ending on the second subsequent Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 14 | | BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date. | YES | NO | 1 | 14 | | SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly two periods per calendar month, where both the first and the last period may be partial, and periods will alternate between representing the 1st-15th of the month and the 16th-end of the month. | YES | YES | 1 | 16 | | MONTHLY_CALENDAR | The report time period will be broken up into one period per calendar month. | YES | YES | 1 | 31 | | MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by one period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 36 | | QUARTERLY_CALENDAR | The report time period will be broken up into one period per three calendar months, where both the first and last period may be partial. | YES | YES | 1 | 92 | | QUARTERLY_ROLLING_90 | The report time period will be broken up into three periods of 90 calendar dates followed by one period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 96 | | ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date. | YES | NO | 1 | 366 | | HISTORICALLY | The report time period will be represented by exactly one period. | NO | NO | 1 | Duration of report data | The JSON snippet shows an example of how a time interval type is represented. * JsonS ```jsonS "constraints": { "analyticsReportData": { "timeIntervalTypes": [ "MONTHLY_CALENDAR", "ANNUALLY" ] } } ```
### JSON report structure - Analytics section {#json-report-structure---analytics-section} Analytics will be provided at the account level, grouped by financial institution and at an aggregated customer level. The following examples show a customer with two accounts that contain transactions. * Json ```json "accounts": [ {"id": 3034460414}, {"id": 3034460415} ] ``` The analytics section is divided into three sections. * Transactional attributes * State attributes * Streams **Account-level analytics structure** This section is for each of the customer accounts. * Json ```json "analytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ```
**Customer-level analytics structure** * Json ```json "customerAnalytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ```
#### Transactional attributes {#transactional-attributes} Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. For example, an attribute called DWELLING_EXPENSES may be a classification of all transactions that we assume to be a customer paying towards a mortgage, rent, home insurance and so on. The following sample JSON snippets are for transactional attributes at an accounts and customer level. * The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months. * The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates. * Not all attributes are showcased. Refer to the attribute table to view all PRI attributes. * The data in the snippets are for profile-2750-2756 with some modifications. * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2023-07-31", "max": -7.16, "mean": -7.16, "median": -7.16, "min": -7.16, "standardDeviation": 0.14142135623730964, "startDate": "2023-07-01", "sum": -7.16, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] } ] }, { "periods": [ { "count": 7, "endDate": "2024-03-04", "max": -12.17, "mean": -7.55, "median": -7.16, "min": -3.07, "standardDeviation": 0.14142135623730964, "startDate": "2023-03-05", "sum": -42.96, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "107337ef-fa51-48cf-a70b-81144fb1e6e8" ], "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980" ], "projectedValues": [], "streamConfidences": null } ] ``` * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-07-31", "max": -9.75, "mean": -6.888888, "median": -6.888888, "min": -4.01, "standardDeviation": -4.0587929, "startDate": "2023-07-01", "sum": -13.76, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] } ] }, { "periods": [ { "count": 5, "endDate": "2024-03-04", "max": -14.01, "mean": -8.10, "median": -7.85, "min": -3.94, "standardDeviation": 0.45253246733731172, "startDate": "2023-03-05", "sum": -47.46, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "5c6c913a-62dc-4d07-b4ed-28fbb68f9995" ], "transactionIds": [ "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ], "projectedValues": [], "streamConfidences": null } ] ``` * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 3, "endDate": "2023-07-31", "max": -9.75, "mean": -7.16, "median": -7.16, "min": -3.07, "standardDeviation": 0.0, "startDate": "2023-07-01", "sum": -14.32, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-01-01", "cohortValues": [] } ] }, { "periods": [ { "count": 12, "endDate": "2024-03-04", "max": -14.01, "mean": -7.69, "median": -7.51, "min": -3.07, "standardDeviation": 0.25061422791045044, "startDate": "2023-03-05", "sum": -90.42, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "107337ef-fa51-48cf-a70b-81144fb1e6e8", "5c6c913a-62dc-4d07-b4ed-28fbb68f9995" ], "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980", "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ], "projectedValues": [], "streamConfidences": null } ] ``` **JSON fields description** | Key (Datatype) | Description | Applicable for PRI | |---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| | aggregatedByTimePeriods (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes | | periods (object) | Statistics of aggregated transactions over some time period. | Yes | | count (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes | | endDate (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes | | max (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes | | mean (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for a monthly time interval, mean will be shown for each month of a year. | Yes | | median (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for a monthly time interval, the median will be shown for each month of a year. | Yes | | min (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for a monthly time interval, the min will be shown for each month of a year. | Yes | | standardDeviation (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for a monthly time interval, the standardDeviation will be shown for each month of a year. | Yes | | startDate (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for a monthly time interval, the startDate will be shown for each month of a year. | Yes | | sum (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for a time interval, the sum will be shown for each month of a year. | Yes | | comparedToCohorts (object) | An array of elements comparing the customer's income / spending during a time period to the average customer's income / spending in various cohorts, such as postal code, during the same time period. | No | | cohortType (string) | Describes the type of cohort being compared to for this period, for example POSTAL_CODE. This field will be empty as it is not applicable for PRI. | No | | totalDifferenceToCohort (number) | Reflects the difference between the customer's income / spending value for the period minus that of the average income / spending in this cohort. This field will be empty as it is not applicable for PRI. | No | | percentageDifferenceToCohort (number) | Reflects the percentage difference between the customer's income / spending value for the period and the average income / spending of the cohort. This field will be empty as it is not applicable for PRI. | No | | timeIntervalType (string) | Refer to Time Interval Types for how each period is defined. | Yes | | cohortBenchmarkPeriods (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the income / spending of cohorts in the customer's zip code during that period for an attribute. | No | | startDate (string) | The first day of the cohort benchmark period. | No | | endDate (string) | The final day of the cohort benchmark period. | No | | cohortValues (object) | An object that contains the type and value of a cohort benchmark period. This field will be empty as it is not applicable for PRI. | No | | cohortType (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, for example POSTAL_CODE. This field will be empty as it is not applicable for PRI. | No | | value (number) | For each cohort benchmark period, the average income / spending for the cohort during this time period. This field will be empty as it is not applicable for PRI. | No | | attributeName (string) | Name of the transactional / state / stream attribute that we are reporting the numbers for. Refer to the Payment Risk Insights Report Attributes. | Yes | | streamIds | List of stream IDs associated with the attribute. | Yes | | transactionIds(object) | List of transaction IDs associated with the attribute (a classification). | Yes | | projectedValues (object) | List of projection objects, where each object indicates the projected income / spending value of the attribute over some coming period of time. This field will be empty as it is not applicable for PRI. | No | | timeUnit (string) | The unit of time being described, for example MONTHS. This field will be empty as it is not applicable for PRI. | No | | timeValue (number) | The number of timeUnit units for which we are projecting, for example 12 (for 12 months). This field will be empty as it is not applicable for PRI. | No | | projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. This field will be empty as it is not applicable for PRI. | No | | streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | Yes | | streamId (string) | The stream ID for which we are reporting the confidence. | Yes | | confidence (number) | A float value between 0 and 100. | Yes |
#### State Attributes {#state-attributes} The unit of data for state attributes is some generic "state" at a point in time. Whereas transactional attributes are based on specific events (the posting of a transaction), state attributes make some inference about a point in time based on an assembly of underlying data. Examples of state attributes include the balance of an account over time, a calculation based on underlying transactions in a time period (such as net cash flow), or other calculations such as a debt-to-income ratio. The following sample JSON snippets are for state attributes at an accounts and customer level. * The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months. * The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates. * Not all attributes are showcased. Refer to the attribute table to view all PRI attributes. * The data in the snippets are for profile-2750-2756 with some modifications. * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 325.06, "count": 31, "endDate": "2023-07-31", "endingValue": 332.22, "max": 332.22, "mean": 328.6909677419355, "median": 332.12, "min": 324.96, "standardDeviation": 3.639724673505515, "startDate": "2023-07-01", "sum": 10189.42, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] }, ] }, { "periods": [ { "beginningValue": 635.44, "count": 365, "endDate": "2024-03-04", "endingValue": 401.56, "max": 696.23, "mean": 404.1959871413877, "median": 410.06, "min": 299.36, "standardDeviation": 3.997490676405987, "startDate": "2023-03-05", "sum": 147785.90, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] }, ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 506.78, "count": 31, "endDate": "2023-07-31", "endingValue": 479.07, "max": 510.89, "mean": 494.6909677419355, "median": 492.12, "min": 461.96, "standardDeviation": 4.75837468734, "startDate": "2023-07-01", "sum": 15497.36, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 595.94, "count": 365, "endDate": "2024-03-04", "endingValue": 631.59, "max": 652.23, "mean": 610.387463784, "median": 601.06, "min": 451.36, "standardDeviation": 4.862563462, "startDate": "2023-03-05", "sum": 224670.10, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] }, ] } ], "projectedValues": [] }, ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 831.84, "count": 31, "endDate": "2023-07-31", "endingValue": 811.29, "max": 510.89, "mean": 406.381935483871, "median": 413.24, "min": 324.96, "standardDeviation": 4.27944934701103, "startDate": "2023-07-01", "sum": 25686.78, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-04-01", "endDate": "2023-04-30", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 1231.38, "count": 365, "endDate": "2024-03-04", "endingValue": 1033.15, "max": 696.23, "mean": 505.387463784, "median": 499.06, "min": 299.36, "standardDeviation": 4.382563462, "startDate": "2023-03-05", "sum": 372455.0, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] }, ] } ], "projectedValues": [], } ] ``` **Description of JSON fields** | Key (Datatype) | Description | |--------------------------------|------------------------------------------------------------------| | reportedByTimePeriods (object) | Value of the state over some time periods. | | beginningValue (number) | Value of the state as reported on the startDate of the period. | | endingValue (number) | Value of the state as reported on the endDate of the period. | | count (number) | Occurrences of the state between specified startDate and enDate. |
#### Streams {#streams} Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between two parties or accounts, if the same entity owns both the source and destination of funds. Examples of streams include bi-weekly paychecks from an employer to an employee, a customer's monthly phone bill paid to a telecom provider, a customer's monthly transfer from a checking account to an investment account, and so on. Since a stream is a group of transactions, a transactional attribute can assign a list of streams to itself if the transactions in that stream all fit the same classification being described by the attribute. **JSON snippets of stream attributes:** * Json ```json "streams": [ { "cadence": 20, "id": "107337ef-fa51-48cf-a70b-81144fb1e6e8", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-04T00:00:00, "count": 7, "sum": -42.96, "status": "active", "min": -3.07, "max": -12.17, "mean": -7.55, "median": -7.16, "standardDeviation": 0.14142135623730964, "minimumCadence": 5, "maximumCadence": 9, "medianCadence": 6, "modeCadence": 6, "standardDeviationCadence": 7.068617626733007, "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "5c6c913a-62dc-4d07-b4ed-28fbb68f9995", "payee": "JOHN DOE", "payor": "walmart", "recency": 20, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-14T00:00:00, "count": 5, "sum": -47.46, "status": "active", "min": -3.94, "max": -14.01, "mean": -8.10, "median": -7.85, "standardDeviation": 0.45253246733731172, "minimumCadence": 3, "maximumCadence": 7, "medianCadence": 4, "modeCadence": 4, "standardDeviationCadence": 5.172827626734145, "transactionIds": [ "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "107337ef-fa51-48cf-a70b-81144fb1e6e8", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-04T00:00:00, "count": 7, "sum": -42.96, "status": "active", "min": -3.07, "max": -12.17, "mean": -7.55, "median": -7.16, "standardDeviation": 0.14142135623730964, "minimumCadence": 5, "maximumCadence": 9, "medianCadence": 6, "modeCadence": 6, "standardDeviationCadence": 7.068617626733007, "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980" ] }, { "cadence": 20, "id": "5c6c913a-62dc-4d07-b4ed-28fbb68f9995", "payee": "JOHN DOE", "payor": "walmart", "recency": 20, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-14T00:00:00, "count": 5, "sum": -47.46, "status": "active", "min": -3.94, "max": -14.01, "mean": -8.10, "median": -7.85, "standardDeviation": 0.45253246733731172, "minimumCadence": 3, "maximumCadence": 7, "medianCadence": 4, "modeCadence": 4, "standardDeviationCadence": 5.172827626734145, "transactionIds": [ "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ] } ] ``` **Description of JSON fields** | Key (Datatype) | Description | |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | cadence (number) | The average number of days elapsed between consecutive transactions in the stream. | | id (string) | A randomly generated UUID to uniquely identify the stream. | | payee (string) | The party that is receiving the funds. | | payor (string) | The party that is sending the funds. | | recency (number) | The number of days elapsed since the most recent transaction in the stream. | | earliestObservedDate (string) | The date-time of the first observed transaction in the stream. | | latestObservedDate (string) | The date-time of the last observed transaction in the stream. | | status (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence. | | minimumCadence (number) | The smallest observed duration of time elapsed between any two consecutive transactions in the stream. | | maximumCadence (number) | The largest observed duration of time elapsed between any two consecutive transactions in the stream. | | medianCadence (number) | The median number of days elapsed between consecutive transactions in the stream. | | modeCadence (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream. | | standardDeviationCadence (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream. | | transactionIds (object) | A list of all the transaction IDs that were assigned to the stream. |
## Testing {#testing} For testing PRI you can use the [Payment Risk Insights test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profiles), which generate reports with different risk levels. ## Legacy Endpoint {#legacy-endpoint} #### Generate Payment History Report (To Be Deprecated) {#generate-payment-history-report-to-be-deprecated} This is a previous Payment Risk Insights endpoint which only supported business use cases. New integrations should use the endpoint described in [Generate a Payment Risk Insights Report](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md#generate-a-payment-risk-insights-report) above. API Reference: `POST /decisioning/customers/{customerId}/reports/payment-history/userTypes/business` --- # Guide for Partners (Clients) - Recipient source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/index.md As an Open Finance partner you are able to obtain consent from your customer to allow a third party to access their banking data for a specific purpose - for example, to access their ACH routing details in order to make a payment. To do this you must obtain the customer's consent using the Data Connect user experience, then create a third party access token (consent receipt) which specifies the access to be granted. You then share this consent receipt with your chosen third party processor so that they can make the necessary Open Finance API calls. In order to do so, the third party processor must have a secure method of receiving the consent receipt from you, and must be onboarded in order to use Mastercard Open Finance APIs. The following third party processors have support for Partner Linked access currently: * Dwolla - see the Dwolla [Secure Exchange](https://developers.dwolla.com/docs/secure-exchange) documentation for details (see the "Finicity" example). * Usio - see the Usio [ACH Payments](https://payments.usiopay.com/2.0/documentation/#ach) documentation for details. * Highnote If you have a relationship with other payment processors that you would like to use, they will first need to integrate with Mastercard Open Finance and provide a mechanism for sharing the consent receipt. Read the following for more details: * [Client (requestor) steps](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/client-steps/index.md) * [Manage access keys](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/manage-access-keys/index.md) * [Example - Using Dwolla for payment processing](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/example-dwolla/index.md) --- # Data Access Tiers source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md Note: Partners using [TxPUSH](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md) are not eligible for Data Access Tiers. Please contact your Sales Representative for more information on what tier is most appropriate for your application's use case. Data Access Tiers is a billing option for [Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) and [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md). This product offers three levels of access to account data for each customer. * [Tier 1](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md#tier-1): Account Simple Details (ASD) - **no additional cost** * provides basic account information such as account name, type, status and currency. This enables you to check if accounts that have been permissioned are operational before using the paid tiers. * [Tier 2](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md#tier-2): Account Full Details (AFD) - **paid** * provides access to account information such as current balance, available balance, credit available and last payment date. It does not include transaction data. * [Tier 3](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md#tier-3): Account \& Transaction Details (ATD) - **paid** * provides access to Account Full Details (AFD) endpoints along with access to account transactions for up to six months (possibly longer for certain liability account types where the history of data is supported by the financial institution), such as transaction type, date, amount and categorization information. Tip: If you access Tier 2 data and Tier 3 data for a customer in the same month, you will only incur the Tier 3 charge for that customer. If you access a billable account or transaction data endpoint for a customer (apart from Account Balance Check), the cost of any Tier 2 or Tier 3 access for that customer is waived for that month. ### General Use Case {#general-use-case} Allows you to receive account and transaction data on your customers in real time, and make informed business decisions. Diagram dynamic-billing ### How It Works {#how-it-works} To use Data Access Tiers, you must have a customer created through your `partnerId` and the customer must have at least one linked account. These endpoints require [Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). Warning: If you are using Data Access Tiers, do not use the data refresh endpoints for standalone services. You must use the V2 refresh endpoints, or alternatively the [Asynchronous Data Refresh Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#asynchronous-data-refresh-endpoints). See the [Data Refresh](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md) documentation for details. ## Tier 1 - Account Simple Details {#tier-1---account-simple-details} Account Simple Details (ASD) provides access to the simple versions of the Get Customer Account(s) APIs. These versions return only basic account information. * Get Customer Account by ID (Simple) * Get Customer Accounts (Simple) * Get Customer Accounts by Institution ID (Simple) * Get Customer Accounts by Institution Login ID (Simple)
See [Account Simple Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-simple-details-asd) for full endpoint documentation. Use the [Refresh Endpoints for Data Access Tiers (V2)](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-endpoints-for-data-access-tiers-v2) or the [Asynchronous Data Refresh Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#asynchronous-data-refresh-endpoints) to refresh data. ## Tier 2 - Account Full Details {#tier-2---account-full-details} Account Full Details (AFD) provides access to the full versions of the Get Customer Account(s) APIs. These versions return more detailed account information such as current balance, available balance, credit available and last payment date. * Get Customer Account by ID * Get Customer Accounts * Get Customer Accounts by Institution ID * Get Customer Accounts by Institution Login ID
See [Account Full Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-full-details-afd-or-account-limited-aggregation-ala) for full endpoint documentation. Use the [Refresh Endpoints for Data Access Tiers (V2)](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-endpoints-for-data-access-tiers-v2) or the [Asynchronous Data Refresh Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#asynchronous-data-refresh-endpoints) to refresh data. ## Tier 3 - Account Transaction Details {#tier-3---account-transaction-details} Account Transaction Details (ATD) includes all Account Full Details (AFD) endpoints and provides access to transaction history. * Get Customer Account Transactions * Get Customer Transaction by ID * Get All Customer Transactions
See [Account Transaction Details](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#account-transaction-details-atd-or-transaction-aggregation-tau) for full endpoint documentation. Use the [Refresh Endpoints for Data Access Tiers (V2)](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-endpoints-for-data-access-tiers-v2) or the [Asynchronous Data Refresh Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#asynchronous-data-refresh-endpoints) to refresh data. --- # Migrate Customers source: https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/migration-customers/index.md You can choose how you want to manage new customers and migrating existing customers accounts moving from a legacy connection to a new OAuth connection: * Use the Migration Service to move customer accounts. * Wait for the legacy connection to expire as indicated in the communicated migration plan from the CSM team. Any accounts remaining on the legacy connection are automatically migrated the OAuth connection.
Details of the Migration Service follow. ## Migration Service {#migration-service} Use [Migrate Institution Login Accounts](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/migration-customers/index.md#migrate-institution-login-accounts) to automatically change information needed to move customer accounts from a financial institution's (FI) legacy connection to an OAuth connection. The migration service does the following: 1. Changes the FI ID from the legacy connection and updates the FI ID for the OAuth connection. 2. The aggregation status code of the account is set to code 948. Use this status coded to prompt the customer to authenticate their accounts using the new OAuth method. 3. The financial institution transaction identifier is formatted to ensure deduplicating transactions. Tip: Use the `institutionSettings: autoreplace` feature so that only OAuth institutions are listed in the search list of a Data Connect session as you migrate to a new OAuth connection. See [Financial Institution Search List](https://developer.mastercard.com/open-finance-us/documentation/connect/connect-institutions-settings/index.md). ## Final Migration Steps {#final-migration-steps} Program your applications to do the following: 1. Indicate to the customer that their FI has updated their connection, and they must sign into their account to reauthenticate on the new connection. 2. Use the [Generate Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-fix) API to set the `institutionLoginId` account. 3. Present Data Connect Fix application pages to the customer. ### Migrate Institution Login Accounts {#migrate-institution-login-accounts} API Reference: `PUT /aggregation/v2/customers/{customerId}/institutionLogins/{institutionLoginId}/migration` **See also**: * [Register Applications](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/register-your-applications/index.md) * [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md) --- # Small Business Credit Analytics source: https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md Small Business Credit Analytics (SBCA) provides underwriters with access to near real-time transaction-based insights to build a more complete view of business performance and creditworthiness, helping them underwrite more businesses and reduce risk. Mastercard has rich transaction data from Mastercard-accepting merchant locations. These transactions are enriched and anonymized to generate transaction-based metrics at the location level. For merchants who have provided their consent, underwriters can request these metrics through the API. Note: The SBCA service is available as a [standalone API](https://developer.mastercard.com/small-business-credit-analytics/documentation). It is now also available as part of Open Finance. The Open Finance version enables you to use SBCA with your existing Open Finance credentials and projects, and requires a business customer record. It returns the same reports as the standalone version. ## Report Types {#report-types} There are two SBCA report types available: * **Retail Sales Analytics** (weekly or monthly) - provides a breakdown of a merchant location's performance across 44 metrics for the last 12 months. * **Retail Sales Benchmarks** (monthly only) - provides a breakdown of a merchant location's performance against a benchmark peer set across 11 benchmark metrics for the latest month.
The following table shows some sample metrics from each report type. | Metrics Category | Description | Sample Metrics || | | | Retail Sales Analytics | Retail Sales Benchmarks | |-----------------------|-----------------------------------------------------------------------|--------------------------------------------------------|--------------------------------------------------------| | **Business Metadata** | Metrics on small business identity and operations | Last seen transaction date First seen transaction date | Last seen transaction date First seen transaction date | | **Merchant Sales** | Metrics on business's retail sales and sales growth | Trend on average card spend | Average spend per card index | | **Channel Sales** | Metrics on customers' preferred channel at the business location | % Spend from online channels | % of e-Commerce transactions index | | **Customer Loyalty** | Metrics on recurring customer activity at the small business location | % of repeat customers | Cards repeated in 6 months index | | **Returns** | Metrics on the rate of returned purchases | % of returned transactions | Returned transactions index | | **Business Risk** | Metrics on business's authorization and fraud rates | Historical weekly or monthly card spend | Fraud chargeback index | ## How It Works {#how-it-works} To retrieve an SBCA report, there are two steps: 1. [Merchant Matching](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md#merchant-matching) - use metadata to determine a location ID for the merchant. 2. [Generate SBCA Report](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md#generate-sbca-report) - use the location ID to request the desired report type for that merchant location. Note: Reports provide metrics for a single merchant location. If a merchant has multiple locations, you must request a report for each location separately. Warning: Before you generate a report, you must contact the merchant directly and get their consent. Currently there is no way for a merchant to provide permission through Mastercard Open Finance. ## Merchant Matching {#merchant-matching} The recommended way to find a merchant's location ID is to use the following metadata: * Merchant name * Street address * City * State/province/region * Zip/postal code
You can also use the merchant's Mastercard merchant ID if you know it. Use the following endpoint to find the location ID: API Reference: `GET /decisioning/sbca/location-matches` The response can include multiple matches for the metadata you provided, with the most likely match listed first. ## Generate SBCA Report {#generate-sbca-report} To generate a report, you must have a [customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) for the merchant with an associated [business record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses). You must have obtained explicit consent from the merchant. Use the merchant's location ID and customer ID with the following endpoint to generate a report: API Reference: `POST /decisioning/customers/{customerId}/sbca` In the request body, use `metricType` to specify the report type you want: `retail_sales_analytics` or `retail_sales_benchmarks`. If you are requesting Retail Sales Analytics, use `metricFrequency` to request a `Weekly` or `Monthly` report. For Retail Sales Benchmarks, only `Monthly` is supported. ## Reading an Analytics Report {#reading-an-analytics-report} This section explains the metrics returned in a Retail Sales Analytics report. The metrics are presented in groups based on the key business question they could help answer. Note that the grouping is created for guidance only, and the API does not deliver data in these groups. ### Analytics Metrics {#analytics-metrics} **Does the small business exist and is it still operating?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| | `merchantCategoryCode` | `integer` | the Mastercard-defined merchant category code for the returned merchant. For full list, see [MCC Codes Booklet](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/quick-reference-booklet-merchant.pdf) | 478 | | `naicsCode` | `string` | North American Industry Classification System (NAICS) code. For full list, visit: [www.census.gov/naics](http://www.census.gov/naics) | 454113 | | `industryName` | `string` | the Mastercard-defined name of the industry of the merchant. For full list, see the [Industry Names](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md#industry-names) section on this page | Arts and Craft Stores | | `firstSeenTxnDate` | `string` | the date of the first Mastercard transaction processed for this merchant. Format: YYYY-MM-DD | 2021-01-01 | | `lastSeenTxnDate` | `string` | the date of the last Mastercard transaction processed for this merchant. Format: YYYY-MM-DD | 2021-12-31 | | `periodStartDate` | `string` | the calendar date marking the beginning (inclusive) of the period for which this metric was calculated. Format: YYYY-MMDD | 2021-01-03 | | `periodEndDate` | `string` | the calendar date marking the end (inclusive) of the period for which this metric was calculated. Format: YYYY-MM-DD | 2021-01-09 | | `year` | `integer` | the calendar year for which this metric was calculated | 2021 | **Can the business afford to pay back a loan?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |----------------------|-----------|-----------------------------------------|--------------| | `txn_amt` | `double` | total amount of spend | 31289.666484 | | `txn_cnt` | `double` | total count of transactions | 408.0 | | `tkt_size_avg` | `double` | average spend per transaction | 77.543760 | | `spend_per_card_avg` | `double` | average spend per card | 81.131128 | | `txn_per_card_avg` | `double` | average number of transactions per card | 1.054190 | **How volatile is the business?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |-------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------------------|-------------| | `spend_per_card_avg_yoy` | `double` | year-over-year weekly average spend per card | 0.094517 | | `txn_amt_yoy` | `double` | year-over-year total spend amount | 0.463873 | | `txn_cnt_yoy` | `double` | year-over-year total count of transactions | 1.083943 | | `tkt_size_avg_yoy` | `double` | year-over-year weekly average ticket | 0.336586 | | `recurring_cnt_yoy` | `double` | year-over-year total count of recurring transactions | 0.777531 | | `recurring_amt_perc` | `double` | percentage of spend from recurring transactions | 0.776268 | | `recurring_cnt_perc` | `double` | percentage of transactions from recurring transactions | 0.658485 | | `declined_cnt_rate` | `double` | percentage of transactions that are declined | 0.031240 | | `fraud_chargeback_cnt_perc` | `double` | percentage of transactions that are fraudulent | 0.000677 | | `cardholder_disputed_chargeback_cnt_perc` | `double` | percentage of transactions that are cardholder disputed | 0.004183 | | `reversed_amt` | `double` | total spend amount of returned purchases; the value is negative to reflect offsetting effect of returned purchases | -207.872189 | | `reversed_cnt` | `double` | total transaction count of returned purchases | 2 | | `reversed_amt_yoy` | `double` | year-over-year total spend amount of returned purchases | 7.115391 | | `reversed_cnt_yoy` | `double` | year-over-year total count of transaction of returned purchases | 0.907406 | **How does the business perform across different channels?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |-------------------|-----------|----------------------------------------------------------------|----------| | `chp_amt_perc` | `double` | percentage of cardholder present spend | 0.8209 | | `chp_cnt_perc` | `double` | percentage of cardholder present transactions | 0.68 | | `chnp_amt_perc` | `double` | percentage of cardholder not present spend | 0.162 | | `chnp_cnt_perc` | `double` | percentage of cardholder not present transactions | 0.0367 | | `online_amt_perc` | `double` | percentage of spend from online channels | 0.7812 | | `online_cnt_perc` | `double` | percentage of transactions from online channels | 0.265431 | | `online_cnt_yoy` | `double` | year-over-year total count of transaction from online channels | 637.83 | **What is the spend profile of the business' customers?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |----------------------------------------------------------|-----------|--------------------------------------------------------------------------------|----------| | `credit_amt_perc` | `double` | percentage of spend from credit cards | 0.220945 | | `debit_amt_perc` | `double` | percentage of spend from debit cards | 0.172125 | | `small_business_amt_perc` | `double` | percentage of spend from small business cards | 0.399925 | | `credit_cnt_perc` | `double` | percentage of transactions from credit cards | 0.154 | | `debit_cnt_perc` | `double` | percentage of transactions from debit cards | 0.9 | | `small_business_cnt_perc` | `double` | percentage of transactions from small business cards | 0.561112 | | `debit_tkt_size_avg` | `double` | average spend per transactions on debit cards | 37.21 | | `small_business_tkt_size_avg` | `double` | average spend per transactions on small business card cards | 85.361 | | `debit_spend_per_card_avg` | `double` | average spend per debit card | 47.7 | | `small_business_spend_per_card_avg` | `double` | average spend per small business card | 53.23 | | `debit_num_cards_perc` | `double` | percentage of cards that are debit cards | 0.444567 | | `small_business_num_cards_perc` | `double` | percentage of cards that are small business cards | 0.461234 | | `debit_declined_cnt_rate` | `double` | percentage of debit transactions that are declined | 0.974 | | `small_business_declined_cnt_rate` | `double` | percentage of small business card transactions that are declined | 0.2344 | | `debit_fraud_chargeback_cnt_perc` | `double` | percentage of debit transactions that are fraudulent | 0.63 | | `small_business_fraud_chargeback_cnt_perc` | `double` | percentage of small business card transactions that are fraudulent | 0.563 | | `debit_cardholder_disputed_chargeback_cnt_perc` | `double` | percentage of debit transactions that are disputed by cardholder | 0.651209 | | `small_business_cardholder_disputed_chargeback_cnt_perc` | `double` | percentage of small business card transactions that are disputed by cardholder | 0.241778 | #### Analytics Metrics Formatting {#analytics-metrics-formatting} * All example metric amounts are in USD currency. * All metrics are formatted with maximum 6 digits after their decimal points. * The percentage metric values are decimal point representations where 1.0 represents 100%. The values should be multiplied by 100 to get the actual percentage. For example, 0.82 means 82.0%. * The API can return values like `0`, `null`, `-1` in some edge case scenarios where there is low transaction volume or no recent transactions at a merchant location. * `0` -- In the event that no transactions were observed to calculate the respective metrics in that period, for example zero spend at the merchant location. * `null` -- In the event that the minimum number of transactions needed to calculate the respective metrics was not met in that period, or for YoY metrics when there were no data points in the previous year. * `-1` -- For YoY metrics only, in the event that there were no data points in the current year. For example, if there were 50 transactions in the previous year but no transactions in the current year, YoY growth would be calculated as (0-50)/50, which would lead to `-1` as a returned value. #### Analytics Calculations and Delivery {#analytics-calculations-and-delivery} * All metrics are calculated and delivered at weekly aggregations, one row per calendar week. * Metrics are refreshed every week with a lag for the latest available week of metrics that can be retrieved. * In some cases, `lastSeenTxnDate` could be later than the most recent available period of metrics due to the lag involved in generating weekly metrics. * The fields `periodStartDate`, `periodEndDate`, and `year` are displayed for each week of data in the API. * A Card Present type of transaction signifies the presence of a cardholder at the Point of Sale (POS), whereas a Card Not Present transaction may include Online (Electronic commerce), recurring transactions, mail order, phone order. * Recurring metrics like `recurring_cnt_perc` are calculated based on recurring transactions, where the cardholder authorizes a merchant to store and use their data periodically - for example, merchant categories like Books, Newspapers, Electric and Gas Utilities, Cable Services are some examples that frequently process recurring transactions. ## Reading a Benchmarks Report {#reading-a-benchmarks-report} This section explains the metrics returned in a Retail Sales Benchmarks report. The metrics are presented in groups based on the key business question they could help answer. Note that the grouping is created for guidance only, and the API does not deliver data in these groups. ### Benchmark Metrics {#benchmark-metrics} **Does the small business exist and is still operating?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| | `merchantCategoryCode` | `integer` | the Mastercard-defined merchant category code for the returned merchant. For full list, see [MCC Codes Booklet](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/quick-reference-booklet-merchant.pdf) | 478 | | `naicsCode` | `string` | North American Industry Classification System (NAICS) code. For full list, visit: [www.census.gov/naics](http://www.census.gov/naics) | 454113 | | `industryName` | `string` | the Mastercard-defined name of the industry of the merchant. For full list, see the [Industry Names](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/sbca/index.md#industry-names) section on this page | Arts and Craft Stores | | `firstSeenTxnDate` | `string` | the date of the first Mastercard transaction processed for this merchant. Format: YYYY-MM-DD | 2008-08-14 | | `lastSeenTxnDate` | `string` | the date of the last Mastercard transaction processed for this merchant. Format: YYYY-MM-DD | 2022-02-29 | | `periodStartDate` | `string` | the calendar date marking the beginning (inclusive) of the period for which this metric was calculated. Format: YYYY-MM-DD | 2022-02-01 | | `periodEndDate` | `string` | the calendar date marking the end (inclusive) of the period for which this metric was calculated. Format: YYYY-MM-DD | 2022-02-28 | | `year` | `integer` | the calendar year for which this metric was calculated | 2021 | **What is the business' relative performance compared to its peers?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |----------------------------|-----------|----------------------------------------------------------------------------------------------------|---------| | `net_spend_index` | `double` | Relative performance of merchant's total spend amount vs. its competitor set | 114.0 | | `txn_cnt_index` | `double` | Relative performance of merchant's total spends transactions count vs. its competitor set | 118.0 | | `tkt_size_avg_index` | `double` | Relative performance of average spends per transaction at merchant location vs. its competitor set | 103.0 | | `spend_per_card_avg_index` | `double` | Relative performance of average spends per card at merchant location vs. its competitor set | 104.0 | **Can the business attract more repeat customers than its peers?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |----------------------------|-----------|----------------------------------------------------------------------------------------------------------|---------| | `recurring_txn_perc_index` | `double` | Relative performance of percentage of recurring transactions at merchant location vs its competitor set. | 122.0 | **How volatile is the business compared to its peers?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |---------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------|---------| | `declined_rate_perc_index` | `double` | Relative performance of percentage of transactions that are declined at merchant location vs its competitor set. | 103.0 | | `fraud_chargeback_rate_perc_index` | `double` | Relative performance of percentage of transactions that are fraudulent at merchant location vs its competitor set. | 107.0 | | `disputed_chargeback_rate_perc_index` | `double` | Relative performance of percentage of transactions that are cardholder disputed at merchant location vs its competitor set. | 94.0 | | `return_txn_amt_index` | `double` | Relative performance of total spends amount of returned purchases at merchant location vs its competitor set. | 116.0 | | `return_txn_cnt_index` | `double` | Relative performance of total transaction count of returned purchases at merchant location vs its competitor set. | 69.0 | **How does the business perform across online channels compared to its peers?** | METRIC | DATA TYPE | DESCRIPTION | EXAMPLE | |-------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------|---------| | `online_txn_perc_index` | `double` | Relative performance for percentage of transactions from online channels at merchant location vs. its competitor set. | 107.0 | #### Benchmark Metrics Formatting {#benchmark-metrics-formatting} * All metrics are rounded to the nearest integer, and due to their representation as double values, they display one decimal place consistently as zero - for example: 67.0, 116.0. * The API can return values like `0`, `null`, `-1` in some edge case scenarios where there is low transaction volume or no recent transactions at a merchant location. * `0` -- If no transactions were observed for the respective metrics at the merchant location. * `null` -- If the minimum number of transactions needed to calculate the respective not met in that period for the merchant location. * `-1` -- If there were transactions at the merchant location but insufficient transactions in the merchant competition set. #### Benchmarks Calculations and Delivery {#benchmarks-calculations-and-delivery} * All example metric amounts are index scores of performances of underlying transaction type at merchant location vs at the competitor set. * All metrics are calculated and delivered at monthly aggregation (calendar months) for the latest month only. * Metrics are refreshed every month with a lag for the latest available month of metrics that can be retrieved. * In some cases, `lastSeenTxnDate` could be later than the most recent available period of metrics due to the lag involved in generating monthly metrics. * An Online transaction is a sub-channel type of Card Not Present transactions where the customer places the order via Ecommerce. Other types of Card Not Present transactions may include recurring transactions, mail order, phone order. * Metric value of 100.0 indicates that the SMB is performing equivalent to its benchmark peer set, a value greater than 100.0 indicates the SMB is over-performing and less than 100.0 indicates that it is underperforming. For example, a `spend_per_card_avg_index` value of 104.0 means that the merchant is outperforming its peer set by 4%, while 97.0 means it is relatively underperforming by 3%, in terms of average spend per card. * Recurring metrics like `recurring_cnt_perc` are calculated based on recurring transactions, where the cardholder authorizes a merchant to store and use their data periodically. Merchant categories like Books, Newspapers, Electric and Gas Utilities, Cable Services are some examples that frequently process recurring transactions. ## Industry Names {#industry-names} This table lists the possible values for the `industryName` metric. This applies to both the Analytics and Benchmark reports. * Txt ```txt Accommodations Elementary, Middle, High Schools Optical Accounting and Legal Services Employment, Consulting Agencies Other Transportation Services Advertising Services Equipment Rental Pet Stores Agriculture/Forestry/Fishing/Hunting Family Apparel Photofinishing Services Amusement, Recreation Activities Financial Services Photography Services Arts and Craft Stores Florists Professional Sports Teams Automotive Fuel Giftware/Houseware/Card Shops Public Administration Automotive New and Used Car Sales Grocery Stores Real Estate Services Automotive Retail Health Care and Social Assistance Religious, Civic and Professional Organizations Automotive Used Only Car Sales Health/Beauty/Medical Supplies Security, Surveillance Services Bars/Taverns/Nightclubs Home Furnishings/Furniture Shoe Stores Beer/Wine/Liquor Stores Home Improvement Centers Software Production, Network Services and Data Processing Book Stores Information Retrieval Services Specialty Food Stores Camera/Photography Supplies Insurance Sporting Goods/Apparel/Footwear Casino and Gambling Activities Jewelry and Giftware T+E Airlines Children's Apparel Live Performances, Events, Exhibits T+E Bus Cleaning and Exterminating Services Luggage and Leather Stores T+E Cruise Lines Clothing, Uniform, Costume Rental Maintenance and Repair Services T+E Railroad College, University Education Manufacturing T+E Taxi and Limousine Communications, Telecommunications Equipment Men's Apparel T+E Vehicle Rental Communications, Telecommunications, Cable Services Miscellaneous Toy Stores Computer/Software Stores Miscellaneous Administrative and Waste Disposal Services Travel Agencies and Tour Operators Construction Services Miscellaneous Apparel Utilities Consumer Credit reporting Miscellaneous Educational Services Variety/General Merchandise Stores Consumer Electronics/Appliances Miscellaneous entertainment and recreation Veterinary Services Cosmetics and Beauty Services Miscellaneous Personal Services Video and Game Rentals Courier Services Miscellaneous Professional Services Vocation, Trade and Business Schools Dating Services Miscellaneous Publishing Industries Warehouse Death Care Services Miscellaneous Technical Services Wholesale Clubs Department Stores Miscellaneous Vehicle Sales Wholesale Trade Discount Department Stores Movie and Other Theatrical Women's Apparel Drug Store Chains Music and Videos Empty string when no data is available Dry Cleaning, Laundry Services Newspapers and Magazines Eating Places Office Supply Chains ``` ## Testing the APIs {#testing-the-apis} The [test data for the standalone API](https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/) is also available for use in the Open Finance Sandbox. ## Further Information {#further-information} For more information, see the [FAQ for the standalone API](https://developer.mastercard.com/small-business-credit-analytics/documentation/support/#faq). Note: For support for the Open Finance version of SBCA, do not use the "Get Help" button on the above page, which is for the standalone version. Refer to the [Open Finance support page](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). --- # Data Enrichment source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md Data Enrichment can enhance your internally held (first party) financial account transaction data by categorizing transactions, identifying the entities and platforms involved, location data, logos, and website URLs. This helps improve the usability of transaction data for various applications, such as personal financial management tools and online banking platforms. The service can be used for enriching transactions in your own banking solutions, or those sourced through Open Finance providers other than Mastercard. Tip: There is no need to use [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) to obtain consumer consent before using this service, as the transaction data is already held by you. Data Enrichment supports a wide range of financial accounts including checking, savings, HSAs, and card accounts for both consumers and small businesses. Enriching the data in this way improves the usability of your transaction data for a variety of purposes, including for the use cases outlined below. ## Use Cases {#use-cases} * Personal Financial Management (PFM): Enriched transaction data allows users to track expenses, create budgets, and gain insights into their spending habits. * Fraud Management: Enhanced data transparency helps in identifying and managing fraudulent transactions more effectively. * Customer and Portfolio Analytics: Improved data quality aids in better segmentation, positioning, and personalized marketing strategies. * Personalization: Provides personalized product recommendations, offers, and rewards based on enriched transaction data. * Open Finance Data Consistency: Data received from multiple Open Finance providers can be enriched to provide a consistent output. ## How It Works {#how-it-works} You can use Data Enrichment via an API, or by a batch process: * [Data Enrichment API](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/api/index.md) --- Call the Transaction Data Enrichment endpoint with up to 1000 transactions in the payload. The response will consist of the same list of transactions, with additional fields returned for the enhanced information which was discovered about each transaction. * [Batch processing](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/batch/index.md) --- We also support transaction enrichment through a batch process. The batch process allows you to upload a file containing multiple transactions---up to 6 million transactions per file. The quality of the data returned is the same with each method. --- # Data Connect Components Flows source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md This section gives more detail on the different flows. ## Application Flows {#application-flows} The following sequence diagrams show what happens in the following situations: * Legacy Institution Flow, Successful Login * Legacy Institution Flow, Login Error * Legacy Institution Flow, MFA Challenge * Legacy Institution Flow, Reconnection Flow (using Data Connect Fix) * OAuth Institution, Popup * OAuth Institution, Redirect
### Legacy Institution Flow, Successful Login {#legacy-institution-flow-successful-login} Diagram components-legacy-login-success ### Legacy Institution Flow, Login Error {#legacy-institution-flow-login-error} Diagram components-legacy-login-error ### Legacy Institution Flow, MFA Challenge {#legacy-institution-flow-mfa-challenge} Diagram components-legacy-login-mfa ### Legacy Institution Flow, Reconnection Flow (Using Data Connect Fix) {#legacy-institution-flow-reconnection-flow-using-data-connect-fix} The Reconnection Flow allows Data Connect Fix to be used when a problem occurs with a previously added user account (such as the connection to the user's FI being lost, or if the user's credentials were updated for various reasons). See [Data Connect Fix](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-fix). Diagram components-legacy-login-fix ### OAuth Institution, Popup {#oauth-institution-popup} Diagram components-oauth-popup ### OAuth Institution, Redirect {#oauth-institution-redirect} Diagram components-oauth-redirect ## SDK Flows {#sdk-flows} The following diagram highlights the key aspects of the Data Connect Components Web SDK and how data flows from the calling application, to the SDK, to Mastercard Servers, and back to the calling application. This shows how user credentials are handled securely. Diagram components-sdk-flow ## Legacy and OAuth Connections {#legacy-and-oauth-connections} The APIs used depends on whether the FI is a legacy or OAuth connection. For legacy connections, the Data Connect experience will ask the user for their user credentials for the FI. For direct or OAuth connections, the user is redirected to a login screen hosted by the FI. ### Legacy Connections {#legacy-connections} For connections that do not leverage direct connectivity (i.e., OAuth), a means to embed a login form is provided via this endpoint. **Create Login Forms** API Reference: `POST /connect-components/institutions/{institution_id}/login-forms` Upon calling this endpoint, a customerId is provided as well as the id of the institution for which the customer would like to log into. The response from this call is a JSON structure that cannot be used directly. Instead, the JSON data is provided to the Data Connect Components Web SDK which handles the rendering of the login form. Warning: The serviceAgreement object must be provided in the request body, or the call will fail and no login attempt with the FI will be made. **Render Login Forms** Each element of a login form (i.e., username input, password input) is to be rendered individually, using the Data Connect Components Web SDK. This allows for complete control in placement of the elements. Additionally, the SDK provides means for styling the login form elements. The means for submitting this data (e.g., a button element) is left entirely up to the parent application to design and control. It will be the responsibility of the application developer to ensure that the submit element calls the appropriate Data Connect Components Web SDK method. See [Render Login Form](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#render-login-form) in the Data Connect Components Web SDK documentation for more information. **Submitting Login Form Data** Once the user has entered their credentials and triggered the submit button, a call to the Data Connect Components Web SDK's `form.submit()` method must be made. This method will send an event to the login form elements which will, in turn, submit their contents directly to Mastercard's servers. It is important to note that the user credentials contained within the Login Form are never made available to the calling application and the transmission of them is handled within the SDK using iframes. Additionally, security measures, such as same-origin policies, are enforced to ensure that data cannot be exfiltrated from the Login Form elements. See [Submit Login Form](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#submit-login-form) in the Data Connect Components Web SDK documentation for more information. ### OAuth Connections {#oauth-connections} For OAuth connections, the handling of credentials is facilitated directly by the FI. As such, a URL is needed to direct the user to that managed login page. A call is made to the Mastercard servers to generate this URL for a specific institution and customer. **Create OAuth URL** API Reference: `POST /connect-components/institutions/{institution_id}/oauth-urls` Warning: The serviceAgreement object must be provided in the request body, or the call will fail and no login attempt with the FI will be made. Because the user credential interactions happen entirely within the financial institution's web page, the SDK will not provide any data or emit any events until the user has completed the login and account selection (where available). See [OAuth Usage](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#oauth-usage) in the Data Connect Components Web SDK documentation for more information. **LoggedIn Event** Once the user has completed the interaction with the FI, the user will either be directed to a landing page (in the cases where a popup was used to display the OAuth login form), or the user will be redirected back to the calling application (in cases where redirection was used). In both scenarios, a loggedIn event will be emitted by the SDK. Warning: There are special considerations for event handling in cases where redirection is used. It is the calling application's responsibility to ensure that the SDK is present and loaded on the page to which the user is redirected. This event indicates to the calling application that any cleanup work (such as closing popups) should be performed. At the time this event is received, account discovery has not been completed, so it would be appropriate to display a loading screen to the user. 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. ### Initiate Reconnection (Data Connect Fix for Components) {#initiate-reconnection-data-connect-fix-for-components} The Initiate Reconnection endpoint (which allows a Data Connect Fix flow for Data Connect Components) can be used when a problem occurs with a previously added user account, such as the connection to the user's FI being lost or the user's credentials were updated (for any number of reasons). 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 Initiate Reconnection. The [Aggregation Status Code](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) returned when you call one of the Account Aggregation endpoints will indicate what is causing the issue, and whether using Initiate Reconnection will help. The Data Connect Fix URL can be presented to the user to allow them to re-establish the connection with the FI. API Reference: `POST /connect-components/customers/{customer_id}/institution-login-ids/{institution_login_id}/reconnections` --- # Account Opening and Funding source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-payments/account-opening/index.md Account opening should take seconds, but issues like manual uploads and micro-deposits add delays. This is why Mastercard launched an enhanced Open Finance for Account Opening solution. This innovation integrates account owner verification with identity insights into a single API to help you meet your customers' needs for security and transparency and introduces new ways to instantly verify account ownership creating a better onboarding experience.
## Account Opening and Optional Funding After an Account Has Been Created - Data Connect Full {#account-opening-and-optional-funding-after-an-account-has-been-created---data-connect-full} Tip: Access the [Figma file](https://www.figma.com/design/pqrT4uBCEsbL53GXSxh6g0/Open-Banking-US-for-Payments?node-id=1-65124&t=fxzcOZWigGMOnS4T-4) for this experience to duplicate and customize in your own environment. To view the UX journey, use **full screen mode** or **zoom** controls. Please allow a few seconds for the screens to load. ## Account Opening With Required Account Funding - Data Connect Full {#account-opening-with-required-account-funding---data-connect-full}
## Account Opening With Optional Account Funding - Data Connect Full {#account-opening-with-optional-account-funding---data-connect-full} Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). Note: For developers, here is the API documentation: [Account Opening and Funding](https://developer.mastercard.com/open-finance-us/documentation/usecases/ob-account-opening/index.md)
Next: [Open Finance US for Lending](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/index.md) --- # Verification of Assets source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-assets/index.md Our Open Finance US asset verification puts the borrower at the center of the mortgage application process. After all, they are making one of the most significant purchases in their life. We want to make buying a home as easy as possible for the borrower and rewarding for mortgage lenders. Here is how we do it: * Provide real-time asset information, direct from financial institutions, to mitigate fraud, increase accuracy, and enhance risk assessment. * Offer unlimited report refreshes for 60 days, helping you stay up-to-date. * Stay ahead of the competition by accelerating your digital transformation to exceed the needs of today's consumers. * Get eligibility for rep and warranty relief from Fannie Mae Day 1 Certainty and Freddie Mac AIM programs. * Manage your customer conversion funnel with an easy, user-centric digital process * Distinguish your business by attracting and engaging more prospective customers.
## User Journey - Data Connect Full {#user-journey---data-connect-full} Tip: Access the [Figma file](https://www.figma.com/design/IFeJZsZKnQccdztXSSzySp/Open-Banking-US-for-Lending?node-id=1-1281&t=jcfNF8SU4qJrlSyC-4) for this experience to duplicate and customize in your own environment. To view the UX journey, use **full screen mode** or **zoom** controls. Please allow a few seconds for the screens to load. Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md). Note: For developers, here is the API documentation: [Verification of Assets](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md)
Next: [Verification of Income and Employment](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/open-finance-us-for-lending/verification-of-income-and-employment/index.md) --- # Cash Flow Analytics (Small Business) source: https://developer.mastercard.com/open-finance-us/documentation/products/small-business/cash-flow-analytics-sb/index.md Note: This documentation is for Small Business use cases. For consumer use cases, see [Cash Flow Analytics (Consumer)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md). Cash Flow Analytics (CFA) analyzes up to 24 months of credits and debits in connected accounts to surface cash-flow health and trends - such as inflows, outflows, net cash flow, seasonality, and NSF events - to assess capacity to pay and volatility. For business use cases (CRA or non-CRA), CFA returns model-ready attributes over the desired time intervals. Learn more about Mastercard's [Cash Flow](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#cash-flow) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months * **Cash Flow Analytics:** Includes debit and credit breakouts, net cash flow attributes, and revenue assessment * **Non-Sufficient Funds (NSF) Summary**: The presence of NSFs can be a key indicator of financial distress * **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge * **Supported Account Types**: Checking, Savings, Money Market, CD, Investment account types, Mortgage, Loan, Credit Card, Line of Credit, Payroll, Student Loan, Education Savings, Health Savings Account * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The Cash Flow Analytics product can be used for the following use cases: * Credit Card Issuance * Credit Line Management * Customer/Portfolio Monitoring * Debt Collection * Servicing * Small and Medium Businesses ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API. * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers). * [Create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record for business use cases where the applicant is personally guaranteeing the loan. * [Create and link a business record to the customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses). * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows). ## Generate a Cash Flow Analytics Report {#generate-a-cash-flow-analytics-report} To generate or refresh a Cash Flow Analytics report, use the following endpoint, replacing `{userType}` in the path with `business`: API Reference: `POST /decisioning/v2/customers/{customerId}/reports/cashflow-analytics/userTypes/{userType}` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * The `Revenue` attribute is only provided when `userType` = `business`.
* Use the `timeIntervalType` to select the periodicity at which attributes will be calculated. Defaults to Monthly Calendar. Customize the type of Cash Flow Analytics report received based on inputs provided when generating the report: | Report Type | User Type | forCraPurpose | applicantIs PersonalGuarantor | Consumer Required? | Customer Required? | Business Required? | |-------------|-----------|---------------|-------------------------------|--------------------|--------------------|--------------------| | cfrbcra | business | true | true | Y | Y | Y | | cfrbftc | business | true | false | N | Y | Y | | cfrbnoncra | business | false | false | N | Y | Y | ## Get Cash Flow Analytics Reports {#get-cash-flow-analytics-reports} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "bey4bhxx3ydi-cfrbnoncra", "customerType": "testing", "customerId": 9019235966, "requestId": "v6ijg565kt", "requesterName": "Mastercard", "createdDate": 1778686318, "title": "Mastercard Open Banking Cash Flow Analytics", "type": "cfrbnoncra", "status": "success", "businessDetails": { "businessId": "496559", "name": "Acme Test LLC", "address": { "addressLine1": "123 Main St", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123" } }, "constraints": { "analyticsReportData": { "forCraPurpose": false, "timeIntervalTypes": [ "MONTHLY_CALENDAR" ] } }, "startDate": 1715614318, "endDate": 1778686318, "days": 730, "institutions": [ { "id": 102105, "name": "FinBank Profiles - A", "urlHomeApp": "http://www.finbank.com", "accounts": [ { "id": 9022057712, "ownerName": "PATRICK & LORRAINE PURCHASER", "ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859", "name": "Checking", "number": "0130", "type": "checking", "aggregationStatusCode": 0, "currentBalance": 9357.24, "availableBalance": 0.0, "balanceDate": 1778686321, "transactions": [ { "id": 13700605149, "amount": 13.74, "postedDate": 1777982400, "description": "BIGBOX DEBIT CRD ACH TRAN 0005", "memo": "12345678903 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605148, "amount": -57.32, "postedDate": 1775390400, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605147, "amount": 13.74, "postedDate": 1772712000, "description": "BIGBOX DEBIT CRD ACH TRAN 0004", "memo": "12345678902 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605144, "amount": -57.32, "postedDate": 1770292800, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605142, "amount": 13.74, "postedDate": 1767614400, "description": "BIGBOX DEBIT CRD ACH TRAN 0003", "memo": "12345678901 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605156, "amount": -57.32, "postedDate": 1764936000, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605157, "amount": 13.74, "postedDate": 1762344000, "description": "BIGBOX DEBIT CRD ACH TRAN 0014", "memo": "12345678912 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605134, "amount": -57.32, "postedDate": 1759665600, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605135, "amount": 13.74, "postedDate": 1757073600, "description": "BIGBOX DEBIT CRD ACH TRAN 0013", "memo": "12345678911 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605137, "amount": -57.32, "postedDate": 1754395200, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605138, "amount": 13.74, "postedDate": 1751716800, "description": "BIGBOX DEBIT CRD ACH TRAN 0012", "memo": "12345678910 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605141, "amount": -57.32, "postedDate": 1749124800, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605143, "amount": 13.74, "postedDate": 1746446400, "description": "BIGBOX DEBIT CRD ACH TRAN 0011", "memo": "12345678909 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605154, "amount": -57.32, "postedDate": 1743854400, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605152, "amount": 13.74, "postedDate": 1741176000, "description": "BIGBOX DEBIT CRD ACH TRAN 0010", "memo": "12345678908 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605151, "amount": -57.32, "postedDate": 1738756800, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605150, "amount": 13.74, "postedDate": 1736078400, "description": "BIGBOX DEBIT CRD ACH TRAN 0009", "memo": "12345678907 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605136, "amount": -57.32, "postedDate": 1733400000, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605139, "amount": 13.74, "postedDate": 1730808000, "description": "BIGBOX DEBIT CRD ACH TRAN 0020", "memo": "12345678918 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605140, "amount": -57.32, "postedDate": 1728129600, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605145, "amount": 13.74, "postedDate": 1725537600, "description": "BIGBOX DEBIT CRD ACH TRAN 0019", "memo": "12345678917 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605146, "amount": -57.32, "postedDate": 1722859200, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" }, { "id": 13700605153, "amount": 13.74, "postedDate": 1720180800, "description": "BIGBOX DEBIT CRD ACH TRAN 0018", "memo": "12345678916 POS ID: 1234567896", "normalizedPayee": "Crd Ach", "institutionTransactionId": "0000000000", "category": "Deposit" }, { "id": 13700605155, "amount": -57.32, "postedDate": 1717588800, "description": "Credit Card Payment", "normalizedPayee": "credit card payment", "institutionTransactionId": "0000000000", "category": "Credit Card Payment" } ], "analytics": { "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2024-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-06-05", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-06-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "e980319e-5aad-47d4-8d12-5443c1f59def" ], "transactionIds": [ "13700605154", "13700605146", "13700605144", "13700605136", "13700605137", "13700605151", "13700605141", "13700605148", "13700605134", "13700605155", "13700605156", "13700605140" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-05-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-05-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-05-13", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-05-01", "sum": 13.74, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "CASH_INFLOW", "streamIds": [ "7da324f5-69eb-4679-9cee-c91c624eab5c" ], "transactionIds": [ "13700605145", "13700605143", "13700605135", "13700605138", "13700605153", "13700605152", "13700605142", "13700605149", "13700605150", "13700605139", "13700605157", "13700605147" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2024-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-06-05", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-05-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-05-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-06-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-05-13", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-05-01", "sum": 13.74, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "ALL_CASH_FLOWS", "streamIds": [ "7da324f5-69eb-4679-9cee-c91c624eab5c", "e980319e-5aad-47d4-8d12-5443c1f59def" ], "transactionIds": [ "13700605137", "13700605153", "13700605142", "13700605157", "13700605134", "13700605156", "13700605145", "13700605144", "13700605152", "13700605148", "13700605143", "13700605154", "13700605136", "13700605135", "13700605138", "13700605151", "13700605141", "13700605155", "13700605147", "13700605140", "13700605146", "13700605149", "13700605150", "13700605139" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "REVENUE", "streamIds": [], "transactionIds": [], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "NSF_FEE_CHARGES", "streamIds": [], "transactionIds": [], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "NSF_FEE_REVERSALS", "streamIds": [], "transactionIds": [], "projectedValues": [], "streamConfidences": null } ], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 9822.88, "count": 26, "endDate": "2024-06-30", "endingValue": 9822.88, "max": 9822.88, "mean": 9822.88, "median": 9822.88, "min": 9822.88, "standardDeviation": 0.0, "startDate": "2024-06-05", "sum": 255394.87999999998, "comparedToCohorts": [] }, { "beginningValue": 9822.88, "count": 31, "endDate": "2024-07-31", "endingValue": 9836.62, "max": 9836.62, "mean": 9834.847096774194, "median": 9836.62, "min": 9822.88, "standardDeviation": 4.682277361533348, "startDate": "2024-07-01", "sum": 304880.26, "comparedToCohorts": [] }, { "beginningValue": 9836.62, "count": 31, "endDate": "2024-08-31", "endingValue": 9779.3, "max": 9836.62, "mean": 9786.696129032258, "median": 9779.3, "min": 9779.3, "standardDeviation": 19.533343403425572, "startDate": "2024-08-01", "sum": 303387.57999999996, "comparedToCohorts": [] }, { "beginningValue": 9779.3, "count": 30, "endDate": "2024-09-30", "endingValue": 9793.04, "max": 9793.04, "mean": 9791.208, "median": 9793.04, "min": 9779.3, "standardDeviation": 4.750548716038342, "startDate": "2024-09-01", "sum": 293736.24, "comparedToCohorts": [] }, { "beginningValue": 9793.04, "count": 31, "endDate": "2024-10-31", "endingValue": 9735.72, "max": 9793.04, "mean": 9743.116129032258, "median": 9735.72, "min": 9735.72, "standardDeviation": 19.533343403425572, "startDate": "2024-10-01", "sum": 302036.6, "comparedToCohorts": [] }, { "beginningValue": 9735.72, "count": 30, "endDate": "2024-11-30", "endingValue": 9749.46, "max": 9749.46, "mean": 9747.627999999999, "median": 9749.46, "min": 9735.72, "standardDeviation": 4.750548716037713, "startDate": "2024-11-01", "sum": 292428.83999999997, "comparedToCohorts": [] }, { "beginningValue": 9749.46, "count": 31, "endDate": "2024-12-31", "endingValue": 9692.14, "max": 9749.46, "mean": 9699.536129032258, "median": 9692.14, "min": 9692.14, "standardDeviation": 19.533343403424954, "startDate": "2024-12-01", "sum": 300685.62, "comparedToCohorts": [] }, { "beginningValue": 9692.14, "count": 31, "endDate": "2025-01-31", "endingValue": 9705.88, "max": 9705.88, "mean": 9704.107096774193, "median": 9705.88, "min": 9692.14, "standardDeviation": 4.682277361532728, "startDate": "2025-01-01", "sum": 300827.31999999995, "comparedToCohorts": [] }, { "beginningValue": 9705.88, "count": 28, "endDate": "2025-02-28", "endingValue": 9648.56, "max": 9705.88, "mean": 9656.74857142857, "median": 9648.56, "min": 9648.56, "standardDeviation": 20.425885848560117, "startDate": "2025-02-01", "sum": 270388.95999999996, "comparedToCohorts": [] }, { "beginningValue": 9648.56, "count": 31, "endDate": "2025-03-31", "endingValue": 9662.3, "max": 9662.3, "mean": 9660.527096774193, "median": 9662.3, "min": 9648.56, "standardDeviation": 4.682277361532728, "startDate": "2025-03-01", "sum": 299476.33999999997, "comparedToCohorts": [] }, { "beginningValue": 9662.3, "count": 30, "endDate": "2025-04-30", "endingValue": 9604.98, "max": 9662.3, "mean": 9612.622666666666, "median": 9604.98, "min": 9604.98, "standardDeviation": 19.818155196745607, "startDate": "2025-04-01", "sum": 288378.68, "comparedToCohorts": [] }, { "beginningValue": 9604.98, "count": 31, "endDate": "2025-05-31", "endingValue": 9618.72, "max": 9618.72, "mean": 9616.947096774193, "median": 9618.72, "min": 9604.98, "standardDeviation": 4.682277361532728, "startDate": "2025-05-01", "sum": 298125.36, "comparedToCohorts": [] }, { "beginningValue": 9618.72, "count": 30, "endDate": "2025-06-30", "endingValue": 9561.4, "max": 9618.72, "mean": 9569.042666666666, "median": 9561.4, "min": 9561.4, "standardDeviation": 19.818155196745607, "startDate": "2025-06-01", "sum": 287071.27999999997, "comparedToCohorts": [] }, { "beginningValue": 9561.4, "count": 31, "endDate": "2025-07-31", "endingValue": 9575.14, "max": 9575.14, "mean": 9573.367096774193, "median": 9575.14, "min": 9561.4, "standardDeviation": 4.682277361532728, "startDate": "2025-07-01", "sum": 296774.38, "comparedToCohorts": [] }, { "beginningValue": 9575.14, "count": 31, "endDate": "2025-08-31", "endingValue": 9517.82, "max": 9575.14, "mean": 9525.216129032258, "median": 9517.82, "min": 9517.82, "standardDeviation": 19.533343403424954, "startDate": "2025-08-01", "sum": 295281.7, "comparedToCohorts": [] }, { "beginningValue": 9517.82, "count": 30, "endDate": "2025-09-30", "endingValue": 9531.56, "max": 9531.56, "mean": 9529.728, "median": 9531.56, "min": 9517.82, "standardDeviation": 4.750548716037713, "startDate": "2025-09-01", "sum": 285891.83999999997, "comparedToCohorts": [] }, { "beginningValue": 9531.56, "count": 31, "endDate": "2025-10-31", "endingValue": 9474.24, "max": 9531.56, "mean": 9481.636129032258, "median": 9474.24, "min": 9474.24, "standardDeviation": 19.533343403424954, "startDate": "2025-10-01", "sum": 293930.72, "comparedToCohorts": [] }, { "beginningValue": 9474.24, "count": 30, "endDate": "2025-11-30", "endingValue": 9487.98, "max": 9487.98, "mean": 9486.148, "median": 9487.98, "min": 9474.24, "standardDeviation": 4.750548716037713, "startDate": "2025-11-01", "sum": 284584.44, "comparedToCohorts": [] }, { "beginningValue": 9487.98, "count": 31, "endDate": "2025-12-31", "endingValue": 9430.66, "max": 9487.98, "mean": 9438.056129032258, "median": 9430.66, "min": 9430.66, "standardDeviation": 19.533343403424954, "startDate": "2025-12-01", "sum": 292579.74, "comparedToCohorts": [] }, { "beginningValue": 9430.66, "count": 31, "endDate": "2026-01-31", "endingValue": 9444.4, "max": 9444.4, "mean": 9442.627096774193, "median": 9444.4, "min": 9430.66, "standardDeviation": 4.682277361532728, "startDate": "2026-01-01", "sum": 292721.44, "comparedToCohorts": [] }, { "beginningValue": 9444.4, "count": 28, "endDate": "2026-02-28", "endingValue": 9387.08, "max": 9444.4, "mean": 9395.26857142857, "median": 9387.08, "min": 9387.08, "standardDeviation": 20.425885848560117, "startDate": "2026-02-01", "sum": 263067.52, "comparedToCohorts": [] }, { "beginningValue": 9387.08, "count": 31, "endDate": "2026-03-31", "endingValue": 9400.82, "max": 9400.82, "mean": 9399.047096774193, "median": 9400.82, "min": 9387.08, "standardDeviation": 4.682277361532728, "startDate": "2026-03-01", "sum": 291370.45999999996, "comparedToCohorts": [] }, { "beginningValue": 9400.82, "count": 30, "endDate": "2026-04-30", "endingValue": 9343.5, "max": 9400.82, "mean": 9351.142666666667, "median": 9343.5, "min": 9343.5, "standardDeviation": 19.818155196745607, "startDate": "2026-04-01", "sum": 280534.28, "comparedToCohorts": [] }, { "beginningValue": 9343.5, "count": 13, "endDate": "2026-05-13", "endingValue": 9357.24, "max": 9357.24, "mean": 9353.012307692308, "median": 9357.24, "min": 9343.5, "standardDeviation": 6.600482499845587, "startDate": "2026-05-01", "sum": 121589.16, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "projectedValues": [] }, { "attributeName": "LIABILITY_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 0.0, "count": 26, "endDate": "2024-06-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-06-05", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-07-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-07-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-08-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-08-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-09-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-09-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-10-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-10-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-11-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-11-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-12-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-12-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-01-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-01-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2025-02-28", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-02-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-03-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-03-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-04-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-04-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-05-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-05-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-06-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-06-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-07-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-07-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-08-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-08-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-09-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-09-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-10-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-10-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-11-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-11-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-12-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-12-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-01-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-01-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2026-02-28", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-02-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-03-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-03-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2026-04-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-04-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 13, "endDate": "2026-05-13", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-05-01", "sum": 0.0, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "projectedValues": [] }, { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": -57.32, "count": 26, "endDate": "2024-06-30", "endingValue": 0.0, "max": 0.0, "mean": -2.2046153846153844, "median": 0.0, "min": -57.32, "standardDeviation": 11.241376866120708, "startDate": "2024-06-05", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-07-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2024-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-08-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2024-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-09-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2024-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-10-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2024-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-11-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2024-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-12-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2024-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-01-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2025-02-28", "endingValue": 0.0, "max": 0.0, "mean": -2.047142857142857, "median": 0.0, "min": -57.32, "standardDeviation": 10.832461796444452, "startDate": "2025-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-03-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-04-30", "endingValue": 0.0, "max": 0.0, "mean": -1.9106666666666667, "median": 0.0, "min": -57.32, "standardDeviation": 10.465152332065374, "startDate": "2025-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-05-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-05-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-06-30", "endingValue": 0.0, "max": 0.0, "mean": -1.9106666666666667, "median": 0.0, "min": -57.32, "standardDeviation": 10.465152332065374, "startDate": "2025-06-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-07-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-08-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2025-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-09-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2025-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-10-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2025-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-11-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2025-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-12-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2025-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-01-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2026-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2026-02-28", "endingValue": 0.0, "max": 0.0, "mean": -2.047142857142857, "median": 0.0, "min": -57.32, "standardDeviation": 10.832461796444452, "startDate": "2026-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-03-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2026-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2026-04-30", "endingValue": 0.0, "max": 0.0, "mean": -1.9106666666666667, "median": 0.0, "min": -57.32, "standardDeviation": 10.465152332065374, "startDate": "2026-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 13, "endDate": "2026-05-13", "endingValue": 0.0, "max": 13.74, "mean": 1.0569230769230769, "median": 0.0, "min": 0.0, "standardDeviation": 3.810790348067324, "startDate": "2026-05-01", "sum": 13.74, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "projectedValues": [] } ], "streams": [ { "cadence": 61, "id": "7da324f5-69eb-4679-9cee-c91c624eab5c", "payee": "PATRICK - LORRAINE PURCHASER", "payor": "crd ach", "recency": 8, "earliestObservedDate": "2024-07-05T06:00:00", "latestObservedDate": "2026-05-05T06:00:00", "count": 12, "sum": 164.88, "status": "active", "min": 13.74, "max": 13.74, "mean": 13.74, "median": 13.74, "standardDeviation": 0.0, "minimumCadence": 59, "maximumCadence": 62, "medianCadence": 61, "modeCadence": 61, "standardDeviationCadence": 0.9820034664301385, "transactionIds": [ "13700605153", "13700605145", "13700605139", "13700605150", "13700605152", "13700605143", "13700605138", "13700605135", "13700605157", "13700605142", "13700605147", "13700605149" ], "attributes": [ "CASH_INFLOW", "ALL_CASH_FLOWS" ] }, { "cadence": 61, "id": "e980319e-5aad-47d4-8d12-5443c1f59def", "payee": "credit card payment", "payor": "PATRICK - LORRAINE PURCHASER", "recency": 38, "earliestObservedDate": "2024-06-05T06:00:00", "latestObservedDate": "2026-04-05T06:00:00", "count": 12, "sum": -687.84, "status": "active", "min": -57.32, "max": -57.32, "mean": -57.32, "median": -57.32, "standardDeviation": 0.0, "minimumCadence": 59, "maximumCadence": 62, "medianCadence": 61, "modeCadence": 61, "standardDeviationCadence": 0.9648821040663343, "transactionIds": [ "13700605155", "13700605146", "13700605140", "13700605136", "13700605151", "13700605154", "13700605141", "13700605137", "13700605134", "13700605156", "13700605144", "13700605148" ], "attributes": [ "CASH_OUTFLOW", "ALL_CASH_FLOWS" ] } ] }, "currency": "USD" } ], "oauthEnabled": false } ], "customerAnalytics": { "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 9822.88, "count": 26, "endDate": "2024-06-30", "endingValue": 9822.88, "max": 9822.88, "mean": 9822.88, "median": 9822.88, "min": 9822.88, "standardDeviation": 0.0, "startDate": "2024-06-05", "sum": 255394.87999999998, "comparedToCohorts": [] }, { "beginningValue": 9822.88, "count": 31, "endDate": "2024-07-31", "endingValue": 9836.62, "max": 9836.62, "mean": 9834.847096774194, "median": 9836.62, "min": 9822.88, "standardDeviation": 4.682277361533348, "startDate": "2024-07-01", "sum": 304880.26, "comparedToCohorts": [] }, { "beginningValue": 9836.62, "count": 31, "endDate": "2024-08-31", "endingValue": 9779.3, "max": 9836.62, "mean": 9786.696129032258, "median": 9779.3, "min": 9779.3, "standardDeviation": 19.533343403425572, "startDate": "2024-08-01", "sum": 303387.57999999996, "comparedToCohorts": [] }, { "beginningValue": 9779.3, "count": 30, "endDate": "2024-09-30", "endingValue": 9793.04, "max": 9793.04, "mean": 9791.208, "median": 9793.04, "min": 9779.3, "standardDeviation": 4.750548716038342, "startDate": "2024-09-01", "sum": 293736.24, "comparedToCohorts": [] }, { "beginningValue": 9793.04, "count": 31, "endDate": "2024-10-31", "endingValue": 9735.72, "max": 9793.04, "mean": 9743.116129032258, "median": 9735.72, "min": 9735.72, "standardDeviation": 19.533343403425572, "startDate": "2024-10-01", "sum": 302036.6, "comparedToCohorts": [] }, { "beginningValue": 9735.72, "count": 30, "endDate": "2024-11-30", "endingValue": 9749.46, "max": 9749.46, "mean": 9747.627999999999, "median": 9749.46, "min": 9735.72, "standardDeviation": 4.750548716037713, "startDate": "2024-11-01", "sum": 292428.83999999997, "comparedToCohorts": [] }, { "beginningValue": 9749.46, "count": 31, "endDate": "2024-12-31", "endingValue": 9692.14, "max": 9749.46, "mean": 9699.536129032258, "median": 9692.14, "min": 9692.14, "standardDeviation": 19.533343403424954, "startDate": "2024-12-01", "sum": 300685.62, "comparedToCohorts": [] }, { "beginningValue": 9692.14, "count": 31, "endDate": "2025-01-31", "endingValue": 9705.88, "max": 9705.88, "mean": 9704.107096774193, "median": 9705.88, "min": 9692.14, "standardDeviation": 4.682277361532728, "startDate": "2025-01-01", "sum": 300827.31999999995, "comparedToCohorts": [] }, { "beginningValue": 9705.88, "count": 28, "endDate": "2025-02-28", "endingValue": 9648.56, "max": 9705.88, "mean": 9656.74857142857, "median": 9648.56, "min": 9648.56, "standardDeviation": 20.425885848560117, "startDate": "2025-02-01", "sum": 270388.95999999996, "comparedToCohorts": [] }, { "beginningValue": 9648.56, "count": 31, "endDate": "2025-03-31", "endingValue": 9662.3, "max": 9662.3, "mean": 9660.527096774193, "median": 9662.3, "min": 9648.56, "standardDeviation": 4.682277361532728, "startDate": "2025-03-01", "sum": 299476.33999999997, "comparedToCohorts": [] }, { "beginningValue": 9662.3, "count": 30, "endDate": "2025-04-30", "endingValue": 9604.98, "max": 9662.3, "mean": 9612.622666666666, "median": 9604.98, "min": 9604.98, "standardDeviation": 19.818155196745607, "startDate": "2025-04-01", "sum": 288378.68, "comparedToCohorts": [] }, { "beginningValue": 9604.98, "count": 31, "endDate": "2025-05-31", "endingValue": 9618.72, "max": 9618.72, "mean": 9616.947096774193, "median": 9618.72, "min": 9604.98, "standardDeviation": 4.682277361532728, "startDate": "2025-05-01", "sum": 298125.36, "comparedToCohorts": [] }, { "beginningValue": 9618.72, "count": 30, "endDate": "2025-06-30", "endingValue": 9561.4, "max": 9618.72, "mean": 9569.042666666666, "median": 9561.4, "min": 9561.4, "standardDeviation": 19.818155196745607, "startDate": "2025-06-01", "sum": 287071.27999999997, "comparedToCohorts": [] }, { "beginningValue": 9561.4, "count": 31, "endDate": "2025-07-31", "endingValue": 9575.14, "max": 9575.14, "mean": 9573.367096774193, "median": 9575.14, "min": 9561.4, "standardDeviation": 4.682277361532728, "startDate": "2025-07-01", "sum": 296774.38, "comparedToCohorts": [] }, { "beginningValue": 9575.14, "count": 31, "endDate": "2025-08-31", "endingValue": 9517.82, "max": 9575.14, "mean": 9525.216129032258, "median": 9517.82, "min": 9517.82, "standardDeviation": 19.533343403424954, "startDate": "2025-08-01", "sum": 295281.7, "comparedToCohorts": [] }, { "beginningValue": 9517.82, "count": 30, "endDate": "2025-09-30", "endingValue": 9531.56, "max": 9531.56, "mean": 9529.728, "median": 9531.56, "min": 9517.82, "standardDeviation": 4.750548716037713, "startDate": "2025-09-01", "sum": 285891.83999999997, "comparedToCohorts": [] }, { "beginningValue": 9531.56, "count": 31, "endDate": "2025-10-31", "endingValue": 9474.24, "max": 9531.56, "mean": 9481.636129032258, "median": 9474.24, "min": 9474.24, "standardDeviation": 19.533343403424954, "startDate": "2025-10-01", "sum": 293930.72, "comparedToCohorts": [] }, { "beginningValue": 9474.24, "count": 30, "endDate": "2025-11-30", "endingValue": 9487.98, "max": 9487.98, "mean": 9486.148, "median": 9487.98, "min": 9474.24, "standardDeviation": 4.750548716037713, "startDate": "2025-11-01", "sum": 284584.44, "comparedToCohorts": [] }, { "beginningValue": 9487.98, "count": 31, "endDate": "2025-12-31", "endingValue": 9430.66, "max": 9487.98, "mean": 9438.056129032258, "median": 9430.66, "min": 9430.66, "standardDeviation": 19.533343403424954, "startDate": "2025-12-01", "sum": 292579.74, "comparedToCohorts": [] }, { "beginningValue": 9430.66, "count": 31, "endDate": "2026-01-31", "endingValue": 9444.4, "max": 9444.4, "mean": 9442.627096774193, "median": 9444.4, "min": 9430.66, "standardDeviation": 4.682277361532728, "startDate": "2026-01-01", "sum": 292721.44, "comparedToCohorts": [] }, { "beginningValue": 9444.4, "count": 28, "endDate": "2026-02-28", "endingValue": 9387.08, "max": 9444.4, "mean": 9395.26857142857, "median": 9387.08, "min": 9387.08, "standardDeviation": 20.425885848560117, "startDate": "2026-02-01", "sum": 263067.52, "comparedToCohorts": [] }, { "beginningValue": 9387.08, "count": 31, "endDate": "2026-03-31", "endingValue": 9400.82, "max": 9400.82, "mean": 9399.047096774193, "median": 9400.82, "min": 9387.08, "standardDeviation": 4.682277361532728, "startDate": "2026-03-01", "sum": 291370.45999999996, "comparedToCohorts": [] }, { "beginningValue": 9400.82, "count": 30, "endDate": "2026-04-30", "endingValue": 9343.5, "max": 9400.82, "mean": 9351.142666666667, "median": 9343.5, "min": 9343.5, "standardDeviation": 19.818155196745607, "startDate": "2026-04-01", "sum": 280534.28, "comparedToCohorts": [] }, { "beginningValue": 9343.5, "count": 13, "endDate": "2026-05-13", "endingValue": 9357.24, "max": 9357.24, "mean": 9353.012307692308, "median": 9357.24, "min": 9343.5, "standardDeviation": 6.600482499845587, "startDate": "2026-05-01", "sum": 121589.16, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "projectedValues": [] }, { "attributeName": "LIABILITY_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 0.0, "count": 26, "endDate": "2024-06-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-06-05", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-07-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-07-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-08-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-08-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-09-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-09-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-10-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-10-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-11-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-11-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-12-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2024-12-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-01-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-01-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2025-02-28", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-02-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-03-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-03-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-04-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-04-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-05-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-05-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-06-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-06-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-07-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-07-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-08-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-08-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-09-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-09-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-10-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-10-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-11-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-11-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-12-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2025-12-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-01-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-01-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2026-02-28", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-02-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-03-31", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-03-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2026-04-30", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-04-01", "sum": 0.0, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 13, "endDate": "2026-05-13", "endingValue": 0.0, "max": 0.0, "mean": 0.0, "median": 0.0, "min": 0.0, "standardDeviation": 0.0, "startDate": "2026-05-01", "sum": 0.0, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "projectedValues": [] }, { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": -57.32, "count": 26, "endDate": "2024-06-30", "endingValue": 0.0, "max": 0.0, "mean": -2.2046153846153844, "median": 0.0, "min": -57.32, "standardDeviation": 11.241376866120708, "startDate": "2024-06-05", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-07-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2024-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-08-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2024-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-09-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2024-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-10-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2024-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2024-11-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2024-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2024-12-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2024-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-01-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2025-02-28", "endingValue": 0.0, "max": 0.0, "mean": -2.047142857142857, "median": 0.0, "min": -57.32, "standardDeviation": 10.832461796444452, "startDate": "2025-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-03-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-04-30", "endingValue": 0.0, "max": 0.0, "mean": -1.9106666666666667, "median": 0.0, "min": -57.32, "standardDeviation": 10.465152332065374, "startDate": "2025-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-05-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-05-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-06-30", "endingValue": 0.0, "max": 0.0, "mean": -1.9106666666666667, "median": 0.0, "min": -57.32, "standardDeviation": 10.465152332065374, "startDate": "2025-06-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-07-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2025-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-08-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2025-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-09-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2025-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-10-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2025-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2025-11-30", "endingValue": 0.0, "max": 13.74, "mean": 0.458, "median": 0.0, "min": 0.0, "standardDeviation": 2.508569313373661, "startDate": "2025-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2025-12-31", "endingValue": 0.0, "max": 0.0, "mean": -1.8490322580645162, "median": 0.0, "min": -57.32, "standardDeviation": 10.294975912174737, "startDate": "2025-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-01-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2026-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 28, "endDate": "2026-02-28", "endingValue": 0.0, "max": 0.0, "mean": -2.047142857142857, "median": 0.0, "min": -57.32, "standardDeviation": 10.832461796444452, "startDate": "2026-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 31, "endDate": "2026-03-31", "endingValue": 0.0, "max": 13.74, "mean": 0.4432258064516129, "median": 0.0, "min": 0.0, "standardDeviation": 2.4677768498478874, "startDate": "2026-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 30, "endDate": "2026-04-30", "endingValue": 0.0, "max": 0.0, "mean": -1.9106666666666667, "median": 0.0, "min": -57.32, "standardDeviation": 10.465152332065374, "startDate": "2026-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "beginningValue": 0.0, "count": 13, "endDate": "2026-05-13", "endingValue": 0.0, "max": 13.74, "mean": 1.0569230769230769, "median": 0.0, "min": 0.0, "standardDeviation": 3.810790348067324, "startDate": "2026-05-01", "sum": 13.74, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "projectedValues": [] } ], "streams": [ { "cadence": 61, "id": "7da324f5-69eb-4679-9cee-c91c624eab5c", "payee": "PATRICK - LORRAINE PURCHASER", "payor": "crd ach", "recency": 8, "earliestObservedDate": "2024-07-05T06:00:00", "latestObservedDate": "2026-05-05T06:00:00", "count": 12, "sum": 164.88, "status": "active", "min": 13.74, "max": 13.74, "mean": 13.74, "median": 13.74, "standardDeviation": 0.0, "minimumCadence": 59, "maximumCadence": 62, "medianCadence": 61, "modeCadence": 61, "standardDeviationCadence": 0.9820034664301385, "transactionIds": [ "13700605153", "13700605145", "13700605139", "13700605150", "13700605152", "13700605143", "13700605138", "13700605135", "13700605157", "13700605142", "13700605147", "13700605149" ], "attributes": [ "CASH_INFLOW", "ALL_CASH_FLOWS" ] }, { "cadence": 61, "id": "e980319e-5aad-47d4-8d12-5443c1f59def", "payee": "credit card payment", "payor": "PATRICK - LORRAINE PURCHASER", "recency": 38, "earliestObservedDate": "2024-06-05T06:00:00", "latestObservedDate": "2026-04-05T06:00:00", "count": 12, "sum": -687.84, "status": "active", "min": -57.32, "max": -57.32, "mean": -57.32, "median": -57.32, "standardDeviation": 0.0, "minimumCadence": 59, "maximumCadence": 62, "medianCadence": 61, "modeCadence": 61, "standardDeviationCadence": 0.9648821040663343, "transactionIds": [ "13700605155", "13700605146", "13700605140", "13700605136", "13700605151", "13700605154", "13700605141", "13700605137", "13700605134", "13700605156", "13700605144", "13700605148" ], "attributes": [ "CASH_OUTFLOW", "ALL_CASH_FLOWS" ] } ], "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2024-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-06-05", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-06-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "e980319e-5aad-47d4-8d12-5443c1f59def" ], "transactionIds": [ "13700605154", "13700605146", "13700605144", "13700605136", "13700605137", "13700605151", "13700605141", "13700605148", "13700605134", "13700605155", "13700605156", "13700605140" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-05-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-05-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-05-13", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-05-01", "sum": 13.74, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "CASH_INFLOW", "streamIds": [ "7da324f5-69eb-4679-9cee-c91c624eab5c" ], "transactionIds": [ "13700605145", "13700605143", "13700605135", "13700605138", "13700605153", "13700605152", "13700605142", "13700605149", "13700605150", "13700605139", "13700605157", "13700605147" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2024-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-06-05", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2024-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2024-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2024-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-05-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-05-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-06-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-06-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-07-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-07-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-08-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-08-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-09-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-09-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-10-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-10-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-11-30", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2025-11-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2025-12-31", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2025-12-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-01-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-01-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-02-28", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-02-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-03-31", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-03-01", "sum": 13.74, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-04-30", "max": -57.32, "mean": -57.32, "median": -57.32, "min": -57.32, "startDate": "2026-04-01", "sum": -57.32, "comparedToCohorts": [] }, { "count": 1, "endDate": "2026-05-13", "max": 13.74, "mean": 13.74, "median": 13.74, "min": 13.74, "startDate": "2026-05-01", "sum": 13.74, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "ALL_CASH_FLOWS", "streamIds": [ "7da324f5-69eb-4679-9cee-c91c624eab5c", "e980319e-5aad-47d4-8d12-5443c1f59def" ], "transactionIds": [ "13700605137", "13700605153", "13700605142", "13700605157", "13700605134", "13700605156", "13700605145", "13700605144", "13700605152", "13700605148", "13700605143", "13700605154", "13700605136", "13700605135", "13700605138", "13700605151", "13700605141", "13700605155", "13700605147", "13700605140", "13700605146", "13700605149", "13700605150", "13700605139" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "REVENUE", "streamIds": [], "transactionIds": [], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "NSF_FEE_CHARGES", "streamIds": [], "transactionIds": [], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-05", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-07-31", "startDate": "2024-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-08-31", "startDate": "2024-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-09-30", "startDate": "2024-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-10-31", "startDate": "2024-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-11-30", "startDate": "2024-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2024-12-31", "startDate": "2024-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-01-31", "startDate": "2025-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-02-28", "startDate": "2025-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-03-31", "startDate": "2025-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-04-30", "startDate": "2025-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-05-31", "startDate": "2025-05-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-06-30", "startDate": "2025-06-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-07-31", "startDate": "2025-07-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-08-31", "startDate": "2025-08-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-09-30", "startDate": "2025-09-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-10-31", "startDate": "2025-10-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-11-30", "startDate": "2025-11-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2025-12-31", "startDate": "2025-12-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-01-31", "startDate": "2026-01-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-02-28", "startDate": "2026-02-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-03-31", "startDate": "2026-03-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-04-30", "startDate": "2026-04-01", "comparedToCohorts": [] }, { "count": 0, "endDate": "2026-05-13", "startDate": "2026-05-01", "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [] } ], "attributeName": "NSF_FEE_REVERSALS", "streamIds": [], "transactionIds": [], "projectedValues": [], "streamConfidences": null } ] }, "gseEnabled": true } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a Cash Flow Analytics report: [Cash_Flow_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Cash_Flow_Analytics_HTR.pdf) (4MB) ## Reading a Cash Flow Analytics JSON Report {#reading-a-cash-flow-analytics-json-report} This section provides a detailed description of the structure and format of the JSON version of Cash Flow Analytics. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. ### Cashflow Analytics Attributes {#cashflow-analytics-attributes} The above sample demonstrates some, if not all, Cashflow Analytics attributes from the following table:
| Attribute | Definition | Type | |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | REVENUE | An identification of all transactions that are classified as business revenue. This is not applicable for personal cashflow report. | Transactional | | NSF_FEE_CHARGES | Fees charged to the customer, by their financial institution - resulting from a lack of sufficient funds or low balance to cover a purchase. | Transactional | | NSF_FEE_REVERSALS | Credit transaction of an NSF fee charged earlier. | Transactional | | CASH_INFLOW | Credit transactions in a customer's account | Transactional | | CASH_OUTFLOW | Debit/Spend transactions in a customer's account | Transactional | | ALL_CASH_FLOWS | This is an umbrella attribute which sums: - CASH_INFLOW - CASH_OUTFLOW | Transactional | | NET_CASH_FLOW | Total Credits less Total Debits over a period of time and across all accounts owned by an individual or business. Calculation of net cash flow into or out of a customer's account(s). | State | | | | | #### Time Interval Types {#time-interval-types} A report supports up to two time interval types currently. If you request more than two interval types, the endpoint returns an error `More than 2 intervalTypes passed request`. If the time interval type is not specified, the default is `MONTHLY_CALENDAR`. The following table shows all possible time interval types you can request a report for: | Time Interval Type | Description | First (Earliest) period may be partial | First (Most Recent) period may be partial | Shortest possible period length | Longest possible period length | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------| | DAILY | The report will be broken up into one period for every calendar date in the report time period | NO | NO | 1 | 1 | | WEEKLY_CALENDAR | The report time period will be broken up into periods of 7 calendar dates, each beginning on Monday and ending on Sunday, except the first and last periods which may be partial | YES | YES | 1 | 7 | | WEEKLY_ROLLING_7 | The report time period will be broken up into periods of 7 calendar dates, counting backwards from the report end date | YES | NO | 1 | 7 | | BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, each beginning on a Monday and ending on the 2nd subsequent Sunday, except the first and last periods which may be partial | YES | YES | 1 | 14 | | BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date | YES | NO | 1 | 14 | | SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly 2 periods per calendar month, where both the first and last period may be partial, and periods will alternate between representing the 1st-15th and the 16th-end of the month | YES | YES | 1 | 16 | | MONTHLY_CALENDAR | The report time period will be broken up into 1 period per calendar month | YES | YES | 1 | 31 | | MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by 1 period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 36 | | QUARTERLY_CALENDAR | The report time period will be broken up into 1 period per 3 calendar months, where both the first and last period may be partial | YES | YES | 1 | 92 | | QUARTERLY_ROLLING_90 | The report time period will be broken up into 3 periods of 90 calendar dates followed by 1 period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 96 | | ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date | YES | NO | 1 | 366 | | HISTORICALLY | The report time period will be represented by exactly 1 period covering the duration of report data | NO | NO | 1 | Duration of report data | The following JSON snippet shows an example of how time interval type is requested: * Json ```json { "analyticsReportData": { "timeIntervalTypes": [ "MONTHLY_CALENDAR", "ANNUALLY" ] } } ``` ### JSON Report Structure - Analytics Section {#json-report-structure---analytics-section} Analytics will be provided at both the account level, grouped by (financial) institution, and at an aggregated customer level, similar to how most other Lend and OBB products work today. The following examples show a customer with two accounts that contain transactions. * Json ```json "accounts": [ { "id": 1065737689 }, { "id": 1065737690 } ] ``` The analytics section is divided into 3 sections: 1. Transactional attributes 2. State attributes 3. Streams #### Account-Level Analytics Structure {#account-level-analytics-structure} * Json ```json "analytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ``` Note: This section will be for each of the customer accounts. #### Customer-Level Analytics Structure {#customer-level-analytics-structure} * Json ```json "customerAnalytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ``` ### Transactional Attributes {#transactional-attributes} Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. As an example, an attribute called DWELLING_EXPENSES may be a classification of all transactions that we assume to be a customer paying towards a mortgage, rent, home insurance, etc. Transactional attributes will be reported by one of the below time interval type specified in the constraints by the requesting partner. The following JSON snippets are for transactional attributes on accounts and customer level. Please note the following: 1. For demonstration purposes, the below snippets show transaction data of 1 month for MONTHLY_CALENDAR time interval type. The actual report will have all transaction stats for all the months. 2. The period array for ANNUALLY will show aggregated data for all the months between the specified start and end dates. 3. Not all attributes are showcased. Please access the attribute table above to see all the Cashflow Analytics attributes. 4. The data in the below snippets are for *Cashflow_Analytics* report which is attached above.
* Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": -12.11, "mean": -12.21, "median": -12.21, "min": -12.31, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": -24.42, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 18, "endDate": "2024-06-23", "max": -1.2, "mean": -6.9911111111111115, "median": -7.140000000000001, "min": -12.31, "standardDeviation": 3.617743672656446, "startDate": "2023-06-24", "sum": -125.84, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "ae6bec67-e1a0-4ff4-8220-8439398a373e" ], "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": 12.21, "mean": 12.11, "median": 12.11, "min": 12.01, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": 24.22, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 19, "endDate": "2024-06-23", "max": 12.21, "mean": 6.6352631578947365, "median": 6.24, "min": 1.1, "standardDeviation": 3.5608962174353, "startDate": "2023-06-24", "sum": 126.07, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_INFLOW", "streamIds": [ "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4" ], "transactionIds": [ "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 4, "endDate": "2023-12-31", "max": 12.21, "mean": -0.04999999999999982, "median": -0.04999999999999982, "min": -12.31, "standardDeviation": 14.041633333293769, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 37, "endDate": "2024-06-23", "max": 12.21, "mean": 0.006216216216216155, "median": 1.1, "min": -12.31, "standardDeviation": 7.75851587731949, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "ALL_CASH_FLOWS", "streamIds": [ "ae6bec67-e1a0-4ff4-8220-8439398a373e", "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4" ], "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829", "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ], "projectedValues": [], "streamConfidences": null } ] ``` * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": -12.11, "mean": -12.21, "median": -12.21, "min": -12.31, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": -24.42, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 18, "endDate": "2024-06-23", "max": -1.2, "mean": -6.9911111111111115, "median": -7.140000000000001, "min": -12.31, "standardDeviation": 3.617743672656446, "startDate": "2023-06-24", "sum": -125.84, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "9ef16f42-baa9-47ba-a936-564ce19fb9ee" ], "transactionIds": [ "128512270962", "128512270955", "128512270954", "128512270956", "128512268805", "128512270976", "128512270940", "128512270960", "128512268803", "128512268800", "128512268799", "128512270943", "128512270942", "128512270938", "128512268808", "128512268807", "128512268793", "128512270953" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": 12.21, "mean": 12.11, "median": 12.11, "min": 12.01, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": 24.22, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 19, "endDate": "2024-06-23", "max": 12.21, "mean": 6.6352631578947365, "median": 6.24, "min": 1.1, "standardDeviation": 3.5608962174353, "startDate": "2023-06-24", "sum": 126.07, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_INFLOW", "streamIds": [ "2efb4258-4457-4391-8f40-4bfd973af49a" ], "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 4, "endDate": "2023-12-31", "max": 12.21, "mean": -0.04999999999999982, "median": -0.04999999999999982, "min": -12.31, "standardDeviation": 14.041633333293769, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 37, "endDate": "2024-06-23", "max": 12.21, "mean": 0.006216216216216155, "median": 1.1, "min": -12.31, "standardDeviation": 7.75851587731949, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "ALL_CASH_FLOWS", "streamIds": [ "9ef16f42-baa9-47ba-a936-564ce19fb9ee", "2efb4258-4457-4391-8f40-4bfd973af49a" ], "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ], "projectedValues": [], "streamConfidences": null } ] ``` ##### JSON Fields Description {#json-fields-description} | Key (Datatype) | Description | Applicable for Cashflow Analytics | |-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------| | **aggregatedByTimePeriods** (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes | | **periods** (object) | Statistics of aggregated transactions over some time period. | Yes | | **count** (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes | | **endDate** (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes | | **max** (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes | | **mean** (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for monthly time interval, mean will be shown for each month of a year. | Yes | | **median** (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for monthly time interval, median will be shown for each month of a year. | Yes | | **min** (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for monthly time interval, min will be shown for each month of a year. | Yes | | **standardDeviation** (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for monthly time interval, standardDeviation will be shown for each month of a year. | Yes | | **startDate** (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for monthly time interval, startDate will be shown for each month of a year. | Yes | | **sum** (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for monthly time interval, sum will be shown for each month of a year. | Yes | | **comparedToCohorts** (object) | An array of elements comparing the customer's spending during a time period to the average customer's spending in various cohorts, such as postal code, during the same time period. | No | | **cohortType** (string) | Describes the type of cohort being compared to for this period, e.g. POSTAL_CODE | No | | **totalDifferenceToCohort** (number) | Reflects the difference between the customer's spending for the period minus that of the average spending in this cohort. | No | | **percentageDifferenceToCohort** (number) | Reflects the percentage difference between the customer's sum value for the period and the average of the cohort | No | | **timeIntervalType** (string) | See *Time Interval Types* above for how each period is defined. | Yes | | **cohortBenchmarkPeriods** (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the spending of cohorts in the customer's zip code during that period for an attribute. | Yes | | **startDate** (string) | The first day of the cohort benchmark period. | Yes | | **endDate** (string) | The final day of the cohort benchmark period. | Yes | | **cohortValues** (object) | An object that contains type and value of a cohort benchmark period. | No | | **cohortType** (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, e.g. POSTAL_CODE. | No | | **value** (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | No | | **attributeName** (string) | Name of the attribute that we are reporting the numbers for. Refer to the attributes list above. | Yes | | **streamIds** | List of stream IDs associated with the attribute. See more details about "Streams" below | Yes | | **transactionIds** (object) | List of transaction IDs associated with the attribute. | Yes | | **projectedValues** (object) | List of projection objects, where each object indicates the projected sum value of the attribute over some coming period of time. | No | | **timeUnit** (string) | The unit of time being described, e.g. MONTHS | No | | **timeValue** (number) | The number of timeUnit units for which we are projecting, e.g. 12 (for 12 months) | No | | **projectionValue** (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | No | | **streamConfidences** (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | No | | **streamId** (string) | The stream ID we are reporting the confidence for. | No | | **confidence** (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an income attribute | No | ### State Attributes {#state-attributes} The unit of data for state attributes is some generic "state" at a point in time. Whereas transactional attributes are based on specific events (the posting of a transaction), state attributes make some inference about a point in time based on some assembly of underlying data. Examples of state attributes might include something like the balance of an account over time, a calculation based on underlying transactions in a time period (e.g. net cash flow), or some other calculation such as a debt to income ratio. The following JSON snippets for transactional attributes on accounts and customer level. Please note the following: 1. For demonstration purposes, the below snippets show transaction data of 1 month for MONTHLY_CALENDAR time interval type. The actual report will have all transaction stats for all the months. 2. The period array for ANNUALLY will show aggregated data for all the months between the specified start and end dates. 3. The data in the below snippets are for *Cashflow_Analytics* report which is attached above.
* Json ```json "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 12.01, "count": 31, "endDate": "2023-12-31", "endingValue": -12.31, "max": 12.21, "mean": -0.006451612903225784, "median": 0.0, "min": -12.31, "standardDeviation": 4.44038703147004, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 6.24, "count": 366, "endDate": "2024-06-23", "endingValue": 0.0, "max": 12.21, "mean": 0.000628415300546442, "median": 0.0, "min": -12.31, "standardDeviation": 2.436596410931794, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 12.01, "count": 31, "endDate": "2023-12-31", "endingValue": -12.31, "max": 12.21, "mean": -0.006451612903225784, "median": 0.0, "min": -12.31, "standardDeviation": 4.44038703147004, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 6.24, "count": 366, "endDate": "2024-06-23", "endingValue": 0.0, "max": 12.21, "mean": 0.000628415300546442, "median": 0.0, "min": -12.31, "standardDeviation": 2.436596410931794, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 24.02, "count": 31, "endDate": "2023-12-31", "endingValue": -24.62, "max": 24.42, "mean": -0.012903225806451568, "median": 0.0, "min": -24.62, "standardDeviation": 8.88077406294008, "startDate": "2023-12-01", "sum": -0.3999999999999986, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 12.48, "count": 366, "endDate": "2024-06-23", "endingValue": 0.0, "max": 24.42, "mean": 0.001256830601092884, "median": 0.0, "min": -24.62, "standardDeviation": 4.873192821863588, "startDate": "2023-06-24", "sum": 0.4599999999999955, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` #### JSON Fields Description {#json-fields-description-1} While most of the keys overlap with transactional attributes, the following are state attributes-specific keys: | Key (Datatype) | Description | |------------------------------------|------------------------------------------------------------------------| | **reportedByTimePeriods** (object) | Value of the "state" over some time periods | | **beginningValue** (number) | Value of the "state" as reported on the `startDate` of the period | | **endingValue** (number) | Value of the "state" as reported on the `endDate` of the period | | **count** (number) | Occurrences of the "state" between specified `startDate` and `endDate` | ### Streams {#streams} Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between two parties (or accounts, if the same entity owns both the source and destination of funds). Examples of streams include: bi-weekly paychecks from an employer to an employee, a customer's monthly phone bill paid to a telecom provider, a customer's monthly transfer from a checking account to an investment account, etc. Since a stream is just a group of transactions, a transactional attribute can assign a list of streams to itself if the transactions in that stream all fit the same classification being described by the attribute. * Json ```json "streams": [ { "cadence": 20, "id": "ae6bec67-e1a0-4ff4-8220-8439398a373e", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829" ] }, { "cadence": 20, "id": "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "9ef16f42-baa9-47ba-a936-564ce19fb9ee", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270962", "128512270955", "128512270954", "128512270956", "128512268805", "128512270976", "128512270940", "128512270960", "128512268803", "128512268800", "128512268799", "128512270943", "128512270942", "128512270938", "128512268808", "128512268807", "128512268793", "128512270953" ] }, { "cadence": 20, "id": "2efb4258-4457-4391-8f40-4bfd973af49a", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "ae6bec67-e1a0-4ff4-8220-8439398a373e", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829" ] }, { "cadence": 20, "id": "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ] }, { "cadence": 20, "id": "9ef16f42-baa9-47ba-a936-564ce19fb9ee", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270962", "128512270955", "128512270954", "128512270956", "128512268805", "128512270976", "128512270940", "128512270960", "128512268803", "128512268800", "128512268799", "128512270943", "128512270942", "128512270938", "128512268808", "128512268807", "128512268793", "128512270953" ] }, { "cadence": 20, "id": "2efb4258-4457-4391-8f40-4bfd973af49a", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ] } ] ```
#### JSON Fields Description {#json-fields-description-2} While most of the keys overlap with transactional attributes, the following are stream attributes-specific keys: | Key (Datatype) | Description | |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | **cadence** (number) | The average number of days elapsed between consecutive transactions in the stream | | **id** (string) | A randomly generated UUID to uniquely identify the stream | | **payee** (string) | The party that is receiving the funds | | **payor** (string) | The party that is sending the funds | | **recency** (number) | The number of days elapsed since the most recent transaction in the stream | | **earliestObservedDate** (string) | The date-time of the first observed transaction in the stream | | **latestObservedDate** (string) | The date-time of the last observed transaction in the stream | | **status** (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence | | **minimumCadence** (number) | The smallest observed duration of time elapsed between any 2 consecutive transactions in the stream | | **maximumCadence** (number) | The largest observed duration of time elapsed between any 2 consecutive transactions in the stream | | **medianCadence** (number) | The median number of days elapsed between consecutive transactions in the stream | | **modeCadence** (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream | | **standardDeviationCadence** (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream | | **transactionIds** (object) | A list of all the transaction IDs that were assigned to the stream | ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # TxPUSH source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md TxPUSH is an alternative to pulling aggregated account and transaction data daily in order to stay up to date. TxPUSH automatically sends update notifications to an event listener, so a client can be PUSHed the most up to date information when it is available, and skip PULLing when there are no changes. Note: The TxPUSH service is not compatible with [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) (ASD, AFD, and ATD). ## How It Works {#how-it-works} TxPUSH services allow an app to register a TxPUSH Listener service to receive notifications whenever there are updates to account or transaction data for a specific customer's account. ### Subscribe to TxPUSH Notifications {#subscribe-to-txpush-notifications} API Reference: `POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush` ### Disable TxPUSH Notification {#disable-txpush-notification} API Reference: `DELETE /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush` ### Delete TxPUSH Subscription {#delete-txpush-subscription} API Reference: `DELETE /aggregation/v1/customers/{customerId}/subscriptions/{subscriptionId}` ### Create TxPUSH Test Transaction {#create-txpush-test-transaction} API Reference: `POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions` ### Subscription Record {#subscription-record} TxPUSH subscription details: | Name | Description | |------------------------|-----------------------------------------------------------| | id (Required) | (Long) Unique subscription identifier. | | accountId (Required) | (Long) The Finicity account ID for the subscription. | | type (Required) | (String) Event subscription type. account or transaction. | | callbackUrl (Required) | (String) The url for the events. | | signingKey (Required) | (String) Signing key for events. | ## Setting Up the TxPUSH Listener Service {#setting-up-the-txpush-listener-service} An account must already be added to the Mastercard platform via [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) before a TxPUSH subscription can be set up. To begin receiving TxPUSH notifications, the TxPUSH Listener needs to be set up. You will need to define a public RESTful web service that is accessible from the Mastercard platform. Using the Subscribe to TxPUSH Notifications endpoint, enter a URL that will be used as the TxPUSH Listener URL, where notifications will be sent. The URL can use the standard HTTP protocol (port 80) for test accounts, but must use the secure HTTPS protocol (port 443) for any real-world accounts. This arrangement is to facilitate testing, by requiring SSL configuration only when moving into Production. The use of other ports will result in the call failing. Notifications can be sent in either JSON or XML format. To set up notifications in JSON, list application/json in the Accept field of the header; to set up notifications in XML, list application/xml in the Accept field of the header. After the subscription request has been sent, Mastercard will respond with a GET call to the listener with a URL parameter that includes a txpush_verification_code. Respond with an HTTP 200, header Content-Type: text/plain, and a response body containing the txpush_verification_code in plain text in the body of the response. Finally, Mastercard will respond again with an HTTP 200 and an ID, which can be treated as a confirmation code, and a signingKey, which can be used as a key to validate the txpush-signature of future notifications. This is a one-time event to verify an active TxPUSH Listener URL. The txpush_verification_code and ID are not needed in any subsequent requests. For example, if the callback URL `https://callback.example.com/txpush` is used, Mastercard will respond: `GET https://callback.example.com/txpush?txpush_verification_code=CODE`. The TxPUSH Listener should respond with an HTTP code 200, header Content-Type: text/plain, and a response body containing the verification code value (copied from the request parameter) in plain text. If a txpush_verification_code is not sent in the first HTTP 200 response, or the txpush_verification_code is incorrect, Mastercard will respond with a 60000 code indicating the txpush_verification_code is invalid, and the subscription request will be rejected. To validate a successful set up, the Create TxPush Test Transaction endpoint can be used to set up a test transaction on a test account to trigger a TxPUSH notification. ## TxPUSH Webhook Notification {#txpush-webhook-notification} Partners must create a listener endpoint to receive the TxPUSH Webhook Notification. You can download the specification for the notification events: [txpush-webhooks-us.yaml](https://static.developer.mastercard.com/content/open-finance-us/swagger/txpush-webhooks-us.yaml) (12KB) When an event is received, the listener must return HTTP 200 (OK) to acknowledge the message. If an event is not acknowledged promptly, Mastercard will resend the notice every 30 minutes for up to six hours. If the notification is not acknowledged within six hours, the notification service on that event will be canceled. Instead, the event can be retrieved through an account aggregation or transaction aggregation API call. TxPUSH notifications can be cancelled by using the [Disable TxPUSH Notifications endpoint](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md#disable-txpush-notification). This will stop all future account data or transaction events from being sent to the TxPUSH Listener URL for the specified account. TxPUSH notifications may be set-up again for the specified account by following the Setting Up the TxPUSH Listener Service steps above. Note: TxPUSH notifications are sent from the IP address 68.142.128.67. To ensure the arrival of notifications, add this address to your allow-list for inbound traffic. Allow-listing is an alternative option to verifying the txpush-signature by blocking all other traffic. When setting up more than one TxPUSH subscription, different URLs are not needed for each account. They can be the same, different, or a combination; however, subscription set-up must be completed for each account. TxPUSH varies from Webhook technology as webhooks will have an expected response, such as a report that has been requested. TxPUSH works on aggregation, where there may or may not be an update, depending on financial institution and customer actions. One use of TxPUSH is to determine when the first aggregation has been completed on an account. Clients may consider the following flow to enable this solution: * Customer adds an account in Connect * Call **Get Customer Account** * Subscribe to TxPUSH Notifications * Call **Refresh Customer Accounts**
TxPUSH will send both an account and transaction event with the data, so clients can skip additional calls to the Account Aggregation and Transaction Aggregation endpoints on the first aggregation. In addition, TxPUSH reduces your development time by allowing you to keep your data up to-date without the development work required with a traditional batch process. ## Understanding TxPUSH Notifications {#understanding-txpush-notifications} TxPUSH runs constantly, and a notification will automatically be sent out to the TxPUSH Listener URL when there is an update (called event) to either account or transaction data for a specific customer's account. These updates are batched, so there may be a slight delay between Mastercard receiving the update, and a TxPUSH notification being sent out. Notifications are sent as HTTP POST requests to the TxPUSH Listener URL in the format determined during setup. Warning: If you are caching transaction data, we recommend that you use the `uniqueTransactionId` instead of the simple transaction ID when querying the cached data. This avoids any potential problems caused by the same transaction ID being used with more than one customer. If you are not able to use the unique ID (for example if you have data cached from before the unique ID was introduced in Q1 2026), ensure you use the transaction ID along with an `accountId` or `customerId` when querying the cached data. This avoids any potential problems caused by the same transaction ID being used with more than one customer. There are two classes of events the Listener can receive, account data events and transaction events. The account data events and transaction events include the following event types: MODIFIED, DELETED, and CREATED. ### Event Classes {#event-classes} This table describes each event type and their significance for both event categories. | Types of Event | Account Data | Transaction Data | |----------------|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MODIFIED | This event indicates one of the 6 monitored fields has been updated. | This event indicates a [transaction status](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/understanding-transaction-data/index.md#transaction-status) has changed. Refer to the Transaction Events table for status combinations. | | DELETED | This event indicates an account has been deleted. | This type of event will **never be sent** for this category. | | CREATED | This type of event will **never be sent** for this category. | This event indicates there is a new pending or active transaction record. | #### Transaction Events {#transaction-events} This table describes how the transaction status changes based on transaction events. | Event Type | Condition/Trigger | Status | |------------|------------------------------------------------------------------------------------------------------------------------|-----------| | Created | New active transaction is created | `active` | | Created | New pending transaction is created | `pending` | | Modified | Transaction is updated from pending/shadow to active | `active` | | Modified | Transaction is updated from active to shadow (when it is not found on a subsequent refresh for the same date range) | `shadow` | | Modified | Transaction is updated from pending to inactive (when it is not found on a subsequent refresh for the same date range) | `deleted` | ## Sample Notifications {#sample-notifications} ### Account Modified {#account-modified} The following example shows how a typical message body might look for an account modified event: * JSON * XML ```JSON { "event": { "class": "account", "type": "modified", "source": "Connect Fix", "records": [ { "id": "2055", "number": ">XXXX-XXXXXX-32765", "name": "Checking", "balance": 964.23, "type": "checking", "aggregationStatusCode": 0, "status": "active", "customerId": "41442", "institutionId": "101732", "balanceDate": 1444768982, "aggregationSuccessDate": 1444768982, "aggregationAttemptDate": 1444768982, "createdDate": 1422395818, "lastUpdatedDate": 1444768982 } ] } } ``` ```XML account modified Connect Fix 2055 >XXXX-XXXXXX-32765 Checking 964.23 checking 0 active 41442 101732 1444768982 1444768982 1444768982 1422395818 1444768982 ``` ### Account Deleted {#account-deleted} The following example shows how a typical message body might look for an account delete event: * JSON * XML ```JSON { "event": { "class": "account", "type": "deleted", "source": "Connect Fix", "records": [ { "id": "2055", "number": ">XXXX-XXXXXX-32765", "name": "Checking", "balance": 964.23, "type": "checking", "aggregationStatusCode": 0, "status": "deleted", "customerId": "41442", "institutionId": "101732", "balanceDate": 1444768982, "aggregationSuccessDate": 1444768982, "aggregationAttemptDate": 1444768982, "createdDate": 1422395818, "lastUpdatedDate": 1444768982 } ] } } ``` ```XML account deleted Connect Fix 2055 >XXXX-XXXXXX-32765 Checking 964.23 checking 0 deleted 41442 101732 1444768982 1444768982 1444768982 1422395818 1444768982 ``` ### Transaction Created {#transaction-created} The following example shows how a typical message body might look for a new pending transaction record: * JSON * XML ```JSON { "event": { "class": "transaction", "type": "modified", "records": [ { "id": 7158760954, "amount": -42.18, "accountId": 7001630128, "customerId": 7000224872, "status": "created", "description": "WALMART SUPERCENTER #2153 MEW YORK NY", "uniqueTransactionId": "7158760954-7001630128", "memo": "Debit", "interestAmount": 0, "principalAmount": 0, "escrowAmount": 0, "postedDate": 1738411200, "transactionDate": 1738411200, "createdDate": 1738440763, "lastUpdatedDate": 1738558241, "categorization": { "normalizedPayeeName": "Walmart", "category": "Shopping", "score": 1, "bestRepresentation": "WALMART SUPERCENTER MEW YORK NY DEBIT", "country": "USA", "entityStandardizationConfidenceScore": 96.7 } } ] } } ``` ```XML transaction modified 7158760954 -42.18 7001630128 7000224872 created WALMART SUPERCENTER #2153 MEW YORK NY 7158760954-7001630128 Debit 0 0 0 1738411200 1738411200 1738440763 1738558241 Walmart Shopping 1 WALMART SUPERCENTER MEW YORK NY DEBIT USA 96.7 ``` ### Transaction Modified {#transaction-modified} The following example shows how a typical message body might look for a transaction status change event: * JSON * XML ```JSON { "event": { "class": "transaction", "type": "modified", "records": [ { "id": 7158760954, "amount": -27.43, "accountId": 7001630128, "customerId": 7000224872, "status": "modified", "description": "STARBUCKS STORE 01452 OGDEN UT", "uniqueTransactionId": "7158760954-7001630128", "memo": "DEBIT", "interestAmount": 0, "principalAmount": 0, "escrowAmount": 0, "postedDate": 1738411200, "transactionDate": 1738411200, "createdDate": 1738440763, "lastUpdatedDate": 1738558241, "categorization": { "normalizedPayeeName": "Starbucks", "category": "Coffee Shops", "score": 1, "bestRepresentation": "STARBUCKS OGDEN UT DEBIT", "country": "USA", "entityStandardizationConfidenceScore": 97.8 } } ] } } ``` ```XML transaction modified 7158760954 -27.43 7001630128 7000224872 modified STARBUCKS STORE 01452 OGDEN UT 7158760954-7001630128 DEBIT 0 0 0 1738411200 1738411200 1738440763 1738558241 Starbucks Coffee Shops 1 STARBUCKS OGDEN UT DEBIT USA 97.8 ``` ### Transaction Deleted {#transaction-deleted} The following example shows how a typical message body might look when a transaction status has changed to shadow: * JSON * XML ```JSON { "event": { "class": "transaction", "type": "modified", "records": [ { "id": 7158760954, "amount": -54.27, "accountId": 7001630128, "customerId": 7000224872, "status": "deleted", "description": "TRADER JOE'S #0123 HARTFORD CT", "uniqueTransactionId": "7158760954-7001630128", "memo": "DEBIT", "interestAmount": 0, "principalAmount": 0, "escrowAmount": 0, "postedDate": 1771934700, "transactionDate": 1771877880, "createdDate": 1771877910, "lastUpdatedDate": 1771934700, "categorization": { "normalizedPayeeName": "Trader Joe's", "category": "Groceries", "score": 1, "bestRepresentation": "TRADER JOES HARTFORD CT DEBIT", "country": "USA", "entityStandardizationConfidenceScore": 93.2 } } ] } } ``` ```XML transaction modified 7158760954 -54.27 7001630128 7000224872 deleted TRADER JOE'S #0123 HARTFORD CT 7158760954-7001630128 DEBIT 0 0 0 1771934700 1771877880 1771877910 1771934700 Trader Joe's Groceries 1 TRADER JOES HARTFORD CT DEBIT USA 93.2 ``` There are specific fields monitored for TxPUSH notifications. If data in one of these fields changes, a notification will be sent. Data can change in a non-monitored field during refresh, and a TxPUSH notification will not be sent. Due to this, Mastercard recommends a bi-weekly reconciliation of account and transaction data to ensure uniformity between Mastercard's data and a Client's data. If there ever is an instance of a missing TxPUSH event, please submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) for troubleshooting. | Data | Fields Monitored for TxPUSH Notifications | |--------------|------------------------------------------------------------------------| | Account data | accountNumber, nickname, aggrNickname, balance, status, aggrStatusCode | | Transactions | status | Clients may opt-in to receiving TxPUSH notifications whenever the `aggregationSuccessDate` is updated, indicating a successful refresh and new data may be available outside of the monitored fields. Reach out to your Client Success Manager if you wish to opt-in. ## Validating a txpush-signature {#validating-a-txpush-signature} All events contain a txpush-signature to validate the authenticity of the update. If the txpush-signature does not match the expected result, submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) for assistance. Use the following steps to validate the txpush-signature: 1. Base64 encode the event message's Body (request body). 2. Create a new empty string, known here as the signing string. 3. Append the text "content-type". 4. Append the value of the Content-Type header for the HTTP request (all lower-case). This will depend on the output format that you are using (JSON or XML). For example: `content-typeapplication/json` or `content-typeapplication/xml`. 5. Append the text "host". 6. Append the value of the host from the Header from the HTTP request (all lower-case). 7. Append the Base64-encoded string from step 1 to the end of the signing string. 8. Using HMAC SHA256, create a signature in Base64 format. For this algorithm, the "secret key" is the signingKey from the [Subscribe to TxPush Notifications](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/index.md#subscribe-to-txpush-notifications) API, and the "value" is the signing string. 9. UrlEncode the resulting Base64 value. 10. Compare the result to the txpush-signature. If the values are the same, the notification is authentic. If the values are not the same, submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm). ### Example {#example} This example shows how to perform these verification steps with the following event message and signing key. The following shows the header of an event sent to your call back / listener service as XML: ```curl POST https://domain.example.com/txpush/listener Content-Type: application/xml Host: domain.example.com x-txpush-signature: Mtbdwo1ZCsmDrcvBkVa8K5LzY9KBPYQ7S44TQdcDLIw%3D ``` The Event Message Body (request body) for this might look similar to the following (this is an XML message for an Account event): ```XML modified account 2055 ... ``` signingKey (given during set-up): `1234567890` #### Verification Steps {#verification-steps} * **Step 1:** Base64 encode the event message body (request body): `PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8ZXZlbnQ+CiAgPHR5cGU+bW9kaWZpZWQ8L3R5cGU+CiAgPGNsYXNzPmFjY291bnQ8L2NsYXNzPgogIDxyZWNvcmRzPgogICAgPGFjY291bnQ+CiAgICAgIDxpZD4yMDU1PC9pZD4KICAgICAgLi4uCiAgICA8L2FjY291bnQ+CiAgPC9yZWNvcmRzPgo8L2V2ZW50Pg==` * **Steps 2 to 6**: Create the signing string: `content-typeapplication/xmlhostdomain.example.com` * **Step 7**: Combine the signing string and the Base64 encoded event message body: `content-typeapplication/xmlhostdomain.example.comPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8ZXZlbnQ+CiAgPHR5cGU+bW9kaWZpZWQ8L3R5cGU+CiAgPGNsYXNzPmFjY291bnQ8L2NsYXNzPgogIDxyZWNvcmRzPgogICAgPGFjY291bnQ+CiAgICAgIDxpZD4yMDU1PC9pZD4KICAgICAgLi4uCiAgICA8L2FjY291bnQ+CiAgPC9yZWNvcmRzPgo8L2V2ZW50Pg==` * **Step 8**: Create a signature in Base64 format using HMAC SHA256: `Mtbdwo1ZCsmDrcvBkVa8K5LzY9KBPYQ7S44TQdcDLIw=` * **Step 9**: URL encode the Base64 signature: `Mtbdwo1ZCsmDrcvBkVa8K5LzY9KBPYQ7S44TQdcDLIw%3D` * **Step 10**: Compare the Base64 encoded signature to the txpush-signature: The signatures match, so the notification is authentic. --- # Data Connect Fix Experience source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/recall-experience-connect-fix/index.md **Data Connect Fix** is a feature within Mastercard Data Connect that enables end users to seamlessly restore access to accounts that are disconnected or "broken." When a connection issue occurs---often token revocation and/or expiration, due to password changes, multi-factor authentication updates, or other technical interruptions---partners can prompt end users to securely re-enter Data Connect to re-establish the link. Most accounts refresh automatically on a nightly basis, but occasional disruptions can occur. **Benefits of Data Connect Fix for customers:** * **Faster Resolution:** Quickly repair broken connections without waiting for manual support intervention. * **Improved continuity:** Minimize gaps in aggregated data by restoring access promptly. * **Better User Experience:** Provide a secure, guided process to fix accounts, reducing confusion and support requests. ## When Is Data Connect Fix Used? {#when-is-data-connect-fix-used} Data Connect Fix should be implemented whenever an account experiences an aggregation error that can be resolved by the end user. Specifically, when the account returns a ["fixable" error code](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#using-data-connect-fix) when using Data Connect Fix. These codes indicate issues, such as expired credentials or additional authentication requirements that the user can resolve by re-entering Data Connect. Note: Connect Fix should not be used for errors outside of these fixable codes (for example, institution downtime or unsupported account types), as end-user action will not resolve these conditions. **When integrating Data Connect Fix, partners should evaluate:** * **Triggering criteria:** Determine which ["fixable" error codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#using-data-connect-fix) align with your product flow and when to prompt users through a recall experience. * **User experience (UX) goals:** Provide proactive notifications (for example, through SMS, email, or in-app messaging) versus passive prompts within your interface. * **Implementation model:** Decide how to integrate Connect Fix (for example, standalone fix experience versus integrated into existing Connect flows). ## How Is Data Connect Fix Enabled? {#how-is-data-connect-fix-enabled} There are two primary ways to enable Data Connect Fix depending on whether you use **Mastercard Data Connect Full** or **Mastercard Data Connect Lite** and how much control you need over the user experience (UX). ### Option 1: Embed in the Standard Data Connect Flow {#option-1-embed-in-the-standard-data-connect-flow} For partners using Mastercard Data Connect Full, Data Connect Fix is enabled by default as part of the standard Data Connect experience. In this model, when an account encounters a ["fixable" error](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#using-data-connect-fix), users are automatically prompted to repair the connection during their normal Connect session. No additional development work is required. | Pros | Considerations | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | * Requires no additional development work. * Simplifies implementation by leveraging built-in functionality within Data Connect Full. * Provides a familiar and consistent experience for users already interacting with Data Connect. | * Users may need to complete 1--2 extra clicks to access and resolve broken accounts. * Limited flexibility to customize the Data Connect Fix workflow beyond what Data Connect natively provides. | ### Option 2: Use the Data Connect Fix Endpoint {#option-2-use-the-data-connect-fix-endpoint} Mastercard Data Connect Lite partners must use the [Generate Data Connect Fix URL endpoint](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md) since the embedded Data Connect Fix workflow is not available in Data Connect Lite. Full partners may also choose this method if they need greater control over how and when users are prompted to fix broken accounts. | Pros | Considerations | |----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | * Directs users straight to the broken accounts offering a faster, more focused repair experience. | * Requires additional development effort to integrate with the Data Connect Fix API endpoint. * Partners must implement logic to identify ["fixable" error codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md#using-data-connect-fix) and trigger the Data Connect Fix flow only when applicable. | ### Decision Tree: Which Approach Should You Use? {#decision-tree-which-approach-should-you-use} ![Decision tree](https://static.developer.mastercard.com/content/open-finance-us/uploads/decision-tree.png) ## Data Connect Fix User Experience Flow {#data-connect-fix-user-experience-flow} For the best viewing experience of app to app, click the **full screen mode** option or **zoom** using the controls located on the right. ## What Causes an Account Connection to Break? {#what-causes-an-account-connection-to-break} Broken account connections occur when Data Connect can no longer successfully aggregate data from a financial institution. These disruptions typically map to "fixable" error codes (as detailed in the [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) documentation) and can usually be resolved through user action through Data Connect Fix. Understanding these causes enables partners to design proactive notifications, minimize user friction, and improve overall data continuity. **There are four main reasons for an account connection to break:** 1. **Authentication and credential-related issues** * **Credential changes** Customers who update their login credentials (for example, password or username) at their financial institution must re-enter Data Connect to restore access. * **MFA expirations** Multi-Factor Authentication (MFA) prompts can expire if not completed in time, leading to a failed connection that requires re-authentication. * **MFA-enforced challenges** Some institutions enforce MFA at scheduled intervals (for example, every 30 or 90 days) or trigger MFA dynamically, based on risk (for example, logging in from a new device or location). If the user does not complete these challenges, the connection breaks. * **MFA high-risk actions** MFA may be required for specific high-risk actions (such as initiating large transfers or modifying sensitive account details), and failure to complete such actions disrupts access. 2. **Session and token expiry issues** * **OAuth token expiration** OAuth tokens provided by financial institutions have defined lifespans. When these tokens expire, users must re-authenticate to regain access and re-authorize data sharing. 3. **Account and consent change issues** * **Consent revocation** Users can withdraw consent at any time through their financial institution, which immediately terminates aggregator access until renewed by the user. 4. **Institution-level changes and technical disruption issues** * **Financial Institution (FI) API or system Updates** FIs may deploy updates (for example, API schema changes, new security protocols) that temporarily disrupt aggregator connectivity until integrations are updated. * **FI connectivity losses or downtime** Outages or temporary connectivity failures at the FI can also cause account aggregation to fail. * **Fixable versus non-fixable causes** Not every broken connection can be resolved using Connect Fix. * **Typically fixable:** Credential updates, expired MFA or token challenges, and periodic or risk-based MFA requirements * **Typically non-fixable:** FI downtime or outages, permanent account closures, and consent revocations (until renewed by the user)
Refer to the [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) page to confirm which specific error codes qualify for Data Connect Fix. ### Best Practice {#best-practice} * Proactively alert users when their connection breaks and provide a **direct entry point to Connect Fix** (for example, through in-app notification or email). Sending an alert reduces confusion, shortens resolution time, and improves customer satisfaction by guiding them to the fixable issue. See the Figma file of the [Data Connect Fix user experience flow](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/recall-experience-connect-fix/index.md#data-connect-fix-user-experience-flow) above for greater detail. * Developers and product owners should review the Data Connect Fix technical documentation, which provides detailed guidance on the web hooks and APIs required for implementation. Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Accessibility Guidelines](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/accessibility-guidelines/index.md) --- # Data Connect Components UX Guidelines source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md This page outlines both requirements and best practices when using Mastercard Data Connect Components: * [UX requirements](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md#ux-requirements) -- There are some requirements that must be met, such as making Mastercard's role clear to end users, and presenting the terms and conditions. * [UX Best practices](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md#ux-best-practices) -- Recommended approaches which are not mandatory but which we regard as being best practice where possible. These are explained below. ## UX Requirements {#ux-requirements} The following requirements *must* be adhered to: 1. Mastercard's role must be clearly stated to the end user. 2. Mastercard's Terms and Privacy Notice must be presented to, and accepted by, the end user. 3. Mastercard's brand must be represented appropriately. 4. The user's login credentials must not touch a Partner's servers.
The following illustrations detail the specifics of what each of these 4 requirements entail. The UX images are meant to demonstrate the requirements, and are illustrative only. The boxes on the right are the specific requirements that must be adhered to. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components_ux_requirements_1_june2025.png) ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components_ux_requirements_2_june2025.png) ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components_ux_requirements_3_june2025.png) ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/components_ux_requirements_4_june2025.png) ## UX Best Practices {#ux-best-practices} The following embedded Figma files illustrate recommended user journeys for legacy and OAuth (direct) connections. For the best viewing experience of the UX journey, click the **full screen mode** option or **zoom** using the controls located on the right.


--- # Account Owner Verification source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md Retrieves account ownership details (name, address, email and phone - where available) from a connected account at a financial institution. This is a premium endpoint - each successful call to this API results in a billable event. With Account Owner Verification, you can: 1. Retrieve [account ownership details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---get-account-owner-details), including full name (required), address, email and phone. Optionally, you can send customer data to our [match account ownership details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) endpoint to receive confidence scores comparing the provided data and the account ownership details provided by a financial institution. This product provides everything you need to verify ownership of an account before originating a payment or funds transfer. 2. Return [identity insights](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta) based on the user's session and device data and powered by Mastercard's Identity Network. This product is available through either the Get Account Owner Details or the Match Account Owner Details endpoint. Note that this functionality is currently in beta and will incur additional cost. Aside from verifying account ownership, this product provides signals to validate that the user adding the account is likely the owner of that connected external account. ##### Account Opening Program for Mastercard Issuers {#content} Issuers can opt into the Open Finance for Account Opening Program to secure and streamline the digital account opening process for Mastercard consumer and small business debit cards and general-purpose reloadable Mastercard consumer prepaid products. Participating Issuers will have access to Mastercard Open Finance's Account Owner Verification (one-time request), Account Detail Verification (one-time request) and Account Balance Check (up to 60 days) solutions, providing confidence in who their customers are, reducing content abandonment and inactivity, and decreasing non-sufficient fund (NSF) returns.
Under the program, these Open Finance services are provided as a free core benefit to Mastercard issuers when they are used to support digital account opening of an eligible Mastercard account.
Issuers who wish to participate in the Open Finance for Account Opening Program must sign an enrollment form. Download the form [here](https://w201.mastercardconnect.com/gcccic001/homememb/library/shared/Forms_Library/Forms/doc/0322.docx). Reach out to your support representative for more information. ## How It Works {#how-it-works} 1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) in the Quick Start Guide. 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) in the Quick Start Guide. 3. Create a customer and link them to at least one account. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) in the Quick Start Guide (you will need to connect a checking and savings account using "Finbank" with the username and password "demo_rtn2"). 4. Call [Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---get-account-owner-details) with a `customerId` and `accountId` to return the account ownership information; or call [Match Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) with a `customerId` and `accountId` and any values you wish to be matched (name, address, email and phone) to return the account ownership information and matching confidence scores. Diagram account-owner
### Account Owner Data {#account-owner-data} Many Financial Institutions (FI) include more detailed information about the account owner than just their name and address. The following data objects are available if they are provided by an FI that allow you to accurately identify the individual that you are doing business with and make informed business decisions: * Account holders * Addresses * Email addresses * Phone numbers * Documentations (not currently in use) Note: The Account Owner endpoints will always include at least one `holder` containing `ownerName` and `nameClassification`. The remaining fields are optional and dependent upon the financial institution providing the data. This includes, among others: `ownerAddress` (and corresponding structured data elements), `email` (with type and primary designation) `phone` (with type), and account holder `relationship`. At present, the `documentation` data object is not currently in use in any region. The data provided in testing environments is only for illustrative purposes. ### Name Classification {#name-classification} The Name Classification service is built on state-of-the-art machine learning technology that provides detailed data about the account holder, which can help you make informed business decisions. The service classifies the data into one of the following `nameClassification` categories: * Person * Business * Other
The `nameClassificationConfidenceScore` value provides a confidence score between 0.0 and 1.0, indicating the certainty of the accuracy of the `nameClassification` value. While you can determine your own ranges, we recommend grouping scores according to the following ranges: | 0 - 59 | 60 - 89 | 90 - 100 | |---------------|------------------|----------------| | LowConfidence | MediumConfidence | HighConfidence | Another way to interpret these scoring brackets is as follows: * 0.9 - 1.0: High confidence. * 0.6 - 0.89: Medium confidence. * 0.0 - 0.59: Low confidence. Additional verification is needed (we recommend verifying other data).
### Recommendations {#recommendations} When verifying ownership of a financial account the following best practices are recommended: * **Name** : Only `ownerName` is required for a successful account owner response and will be included by all data providers that support this product. Many providers also provide the name value broken down to individual fields; we recommend validating the individual name fields such as `firstName` and `lastName`, and then falling back to the `ownerName` value in the event other fields are unavailable. * **Address** : While `ownerAddress` is provided by a majority of data providers, it is not required for a successful account owner response. Many providers also provide the address value broken down to individual fields; if you choose to evaluate an account owner's address, we recommend validating the individual address fields such as `line1`, `city` and `postalCode`, and then falling back to the `ownerAddress` value in the event other fields are unavailable as well as accounting for a null address response. * **Phone** : If provided, the `phone` number could be supplied with or without formatting, depending on the data provider. If creating a rule against this optional value, we recommend accounting for the following variations: ##########, ###-###-####, +##########, ###-###-#####, ###########, +# (###) ###-####, (###) ###-#### * **Email** : If provided, the `email` address should follow the standard format of \[username\]@\[domain name\].\[top-level domain\] such as "[username@example.com](mailto:username@example.com)". If you create a rule against this optional value, we recommend validating the format matches the standard email format. * **Documentations** : While provided in the FDX specification and within our Sandbox environment, these data elements are not currently supplied by any data providers in production. *At this time, we do not recommend creating rules against any of the fields provided in the `documentations` section.* Keeping the above information in mind, review the various endpoints below to determine which features you need to verify account ownership, match ownership data to your platform, or gain further identity insights on your users. ## API - Get Account Owner Details {#api---get-account-owner-details} The latest version of our account owner product includes a response that is broken out into individually structured [data objects](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#account-owner-data) identifying account holders by their name, addresses, phone numbers and emails - when provided by a connected financial institution. The response also includes a [Name Classification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#name-classification) designation that determines the "nameClassification" (person, business, etc.) for any account holders identified for the connected account. API Reference: `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/owner` ### Testing {#testing} We have made multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#testing-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, contact your solution engineer. A sample Get Account Owner v3 request and response is shown below: curl -X GET \ --url 'https://api.finicity.com/aggregation/v3/customers/{customerId}/accounts/{accountId}/owner' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' The response will require that `ownerName` and `nameClassification` be provided at minimum. The availability of other data elements (address, email, phone, etc.) are dependent upon institution: ```JSON { "holders":[ { "relationship":"AUTHORIZED_USER", "ownerName":"John Smith, PhD", "firstName":"John", "middleName":"L", "lastName":"Smith", "suffix":"PhD", "nameClassification":"person", "nameClassificationconfidencescore":0.9, "addresses":[ { "ownerAddress":"434 W Ascension Way Suite #200 Murray UT 84123", "type":"Home", "line1":"434 W Ascension Way", "line2":"Suite #200", "line3":"UT 84123", "city":"Murray", "state":"UT", "postalCode":"84123", "country":"USA" } ], "emails":[ { "isPrimary":true, "email":"myname@example.com", "emailType":"Personal" } ], "phones":[ { "type":"HOME", "country":"US", "phone":"1-801-984-4200" } ] } ] } ``` ## API - Match Account Owner Details {#api---match-account-owner-details} This endpoint returns a confidence score indicating how closely the customer-provided owner data (name, address, email, and phone) matches the information retrieved from their connected financial institution during the Know Your Customer (KYC) process. To use this endpoint, you must collect the customer's data in advance and include it in the POST request (name is a required element of the request, while providing address, email and phone is optional). Note that the response contains the institution-sourced account owner data as well as the matching confidence scores. API Reference: `POST /account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}` In addition we've added the ability to request optional [identity insights](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#identity-insights-beta) for a customer through this endpoint. That product includes a set of real-time identity signals assessing how account owner's information align with the user's session and device data. Note that this functionality is currently in beta and will incur additional cost. ### Testing {#testing-1} We have made multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#testing-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your solution engineer. A sample Match Account Owner Details request and response is shown below: curl --location 'https://api.finicity.com/account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "name": { "firstName": "John", "lastName": "Smith" }, "address": { "line1": "101 Test Street", "line2": "Apt 101A", "city": "New York City", "state": "NY", "country": "USA", "postalCode": "12345", "type": "Home" }, "phone": "1002221234", "email": "test@mastercard.com" }' The output will be similar to the base account owner, with the addition of confidence scores for each element both provided in the request and retrieved from the institution: ```JSON { "holders":[ { "relationship":"PRIMARY", "ownerName":"John Smith", "firstName":"John", "middleName":"K", "lastName":"Smith", "nameClassification":"person", "nameClassificationconfidencescore":1.0, "nameScores": { "ownerName": 100, "firstName": 100, "lastName": 100 }, "addresses":[ { "ownerAddress":"101 Test Street #1A New York City NY 12345", "type":"Home", "line1":"101 Test Street", "line2":"#101A", "line3":"UT 84123", "city":"New York City", "state":"NY", "postalCode":"12345", "country":"USA", "addressScores": { "ownerAddress": 100, "type": 100, "line1": 100, "line2": 100, "city": 100, "state": 100, "postalCode": 100, "country": 100 } } ], "emails":[ { "isPrimary":true, "email":"myname@example.com", "emailType":"Personal", "emailScores": { "email": 100 } } ], "phones":[ { "type":"HOME", "country":"US", "phone":"1-100-222-1234", "phoneScores": { "phone": 100 } } ] } ] } ``` ### Scoring Process {#scoring-process} We use a combination of string character comparison logic and a machine learning model to determine if the values provided in the request match with those provided by the customer's financial institution. We also have incorporated logic to verify against common abbreviations and designators (w : west, ave : avenue, NY : New York, apt : unit, etc.) to increase matching confidence. A score will be produced for each value provided in the request, granted that the same data element is provided by the financial institution. Note: The score produced for `ownerName` is generated based on the name values provided in the request (`firstName`, `lastName`, etc.) as compared to the `ownerName` provided by the financial institution. The score produced for `ownerAddress` is generated based on the address values provided in the request (`line1`, `line2`, `city`, etc.) as compared to the `ownerAddress` provided by the financial institution or structured fields, when available. ### Score Interpretation {#score-interpretation} Matching results are provided on a scale from 0 to 100, with a higher score indicating a higher likelihood that a match exists. The best practice would be to refer to the most specific scores as a primary check (giving preference to "firstName" and "lastName" scores over the "ownerName" score as well as "line1", "city", "postalCode", etc. scores over the "ownerAddress" score) but allowing a check to fall back on the overall score if specific values are unavailable. Scores are provided at a granular level, allowing you to set acceptance levels based on your own risk tolerance. We recommend interpreting the scores values in buckets of pass (Match), fail (NoMatch) or needs review (PossibleMatch) as follows: | Scores | 0 - 59 | 60 - 69 | 70 - 89 | 90 - 99 | 100 | |-------------|---------|---------|---------------|---------|-------| | **Name** | NoMatch | NoMatch | PossibleMatch | Match | Match | | **Address** | NoMatch | NoMatch | PossibleMatch | Match | Match | | **Phone** | NoMatch | N/A | N/A | N/A | Match | | **Email** | NoMatch | N/A | N/A | N/A | Match | Another way to interpret these scoring brackets is as follows: * 100 = Excellent, Match (the values match exactly) * 90 - 99 = Good, Match (the values match closely, but have some minor difference) * 70 - 89 = Satisfactory, Match Possible (the values are similar, but may require more review) * 60 - 69 = Mixed, Not a Match (the results are mixed, and less likely to be a match) * 0 - 59 = Irrelevant, Not a Match (few similarities, not a match) ### Recommendations {#recommendations-1} #### Name Matching {#name-matching} When matching against account owner information, only the name value (`firstName` \& `lastName`) is required in the request. Based on the values included, we provide individual scores for each field returned by the financial institution (i.e. a `firstName` score and so on); additionally, an `ownerName` score is provided based on the combined name values provided in the request (`firstName` + `middleName` + `lastName` + `suffix`) matched against the `ownerName` provided in the response. Direct users to provide their legal name to increase matching confidence against a financial institution-provided name. We recommend only sending `firstName` and `lastName` in the request, while excluding `middleName` \& `suffix`. The rate at which `middleName` and `suffix` are provided (fill rate) is not consistent among all institutions, and may decrease the matching score for `ownerName`. When reviewing scores in the response, first attempt to validate the `firstName` and `lastName` scores and then fall back to the `ownerName` score if not provided or when validating an organization name. ##### Sample Request: Person Name Example {#sample-request-person-name-example} "name": { "firstName": "John", "lastName": "Smith" } ##### Sample Request: Business Name Example {#sample-request-business-name-example} "name": { "ownerName": "Circus City Inc" } #### Address Matching {#address-matching} If you provide an address for matching, ensure you include all address fields (`line1`, `line2`, `city`, `state`, `postalCode`, `country`) that are applicable to the user. In the response, matching scores will be returned for each individual field provided by the institution as well as against the full `ownerAddress` string (where available). Note that `ownerAddress` and individual address fields are optional in the response, and is subject to availability. If you wish to provide this value for matching, direct your users to provide their billing or mailing address to increase matching confidence against a financial institution-provided address. When reviewing scores in the response, first attempt to validate the `line1`, `city` and `postalCode` scores (optionally, you may include the `line2` and `state` values in this) and then fall back to the `ownerAddress` score if the individual scores are not provided. Generally speaking, the `line3` value can be ignored as it is most often a reflection of the `city`, `state` and `postalCode` that will likely have been provided or can be inferred. ##### Sample Request: Example Address 1 {#sample-request-example-address-1} "address": { "line1": "101 Test Street", "line2": "Apt 101A", "city": "New York City", "state": "NY", "country": "USA", "postalCode": "12345", "type": "Home" } ##### Sample Request: Example Address 2 {#sample-request-example-address-2} "address": { "line1": "102 Test Street", "city": "New York City", "state": "NY", "country": "United States", "postalCode": "123456789", "type": "Home" } #### Phone \& Email Matching {#phone--email-matching} Direct users to provide the primary mobile phone number or email address used for communication from their financial institution to increase matching confidence against a financial institution-provided `phone` or `email` value. ##### Sample Request: Example Phone \& Email {#sample-request-example-phone--email} "phone": "1002221234", "email": "test@mastercard.com"
## Identity Insights (Beta) {#identity-insights-beta} Additional insight into an account holder's identity and behaviors is available through the Get Account Owner Details and Match Account Owner Details endpoints. Note that requesting identity insights will incur an additional cost - please contact your sales representative/account manager to learn more. For Financial Institutions especially, the balance between consumer friction and fraud detection is even more acute when assessing thin-file or under-banked consumers. Risk-averse banks often treat applications as fraudulent until proven otherwise to protect against growing identity fraud, leading to poor user experiences that may drive good consumers to competitors. With additional identity insights and predictive signals, it is possible to balance customer acquisition goals while combating fraud. These identity insights enable real-time risk assessments without disrupting potential customers. Unlike other account opening solutions, we provide dynamic data sources --- including account ownership details, device intelligence, individual attributes (PII), and predictive signals and scores --- in a single API response to enable businesses to optimize their onboarding decisioning. These insights are provided in partnership with [Ekata Inc., a Mastercard company](https://developer.mastercard.com/identity-insights-for-accounts/documentation/). Ekata is a leader in identity validation and fraud prevention. Leveraging their capabilities, the Account Owner endpoint can provide insights about your customer's identity that can enhance your fraud protection and decisioning. Key features of identity insights data are: * **Account Owner Details** --- Personal information (name, email, address, phone), directly sourced from the account holder's financial institution. * **Individual Attributes** --- High-quality licensed data from global providers to access the validity of individual attributes and how they are linked together. * **Device Intelligence** --- Real time signals to assess device authenticity, spoofed settings, or association with past fraud across our device network. * **Predictive Signals and Scores** --- Network and model-derived predictions to assess the potential risk of an application and inform onboarding decisions and rules. Note: Identity insights are only available from a selection of Financial Institutions, including those which have an [OAuth connection](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md) or have otherwise been optimized through our Fast AO process to collect the owner's phone and email address. Requesting identity insights will incur an additional cost. Contact your Sales representative/Account Manager to learn more. ### Testing {#testing-2} We have made multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#testing-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your solution engineer. To request Identity Insights you need to include the `?withInsights=true` parameter in the request URI. Diagram ekata-account-owner A sample request to include identity insights is shown below: ### Get Account Owner Details {#get-account-owner-details} curl -X GET \ --url 'https://api.finicity.com/aggregation/v3/customers/{customerId}/accounts/{accountId}/owner?withInsights=true \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' ### Match Account Owner Details {#match-account-owner-details} curl --location 'https://api.finicity.com/account-owner-verification-matchings/customers/{customerId}/accounts/{accountId}?insights=true' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: {{appToken}}' \ --data-raw '{ "name": { "firstName": "Test", "lastName": "Customer" }, "address": { "line1": "101 Test Street", "line2": "Apt 101A", "city": "New York City", "state": "NY", "country": "USA", "postalCode": "12345", "type": "Home" }, "phone": "1002221234", "email": "test@mastercard.com" }' The output will be similar to the base account owner or account owner match response, with the addition of one or more optional `identityInsights` data elements as provided below: Warning: At present, the data elements in the `device` section are currently being redesigned. New device scores and signals will replace these values in late 2025. Contact your Sales representative/Account Manager for more information. ```JSON { "holders": [ { ... "identityInsights": { "requestRefId": "be3ad617-04ad-43e1-a438-79425b6511b6", "isEmailValid": true, "emailFirstSeenDays": 453, "emailDomainCreationDate": "2011-06-29T00:00:00.000Z", "emailToName": "not found", "ipRisk": true, "ipRiskScore": 0.123, "ipLastSeenDays": 15, "ipGeolocationCountryCode": "US", "ipGeolocationSubdivision": "Oregon", "ipPhoneDistance": 200, "ipAddressDistance": 210, "isPhoneValid": true, "phoneLineType": "mobile", "phoneCarrier": "Vodafone UK ltd.", "phoneCountryCode": "UK", "phoneLastSeenDays": 42, "phoneEmailFirstSeenDays": 54, "phoneToName": "match", "phoneToAddress": "match", "addressValidityLevel": "valid", "addressToName": "match", "emailRisk": 0.8, "identityRiskScore": 275, "identityRiskReasonCode": "AA", "deviceRiskScore": 0.45, "deviceType": "iPhone", "deviceBrowser": "Mobile Safari", "devicePlatform": "iOS", "devicePhoneEmailFirstSeen": 140, "deviceBrowserIpTzDifference": 1000, "deviceIpEmailFirstSeen": 365, }, "warnings": [ "Test warnings" ], "alerts": [ "Unable to generate IP and user insights" ] } } ] } ``` ### Recommendations {#recommendations-2} The purpose of these rule recommendations is to help you use Account Owner data and Identity Insights within the appropriate workflows to meet your business objectives, such as mitigating potential fraud or increasing approvals for low risk users. We hope these recommendations make it easier for you to get started, but we ask you to keep in mind that they are only meant to serve as a guiding light. As you begin to see data returned from the use of these signals, we suggest assessing which signals are most useful as predictors of risk and adjusting any rules to derive as much value as possible. Rather than implementing a ruleset from the start, it may be beneficial to begin ingesting the insight signals and evaluating which values are most predictive for your particular application. Consultation services are available in a limited capacity - contact your support representative for more information. #### Guidelines {#guidelines} We recommend trying combinations of criteria from different rows within the same target column to create your rules. A few things to note: * Italicized rules tend to be the most predictive in identifying high risk users, however, we still suggest adjusting them according to your population for the greatest impact. * We recommend trying combinations of rules from different rows to see which signals are most predictive for your use case. * Rules in the same row (High Risk, Moderate, Low Risk) should not be used together --- pick one column and select a few signals to monitor from that ruleset. * Combine with AND to get higher precision (more restrictive). Combine with OR to get higher recall (more approvals). * Ultimately, adjust thresholds as you see fit - these are just guidelines. | Signals | Stop High-Risk Rule | Moderate Rule | Pass Low-Risk Rule | |----------------------------------|------------------------|----------------------|--------------------| | **Scores** | | | | | *Identity Risk Score* | \> 400 | \> 450 | \< 150 | | *IP Risk Score* | \> 0.9 | \> 0.95 | \< 0.3 | | *Email Risk Score* | \> 0.9 | \> 0.95 | \< 0.3 | | *Device Risk Score* | \> 0.9 | \> 0.95 | \< 0.3 | | **Phone Checks** | | | | | Is Phone Valid | = False | -- | = True | | *Phone Line Type* | != mobile | = non-fixed-voip | = mobile | | Phone Last Seen | \< 30 or \> 365 days | \< 10 or \> 730 days | -- | | Phone/Email First Seen | \< 30 days | = 0 days | \> 365 days | | *Phone to Name* | != match | = no-match | = match | | *Phone to Address* | country match/no-match | no-match | match | | **IP Checks** | | | | | *IP Distance from Address* | \> 100 miles | \> 1000 miles | \< 50 miles | | *IP Distance from Phone* | \> 100 miles | \> 1000 miles | \< 50 miles | | IP Last Seen | \< 30 or \> 365 | \< 10 or \> 730 | -- | | **Email Checks** | | | | | Email Domain Creation Date | within past year | today | \> 5 years | | *Email First Seen* | \< 30 days | = 0 days | \> 365 days | | Email to Name | != match | = no-match | = match | | **Address Checks** | | | | | *Address Validity Level* | != valid | = invalid | = valid | | Address to Name | != match | = no-match | = match | | **Device Checks** | | | | | Device Email \& Phone First Seen | \< 30 days | = 0 days | \> 60 days | | *Device Email \& IP First Seen* | \< 30 days | = 0 days | \> 60 days | | *Browser IP Timezone Difference* | \> 0 | \> 0 | = 0 | #### Moderate Rule Example: {#moderate-rule-example} If you're formulating a rule to stop fraud with high precision, look at the criteria within the "Moderate Rule" column. Combine the bolded high-performing criteria first with an "AND" operator, then evaluate how many records in your transaction population meet this threshold. Then, assess whether the rule needs to be more restrictive by adding more AND criteria --- or less restrictive, by removing criteria.
##### Sample High-Risk Rule: {#sample-high-risk-rule} IF: (Identity Risk Score > 450) AND (Identity Network Score > 0.95) AND (Phone Match to Name = No Match) THEN: [Add additional verification step] OR [Reduce transfer limit] OR [Reject user action]
## Testing Profiles {#testing-profiles} In addition to the test data provided below, we have multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#account-opening-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your implementation specialist. The test profile holder information has been formatted as if it was a request for the Match Account Owner endpoint: Username \& Password: profile_7000 Holder 1: ```JSON { "name": { "firstName": "Homer", "lastName": "Loanseeker" }, "address": { "line1": "434 W Ascension Way", "line2": "#200", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123", "type": "Home" }, "phone": "9999999998", "email": "finicitycss@gmail.com" } ``` Username \& Password: profile_7002 Holder 1: ```JSON { "name": { "firstName": "Homer", "lastName": "Loanseeker" }, "address": { "line1": "434 W Ascension Way", "line2": "#200", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123", "type": "Home" }, "phone": "9999999998", "email": "finicitycss@gmail.com" } ``` Holder 2: ```JSON { "name": { "firstName": "Lorraine", "lastName": "Loanseeker" }, "address": { "line1": "434 W Ascension Way", "line2": "#200", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123", "type": "Home" }, "phone": "9999999998", "email": "finicitycss@gmail.com" } ``` Username \& Password: profile_1766 Holder 1: ```JSON { "name": { "firstName": "CIRCUS CITY", "lastName": "INCORPORATED" }, "address": { "line1": "123 Test Avenue", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123", "type": "Business" } } ``` Username \& Password: profile_1765 Holder 1: ```JSON { "name": { "firstName": "More", "lastName": "Mechanics", "suffix": "LLC" }, "address": { "line1": "123 Test Avenue", "city": "Murray", "state": "UT", "country": "US", "postalCode": "84123", "type": "Work" }, "phone": "8015555555", "email": "test@test.com" } ``` Holder 2: ```JSON { "name": { "firstName": "Jimbo", "lastName": "Macintosh" }, "address": { "line1": "456 Imagination Lane", "city": "Salt Lake City", "state": "UT", "country": "US", "postalCode": "84000", "type": "Home" }, "phone": "8015555555", "email": "test@test.com" } ``` Username \& Password: profile_02 Holder 1: ```JSON { "name": { "firstName": "HOMER", "lastName": "LOANSEEKER" }, "address": { "line1": "123 FAKE STREET", "city": "OGDEN", "state": "UT", "country": "US", "postalCode": "84401", "type": "Home" } } ``` Username \& Password: profile_03 Holder 1 \& 2: ```JSON { "name": { "firstName": "PATRICK", "middleName": "LORRAINE", "lastName": "PURCHASER" }, "address": { "line1": "7195 BELMONT ST.", "city": "PARLIN", "state": "NJ", "country": "US", "postalCode": "08859", "type": "Home" } } ``` Note: If there are multiple holders on a legacy connection (not enabled for OAuth), the names may be provided together as a single holder. In this case, the ownerName is returned as "PATRICK \& LORRAINE PURCHASER". Presently, only a single owner can be sent to be matched per request Username \& Password: profile_05 Holder 1 \& 2: ```JSON { "name": { "firstName": "JOHN", "lastName": "HOMEOWNER" }, "address": { "line1": "123 Test ST.", "city": "SPRINGFIELD", "state": "VA", "country": "US", "postalCode": "221621058", "type": "Home" } } ``` Note: If there are multiple holders on a legacy connection (not enabled for OAuth), the names may be provided together as a single holder. In this test case, the ownerName is returned as "JOHN HOMEOWNER MARY HOMEOWNER". Presently, only a single owner can be sent to be matched per request. ## Common Errors {#common-errors} In the event that we encounter an issue at any point while requesting Account Owner Verification, you will be informed by a response containing the error `code` and corresponding `message` explaining the issue and any possible resolution steps. While some commonly encountered errors are listed below, be sure to refer to our [Error Code](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) documentation page for an exhaustive list of potential errors and click on the link to review documentation for a specific code. | Code | HTTP Status | Brief Description | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------| | [102](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#102) | 500 | We're unable to establish a connection to your financial institution. | | [103](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidcredentials/index.md#103) | 500 | Invalid login credentials. | | [106](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#106) | 500 | User action required at financial institution. | | [170](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#168-170-178-180-and-184) | 500 | An error occurred in the financial institution connection. | | [185](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/incompleteauth/938-940-971-185-187/index.md#185) | 500 | Missing or incorrect MFA answer. | | [197](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#168-170-178-180-and-184) | 500 | An error occurred in the financial institution connection. | | [265](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#265) | 500 | Owner information not available. | | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/325/index.md) | 500 | The account is currently being aggregated. | | [910](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-interrupt/existing-connection-interruptions/index.md#910) | 500 | Financial institution connection is currently broken and currently being worked on. | | [946](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#946)​ | 500 | The token has been accepted but no record has been returned from the institution for the request. This may be due to account closure. | | [947](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/invalidtoken/947-2024/index.md#947) | 500 | Your token is invalid or has expired, Please re-authenticate. | | [960](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#960) | 500 | Electronic Statement is not available for the requested account. | | [961](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/addinfo/106-108-109-961-959/index.md#961) | 500 | Enrollment Required for Paperless Statement/Activate Electronic Statement. | | [973](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#973) | 500 | The user is not authorized for the requested resource or online access. | | [975](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/connection-not-supported/index.md#975) | 500 | Bank has blocked access to resources for the user concerning security reasons. | | [982](https://developer.mastercard.com/open-finance-us/documentation/errors/institutionerrors/other-connection-issues/index.md#979-980-982-and-983) | 500 | An error occurred in the financial institution connection. | | [13002](https://developer.mastercard.com/open-finance-us/documentation/errors/request/item-not-found/index.md#13002) | 404 | The Statement asset for this account was not found. | | [19000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/unexpected-system-issue/index.md#19000) | 500 | The Account Owner Verification service experienced an internal error. | | [38003](https://developer.mastercard.com/open-finance-us/documentation/errors/accounterrors/account-not-found/909-913-914-946-952/index.md#38003) | 404 | The customer does not have the given account. This may be due to the account being deleted.​ | | [44000](https://developer.mastercard.com/open-finance-us/documentation/errors/request/max-limit-exceeded/index.md#44000) | 202 | Invalid App key. | ## Fast AOV {#fast-aov} Fast AOV is an optimized Account Owner Verification solution that enables faster responses to [Get Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---get-account-owner-details) or [Match Account Owner Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md#api---match-account-owner-details) requests. It works by caching the required data on our server for up to 4 days for faster retrieval. In many cases, it also provides richer ownership data, such as an owner's email address and phone number. When Fast AOV is enabled, we proactively fetch the account owner details during the account linking process. This reduces latency and helps prevent some data aggregation errors. Fast AOV is offered at no additional charge. By default, we enable Fast AOV when you create a new production project and you are using account owner verification services. Fast AOV may not be right for all projects and is not supported by all institutions. Speak with your Account Manager about enabling or opting out of Fast AOV. Enabling the service for your project can take 2 to 5 business days. The following sequence diagram shows how Fast AOV proactively caches routing data during the account linking process: Diagram account-owner-cached ### Financial Data Exchange (FDX) {#financial-data-exchange-fdx} The [Financial Data Exchange (FDX)](https://financialdataexchange.org/) is dedicated to unifying standards for secure and convenient access to user-permissioned financial data sharing throughout the financial services industry. The Get Account Owner v3 API is aligned with the [FDX API 5.0 standards](https://www.financialdataexchange.org/FDX/FDX/News/Press-Releases/Financial_Data_Exchange_Releases_FDX_API_5.0.aspx). FDX is currently working with more than 30 different working groups and task forces involved in defining standards and improving increased access and performance. ### Get Account Owner v1 (To Be Deprecated in 2026) {#get-account-owner-v1-to-be-deprecated-in-2026} This is a historical version of the Get Account Owner endpoint; new features and enhancements are being added to the v3 endpoint (Get Account Owner Details). The Get Account Owner v1 endpoint retrieves only the names and address for a customer's account from a financial institution. The `ownerName` and `ownerAddress` parameters are returned with multiple values present within the same, pipe-delimited response object. A sample Get Account Owner v1.0 response: ```JSON { "ownerName": "John Smith | Jane Smith", "ownerAddress": "APT C 5600 S SPRINGFIELD GARDENS CIR SPRINGFIELD, VA 22162-1058" } ``` API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/owner` --- # App to App Authentication Toolkit source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/app-to-app-auth-best-practices/index.md App to App authentication is a feature that enables mobile users to permission access to their data by signing in with their financial institution's (FI's) mobile app if downloaded on the device they are using. The customer can sign in using the applicable biometric login features for the FI. If the app is not downloaded, the customer is directed to log in through the FI's website in a browser window. ## Why Is App to App Important? {#why-is-app-to-app-important} App to App Authentication can help increase the success rates of customers by directing them to their bank app to log in and authenticate their data. This reduces friction in the experience by enabling customers to log in as they typically do, thereby reducing dropout. **In two surveys conducted by the Open Finance Mastercard research team, we discovered:** * more than 70% of participants primarily use a mobile phone to access and manage their primary checking account daily or every 2-3 days. * more than 80% of participants prefer to be (or are comfortable with being) directed to their bank app to log in to their account. ## What Does App to App Authentication Look Like for an End User? {#what-does-app-to-app-authentication-look-like-for-an-end-user} The following Figma diagram shows the user flow from the data recipient (the partner app), via the data access platform (Mastercard Data Connect), to the data provider (the chosen FI's banking app), and back. For the best viewing experience of app to app, click the **full screen** option or **zoom** using the controls located on the right.
The following sequence diagram shows the interaction between the Partner application which is using Mastercard Open Finance, Mastercard, the mobile OS, and the FI application (banking app) and FI server. The Partner application is also known as the Data Recipient (they are authenticating so their users can obtain their banking data) and the Financial Institution (bank) is also known as the Data Provider. Diagram app-to-app For the app to app flow to work, both the partner's app and the Financial Institution's app will need to implement Universal links (iOS) or App Links (Android). The following sections give advice on how to configure universal links/app links for both the FI (as data provider) and the partner (as data recipient). ## How Can Financial Institutions Support App to App? {#how-can-financial-institutions-support-app-to-app} To enable seamless authentication within your mobile banking app, follow these steps: #### Define a New Consent URL {#define-a-new-consent-url} Here is an example of what your newly configured consent URL will look like: ##### Example {#example} New Path: * Bash ```bash GET /api/v1/mobile/oauth/authorize-url ``` Old Path: * Bash ```bash GET /api/v1/oauth/authorize-url ``` The new endpoint functions the same as the old one, except that your mobile app is now set up to intercept the URL and redirect the customer to the mobile consent experience, where biometric authentication is available. #### Configure the New Consent URL as a Claimed HTTPS URL (Universal Link/App Link) {#configure-the-new-consent-url-as-a-claimed-https-url-universal-linkapp-link} The newly configured consent URL needs to be set up as a claimed HTTPS URL (Universal Link on iOS / App Link on Android) so that users can be redirected to the bank's mobile app authentication flow instead of opening a web browser. Your universal link should redirect users to your authentication flow in the mobile app. If the user clicks on this URL and the bank does not support Universal links, it will open in a web browser instead of the bank's mobile app. To ensure that the bank's mobile app is opened instead of a web browser, the financial institution should set up Universal Links (iOS) or App Links (Android). #### iOS Configuration (Universal Links) {#ios-configuration-universal-links} In the `apple-app-site-association` file hosted at `/well-known/apple-app-site-association`: ```json { "applinks": { "apps": [], "details": [ { "appID": "ABCDE12345.com.example.app", "paths": [ "/auth/*" ] } ] } } ``` For more information on how to configure Universal Links, see [Apple's developer documentation](https://developer.apple.com/ios/universal-links/). #### Android Configuration (App Links) {#android-configuration-app-links} In the `/app/src/main/AndroidManifest.xml`: Here is an example for the `assetlink.json`: `https://bank.example.com/well-known/assetlinks.json` ```xml ``` For more information on how to configure App Links, see the [Android developer documentation](https://developer.android.com/training/app-links). #### Ensure Your Mobile App Supports App-to-App Authentication {#ensure-your-mobile-app-supports-app-to-app-authentication} Your mobile app must: * intercept the Universal/App Link (for example, `https://bank.example.com/auth/link`) and extract the authorization URL. * open the OAuth 2.0 authorization flow within the app. * authenticate the end user and allow them to select and share accounts. * retrieve the OAuth 2.0 authorization code upon user consent. #### Redirect the User Back With an Authorization Code {#redirect-the-user-back-with-an-authorization-code} Once authentication is complete: * redirect the user to the pre-registered redirect URI (provided by the data access platform). * attach the authorization code to the redirect URI. * the data access platform can then exchange this code for an access token.
Example redirect URI: * URI ```URI https://aggregator.example.com/callback?code=AUTHORIZATION_CODE&state=randomStateValue ``` ## How Partners Should Implement App to App Authentication {#how-partners-should-implement-app-to-app-authentication} There are two main requirements to use the app to app authentication enhancement: * Create your domain's `redirectUrl` through a Universal link (iOS)/App Link (Android). * Configure your `redirectUrl`. The Mastercard SDKs redirect users to the Financial Institution's app if it is installed and the `redirectUrl` (Universal Link or App Link) ensures the end user is redirected from the Financial Institution's app back to your application. For further information about how to integrate app to app within the Data Connect experience using our mobile SDKs, see the following pages in our integration guide: * [App to App Authentication with Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) * [App to App support (Data Connect iOS SDK)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#app-to-app-support) * [App to App support (Data Connect Android SDK)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-to-app-support) Note: #### Additional Info {#additional-info} There is no customization. However, if the native browser is not used by a user, a redirect button may appear within the flow after connecting their accounts via the Financial Institution's app. * Supported Browsers: iOS: Automatic Redirect: Safari Redirect Button: Chrome, Edge, Firefox * Supported Browsers: Android: Automatic Redirect: Chrome, Edge, Native Browser Redirect Button: Firefox Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Building a user-friendly FI search experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/fi-search-experience/index.md) --- # Account ACH Details with RTP/FedNow source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md Tip: Account ACH Details now supports [Feedback Loop](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md) which reduces payment failures by securely sharing payment outcome data with Mastercard, enabling us to identify and correct data quality issues. Contact your Customer Success Manager to participate. Retrieve a customer's ACH (Automated Clearing House) details for a specified account. The payment instruction types that the bank account provides are returned. The response indicates whether Real Time Payments (RTP), FedNow Payments (Federal Reserve) and [Tokenized Account Numbers](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#tokenized-account-numbers-tan) (TANs) are enabled. The ACH, RTP and FedNow details can be used for account opening or payment initiation. * The RTP flag indicates if the account can receive and/or send RTPs. It does not indicate if the account or financial institution is Request for Payment (RFP) enabled. * The FedNow flag indicates if the account can receive and/or send instant FedNow payments. It does not indicate if the account or financial institution is Request for Payment (RFP) enabled. * The TAN enabled flag indicates if the Financial Institution leverages a Tokenized Account Number (TAN) for payment initiation. If the account is verified manually using our microdeposit service Account Validation Assistant (AVA), the account is using the real account number and will never be represented by a TAN. Warning: To minimize risk of fraud, we highly recommend verifying the account owner before proceeding with consumer transactions. See [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md). Note: This is a premium service, billable per every successful API call. Note: Before calling any Account Opening endpoints you should verify the FI concerned supports the service by checking our [Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#certified-institutions) list. ## How It Works {#how-it-works} 1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) in the Quick Start Guide. 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) in the Quick Start Guide. 3. Create a customer and link them to at least one account. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) in the Quick Start Guide (you will need to connect a checking and savings account using "Finbank" with the username and password "demo_rtn2"). 4. Call `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/details` with a `customerId` and `accountId` to return the payment instruction details (ACH and, if applicable, RTP/FedNow money transfer details). Diagram account-ach ## API {#api} API Reference: `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/details` Tip: Some FIs will return a tokenized version of the account number (this is indicated in the response by the `tanEnabled` flag). For details see [Tokenized Account Numbers (TAN)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#tokenized-account-numbers-tan). ## Fast ACH {#fast-ach} Our Fast ACH solution enables the Get Account ACH Details to give a faster response to those partners who have enrolled for the service, by caching the required data on our server. Fast ACH is offered at no additional charge. When Fast ACH is enabled, we will pre-fetch the account and routing number details during the account linking process. This is advantageous if you have a time-sensitive use case, as in most cases, the data will be available before the user completes the account linking process. There will also be no need to make an API call to refresh customer account data prior to the Get Account ACH Details call when using Fast ACH, as this will have been done when the data was cached. Fast ACH isn't necessary or appropriate for all partners and is not supported for all FIs. While Fast ACH is offered at no additional charge, it does require enrollment. Speak with your Account Manager to determine if Fast ACH is right for your use case and to enroll. Be aware that it might take a few days for the service to be set up for you. We might need to contact you to help decide if Fast ACH is appropriate for your situation. The following sequence diagram shows how Fast ACH, when available, allows the routing data to be fetched and cached during the account linking process: Diagram ach-cached ## Tokenized Account Numbers (TAN) {#tokenized-account-numbers-tan} A TAN is a tokenized version of the account number in the response to the Get Account ACH details call. Chase, PNC, and soon US Bank will return a Tokenized Account Number (TAN) in place of the real account number and routing number (the `tanEnabled` flag in the response indicates when TANs are used). Alert: US Bank are rolling out their move to using TANs April 30, 2026. Ensure that you check the `tanEnabled` flag in the `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/details` response and handle account numbers accordingly. TANs are specific to each application and therefore provide extra security for the customer. The variances of the TANs returned by Chase, PNC, and US Bank are explained in this table: | Scenario | Chase | PNC | US Bank | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | What actions should be taken to keep the TAN valid? | Ensure that the `customerId` is **not** deleted from the Mastercard Open Finance database. Proactively educate end users to avoid revoking data sharing consent from within their Chase banking portal. Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | Ensure that the `customerId` is **not** deleted from the Mastercard Open Finance production platform. Proactively educate end users to avoid revoking data sharing consent (see **"How is a TAN revoked?"** ). Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | No actions are required by data recipients to keep TANs valid for US Bank. | | Do TANs expire? | TANs issued by Chase do not expire. | TANs issued by PNC will expire when data sharing authorization expires. | TANs do not expire or get revoked for reasons other than fraud. | | When does a TAN become invalid? | The TAN becomes invalid when the user explicitly revokes data sharing consent or if the `customerId` or `institutionLoginId` are deleted via the delete customer endpoint. Invalid TANs will cause any new or pending payments using the TAN to fail. | The validity of the TAN is tied to the user's data sharing authorization. Only TANs issued against valid authorizations are eligible for payment. Invalid TANs will cause any new or pending payments using the TAN to fail. | TANs are only revoked when fraud is detected/reported. | | Does a user need to reconsent to maintain the validity of an existing TAN? | Reconsent for the purpose of maintaining the validity of an existing TAN is not required. | Reconsent for the purpose of maintaining the validity of an existing TAN is not required. | No. | | What is the TAN activation schedule? | TANs are activated and available for use in money movement immediately after generation. | PNC uses a batch activation schedule for TANs. Therefore, TANs are activated approximately 15-30 minutes post generation. Mastercard recommends waiting for 45 minutes after the TAN is generated before attempting money movement with PNC TANs. | ACH payments: May take between 15 to 35 minutes for activation. RTP/FedNow payments: Available immediately. | | How is a TAN revoked? | When the user explicitly revokes data sharing consent, or if the `customerId` or `institutionLoginId` is deleted from the Mastercard Open Finance database. If the TAN has been revoked, the user must reconsent to receive a new TAN. | PNC TANs are only valid if the user's data sharing authorization is valid. Any revocation or expiry of data sharing authorization will revoke a TAN. This includes when a `customerId` or `institutionLoginId` is deleted. PNC may operationally revoke a TAN for reasons including end user request or account fraud concerns. If the TAN has been revoked, the user must reconsent to receive a new TAN. | TANs are only revoked when fraud is detected/reported. Revocation by customers is not currently supported (US Bank may add this in future). If data sharing is revoked, expired, or broken, the TAN remains active if in good standing. | | Is there a way to know if a TAN is valid? | An `aggregationStatusCode` of "947" indicates that a token has been revoked. Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | An `aggregationStatusCode` of "947" indicates a token has been revoked. Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | This will be added in 2026, but given limited revocation of TANs at US Bank, this should not be an issue in the intermediate term. | | Are customers issued a new TAN if consent sharing was revoked but is later reauthorized? | Yes. Chase will issue a new TAN if consent was explicitly revoked and the user later reauthorized. Conversely, Chase will reissue the existing (same) TAN if the data sharing token expired due to non-usage and the user later reauthorized sharing. This occurs because token expiration does not lead to TAN revocation. | Yes. PNC will issue a new TAN if consent was explicitly revoked and the user later reauthorizes data sharing (and the 45-minute window has passed). If a TAN is operationally revoked by PNC (see **"How is a TAN revoked?"**), a new TAN will be issued once the customer reauthorizes. | If a customer has their account TAN revoked for a fraud use case, and they choose to re-authorize data sharing, a new TAN will be issued. | | What is the best practice for keeping TANs valid? | Educating the end user to avoid proactive consent revocation within their account portal is essential for TAN validity. | Once issued and activated, TANs will remain valid unless the `customerId` or `institutionLoginId` are deleted from the Mastercard Open Finance production platform or operationally revoked by PNC (see **"How is a TAN revoked?"**). | No actions are required by data recipients to keep TANs valid for US Bank. | ## Legacy Endpoint {#legacy-endpoint} ### Get Account ACH Details (To Be Deprecated) {#get-account-ach-details-to-be-deprecated} This is a historical version of the Get Account ACH Details endpoint; new features and enhancements are being added to the [Get Account ACH Details with RTP/FedNow](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#api) endpoint. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/details` --- # Onboarding Affiliates source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md Alert: To use the Partner Direct Model via an API, you need to sign up for the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/). Users who do not have the permission to access the Mastercard Developers API will be directed to a page where they can request access. As a Direct Partner, you can use the following options to onboard your affiliate customers: * [Mastercard Developers API](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md#onboard-using-the-api) * [Mastercard Developers Dashboard](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md#onboard-using-mastercard-developers-dashboard) ## Onboard Using the Mastercard Developers API {#onboard-using-the-mastercard-developers-api} Note: The Mastercard Developers API (Onboarding API) and the Open Finance API use different base URLs. * For Mastercard Developers API, the base URL is `https://apiedge.mastercard.com/`. * For Open Finance API, the base URL is `https://api.finicity.com/`. Make sure to use the correct base URL depending on whether you are working with the Mastercard Developers API (Onboarding API) or the Open Finance API. Call the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/) to create projects to onboard and manage your affiliate customers/partners. When a project is created, the project corresponds to a specific affiliate customer. A one-to-one relationship exists between projects and the affiliates you onboard. Mastercard Developers API uses OAuth 1.0a for authenticating your requests. To learn more, see [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/). Once you successfully create projects for your affiliates, project credentials are generated for each one of your affiliate customers. The project credentials are unique and can be used to serve business needs such as registering applications and customizing experiences for your consumers/end-users. After you create projects through the Developers API and onboard affiliate customers, the projects will be available on the [project dashboard](https://developer.mastercard.com/dashboard) of your account on Mastercard Developers. Tip: You can start using the Developers API without writing any code. Follow the steps in the [Developers API Quick Start Guide](https://developer.mastercard.com/mastercard-developers-api/documentation/quick-start-guide/) to explore the Developers API Postman Collection and test all the endpoints. You can use the pre-defined requests in the Postman collection to call the API. 1. [Log in](https://developer.mastercard.com/dashboard) to Mastercard Developers. 2. **Add API Key** * Go to your [Account](https://developer.mastercard.com/account/profile) page and in the Developers API Keys section click **Add key** 3. **Generate a Key** * Provide a **Key name** and **Keystore Password** * If prompted, review and accept the **Mastercard Developers API Terms \& Conditions** to proceed * Click **Create Key** to generate a private key in your browser. This will create a PKCS#12 keystore file secured with your keystore password * Download the signing key as a PKCS#12 keystore by clicking **Download key** . To learn more about the methods available for creating your keys, refer to the [Creating Keys](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#creating-keys) section in the Mastercard Developers Platform documentation 4. **Get Your Consumer Key** Get your consumer key from the Developers API Keys section of your Account page. To learn more about what a consumer key is and its usage, refer to the [Consumer Key](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#the-consumer-key) section in the Mastercard Developers Platform documentation. 5. **Extract the Signing Key (Private Key)** The signing key is a private key used to generate request signatures and confirms ownership of the consumer key. Use the following command to extract the private key from your PKCS#12 keystore (use the password protecting your PKCS#12 file): * OpenSSL ```OpenSSL openssl pkcs12 -in 'mykey.p12' -nocerts -nodes -passin pass:{password} | openssl rsa -out mykey.pem ``` Expected result: ```java -----BEGIN RSA PRIVATE KEY----- MIIEpQIBAAKCAQEAzSdC+wm6Dv4ynlhU5tuMLMsX7AeMWoysQKAaCDCStEWUHyj4 K84X+ZQH0kIJkpWS0M1+vWHTSAu0QvHNDPRIJKMNE2cCRVKApVZ8jQ9DhFkVYE0j AhggCNQTJ0kXDBvc1mZPOJDmXusvHIG3BbRSE6ohZHoUXAuAg4bbwZwmvgDgMrmN 9A9upgMrVZMfrCWeKiBUKoGnwGwUf0iMiHXJhD1Wjdtf0+VAsZNI7r05n9FTHmiC ... YlR8szTbz1WEx//hU5Ea2sfcKmPDTNWQnx0IgSmPu5I9qf7KJxSYhOk= -----END RSA PRIVATE KEY----- ``` 6. **Use the Consumer Key and Private Key** You will require both the `Consumer Key` and the private key extracted from the PKCS#12 file in the previous step to be able to call the API. 7. **Add a Key using a CSR** You can also add a key by uploading a CSR generated in your system: * Go to the Developers API Keys section in your [Account](https://developer.mastercard.com/account/profile) page and click **Add Key** * Select **Upload a CSR** * Provide a Key name and click **Add an attachment**. Browse and choose the CSR file generated in your system * If prompted, review and accept the **Mastercard Developers API Terms \& Conditions** to proceed * Click **Create Key** . For more information on this method, refer to the [Creating Keys](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#method-2) section in the Mastercard Developers Platform documentation **Key Limits and Status:** * After adding a key, its status will appear as **Pending**. You will receive an email notification once the key is approved, after which you can start sending requests to the Developers API * You can add a maximum of **2 keys** * If a key request is declined, you must revoke the declined key before adding a new one To create a project, call the `POST /projects` endpoint. Ensure that the `type` is set to `OPEN_BANKING_PARTNER` and the `serviceId` to `1443`. For more details on the request parameters, see the [API Reference](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference) section in the Mastercard Developers API documentation. ##### Sample Request {#sample-request} ```JSON { "type": "OPEN_BANKING_PARTNER", "name": "My Open Finance Project", "region": "US", "service": { "serviceId": 1443 }, "environment": "SANDBOX", "credential": { "type": "PARTNER", "description": "A custom description for the credential" }, "company": { "name": "Client Company Name", "isGovernmentEntity": false, "address": { "type": "Headquarters", "addressLine1": "420 8th Street S.E", "addressLine2": "Brooklyn, NY", "city": "NYC", "state": "NY", "postalCode": "90210", "countryCode": "USA" } }, "commercialCountries": [ "USA" ] } ``` After successful project creation, the Developers API returns the affiliate customer details including their `partnerId`, `secret`, and `appKey` along with the ID for the newly created project. This project ID will be required to request production access. You will receive an email notification once the project is successfully created. ##### Sample Response {#sample-response} ```JSON { "id": "1c1ea17e-260d-11ee-be56-0242ac120002", "name": "My Open Finance Project", "type": "OPEN_BANKING_PARTNER", "region": "US", "services": [ { "id": 1443, "name": "Open Finance" } ], "environments": [ { "name": "SANDBOX", "credentials": [ { "id": "04bcdc45-9a96-4516-a7b0-49a26440d405", "type": "PARTNER", "partnerId": "2445583866521", "appKey": "555617add4733a9befefa2560cdcfb71", "plan": "Test Drive", "status": "APPROVED", "description": "A custom description for the credential", "secrets": [ { "secret": "SdknnFTYoAlWgFakTHy1", "expirationDate": "2025-10-25T15:24:20Z" } ] } ], "projectServices": [ { "serviceId": 1443, "status": "APPROVED" } ] } ], "teamMembers": [], "invitedUsers": [], "company": { "id": "a7a200c9-f0ae-44c9-97f7-0ebd2943adfd", "companyId": "293101", "name": "Client Company Name", "verified": true, "isGovernmentEntity": false, "address": { "type": "Headquarters", "addressLine1": "420 8th Street S.E", "addressLine2": "Brooklyn, NY", "city": "NYC", "state": "NY", "postalCode": "90210", "countryCode": "USA" } }, "commercialCountries": [ "USA" ] } ``` Optionally you can call [GET /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) to view the status of your project creation.
We recommend that you onboard affiliate customers in a Sandbox environment first before requesting production access. Onboarding your affiliate customers in Sandbox not only gives you the ability to test, but also helps you avoid incurring any accidental billing before enabling production access for your customers. To request production access, call [POST /projects/{project_id}/environments](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) with the `projectId` assigned to your affiliate customer's project. You can retrieve a full list of your projects including the project IDs by calling the [GET /projects](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) endpoint. ##### Sample Request {#sample-request} ```JSON { "name": "PRODUCTION", "credential": { "type": "PARTNER", "description": "A credential used in Production" } } ``` You will receive a response containing the credentials for the production environment. These credentials are still not approved for production use and will be in `PENDING` status. The production access request will be reviewed by Mastercard, and once approved you will receive a notification via email. Note: The response to your production access request can contain one or more statuses. It is important to refer to the appropriate status field to determine the state of your production access request. * The `CredentialStatus` field accurately represents the status of the credentials for use in production. When returned as `APPROVED` you can use your credentials in production. * The `ProjectServiceStatus` field is always returned as `APPROVED` and does not reflect the status of your production access. ##### Sample Response {#sample-response} ```JSON { "name": "PRODUCTION", "credentials": [ { "status": "PENDING_APPROVAL", "partnerId": "2445584446024", "id": "d945c717-0196-49f7-a782-c9dbe312ff42", "type": "PARTNER", "appKey": "b41a66b50cfbfc2955fed24f3e425099", "plan": "Test Drive", "secrets": [ { "secret": "e3CMpVzJYZfE91A8G1hU", "expirationDate": "2025-03-19T06:07:18Z" } ], "description": "Production credentials for my project", "error": null } ], "projectServices": [ { "serviceId": 1443, "status": "APPROVED", "credentials": [] } ] } ``` Optionally you can call [GET /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) to view the status of your production access request. Once approved, the status of the credentials change from `PENDING_APPROVAL` to `APPROVED`. ## Onboard Using Mastercard Developers Dashboard {#onboard-using-mastercard-developers-dashboard} 1. [Log in](https://developer.mastercard.com/account/log-in) to Mastercard Developers and click the **Create New Project** button at the top of this page. 2. Enter a name for your project. 3. You have the option to choose if you want to create a project for yourself or for a client. Choose **Yes** to create a project on behalf of a client. 4. Enter the company name and address of the affiliate customer. 5. Select **Open Finance** from the **Select your API service** drop-down list. 6. Ensure the region is selected as United States. 7. Provide a helpful description for the Sandbox credentials and click **Create Project** . 1. Go to the Production section and click **Request Upgrade**. 2. Provide a helpful description for the production credentials and click **Proceed**. The production access request will be reviewed by Mastercard and once approved, you will receive a notification via email. ## Create an Experience for Your Affiliate Customers {#create-an-experience-for-your-affiliate-customers} To simplify the process of ensuring your affiliates have a suitable Data Connect experience defined, you can use the following endpoint to create a new experience ID which is a duplicate of an existing one. API Reference: `POST /connect/experiences/{experience_id}/duplicate` Note that this is an Open Finance endpoint, not part of the Mastercard Developers API. You will need to already have a suitable US Open Finance project, with a defined experience (which you know the ID of) and the ability to make API calls to US Open Finance endpoints. See the [Configure the Data Connect Experience](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/index.md) and [Customizing Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) pages to understand more about how the Mastercard Data Connect experience can be customized to be suitable for your use case. Once you have an experience ID which is suitable, you can duplicate that experience as many times as you need in order to create new experience IDs for your affilates. Each duplicate experience can be modified further after it is created if necessary. ## Next Steps {#next-steps} See [Manage Projects](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/managing-customers/index.md) to manage your affiliate customers' projects on Mastercard Developers. --- # Loan Payment Details source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/loan-payment-details/index.md Loan Payment Details retrieves the information needed to move money to a non-routable liability account, as well as provide a 10-day future payoff amount, depending on the availability by the financial institution. This is a billable service, where a charge is incurred for each successful API call. ## How It Works {#how-it-works} After a customer has added accounts in [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), Loan Payment Details can be retrieved from a financial institution. Our list of Supported Institutions confirms payment detail availability. **Get Loan Payment Details** API Reference: `GET /aggregation/v2/customers/{customerId}/accounts/{accountId}/loanDetails`
The following fields in the response are required fields: `loanNumber`, `loanPaymentNumber`, and `loanPaymentAddress`. If one of these fields are not available, the API call will not be successful. The futurePayoffAmount and futurePayoffDate fields (for account, group, or loan) are optional, meaning if the field is available, it will be returned in the API response, but if is not available, the call may still be successful. ### Student Loan Data {#student-loan-data} For Certified Student Loan Institutions, use the account ID of the studentLoanAccount account `type` as the input parameter for `accountId`. This will enable a consolidated response to return the payment details of the entire sub-structure consisting of the `studentLoanGroup` and `studentLoan` accounts. Using the account ID of the incorrect account type will result in a failed call. Certified Student Loan Institutions can be identified via Supported Institutions. ## Good to Know {#good-to-know} Even though an institution may support Loan Payment Details, there are some account types at that institution may not be supported. **Common API Status Codes** | HTTP Code | Meaning | Resolution | |-----------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 20010 | Loan number not found | Submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) | | 20011 | Loan payment number not found | Submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) | | 20022 | Loan payment address not found | Submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) | | 38008 | Account details not found | Submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) | | 38003 | Customer does not have given account | Resubmit with a correctly related customerId and accountId | | 44000 | Timeout - The request has been accepted for processing. | Try again later. If the issue persists, submit a [support ticket](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) | --- # Migrating to Data Connect Components source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/migration/index.md ## Onboarding {#onboarding} The following will be provided to the partner during onboarding: * Mastercard Terms and Privacy Notice links * Mastercard brand assets
Both of these are required to be embedded in the partner experience as outlined in the [UX Requirements](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md#ux-requirements) section of the [Data Connect Components UX Implementation Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/components/ux-implementation/index.md). During the onboarding process the partner will be required to get Mastercard legal sign off on the user journey to ensure all Mastercard requirements are met. This includes sharing screens of the user journey. Please coordinate with your Mastercard representative to begin this process. ## Authentication and Configuration {#authentication-and-configuration} A partner must authenticate to be able to successfully call any Data Connect Components APIs. A partner must also create a customer prior to calling Data Connect Components APIs. A customer ID is needed when calling [Create Login Form](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md#legacy-connections), [Create OAuth URL](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md#oauth-connections) or [Initiate Reconnection (Data Connect Fix)](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md#initiate-reconnection-data-connect-fix-for-components) API calls. See also the [Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) and [Customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) sections for more details. ## FI Selection {#fi-selection} It is the responsibility of the partner to build and manage the FI selection portion of the user journey. As with Data Connect Lite, APIs are provided to retrieve the Mastercard Institution List to build and manage the user FI selection. This includes managing certification and branding. Both of which are available via API. ## Account Selection and Review {#account-selection-and-review} It is the responsibility of the partner to build and manage the account selection and review portion of the user journey. As with Data Connect Lite, APIs are provided to retrieve account details to build and manage the account selection and review. Data Connect Components will provide the account IDs via webhook or SDK events that will be needed to retrieve the account details. ## Adding Accounts {#adding-accounts} Data Connect Components add all accounts when retrieving accounts. The only time this does not happen is when the configuration object of the specific partner sets account type filtering to exclude certain types of accounts. Once the accounts are added, the list of account IDs will be returned via webhook or SDK event. ## Error States {#error-states} It is the responsibility of the partner to manage error states for their users. An error code, when applicable, will be provided via API response, webhooks, or SDK events. The partner will need to understand the error code and act accordingly to manage the user experience and flow. Example: The credentials submitted by the user when attempting to log into a Legacy institution are incorrect. The partner will receive an error code (likely 103) via webhook or SDK event, depending on integration type. The partner will need to manage how they tell the user that the credentials submitted were not correct. Data Connect Components does not present anything to the user. ## Differences Between Data Connect Components and Data Connect Full and Lite {#differences-between-data-connect-components-and-data-connect-full-and-lite} * No Experiences Data Connect Components does not use experiences or experience IDs like the other versions of Data Connect Because of the flexibility and high level of customization Data Connect Components provides partners, partners are able to manage and configure the experience themselves. Experiences in the other versions of Data Connect are available for things such as brand color, brand icon or hiding the exit button. These things and all of the user journey design and experience are managed by the partner. As such, experiences and experience IDs are not in Data Connect Components. * No Data Connect Components Managed Sessions With the flexibility and high level of customization Data Connect Components provides partners are able to manage the user journey. Because the entire user journey is managed and hosted by the partner, Data Connect Components has no sessions and does not track sessions. The partner needs to manage user sessions and session information. * Webhook Mapping between Data Connect Component and Data Connect Lite Note: The names of the Data Connect Components events are different in structure due to using the Open Finance Centralized Webhook Service. | Data Connect Lite Webhook | Data Connect Components Webhook | Partner Actions | |---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `started` | N/A | Partners handles the start of the flow | | `processing` | `connect-components.legacy-user-login.submitted` | | | `processing` | `connect-components.legacy-user-login.accepted` | | | `institutionNotSupported` | N/A | | | `institutionSupported` | N/A | Partners are responsible for directing users to supported FIs | | `invalidCredentials` | `connect-components.legacy-user-login.rejected` | | | `mfa` | `connect-components.mfa.submitted`, `connect-components.mfa.submitted`, `connect-components.mfa.required`, `connect-components.mfa.rejected` | | | `mfaUpdated` | N/A | | | `unableToConnect` | `connect-components.legacy-user-login.rejected` | | | `adding` | N/A | Data Connect Components receives the accounts added. Therefore, this use case doesn't apply and is covered by the `accountsReturned` event. | | `added` | `connect-components.accounts.added` | Unlike Lite, Components returns the account IDs. The Partner needs to call an aggregation API (see below) to get the account details for the accounts that the end user selected. `GET https://api.finicity.com/aggregation/v1/customers/:customerId/accounts/:accountId`, `GET https://api.finicity.com/aggregation/v1/customers/:customerId/institutionLogins/:institutionLoginId` | | `done` | N/A | Partner receives accounts in `AccountsReturned`, which indicates the flow is complete for the given institution. | --- # Generating Reports source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md This section explains how to generate Lend reports. There are three ways to generate reports: * [Using Data Connect](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-data-connect) -- your Data Connect experience can be enabled to auto-generate reports at the end of the session. * [Using the API](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-the-api) -- call a report generation endpoint after the customer has provided permission to access their data through Data Connect. * [Using the Client Hub](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-the-client-hub) -- use the no-code Order Reports tool in the Client Hub portal to request reports without building an API integration.
For details of each report type, see the [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md). ## Prerequisites {#prerequisites} The prerequisites for generating a report depend on the report type and the method you use. You will typically need: * a [customer record](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#customer-record) (for FCRA use cases) * a [consumer record](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#consumer-record) * a [business record](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#business-record) (for certain business use cases) * a [Permissible Purpose Code](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#permissible-purpose) (for FCRA use cases) * customer [data access through Data Connect](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#connected-data)
This section assumes you have followed the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) and have created an Open Finance project with API credentials. ### Customer Record {#customer-record} You need a customer record for an individual or business whose data you want to report on. See [Customer Records](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md) for details on creating and managing customer records. ### Consumer Record {#consumer-record} Most Lend products are created within Fair Credit Reporting Act (FCRA) protections. To generate and retrieve CRA reports, a consumer record is required. Unlike a customer record, a consumer record cannot be deleted. A copy of each report created for a consumer is available for six years. There is a one-to-one relationship between a customer record and a consumer record. For details, see the [consumer record documentation](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers). Note: When creating a consumer record, end user information must be provided by partners that are resellers. This is due to FCRA regulatory requirements. Note: Customers can access, view, and dispute reports using the [Consumer Portal](https://consumer.finicityreports.com/). For more information about how the Consumer Portal works, see the [consumer-facing documentation](https://www.mastercard.com/us/en/business/open-finance/consumer.html). ### Business Record {#business-record} A business record may be required in addition to or in place of a consumer record for some small business use cases. Certain products, such as Transaction CRA and Verification of Income, do not support the business record. In some instances, it is appropriate to enter [business data](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumer-records-and-small-business-lending) into the consumer record. For details, see [the business record documentation](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses). ### Permissible Purpose {#permissible-purpose} As part of FCRA regulations, a permissible purpose code is required when retrieving CRA reports. See [Permissible Purpose Codes](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) for the list of valid codes and when to use them. ### Connected Data {#connected-data} Before you can generate a report, the customer must provide access to the relevant data. Lend reports require the customer to link bank or payroll accounts or upload a paystub through [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md). The type of accounts required depends on the report: * **Bank account reports** (such as VOA, VOI, VOAI, Transaction CRA, Cash Flow Analytics, Balance Analytics): The customer must connect their bank accounts. * **Payroll reports** (such as VOIE - Payroll, VOE - Payroll): The customer must connect their payroll provider account. * **Paystub reports** (such as VOIE - Paystub): A paystub must be uploaded, either through Data Connect or via the API. * **Bank account and paystub reports** (such as VOIE - Paystub with TXVerify): The customer must connect their bank accounts and upload a paystub. This produces a single report that verifies income using both transaction and paystub data.
See the [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) for specific prerequisites for each report type. ## Generating Reports Using Data Connect {#generating-reports-using-data-connect} [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) provides a variety of guided user experiences to enable customers to grant access to the required data. Data Connect Full experiences are commonly used for Lend products. These experiences can automatically generate a report at the end of the session. Note: Automatic report generation is enabled by default, but you can disable it using the [Skip Report](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#skip-report) option. ### Data Connect Full Experiences {#data-connect-full-experiences} The Financial Institution (FI) certification and other settings of these experiences are configured for best results for the listed report types. Contact your Mastercard Account Manager for help configuring your Data Connect experience. | Data Connect Product Type | Report(s) Generated | Description | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Transactions CRA | Transaction CRA | Bank account connection experience. | | VOI | VOI | Bank account connection experience. | | VOA | VOA | Bank account connection experience. | | VOA History | VOAI ‑ Transactions | Bank account connection experience. | | VOE Transactions | VOE ‑ Transactions | Bank account connection experience. This product is most often used as a refresh of a VOAI or VOA report and not a standalone experience. | | VOIE Payroll | VOIE ‑ Payroll | Payroll connection experience. | | VOE Payroll | VOE ‑ Payroll | Payroll connection experience. This product is most often used as a direct refresh of a VOIE - Payroll report and not a new consumer experience. | | Cash Flow Analytics Business CRA, Cash Flow Analytics Business FTC, Cash Flow Analytics Non‑CRA, Cash Flow Analytics Personal CRA, Cash Flow Analytics Personal Non‑CRA | Cash Flow Analytics | Bank account connection experience. | | Balance Analytics Business CRA, Balance Analytics Business FTC, Balance Analytics Business Non‑CRA, Balance Analytics Personal CRA, Balance Analytics Personal Non‑CRA | Balance Analytics | Bank account connection experience. | | VOIE Paystub Tx Verify | VOIE ‑ Paystub (with TXVerify) | VOIE - Paystub (with TXVerify) experience. The customer is prompted to connect to their direct deposit account(s) and upload their most recent paystub. | | VOIE Paystub | VOIE with Statement (no TXVerify) | Paystub experience. The customer is prompted to upload their most recent paystub. | | Pre Qual VOA | AssetReady | Bank account connection experience. | | MVS IE | VOIE ‑ Payroll, VOIE ‑ Paystub (with TXVerify) | MVS - Income and Employment waterfall experience to collect all information necessary for income and employment verification in one step. The customer connects their payroll data and is then asked if they have additional employment records to add. If so, they are prompted to connect their direct deposit account(s) and upload their most recent paystub. Generates VOIE - Payroll (if data found) and VOIE - Paystub (with TXVerify) (if required). | | MVS IE Basic | VOIE ‑ Payroll, VOAI | MVS - Income and Employment Basic waterfall experience to collect all information necessary for income and employment validation in one step, without paystub data. The customer connects their payroll data and is then asked if they have additional employment records to add. If so, they are prompted to connect their direct deposit account(s). Generates VOIE - Payroll (if data found) and VOAI (if required). | | MVS Basic | VOIE ‑ Payroll, VOAI ‑ Transactions | MVS - Basic Asset, Income and Employment waterfall experience to collect all data for asset, income and employment verification through payroll and transaction data. The customer is prompted to connect their bank accounts and payroll data. Generates VOIE - Payroll (if data found) and VOAI - Transactions. | | MVS Basic Paystub | VOIE ‑ Paystub (with TXVerify), VOAI ‑ Transactions | MVS - Basic Paystub experience. The customer is prompted to connect their bank account(s) and upload their most recent paystub. | | MVS Full | VOIE ‑ Payroll, VOAI, VOIE ‑ Paystub (with TXVerify) | MVS - Full waterfall experience to collect all information necessary for assets, income and employment verification in one step. Also known as "MVS-1-Touch". First, the customer is prompted to connect their bank accounts and payroll data. The customer is then asked if they have additional employment records to add and if so, they are prompted to upload their most recent paystub. Generates VOIE - Payroll (if data found), VOAI, and VOIE - Paystub (with TXVerify) (if required). | Tip: If a product is not on the list above, you can use the basic Aggregation Data Connect experience type to have the customer connect bank accounts, then generate the report yourself using the API endpoint for the required report. See [Generating Reports Using the API](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-the-api). ### Embedding Data Connect {#embedding-data-connect} To enable Data Connect, either embed a [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) into your experience, or [send a Data Connect email](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#send-data-connect-email) to the customer. For best results, prepare the customer by letting them know the benefits of digitally connecting their accounts and reminding them what account types to connect. For joint borrower use cases, use the [Data Connect Full -- Joint Borrower](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) flow. Multiple customer IDs and consumer IDs can be tied together to one Data Connect experience. Bank accounts are connected and linked to the customer/consumer record tied to the customer designated as the "primary" borrower. Payroll accounts are connected individually per borrower. For more information, see the [Data Connect documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) and the [UX implementation best practices](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md). ## Generating Reports Using the API {#generating-reports-using-the-api} You can generate or refresh reports by calling the report generation API endpoint for the specific report type. This approach is useful in these cases: * The customer has already connected their data through Data Connect (including non-Full experience types such as Aggregation). * You want to refresh an existing report with updated data. * You are using a Data Connect Full experience but auto-generation is disabled.
To generate a report through the API, call the report generation endpoint for the report type you need. Each report type has its own endpoint -- see the [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) for the endpoint and parameters for each report. Tip: We recommend using report webhooks to get a notification when the report is ready, by passing a suitable listener URL in the `callbackUrl` parameter in your report generation API call. You can then listen for events on this URL and fetch the report when it is ready., For details of the report events, see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md). Alternatively, you can call one of the Get Report APIs some time after generating the report. Refer to the [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) for the median time it takes to generate each report type. ### Refreshing Reports {#refreshing-reports} Any report generation request for the same customer after the initial report is considered a refresh and returns updated data. A refresh is executed without re-engaging the customer. Refreshed reports default to the same parameters as the original report unless you specify otherwise. Warning: You can only generate or refresh a maximum of 150 Lend reports for each customer ID. Any type of report counts towards the lifetime limit of 150. ## Generating Reports Using the Client Hub {#generating-reports-using-the-client-hub} The [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) tool in the Open Finance Client Hub enables you to request and view Lend reports using a web interface without building an API integration. The tool emails customers a request to grant permission to share the required data through Data Connect. Once the report is done, it can be downloaded from the Client Hub in PDF format. You can also use Order Reports for testing or as a temporary solution while building an integration. For details on setting up an account and using the tool, see [Order Reports](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md). ## Getting Reports {#getting-reports} Once a report has been generated (whether from the API or the Client Hub), you can retrieve it using the Get Report API endpoints. See [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) for full documentation. Reports generated from the Client Hub can also be downloaded via the Order Reports tool. Most reports can be retrieved in JSON or PDF format via the API. Currently, the Order Reports tool only supports PDF format. ### Report Webhooks {#report-webhooks} You can set up a webhook listener to get report status notifications so you know when a report is done and ready to be retrieved. See [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md) for full webhook documentation. ## Testing {#testing} Test the APIs by connecting data using our test institutions and test accounts. See [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md). Ensure the test profile you select contains account types that are supported by the report you are ordering. In addition to the basic test profiles, there are several Lend-specific test profiles: * [Payroll Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles) * [Paystub Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#paystub-profiles) * [MVS Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#mvs-profiles) --- # Getting Reports source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md Each type of report is generated using a different API endpoint, but all reports can be fetched once they are ready using the Get Report endpoints. You need the ID of the report that was returned when you generated the report. The endpoint response contains different data depending on the type of report that was generated. The [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) has example JSON and PDF reports for each report type. Tip: We recommend using report webhooks to get a notification when the report is ready. You can provide a suitable URL for receiving webhook events either when you generate a report via API, or when you create a Connect session which results in a report being generated. See [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md) for details. Alternatively, you can call one of the Get Report APIs some time after generating the report. Refer to the [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md) for the median time it takes to generate each report type. Note: Get Report endpoints can be used to obtain either JSON or PDF format reports. To specify the format required, use `application/json` or `application/pdf` in the `Accept` request header. If neither is set in the `Accept` request header, the report format will be returned in JSON format. ## Get Report by Report ID {#get-report-by-report-id} Tip: This is a new endpoint which enables you to get a report with the report ID alone without providing a customer or consumer ID. We recommend using this endpoint to get reports to simplify implementing your solution. Use the report ID to obtain a generated report using the following endpoint. Note that this endpoint can retrieve all Lend report types. The details of the response depend on the type of report being requested. API Reference: `POST /decisioning/v3/reports/{reportId}` ## Get Report by Consumer {#get-report-by-consumer} Use the report ID and the consumer ID to obtain a generated report using the following endpoint. Note that this endpoint can retrieve all Lend report types. The details of the response depend on the type of report being requested. API Reference: `GET /decisioning/v3/consumers/{consumerId}/reports/{reportId}` ## Get Report by Customer {#get-report-by-customer} Use the report ID and the customer ID to obtain a generated report using the following endpoint. Note that this endpoint can retrieve all Lend report types. The details of the response depend on the type of report being requested. API Reference: `GET /decisioning/v3/customers/{customerId}/reports/{reportId}` ## Get List of Reports by Consumer {#get-list-of-reports-by-consumer} Get a list of all generated reports for an individual consumer. Use the report IDs returned to obtain full details of a particular report using one of the other endpoints. API Reference: `GET /decisioning/v1/consumers/{consumerId}/reports` ## Get List of Reports by Customer {#get-list-of-reports-by-customer} Get a list of all generated reports for an individual customer. Use the report IDs returned to obtain full details of a particular report using one of the other endpoints. API Reference: `GET /decisioning/v1/customers/{customerId}/reports` ## Report Reissue {#report-reissue} Report Reissue is a billable service that enables authorized third parties - such as investors, mortgage insurers, QC agencies, and loan management systems - to securely access an existing CRA report originally generated by another Mastercard partner. This eliminates the need for manual workarounds like PDF sharing or credential exchange, ensuring auditable, read-only access to consumer data. Report Reissue helps streamline secondary market workflows and maintain data security throughout the loan lifecycle. * **Supported Report Types**: All FCRA reports. Note: Reports may only be reissued for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of reissued reports is subject to all applicable obligations of the FCRA. To reissue a previously generated report, use the following endpoint: API Reference: `POST /decisioning/v1/reports/{reportId}/partners` Note: This is a billable service. ### Implementation Notes {#implementation-notes} * Reports can only be reissued within 180 days of the report created date * An API lock out for failed attempts is in place, so be sure to use a valid report ID * Retrieve the report in JSON or PDF format using the Accept header in the request ## Portfolios {#portfolios} You can retrieve a portfolio that includes all the reports generated for a particular consumer. This is useful for mortgage verification use cases where you need to send reports to Government Sponsored Enterprises (Fannie Mae/Freddie Mac). See [Portfolio ID Usage](https://developer.mastercard.com/open-finance-us/documentation/products/lend/mortgage-implementation/index.md#portfolio-id-usage) for details. --- # Report Events (API) source: https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/report-webhooks-api/index.md API report webhook notifications are sent for reports generated using a request to an API endpoint. Note: Notifications are sent to the webhook URL you specified using the `callbackUrl` request parameter in your generate report API call. See [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md). Notifications are sent when a report starts, fails, or completes. This page provides example webhook notifications for [supported reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md). Sent when a report is being generated. * JSON ```JSON { "eventName": "inProgress", "id": "REPORT_ID", "consumerId": "CONSUMER_ID", "consumerSsn": "1234", "type": "voaHistory", "status": "inProgress", "portfolioId": "PORTFOLIO_ID", "customerId": 123456, "reportCustomFields": [ { "label": "label 0", "value": "value 0", "shown": false } ] } ``` Sent after a report has failed to generate. * JSON ```JSON { "eventName": "failed", "id": "REPORT_ID", "consumerId": "CONSUMER_ID", "consumerSsn": "1234", "type": "voi", "status": "failed", "portfolioId": "PORTFOLIO_ID", "customerId": 123456, "reportCustomFields": [ { "label": "label 0", "value": "value 0", "shown": false } ] } ``` Sent when a report is complete. * JSON ```JSON { "eventName": "done", "id": "REPORT_ID", "consumerId": "CONSUMER_ID", "consumerSsn": "1234", "type": "voa", "status": "success", "portfolioId": "PORTFOLIO_ID", "customerId": 123456, "reportCustomFields": [ { "label": "label 0", "value": "value 0", "shown": false } ] } ``` --- # Account Balance source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md The Account Balance service provides real-time or cached bank account balance information from your customer's Financial Institution (FI). The information returned includes: * Available balance---the amount of money that the account holder can spend or withdraw immediately. This value reflects some pending transactions (for example, a pending debit card transaction). * Cleared balance---the amount of money currently in the account. This may vary from the available balance as it does not account for pending transactions.
The available and cleared balance will be the same if there are no pending transactions or funds to clear. However, if there is, for example, a pending debit card transaction of $50, the available balance will be $50 lower than the cleared balance. For both fraud prevention and managing insufficient funds (NSF), we recommend you rely on the available balance. This value provides a more accurate view of funds by factoring in pending debit transactions or holds, which the cleared balance does not include. Tip: To leverage the **Get Available Balance** solution, enrollment to this service is required. Please contact your account manager to learn more. Note: The **Get Available Balance** endpoint is a premium service, and is billable for each successful API call. ## Use Cases {#use-cases} * **Payments** - Evaluate a customer's ability to make a payment. * **Financial Aggregation Tools** - Provides up-to-date account balance information that can be consolidated and displayed to the customer. ## How It Works {#how-it-works} 1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) in the Quick Start Guide. 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) in the Quick Start Guide. 3. Create [a customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) and link them to at least one account via [Mastercard Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). You can use any of the [Bank Account Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles) to test. 4. Call [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetAvailableBalanceLive).
You can use the optional `balance_cache_interval` query parameter to control balance caching. The value specifies the maximum age in minutes of the cached balance that you will receive. The value must be from 0 to 1440 (1440 minutes is 24 hours) and defaults to 30 if not specified. For example, if you specify 15 minutes, cached data is returned only if the data was cached in the last 15 minutes. If no suitable cached balance exists, the Financial Institution is called to return a live balance. Specify a `balance_cache_interval` of `0` to force retrieval of a live balance. Tip: Using a balance cache interval improves performance by avoiding making too many requests to the FI to obtain a live balance. We recommend using the default 30-minute interval, but you can adjust this based on your specific needs. ### Get Available Balance {#get-available-balance} Retrieve the available and cleared account balances for a single account in real-time from an FI, using `customerId` and `accountId` in the request parameters. You can use this endpoint to retrieve either a live or cached balance from an FI. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/availableBalance/live` Note: The default caching behavior of this endpoint changed on **30 June 2026**. * **Previously** : if `balance_cache_interval` was not specified, it defaulted to 0 (a live balance was always retrieved). * **From 30 June 2026** : if `balance_cache_interval` is not specified, it defaults to 30 minutes (a cached balance is returned if available). Diagram account-balance ## Testing {#testing} See [Balance Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#balance-profiles) for details of banking profiles that are provided for testing purposes. These profiles are designed to return different account balances for testing purposes. --- # Returning User Experience source: https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/returning-user-experience/index.md The Returning User Experience (RUX) enables returning customers to quickly and securely share financial data using Mastercard Data Connect. By recognizing customers who have previously linked accounts, RUX accelerates repeat data-sharing sessions while maintaining strong authentication, consent, and transparency. Both Data Connect Full and Data Connect Lite support RUX. The experience adapts automatically based on product and institution. ![RUX](https://static.developer.mastercard.com/content/open-finance-us/uploads/demo2.svg) ### Demos {#demos} View interactive prototypes of the Returning User Experience for a single-account Pay use case. [Data Connect Full](https://www.figma.com/proto/q9tpU7Oc9ObtG6FqmYa5fc/EDGE-RUX-with-Passkey-Demo?node-id=2-6687&page-id=0%3A1&starting-point-node-id=2%3A6687&show-proto-sidebar=1&t=lkZTnkuDHqD0FBDx-1) [Data Connect Lite](https://www.figma.com/proto/xjSUiva4iCAsCHOCz2jVfC/EDGE-Connect-Lite-RUX--Demo?node-id=1-132&p=f&viewport=117%2C447%2C0.1&t=RcPZtErcplWcItfc-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=1%3A132&page-id=1%3A3) ![RUX](https://static.developer.mastercard.com/content/open-finance-us/uploads/figma2.svg) ### Figma Files {#figma-files} Access the end-to-end product experience for the Returning User Experience to duplicate and customize in your own environment. [Data Connect Full](https://www.figma.com/design/4vQwpyyNezaAKBg0UYiwrF/EDGE---RUX-End-to-End-Flow?node-id=6099-5068) [Data Connect Lite](https://www.figma.com/design/pKFZI7LF0WPGQKovthPyaL/EDGE---Connect-Lite-with-RUX-End-to-End-Flow?node-id=6099-5068&t=O5nERSajK0wjaPd4-1) ## Benefits of the Returning User Experience {#benefits-of-the-returning-user-experience} Many customers connect financial accounts more than once---across apps, use cases, or over time. RUX is designed to recognize those customers and make repeat account sharing faster, clearer, and more consistent across Mastercard Data Connect. With RUX, customers who have already shared accounts can quickly authenticate and continue their journey without repeating steps they've already completed. Their previously shared financial institutions and accounts are available again, and the experience adapts automatically, based on the institution and product being used. RUX benefits to you: * A smoother experience while maintaining strong security * Clear consent * Customer visibility into data sharing RUX benefits to customers: * Secure, faster authentication in future sessions * Instant sharing of eligible financial accounts without re-entering credentials when using a registered passkey * Institutions are recommended based on the customer's previous selections for faster account linking (Data Connect Full integrations only) To promote transparency and customer trust, customers can view all their active data connections through a standalone dashboard. Customers receive an SMS link to this dashboard each time they link a new account with a RUX-enabled partner and can also access it anytime at [connections.finicity.com](https://connections.finicity.com). Together, these features increase visibility into data activity while improving satisfaction and reducing friction across the Data Connect experience. Note: The [Add Customer](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#AddCustomer) endpoint includes an optional field for adding a mobile number during the "Create Customer" step. By including this field, the customer's mobile number is pre-filled on the mobile entry screen, removing a step for the user. Once the customer is registered, they simply verify their identity to have access to their previously-shared accounts. ## How Returning User Experience Works {#how-returning-user-experience-works} ### Returning Customers {#returning-customers} When a customer returns to your app, even if their first session was with a different Mastercard partner: 1. If there is no phone number present in the customer record, RUX prompts them to enter their mobile phone number. 2. They authenticate using either: * Registered passkey * OTP (one-time passcode) if a passkey was not created 3. Previously shared institutions and eligible accounts are presented for selection. ### First-Time Customers {#first-time-customers} 1. If there is no phone number present in the customer record, RUX prompts them to enter their mobile phone number. 2. Verify identity using a one-time passcode (OTP). 3. (Optional) Create a passkey for faster authentication in future sessions. 4. Select and share financial accounts. Once the session is complete: * Bank selections are securely saved * The customer receives an SMS link to a dashboard where they can review active data connections Note: If a customer completes the OTP but chooses to skip passkey creation during registration, they still benefit from recorded account selections and are taken directly to FI selection when they return. However, they must re-authenticate as they did during their initial experience. ## RUX with Data Connect Full and Data Connect Lite {#rux-with-data-connect-full-and-data-connect-lite} The customer's flow depends on whether your application is using Data Connect Full or Data Connect Lite, as described below: ### Data Connect Full {#data-connect-full} * Once authenticated, customers are taken directly to: * Suggested financial institutions, or * Account selection for previously shared institutions * If re-authentication with the FI is required, customers proceed directly to the FI login after selection ### Data Connect Lite {#data-connect-lite} * Customers can link previously shared accounts without re-entering banking credentials when supported * If re-authentication is required, authenticated customers are taken directly to the FI login ## View the End-to-End Flow {#view-the-end-to-end-flow} For the best viewing experience of Mastercard Data Connect and the Returning User Experience, select the **full screen mode** option or **zoom** using the controls located on the right. ### Data Connect Full {#data-connect-full-1} ### Data Connect Lite {#data-connect-lite-1} Tip: If you have any questions or need assistance with the customer experience or development, [contact us](https://developer.mastercard.com/open-finance-us/documentation/support/index.md).
Next: [Data Connect Fix Experience](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/connect-enhancements-and-features/recall-experience-connect-fix/index.md) --- # Legacy PSI Endpoints source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md The legacy endpoints are for an older version of PSI. These endpoints do not provide an unauthorized return score, and NSF reason codes are not optional. API Reference: `GET /aggregation/v2/customers/{customerId}/accounts/{accountId}/payments/paymentIndicator` API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/payments/paymentIndicator/fcra` Warning: Do not use the legacy endpoints for a new integration. They are scheduled to be deprecated. We recommend using the new PSI endpoints which support an unauthorized return score: * [New FCRA Version](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md) * [New non-FCRA Version](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md) --- # Web Applications source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md We recommend using the Web SDK to integrate the Data Connect experience into your web applications. You can also use the Web SDK to help you add the Data Connect experience to your mobile applications, by showing your web application within a webview in your mobile apps, although we recommend using our iOS, Android, or React Native SDKs for best results on mobile. Each option still allows for App to App authentication. The Data Connect Web SDK allows you to embed the Data Connect user experience into an iFrame or add it into a popup window. The Data Connect Web SDK also provides events to help you monitor the progress of a user within the flow. You can choose to install the Web SDK into your build project via npm, or reference it via our Content Delivery Network (CDN) using either the ESM, UMD, or IIFE module formats. App to app authentication is supported in all cases. See the following for details: * [Using the Web SDK via Package Manager](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md) -- Use the SDK after installing using npm or via our starter code pack. * [Using the Web SDK via CDN](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/web-sdk-cdn/index.md) --- If the npm Package Manager is not suitable or you do not wish to install the SDK then you can use our CDN solution instead, meaning you don't need to worry about dependencies and build processes. * [Web SDK Migration Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/websdk-migration/index.md) --- If you previously used the Finicity SDK then you should read our Migration Guide to find out how to update to the current SDK. --- # Manage Access Keys source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/manage-access-keys/index.md Clients use the following APIs to manage consent receipts for processors. * Generate Access Key: Request access and create a consent receipt for a processor. * Update Access Key: Update the parameters of an active consent receipts. * Revoke Access Key: Consent receipts revoke access to our platform despite the consent receipt's expiration date and time. These are described below. ## Generate Access Key {#generate-access-key} Used to create a consent receipt on behalf of a processor wanting to access consented data on our API platform. Specify the thirdPartyPartnerId, customerId, product, accountId, timeframe and all other fields of the objects that the processor needs to automate processing payments. Note: The timeframe value is in ISO-8601 format while all other APIs are in Epoch format. ### Considerations {#considerations} * Only one customerId per consent receipt request. * Only one thirdPartyPartnerId per consent receipt. * You can specify multiple products for one customerId per the same thirdPartyPartnerId. API Reference: `POST /aggregation/v1/partners/accessKey` ## Update Access Key {#update-access-key} Used to update a consent receipt to change what the processor is allowed to retrieve from our API platform. The ThirdPartyAccessReceipt version number increments so that the processor knows the latest version of what they are authorized to access. Specify the thirdPartyPartnerId, customerId, product, accountId, timeframe and all other fields of the objects that the processor needs to automate processing payments. Note: The timeframe value is in ISO-8601 format while all other APIs are in Epoch format. ### Considerations {#considerations-1} * Only active consent receipts get updated. * Only one customerId per consent receipt request. * Only one thirdPartyPartnerId per consent receipt. * You can specify multiple products for one customerId per the same thirdPartyPartnerId. API Reference: `PUT /aggregation/v1/partners/accessKey/{consentReceiptId}` ## Delete Access Key {#delete-access-key} The Recipient can revoke the Requester's Access Key at any time regardless of its expiration date and time. The access receiptId is deleted from the platform, and the Requester no longer has access to retrieve Access Key related data from our platform. An HTTP status code of 204 (no content) response is generated if the access key was successfully found and deleted. A 404 (not found) response is returned if the specified key does not exist. API Reference: `DELETE /aggregation/v1/partners/accessKey/{consentReceiptId}` ## Error Codes {#error-codes} Requesters may encounter errors requesting or using the Access Key. The error code responses and descriptions are the same error codes received for all clients. The error code data is in the following data structure. ```JSON { "code": 12001, "message": "An unexpected error has occurred. No consent receipts for receiptId" } ``` | HTTP status code | Reason code | Description | |------------------|-------------|---------------------------------------------------------------------------------------------------| | 404 | 12000 | No information found for the partner. | | 404 | 10304 | Consent receipt not found. | | 409 | 12003 | MFA/OTP encountered. Note: Data Connect must resolve the MFA question. | | 401 | 12004 | Access consent is revoked for the current product of the account. | | 401 | 12005 | Access consent has expired for the current product of the account. | | 401 | 12006 | Access consent usage has reached the allowed usage limits for the current product of the account. | | 401 | 12007 | Access consent is not yet processed for the current product of the account. | | 500 | 12001 | An unexpected error has occurred. | --- # Using Webviews via the Web SDK source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/index.md Webviews enable you to display web content within a native application, without needing to launch a full browser experience. Data Connect Full, Lite and Fix can all be displayed within Webviews. We support the use of webviews to display the Data Connect experience in mobile apps without using our SDKs (see our [Non-SDK Integration Guide for iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-ios/index.md) and [Non-SDK Integration Guide for Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-android/index.md) pages), but our recommendation is to use either the Web SDK or one of the iOS, Android, or React Native SDKs. Note: In order to support App to App authentication make sure you pass a suitable `redirectUrl` parameter via the Data Connect Web SDK. See [Data Connect Web SDK App to App support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md#app-to-app-support). * [App to app using webviews with the Web SDK on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/ios-webviews/index.md) * [App to app using webviews with the Web SDK on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/android-webviews/index.md) --- # Android Applications source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/index.md If you are creating an Android app, we recommend using our Android SDK (or the cross-platform React Native SDK). You can also choose to use webviews to display the Data Connect interface, either with or without secure containers. We recommend using our Web SDK if you choose this route. App to app authentication is supported in all cases. * [Using the Data Connect Android SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md) * [Data Connect Android SDK Migration Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk-migration/index.md) * [Using secure web containers with the Web SDK on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/websdk-android/index.md) --- # Mastercard Data Connect Events source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/index.md This page contains a list of all the events that you can receive through the event listeners you will have created using either the web or mobile SDKs (see [Integrating with Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md) for details of the Data Connect SDKs provided). There are three different event types: * [Web SDK Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-websdk-events/index.md)---Monitor the Data Connect app. * [User Events (optional)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md)---Visibility into customer actions as they use the Data Connect app. * [Route Events (optional)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-route-events/index.md)---Visibility into customers as they navigate through the Data Connect app. --- # iOS Applications source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/index.md If you are creating an iOS app, we recommend using our iOS SDK (or the cross-platform React Native SDK). You can also choose to use webviews to display the Data Connect interface, either with or without secure containers. We recommend using our Web SDK if you choose this route. App to app authentication is supported in all cases. * [Using the Data Connect iOS SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md) * [Data Connect iOS SDK Migration Guide](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk-migration/index.md) * [Using secure web containers with the Web SDK on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/websdk-ios/index.md) --- # Understanding Account Data source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/understanding-account-data/index.md The account and transaction data elements returned from [Account Aggregation](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md) and [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) vary depending on the account type. The account types are grouped into data segments: * Deposit * Line Of Credit * Investment * Mortgage/Loans * Student loan For example, within deposits there will be savings and checking accounts, and for investments you will see 401K, IRA and many other types of retirement and non-retirement accounts. Within the `accounts` data, for some accounts / account types there will be a `details` array with additional account details (which will vary from one account type to another). The following sections show the typical structure of account data and the details data, and also how to understand the key identifiers within the data which can help you to identify and properly organize account data within your application. ## Account Data {#account-data} Account level data is universally available for all account types. A sample of the data is shown below. "accounts": [ { "id": "6060665493", "number": "xx0004", "realAccountNumberLast4": "0004", "accountNumberDisplay": "0004", "name": "Credit Card", "balance": -299.90, "type": "creditCard", "aggregationStatusCode": 0, "status": "active", "customerId": "6031425958", "institutionId": "102105", "balanceDate": 1695725297, "aggregationSuccessDate": 1695725297, "aggregationAttemptDate": 1695725297, "createdDate": 1691489793, "lastUpdatedDate": 1691489835, "currency": "USD", "lastTransactionDate": 1692103954, "institutionLoginId": 6028474654, "displayPosition": 4, "accountNickname": "Credit Card", "oldestTransactionDate": 1629374400, "marketSegment": "personal" } ] ## Account Details {#account-details} Data at the account details level provides additional insight into a particular account. Data elements in this level can be found in multiple segments depending on the account type being accessed. A sample showing the different account details for the respective account type is shown below. Note: The data elements that are returned vary depending on the financial institution and the account type. * Deposit * Line-of-Credit * Investment * Mortgage-Loans * Student-Loans ```Deposit "detail": { "dateAsOf": 1607450357, "availableBalanceAmount": 5678.78, "openDate": 1607450357, "periodStartDate": 1607450357, "periodEndDate": 1607450357, "periodInterestRate": 13.245, "periodDepositAmount": 2356.56, "periodInterestAmount": 1234.56, "interestYtdAmount": 1056.67, "interestPriorYtdAmount": 3056.79, "maturityDate": 1607450357, } ``` ```Line-Of-Credit "detail": { "dateAsOf": 1607450357, "interestRate": "15.789", "creditAvailableAmount": 3000, "creditMaxAmount": 7000, "cashAdvanceAvailableAmount": 2000, "cashAdvanceMaxAmount": 3000, "cashAdvanceBalance": 1000, "cashAdvanceInterestRate": 21.5, "currentBalance": 5789.34, "paymentMinAmount": 456.78, "paymentDueDate": 1607450357, "previousBalance": 1234.56, "statementStartDate": 1607450357, "statementEndDate": 1607450357, "statementPurchaseAmount": 2345.9, "statementFinanceAmount": 156.78, "statementCreditAmount": 345, "rewardEarnedBalance": 500, "pastDueAmount": 3688.99, "lastPaymentAmount": 567.89, "lastPaymentDate": 1607450357, "statementCloseBalance": 2456.69 } ``` ```Investment "detail": { "dateAsOf": 1607450357, "marginBalance": 456, "shortBalance": 1245.89, "availableCashBalance": 3549.78, "maturityValueAmount": 34067.78, "vestedBalance": 45000, "empMatchAmount": 256.99, "empPretaxContribAmount": 450, "empPretaxContribAmountYtd": 700, "contribTotalYtd": 2045, "cashBalanceAmount": 2000, "preTaxAmount": 78564.99, "afterTaxAmount": 68564.99, "matchAmount": 378, "profitSharingAmount": 34678.89, "rolloverAmount": 101234.67, "otherVestAmount": 34000, "otherNonvestAmount": 26000, "currentLoanBalance": 345789.23, "loanRate": 3.275, "buyPower": 34567.89, "rolloverLtd": 23456.78 }, ``` ```Mortgage-Loans "detail": { "dateAsOf": 1607450357, "availableBalanceAmount": 500.00, "interestRate": "15.789", "paymentMinAmount": 456.78, "lastPaymentAmount": 567.89, "termOfMl": "36", "mlHolderName": "John Smith", "description": "a description", "lateFeeAmount": 35, "payoffAmount": 45567.98, "payoffAmountDate": 1607450357, "originalMaturityDate": 1607450357, "principalBalance": 45056.7, "escrowBalance": 2345.01, "interestPeriod": "monthly", "initialMlAmount": 65000, "initialMlDate": 1607450357, "nextPaymentPrincipalAmount": 1256.67, "nextPaymentInterestAmount": 234.56, "nextPayment": 1578, "nextPaymentDate": 1607450357, "lastPaymentDueDate": 1607450357, "lastPaymentReceiveDate": 1607450357, "lastPaymentPrincipalAmount": 1256.67, "lastPaymentInterestAmount": 234.56, "lastPaymentEscrowAmount": 456.78, "lastPaymentLastFeeAmount": 150, "lastPaymentLateCharge": 50, "ytdPrincipalPaid": 5432.01, "ytdInterestPaid": 3948.56, "ytdInsurancePaid": 1345.89, "ytdTaxPaid": 1489, "autoPayEnrolled": true, "collateral": "nissan sentra", "firstPaymentDate": 1607450357, "firstMortgage": true, "loanPaymentFreq": "monthly", "recurringPaymentAmount": 456.23, "lender": "utah community credit union", "endingBalanceAmount": 234789.45, "loanTermType": "fixed", "paymentsMade": 14, "balloonAmount": 1678.56, "projectedInterest": 10456.78, "interestPaidLtd": 56789.34, "interestRateType": "variable", "loanPaymentType": "principle", "paymentsRemaining": 45 } ``` ```Student-Loans "detail": { "dateAsOf": 1607450357, "loanAwardId": "1234568", "loanAwardId": "1234568", "originalInterestRate": 12, "guarantor": "FinBank", "owner": "FinBank", "interestSubsidyType": "Subsidy type", "interestBalance": 2000, "remainingTermOfMl": 2, "initialInterestRate": 34567.89, "feesBalance": 150, "loanYtdInterestPaid": 5623.23, "loanYtdFeesPaid": 5621.23, "loanYtdPrincipalPaid": 5621.23, "loanStatus": "Deferment", "loanStatusStartDate": 1607450357, "loanStatusEndDate": 1607450357, "weightedInterestRate": 12, "repaymentPlanStartDate": 1607450357, "repaymentPlanEndDate": 1607450357, "repaymentPlan": "Standard", "expectedPayoffDate": 1607450357, "currentSchool": "utah valley university", "originalSchool": "brigham young university", "outOfSchoolDate": 1607450357, "convertToRepayment": 1607450357, "daysDelinquent": 5, "totalPrincipalPaid": 15000, "totalInterestPaid": 1125, "totalAmountPaid": 16125 } ``` ### Investment Account Positions {#investment-account-positions} Data at the account position level will only be populated for investment account types. A position will be returned for each specific investment or holding in a customer's account. The below example shows all the possible data elements within the position object. "position": [ { "id": 454678080, "description": "DELTA AIR LINES INC", "symbol": "DAL", "units": 6.537, "currentPrice": 41.585, "securityName": "DELTA AIR LINES INC", "transactionType": "Margin", "marketValue": 271.84, "costBasis": 190.01, "status": "A", "currentPriceDate": 1607450357, "securityType": "Stock", "mfType": "OPENEND", "posType": "Long", "totalGLDollar": 162742.9, "totalGLPercent": 68.89, "optionStrikePrice": 50, "optionType": "PUT", "optionSharesPerContract": 100, "optionExpireDate": "1644994800", "fiAssetClass": "COMNEQTY", "assetClass": "INTLSTOCK", "currencyRate": 1, "securityId": "25400W102", "securityIdType": "CUSIP", "costBasisPerShare": 13.38, "subAccountType": "CASH", "securityCurrency": "USD", "todayGLDollar": 16272.9, "todayGLPercent": 18.89 } ], "displayPosition": 2, "parentAccount": "5011648377" ## Understanding Key Account Identifiers {#understanding-key-account-identifiers} Customer account records have many data points that can be used in your application. You can properly identify accounts and organize account data inside of your application by using the following Mastercard assigned identifiers. ### Key Account Record Fields {#key-account-record-fields} Using the account key identifiers can not only help identify accounts, but organize them well within an application. | Field | Description | |----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | The Mastercard assigned unique account identifier. Use this for future account data retrieval and organization. | | `institutionId` | The Mastercard assigned unique identifier for the financial institution. Use this to organize accounts by financial institution. | | `institutionLoginId` | The Mastercard assigned unique identifier for the set of login credentials. Use this to organize accounts under a login group and give proper context to accounts at the same institution, but under different login sets. | | `type` | The Mastercard normalized account type, describing if the account is a checking, savings, loan, etc. Use this to determine how you will use accounts in your application, or filter accounts in Data Connect to enhance the user experience. | --- # How PSI Works source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/how-psi-works/index.md Note: This documentation has been updated to describe the latest PSI endpoints which add support for an unauthorized return score. For details of the legacy endpoints, see [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md). PSI offers two regulatory API versions: an [FCRA](https://www.ftc.gov/legal-library/browse/statutes/fair-credit-reporting-act)-compliant version and a non-FCRA version. Both versions use the same models and return the following: * **Non-sufficient funds (NSF) score** -- Risk of insufficient funds (R01) * Ranging from 0-100, forecasted up to 10 days to predict optimal payment timing * **Unauthorized return score** -- Risk of unauthorized return (R10) * Ranging from 0-100 for the current day ## Choosing a Version {#choosing-a-version} The FCRA version is required when rejecting transactions using the NSF score, while the Non-FCRA version can be used when timing transactions based on the NSF return days. Both versions support transaction rejection based on the unauthorized return score. [FCRA Version](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md) -- Use when evaluating transactions based on non-sufficient funds score \& unauthorized return score. * Requires that the [customer record](https://developer.mastercard.com/open-finance-us/documentation/access-and-config/customers/index.md) has an email address * Requires you to provide an [FCRA permissible purpose code](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) in the API request * Includes a consumer dispute process (via the [Finicity portal](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md#fcra-requirements-by-participant)) * FCRA-compliant
[Non-FCRA Version](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md) -- Use when evaluating transactions based only on the unauthorized return score. * Customer email address is optional * No dispute process required * Ideal for fraud mitigation without triggering FCRA compliance obligations
Both versions use the same non-sufficient funds \& unauthorized return models for the API response. ## Output Insights {#output-insights} ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi/output-insights.svg) ## Interpreting the Scores {#interpreting-the-scores} Each of the two risk scenarios is scored on a scale from 0 to 100, where **higher scores indicate lower risk**. Tip: Think of it like a school exam -- a higher score is better. * A score of 100 means that the transaction is highly likely to succeed or that the payment is very likely to be legitimate. * A score of 5, on the other hand, suggests the transaction is less likely to succeed, either due to non-sufficient funds or potential unauthorized returns. For example: * A **non-sufficient funds score of 5** means the account is unlikely to have enough funds to cover the transaction. * An **unauthorized return score of 5** could mean that the transaction was initiated by a third-party fraudster, or in some cases, by the actual account holder engaging in known first-party fraud. | Risk Score Value | Meaning | |------------------|------------------------------------------------------------------------------------------------------| | 0-10 | **High Risk** - the account has a high risk of insufficient funds or unauthorized fraud return | | 11-30 | **Medium Risk** - the account has a moderate risk of insufficient funds or unauthorized fraud return | | 31-100 | **Low Risk** - the account has a low risk of insufficient funds or unauthorized fraud return | Tip: You will receive NSF risk scores for the current day and up to 10 days in the future. Consider settling on the day with the highest NSF score (lowest risk), while factoring in the unauthorized return score. Note: The score interpretation provided here is for general guidance only. Actual performance may vary based on your specific transaction data and risk tolerance. The PSI team can assist in performing this analysis and sharing tailored threshold recommendations. ## Interpreting the Optional Reason Codes {#interpreting-the-optional-reason-codes} Reason codes help explain what's driving the non-sufficient funds `compositeScore` value (this feature is currently only available for the NSF scores). You can think of reason codes as impact scores showing which factors had the most influence. There are 8 possible reason codes: | **Reason Code** | **Description** | |-------------------|----------------------------------------------------| | recentBalance | Balance trends over a recent time period | | balanceHistory | Balance trends over a complete time period | | nsfHistory | Returns over a complete time period | | recentNsfHistory | Returns over a recent time period | | recurringNsf | Pattern of repeat behavior for NSF | | spendHistory | Spend trends over a complete time period | | depositHistory | Deposit trends over a complete time period | | transactionAmount | Amount relative to a typical spend for the account | * Higher reason code values (e.g. 81-100) mean those reasons had a **strong impact** on the overall score. * These reasons can be **positive or negative** --- meaning that they could either increase or decrease the risk scores. | Reason Code Value | Meaning | |-------------------|--------------------------------------------------------------------------------------| | 0-50 | **Low Influence** - the reason code has low to no influence on the composite score | | 51-80 | **Medium Influence** - the reason code has moderate influence on the composite score | | 81-100 | **High Influence** - the reason code has high influence on the composite score | Examples: ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi/risk-scores.svg) --- # 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 } ] } ``` --- # PSI FCRA source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md Note: This documentation has been updated to describe the latest PSI endpoints which add support for an unauthorized return score. For details of the legacy endpoints, see [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md). ## PSI FCRA Flow {#psi-fcra-flow} Diagram psi-fcra ## Execution Steps {#execution-steps} 1. Customer Consent: The merchant/fintech/PSP obtains customer consent to share bank data when setting up recurring payments. 2. PSI Request: A PSI FCRA request is sent prior to payment initiation via a **POST** call. 3. Risk Assessment: Mastercard analyzes the account and returns NSF and unauthorized return risk scores via a **GET** call. 4. Payment Decision: The merchant makes a decision. * If using PSI FCRA, the customer must receive a link to the [Finicity Consumer Portal](https://consumer.finicityreports.com/) to dispute decisions. Note: For PSI FCRA: * the [customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) must include an email address. * the API request must include an FCRA [permissible purpose code](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md). ## Technical Documentation {#technical-documentation} Refer to the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) for creating a [customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) record using your `partnerId` and generating a [Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) URL to use this service. Note that the endpoints require [authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). API Reference: `POST /payments/customers/{customerId}/accounts/{accountId}/fcra-payment-success-indicators` **Generate FCRA Payment Success Indicators** returns a `payRequestId` - use it to call the endpoint below and retrieve the PSI scores. API Reference: `GET /payments/customers/{customerId}/accounts/{accountId}/fcra-payment-success-indicators/{payRequestId}` Tip: If you want the optional NSF reason codes, set `include_reasons` to `true` when calling the above endpoint. If the PSI data is not yet ready, **Get FCRA Payment Success Indicators by Pay Request ID** returns a `status` value of `IN PROGRESS`. You can poll the endpoint until the data is available. If you are making multiple GET requests immediately after calling **Generate Non-FCRA Payment Success Indicators**, wait 0.5 to 1 second between each GET request. We recommend integrating with the [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md#get-available-balance) endpoint as a fallback. Your solution should first call **Get FCRA Payment Success Indicators by Pay Request ID** , then use **Get Available Balance** if the PSI request fails, so you can still retrieve the customer's available balance. ## Understanding the PSI Response Data {#understanding-the-psi-response-data} * The `nsfReturnRisk` and `unauthorizedReturnRisk` tiers correspond to the `score` value. There are 3 possible tiers: * `score` 0-10 corresponds to "High Risk" * `score` 11-30 corresponds to "Medium Risk" * `score` 31-100 corresponds to "Low Risk" * The `reasons` array for each day with the `nsfReturnRisk` can be used to see why the score for a given day was generated. Reasons can be interpreted as both negative and positive drivers, influencing the `score` value. For example: * `score` 100 and `nsfHistory` 100 may be interpreted as that this account has had few, if any, NSF occurrences in the past, and it is **unlikely** to result in NSF. * `score` 10 and `nsfHistory` 100 may be interpreted as that this account has multiple NSF occurrences in the past, and it is **likely** to result in NSF.
See [Interpreting the Scores](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/how-psi-works/index.md#interpreting-the-scores) for full details. ## Error Codes {#error-codes} The following table lists the errors that are specific to this API. See also the [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) section for a list of general errors and status codes which can occur. Warning: In some cases, a server-side failure can result in an HTTP 200 response being returned with an internal error (such as 18002) in the response body. This is a known issue which we are working to resolve. Retry the request and contact your Customer Success Manager if the problem persists. | **HTTP Code** | **Status Code** | **Description** | **Remediation for Partner** | |---------------|-----------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | 10005 | "invalid purpose code" | [Permissible purpose code](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) must be "1P" for a payments use case. | | 400 | 10006 | "settleByDate must not be in the past" | Call the PSI endpoint with a `settleByDate` value equal to today or for a future date. | | 400 | 10007 | "\[FIELD\] is the incorrect type" | Call the PSI endpoint with correct type for the identified field. | | 400 | 10008 | "account has no transactions" | This indicates that the consumer's account does not have sufficient transaction history to produce a risk score with confidence. You may decline or accept the transaction. | | 400 | 10009 | "\[FIELD\] is a required parameter" | Call the PSI endpoint with the identified field provided. | | 400 | 10013 | "Only active accounts can be used, please use a different account" | The customer must select an active account when linking their accounts. | | 400 | 12022 | "An email is required when registering a customer for PSI-FCRA" | Add customer email during the [create customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) process. | | 401 | 24302 | "Bad credentials" | Call the PSI endpoint with a valid app key and token. If this doesn't work, it is possible that your account is locked due to security reasons (normally as a result of multiple failed attempts). Contact customer support to unlock your account. | | 404 | 14001 | "customerId not found" | Ensure you are using the correct customer ID. If the customer ID is correct, it might be that the account has had no activity for a long period leading to an inactive status.​ | | 404 | 38003 | "accountId not found" | Ensure you are using the correct account ID and that the customer has connected their account. | ## Testing {#testing} See the [Payment Success Indicator Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-success-indicator-profiles) section of [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) for details of banking profiles which are provided for testing purposes. These profiles are designed to return different PSI scores for different payment amounts and settlement dates. ## FCRA Considerations {#fcra-considerations} This section is intended for product, compliance, and operational teams to understand and implement The Fair Credit Reporting Act (FCRA) requirements and responsibilities. ### FCRA Background {#fcra-background} The Fair Credit Reporting Act (FCRA) regulates access to and accuracy of consumer reports and enables consumers to see and dispute the content of the consumer reports prepared on them. Companies and persons seeking to obtain a consumer report must have a legally permissible purpose enumerated under the FCRA, such as decisioning an application for credit, insurance, employment, or other defined purposes. Additionally, the FCRA requires that report users notify the consumer when an adverse action is taken based on such reports. ### FCRA Applicability {#fcra-applicability} The FCRA applies when a consumer's credit or other financial account and personal information is provided by a consumer reporting agency to a third party to inform that third-party's decisions about a consumer's eligibility, such as their eligibility for credit, housing, employment, or other business purposes. With respect to PSI, the FCRA is applicable to use cases where a merchant intends on leveraging PSI to determine whether to accept or reject consumer payment transactions and/or provide instant access to funds or services. ### FCRA Requirements {#fcra-requirements} For products and use cases that are subject to FCRA, consumers are granted several rights, including the right to be notified that an adverse action has been taken against them; the right to access their file, which must include the data compiled on them to generate a consumer report; and the right to dispute and have corrected any incomplete, inaccurate, or unverifiable information in that file. ### FCRA Requirements by Participant {#fcra-requirements-by-participant} | **Requirement and Description** | **Responsible Party and Guidelines** | |------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Notification:** Consumers must be notified that an adverse action, such as a rejected transaction, has been taken against them. | **Partner:** Partners using PSI FCRA must update their experience to notify the consumer. The notification must include the Pay Request ID and link to the Finicity Consumer Portal. An example notification is captured below. We recommend that you store the Pay Request ID for 60 days, as consumers are allotted 60 days to initiate a dispute. | | **Consumer Report Disclosure:** Consumers must be provided access to review information in consumer reports on them. | **Finicity:** Finicity provides, as part of the Consumer Portal, the Consumer Report Disclosure, which was designed in compliance with regulatory requirements and with the end consumer in mind. | | **Consumer Disputes via Portal:** Consumers must have the ability to review and dispute the information in their consumer reports. | **Finicity:** Finicity provides a Consumer Portal, where the consumer can view his/her report and is assisted by our dedicated Disputes Team. The Consumer Portal is located at [`https://consumer.finicityreports.com/`](https://consumer.finicityreports.com/). For more information on how consumers can use the portal, see the [consumer-facing guidance](https://www.mastercard.com/us/en/business/open-finance/consumer.html). | ### Example FCRA Notification {#example-fcra-notification} The following example user flow shows how a merchant app might use PSI to assess the risk of accepting a payment, and display an alert to the consumer with a link to the Finicity consumer dispute portal if the payment is not accepted as a result. The consumer must also be provided with the Pay Request ID relating to the payment in question. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi-fcra-notification-cx_1.png) ### FCRA Consumer Journey in the Finicity Consumer Portal {#fcra-consumer-journey-in-the-finicity-consumer-portal} The following screens show a typical user journey in the consumer portal. The consumer will need to create an account (if they don't already have one), authenticate themselves, and then provide the Pay Request ID they were given by the merchant. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi-fcra-dispute-portal-cx-1_1.png) The consumer portal will then provide information about the PSI report so they can file a dispute if they think something is wrong. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi-fcra-dispute-portal-cx-2_1.png) --- # PSI Non-FCRA source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md Note: This documentation has been updated to describe the latest PSI endpoints which add support for an unauthorized return score. For details of the legacy endpoints, see [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md). ## PSI Non-FCRA Flow {#psi-non-fcra-flow} Diagram psi ## Execution Steps {#execution-steps} 1. Consumer Consent: The merchant/fintech/PSP obtains consumer consent to share bank data when setting up recurring payments. 2. PSI Request: A PSI Non-FCRA request is sent prior to payment initiation via a **POST** call 3. Risk Assessment: Mastercard analyzes the account and returns NSF and unauthorised return risk scores via a **GET** call 4. Payment Decision: The merchant makes a decision. ## Technical Documentation {#technical-documentation} Refer to the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) for creating a [Customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) record using your `partnerId` and generating a [Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) URL to use this service. Note that the endpoints require [Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). API Reference: `POST /payments/customers/{customerId}/accounts/{accountId}/payment-success-indicators` **Generate Payment Success Indicators** returns a `payRequestId` - use it to call the endpoint below and retrieve the PSI scores. API Reference: `GET /payments/customers/{customerId}/accounts/{accountId}/payment-success-indicators/{payRequestId}` Tip: If you want the optional NSF reason codes, set `include_reasons` to `true` when calling the above endpoint. If the PSI data is not yet ready, **Get Non-FCRA Payment Success Indicators by Pay Request ID** returns a `status` value of `IN PROGRESS`. You can poll the endpoint until the data is available. If you are making multiple GET requests immediately after calling **Generate FCRA Payment Success Indicators**, wait 0.5 to 1 second between each GET request. We recommend integrating with the [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md#get-available-balance) endpoint as a fallback. Your solution should first call **Get Non-FCRA Payment Success Indicators by Pay Request ID** , then use **Get Available Balance** if the PSI request fails, so you can still retrieve the customer's available balance. ## Understanding the PSI Response Data {#understanding-the-psi-response-data} * The `nsfReturnRisk` and `unauthorizedReturnRisk` tiers correspond to the `score` value. There are 3 possible tiers: * `score` 0-10 corresponds to "High Risk" * `score` 11-30 corresponds to "Medium Risk" * `score` 31-100 corresponds to "Low Risk" * The `reasons` array for each day with the `nsfReturnRisk` can be used to see why the score for a given day was generated. Reasons can be interpreted as both negative and positive drivers, influencing the `score` value. For example: * `score` 100 and `nsfHistory` 100 may be interpreted as that this account has had few, if any, NSF occurrences in the past, and it is **unlikely** to result in NSF. * `score` 10 and `nsfHistory` 100 may be interpreted as that this account has multiple NSF occurrences in the past, and it is **likely** to result in NSF.
See [Interpreting the Scores](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/how-psi-works/index.md#interpreting-the-scores) for full details. ## Error Codes {#error-codes} The following table lists the errors that are specific to this API. See also the [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) section for a list of general errors and status codes which can occur. Warning: In some cases, a server-side failure can result in an HTTP 200 response being returned with an internal error (such as 18002) in the response body. This is a known issue which we are working to resolve. Retry the request and contact your Customer Success Manager if the problem persists. | **HTTP Code** | **Status Code** | **Description** | **Remediation for Partner** | |---------------|-----------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | 10006 | "settleByDate must not be in the past" | Call the PSI endpoint with a `settleByDate` value equal to today or for a future date. | | 400 | 10007 | "\[FIELD\] is the incorrect type" | Call the PSI endpoint with correct type for the identified field. | | 400 | 10008 | "account has no transactions" | This indicates that the consumer's account does not have sufficient transaction history to produce a risk score with confidence. You may decline or accept the transaction. | | 400 | 10009 | "\[FIELD\] is a required parameter" | Call the PSI endpoint with the identified field provided. | | 400 | 10013 | "Only active accounts can be used, please use a different account" | The customer must select an active account when linking their accounts. | | 401 | 24302 | "Bad credentials" | Call the PSI endpoint with a valid app key and token. If this doesn't work, it is possible that your account is locked due to security reasons (normally as a result of multiple failed attempts). If this happens, contact customer support to unlock your account. | | 404 | 14001 | "customerId not found" | Ensure you are using the correct customer ID. If the customer ID is correct, it might be that the account has had no activity for a long period leading to an inactive status. | | 404 | 38003 | "accountId not found" | Ensure you are using the correct account ID and that the customer has connected their account. | ## Testing {#testing} See the [Payment Success Indicator Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-success-indicator-profiles) section of [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) for details of banking profiles which are provided for testing purposes. These profiles are designed to return different PSI scores for different payment amounts and settlement dates. --- # Historical Data Sharing source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/historical-data-sharing/index.md To support ongoing model improvement and ensure alignment with evolving fraud trends, partners are required to share historical transaction data with us securely via [Feedback Loop](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md). Whether using the PSI [FCRA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md) or [Non-FCRA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi/index.md) endpoints, this data is essential for evaluating and fine-tuning model performance. Warning: To enable data sharing, you must ensure you **store the required fields in your own systems** so that they can be provided to us via Feedback Loop. The following fields are required when submitting historical data to Feedback Loop and must be uploaded as a CSV file. See the Feedback Loop [Submission Format](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/index.md#submission-format) documentation for full details. | Field Name | Data Type | Description | Required | Notes | |--------------------|-----------|------------------------------------------------------------|----------|---------------------------------------------------------------| | `partnerId` | integer | Production partner ID provided by Mastercard | Y | Must exist in system | | `customerId` | integer | Customer ID provided by Mastercard | Y | Must exist in system | | `payReqId` | string | ID of the payment transaction this feedback relates to | Y | Use payment request ID (`payReqId`) from earlier PSI response | | `paymentId` | string | Partner-provided identifier to track/update payment status | Y | Helps correlate multiple submissions (e.g. retries) | | `settled` | string | Indicates whether the transaction settled | Y | Values: `Y` or `N` | | `initiationAmount` | decimal | Value of the transaction | Y | Digits or decimal | | `initiationDate` | string | Date the transaction was initiated | Y | Provide actual initiation timestamp | | `settledDate` | string | Date the transaction settled | Y | Leave blank if `settled = N` | | `returnDate` | string | Date the transaction was returned (yyyy-mm-dd) | Y | Leave blank if `settled = Y` | | `returnReason` | string | Reason the transaction was returned (e.g. ACH return code) | Y | Leave blank if `settled = Y` | --- # Mastercard Data Connect Components Webhooks source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebhooks/index.md Mastercard Data Connect Components will soon provide real-time webhook notifications when specific events occur. Integrating with webhooks is optional. SDK events also provide the same information. Note: Support for Data Connect Components webhooks is provided through the **Open Banking Webhook Management System** (OBWMS). OBWMS is currently being redeveloped to address additional use cases. Components webhooks are expected to be available through the updated OBWMS service in mid 2026. For an overview of OBWMS, see the [Open Banking Webhook Management System](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md) documentation. --- # Data Refresh source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md Mastercard automatically updates the data from accounts added by customers during our nightly batch aggregation. As long as those accounts have an active `aggregationStatusCode` equal to 0, indicating the account is ready for aggregation, Mastercard continues updating the account details to stay current with the host financial institution. The `aggregationSuccessDate` field indicates the timestamp of the last successful aggregation of the account. When there is a specific business case, account data may also be refreshed on demand by using the Account Refresh Service. Discuss with your Account Manager and Solution Engineer for further clarification. Client applications are not permitted to automate calls to the data refresh service. As many financial institutions only post transactions once per day, calling the data refresh service repeatedly is usually a waste of resources and could have an adverse impact on your integration. ## Asynchronous Data Refresh Endpoints {#asynchronous-data-refresh-endpoints} The asynchronous Data Refresh endpoints enable you to trigger an asynchronous refresh of transaction data for a customer's accounts. We recommend using these endpoints for new integrations instead of the [legacy endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#legacy-refresh-endpoints) described below. You can choose to refresh specific accounts, or all accounts linked to a provided institution login ID. You can also choose the date range of transactions to refresh. 1. Call **Trigger Customer Account Refresh** with a request body specifying either an `institutionLoginId` or a list of `accountIds`. If both are provided, `accountIds` takes priority. Use the `mode` parameter to specify the date range for the refresh (refer to [Refresh Modes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-modes) on this page). API Reference: `POST /aggregation/customers/{customerId}/transactions/refreshes` 2. The endpoint returns a `202 Accepted` response containing a `refreshId`, a `createdAt` value (an ISO 8601 date-time value with timezone describing when the refresh request was created) and an initial `status` of `NEW`. Note: Identical **Trigger Customer Account Refresh** requests within 5 minutes of each other are treated as duplicates: the same `refreshId` is returned and no new refresh is triggered. If more than 5 minutes have passed since the last identical request, a new refresh is triggered. 3. Either: * Poll **Get Customer Account Refresh Status** with the `refreshId` until the status is `COMPLETED` or `FAILED` (refer to [Refresh Status Values](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-status-values) on this page for details). API Reference: `GET /aggregation/customers/{customerId}/transactions/refreshes/{refreshId}` * Subscribe to the `data-refresh.transaction.status-changed` webhook event through [OBWMS](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md) to receive the same data provided by the Get Customer Account Refresh Status response when processing completes.
The response always returns all fields shown in the `TransactionRefreshStatusDetails` object except `aggregationStatusCode` and `aggregationSuccessDate`, which are optional. Tip: A `COMPLETED` status does not mean every account refreshed successfully. The response includes `totalCount`, `successCount`, and `failedCount` fields, along with per-account `aggregationStatusCode` values. Check these to confirm which accounts were refreshed and which encountered errors. 4. Retrieve the refreshed transaction data using the standard transaction endpoints, for example: * [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetAllCustomerTransactions) * [Get Customer Account Transactions](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccountTransactions) ### Refresh Modes {#refresh-modes} | Mode | Description | Date range | Billing | |------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `standard` | Standard refresh (default) | Last 6 months (`fromDate` and `toDate` are ignored) | Non-billable | | `historic` | Extended historical load | Last 2 years (`fromDate` and `toDate` are ignored) | Billable (uses [Load Historic Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#load-historic-transactions)) | | `custom` | Custom date range | `fromDate` is required `fromDate` cannot be more than 2 years in the past; values before 2 years ago return a 400 error `toDate` defaults to the current date if not provided | Billable if `fromDate` is more than 6 months in the past | Note: For `custom` mode, `fromDate` and `toDate` use ISO 8601 date-time format with timezone, for example `2022-03-10T06:06:20.042Z`. This differs from most other Open Finance endpoints, which use Unix epoch timestamps. ### Refresh Status Values {#refresh-status-values} | Status | Description | |---------------|----------------------------------------------------------------------------------------------------| | `NEW` | Refresh request received | | `IN_PROGRESS` | Refresh is running | | `COMPLETED` | The overall operation has finished; check `successCount` and `failedCount` for per-account results | | `FAILED` | The refresh failed for all accounts |
## Legacy Refresh Endpoints {#legacy-refresh-endpoints} There are two sets of legacy synchronous refresh endpoints. Note: You must use the correct pair of endpoints depending on whether you use Data Access Tiers or Standalone services: * If you are using Data Access Tiers (ASD, AFD, or ATD), you must use the V2 Refresh endpoints. * If you are using the standalone Account Limited Aggregation (ALA) and Transaction Access (TAU), you must use the V1 Refresh endpoints. See [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) for more information about the different tiers. The recommended timeout setting for this request is 180 seconds in order to receive a response. However, a terminated call prior to a response does not terminate the refresh. Evidence of a refresh request can be found in the `aggregationAttemptDate` field, and data can be retrieved through the Account Aggregation and Transaction Aggregation services. ### Refresh Endpoints for Data Access Tiers (V2) {#refresh-endpoints-for-data-access-tiers-v2} If you are using Data Access Tiers (ASD, AFD, ATD), use the V2 endpoints in this section. Refresh customer account data for all accounts: API Reference: `POST /aggregation/v2/customers/{customerId}/accounts` Refresh customer account data for all accounts associated with a given financial institution: API Reference: `POST /aggregation/v2/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts`
### Refresh Endpoints for Standalone Services (V1) {#refresh-endpoints-for-standalone-services-v1} If you are using the standalone Account Limited Access (ALA) service and not using Data Access Tiers, use the V1 endpoints in this section. Note these are not suitable if you are using any of the Data Access Tiers products (ASD, AFD, ATD). Refresh customer account data for all accounts: API Reference: `POST /aggregation/v1/customers/{customerId}/accounts` Refresh customer account data for all accounts associated with a given institution login ID with a connection to the institution: API Reference: `POST /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts` --- # Payment Risk Insights (Consumer) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/payment-risk-insights/index.md Note: This documentation is for consumer use cases. For Small Business use cases, see [Payment Risk Insights (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md). ## Overview {#overview} The Payment Risk Insights report retrieves up to 24 months of transaction history from connected accounts, and calculates a risk score based on a customer's financial history. The risk score can be used to determine the probability that a customer will experience a payment risk event, such as Non-Sufficient Funds/Overdraft or missed recurring payments, in the near future when making a payment. #### Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months * **Payment Risk Insights Analytics:** * Monthly average income over the previous 24 months * Total deposit amount by month for all accounts and level of confidence that it represents income * Total withdrawal amount by month for all accounts * Number of NSF counts and aggregate amount per month * Recurring loan payment amounts per month * Insurance payment amount per month * Tax payment amounts per month * **Risk Score** representing the likelihood of a missed payment * **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar #### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshing a report is billable at a discounted rate. * **Supported Account Types**: Checking, Savings * **Supported Report Format:** JSON and PDF #### Use Cases {#use-cases} The following use cases apply to consumer Payment Risk Insights reports: * **Personal Lending** - Lenders can use the risk score and attributes to assess a consumer's likelihood of missing a payment when underwriting personal loans. * **Credit Card Issuance** - Issuers can incorporate Payment Risk Insights into their decision process for new credit card applications. * **Account Management** - Lenders can use Payment Risk Insights to make account management decisions such as credit limit adjustments and interest rate changes. * **Tenant Screening** - Property managers can use the report to assess the payment reliability of prospective tenants. #### Sequence Diagram {#sequence-diagram} Diagram payment-history-report ## How it Works {#how-it-works} ### Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API. * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers). * [Create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record for the customer. * [Generate a connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows). ### Generate a Payment Risk Insights Report {#generate-a-payment-risk-insights-report} To generate or refresh a Payment Risk Insights Report use the following endpoint: API Reference: `POST /decisioning/customers/{customerId}/reports/payment-risk-insights/userTypes/{userType}` Set the `userType` path parameter to `personal` for consumer reports. The response includes the status of the report generation and a report ID. If you are using report webhooks (recommended), a notification is sent to the webhook listener when report generation is complete or an error occurs (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). If you are not using report webhooks, you can poll one of the [Get Report endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) every 20 seconds until the report is returned. #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * Use `timeIntervalType` to select the period at which attributes will be calculated. Defaults to Monthly Calendar. Customize the type of Payment Risk Insights report received based on inputs provided when generating the report: | **Report Type** | **User Type** (required) | **forCraPurpose** (required) | **Consumer Required?** | **Customer Required?** | |-----------------|--------------------------|------------------------------|------------------------|------------------------| | pripcra | personal | true | Y | Y | | pripnoncra | personal | false | N | Y | Note: The CRA version of the Payment Risk Insights Report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and you must provide a [permissible purpose](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) code when retrieving the report. Provision and use of this report is subject to all applicable obligations of the FCRA.
## Get Payment Risk Insights Reports {#get-payment-risk-insights-reports} Once the report is generated, retrieve the report using one of the [Get Report](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Reports {#example-reports} The Get Report response contains different data depending on the type of report requested. The following examples show what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. * `pripcra` (CRA) report: [example-pripcra.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/example-json/example-pripcra.json) (279KB) * `pripnoncra` (Non-CRA) report: [example-pripnoncra.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/example-json/example-pripnoncra.json) (279KB) ### PDF Version {#pdf-version} A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. To receive a PDF version of the report, set the `Accept` request header to `application/pdf` - otherwise, the report is returned as JSON. * Example Payment Risk Insights PDF report: [Payment_Risk_Insights_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/Payment_Risk_Insights_Example_Report.pdf) (675KB) * How to read a Payment Risk Insights PDF report: [PRI_HtR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/pri/PRI_HtR.pdf) (9MB) ## Reading a Payment Risk Insights JSON Report {#reading-a-payment-risk-insights-json-report} This section provides a detailed description of the structure and format of the Payment Risk Insights Report JSON report. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. The JSON report is generated to provide data in a structured and machine-readable format. #### Payment Risk Insights Report Attributes {#payment-risk-insights-report-attributes} | **Attribute** | **Definition** | **Type** | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | ASSET_BALANCE | History of asset balances for the customer and their accounts. | State | | NSF_FEE_CHARGES | Fees charged to the customer by their financial institution resulting from a lack of sufficient funds or low balance to cover a purchase. | Transactional | | CASH_INFLOW | Credit transactions in a customer's account. | Transactional | | CASH_OUTFLOW | Debit / Spend transactions in a customer's account. | Transactional | | DISCRETIONARY_SPENDING | Spend towards expenses that are not required either for core business operations (in the case of a business customer) or living expenses (in the case of a consumer customer). | Transactional | | NONDISCRETIONARY_SPENDING | Spend towards expenses that are required for core business operations or living expenses. | Transactional | | INSURANCE_SPENDING | Payments made towards an insurance company. | Transactional | | TAX_PAYMENTS | Payments made towards a tax collection agency such as the IRS. | Transactional | | RECURRING_EXPENSES | Payments made towards expenses that typically recur over time. | Transactional | | DIVIDEND_INCOME | Dividend income is received as a stock shareholder's right for owning equity in a publicly traded company. | Transactional | | MISSED_RECURRING_EXPENSES | Payments toward recurring expenses that were missed by the customer during the reporting period. | State | | RECURRING_LOAN_PAYMENTS | Payments made towards loans that recur over time. | Transactional | | MISSED_RECURRING_LOAN_PAYMENTS | Payments toward loans that were missed by the customer during the reporting period. | State | | PAYMENT_RISK_SCORE | A score value between 0 and 100 that indicates the riskiness of the customer to miss an upcoming payment. Higher values indicate higher risk. The score has four levels: Low (0-25), Medium (26-50), Medium-High (51-75), and High (76-100). | State | ### Sample JSON Report {#sample-json-report} The JSON sample is an output of the PRI profile profile-2750-2756 used in the sandbox (for your own testing you can use one of the [Payment Risk Insights test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profiles) with FinBank Profiles - A): [phrbcra-profile-2750-2756.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/phrbcra-profile-2750-2756.json) (266KB) ### Time Interval Types {#time-interval-types} A report supports up to two time interval types. If a partner requests for more than two interval types, then the end point gives the error `More than 2 intervalTypes passed request.` If the time interval type is not specified, the default is MONTHLY_CALENDAR. The table shows all possible time interval types for which a partner can request a report. | Time Interval Type | Description | First (Earliest) period may be partial | First (Most recent) period may be partial | Shortest possible period length | Longest possible period length | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------| | DAILY | The report will be broken up into one period for every calendar date in the report time period. | NO | NO | 1 | 1 | | WEEKLY_CALENDAR | The report time period will be broken up into periods of seven calendar dates, with each period beginning on a Monday and ending on a Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 7 | | WEEKLY_ROLLING_7 | The report time period will be broken up into periods of seven calendar dates, counting backwards from the report end date. | YES | NO | 1 | 7 | | BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, with each period beginning on a Monday and ending on the second subsequent Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 14 | | BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date. | YES | NO | 1 | 14 | | SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly two periods per calendar month, where both the first and the last period may be partial, and periods will alternate between representing the 1st-15th of the month and the 16th-end of the month. | YES | YES | 1 | 16 | | MONTHLY_CALENDAR | The report time period will be broken up into one period per calendar month. | YES | YES | 1 | 31 | | MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by one period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 36 | | QUARTERLY_CALENDAR | The report time period will be broken up into one period per three calendar months, where both the first and last period may be partial. | YES | YES | 1 | 92 | | QUARTERLY_ROLLING_90 | The report time period will be broken up into three periods of 90 calendar dates followed by one period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 96 | | ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date. | YES | NO | 1 | 366 | | HISTORICALLY | The report time period will be represented by exactly one period. | NO | NO | 1 | Duration of report data | The JSON snippet shows an example of how a time interval type is represented. * JsonS ```jsonS "constraints": { "analyticsReportData": { "timeIntervalTypes": [ "MONTHLY_CALENDAR", "ANNUALLY" ] } } ```
### JSON report structure - Analytics section {#json-report-structure---analytics-section} Analytics will be provided at the account level, grouped by financial institution and at an aggregated customer level. The following examples show a customer with two accounts that contain transactions. * Json ```json "accounts": [ {"id": 3034460414}, {"id": 3034460415} ] ``` The analytics section is divided into three sections. * Transactional attributes * State attributes * Streams **Account-level analytics structure** This section is for each of the customer accounts. * Json ```json "analytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ```
**Customer-level analytics structure** * Json ```json "customerAnalytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ```
#### Transactional attributes {#transactional-attributes} Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. For example, an attribute called DWELLING_EXPENSES may be a classification of all transactions that we assume to be a customer paying towards a mortgage, rent, home insurance and so on. The following sample JSON snippets are for transactional attributes at an accounts and customer level. * The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months. * The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates. * Not all attributes are showcased. Refer to the attribute table to view all PRI attributes. * The data in the snippets are for profile-2750-2756 with some modifications. * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2023-07-31", "max": -7.16, "mean": -7.16, "median": -7.16, "min": -7.16, "standardDeviation": 0.14142135623730964, "startDate": "2023-07-01", "sum": -7.16, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] } ] }, { "periods": [ { "count": 7, "endDate": "2024-03-04", "max": -12.17, "mean": -7.55, "median": -7.16, "min": -3.07, "standardDeviation": 0.14142135623730964, "startDate": "2023-03-05", "sum": -42.96, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "107337ef-fa51-48cf-a70b-81144fb1e6e8" ], "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980" ], "projectedValues": [], "streamConfidences": null } ] ``` * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-07-31", "max": -9.75, "mean": -6.888888, "median": -6.888888, "min": -4.01, "standardDeviation": -4.0587929, "startDate": "2023-07-01", "sum": -13.76, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] } ] }, { "periods": [ { "count": 5, "endDate": "2024-03-04", "max": -14.01, "mean": -8.10, "median": -7.85, "min": -3.94, "standardDeviation": 0.45253246733731172, "startDate": "2023-03-05", "sum": -47.46, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "5c6c913a-62dc-4d07-b4ed-28fbb68f9995" ], "transactionIds": [ "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ], "projectedValues": [], "streamConfidences": null } ] ``` * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 3, "endDate": "2023-07-31", "max": -9.75, "mean": -7.16, "median": -7.16, "min": -3.07, "standardDeviation": 0.0, "startDate": "2023-07-01", "sum": -14.32, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-01-01", "cohortValues": [] } ] }, { "periods": [ { "count": 12, "endDate": "2024-03-04", "max": -14.01, "mean": -7.69, "median": -7.51, "min": -3.07, "standardDeviation": 0.25061422791045044, "startDate": "2023-03-05", "sum": -90.42, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "107337ef-fa51-48cf-a70b-81144fb1e6e8", "5c6c913a-62dc-4d07-b4ed-28fbb68f9995" ], "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980", "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ], "projectedValues": [], "streamConfidences": null } ] ``` **JSON fields description** | Key (Datatype) | Description | Applicable for PRI | |---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| | aggregatedByTimePeriods (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes | | periods (object) | Statistics of aggregated transactions over some time period. | Yes | | count (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes | | endDate (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes | | max (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes | | mean (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for a monthly time interval, mean will be shown for each month of a year. | Yes | | median (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for a monthly time interval, the median will be shown for each month of a year. | Yes | | min (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for a monthly time interval, the min will be shown for each month of a year. | Yes | | standardDeviation (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for a monthly time interval, the standardDeviation will be shown for each month of a year. | Yes | | startDate (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for a monthly time interval, the startDate will be shown for each month of a year. | Yes | | sum (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for a time interval, the sum will be shown for each month of a year. | Yes | | comparedToCohorts (object) | An array of elements comparing the customer's income / spending during a time period to the average customer's income / spending in various cohorts, such as postal code, during the same time period. | No | | cohortType (string) | Describes the type of cohort being compared to for this period, for example POSTAL_CODE. This field will be empty as it is not applicable for PRI. | No | | totalDifferenceToCohort (number) | Reflects the difference between the customer's income / spending value for the period minus that of the average income / spending in this cohort. This field will be empty as it is not applicable for PRI. | No | | percentageDifferenceToCohort (number) | Reflects the percentage difference between the customer's income / spending value for the period and the average income / spending of the cohort. This field will be empty as it is not applicable for PRI. | No | | timeIntervalType (string) | Refer to Time Interval Types for how each period is defined. | Yes | | cohortBenchmarkPeriods (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the income / spending of cohorts in the customer's zip code during that period for an attribute. | No | | startDate (string) | The first day of the cohort benchmark period. | No | | endDate (string) | The final day of the cohort benchmark period. | No | | cohortValues (object) | An object that contains the type and value of a cohort benchmark period. This field will be empty as it is not applicable for PRI. | No | | cohortType (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, for example POSTAL_CODE. This field will be empty as it is not applicable for PRI. | No | | value (number) | For each cohort benchmark period, the average income / spending for the cohort during this time period. This field will be empty as it is not applicable for PRI. | No | | attributeName (string) | Name of the transactional / state / stream attribute that we are reporting the numbers for. Refer to the Payment Risk Insights Report Attributes. | Yes | | streamIds | List of stream IDs associated with the attribute. | Yes | | transactionIds(object) | List of transaction IDs associated with the attribute (a classification). | Yes | | projectedValues (object) | List of projection objects, where each object indicates the projected income / spending value of the attribute over some coming period of time. This field will be empty as it is not applicable for PRI. | No | | timeUnit (string) | The unit of time being described, for example MONTHS. This field will be empty as it is not applicable for PRI. | No | | timeValue (number) | The number of timeUnit units for which we are projecting, for example 12 (for 12 months). This field will be empty as it is not applicable for PRI. | No | | projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. This field will be empty as it is not applicable for PRI. | No | | streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | Yes | | streamId (string) | The stream ID for which we are reporting the confidence. | Yes | | confidence (number) | A float value between 0 and 100. | Yes |
#### State Attributes {#state-attributes} The unit of data for state attributes is some generic "state" at a point in time. Whereas transactional attributes are based on specific events (the posting of a transaction), state attributes make some inference about a point in time based on an assembly of underlying data. Examples of state attributes include the balance of an account over time, a calculation based on underlying transactions in a time period (such as net cash flow), or other calculations such as a debt-to-income ratio. The following sample JSON snippets are for state attributes at an accounts and customer level. * The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months. * The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates. * Not all attributes are showcased. Refer to the attribute table to view all PRI attributes. * The data in the snippets are for profile-2750-2756 with some modifications. * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 325.06, "count": 31, "endDate": "2023-07-31", "endingValue": 332.22, "max": 332.22, "mean": 328.6909677419355, "median": 332.12, "min": 324.96, "standardDeviation": 3.639724673505515, "startDate": "2023-07-01", "sum": 10189.42, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] }, ] }, { "periods": [ { "beginningValue": 635.44, "count": 365, "endDate": "2024-03-04", "endingValue": 401.56, "max": 696.23, "mean": 404.1959871413877, "median": 410.06, "min": 299.36, "standardDeviation": 3.997490676405987, "startDate": "2023-03-05", "sum": 147785.90, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] }, ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 506.78, "count": 31, "endDate": "2023-07-31", "endingValue": 479.07, "max": 510.89, "mean": 494.6909677419355, "median": 492.12, "min": 461.96, "standardDeviation": 4.75837468734, "startDate": "2023-07-01", "sum": 15497.36, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-07-01", "endDate": "2023-07-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 595.94, "count": 365, "endDate": "2024-03-04", "endingValue": 631.59, "max": 652.23, "mean": 610.387463784, "median": 601.06, "min": 451.36, "standardDeviation": 4.862563462, "startDate": "2023-03-05", "sum": 224670.10, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] }, ] } ], "projectedValues": [] }, ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 831.84, "count": 31, "endDate": "2023-07-31", "endingValue": 811.29, "max": 510.89, "mean": 406.381935483871, "median": 413.24, "min": 324.96, "standardDeviation": 4.27944934701103, "startDate": "2023-07-01", "sum": 25686.78, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-04-01", "endDate": "2023-04-30", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 1231.38, "count": 365, "endDate": "2024-03-04", "endingValue": 1033.15, "max": 696.23, "mean": 505.387463784, "median": 499.06, "min": 299.36, "standardDeviation": 4.382563462, "startDate": "2023-03-05", "sum": 372455.0, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-03-05", "endDate": "2024-03-04", "cohortValues": [] }, ] } ], "projectedValues": [], } ] ``` **Description of JSON fields** | Key (Datatype) | Description | |--------------------------------|------------------------------------------------------------------| | reportedByTimePeriods (object) | Value of the state over some time periods. | | beginningValue (number) | Value of the state as reported on the startDate of the period. | | endingValue (number) | Value of the state as reported on the endDate of the period. | | count (number) | Occurrences of the state between specified startDate and enDate. |
#### Streams {#streams} Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between two parties or accounts, if the same entity owns both the source and destination of funds. Examples of streams include bi-weekly paychecks from an employer to an employee, a customer's monthly phone bill paid to a telecom provider, a customer's monthly transfer from a checking account to an investment account, and so on. Since a stream is a group of transactions, a transactional attribute can assign a list of streams to itself if the transactions in that stream all fit the same classification being described by the attribute. **JSON snippets of stream attributes:** * Json ```json "streams": [ { "cadence": 20, "id": "107337ef-fa51-48cf-a70b-81144fb1e6e8", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-04T00:00:00, "count": 7, "sum": -42.96, "status": "active", "min": -3.07, "max": -12.17, "mean": -7.55, "median": -7.16, "standardDeviation": 0.14142135623730964, "minimumCadence": 5, "maximumCadence": 9, "medianCadence": 6, "modeCadence": 6, "standardDeviationCadence": 7.068617626733007, "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "5c6c913a-62dc-4d07-b4ed-28fbb68f9995", "payee": "JOHN DOE", "payor": "walmart", "recency": 20, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-14T00:00:00, "count": 5, "sum": -47.46, "status": "active", "min": -3.94, "max": -14.01, "mean": -8.10, "median": -7.85, "standardDeviation": 0.45253246733731172, "minimumCadence": 3, "maximumCadence": 7, "medianCadence": 4, "modeCadence": 4, "standardDeviationCadence": 5.172827626734145, "transactionIds": [ "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "107337ef-fa51-48cf-a70b-81144fb1e6e8", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-04T00:00:00, "count": 7, "sum": -42.96, "status": "active", "min": -3.07, "max": -12.17, "mean": -7.55, "median": -7.16, "standardDeviation": 0.14142135623730964, "minimumCadence": 5, "maximumCadence": 9, "medianCadence": 6, "modeCadence": 6, "standardDeviationCadence": 7.068617626733007, "transactionIds": [ "101500062955", "101500062933", "101500062908", "101500062911", "101500062974", "101500062918", "101500062980" ] }, { "cadence": 20, "id": "5c6c913a-62dc-4d07-b4ed-28fbb68f9995", "payee": "JOHN DOE", "payor": "walmart", "recency": 20, "earliestObservedDate": 2023-03-05T00:00:00, "latestObservedDate": 2024-02-14T00:00:00, "count": 5, "sum": -47.46, "status": "active", "min": -3.94, "max": -14.01, "mean": -8.10, "median": -7.85, "standardDeviation": 0.45253246733731172, "minimumCadence": 3, "maximumCadence": 7, "medianCadence": 4, "modeCadence": 4, "standardDeviationCadence": 5.172827626734145, "transactionIds": [ "101500063007", "101500063020", "101500062990", "101500063028", "101500063033" ] } ] ``` **Description of JSON fields** | Key (Datatype) | Description | |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | cadence (number) | The average number of days elapsed between consecutive transactions in the stream. | | id (string) | A randomly generated UUID to uniquely identify the stream. | | payee (string) | The party that is receiving the funds. | | payor (string) | The party that is sending the funds. | | recency (number) | The number of days elapsed since the most recent transaction in the stream. | | earliestObservedDate (string) | The date-time of the first observed transaction in the stream. | | latestObservedDate (string) | The date-time of the last observed transaction in the stream. | | status (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence. | | minimumCadence (number) | The smallest observed duration of time elapsed between any two consecutive transactions in the stream. | | maximumCadence (number) | The largest observed duration of time elapsed between any two consecutive transactions in the stream. | | medianCadence (number) | The median number of days elapsed between consecutive transactions in the stream. | | modeCadence (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream. | | standardDeviationCadence (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream. | | transactionIds (object) | A list of all the transaction IDs that were assigned to the stream. |
## Testing {#testing} For testing PRI you can use the [Payment Risk Insights test profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profiles), which generate reports with different risk levels. --- # Verification of Employment - Transactions source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-transactions/index.md The Verification of Employment -- Transactions (VOE - Transactions) product provides insights into the consumer's income stream status with no amounts or balance details so the client can focus on employment verification. Often used as a verification of employment prior to closing a loan, to confirm the consumer is still getting their direct deposits on the expected cadence. For more information about Mastercard's Employment products see [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment). ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Deposit Income Streams**: Provides the last 180 days of deposit history. No amounts are included so that no additional assets or income review is required. By default, this report includes Moderate and High confidence income streams, but can be adjusted to include Low confidence streams as well. ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type** : Verification of Income (VOI). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. * **Supported Account Types**: Checking, Savings, Money Market * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The VOE -- Transactions product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate VOE - Transactions Report {#generate-voe---transactions-report} To generate or refresh a VOE -- Transactions report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voeTransactions` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} VOE - Transactions reports are often ordered as a pre-closing verification of employment after previously ordering a VOAI or VOI report. If the bank accounts are still connected, the VOE - Transactions report can be ordered without needing to re-engage the consumer. If accounts are not connected, you will get an error when generating the report and will need to send the consumer back into Mastercard Data Connect to reconnect their accounts. * Use the `fromDate` parameter to customize the transaction history included in the report, up to 24 months maximum. By default, 180 days of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. You can also ensure only the accounts from a prior report (such as VOAI or VOI) by using the `reportId` parameter. * Customize the income streams returned in this report based on the confidence level. This input is called `incomeStreamConfidenceMinimum`. All income streams whose confidence level is greater than or equal to the number requested are provided. By default, the report will default to only include Moderate and High confidence income streams. Receiving all income streams may be desirable based on your implementation and use case. * High confidence levels correspond to `confidence` values of 75 and 100. * Moderate confidence levels correspond to a `confidence` value of 50. * Low confidence levels correspond to `confidence` values of 0 and 25. ## Get VOE - Transactions Report {#get-voe---transactions-report} Once the report is generated, retrieve the report using one of the Get Report endpoints: [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "n1rndg1iz8yy-voetransactions", "portfolioId": "dyr6weqd2yhb-2-port", "customerType": "active", "customerId": 1000006677, "requestId": "sfb7x1we9w", "title": "Mastercard Open Banking Verification of Employment - Transactions", "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "constraints": { "reportId": "j7k8qbgwsa7d-voietxverify", "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true } ], "incomeStreamConfidenceMinimum": 50 }, "type": "voeTransactions", "status": "success", "createdDate": 1588350269, "startDate": 1572625469, "endDate": 1588350269, "days": 120, "seasoned": true, "institutions": [ { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": [ { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1652114265, "name": "Checking", "type": "checking", "aggregationStatusCode": 0, "incomeStreams": [ { "id": "u4hstnyak45g1", "name": "none", "status": "ACTIVE", "estimateInclusion": "MODERATE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 14 }, "daysSinceLastTransaction": 15, "nextExpectedTransactionDate": 1698788820, "incomeStreamMonths": 18, "transactions": [ { "id": 100000527471, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "normalizedPayee": "Finicity", "institutionTransactionId": "100000000", "category": "Paycheck" } ] } ] } ] } ] } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. ## Testing {#testing} How to read a VOE -- Transactions report: [VOE_Transactions_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOE_Transactions_Report_HTR.pdf) (1MB) Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Statement Aggregation CRA (SACRA) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/statements/index.md The Statement Aggregation CRA (SACRA) report provides a single account statement. The report includes the account statement document in a PDF report format with a cover page and report ID. Learn more about Mastercard's [Transactions and Statements](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#transactions-and-statements) products. ## Key Product Features {#key-product-features} * **Account PDF statement**: Statement provided directly from the FI without alteration ### Additional Product Information {#additional-product-information} * **FI Certification Type** : Statement Aggregation (SA). Each financial institution (FI) goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 5 seconds * **Supported Account Types**: Checking, Savings, Money Market, CD, Investment account types, Mortgage, Loan, Credit Card, Line Of Credit, Payroll, Student Loan, Education Savings, Health Savings Account * **Supported Report Format:** PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The Statement Report product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Consumer/Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow)
## Generate Statement Report {#generate-statement-report} To generate a statement report, use the following steps: 1. **Determine which account statement is desired** Identify the account ID of the account for which a statement report is desired. The [Mastercard Data Connect webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/index.md) response will contain the account ID, or you can use [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#get-customer-accounts). 2. **Check if the financial institution supports retrieving statements** You can use the [Get Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCertifiedInstitutions) endpoint to check if the FI supports retrieving statements using an FI name for the `search` parameter (for example, "finbank" for the test FI in Sandbox) and `stateAgg` as the `type` parameter. If retrieving statements is supported, the response has a `stateAgg` value of `true`. 3. **Generate the statement report** Use the account ID and `statementIndex` to generate the report for the statement desired with the following API: API Reference: `POST /decisioning/v2/customers/{customerId}/statement` The response includes the status of the report generation and a report ID. A webhook notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). Tip: To retrieve a statement successfully, verify the account has aggregation status 0 before initiating statement retrieval. If the account has any other aggregation status code, the request will fail. Confirm with the customer that they have the "paperless" option activated in their bank portal; otherwise, the FI won't have the statements available to retrieve and the request will fail. #### Implementation Notes {#implementation-notes} * Request a report for any of the last 24 statements, with the most recent having the index value of 1, the second most recent statement having the index value of 2, etc. See the [Get Customer Account Multiple Statement Details](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccountMultipleStatement) API. * Each report will contain a single statement corresponding to the index value provided. ## Get Statement Report {#get-statement-report} Once the report generation is finished, you can then retrieve the report. See [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows a successful JSON response for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "38dknche83oh-statement", "customerType": "active", "customerId": 1000262464, "requestId": "nd4b55a4bg", "title": "Mastercard Open Banking Statement Report", "consumerId": "d15ff15ed0c8627eae61c452928d7fc3", "consumerSsn": "1111", "disputeStatement": "Invalid data present.", "requesterName": "Demo", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "constraints": { "statementReportData": { "accountId": 1000076901, "statementIndex": 1 }, "reportCustomFields": [ { "label": "loanID", "value": "123456", "shown": true } ] }, "type": "statement", "status": "success", "createdDate": 1586189339, "assetId": "aaaa3be2-6f1a-4aac-a360-4ad240aa652d" } ``` For SACRA, we support a human-readable PDF version of the report. Example SACRA report (PDF): [SACRA_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/SACRA_Example_Report.pdf) (466KB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Verification of Income and Employment - Payroll source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md The Verification of Income and Employment -- Payroll (VOIE-Payroll) product provides insights into the consumer's income and employment. The report includes employment details, including employer name, employment status, and other employment information as available. The report also includes income details, including a summary of annual payments for the current year to date through prior year two, as well as other pay period payment history details as available. Learn more about Mastercard's [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products. ## Key Product Features {#key-product-features} * **Employment Summary:** Employer name, address, hire date, latest pay date, employment status, etc * **Income Summary:** Pay frequency, pay rate, annual income summary, estimated monthly income, payment histories (as available), etc ### Additional Product Information {#additional-product-information} * **Report Generation Time (median):** * Direct API payroll accounts: Less than 5 seconds * Credentialed payroll accounts: Less than 2 minutes * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. This report may also be refreshed as a Verification of Employment (VOE) Payroll product. * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The VOIE -- Payroll product is suitable for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate VOIE -- Payroll Report {#generate-voie----payroll-report} To generate or refresh a VOIE -- Payroll report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voiePayroll` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * VOIE -- Payroll reports may be refreshed as VOE -- Payroll reports for mortgage lending if updated income information is not desired in the new report. See [VOE -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) for more information. * Use the `paystatementFromDate` parameter to customize the payment history included in the report. If not used, the report will default to including the full history through prior year two, as available. ## Get VOIE -- Payroll Report {#get-voie----payroll-report} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "41h4nzppn37u-voiepayroll", "portfolioId": "9qud7dtuzbew-1-port", "gseEnabled": true, "customerType": "active", "customerId": 1275320, "requestId": "7a7qyps2iy", "consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "type": "voiePayroll", "reportStyle": "credentialedPayroll", "status": "success", "createdDate": 1579819592, "title": "Mastercard Open Banking Verification of Income and Employment - Payroll", "constraints": { "payrollData": { "payrollAccountIds": [ "018b8f10-fdf8-0ef7-ded5-34a17c34d86f" ], "payrollAggregatorResponseId": "4baxktu9wdda" }, "reportCustomFields": { "label": "loanID", "value": "12345", "shown": true } }, "employmentHistory": { "asOfDate": 1596175200, "employmentId": "vkvxszcy7nc9c19d", "employerName": "ACME INC", "payrollSource": "argyle", "payrollProvider": "Paychex", "employee": { "name": "John Doe Smith", "givenName": "John", "middleName": "Doe", "familyName": "Smith", "address": [ { "address1": "Address 1", "city": "City", "state": "TX", "zip": "99999" } ] }, "employment": { "employerName": "ACME INC", "legalEntityId": "752760000", "originalHireDate": 1527832800, "latestHireDate": 1527832800, "latestPayDate": 1596175200, "daysSinceLastPay": 10, "numberPayCadenceWithoutPay": 1, "employmentEndDate": 1527832800, "employmentDuration": "P1Y6M0D", "employerAddress": [ { "address1": "Address 1", "city": "City", "state": "TX", "zip": "99999" } ], "employmentStatusCode": "A", "employmentStatusName": "Active", "workLevelCode": "FT", "workLevelName": "Full Time-Regular", "workLevelStatus": "Full Time", "positionTitle": "Shift Supervisor", "positionDuration": "P1Y6M0D" }, "income": { "payFrequency": "Weekly", "payType": "Hourly", "basePayRate": 27.5, "annualIncome": [ { "year": "2021", "grossPayAmountYTD": 73925.12, "netPayAmountYTD": 73925.12, "basePayAmountYTD": 73925.12, "overtimePayAmountYTD": 100.01 }, { "year": "2020", "grossPayAmountYTD": 73925.12, "netPayAmountYTD": 73925.12, "basePayAmountYTD": 73925.12, "overtimePayAmountYTD": 100.01 }, { "year": "2019", "grossPayAmountYTD": 73925.12, "netPayAmountYTD": 73925.12, "basePayAmountYTD": 73925.12, "overtimePayAmountYTD": 100.01 } ], "monthlyIncome": { "estimatedMonthlyBasePay": 2000, "estimatedMonthlyOvertimePay": 100 }, "directPayStatements": [ { "payrollPayHistoryId": "cy1a742k28", "lastPayPeriodIndicator": true, "mainPayStatementFields": { "payDate": 1596175200, "startDate": 1595138400, "endDate": 1595656800, "payPeriodHours": 40, "payFrequency": "Weekly", "payType": "Hourly", "grossPayAmount": 1888.75, "grossPayAmountYTD": 73925, "netPayAmount": 1401.95, "netPayAmountYTD": 73925 }, "earnings": [ { "name": "basePayAmount", "type": "base", "rate": 27.5, "amount": 1100, "amountYTD": 5500 } ], "deductions": [ { "type": "Federal tax", "amount": 143.45 }, { "type": "State tax", "amount": 12.5 } ] } ] } } } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a VOIE -- Payroll report: [VOIE_Payroll_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOIE_Payroll_HTR.pdf) (2MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that is indicated as supporting Payroll such as [Homer Loanseeker](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles). --- # Transaction Consumer Reporting Agency (TACRA) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/tacra/index.md Transactions CRA (TACRA) delivers categorized, normalized transaction history suitable for FCRA-regulated lending decisions and downstream model building. A single generate call returns the report; billing distinguishes TACRA (\<=6 months of returned data) from TACRAH (\>6 months), and the dataset serves as a foundation for Lend analytics and verification products. Learn more about Mastercard's [Transactions and Statements](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#transactions-and-statements) products. ## Key Product Features {#key-product-features} * **Data History** : Up to 24 months of transaction data based on availability from the FI. Length of history is customizable using `fromDate` and defaults to 24 months ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 25 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. * **Supported Account Types**: Checking, Savings, Money Market, CD, Investment Account Types, Mortgage, Loan, Credit Card, Line of Credit, Payroll, Student Loan, Education Savings, Health Savings Account * **Supported Report Formats:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The Transaction CRA report is suitable for the following use cases: * Auto Lending * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening
## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow)
## Generate Transaction CRA {#generate-transaction-cra} To generate or refresh this report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/transactions` The response includes the status of the report generation and a report ID. A webhook notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history provided in the report. By default, 24 months of history will be aggregated as available. * While there is a single endpoint to generate this report, it can be billed in two ways depending on the amount of data returned: * If 6 months or less of data is returned, it is billed as a Transactions CRA report (also called TACRA). * If more than 6 months of data is returned, the report will be billed as a Transactions CRA History report (also called TACRAH). * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types connected by the customer.
## Get Transaction Reports {#get-transaction-reports} Once the report is generated, retrieve the report using one of the Get Report endpoints: [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows a successful JSON response for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "1000075473", "title": "Mastercard Open Banking Transactions Report", "customerType": "testing", "customerId": 1000018865, "consumerId": "a925b07c9e028c680ad9c1d18d2e7199", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "type": "transactions", "status": "success", "createdDate": 1594678007, "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "constraints": { "accountIds": [ "1000075473" ], "fromDate": 1578952809, "toDate": 1594677609, "includePending": true, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true }, { "label": "loanType", "value": "car", "shown": false }, { "label": "vendorID", "value": "1613aa23", "shown": true }, { "label": "vendorName", "value": "PSC Finance", "shown": false } ], "findTransaction": [ { "findTransactionDescriptionMemo": "Payment to PSC Finance", "findTransactionAmountFrom": -100.01, "findTransactionAmountTo": 200, "findTransactionCategory": [ "Payment", "Transfer" ] } ] }, "startDate": 1579348800, "endDate": 1594382400, "days": 174, "seasoned": false, "portfolioId": "wqbh0r2kbv5g-4-port", "institutions": [ { "id": 102105, "name": "FinBank Profiles - A", "urlHomeApp": "http://www.bank.example.com", "accounts": [ { "id": 1000075473, "number": "5015", "name": "Super Checking", "type": "checking", "availableBalance": 1000, "aggregationStatusCode": 0, "balance": 1000, "balanceDate": 1594676289, "transactionsCount": 2, "transactions": [ { "id": 100001490719, "amount": -99, "postedDate": 1594382400, "description": "ACH Withdrawal AMERICA FIRST CR", "normalizedPayee": "America First Cr", "institutionTransactionId": "0000000000", "category": "Transfer", "memo": "Payment to PSC Finance" }, { "id": 100001490897, "amount": 199.7, "postedDate": 1594123200, "description": "Payment to PSC Finance", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Payment", "memo": "TMOBILE debit" } ] } ] } ] } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. Sample TACRA report: [TACRA_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/TACRA_Example_Report.pdf) (2MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#bank-account-profiles). --- # Verification of Employment - Payroll source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md The Verification of Employment -- Payroll (VOE-Payroll) product provides insights into the consumer's employment. The report includes employment details, including employer name, employment status, and other employment information as available. Often used as a verification of employment prior to closing a mortgage loan. Learn more about Mastercard's [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products. ## Key Product Features {#key-product-features} * **Employment Summary:** Employer name, address, hire date, latest pay date, employment status, etc ### Additional Product Information {#additional-product-information} * **Report Generation Time (median):** * Direct API payroll accounts: Less than 5 seconds * Credentialed payroll accounts: Less than 10 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The VOE -- Payroll product is suitable for the following use case: * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate VOE -- Payroll Report {#generate-voe----payroll-report} To generate or refresh a VOE -- Payroll report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voePayroll` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} VOE-Payroll reports are often ordered as a pre-closing verification of employment after previously ordering a VOIE-Payroll report for mortgage lending. If the payroll accounts are still connected, the VOE-Payroll report can be ordered without needing to re-engage the consumer. If accounts are not connected, an error will occur when generating the report, and the customer must be sent back into Data Connect to reconnect their accounts. ## Get VOE -- Payroll Report {#get-voe----payroll-report} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "41h4nzppn47u-voepayroll", "portfolioId": "9qud7dtuzbew-1-port", "gseEnabled": true, "createdDate": 1579819592, "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "7a7qyps2iy", "customerType": "active", "customerId": 1275320, "consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "type": "voePayroll", "reportStyle": "credentialedPayroll", "title": "Mastercard Open Banking Verification of Employment - Payroll", "status": "success", "constraints": { "payrollData": { "payrollAccountIds": [ "018d3f0e-6c1c-fa13-7e50-0003acfcfdae" ], "payrollAggregatorResponseId": "4baxktu9wdda" } }, "employmentHistory": [ { "asOfDate": 1596175200, "employmentId": "zgk6wh3urqr0gtxv", "employerName": "ACME INC", "payrollSource": "argyle", "payrollProvider": "Paychex", "employee": { "name": "John Doe Smith", "givenName": "John", "middleName": "Doe", "familyName": "Smith", "address": [ { "address1": "Address 1", "city": "City", "state": "TX", "zip": "99999" } ] }, "employment": { "employerName": "ACME INC", "legalEntityId": "752760000", "originalHireDate": 1527832800, "latestHireDate": 1527832800, "latestPayDate": 1596175200, "daysSinceLastPay": 10, "numberPayCadenceWithoutPay": 1, "employmentEndDate": 1527832800, "employmentDuration": "P1Y6M0D", "employerAddress": [ { "address1": "Address 1", "city": "City", "state": "TX", "zip": "99999" } ], "employmentStatusCode": "A", "employmentStatusName": "Active", "workLevelCode": "FT", "workLevelName": "Full Time-Regular", "latestPayPeriodEndDate": 1699747200, "derivedEmploymentStatus": false, "workLevelStatus": "Full Time", "positionTitle": "Shift Supervisor", "positionDuration": "P1Y6M0D" }, "income": { "payFrequency": "Weekly" } } ] } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a VOE -- Payroll report: [VOIE_Payroll_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOIE_Payroll_HTR.pdf) (2MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that is indicated as supporting Payroll such as [Homer Loanseeker](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles). --- # Asset Prequalification source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/prequal/index.md The Asset Prequalification product provides insights into the customer's assets and balances via a verification report. It differs from a Verification of Assets report in that it doesn't have transaction-level information. Learn about Mastercard's [Assets and Balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#assets-and-balances) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Assets Summary**: Provided as a balance summary across all accounts, and includes the current balance, the average 2-month daily balance, and the average 6-month daily balance * **Data History** : Up to 24 months of transaction data based on availability from the FI. Length of history is customizable using the `fromDate` and defaults to 6 months ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type** : Verification of Assets (VOA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 25 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. * **Supported Account Types**: Checking, Savings, Money Market, CD, Investment Account Types, Education Savings, Health Savings Account * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The Asset Prequalification product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate Asset Prequalification Report {#generate-asset-prequalification-report} To generate or refresh an Asset Prequalification report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/preQualVoa` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report, up to 24 months maximum. By default, 6 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * If the Non-Sufficient Funds (NSF) information is not desired set the `showNsf` parameter to `false`. ## Get Asset Prequalification Report {#get-asset-prequalification-report} Once the report is generated, retrieve the report using one of the Get Report endpoints: [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "88w4fbssrbja-prequalvoa", "customerId": 1000006677, "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "sfb7xacr9w", "type": "preQualVoa", "status": "success", "createdDate": 1588350269, "constraints": { "accountIds": [ "1000535275", "1000535276" ], "fromDate": 1577986990, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true }, { "label": "loanType", "value": "car", "shown": false }, { "label": "vendorID", "value": "1613aa23", "shown": true }, { "label": "vendorName", "value": "PSC Finance", "shown": false } ], "showNsf": false }, "customerType": "active", "title": "Asset Ready Report (CRA)", "startDate": 1572625469, "endDate": 1588350269, "days": 230, "seasoned": true, "consolidatedAvailableBalance": 1929.57, "portfolioId": "0whcism47a34-5-port", "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1588350276, "name": "Checking", "type": "checking", "aggregationStatusCode": 0, "balance": 501.24, "balanceDate": 1588350276, "averageMonthlyBalance": 501.02, "totNumberInsufficientFundsFeeDebitTxAccount": 0, "totNumberInsufficientFundsFeeDebitTxOver6MonthsAccount": 0, "totNumberDaysSinceMostRecentInsufficientFundsFeeDebitTxAccount": 120, "transactions": [], "asset": { "type": "checking", "availableBalance": 1000, "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 }, "details": { "interestMarginBalance": -50000, "availableCashBalance": 1500, "vestedBalance": 300000, "currentLoanBalance": 0, "availableBalanceAmount": 1000 } } }, "assets": { "currentBalance": 1000, "availableBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 } } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read an Asset Prequalification report: [Prequalification_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Prequalification_Report_HTR.pdf) (1MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # React Native Applications source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/react-native-sdk/index.md If you are creating cross platform mobile app, we recommend using our React Native SDK. App to app authentication is supported in much the same way as with our native iOS and Android SDKs. ## React Native SDK {#react-native-sdk} The Data Connect React Native SDK provides an easy way for you to integrate Mastercard Open Finance Data Connect into your React Native application. ### Compatibility {#compatibility} The Data Connect React Native SDK supports the following Android and iOS versions: * Android: Android 5.0 (Lollipop) or later, Android SDK level 21 or later. * iOS: iOS 11 or later. Note: The `redirectUrl` property, supporting universal links on iOS, app links on Android, and deeplinks, is available from Data Connect React Native SDK version 2.0.0 onward (we recommend using the most recent available version of the SDK). For more information see our [Github repository](https://github.com/Mastercard/connect-react-native-sdk). ### Install the Data Connect React Native SDK {#install-the-data-connect-react-native-sdk} ### Dependencies {#dependencies} The Data Connect React Native SDK has the following `peerDependencies`: * [react-native-inappbrowser-reborn](https://www.npmjs.com/package/react-native-inappbrowser-reborn) \>= 3.6 * [react-native-webview](https://www.npmjs.com/package/react-native-webview) \>= 11 * [react](https://www.npmjs.com/package/react) \>= 16.13 * [react-native](https://www.npmjs.com/package/react-native) \>= 0.63 ### Step 1: Add Repository to Your Project {#step-1-add-repository-to-your-project} If your application doesn't use `react-native-inappbrowser-reborn` and `react-native-webview` as dependencies, you can install them using the following: * [react-native-inappbrowser-reborn](https://github.com/proyecto26/react-native-inappbrowser) * [react-native-webview](https://github.com/react-native-webview/react-native-webview)
The Data Connect React Native SDK has been tested on `react-native-inappbrowser-reborn` version 3.7.0 and `react-native-webview` version 13.6.4. ### Step 2: Add Data Connect React Native SDK {#step-2-add-data-connect-react-native-sdk} The easiest way to install the SDK is to use npm or yarn: * npm: `npm install connect-react-native-sdk` * yarn: `yarn add connect-react-native-sdk`
On iOS, CocoaPods needs this additional step: `$ cd ios && pod install && cd ..` Tip: You can view the SDK source code on [Github](https://github.com/Mastercard/connect-react-native-sdk). Note: The Data Connect React Native SDK only supports React Native versions above 0.64. Linking the package manually is not required as it uses [Autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). ### Step 3: Update Android Application Settings {#step-3-update-android-application-settings} The Data Connect React Native SDK requires internet access to connect with our servers, so you need to add internet permissions to the `AndroidManifest.xml` file: ```xml ``` ### Usage {#usage} #### Parameters {#parameters} | Parameter | Description | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `connectUrl` (required) | The SDK loads the Data Connect URL provided in order to show the Data Connect experience. | | `eventHandlers` (required) | A class implementing the `ConnectEventHandlers` interface. | | `redirectUrl` (optional) | The URL to redirect back to your mobile app after completing an FI's OAuth flow (universal link on iOS, app link on Android). This parameter is only required for App to App. | See the [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) section for details of how to generate a Data Connect URL for the `connectUrl` parameter. ```javascript import { Connect, ConnectEventHandlers, } from 'connect-react-native-sdk'; const MyConnectComponent = () => { const eventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => {}, onCancel: (event: ConnectCancelEvent) => {}, onError: (event: ConnectErrorEvent) => {}, onRoute: (event: ConnectRouteEvent) => {}, onUser: (event: any) => {}, onLoad: () => {}, }; return ( ); }; ``` ### Event Handler Interface {#event-handler-interface} Throughout the Data Connect flow, events about the state of the web application are sent as JSON objects to the `eventHandlers` prop. Note: The `onUser` event handler will not return anything unless you are specifically targeting Data Connect, ```javascript export interface ConnectEventHandlers { onDone: (event: ConnectDoneEvent) => void; onCancel: (event: ConnectCancelEvent) => void; onError: (event: ConnectErrorEvent) => void; onRoute?: (event: ConnectRouteEvent) => void; onUser?: (event: any) => void; onLoad?: () => void; } ``` #### Callback Events {#callback-events} See [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md#callback-events) for details on the events via their callback interface. **Note** : The `onDone`, `onError`, `onRoute`, and `onUser` callback functions will have a **JSONObject** parameter that contains data about the event. ## App to App Support {#app-to-app-support} To provide the best app to app authentication experience for your customers, you should send a universal link URL in the `redirectUrl` parameter when using Data Connect. See [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) for more details, including [how to test](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#how-to-test-app-to-app-authentication). Before installing the Data Connect React Native SDK for use with app to app authentication, complete the following: * Create your domain's `redirectUrl` (iOS universal link, Android app link) * Configuring your `redirectUrl` ### iOS: Create Your Domain's redirectUrl {#ios-create-your-domains-redirecturl} For information on how to create a [Universal Link](https://developer.apple.com/ios/universal-links/) to be used as the `redirectUrl` in your application, see Apple's [Allowing apps and websites to link to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) documentation. For information on how to configure your server, see [supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) in the Apple developer documentation. Tip: In order to provide the best app to app authentication customer experience, you should use a universal link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security that Apple's Universal Links provide through the two-way association between your app and your website. A deep link will also trigger an alert on iOS devices which can add friction to the customer experience, requesting permission to redirect back to the Partner's app. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any other application that has registered the same URL scheme. ### Android: Create Your Domain's redirectUrl {#android-create-your-domains-redirecturl} For information on how to create an [App Link](https://developer.android.com/training/app-links#android-app-links) as `redirectUrl` in your application, see [adding Android App Links](https://developer.android.com/studio/write/app-link-indexing) in the Android developer documentation. Tip: In order to provide the best app to app authentication customer experience, you should use an app link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security that Android App Links provide through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from Android. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any other application that has registered the same URL scheme. ### Configuring Your redirectUrl {#configuring-your-redirecturl} In order to return control back to your application after a customer completes an FI's OAuth flow, you must specify a `redirectUrl` value. This URL is used to redirect back to your mobile app after completing an FI's OAuth flow (this should be a universal link on iOS or an app link on Android). Here is an example of a universal link `redirectUrl` within your code: ```html ``` ### Android: Working Without redirectUrl {#android-working-without-redirecturl} If your Android application does not pass `redirectUrl`, additional configuration is required in order to support OAuth redirection and deep linking back to your application. Tip: In order to have the best app to app authentication experience, we recommend specifying a universal or app link as `redirectUrl` for iOS and Android platforms. If however this is not possible, the following additional configuration is required with Android, due to behavior changes introduced in Android 15. This ensures the Connect flow can redirect securely back to your application after authentication. On iOS, the existing URL scheme handling will be used. To enable this, you must ensure you are using version 2.0.5 or later of the Data Connect React Native SDK, then configure an intent filter in your Android app's **AndroidManifest.xml** file. Inside the `` that handles app launches (usually `MainActivity`), add the intent filter as follows: ```xml ``` Warning: Do not change the scheme, host, or path unless explicitly instructed. Ensure this intent filter is added only once. ## Sample React Native App {#sample-react-native-app} We provide a sample project uses the Data Connect React Native SDK on Github: [ConnectReactNativeDemoApp](https://github.com/Mastercard/connect-react-native-sdk/tree/master/ConnectReactNativeDemoApp) Ensure that you have the necessary setup for React Native version 0.72 to successfully run and explore this demo app. ## Data Connect React Native SDK Migration Guide {#data-connect-react-native-sdk-migration-guide} This migration guide provides step by step instructions for migrating from Data Connect React-Native SDK version 1.x to version 2.x. Follow the outlined changes carefully to ensure a smooth transition. ### Step 1: Update Your Installation {#step-1-update-your-installation} The first step is to make sure you install the new version of the SDK. If you were previously using npm then you will need to update your npm command as shown. You can also use yarn from v2.x onward. **v1.x** npm install @finicity/connect-react-native-sdk **v2.x** * npm: `npm install connect-react-native-sdk` * yarn: `yarn add connect-react-native-sdk`
On iOS, CocoaPods needs this additional step: `$ cd ios && pod install && cd ..` ### Step 2: Update Your Code {#step-2-update-your-code} You will need to update your code where you import the SDK and use the components as follows. **v1.x** With v1.x, you needed to import `FinicityConnect` and `ConnectEventHandlers` from `@finicity/connect-react-native-sdk`, and your return function could define the `linkingUri` property: ```javascript import { FinicityConnect, ConnectEventHandlers, } from '@finicity/connect-react-native-sdk'; const MyConnectComponent = () => { const eventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => {}, onCancel: (event: ConnectCancelEvent) => {}, onError: (event: ConnectErrorEvent) => {}, onRoute: (event: ConnectRouteEvent) => {}, onUser: (event: any) => {}, onLoad: () => {}, }; return ( ); }; ``` **v2.x** With v2.x, you need to import `Connect` and `ConnectEventHandlers` from `connect-react-native`, and your return code will need to be updated to use `redirectUrl` instead of `linkingUri`, as shown below: ```javascript import { Connect, ConnectEventHandlers, } from 'connect-react-native-sdk'; const MyConnectComponent = () => { const eventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => {}, onCancel: (event: ConnectCancelEvent) => {}, onError: (event: ConnectErrorEvent) => {}, onRoute: (event: ConnectRouteEvent) => {}, onUser: (event: any) => {}, onLoad: () => {}, }; return ( ); }; ``` --- # Batch Processing source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/batch/index.md This section explains how to use [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) via batch processing. We also have an [API](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/api/index.md) solution. ## How It Works - Batch {#how-it-works---batch} The batch process allows you to upload a file containing up to 6 million transactions per file. The file will be processed by our enrichment logic and returned to you. Batch files must follow the specifications for column headers, be formatted as CSV, encrypted, and transferred via SFTP. ## SFTP Onboarding {#sftp-onboarding} To enable the batch process, please work with your Customer Success Manager (CSM) to provide the following: * The public IP address from which you will access the SFTP server. * Your public SSH Key (this will allow passwordless authentication to the SFTP server).
Note: If you do not use your SFTP access, you will lose access after 90 days and you will need contact us again to reactivate. Your Customer Success Manager will also be able to help with the process of creating the necessary encryption keys, which are not available via the Mastercard Developers project dashboard by default. ## Encryption Key Setup {#encryption-key-setup} To send data to the Open Finance Batch process, you will need encryption keys to secure the data exchanges with Mastercard. See the [API Basics](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md) section for details of how to create a project and obtain the required project credentials. Tip: You will need to note partner ID when you have created the project, even if you are only using the batch process and not accessing any APIs. You will also need encryption keys which you can access from the **Projects** section on Mastercard Developers after logging in (select your project and then look for the project credentials). You will also need to request production access. Contact your Customer Success Manager (CSM) for further details and to ensure that the option to create the required keys is enabled. ### Encryption Keys {#encryption-keys} In addition to the credentials used to authenticate your requests, when using the batch file transfer process, you are required to encrypt the data exchanged with Mastercard. There are two types of encryption keys: 1. **Client Encryption Key** 2. **Mastercard Encryption Key** Both will be required. By default you will not see the option to create keys for an Open Finance project on your Mastercard Developers project dashboard. Your Customer Success Manager will enable this functionality for you after you request production access and provide your details. Once enabled, you will be able to create keys as follows: ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/mcd-add-key.png) Once created, you can view and download the keys as required: ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/mcd-keys-prod-keys-openfinance.png) To read more about Encryption Key creation on Mastercard Developers see [Onboarding for Encryption Key Management](https://developer.mastercard.com/open-finance-us/documentation/onboarding-encryption-keys/index.md). To learn more about how data between client applications and Mastercard is secured, see [Securing Payload Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/) in the [Mastercard Developers Platform](https://developer.mastercard.com/platform/documentation) documentation. To assist you in performing payload encryption and decryption, Mastercard provides [encryption libraries](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/#client-libraries). ## Encrypting Data and Sending to SFTP {#encrypting-data-and-sending-to-sftp} There are two aspects to the encryption process: * You will need to encrypt your CSV data file using an AES-256 ephemeral key. * Then, you need to encrypt your AES-256 ephemeral key, IV byte array, and encryption tag using JSON Web Encryption (JWE). This should then be packaged as a metadata file in JSON format. These two files should then be placed in a zip and sent to Mastercard via SFTP. Follow the steps below to securely send a batch file to Mastercard: Diagram data-enrichment-batch 1. Prepare the transaction data in a CSV file suitable (see [File Format](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/batch/index.md#file-format) below) for batch processing. 2. Create an initial vector (IV) byte array and an ephemeral AES 256-bit key as a data encryption key. When creating this key, use the AES algorithm in GCM mode (AES/GCM/NoPadding). You can find sample code for creating both an IV byte array and an AES ephemeral key on GitHub [here](https://github.com/Mastercard/client-encryption-java/blob/main/src/main/java/com/mastercard/developer/encryption/aes/AESEncryption.java#L28). 3. Encrypt the CSV file using the ephemeral key and IV byte array from step 2, with the AES encryption algorithm in GCM mode. Name this file `transactions_YYYYMMDDHHMMSS.bin`. The encryption result will also return a `tag` value that will be used in the next step. The following Python example illustrates this: * Python ```python from Crypto.Cipher import AES from Crypto.Random import get_random_bytes key = get_random_bytes(32) # 32 bytes X 8 bits = 256 bits iv = get_random_bytes(16) cipher = AES.new(key, AES.MODE_GCM, nonce=iv, use_aesni=True) blocksize = 64 * 1024 * 1024 # 64 MB block with open("path/to/raw/transactions_YYYYMMDDHHMMSS.csv", 'rb') as reader, \ open("path/to/encrypted/transactions_YYYYMMDDHHMMSS.bin", 'wb') as writer # encrypt large file in 64 MB chunk. This is to avoid loading entire file in memory while True: block = reader.read(blocksize) if not block: break writer.write(cipher.encrypt(block)) tag = cipher.digest() ``` 4. Mastercard will need to know how to decrypt your encrypted CSV file. To do this you need to send the necessary details within a JWE. Encode the `key`, `iv`, and `tag` values as base64 encoded strings (with ASCII codec), and create a JSON metadata payload in the following format: ```json { "key": "5gO+78x1ZjKG3BzwY8AP9dovzUyrBtL/HNgrVIggEIw=", "iv": "9PYO6dNmmTuchtbpwT7ldA==", "tag": "+vEElaaYP05RMAvR42QEHw==" } ``` Encrypt this metadata with JWE Encryption. You can use the [Mastercard Client Encryption Library](https://github.com/Mastercard?&q=client-encryption) to do so. You will need to use your Client Encryption Key tied to your project when setting up the JWE configuration. * Python ```python import json from client_encryption.jwe_encryption_config import JweEncryptionConfig from client_encryption.jwe_encryption import encrypt_payload, decrypt_payload metadata = { "key": "5gO+78x1ZjKG3BzwY8AP9dovzUyrBtL/HNgrVIggEIw=", "iv": "9PYO6dNmmTuchtbpwT7ldA==", "tag": "+vEElaaYP05RMAvR42QEHw==" } payload = { "enc": metadata, } pub_cert_path = "path/to/client-encryption-key" conf = JweEncryptionConfig({ "paths": { "$": { "toEncrypt": { "enc": "enc", }, "toDecrypt": {} } }, "encryptedValueFieldName": "jwe", "encryptionCertificate": pub_cert_path }) enc = encrypt_payload(payload=payload, config=conf) jwe = enc["enc"] with open("path/to/transactions_YYYYMMDDHHMMSS.metadata.json") as metaf: metaf.write(json.dumps(jwe)) ``` 5. The JWE created will be used in the next step. 6. Package the returned JWE into a JSON file called `transactions_YYYYMMDDHHMMSS.metadata.json` in the following form: * Json ```json { "jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiZTI0YzAyZDU0NGIyYjExNmJhMDZlZDc2NWNjZDY1MzI3OGZkNmIxODQ2MTAxZTU0MjdlNjM2YzkwY2RlZjk0OSIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24ifQ.YbgsnILXFkVba7mU0PUQpMwsWuVASTAfTIeokghGnCgQbLpjKag75slXCQyroJ27fK0Y_Qgus05yWKYKRaP6zdP1YO5mLIm44iz-EPpz1e3v6DgkZ5MMTxeMqREPkC03cTO9OIajIw0UgbafrmfJ18izJojKerdsnMvnEKZ8_23oqMYN7CHW9Jg5HuEaqxKme0OoITJpzs4Jk-bPsvtxeWam8iNH9l77hWuf2wyTIW_qyx5J9vBXNB6_96uTCtHECttOQkk7-Tk1zYmhKqR4ZG8AOMTIE4YHFmkQoSLxU8YAuMDQFN4Xr5egoo9AlUkN7urrf37gdgUG1ldPVxgXcg.EjRNhXhJUj50-q9DB7XSkg.4fGc5xCuoySNzbMhDYUGRdEA2FfRqlV5yEdrDMlu3sz3tHycLrLJXYBaPyueCUWsi2RJpG85-nY-o689Z2TOQkfu9UZty8nyLfmFfhpUGwhcCaN-OZaXSYOxsLR2UIgbJ8VuFnml1dJ5BfswIaJF2UZXjfbA6yNHig4Jvg.aPVGN0J-JUfqzYhuQ_pkFA" } ``` 7. Package the `transactions_YYYYMMDDHHMMSS.bin` and `transactions_YYYYMMDDHHMMSS.metadata.json` into a zip folder using this naming convention: `transactions_YYYYMMDDHHMMSS.zip` 8. Transfer the zip package to Mastercard via SFTP (in the /inputs directory). ## Decrypt the Resulting Data File {#decrypt-the-resulting-data-file} Downloading and decrypting the output file is the reverse of the process above for sending files. You will need to download a zip, extract the JWE from the metadata file, and use the ephemeral encryption key details from the JWE to then decrypt the output file itself. There may be two output files, as any failures will be returned in a second file along with error messages. The process is as follows: Diagram data-enrichment-batch2 1. Transfer the output file from the Mastercard SFTP to your network. The file will be named with this naming convention: `transactions_YYYYMMDDHHMMSS_output.zip` 2. Unzip the files: * `transactions_YYYYMMDDHHMMSS.metadata.json` - This file contains the encryption metadata. * `transactions_YYYYMMDDHHMMSS_success.bin` - This is an encrypted file which contains the successfully enriched records. * `transactions_YYYYMMDDHHMMSS_fail.bin` - This is an encrypted file which contains those records where data enrichment failed. You can use the error messages to help diagnose what caused the problem. The metadata JSON file contains two fields, `jwe` and `fingerprint`: * `jwe` contains the encrypted `key` and `iv` used during the encryption of the output files, plus the `successTag` and `failTag` extracted from encrypted output files. * `fingerprint` contains the finger print of the key pair used for encrypting the output files. For example: * Json ```json { "jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiZTI0YzAyZDU0NGIyYjExNmJhMDZlZDc2NWNjZDY1MzI3OGZkNmIxODQ2MTAxZTU0MjdlNjM2YzkwY2RlZjk0OSIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24ifQ.YbgsnILXFkVba7mU0PUQpMwsWuVASTAfTIeokghGnCgQbLpjKag75slXCQyroJ27fK0Y_Qgus05yWKYKRaP6zdP1YO5mLIm44iz-EPpz1e3v6DgkZ5MMTxeMqREPkC03cTO9OIajIw0UgbafrmfJ18izJojKerdsnMvnEKZ8_23oqMYN7CHW9Jg5HuEaqxKme0OoITJpzs4Jk-bPsvtxeWam8iNH9l77hWuf2wyTIW_qyx5J9vBXNB6_96uTCtHECttOQkk7-Tk1zYmhKqR4ZG8AOMTIE4YHFmkQoSLxU8YAuMDQFN4Xr5egoo9AlUkN7urrf37gdgUG1ldPVxgXcg.EjRNhXhJUj50-q9DB7XSkg.4fGc5xCuoySNzbMhDYUGRdEA2FfRqlV5yEdrDMlu3sz3tHycLrLJXYBaPyueCUWsi2RJpG85-nY-o689Z2TOQkfu9UZty8nyLfmFfhpUGwhcCaN-OZaXSYOxsLR2UIgbJ8VuFnml1dJ5BfswIaJF2UZXjfbA6yNHig4Jvg.aPVGN0J-JUfqzYhuQ_pkFA", "fingerprint": "cfb9bf8efec58af5f5231d73d7785f2eb3991c3dae8b1539a3cde9fdb6cd6dab" } ``` 3. Extract the JWE from the metadata and decrypt it to obtain the ephemeral key that was used by Mastercard to encrypt the processed file. You can use the Mastercard Client Encryption Library to do so with JWE decryption. Use the Mastercard Decryption Key associated with `fingerprint` to decrypt the `jwe` value. 4. Decrypting the JWE should produce a JSON file containing `key`, `iv`, `successTag` and `failTag`. These will be base64 encoded strings (with ASCII codec). Decode them to bytes. You will then be able to use these to decrypt the data files. 5. With AES in GCM mode and the `key` and `iv` from the previous step, decrypt the `.bin` files: * To decrypt the success file, use `transactions_YYYYMMDDHHMMSS_success.bin` as the payload and the `success_tag` as the tag. * To decrypt the fail file, use `transactions_YYYYMMDDHHMMSS_fail.bin` as the payload and the `fail_tag` as the tag. The following Python code example shows the decryption of the JWE and then the data files. * Python ```python import base64 enc_metadata = { "jwe": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiZTI0YzAyZDU0NGIyYjExNmJhMDZlZDc2NWNjZDY1MzI3OGZkNmIxODQ2MTAxZTU0MjdlNjM2YzkwY2RlZjk0OSIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24ifQ.YbgsnILXFkVba7mU0PUQpMwsWuVASTAfTIeokghGnCgQbLpjKag75slXCQyroJ27fK0Y_Qgus05yWKYKRaP6zdP1YO5mLIm44iz-EPpz1e3v6DgkZ5MMTxeMqREPkC03cTO9OIajIw0UgbafrmfJ18izJojKerdsnMvnEKZ8_23oqMYN7CHW9Jg5HuEaqxKme0OoITJpzs4Jk-bPsvtxeWam8iNH9l77hWuf2wyTIW_qyx5J9vBXNB6_96uTCtHECttOQkk7-Tk1zYmhKqR4ZG8AOMTIE4YHFmkQoSLxU8YAuMDQFN4Xr5egoo9AlUkN7urrf37gdgUG1ldPVxgXcg.EjRNhXhJUj50-q9DB7XSkg.4fGc5xCuoySNzbMhDYUGRdEA2FfRqlV5yEdrDMlu3sz3tHycLrLJXYBaPyueCUWsi2RJpG85-nY-o689Z2TOQkfu9UZty8nyLfmFfhpUGwhcCaN-OZaXSYOxsLR2UIgbJ8VuFnml1dJ5BfswIaJF2UZXjfbA6yNHig4Jvg.aPVGN0J-JUfqzYhuQ_pkFA", "fingerprint": "cfb9bf8efec58af5f5231d73d7785f2eb3991c3dae8b1539a3cde9fdb6cd6dab" } jwe = enc_metadata["jwe"] fingerprint = enc_metadata["fingerprint"] # get the private key (Mastercard Encryption Key) associated with fingerprint private_key_file = "path/to/certs/keyname-mastercard-encryption-key.p12" payload = { "enc": jwe, } cfg = { "paths": { "$": { "toEncrypt": {}, "toDecrypt": { "enc.jwe": "dec", } } }, "encryptedValueFieldName":"jwe", "decryptionKey": private_key_file, "decryptionKeyPassword": "" } conf = JweEncryptionConfig(cfg) metadata = decrypt_payload(payload=payload, config=conf) key = base64.b64decode(metadata["key"]) iv = base64.b64decode(metadata["iv"]) tagSuccess = base64.b64decode(metadata["tagSuccess"]) tagFail = base64.b64decode(metadata["tagFail"]) def decrypt_file(key: bytes, nonce: bytes, enc_file: str, dec_file: str, tag: bytes): blocksize = 64 * 1024 * 1024 # 64 MB block with open(enc_file, 'rb') as reader, open(dec_file, 'wb') as writer: cipher = AES.new(key, AES.MODE_GCM, nonce=nonce, use_aesni=True) # decrypt large file in 64 MB chunk. This is to avoid loading entire file in memory while True: block = reader.read(batch_size) if not block: break writer.write(cipher.decrypt(block)) cipher.verify(tag) enc_file = f"path/to/transactions_YYYYMMDDHHMMSS_success.bin" dec_file = f"path/to/transactions_YYYYMMDDHHMMSS_success.csv" decrypt_file(key, iv, enc_file, dec_file, tagSuccess) enc_file = f"path/to/transactions_YYYYMMDDHHMMSS_fail.bin" dec_file = f"path/to/transactions_YYYYMMDDHHMMSS_fail.csv" decrypt_file(key, iv, enc_file, dec_file, tagFail) ``` ## File Format {#file-format} The CSV file you send to Mastercard must contain externalCustomerId, accountType, description, and amount fields for each row. For best results and to improve your ability to map our results back to your data, ensure you provide each of the following fields listed below. Warning: The externalCustomerId and externalAccountId fields are to allow you to map the transactions back to your data. **Do not send Mastercard plaintext representations of customer or account IDs**. When used, the representative IDs must be obfuscated through cryptographically strong hashing (we recommend using SHA-2 or SHA-3 methods). You can also use your own internal hashing mapping. | Column Name | Description | Data type | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | externalCustomerId | Identifier for you to use to match the transactions back on your end. Mastercard will simply respond with the exact same ID. This should not be a real customer ID. | String, up to 100 characters. | | externalAccountId | Identifier for you to use to match the transactions back on your end. Mastercard will simply respond with the exact same ID. This should not be a real account ID. | String, up to 100 characters. | | accountType | A string that denotes the account type, i.e., savings, checking, etc. If "Unknown" is provided, Data Enrichment will assume it is a checking account. An incorrect assumption could impact the results from Data Enrichment. | String, one of these possible types: "checking", "savings", "creditCard", "brokerageAccount", "investment", "healthSavingsAccount", "unknown". | | postedTimestamp | The date and time the transaction posted. | String, up to 32 characters. Should be in ISO8601 format. | | transactionTimestamp | The date and time the transaction occurred. | String, up to 32 characters. Should be in ISO8601 format. | | description | Description of the transaction. | String, up to 1024 characters. | | memo | Memo of the transaction. | String, up to 511 characters. | | amount | Value amount for transaction. | Number (double). | | directionIndicator | The directionIndicator should be from the perspective of the account holder. If you always send us positive amount values, you MUST send us corresponding directionIndicator values to ensure the categorization logic works as intended. If you have internal logic to provide the amount field as either positive or negative, do not send us data in the directionIndicator. | String, either "Debit" or "Credit". | | transactionFee | Transaction Fee for transaction. | Number (double). | | type | Type for transaction, such as debit or credit. | String, up to 32 characters. | | externalTransactionId | Transaction Id to link the transaction back to your system. While not required, this is **strongly** recommended. Mastercard does not guarantee the order of transactions in the input file will match the order of transactions in the output file. | String, up to 100 characters. | | additionalDetails | Each transaction can optionally include up to 30 sets of additional details as key-value pairs. For each additional detail you need to provide two consecutive columns, one with the key string and the following column with the value string. | String, up to 100 characters for the key and 255 characters for the value. | ## SFTP Folder Structure {#sftp-folder-structure} Files sent for batch processing should be placed in your /input folder. The result file will appear in your /output folder once it has been fully processed (i.e., it is safe to download the file as soon as it appears in the /output folder). As an approximate rule, you should allow for 10 minutes per million rows of transactions, plus 15 minutes, before checking the output folder: * 1,000,000 rows --- allow at least 25 minutes * 2,000,000 rows --- allow at least 35 minutes * 3,000,000 rows --- allow at least 45 minutes * 4,000,000 rows --- allow at least 55 minutes * 5,000,000 rows --- allow at least 65 minutes * 6,000,000 rows --- allow at least 75 minutes ### File Naming Conventions {#file-naming-conventions} You should name your zip file and contents using the following format: * Zip Name: `transactions_YYYYMMDDHHMMSS.zip` Zip Contents: * Encrypted file: `transactions_YYYYMMDDHHMMSS.bin` * Metadata file: `transactions_YYYYMMDDHHMMSS.metadata.json` The zip file returned will be in the following form: * Zip Name: `transactions_YYYYMMDDHHMMSS_output.zip` Zip Contents: * Encrypted Result files: * `transactions_YYYYMMDDHHMMSS_success.bin` * `transactions_YYYYMMDDHHMMSS_fail.bin` * Metadata file: `transactions_YYYYMMDDHHMMSS.metadata.json` Structure of metadata.json: ```json { "jwe": "generated JWE", "iv": "base64 encoded string of iv bytes", "tag": "base64 encoded string of tag bytes" } ``` ## Example File Input and Output {#example-file-input-and-output} We provide example CSV files for input (before data enrichment) and output (after data enrichment) below. * Example input file: [data-enrichment-batch-input.csv](https://static.developer.mastercard.com/content/open-finance-us/uploads/batch/data-enrichment-batch-input.csv) (5KB) * Example output file: [data-enrichment-batch-output.csv](https://static.developer.mastercard.com/content/open-finance-us/uploads/batch/data-enrichment-batch-output.csv) (12KB) --- # Non-SDK Integration Guide for Android source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-android/index.md This page outlines the non-SDK solution and steps needed to load the Data Connect URL in your Android Mobile App (either inside a WebView or Secure Container). This documentation also includes Universal Link and deep link configuration, as well as details on customizing the `WebViewClient` and secure container (Custom Chrome Tabs) for enhanced control and handling of web interactions. These are the steps which occur when launching: 1. Launch your [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) (generated with `isHostedInMobileApp` flag set as true and with the `redirectUri` provided) --- either in a web view or secure web container inside your mobile app. 2. After successful FI OAuth account addition, control returns to your app where you dismiss the already open secure container or web view. Secure containers are mandatory in some situations (for example, Chase does not allow their consent URL to be launched from within insecure webviews). Below we provide details of the following: * **Implementation A** --- Data Connect URL launched in Web View, FI OAuth session opened in Secure Container (Chrome Custom Tabs) as we don't support WebViews for OAuth process. * Scenario 1: FI's app is installed --- the FI app will launch and the OAuth session will occur in the FI's app. * Scenario 2: FI's app is not installed --- the FI OAuth login page will open in new a Chrome Custom Tab as a pop up. * **Implementation B** --- Data Connect URL launched in new separate Secure Container (Chrome Custom Tabs) and where no WebViews are involved. * Scenario 1: FI app is installed --- the FI app will launch and the OAuth session will occur in the FI app. * Scenario 2: FI app is not installed --- the FI OAuth login page will open in the same Chrome Custom Tab. Tip: In order to support [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) make sure you pass a suitable `redirectUri` parameter in your Generating Data Connect URL call. ## Android Project Setup {#android-project-setup} Modify your app-level Gradle file (build.gradle) as follows: dependencies { // ... implementation 'androidx.browser:browser:' } Find the latest version here - in a new tab The Android App needs the `INTERNET` permission to access the WebView. Include this permission in the `AndroidManifest.xml` file. ```xml ..... ``` For further details on app to app setup see here. Listen to your AppLinks / DeepLinks to the `ConnectRedirectActivity` in the `AndroidManifest.xml` file. ```xml ``` ## Implementation A (Data Connect URL in WebView) {#implementation-a-data-connect-url-in-webview} In this implementation, the Data Connect URL (which must be generated with `isHostedInMobileApp` flag as true and `redirectUri` set) is launched in a WebView, then a secure container (Chrome Custom Tab) used for the OAuth popup. ### WebView Configurations {#webview-configurations} Include the WebView component in your layout XML file. ```xml ``` ### WebView Initialization {#webview-initialization} Create an Activity and create the following variables globally in your Activity. ```java private WebView webView; private Context context; ``` Initialize `webView` and `context` in your Activity's `onCreate` using the following code. Create the `ConnectWebViewClient` and `OauthWebChromeClient` class within the same Activity. ```java context = this; webView = findViewById(R.id.webView); webView.getSettings().setJavaScriptEnabled(true); webView.getSettings().setAllowFileAccess(true); webView.getSettings().setSupportMultipleWindows(true); webView.setWebViewClient(new ConnectWebViewClient()); webView.setWebChromeClient(new OauthWebChromeClient()); webView.loadUrl("Pass Your Data Connect WebSDK integrated URL"); ``` ### Loading Your Data Connect URL Inside the WebView {#loading-your-data-connect-url-inside-the-webview} The `ConnectWebViewClient` class extends `WebViewClient` and handles URL loading in the main WebView. Customize the `shouldOverrideUrlLoading` method within `ConnectWebViewClient` to control how URLs are loaded in the main WebView. ```java // this class handles the loading of the urls inside the WebView. private class ConnectWebViewClient extends WebViewClient { @Override public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) { String url = request.getUrl().toString(); handleConnect(view,request.getUrl()); return true; } } ``` ### Handling OAuth Login URL and App to App {#handling-oauth-login-url-and-app-to-app} In order for App to App authentication to work, the `OauthWebChromeClient` class extends `WebChromeClient` and manages the creation of a new WebView for handling Financial Institution OAuth events. Customize the shouldOverrideUrlLoading method within `OauthWebChromeClient` to handle specific OAuth URLs and load them into the Chrome Custom Tabs. When the FI's OAuth process is completed by the user, the FI page in the Chrome Custom Tab will automatically close itself as per the Activity configured via AppLink or DeepLink which is mentioned in the 'AndroidManifest.xml' file (see here). Control then returns to your app's Activity which runs Data Connect in the background with an add accounts screen. ```java // handle the opening of the OAuth Login page OauthWebChromeClient private class OauthWebChromeClient extends WebChromeClient { @Override public boolean onCreateWindow(WebView view, boolean isDialog, boolean isUserGesture, Message resultMsg) { Webview mWebviewPop = new WebView(context); WebView.WebViewTransport transport = (WebView.WebViewTransport) resultMsg.obj; transport.setWebView(mWebviewPop); resultMsg.sendToTarget(); } } ``` ### Dismiss Web View {#dismiss-web-view} ```java // handle and dismiss the webview private void handleConnect(WebView view, Uri uri){ try { String reason = uri.getQueryParameter("reason"); if( uri.toString().equals("https://example.com") ) { // https://example.com is your app link view.loadUrl(connectURLGlobal); } else if(reason != null){ switch (reason){ case "timeout": Log.d("Connect","Connect Flow Timeout"); view.destroy(); finish(); break; case "complete": Log.d("Connect","Connect Flow Completed Successfully"); view.destroy(); finish(); break; case "exit": Log.d("Connect","User Cancelled"); view.destroy(); finish(); break; case "error": Log.d("Connect","Some Error Occurred"); finish(); break; default: } } else { view.loadUrl(uri.toString()); } catch (Exception ignored){ Log.d("Connect", "Some Error Occurred"); } } } ``` ## Implementation B (Data Connect in Secure Container) {#implementation-b-data-connect-in-secure-container} In this implementation, the Data Connect URL (which must be generated with `isHostedInMobileApp` flag as true and `redirectUri` set) is launched a secure container (Chrome Custom Tab) and no WebView is used. ### Loading Your Web URL Inside the Secure Web Container {#loading-your-web-url-inside-the-secure-web-container} To open Chrome Custom Tabs, use the `openLinkInChromeCustomTabs` function. This function takes the String URL as a parameter and relies on a context instance typically representing your Activity. ```java // pass your web url here for example "https://example.com" private void openLinkInChromeCustomTabs(String url) { try { // To open Chrome Custom Tabs CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder(); CustomTabsIntent customTabsIntent = builder.build(); customTabsIntent.intent.setPackage("com.android.chrome"); customTabsIntent.launchUrl(context, Uri.parse(url)); } catch (Exception exception) { Log.d("Connect", "Something went wrong, please check if Chrome Browser is installed"); } } ``` ### Handling OAuth Login URL and App to App {#handling-oauth-login-url-and-app-to-app-1} No extra code is required to handle OAuth events. Chrome Custom Tabs will handle the events automatically. It does this by opening another page in the same Chrome Custom Tab when the FI app is not present, or it will open the app if present on the user's device. When the FI's OAuth process is completed by the user, the FI page in the Chrome Custom Tabs will automatically close itself as per the Activity configured via AppLink or DeepLink which is mentioned in the `AndroidManifest.xml` file (see here). Control then returns to your app's Activity which runs Data Connect in the background with select or review account screen. Tip: To maintain the Chrome Custom Tabs session when redirecting back to your app, it is necessary to create an additional Activity and listen for your AppLinks / DeepLinks in that Activity. This ensures a seamless user experience, preventing any disruption in the flow of the application and the closure of the Chrome Custom Tabs. Create an Activity named `ConnectRedirectActivity` and finish the Activity in its `onCreate` method to handle redirection back to the original Activity from which you initially launched the Chrome Custom Tabs. ```java public class DefaultRedirectActivityAndroid extends Activity { @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); Intent intent = new Intent(DefaultRedirectActivityAndroid.this, ConnectRedirectActivity.class); intent.setData(getIntent().getData()); startActivity(intent); } } ``` Reload Custom chrome tabs according to response from Applink query parameters: ```java public class ConnectRedirectActivity extends AppCompatActivity { protected void onNewIntent(Intent intent) { super.onNewIntent(intent); webView.loadUrl(connectURL); if (intent.getData().getQueryParameter("reason") == null) { isCCTOpen = true; CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder(); CustomTabsIntent intent1 = builder.build(); intent1.launchUrl(WebviewActivityAllScenarios.this, Uri.parse(connectURL)); } } } ``` --- # Non-SDK Integration Guide for iOS source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/non-sdk/non-sdk-ios/index.md This page outlines the non-SDK solution and steps needed to load the Data Connect URL in your iOS Mobile App (either inside a WebView or Secure Container). This documentation also includes Universal Link and deep link configuration, as well as details on customizing the `WebViewClient` and secure container (`SFSafariViewController`) for enhanced control and handling of web interactions. These are the steps which occur when launching: 1. Launch your [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) (generated with `isHostedInMobileApp` flag as true and with the `redirectUri` provided) ---either in a web view or secure web container inside your mobile app. 2. After successful FI OAuth account addition, control returns to your app where you dismiss the already opened secure container or web view. Secure containers are mandatory in some situations (for example, Chase does not allow their consent URL to be launched from within insecure webviews). Below we provide details of the following: * **Implementation A** --- Data Connect URL launched in Web View, FI OAuth session opened in Secure Container (`SFSafariViewController`) as we don't support WebViews for OAuth process. * Scenario 1: FI app is installed --- the FI app will launch and the OAuth session will occur in the FI's app. * Scenario 2: FI app is not installed --- the FI OAuth login page will open in new instance `SFSafariViewController` as a pop up. * **Implementation B** --- Data Connect URL launched in new separate Secure Container (`SFSafariViewController`), no WebViews are involved. * Scenario 1: FI app is installed --- the FI app will launch and the OAuth session will occur in the FI app. * Scenario 2: FI app is not installed --- the FI OAuth login page will open in same `SFSafariViewController`. Tip: In order to support [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) make sure you pass a suitable `redirectUri` parameter in your Generating Data Connect URL call. ## iOS Project Setup {#ios-project-setup} Make sure you have set up the following in your XCode project. Under your Project target, select the Signing and Capabilities section: * Under this section click on **+Capability** to add a new capability, and select **Associated Domains** . Add your domain here. Under the **Signing** section, make sure you have set the development team correctly (or leave the team value as _*None*). * This will create entitlement file `YourProject.entitlements`: ```xml com.apple.developer.associated-domains applinks:*.example.com ``` For further details on app to app setup see here. ## Implementation A (Data Connect URL in WebView) {#implementation-a-data-connect-url-in-webview} In this implementation, the Data Connect URL (which must be generated with `isHostedInMobileApp` flag as true and `redirectUri` set) is launched in a WebView, then a secure container (`SFSafariViewController`) used for the OAuth popup. ### WebView Initialization {#webview-initialization} In your view controller, create a `WKWebView` (named `webView` in the following example) to load Data Connect URL (Generated with with `isHostedInMobileApp` flag and `redirectUri` parameters) in it Then, add setup steps for the `WKWebView` in the `viewDidAppear` function within which `WKPreferences`, `WKWebViewConfiguration` and delegates (`uiDelegate` and `navigationDelegate`) are added to the view controller. ```swift import UIKit import WebKit import SafariServices import Foundation class ViewController: UIViewController, SFSafariViewControllerDelegate { var webView: WKWebView! override func viewDidAppear(_ animated: Bool) { setupWebView() loadUrlInWebView() } // Add this function if not added already in basic XCode project installation steps. func setupWebView() { let preferences = WKPreferences() preferences.javaScriptCanOpenWindowsAutomatically = true let configuration = WKWebViewConfiguration() configuration.preferences = preferences webView = WKWebView(frame: view.bounds, configuration: configuration) webView.autoresizingMask = [.flexibleWidth, .flexibleHeight] webView.uiDelegate = self webView.navigationDelegate = self view.addSubview(webView) } ``` ### Loading Your Data Connect URL Inside the WebView {#loading-your-data-connect-url-inside-the-webview} Call the `loadUrlInWebView()` function to load your domain URL in the `webView`. ```swift func loadUrlInWebView(){ if let url = URL(string: "Generated Data Connect URL with isHostedInMobileApp flag as true and redirectUri parameters") { let urlRequest = URLRequest(url: url) webView.load(urlRequest) } } ``` ### Handling OAuth Login URL and App to App {#handling-oauth-login-url-and-app-to-app} Add a `WKUIDelegate` extension which listens for the FI OAuth Event in Data Connect and opens a Secure Container or FI App. Add a `SafariVIewController` delegate to listen for manual closing of secure container. ```swift func closeChildWebViewOrPopUp(){ if(self.presentedViewController != nil){ self.dismiss(animated: true) } } extension WKWebContainerViewController: SFSafariViewControllerDelegate { public func safariViewControllerDidFinish(_ controller: SFSafariViewController) { controller.dismiss(animated: true, completion: nil) self.closeChildWebViewOrPopUp() } } extension ViewController: WKUIDelegate { func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? { var popupWebView = WKWebView(frame: view.bounds, configuration: configuration) popupWebView!.autoresizingMask = [.flexibleWidth, .flexibleHeight] popupWebView!.navigationDelegate = self popupWebView!.uiDelegate = self popupWebView?.isHidden = true if let url = navigationAction.request.url { OpenUniversalLink.inAnyNativeWay(url: url) { success in // Creation of OpenUniversalLink class is in Step no. 3 if !success { let sfSafariViewController:SFSafariViewController = SFSafariViewController(url:url) sfSafariViewController.delegate = self self.present(sfSafariViewController, animated: true, completion: nil) } } } return popupWebView! } } ``` Add the following code in `SceneDelegate` class for control to close already opened secure container. ```swift // Scene delegate functions to Close Secure Container / Webview Pop Up class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, continue userActivity: NSUserActivity){ self.closeSecureContainerPopUp(url: userActivity.webpageURL) } func closeSecureContainerPopUp(url:URL?) { if(shouldClosePopUp(currentURLString: url.absoluteString)){ var viewController:ViewController = ViewController() if ((self.window?.rootViewController?.children.count)! > 0) { viewController = self.window?.rootViewController?.children.last as! ViewController } else if (self.window?.rootViewController is ViewController) { viewController = self.window?.rootViewController as! ViewController } DispatchQueue.main.asyncAfter(deadline: .now() + 0.005) { viewController.closeChildWebViewOrPopUp() } } } } func shouldClosePopUp(currentURLString: String) -> Bool { guard let urlComponent = URLComponents(string: currentURLString) else { return false } let queryItems = urlComponent.queryItems if let typeQuery = queryItems?.first(where: { $0.name == "redirectedFrom" }), let value = typeQuery.value{ if(value == "maOBFIOauth"){ return true } } return false } ``` Create a new `OpenUniversalLink` class using the following code. This will open the FI app using the universal link if the app is present on the device. ```swift // Sample Open link class import Foundation import UIKit import SafariServices public class OpenUniversalLink { typealias completionHandler = (_ success:Bool) -> Void static func inAnyNativeWay(url: URL, dontPreferEmbeddedBrowser: Bool = false,completion: @escaping completionHandler) { // OPEN AS UNIVERSAL LINK IF EXISTS else : EMBEDDED or EXTERNAL if #available(iOS 10.0, *) { // Try to open with owner universal link app UIApplication.shared.open(url, options: [UIApplication.OpenExternalURLOptionsKey.universalLinksOnly : true]) { (success) in if !success { completion(false) } } } else { completion(false) } } } ``` Dismissing the web view which has opened Data Connect URL: ```swift func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { if let url = navigationAction.request.url{ if(url.description.contains("https://example.com/") && self.shouldCloseWebView(currentURLString: url.description)){ self.navigationController?.popViewController(animated: true) } } decisionHandler(.allow) } // Add this function to check when to pop webview loaded with connect url func shouldCloseWebView(currentURLString: String) -> Bool { guard let urlComponent = URLComponents(string: currentURLString) else { return false } let queryItems = urlComponent.queryItems if (queryItems?.first(where: { $0.name == "reason" })) != nil{ return true } return false } ``` ## Implementation B (Data Connect in Secure Container) {#implementation-b-data-connect-in-secure-container} In this implementation, the Data Connect URL (which must be generated with `isHostedInMobileApp` flag as true and `redirectUri` set) is launched a secure container (`SFSafariViewController`) and no WebView is used. First, add a close function and code to launch a Safari View Controller in the existing `ViewController` to help open the FI OAuth login screen (or to open the FI app for OAuth Login): ```swift class ViewController : UIViewController, SFSafariViewControllerDelegate { var sfSafariViewController:SFSafariViewController? = nil override func viewDidAppear(_ animated: Bool) { launchSafari(url: "Generated Data Connect URL with isHostedInMobielApp and redirectUri parameters") } func launchSafari(url:String){ let sfSafariViewController:SFSafariViewController = SFSafariViewController(url: URL.init(string: url)!) sfSafariViewController.delegate = self self.present(sfSafariViewController, animated: true, completion: nil) } func closeChildWebViewOrPopUp(){ if(self.presentedViewController != nil){ self.dismiss(animated: true) } } } ``` ### Closing the Secure Web Container {#closing-the-secure-web-container} Add the following code in the `SceneDelegate` class to handle the closure of the secure web container: ```swift // Scene delegate functions to close secure web container / webview pop up class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { self.closeSecureContainerPopUp(url: userActivity.webpageURL) } func closeSecureContainerPopUp(url:URL?) { if(shouldCloseSecureContainer(currentURLString: url.absoluteString)){ var viewController:ViewController = ViewController() if( (self.window?.rootViewController?.children.count)! > 0) { viewController = self.window?.rootViewController?.children.last as! ViewController } else if (self.window?.rootViewController is ViewController) { viewController = self.window?.rootViewController as! ViewController } DispatchQueue.main.asyncAfter(deadline: .now() + 0.005) { viewController.closeChildWebViewOrPopUp() } } } } func shouldCloseSecureContainer(currentURLString: String) -> Bool { guard let urlComponent = URLComponents(string: currentURLString) else { return false } let queryItems = urlComponent.queryItems if (queryItems?.first(where: { $0.name == "reason" })) != nil{ return true } return false } ``` --- # Example - Using Dwolla as Payment Processor source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/example-dwolla/index.md In this example we show how you as a Mastercard Open Finance client (partner) can integrate using Dwolla as your payment processor. The following summarizes the steps needed by both client and processor: 1. The client shows the Data Connect Experience flow to the customer so they can grant permission to share the appropriate banking data. 2. Once the customer has provided consent to access their banking data, the client creates a suitable access token (consent receipt). 3. The client shares the consent receipt with the payment processor. In the case of Dwolla, this is done using the Dwolla Exchange API. 4. The processor (Dwolla) can now use the consent receipt to access the relevant banking data using Mastercard Open Finance APIs, in this case the end user's account balance and ACH routing data. ## Client Integration Steps {#client-integration-steps} Here are the basic steps involved for setting up a new customer and allowing them to give the permissions needed: * Use the Add Customer endpoint to create the new customer record: API Reference: `POST /aggregation/v2/customers/active` * Call the Generate Data Connect URL endpoint to obtain a URL for the connect flow (or use the Data Connect SDK): API Reference: `POST /connect/v2/generate` * Display the [Data Connect experience](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) so the customer (end-user) can consent to sharing their banking data. For testing purposes, search as a user for FinBank and use profile_09 in the Data Connect experience (see [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) for more details about test profiles). * Call [Refresh customer accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md). * Send a Generate Access Key request to obtain a consent receipt. Your request needs to specify the products which the processor will be able to access, and for how long. API Reference: `POST /aggregation/v1/partners/accessKey` The response object forms the consent receipt. It contains an access token and confirmation of the Open Finance products which Dwolla are allowed to use, based on the consents given by the customer (end user). The consent receipt also includes a digital signature and time periods for which access is granted. * Call the Dwolla [Create Exchange](https://developers.dwolla.com/docs/api-reference/exchanges/create-an-exchange-for-an-account) API. You will need to provide the information returned as the consent receipt as a JSON object in the body of the call to the Dwolla Create Exchange API. See the "Finicity" example. This will return an Exchange Link URL which can be used with Dwolla's Create Funding Source API. See the [Dwolla Secure Exchange](https://developers.dwolla.com/docs/secure-exchange) documentation for details. * Call the Dwolla [Create Customer Exchange Funding Source](https://developers.dwolla.com/docs/api-reference/funding-sources/create-customer-funding-source) API to create the funding source using the Exchange link from the previous step. Dwolla will now contact Mastercard Open Finance US to obtain ACH details (routing and account numbers). See the [Dwolla Funding Sources](https://developers.dwolla.com/docs/api-reference/funding-sources) documentation for details. * Your application can now submit the Dwolla Transfer API using the Dwolla Funding Source created when you are ready to process a payment. There is no dependency at this point on having a Mastercard Open Finance access key, you will only need to contact the Dwolla API for this. If everything has been set up correctly, Dwolla will have the necessary consents and access tokens to access the Mastercard Open Finance APIs needed to verify the customer account, fetch the customer's current balance, and obtain the customer's ACH routing and real account number in order to initiate payment. --- # Bill Pay Switch source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/bill-pay-switch/index.md Bill Pay Switch provides the ability for consumers to switch their recurring automatic payments from their incumbent account into a new/existing account at a Financial Institution. Bill Pay Switch empowers consumers to update their payment information (ACH or Card on file) for recurring bills and subscriptions, making it easier to switch financial providers. Warning: This product may not be used for purposes subject to the Fair Credit Reporting Act. ## How It Works {#how-it-works} Customers will use your app to launch a Connect Transfer session to establish a connection enabling the bill pay switch with the merchant or service provider concerned. The Connect Transfer experience differs from the regular Mastercard Data Connect experience since it allows end users to login and authenticate with the merchant or service provider (note we use Atomic, a partner of Mastercard, for parts of the user experience). Diagram billpay-switch-mvp You must have already created a [customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) record using your `partnerId` to use this service. Note that the endpoints require [authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). Tip: For testing in Sandbox with [Test Customers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers), note that the final screen in the Connect Transfer flow will prompt the user to "Return to Partner App" during Sandbox testing. When you move to Production, the screen will instead use the application name associated with your experience ID, if provided. ### Integration Options {#integration-options} Bill Pay Switch is only supported for mobile, via the iOS, Android and React Native [Connect Transfer SDKs](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) that we provide. The Connect Transfer mobile SDKs provide native mobile versions of the Atomic user experience, which is not supported by the regular Data Connect mobile SDKs. The Connect Transfer SDKs support TrueAuth authentication of the end user with the merchant or service provider. Warning: Unlike Deposit Switch, Bill Pay Switch is not suitable for integration into a web application either directly or via our Data Connect Web SDK. Currently we also do not support webhooks for Bill Pay Switch, so your mobile app must implement code to handle the SDK events. ## Generate a Connect Transfer URL for Bill Pay Switch {#generate-a-connect-transfer-url-for-bill-pay-switch} In order to allow customers to be able to set up bill pay switches, you will need to offer them a specific Data Connect user experience that allows them to set up the switch. This is different from the usual Data Connect experience which just allows customers to connect bank accounts. API Reference: `POST /connect/generate/transfer/bill-pay-switch` Note that the Connect Transfer experience uses Atomic, a partner of Mastercard, for parts of the user experience. See the [Experience Design Guide section on Bill Pay Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/bill-pay-switch/index.md) for more details of the user flow. ## Get Bill Pay Switches by Customer ID {#get-bill-pay-switches-by-customer-id} Retrieve a list of the Bill Pay Switches that are defined for a given Customer ID. For each switch the ID, status, date of creation, and if applicable any status is returned. API Reference: `GET /transfer/customers/{customer_id}/bill-pay-switches` ## Get Bill Pay Switch Details {#get-bill-pay-switch-details} Retrieve the details of a specific Bill Pay switch, once you know the ID of the switch. API Reference: `GET /transfer/customers/{customer_id}/bill-pay-switches/{switch_id}` A successful response will include details of the status of the switch and also details of the provider, the bank / FI, and the last four digits of the customer's account or card number. ## How to Test Bill Pay Switch {#how-to-test-bill-pay-switch} To test the Bill Pay Switch functionality, follow these steps: 1. Make sure you already have a suitable partner ID and test customer which has at least one bank account connected (see the Quick Start Guide). 2. Generate a suitable URL for testing the user flow by calling Connect Transfer URL. 3. Load the Connect Transfer URL in an iOS or Android test app (note that you cannot test directly in a browser as the Bill Pay Switch experience is tied to mobile). 4. This will then show the Atomic user experience where you can select a merchant or service provider. ### Testing Details {#testing-details} When testing the bill pay switch flow, you can use the following usernames to test various scenarios. Enter the username shown when asked to authenticate (you can use any password). If an email address is required for authentication, append `@example.com` to the username. #### Successful Operation {#successful-operation} Test where the user's credentials are correct and the task completes. When answering MFA questions, any answer will be accepted. | Username | Phone Number | Description | |-----------|----------------|------------------------------| | test-good | (555) 555-0100 | Test a successful operation. | #### User Issue {#user-issue} Test where there is an error that occurs due to an action of the user. | Username | Phone Number | Description | |----------------------------|----------------|-----------------------------------------------------------------------------------------------------| | test-subscription-inactive | (555) 555-0122 | Test a user who doesn't have an active subscription with the service provider. | | test-bundle-wrong-provider | (555) 555-0123 | Test a user whose subscription bundle is managed by another service. | | test-payment-method-locked | (555) 555-0124 | Test a user whose service provider has temporarily disallowed updates to the user's payment method. | #### Service Provider Issue {#service-provider-issue} Test where the user encounters an issue originating from the service provider. | Username | Phone Number | Description | |-----------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------| | test-payment-method-not-supported | (555) 555-0125 | Test a user whose chosen payment method isn't supported by the service provider. | | test-payment-switch-unsuccessful | (555) 555-0126 | Test a user whose payment method could not be updated. We use this generic fail reason when none of the other fail reasons apply. | #### Cards {#cards} To test in Sandbox, use one of the following test card numbers to simulate different card brands. Warning: These test cards are the only cards currently supported for Sandbox testing. | Card Number | CVV | Card Brand | |------------------|--------------|------------------| | 5555555555554444 | Any 3 digits | Mastercard | | 378282246310005 | Any 4 digits | American Express | | 4242424242424242 | Any 3 digits | Visa | --- # Balance Analytics source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md Balance Analytics (BA) provides insights into a customer's account balances over time, helping assess liquidity, trends, and potential risk for lending and portfolio decisions. BA analyzes up to 24 months of transaction history (as available) and returns attributes such as minimum, maximum, and average balances over the desired time intervals. Learn more about Mastercard's [Assets \& Balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#assets-and-balances) solutions. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Data History:** Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using `fromDate` and defaults to 24 months * **Balance Analytics:** Includes min, max, and average cash balance attributes by requested time interval * **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type:** Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge * **Supported Account Types:** Checking, Savings, Money Market, CD, Investment account types, Mortgage, Loan, Credit Card, Line of Credit, Payroll, Student Loan, Education Savings, Health Savings Account * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The Balance Analytics product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) for consumer FCRA use cases and for business use cases where the applicant is personally guaranteeing the loan * [Create and link a business record to the customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses) if a business use case * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows) ## Generate a Balance Analytics Report {#generate-a-balance-analytics-report} To generate or refresh a Balance Analytics report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/reports/balance-analytics/userTypes/{userType}` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * Use the `timeIntervalType` to select the periodicity at which attributes will be calculated. Defaults to Monthly Calendar. * Customize the type of Balance Analytics report received based on inputs provided when generating the report. | Report Type | User Type | forCraPurpose | forFtcPurpose | applicantIs PersonalGuarantor | Consumer Required? | Customer Required? | Business Required? | |-------------|-----------|---------------|---------------|-------------------------------|--------------------|--------------------|--------------------| | barpcra | personal | true | N/A | N/A | Y | Y | N | | barpnoncra | personal | false | N/A | N/A | N | Y | N | | barbcra | business | true | false | true | Y | Y | Y | | barbftc | business | false | true | false | N | Y | Y | | barbnoncra | business | false | false | false | N | Y | Y | ## Get Balance Analytics Reports {#get-balance-analytics-reports} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "sd1j45yn37wr-barpcra", "customerType": "active", "customerId": 1275320, "requestId": "7a7qyps2iy", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "title": "Mastercard Open Banking Balance Analytics", "consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "consumerSsn": "1234", "disputeStatement": "Invalid data present.", "constraints": { "analyticsReportData": { "forCraPurpose": true, "timeIntervalTypes": [ "MONTHLY_CALENDAR" ] } }, "type": "barpcra", "status": "success", "createdDate": 1579819592, "startDate": 1512594823, "endDate": 1575666823, "days": 730, "institutions": [ { "id": "102105", "name": "FinBank Profiles", "urlHomeApp": "http://www.bank.example.com", "accounts": [ { "id": "1111", "ownerName": "PATRICK & LORRAINE PURCHASER", "ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859", "ownerAsOfDate": 1577986990, "name": "Checking", "number": "XX1111", "type": "checking", "aggregationStatusCode": "0", "currentBalance": 100000, "availableBalance": 1000, "balanceDate": 1614880526, "transactions": [ { "id": "00000001", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000002", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000003", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000004", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" } ], "analytics": [ { "transactionalAttributes": [], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "timeIntervalType": "MONTHLY_CALENDAR", "periods": [ { "startDate": "2023-02-05", "endDate": "2023-02-28", "sum": 75517.99999999997, "count": 24, "mean": 3146.583333333333, "median": 3145.2, "min": 3145.2, "max": 3178.4, "standardDeviation": 6.776921621700182, "beginningValue": 3145.2, "endingValue": 3178.4 }, { "startDate": "2023-03-01", "endDate": "2023-03-31", "sum": 95350.54000000005, "count": 31, "mean": 3075.823870967742, "median": 3178.4, "min": 2946.3, "max": 3329.22, "standardDeviation": 132.58604314877732, "beginningValue": 3178.4, "endingValue": 3329.22 } ] } ] } ], "streams": [ { "id": "2b96f6d4-4882-4db2-96c6-f89530a68f1c", "payor": "TD AMERITRADE", "payee": "John Smith", "cadence": 15, "recency": 124, "transactionIds": [ "00000003", "00000004", "00000001" ] }, { "id": "dafc9b5d-762d-4f91-a429-f80573944bcd", "payor": "John Smith", "payee": "TD AMERITRADE", "cadence": 0, "recency": 139, "transactionIds": [ "00000002" ] } ] } ] }, { "id": "2222", "ownerName": "PATRICK & LORRAINE PURCHASER", "ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859", "ownerAsOfDate": 1577986990, "name": "Checking", "number": "XX1111", "type": "checking", "aggregationStatusCode": "0", "currentBalance": 100000, "availableBalance": 1000, "balanceDate": 1614880526, "transactions": [ { "id": "00000005", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000006", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000007", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" }, { "id": "00000008", "amount": -81.7, "postedDate": 1614859200, "description": "TMOBILE*AUTO PAY", "normalizedPayee": "T-Mobile", "institutionTransactionId": "0000000000", "category": "Mobile Phone" } ], "analytics": [ { "transactionalAttributes": [], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "timeIntervalType": "MONTHLY_CALENDAR", "periods": [ { "startDate": "2023-02-05", "endDate": "2023-02-28", "sum": 75517.99999999997, "count": 24, "mean": 3146.583333333333, "median": 3145.2, "min": 3145.2, "max": 3178.4, "standardDeviation": 6.776921621700182, "beginningValue": 3145.2, "endingValue": 3178.4 }, { "startDate": "2023-03-01", "endDate": "2023-03-31", "sum": 95350.54000000005, "count": 31, "mean": 3075.823870967742, "median": 3178.4, "min": 2946.3, "max": 3329.22, "standardDeviation": 132.58604314877732, "beginningValue": 3178.4, "endingValue": 3329.22 } ] } ] } ], "streams": [ { "id": "b838ffb3-2549-43b3-a1b1-50bc13438e0f", "payor": "John Smith", "payee": "Whole Foods", "cadence": 0, "recency": 124, "transactionIds": [ "00000005", "00000008" ] }, { "id": "54214633-39d7-43f4-9314-bae2ce3b6af9", "payor": "John Smith", "payee": "Walmart", "cadence": 0, "recency": 139, "transactionIds": [ "00000006", "00000007" ] } ] } ] } ] } ], "customerAnalytics": { "transactionalAttributes": [], "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "timeIntervalType": "MONTHLY_CALENDAR", "periods": [ { "startDate": "2023-02-05", "endDate": "2023-02-28", "sum": 75517.99999999997, "count": 24, "mean": 3146.583333333333, "median": 3145.2, "min": 3145.2, "max": 3178.4, "standardDeviation": 6.776921621700182, "beginningValue": 3145.2, "endingValue": 3178.4 }, { "startDate": "2023-03-01", "endDate": "2023-03-31", "sum": 95350.54000000005, "count": 31, "mean": 3075.823870967742, "median": 3178.4, "min": 2946.3, "max": 3329.22, "standardDeviation": 132.58604314877732, "beginningValue": 3178.4, "endingValue": 3329.22 } ] } ] } ], "streams": [ { "id": "2b96f6d4-4882-4db2-96c6-f89530a68f1c", "payor": "TD AMERITRADE", "payee": "John Smith", "cadence": 15, "recency": 124, "transactionIds": [ "00000003", "00000004", "00000001" ] }, { "id": "dafc9b5d-762d-4f91-a429-f80573944bcd", "payor": "John Smith", "payee": "TD AMERITRADE", "cadence": 0, "recency": 139, "transactionIds": [ "00000002" ] }, { "id": "b838ffb3-2549-43b3-a1b1-50bc13438e0f", "payor": "John Smith", "payee": "Whole Foods", "cadence": 0, "recency": 124, "transactionIds": [ "00000005", "00000008" ] }, { "id": "54214633-39d7-43f4-9314-bae2ce3b6af9", "payor": "John Smith", "payee": "Walmart", "cadence": 0, "recency": 139, "transactionIds": [ "6010290887", "6010290914" ] } ] } } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a Balance Analytics report: [Balance_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Balance_Analytics_HTR.pdf) (3MB) ## Reading a Balance Analytics JSON Report {#reading-a-balance-analytics-json-report} This section provides a detailed description of the structure and format of the JSON version of Balance Analytics. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. ### Balance Analytics Attributes {#balance-analytics-attributes} The above sample demonstrates some, if not all, Balance Analytics attributes from the following table: | Attribute | Definition | Type | |---------------|----------------------------------------------------------------|-------| | ASSET_BALANCE | History of asset balances for the customer and their accounts. | State | ### Time Interval types {#time-interval-types} A report supports up to 2 time interval types currently. If a partner requests more than 2 interval types, the endpoint returns an error `More than 2 intervalTypes passed request`. If the time interval type is not specified, the default is `MONTHLY_CALENDAR`. The following table shows all possible time interval types you can request a report for: | Time Interval Type | Description | First (Earliest) period may be partial | First (Most Recent) period may be partial | Shortest possible period length | Longest possible period length | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------| | DAILY | The report will be broken up into one period for every calendar date in the report time period | NO | NO | 1 | 1 | | WEEKLY_CALENDAR | The report time period will be broken up into periods of 7 calendar dates, each beginning on Monday and ending on Sunday, except the first and last periods which may be partial | YES | YES | 1 | 7 | | WEEKLY_ROLLING_7 | The report time period will be broken up into periods of 7 calendar dates, counting backwards from the report end date | YES | NO | 1 | 7 | | BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, each beginning on a Monday and ending on the 2nd subsequent Sunday, except the first and last periods which may be partial | YES | YES | 1 | 14 | | BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date | YES | NO | 1 | 14 | | SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly 2 periods per calendar month, where both the first and last period may be partial, and periods will alternate between representing the 1st--15th and the 16th--end of the month | YES | YES | 1 | 16 | | MONTHLY_CALENDAR | The report time period will be broken up into 1 period per calendar month | YES | YES | 1 | 31 | | MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by 1 period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 36 | | QUARTERLY_CALENDAR | The report time period will be broken up into 1 period per 3 calendar months, where both the first and last period may be partial | YES | YES | 1 | 92 | | QUARTERLY_ROLLING_90 | The report time period will be broken up into 3 periods of 90 calendar dates followed by 1 period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 96 | | ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date | YES | NO | 1 | 366 | | HISTORICALLY | The report time period will be represented by exactly 1 period covering the duration of report data | NO | NO | 1 | Duration of report data | The following JSON snippet shows an example of how time interval type is requested: * Json ```json { "constraints": { "analyticsReportData": { "timeIntervalTypes": [ "MONTHLY_CALENDAR", "ANNUALLY" ] } } } ``` ### JSON report structure - Analytics section {#json-report-structure---analytics-section} Analytics will be provided at both the account level, grouped by (financial) institution, and at an aggregated customer level, similar to how most other Lend and OBB products work today. For the purpose of this document, consider a customer with the following two accounts that contain transactions: * Json ```json "accounts": [ { "id": 8059411974 }, { "id": 8059411978 } ] ``` The analytics section is divided into 3 sections: 1. Transactional attributes 2. State attributes 3. Streams ### Account-level analytics structure {#account-level-analytics-structure} * Json ```json "analytics": { "transactionalAttributes": [...], "stateAttributes": [...], "streams": [...] } ``` *Note: This section will be for each of the customer accounts.* ### Customer-level analytics structure {#customer-level-analytics-structure} * Json ```json "customerAnalytics": { "transactionalAttributes": [...], "stateAttributes": [...], "streams": [...] } ``` ### Transactional attributes {#transactional-attributes} Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. As an example, an attribute called DWELLING_EXPENSES may be a classification of all transactions that we assume to be a customer paying towards a mortgage, rent, home insurance, etc. Transactional attributes will be reported by one of the time interval type specified in the constraints by the requesting partner. *Currently, Balance Analytics does not have any transactional attributes.* ### State attributes {#state-attributes} The unit of data for state attributes is some generic "state" at a point in time. Whereas transactional attributes are based on specific events (the posting of a transaction), state attributes make some inference about a point in time based on some assembly of underlying data. Examples of state attributes might include something like the balance of an account over time, a calculation based on underlying transactions in a time period (e.g. net cash flow), or some other calculation such as a debt to income ratio. The following JSON snippets for transactional attributes on accounts and customer level. Please note the following: 1. For demonstration purposes, the below snippets show transaction data of 1 month for MONTHLY_CALENDAR time interval type. The actual report will have all transaction stats for all the months. 2. The period array for ANNUALLY will show aggregated data for all the months between the specified start and end dates. * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 609.5, "count": 31, "endDate": "2024-12-31", "endingValue": 621.7, "max": 621.7, "mean": 614.158064516129, "median": 609.5, "min": 609.4, "standardDeviation": 6.025654829894631, "startDate": "2024-12-01", "sum": 19038.9, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2024-12-01", "endDate": "2024-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 618.61, "count": 365, "endDate": "2025-06-18", "endingValue": 618.49, "max": 623.78, "mean": 618.0496712328767, "median": 619.59, "min": 609.4, "standardDeviation": 4.681207449827294, "startDate": "2024-06-19", "sum": 225588.13, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-06-19", "endDate": "2025-06-18", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 609.5, "count": 31, "endDate": "2024-12-31", "endingValue": 621.7, "max": 621.7, "mean": 614.158064516129, "median": 609.5, "min": 609.4, "standardDeviation": 6.025654829894631, "startDate": "2024-12-01", "sum": 19038.9, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2024-12-01", "endDate": "2024-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 1855.83, "count": 365, "endDate": "2025-06-18", "endingValue": 618.49, "max": 623.78, "mean": 618.0496712328767, "median": 619.59, "min": 609.4, "standardDeviation": 4.681207449827294, "startDate": "2024-06-19", "sum": 225588.13, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-06-19", "endDate": "2025-06-18", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "ASSET_BALANCE", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 1828.5, "count": 31, "endDate": "2024-12-31", "endingValue": 1865.1000000000001, "max": 1865.1000000000001, "mean": 1842.4741935483871, "median": 1828.5, "min": 1828.1999999999998, "standardDeviation": 18.07696448968397, "startDate": "2024-12-01", "sum": 57116.7, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2024-12-01", "endDate": "2024-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 1855.83, "count": 365, "endDate": "2025-06-18", "endingValue": 2473.96, "max": 2473.96, "mean": 1855.843506849315, "median": 1858.77, "min": 1828.1999999999998, "standardDeviation": 35.351654853132914, "startDate": "2024-06-19", "sum": 677382.88, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2024-06-19", "endDate": "2025-06-18", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` ### JSON fields description {#json-fields-description} | Key (Datatype) | Description | Applicable for Balance Analytics | |---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | attributeName (string) | Name of the attribute that we are reporting the numbers for. Refer to the attributes list above. | Yes | | reportedByTimePeriods (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type | | | periods (object) | Statistics of aggregated transactions over some time period. | | | beginningValue (number) | Value of the attribute as reported on the startDate of the period. | | | endingValue (number) | Value of the attribute as reported on the endDate of the period. | | | count (number) | For the selected time interval type, the number of state events that occurred during the period. For example, for monthly time interval, count will be shown for each day of the month. | | | endDate (string) | For the selected time interval type, the final day (inclusive) of the period being reported. | | | max (number) | For the selected time interval type, the maximum value in the period. | | | mean (number) | For the selected time interval type, the mean value in the period. | | | median (number) | For the selected time interval type, the median value in the period. | | | min (number) | For the selected time interval type, the minimum value in the period. | | | standardDeviation (number) | For the selected time interval type, the standard deviation in the period. | | | startDate (string) | For the selected time interval type, the first day (inclusive) of the period being reported. | | | sum (number) | For the selected time interval type, the arithmetic sum for the period. | | | comparedToCohorts (object) | An array comparing the customer's spending during a time period to the average customer's spending in various cohorts (e.g., postal code) during the same time period. | No | | cohortType (string) | Describes the type of cohort being compared to for this period, e.g., POSTAL_CODE. | | | totalDifferenceToCohort (number) | The difference between the customer's spending for the period minus the average spending in this cohort. | | | percentageDifferenceToCohort (number) | The percentage difference between the customer's sum value for the period and the average of the cohort. | | | timeIntervalType (string) | See Time Interval Types above for how each period is defined. | | | cohortBenchmarkPeriods (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the spending of cohorts in the customer's zip code during that period for an attribute. | Yes | | startDate (string) | The first day of the cohort benchmark period. | | | endDate (string) | The final day of the cohort benchmark period. | | | cohortValues (object) | An object that contains type and value of a cohort benchmark period. | No | | cohortType (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, e.g., POSTAL_CODE. | | | value (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | | | streamIds | List of stream IDs associated with the attribute. | No | | transactionIds (object) | List of transaction IDs associated with the attribute. | Yes | | projectedValues (object) | List of projection objects, where each object indicates the projected sum value of the attribute over some coming period of time. | | | timeUnit (string) | The unit of time being described, e.g., MONTHS. | | | timeValue (number) | The number of timeUnit units for which we are projecting, e.g., 12 (for 12 months). | | | projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | | | streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | | | streamId (string) | The stream ID we are reporting the confidence for. | | | confidence (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an income attribute. | | ### Streams {#streams} Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between 2 parties (or accounts, if the same entity owns both the source and destination of funds). Examples of streams include: bi-weekly paychecks from an employer to an employee, a customer's monthly phone bill paid to a telecom provider, a customer's monthly transfer from a checking account to an investment account, etc. Since a stream is just a group of transactions, a transactional attribute can assign a list of streams to itself if the transactions in that stream all fit the same classification being described by the attribute. * Json ```json "streams": [ { "cadence": 20, "id": "688992c4-263b-4220-9c57-ed8e42489340", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "28985672772", "28985672796", "28985653969", "28985672790", "28985672769", "28985672774", "28985653982", "28985672779", "28985672806", "28985672801", "28985672802", "28985672765", "28985672815", "28985672799", "28985653976", "28985653979", "28985672782", "28985672805", "28985653983", "28985672783", "28985672766", "28985672817", "28985672785", "28985672818", "28985653986", "28985672794", "28985672784", "28985653978", "28985653987", "28985672780", "28985672816", "28985672795", "28985653971", "28985672793", "28985672777", "28985672797" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "4c7f0a3e-7d7f-4294-b8c0-07ff5563217f", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "28985654346", "28985675175", "28985675171", "28985675206", "28985654342", "28985675203", "28985675190", "28985654354", "28985675191", "28985675189", "28985675222", "28985675224", "28985675172", "28985675211", "28985654359", "28985675208", "28985675221", "28985654351", "28985675198", "28985675188", "28985654355", "28985654358", "28985675223", "28985654350", "28985675184", "28985675200", "28985675179", "28985675183", "28985675187", "28985654341", "28985675207", "28985675202", "28985675212", "28985675201", "28985675181", "28985675196" ] } ] ``` ### JSON fields description {#json-fields-description-1} | Key (Datatype) | Description | |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | cadence (number) | The average number of days elapsed between consecutive transactions in the stream. | | id (string) | A randomly generated UUID to uniquely identify the stream. | | payee (string) | The party that is receiving the funds. | | payor (string) | The party that is sending the funds. | | recency (number) | The number of days elapsed since the most recent transaction in the stream. | | earliestObservedDate (string) | The date-time of the first observed transaction in the stream. | | latestObservedDate (string) | The date-time of the last observed transaction in the stream. | | status (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence. | | minimumCadence (number) | The smallest observed duration of time elapsed between any 2 consecutive transactions in the stream. | | maximumCadence (number) | The largest observed duration of time elapsed between any 2 consecutive transactions in the stream. | | medianCadence (number) | The median number of days elapsed between consecutive transactions in the stream. | | modeCadence (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream. | | standardDeviationCadence (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream. | | transactionIds (object) | A list of all the transaction IDs that were assigned to the stream. | ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Client Steps source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/client-steps/index.md This page is intended for clients (application developers) who wish to obtain and share an access token (consent receipt) to allow their customers to consent to allow a third party processor to access some of their details (for example their ACH routing data in order to process a payment). ## Before You Begin {#before-you-begin} You will need to know the following: * The partnerId for the processor you want to work with. This is the partnerId that the processor uses when they interact with Mastercard Open Finance APIs, and you will need to specify it when you generate the access key / consent receipt that you will send them. * You will need a relationship with the supplier and a mechanism for sharing the consent receipt. In many cases this will be via an API which they provide to you. * You will need to know how to initiate the payment operation with the processor once all the permissions are granted and they have confirmed they have been able to access the customer data they need. * You will need to agree who is paying for access to Open Finance APIs such as Get ACH Details. Access to Mastercard Open Finance APIs which incur costs are normally billed to the partner making the API call, but in the partner linked scenario can be billed to you if the processor is making API calls on your behalf. The partner ID of the partner to be billed can be specified when creating the consent receipt. * You will need to know which Open Finance products you wish to obtain consent for, and ensure these are specified when you create the consent receipt. The processor will use this information to know which APIs they are allowed to access. ## Present Data Connect User Experience to Customer {#present-data-connect-user-experience-to-customer} The first step is to present the Data Connect experience to your customer so that they grant consent to share their banking information with the third party for the specified purpose. Use the Generate Data Connect URL endpoint to obtain a URL to the Data Connect experience which you can display to the customer. See the [Data Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) section of the documentation for more details about how to implement the Data Connect experience (SDKs for web and mobile are provided). ## Use Generate Access Key to Create a Consent Receipt {#use-generate-access-key-to-create-a-consent-receipt} Create an access key / consent receipt using the following: API Reference: `POST /aggregation/v1/partners/accessKey` In your request body you will need to specify the customer's ID, your partner ID, the ID for the third party (processor), and a structure indicating the products which you are requesting access for on behalf of the third party. In this case we request `moneyTransferDetails`, as the ACH details for payment are what the third party will need. This part of the request also indicates how long the access is to be granted for, the maximum number of calls, and an indication of which partner pays for API access. You can omit this if you will pay for the API access. ```json { "customerId": "1005061234", "partnerId": "1234583871234", "thirdPartyPartnerId": "1234583871234", "provenance": { "clientFingerprint": "LU9ZYxcDNQCwEmAxH52XFzaRiGMAAAAABclSKxW5S9P8pUMDV4fbpg", "ipAddress": "8.8.8.8", "token": "P9YbR+srNVyQI35893d+BzPrhGMAAAAAuacVUt+3m4svbaFjVSbHEA==" }, "products": [ { "product": "moneyTransferDetails", "payorId": "2445581559892", "maxCalls": 200, "accountId": "5011648377", "accessPeriod": { "type": "timeframe", "startTime": "2022-03-10T06:06:20.042584549Z", "endTime": "2022-03-10T06:06:20.042584549Z" } } ] } ``` The response returns the consent receipt object which confirms the access granted and contains a digital signature. ```json { "data": [ { "receipt": { "profile": 3, "version": "1", "receiptId": "cr_4pfI2r1X8aOHrDDwrwC01NHTxOXlT1", "customerId": "3465230025077724000", "partnerId": "1234583871234", "products": [ { "product": "moneyTransferDetails", "payorId": "2445581559892", "maxCalls": 200, "accountId": "5011648377", "accessPeriod": { "type": "timeframe", "startTime": "2022-03-10T06:06:20.042584549Z", "endTime": "2022-03-10T06:06:20.042584549Z" } } ], "provenance": { "clientFingerprint": "LU9ZYxcDNQCwEmAxH52XFzaRiGMAAAAABclSKxW5S9P8pUMDV4fbpg", "ipAddress": "8.8.8.8", "token": "P9YbR+srNVyQI35893d+BzPrhGMAAAAAuacVUt+3m4svbaFjVSbHEA==" }, "timestamp": "2022-03-10T06:06:20.042584549Z" }, "proof": { "signature": "JTdCyTIyY3VzdG9tZXJJZCUyMiUzQSUyMjU0NTQ1MTQwMDI5NTU2MjkzNDMlMjIlMkMlMjJwYXJ0bmVySWQlMjIlM0ElMjIyNDQ1NTgzOTIyNTM2JTIyJTJDJTIycHJvZHVjdHMlMjIlM0ElNUIlN0IlMjJhY2Nlc3NQZXJpb2QlMjIlM0ElN0IlMjJlbmRUaW1lJTIyJTNBJTIyMjAyMy0xMS0yOVQwNiUzQTA2JTNBMjBaJTIyJTJDJTIyc3RhcnRUaW1lJTIyJTNBJTIyMjAyMi0xMS0yOVQwNiUzQTA2JTNBMjBaJTIyJTJDJTIydHlwZSUyMiUzQSUyMnRpbWVmcmFtZSUyMiU3RCUyQyUyMmFjY291bnRJZCUyMiUzQSUyMjQ2MzM0MTU3NDM5NjAzNzQwMjQlMjIlMkMlMjJwcm9kdWN0JTIyJTNBJTIybW9uZXlUcmFuc2ZlckRldGFpbHMlMjIlN0QlMkMlN0IlMjJhY2Nlc3NQZXJpb2QlMjIlM0ElN0IlMjJlbmRUaW1lJTIyJTNBJTIyMjAyMy0xMC0yOVQwNiUzQTA2JTNBMjBaJTIyJTJDJTIyc3RhcnRUaW1lJTIyJTNBJTIyMjAyMi0xMS0yOVQwNiUzQTA2JTNBMjBaJTIyJTJDJTIydHlwZSUyMiUzQSUyMnRpbWVmcmFtZSUyMiU3RCUyQyUyMmFjY291bnRJZCUyMiUzQSUyMjQ2MzM0MTU3NDM5NjAzNzQwMjQlMjIlMkMlMjJwcm9kdWN0JTIyJTNBJTIybW9uZXlUcmFuc2ZlckRldGFpbHMlMjIlN0QlNUQlMkMlMjJwcm9maWxlJTIyJTNBMyUyQyUyMnByb3ZlbmFuY2UlMjIlM0FudWxsJTJDJTIycmVjZWlwdElkJTIyJTNBJTIyY3JfNHBmSTNyMVg4YU9IckREd3J3QzAxTkhDeE9YbFcxJTIyJTJDJTIycmVjZWlwdFZlcnNpb24lMjIlM0ExJTJDJTIydGltZXN0YW1wJTIyJTNBJTIyMjAyMi0xMS0yOVQxOCUzQTM1JTNBMDhaJTIyJTJDJTIydmVyc2lvbiUyMiUzQSUyMjElRjYlN9U=", "keyId": "867-530-900", "timestamp": "2022-03-10T06:06:20.042584549Z" } } ] } ``` ## Share the Consent Receipt / Access Token With the Processor {#share-the-consent-receipt--access-token-with-the-processor} Once you've created a suitable consent receipt, you will need to share this consent receipt with your chosen payment processor. The method used for this will depend on the processor - in some cases they will have an API for this purpose. Once you have shared the consent receipt and received confirmation, you might need to make additional API calls to the processor to initiate certain actions (for example to initiate a payment), which the processor will then be able to complete by making the necessary API calls to Mastercard Open Finance (for example to obtain ACH routing data for your customer's bank account). For more information see the following: | Processor | API | Documentation | |-----------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Dwolla | Secure Exchange / Create Funding source | Create a secure exchange token using the consent receipt then create a funding source using the exchange token. | | Usio | ACH Payments | If you pass the consent receipt via the RemoteToken field then the RoutingNumber and AccountNumber fields are not required - Usio will instead use the consent receipt to obtain the ACH routing details from Mastercard on your behalf. | ## Managing Access Keys {#managing-access-keys} See [Manage Access Keys](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/manage-access-keys/index.md) for details of how you can update an existing access key, or delete an access key once it is no longer required. --- # Deposit Switch source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md Deposit Switch is a seamless, automated solution that allows users to effortlessly switch their direct deposits from one bank account to another. Designed with ease of use and efficiency in mind, this service simplifies the process of managing direct deposits, reducing administrative burdens, enhancing user satisfaction, and driving account primacy. With Deposit Switch, you can: 1. Trigger recurring account funding by inviting your customers to instantly update their direct deposit information. 2. Provide a seamless, easy to use switching journey embedded in the account onboarding process. 3. Let your customers allocate their full or partial paycheck to an account at your bank. Warning: This product may not be used for purposes subject to the Fair Credit Reporting Act. ## Use Cases {#use-cases} * **Fund new accounts** such as retail bank accounts and digital wallets by enabling direct payroll deposit. Deposit switch enables direct deposit for any type of accounts: checking, savings, retirement, etc. This can be used either during an account opening flow, or after onboarding is complete. * **Fund existing accounts** by switching payroll deposits from incumbent banks to our customer/FI. This could be to a new account not yet linked to Open Finance . ## How It Works {#how-it-works} Customers will use your app to launch a Connect Transfer session to establish a connection enabling the direct deposit switch with their payroll provider. The Connect Transfer experience differs from the regular Data Connect experience since it allows end users to login and authenticate with payroll providers (note we use Atomic, a partner of Mastercard, for parts of the user experience). Diagram deposit-switch You must have already created a [customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) record using your partnerId to use this service. Note that the endpoints require [authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). Tip: For testing in Sandbox with [Test Customers](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#test-customers), note that the final screen in the Connect Transfer flow will prompt the user to "Return to Partner App" during Sandbox testing. When you move to Production, the screen will instead use the application name associated with your experience ID, if provided. ### Integration Options {#integration-options} You can either generate a Deposit Switch Connect Transfer URL and embed the experience in an iframe (or secure web container) using the [Data Connect Web SDK](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#using-deposit-switch-with-the-connect-web-sdk), or for mobile you can generate the URL and pass it to the [Connect Transfer mobile SDKs](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) that we provide. The Connect Transfer mobile SDKs provide iOS, Android and React Native versions of the Atomic user experience, which is not supported by the regular Data Connect mobile SDKs. The Connect Transfer SDKs also support TrueAuth authentication of the end user with the payroll provider, rather than OAuth. ## Generate a Connect Transfer URL {#generate-a-connect-transfer-url} In order to allow customers to be able to set up deposit switches, you will need to offer them a specific Data Connect user experience which allows them to set up the switch. This user experience will allow them to, for example, search for their payroll provider or employer, login to the provider with their credentials and select a direct deposit allocation. This is different from the usual Data Connect experience which just allows customers to connect bank accounts. API Reference: `POST /connect/generate/transfer/deposit-switch` Note that the Connect Transfer experience uses Atomic, a partner of Mastercard, for parts of the user experience. See the [Experience Design Guide section on Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md) for more details of the user flow. Note: This endpoint now supports passing an `external` object for in-branch deposit switching. See [Deposit Switch In-Branch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#deposit-switch-in-branch) on this page. ## Get Deposit Switches by Customer ID {#get-deposit-switches-by-customer-id} Retrieve a list of the Deposit Switches that are defined for a given customer ID. For each deposit switch the ID, status, date of creation, and if applicable any status is returned. API Reference: `GET /transfer/customers/{customer_id}/deposit-switches` ## Get Deposit Switches by External ID {#get-deposit-switches-by-external-id} Retrieve a list of the Deposit Switches that are defined for a given external ID, which is your identifier for the employee or branch associated with an In-Branch switch. See [Deposit Switch In-Branch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#deposit-switch-in-branch) on this page. For each deposit switch the ID, status, date of creation, and if applicable any status is returned. API Reference: `GET /transfer/externals/{external_id}/deposit-switches` ## Get Deposit Switch Details {#get-deposit-switch-details} Retrieve the details of a specific deposit switch, once you know the ID of the switch. A successful response will include details of the status of the switch and also details of the provider, the bank / FI, and last four digits of the customer's account number for the account which will be credited. API Reference: `GET /transfer/customers/{customer_id}/deposit-switches/{switch_id}` ## Connect Transfer Webhooks {#connect-transfer-webhooks} The following [Data Connect webhook events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md) can be generated during the Connect Transfer flow: * `ping` - Sent when Connect Transfer begins (to check that your webhook receiver is responding). Your receiver must return a 200 series or the Generate Connect Transfer URL call fails. * `started` - Sent when the Connect Transfer application is loaded and the landing web page is displayed. * `depositSwitchUpdate` - Sent when the payroll flow is used to add or update a deposit switch. This event applies only to Deposit Switch (details below). * `done` - Sent when the deposit switch user flow ends and control is returned to the partner application. ### depositSwitchUpdate {#depositswitchupdate} | Name | 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., "processing", "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" } ] } } ``` The `depositSwitchUpdate` JSON message contains details within the `payload` field which relate to the specific Deposit Switch that the end user is setting up. In addition to the switch ID and the status (was the switch set up successfully or not), you can also see who the provider is, whether the user authenticated, and the `distributions` field contains details of the switch such as whether the switch is for the total amount, a percentage, or a fixed amount (which will be specified). See the [Get Deposit Switch Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#get-deposit-switch-details) endpoint for descriptions of the data returned. You can use this endpoint to obtain the details of any switch at a later stage. ## How to Test Deposit Switch {#how-to-test-deposit-switch} To test the Deposit Switch functionality, follow these steps: 1. Set up a suitable webhook listener so you can receive webhook events. 2. Make sure you already have a suitable partner ID and test customer which has at least one bank account connected (see the Quick Start Guide). 3. Generate a suitable URL for testing the user flow by calling Connect Transfer URL. You will need to provide details of your webhook listener and your partner ID, the customer ID and details of the bank account which the end user will be transferring a direct deposit to. 4. Load the Connect Transfer URL in a browser and agree to the Terms and Conditions and Privacy Policy by clicking *Next*. 5. This will then show the Atomic user experience where you can select an employer or payroll provider. ### Testing Details {#testing-details} When testing the Deposit Switch flow, you can use the following usernames to test various scenarios. Enter the username shown for any employer or payroll provider (you can use any password). If an email address is required for authentication, append `@example.com` to the username. #### Successful Operation {#successful-operation} Test where the user's credentials are correct and the task completes. When answering MFA questions, any answer will be accepted. | Username | Phone Number | Description | |-------------------|----------------|--------------------------------------------------------------------| | test-good | (555) 555-0100 | Test a successful operation. | | test-code-mfa | (555) 555-0101 | Test an authentication that includes a device code based MFA flow. | | test-push-mfa | (555) 555-0102 | Test an authentication that simulates push-based MFA. | | test-question-mfa | (555) 555-0103 | Test an authentication that simulates question-based MFA. | #### Error Establishing Connection {#error-establishing-connection} Test where the user encounters an issue connecting to the third-party system. | Username | Phone Number | Description | |-------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------| | test-system-unavailable | (555) 555-0104 | Test the user experience during a third-party system outage. | | test-unknown-failure | (555) 555-0105 | Test the user experience when there is an unexpected error. | | test-session-timeout | (555) 555-0106 | Test the user experience when the auth session has timed out. | | test-connection-error | (555) 555-0107 | Test the user experience when there is a connection error caused by a network failure. | | test-high-latency | (555) 555-0108 | Test the flow which occurs when there is high latency communicating with backend systems. | | test-post-auth-delay | (555) 555-0109 | Test the flow when there is a post-auth delay happening. This may occur due to an unanticipated change in the third-party system. | | test-failure | (555) 555-0110 | Test a failure that occurs after a successful authentication. | #### Payroll System Configuration {#payroll-system-configuration} Test where the user encounters an issue with their payroll system configuration or access. | Username | Phone Number | Description | |-----------------------------------|----------------|--------------------------------------------------------------------------------------------| | test-distribution-not-supported | (555) 555-0111 | Test a user who enters an unsupported deposit amount. | | test-routing-number-not-supported | (555) 555-0112 | Test a user whose payroll system rejects the routing number of the target deposit account. | | test-product-not-supported | (555) 555-0113 | Test a user whose payroll system does not allow the operation. | #### User Issue {#user-issue} Test where there is an error that occurs due to an action of the user. | Username | Phone Number | Description | |-------------------------------|----------------|-------------------------------------------------------------------------------| | test-bad | (555) 555-0114 | Test an unsuccessful authentication. | | test-lockout | (555) 555-0115 | Test a user who has been locked out of their account. | | test-account-unusable | (555) 555-0116 | Test a user whose payroll account rejects the target deposit account. | | test-enrolled-in-paycard | (555) 555-0117 | Test a user enrolled in a paycard, which prevents payment via direct deposit. | | test-expired | (555) 555-0118 | Test a user whose payroll password has expired. | | test-transaction-pending | (555) 555-0119 | Test a user who already has a direct deposit change in progress. | | test-account-setup-incomplete | (555) 555-0120 | Test a user who has not fully onboarded to their employee payroll system. | | test-work-status-terminated | (555) 555-0121 | Test a user who is not an active employee in the payroll system. | ## Using Deposit Switch With the Data Connect Web SDK {#using-deposit-switch-with-the-data-connect-web-sdk} You can use Connect Transfer for Deposit Switch with the [Data Connect Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md). This usage is very similar to using the Web SDK with for Data Connect Full, except there are some additional [Connect Transfer specific user events](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#data-connect-transfer-user-events). The Web SDK provides the following events which you must provide handlers for: | Event | Description | |------------|-------------------------------------------------------------------------| | `onDone` | Sent when the user successfully completes the Data Connect application. | | `OnCancel` | Sent when the user cancels the Data Connect application. | | `onError` | Sent when there is an error during the Data Connect application. | Optionally, you can also provide handlers for the following events: | Event | Description | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------| | `onLoad` | Sent when the Data Connect web page is loaded and ready to display. | | `onRoute` | Sent when the user navigates to a new route or screen in Data Connect. | | `onUser` | Sent when a user performs an action. User events provide visibility into what action a user could take within the Data Connect application. | For more details on handling Web SDK events in general, see [Data Connect Web SDK Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-websdk-events/index.md) in the main Data Connect documentation (note that the optional `onUrl` event described there is not relevant for Deposit Switch). The user events which are relevant to Connect Transfer and Deposit Switch are described below. ### Connect Transfer User Events {#connect-transfer-user-events} The following user event messages can be received by your implementation of the `onUser()` listener / callback. * InitializeTransfer * TermsAccepted * InitializeDepositSwitch * SearchPayrollProvider * SelectPayrollProvider * ExternalLink * SubmitCredentials * ChangeDefaultAllocation * SubmitAllocation * TaskCompleted * Unauthorized * End #### InitializeTransfer {#initializetransfer} This event message is sent to `onUser()` when the connect opens within WebSDK. For example: { action = InitializeTransfer; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } #### TermsAccepted {#termsaccepted} This event message is sent to `onUser()` when the user accepts the terms of use on the Data Connect Landing Screen within WebSDK. For example: { action = TermsAccepted; } #### InitializeDepositSwitch {#initializedepositswitch} This event message is sent to `onUser()` when the user initiates a Transfer Session. For example: { action = InitializeDepositSwitch; product = 'deposit' } #### Search Payroll Provider {#search-payroll-provider} This event message is sent to `onUser()` when the user searches by company. For example: { action = SearchPayrollProvider; searchTerm = "home depot"; } #### Select Payroll Provider {#select-payroll-provider} This event message is sent to `onUser()` when the user selects a provider from the Search by Company page. For example: { action = SelectPayrollProvider; payrollProvider = Workday; } #### External Login Recovery {#external-login-recovery} This event message is sent to `onUser()` when user clicks the external login recovery link from the login help page. For example: { action = ExternalLink; buttonName = "Login Help "; } #### Submit Credentials {#submit-credentials} This event message is sent to `onUser()` when user clicks the button to start authentication. For example: { action = SubmitCredentials; inputType = username; } #### Change Default Allocation {#change-default-allocation} This event message is sent to onUser() when user clicks Continue from the Percentage Deposit Amount page. For example: { action = ChangeDefaultAllocation; depositAllocation = 222; depositOption = fixed; } #### SubmitAllocation {#submitallocation} This event message is sent to `onUser()` when user clicks Continue from the Fixed Deposit Amount page. For example: { action = SubmitAllocation; depositAllocation = 222; depositOption = fixed; } #### TaskCompleted {#taskcompleted} This event message is sent to `onUser()` when user views the task completed page. For example: { action = TaskCompleted; status = completed; } #### Unauthorized {#unauthorized} This event message is sent to `onUser()` when the user's Atomic session is unauthorized because of an expired or invalid Atomic Token. For example: { action = Unauthorized; expired = false; } #### End {#end} This event message is sent to `onUser()` when the Connect Transfer flow ends, and contains details about the Connect Transfer flow which will not be provided by the `onDone()` event. { action = End; code = 200; company = { "_id" = COMPANY_ID; branding = { color = "#F96302"; logo = { url = "https://cdn-public.atomicfi.com/b2ad42c5-1348-4bfd-a19d-250583791e8c.png"; }; }; name = "The Home Depot"; }; customerId = CUSTOMER_ID; distributionAmount = 222; distributionType = fixed; identifier = CUSTOMER_ID; partnerId = PARTNER_ID; reason = complete; sessionId = SESSION_ID; taskId = 6789ef56fe459a9cc2fafc43; taskWorkflowId = 6789ef56fe459a9cc2fafc4a; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ## Deposit Switch In-Branch {#deposit-switch-in-branch} Note: This feature is currently in beta. Contact your sales representative or account manager to learn more. Deposit Switch In-Branch enables you to deliver a Direct Deposit Switch URL to customers, with tracking of the branch or employee associated with the switch, and the link delivery method. To support In-Branch, [Generate a Connect Transfer URL for Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateTransferDepositSwitchUrl) has a new `external` parameter object with the following fields: * `id` -- your identifier for the branch or employee initiating the switch (type: string). * `context` -- describes how you are using the Mastercard Data Connect link. This can be one of four values: `EMAIL`, `SMS`, `WEB`, or `MOBILE` (type: string). Both fields must be provided if your request includes `external`. API Reference: `POST /connect/generate/transfer/deposit-switch` * Use a separate experience ID for each channel (web, mobile and in-branch). * Use a separate partner ID only if you need billing to be separated by channel.
You can search for completed deposit switches by external ID with the following endpoint: API Reference: `GET /transfer/externals/{external_id}/deposit-switches` This endpoint supports retrieving switch records and statuses within a 31-day window. There are three options for integrating In-Branch: * [Integration with Mobile Links](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#in-branch-integration-with-mobile-links) (recommended) * [Integration with a Link to Your Site](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#in-branch-integration-with-a-link-to-your-site) * [Integration with a Data Connect Link](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#in-branch-integration-with-a-data-connect-link)
### In-Branch Integration With Mobile Links {#in-branch-integration-with-mobile-links} We recommend using In-Branch URLs by linking into your mobile app instead of modifying API flows, using a [universal link (iOS)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#app-to-app-support) or an [app link (Android)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-to-app-support). This provides the best user experience and success rate due to the ability to use TrueAuth on-device authentication, and provides a compelling reason for new customers to download your app. * **Increased Conversion Rates**: Financial institutions using this strategy observe a significant increase in completed user journeys by encouraging users to download and engage with the mobile app, rather than directing them straight to a deposit setup experience outside of the mobile app. * **Higher Success Rates and Mobile App Downloads**: Deep linking users into the app drives the highest success rates with availability of on-device authentication (TrueAuth) that you can successfully leverage via the Mastercard Direct Deposit functionality on mobile SDKs as a key value-add and a compelling reason for new customers to download the app. * **Account Opening Engagement**: Success is largely driven by strong account opening incentives, competition, and educational efforts within branches. This on-the-ground engagement proves critical to driving deposit switch completion rates in the mobile app. * **Customer Behaviors**: Data shows that most new account holders are not ready to commit to complete a direct deposit switch immediately at the branch. On average, direct deposit setup happens about two weeks after account opening. This delay is often due to customers needing time to unwind existing financial obligations (for example, recurring payments, previous direct deposits) from their old accounts before switching. * **No Additional Training**: Branch staff do not require additional upskilling or training to support the use of deposit switching tools via the In-Branch channel. The platform is designed to be intuitive and seamlessly integrated into existing workflows, ensuring minimal disruption and faster adoption. ### In-Branch Integration With a Link to Your Site {#in-branch-integration-with-a-link-to-your-site} In this scenario, when a user clicks on the link in an email/SMS, they are redirected to a page on a website you control. This page loads the Connect Transfer URL using the Data Connect Web SDK. #### Event Notifications {#event-notifications} * If you have integrated with the Web SDK, your app can listen to user events as described in the Data Connect documentation: * [Web SDK Callback Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#callback-events) * [Connect User Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md) Diagram standard-auth-web-only-sdk ### In-Branch Integration With a Data Connect Link {#in-branch-integration-with-a-data-connect-link} In this scenario, you need to pass the following additional parameters while generating the Connect Transfer URL: * `redirectUri`-- address on a site you control where Data Connect redirects once the user flow is completed. * `webhook` -- endpoint where you want to receive notifications from Data Connect Server. When the user clicks on the link in the email/SMS, they are redirected to a domain/page owned by Finicity, a Mastercard company (for example, `connect2.finicity.com/`). On completion of the flow, the user is redirected to your domain as specified by the `redirectUri` value. #### Event Notifications {#event-notifications-1} * The `redirectUri` includes `code` and `reason` in query params which you can read to indicate if the flow was completed successfully. * The Mastercard Data Connect Server sends [Connect Transfer Webhook Events](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#connect-transfer-webhooks). Diagram standard-auth-web-non-sdk --- # Processor Steps source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/processor/processor-steps/index.md This page is intended for processors who want to know how to access Open Finance APIs (for example, to access ACH routing data) for customers who have consented to share their data for this purpose. ## Before You Start {#before-you-start} To ensure you understand the process, we recommend reading The Consent Receipt page first. You will be sent this consent receipt data by the recipient (a client application which uses Mastercard Open Finance services) so that the application can grant permission for you as as receiver to access Open Finance products on their behalf - for example, so that you can obtain ACH routing data in order to process a payment. We recommend you implement a secure API in order that the requestor can send you the consent receipt after you have established a business relationship and agreed the access required. You will also need to be onboarded to the Mastercard Open Finance system in the normal way so you can make the API calls necessary. ## Processor Access Consented Data {#processor-access-consented-data} The consent receipt information the client shared with you makes it possible for you to start making your own calls using our APIs to retrieve authorized data from our platform. Note: You will only have access to those API products which the consent receipt grants permission for. The consent receipt `products` array will contain details of which products you have been granted access to. The `product` value of each array element | `product` value | Product name | Description | |----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | `accountOwner` | [Account Owner Verification](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) | The names and addresses of an account owner from a financial institution. | | `availableBalance` or `availableBalanceLive` | [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) | The latest available and cleared account balances for an account. | | `moneyTransferDetails` | [Get Account ACH Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md) | The real account number and routing number details for an ACH payment. | | `paymentIndicator` | [PSI Tools](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md) | Get the Payment Success Indicator response, scoring the likelihood of payment settlement | The following steps are the example of how to access the client's account owner and available balance information for their customer's accounts. ## Authenticate Your Partner ID to Create an Access Token {#authenticate-your-partner-id-to-create-an-access-token} You have completed the Partner Linked Integration steps working with a client and have agreed to the following: 1. The client wants you to process payments for their customer's accounts. 2. You need information from the Get Account Owner and Get Available Balance APIs on our platform in order to process the payments. 3. Both parties are clear about who is billed for API access. ## Use Get Account Owner {#use-get-account-owner} From the consent receipt information that the client shared with you, use the reciptId as the Fincity-Access-Key parameter in the header of all requests you make to our API platform. These values are used to authenticate and authorize access to the data you're requesting on our platform. From the consent receipt, use the pseudo customerId and the pseudo accountId in the Get Account Owner URL endpoint. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/owner` The Account Owner V1 response returns the real ownerName and the ownerAddress information associated with the pseudo customerId and pseudo accountId passed in the URL endpoint. ```json { "ownerName": "John Smith", "ownerAddress": "APT C 5600 S SPRINGFIELD GARDENS CIR SPRINGFIELD, VA 22162-1058" } ``` ## Use Get Account Balance {#use-get-account-balance} Use the same header values shown for the Get Account Owner request. Pass the pseudo identifiers for the customerId and accountId in the URL endpoint. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/availableBalance/live` curl -X GET \ --url 'https://api.finicity.com/aggregation/v1/customers/{pseudo customerId}/accounts/{pseudo accountId}/availableBalance/live \ -H 'Finicity-App-Token: Finicity-App-Token'\ -H 'Finicity-App-Key: Finicity-App-Key'\ -H 'Finicity-Access-Key: cr_192038u123ohjsdfkh18324234sdf11231\ -H 'Accept: application/json' The Get Available Balance Response returns customer and account information: ```json { "id": 5047759451, "realAccountNumberLast4": "2222", "availableBalance": 228.33, "availableBalanceDate": 1646076805, "cleared Balance": 228.33, "clearedBalanceDate": 1646076805, "aggregationStatusCode": 0, "currency": "USD" } ``` ## Use Get Account ACH (Money Transfer) Details {#use-get-account-ach-money-transfer-details} Use the same header values as shown for the Get Account Owner request. Pass the pseudo identifiers for the customerId and accountId in the URL endpoint. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/details` curl -X GET \ --url 'https://api.finicity.com/aggregation/v1/customers/{pseudo customerId}/accounts/{pseudo accountId}/availableBalance \ -H 'Finicity-App-Token: Finicity-App-Token'\ -H 'Finicity-App-Key: Finicity-App-Key'\ -H 'Finicity-Access-Key: cr_192038u123ohjsdfkh18324234sdf11231\ -H 'Accept: application/json' The Get Account ACH Response returns the customer's routing number and account number: ```json { "routingNumber": "123456789", "realAccountNumber": "002345678901" } ``` The processor is responsible for sharing their data sets with the client as needed per their agreement. Normally this would be via an API which the client calls in order to initiate the activity. --- # React Native App Integration source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/react-native/index.md This guide provides step-by-step instructions on how to integrate the Mastercard Data Connect Components into a React Native application. The purpose of this integration is to allow partners to: * Search for financial institutions * Handle authentication (Legacy \& OAuth) * Retrieve user account details post-authentication ## Prerequisites {#prerequisites} Before starting, ensure that you have the following installed: * React Native environment (React Native CLI or Expo) * Node.js and npm * Axios (for API requests): `npm install axios` * React Native WebView: `npm install react-native-webview` * React Native In-App Browser (for OAuth flows): `npm install react-native-inappbrowser-reborn` ## Installing the Data Connect Components Web SDK {#installing-the-data-connect-components-web-sdk} The Data Connect Components SDK provides reusable web components for handling institution login flows. This needs to be installed in your web application: npm install connect-components-web-sdk For more details on the SDK installation and use see [Data Connect Components Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md). ## React Native Screens Overview {#react-native-screens-overview} Your React Native app will have the following key screens: * **Institution Search** - Allows users to search for financial institutions. * **WebView Integration** - Displays your web app which uses the Data Connect Components web SDK. * **Account Retrieval** - Fetches and displays user accounts after authentication. Each of these is explained in more detail below. ## Institution Search Flow {#institution-search-flow} Steps to Implement: 1. Create a search input field where users can type the name of a financial institution. 2. Use the [Get Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md) API to fetch the list of institutions based on the search input. 3. Display the search results and allow the user to select an institution. Code Example: ```javascript import axios from 'axios'; const fetchInstitutions = async (searchText) => { const response = await axios.get( `/institution/v2/institutions?search=${searchText}` ); return response.data; }; ``` ## WebView Integration (Authentication Flow) {#webview-integration-authentication-flow} Using a webview allows you to leverage your web integration of Data Connect Components: * You will need to have completed your integration of [Data Connect Components Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md) into your web application. * Your React Native app then loads this web application via WebView to handle authentication. ```javascript import { WebView } from 'react-native-webview'; ``` Replace `PARTNER_WEB_APP_CC_SDK_URL` with the URL of your hosted web application which uses the Data Connect Components web SDK. The `onMessage` prop listens for events from the WebView, such as authentication success or failure. You will need to implement code to handle the event messages from WebView (see below). ### Sending Events From WebView to React Native {#sending-events-from-webview-to-react-native} If the web application (where the Data Connect Components SDK is integrated) needs to send messages back to React Native, use the following approach: window.ReactNativeWebView?.postMessage(JSON.stringify(event)); The `ReactNativeWebView` object is automatically attached to the window when using `react-native-webview`, allowing seamless communication between WebView and React Native. ### Handling Messages From WebView {#handling-messages-from-webview} ```javascript const handleWebViewMessages = (event) => { const message = JSON.parse(event.nativeEvent.data); switch (message.type) { case 'url': openSecureContainer(message.data); // Opens OAuth flow in secure browser break; case '..': ..., } }; ``` ### Opening Secure Container for OAuth Login {#opening-secure-container-for-oauth-login} OAuth requires opening a secure browser to authenticate the user. We use the [react-native-inappbrowser-reborn](https://www.npmjs.com/package/react-native-inappbrowser-reborn) package for this. ```javascript import InAppBrowser from 'react-native-inappbrowser-reborn'; const openSecureContainer = async (url) => { await InAppBrowser.isAvailable(); const browserOptions = Platform.OS === 'ios' ? undefined : { forceCloseOnRedirection: false, showInRecents: true }; await InAppBrowser.open(url, browserOptions); }; ``` See the [OAuth Usage](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#oauth-usage) section of the web SDK documentation for details of how you can fetch the OAuth URL to open in a secure container. ## Account Retrieval (After Authentication) {#account-retrieval-after-authentication} Steps to Implement: 1. After successful authentication, call [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md). 2. Display the retrieved accounts in the app. 3. Handle potential errors (e.g., session expiration, API failures). For example: ```javascript const fetchAccounts = async (customerID) => { const response = await axios.get( `/aggregation/v1/customers/${customerID}/accounts` ); return response.data; }; ``` --- # Understanding Transaction Data source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/understanding-transaction-data/index.md [Transaction Data](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md) provides detailed information about a specific account transaction. The data that is returned includes a transaction ID which when used on its own is not enough to accurately identify a transaction as this ID may not always be unique. If you are caching transaction data, you will therefore need to ensure you use the transaction ID along with an `accountId` or `customerId` when querying that cached data. This avoids any potential problems caused by the same transaction ID being used with more than one customer. The **Get Customer Transaction by ID** API takes both the `customerId` and transaction ID as a query parameter which returns specific transaction data. ## Transaction Data by Segment {#transaction-data-by-segment} There is one important difference in the way inflows and outflows are represented for different account types, in traditional transaction data such as for a checking account, a positive amount (credit) corresponds to inflow (salary), while a negative amount corresponds to outflow (paying a bill). However, with investment account or credit card transaction data this convention is the opposite, inflows are negative (stock sales / paying down a balance on credit card) and outflows are positive (stock purchases / purchase on a credit card). * Deposit * Line-of-Credit * Investment * Mortgage-Loans * Student-Loans ```Deposit { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": -54.42, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "Costco Gas Stations", "memo": "FIP COSTCO GAS 137 COSTCO GAS 137 EAST LYME CT9325", "type": "debit", "transactionDate": 1607450357, "createdDate": 1607450357, "checkNum": 589478, "feeAmount": 0.00, "interestAmount": 0.00, "categorization": { "normalizedPayeeName": "Costco Gas", "category": "Gas & Fuel", "bestRepresentation": "COSTCO GAS STATIONS FIP COSTCO GAS COSTCO GAS EAST LYME CT", "country": "USA", }, "runningBalanceAmount": 1521.48, "currencySymbol": "USD" } ] } ``` ```Line-Of-Credit { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": -20.04, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "EBAY", "memo": "EBAY O 22-10785-01239 SAN JOSE CA", "type": "debit", "createdDate": 1607450357, "transactionDate": 1607450357, "categorization": { "normalizedPayeeName": "Ebay", "category": "Shopping", "country": "USA", "bestRepresentation": "Ebay San Jose CA" } } ] } ``` ```Investment { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": -828.50, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "Buy Stock", "memo": "Purchase: NETFLIX COM INC CLIENT ENTERED. PRICE 390.000000", "type": "debit", "transactionDate": 1607450357, "postedDate": 1607450357, "createdDate": 1607450357, "optionExpireDate": 1607450357, "feeAmount": 0.00000000, "suspenseAmount": 0.25, "interestAmount": 132, "principalAmount": 32560, "optionStrikePrice": 10.00000000, "unitQuantity": 150.00000000, "unitPrice": 390.0000000, "runningBalanceAmount": 1000, "subaccountSecurityType": "MARGIN", "commissionAmount": 0.00000000, "ticker": "NFLX", "investmentTransactionType": "optionExercise", "taxesAmount": 0.00000000, "currencySymbol": "USD", "incomeType": "DIV", "splitDenominator": 152.00000000, "splitNumerator": 20.00000000, "sharesPerContract": 100, "subAccountFund": "MARGIN", "securityId": "316389303", "securityIdType": "CUSIP" } ] } ``` ```Mortgage-Loans { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": 1573.10, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "Payment Applied to OCT-01-23", "memo": "Payment", "type": "credit", "transactionDate": 1607450357, "postedDate": 1607450357, "createdDate": 1607450357, "escrowAmount": 459.58, "interestAmount": 2.52, "principalAmount": 210.73, "feeAmount": 41.68, "categorization": { "normalizedPayeeName": "Kwikpay", "category": "Loan Payment", "country": "USA", "bestRepresentation": "Kwikpay Loan" }, "runningBalanceAmount": -144.10, "effectiveDate": 1607450357, "firstEffectiveDate": 1607450357 } ] } ``` ```Student-Loans { "found": 1, "displaying": 1, "moreAvailable": false, "fromDate": 1607450357, "toDate": 1607450357, "sort": "desc", "transactions": [ { "id": 21284820852, "amount": 213.25, "accountId": 5011648377, "customerId": 1005061234, "status": "active", "description": "KwikPay", "memo": "Loan Payment", "type": "credit", "transactionDate": 1607450357, "postedDate": 1607450357, "createdDate": 1607450357, "suspenseAmount": 0.00, "interestAmount": 2.52, "principalAmount": 210.73, "feeAmount": 15.25, "categorization": { "normalizedPayeeName": "Kwikpay", "category": "Loan Payment", "country": "USA", "bestRepresentation": "Kwikpay Loan" }, "runningBalanceAmount": -144.10, "effectiveDate": 1607450357, "firstEffectiveDate": 1607450357 } ] } ``` ## Transaction Status {#transaction-status} The transaction status indicates the availability of the transaction from the financial institution. The status may be active, pending, or shadow. An individual transaction's status may fluctuate between these statuses, depending on the current reporting by the financial institution. * **Active Transactions** An active transaction is a transaction that is currently found on an institution's transaction record during the most recent refresh. * **Pending Transactions** A pending transaction is a transaction that has been initiated but has not been cleared or posted by the institution. Pending transactions are short-lived. Each refresh will capture all available pending transactions at the time; if any of those transactions are not found in a subsequent refresh, they will be removed from the transaction response. There is no continuity guarantee for transactions to move from pending to active. When an institution changes a transaction from pending to posted, the pending transaction may be updated to active, or may be marked as shadow and a new transaction record with an active status may appear. This behavior is determined by the financial institution's reporting. Pending transactions can only change to active or be removed from the response, they cannot change to shadow. * **Shadow Transactions** Mastercard added the ability to identify transactions found in an account in an earlier aggregation, but not in the institution's current data records. These "shadow" transactions have their status field set to `status: "shadow"`. A transaction record with a shadow status means the financial institution previously reported the transaction as `active`, but the transaction record was later removed from their reporting in a subsequent aggregation. It's also possible the financial institution does not provide unique IDs to identify the transaction, and has changed the transaction data from a previous reporting. These modifications or deletions can cause transactions to be duplicated in the Mastercard Open Finance data, or persist after being removed from the institution's data source. When Mastercard identifies such transactions they are designated with the "shadow" status. You can handle shadow transactions in one of the following ways: 1. Remove / do not display shadow transactions to the customer. 2. Display shadow transactions but provide the customer with a way to confirm whether the shadow transaction should be be removed or kept.
In most cases we recommend that you treat shadow transactions as though they have been deleted from the data source. ## Transaction Categorization {#transaction-categorization} Endpoints which return transaction data contain a `categorization` object which provides enriched data describing the transaction. ```json "categorization": { "normalizedPayeeName": "McDonald's", "category": "Fast Food", "city": "Clinton", "state": "SC", "postalCode": "", "country": "USA", "bestRepresentation": "checkcard mcdonalds clinton sc debit" } ``` When presenting transaction details in your user interface, prioritize the `normalizedPayeeName` field, which typically provides a clean and standardized merchant name that enhances readability and user comprehension. In some cases, `normalizedPayeeName` is unavailable or returns a placeholder value such as "No Entity Found". This can occur for internal transfers or ambiguous transactions. In these cases, you should display the `bestRepresentation` value which contains a description like "ATM Surcharge Rebate" to help your users understand the transaction. --- # Cash Flow Analytics (Consumer) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/cash-flow-analytics/index.md Note: This documentation is for consumer use cases. For Small Business use cases, see [Cash Flow Analytics (Small Business)](https://developer.mastercard.com/open-finance-us/documentation/products/small-business/cash-flow-analytics-sb/index.md). Cash Flow Analytics (CFA) analyzes up to 24 months of credits and debits in connected accounts to surface cash-flow health and trends - such as inflows, outflows, net cash flow, seasonality, and NSF events - to assess capacity to pay and volatility. For consumer use cases (CRA or non-CRA), CFA returns model-ready attributes over the desired time intervals. Learn more about Mastercard's [Cash Flow](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#cash-flow) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months * **Cash Flow Analytics:** Includes debit and credit breakouts, and net cash flow attributes * **Non-Sufficient Funds (NSF) Summary**: The presence of NSFs can be a key indicator of financial distress * **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge * **Supported Account Types**: Checking, Savings, Money Market, CD, Investment account types, Mortgage, Loan, Credit Card, Line of Credit, Payroll, Student Loan, Education Savings, Health Savings Account * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The Cash Flow Analytics product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer/Portfolio Monitoring * Debt Collection * Personal Financial Management * Personal Lending * Servicing * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API. * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers). * [Create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record for consumer FCRA use cases. * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows). ## Generate a Cash Flow Analytics Report {#generate-a-cash-flow-analytics-report} To generate or refresh a Cash Flow Analytics report, use the following endpoint, replacing `{userType}` in the path with `personal`: API Reference: `POST /decisioning/v2/customers/{customerId}/reports/cashflow-analytics/userTypes/{userType}` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * Use the `timeIntervalType` to select the periodicity at which attributes will be calculated. Defaults to Monthly Calendar. Customize the type of Cash Flow Analytics report received based on inputs provided when generating the report: | Report Type | User Type | forCraPurpose | Consumer Required? | Customer Required? | |-------------|-----------|---------------|--------------------|--------------------| | cfrpcra | personal | true | Y | Y | | cfrpnoncra | personal | false | N | Y | ## Get Cash Flow Analytics Reports {#get-cash-flow-analytics-reports} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "n1siaxtrn1ni-cfrpcra", "customerType": "testing", "customerId": 1011077785, "requestId": "m8ks9vjq2u", "requesterName": "Open Banking API Tests", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "title": "Mastercard Open Banking Cash Flow Analytics", "consumerId": "8d510370aae83d459da0b905ee59e714", "consumerSsn": "1147", "disputeStatement": "Invalid data present.", "type": "cfrpcra", "status": "success", "constraints": { "analyticsReportData": { "forCraPurpose": true, "timeIntervalTypes": [ "MONTHLY_CALENDAR" ] } }, "createdDate": 1721813301, "startDate": 1658654901, "endDate": 1721813301, "days": 730, "institutions": [ { "id": 102105, "name": "FinBank Profiles - A", "urlHomeApp": "http://www.bank.example.com", "accounts": [ { "id": 3027530342, "ownerName": "JNC PROPERTIES LLC", "ownerAddress": "1944 JAKETOWN RD DONNELLSON IL 62019", "ownerAsOfDate": 1721818584, "name": "Business Investment", "number": "1101", "type": "investment", "aggregationStatusCode": 0, "currentBalance": 100000, "balanceDate": 1721813305, "transactions": [], "analytics": null, "currency": "USD" }, { "id": 3027530343, "ownerName": "NSF USER", "ownerAddress": "123 VINE ST MURRAY, UT 84123", "ownerAsOfDate": 1721813301, "name": "NSF Checking", "number": "0111", "type": "checking", "aggregationStatusCode": 0, "currentBalance": 37700.65, "availableBalance": 38000.45, "balanceDate": 1721813306, "transactions": [ { "id": 101402234899, "amount": -34, "postedDate": 1708776000, "description": "INSUFFICIENT FUNDS FEE FOR A $12", "memo": ".07 ITEM - DETAILS: ALLSTATE INS", "normalizedPayee": "Allstate", "institutionTransactionId": "0000000000", "category": "Low Balance" }, { "id": 101402234924, "amount": -34, "postedDate": 1706961600, "description": "INSUFFICIENT FUNDS FEE FOR A $21", "memo": ".50 ITEM - DETAILS: HK Paymt", "normalizedPayee": "Insufficient", "institutionTransactionId": "0000000000", "category": "Low Balance" }, { "id": 101402234869, "amount": -34, "postedDate": 1679140800, "description": "INSUFFICIENT FUNDS FEE FOR A $64", "memo": ".64 ITEM - DETAILS: UI WEB PAYME", "normalizedPayee": "Insufficient", "institutionTransactionId": "0000000000", "category": "Low Balance" }, { "id": 101402234923, "amount": 34, "postedDate": 1659009600, "description": "INSUFFICIENT FUNDS FEE REFUND", "normalizedPayee": "Insufficient", "institutionTransactionId": "0000000000", "category": "Low Balance" } ], "analytics": { "transactionalAttributes": [ { "attributeName": "CASH_OUTFLOW", "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2022-07-31", "startDate": "2022-07-28" }, { "count": 5, "endDate": "2022-08-31", "max": -24, "mean": -42.6, "median": -34, "min": -90, "standardDeviation": 26.847718711279736, "startDate": "2022-08-01", "sum": -213 }, { "count": 4, "endDate": "2024-06-30", "max": -26.23, "mean": -31.0575, "median": -32, "min": -34, "standardDeviation": 3.7300435654292294, "startDate": "2024-06-01", "sum": -124.23 }, { "count": 3, "endDate": "2024-07-24", "max": -28, "mean": -30.666666666666668, "median": -30, "min": -34, "standardDeviation": 3.0550504633038935, "startDate": "2024-07-01", "sum": -92 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "68bdc784-89d6-4704-9ded-d3e0f706f9e1" ], "transactionIds": [ "101402234901", "101402234939", "101402234879" ] }, { "attributeName": "CASH_INFLOW", "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2022-07-31", "max": 34, "mean": 34, "median": 34, "min": 34, "startDate": "2022-07-28", "sum": 34 }, { "count": 0, "endDate": "2022-08-31", "startDate": "2022-08-01" }, { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-01" }, { "count": 0, "endDate": "2024-07-24", "startDate": "2024-07-01" } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "3dfd89be-33cc-484d-acbf-69587a0c44e6" ], "transactionIds": [ "101402234943" ] }, { "attributeName": "ALL_CASH_FLOWS", "aggregatedByTimePeriods": [ { "periods": [ { "count": 1, "endDate": "2022-07-31", "max": 34, "mean": 34, "median": 34, "min": 34, "startDate": "2022-07-28", "sum": 34 }, { "count": 5, "endDate": "2022-08-31", "max": -24, "mean": -42.6, "median": -34, "min": -90, "standardDeviation": 26.847718711279736, "startDate": "2022-08-01", "sum": -213 }, { "count": 4, "endDate": "2024-06-30", "max": -26.23, "mean": -31.0575, "median": -32, "min": -34, "standardDeviation": 3.7300435654292294, "startDate": "2024-06-01", "sum": -124.23 }, { "count": 3, "endDate": "2024-07-24", "max": -28, "mean": -30.666666666666668, "median": -30, "min": -34, "standardDeviation": 3.0550504633038935, "startDate": "2024-07-01", "sum": -92 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "bb12a859-09b7-4021-8ac5-522e01d00159" ], "transactionIds": [ "101402234901", "101402234883", "101402234928", "101402234879" ] }, { "attributeName": "NSF_FEE_CHARGES", "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2022-07-31", "startDate": "2022-07-28" }, { "count": 5, "endDate": "2022-08-31", "max": -24, "mean": -42.6, "median": -34, "min": -90, "standardDeviation": 26.847718711279736, "startDate": "2022-08-01", "sum": -213 }, { "count": 4, "endDate": "2024-06-30", "max": -26.23, "mean": -31.0575, "median": -32, "min": -34, "standardDeviation": 3.7300435654292294, "startDate": "2024-06-01", "sum": -124.23 }, { "count": 3, "endDate": "2024-07-24", "max": -28, "mean": -30.666666666666668, "median": -30, "min": -34, "standardDeviation": 3.0550504633038935, "startDate": "2024-07-01", "sum": -92 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "68bdc784-89d6-4704-9ded-d3e0f706f9e1" ], "transactionIds": [ "101402234891", "101402234914", "101402234900", "101402234876" ] }, { "attributeName": "NSF_FEE_REVERSALS", "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2022-07-31", "startDate": "2022-07-28" }, { "count": 0, "endDate": "2022-08-31", "startDate": "2022-08-01" }, { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-01" }, { "count": 0, "endDate": "2024-07-24", "startDate": "2024-07-01" } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [], "transactionIds": [] } ], "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 34, "count": 4, "endDate": "2022-07-31", "endingValue": 0, "max": 34, "mean": 8.5, "median": 0, "min": 0, "standardDeviation": 17, "startDate": "2022-07-28", "sum": 34 }, { "beginningValue": 0, "count": 31, "endDate": "2022-08-31", "endingValue": 0, "max": 0, "mean": -6.870967741935484, "median": 0, "min": -90, "standardDeviation": 20.144051124312725, "startDate": "2022-08-01", "sum": -213 }, { "beginningValue": 0, "count": 30, "endDate": "2024-06-30", "endingValue": 0, "max": 0, "mean": -4.141, "median": 0, "min": -34, "standardDeviation": 10.804814492016813, "startDate": "2024-06-01", "sum": -124.23 }, { "beginningValue": 0, "count": 24, "endDate": "2024-07-24", "endingValue": 0, "max": 0, "mean": -3.8333333333333335, "median": 0, "min": -34, "standardDeviation": 10.3992753370719, "startDate": "2024-07-01", "sum": -92 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ] } ], "streams": [ { "cadence": 0, "id": "68bdc784-89d6-4704-9ded-d3e0f706f9e1", "payee": "non-sufficient", "payor": "NSF USER", "recency": 696, "transactionIds": [ "101402234865" ] } ] }, "currency": "USD" } ], "oauthEnabled": false } ], "customerAnalytics": { "transactionalAttributes": [ { "attributeName": "CASH_OUTFLOW", "aggregatedByTimePeriods": [ { "periods": [ { "count": 18, "endDate": "2022-07-31", "max": -2.47, "mean": -53.702222222222225, "median": -22.965, "min": -167.86, "standardDeviation": 58.32137067254321, "startDate": "2022-07-24", "sum": -966.64 }, { "count": 37, "endDate": "2022-08-31", "max": -2.5, "mean": -62.64945945945946, "median": -27.39, "min": -1150, "standardDeviation": 185.22983467912306, "startDate": "2022-08-01", "sum": -2318.03 }, { "count": 10, "endDate": "2024-06-30", "max": -26.23, "mean": -509.856, "median": -300, "min": -1358.11, "standardDeviation": 597.0070650838229, "startDate": "2024-06-01", "sum": -5098.5599999999995 }, { "count": 9, "endDate": "2024-07-24", "max": -28, "mean": -562.9255555555555, "median": -300, "min": -1358.11, "standardDeviation": 607.6863589079302, "startDate": "2024-07-01", "sum": -5066.33 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "bb12a859-09b7-4021-8ac5-522e01d00159", "d0bbf017-2c98-4eb1-835c-66dbe0998b02", "e19e1671-19a1-42b3-91f0-277c0a9dba89", "68bdc784-89d6-4704-9ded-d3e0f706f9e1" ], "transactionIds": [ "101402234822", "101402234883", "101402235089", "101402234758" ] }, { "attributeName": "CASH_INFLOW", "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2022-07-31", "max": 224, "mean": 129, "median": 129, "min": 34, "standardDeviation": 134.35028842544403, "startDate": "2022-07-24", "sum": 258 }, { "count": 12, "endDate": "2022-08-31", "max": 522, "mean": 243.70833333333334, "median": 224, "min": 130, "standardDeviation": 104.15274149347228, "startDate": "2022-08-01", "sum": 2924.5 }, { "count": 9, "endDate": "2024-06-30", "max": 1070, "mean": 396.6666666666667, "median": 60, "min": 60, "standardDeviation": 505, "startDate": "2024-06-01", "sum": 3570 }, { "count": 9, "endDate": "2024-07-24", "max": 1070, "mean": 396.6666666666667, "median": 60, "min": 60, "standardDeviation": 505, "startDate": "2024-07-01", "sum": 3570 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "6c3fb158-b6c2-44f7-a528-28ebd60d4eb1" ], "transactionIds": [ "101402235114", "101402234793", "101402235014", "101402235455" ] }, { "attributeName": "ALL_CASH_FLOWS", "aggregatedByTimePeriods": [ { "periods": [ { "count": 20, "endDate": "2022-07-31", "max": 224, "mean": -35.432, "median": -22.63, "min": -167.86, "standardDeviation": 84.59117856210726, "startDate": "2022-07-24", "sum": -708.64 }, { "count": 49, "endDate": "2022-08-31", "max": 522, "mean": 12.376938775510204, "median": -21.82, "min": -1150, "standardDeviation": 214.3270055138106, "startDate": "2022-08-01", "sum": 606.47 }, { "count": 19, "endDate": "2024-06-30", "max": 1070, "mean": -80.45052631578946, "median": -26.23, "min": -1358.11, "standardDeviation": 712.6092459208832, "startDate": "2024-06-01", "sum": -1528.5599999999997 }, { "count": 18, "endDate": "2024-07-24", "max": 1070, "mean": -83.12944444444443, "median": 16, "min": -1358.11, "standardDeviation": 733.1695588612839, "startDate": "2024-07-01", "sum": -1496.3299999999997 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "3136487d-d9a7-4f89-a1f0-6e9415e053e7", "3efccc82-01b9-497b-bf3f-27f215db2d96" ], "transactionIds": [ "101402234891", "101402234747", "101402234831", "101402235000" ] }, { "attributeName": "NSF_FEE_CHARGES", "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2022-07-31", "max": -35, "mean": -35, "median": -35, "min": -35, "standardDeviation": 0, "startDate": "2022-07-24", "sum": -70 }, { "count": 6, "endDate": "2022-08-31", "max": -24, "mean": -41.333333333333336, "median": -34.5, "min": -90, "standardDeviation": 24.21294419657937, "startDate": "2022-08-01", "sum": -248 }, { "count": 5, "endDate": "2022-09-30", "max": -34, "mean": -34.2, "median": -34, "min": -35, "standardDeviation": 0.4472135954999579, "startDate": "2022-09-01", "sum": -171 }, { "count": 3, "endDate": "2022-10-31", "max": -30, "mean": -32.666666666666664, "median": -34, "min": -34, "standardDeviation": 2.309401076758503, "startDate": "2022-10-01", "sum": -98 }, { "count": 3, "endDate": "2022-11-30", "max": -34, "mean": -34, "median": -34, "min": -34, "standardDeviation": 0, "startDate": "2022-11-01", "sum": -102 }, { "count": 3, "endDate": "2022-12-31", "max": -28, "mean": -32, "median": -34, "min": -34, "standardDeviation": 3.4641016151377544, "startDate": "2022-12-01", "sum": -96 }, { "count": 3, "endDate": "2023-01-31", "max": -30, "mean": -32.666666666666664, "median": -34, "min": -34, "standardDeviation": 2.309401076758503, "startDate": "2023-01-01", "sum": -98 }, { "count": 4, "endDate": "2024-06-30", "max": -26.23, "mean": -31.0575, "median": -32, "min": -34, "standardDeviation": 3.7300435654292294, "startDate": "2024-06-01", "sum": -124.23 }, { "count": 3, "endDate": "2024-07-24", "max": -28, "mean": -30.666666666666668, "median": -30, "min": -34, "standardDeviation": 3.0550504633038935, "startDate": "2024-07-01", "sum": -92 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [ "bb12a859-09b7-4021-8ac5-522e01d00159", "d0bbf017-2c98-4eb1-835c-66dbe0998b02", "68bdc784-89d6-4704-9ded-d3e0f706f9e1" ], "transactionIds": [ "101402234952", "101402235803", "101402235249", "101402235478" ] }, { "attributeName": "NSF_FEE_REVERSALS", "aggregatedByTimePeriods": [ { "periods": [ { "count": 0, "endDate": "2022-07-31", "startDate": "2022-07-24" }, { "count": 0, "endDate": "2022-08-31", "startDate": "2022-08-01" }, { "count": 0, "endDate": "2024-06-30", "startDate": "2024-06-01" }, { "count": 0, "endDate": "2024-07-24", "startDate": "2024-07-01" } ], "timeIntervalType": "MONTHLY_CALENDAR" } ], "streamIds": [], "transactionIds": [] } ], "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": -220.48000000000002, "count": 8, "endDate": "2022-07-31", "endingValue": -329.4, "max": 201.69, "mean": -88.58, "median": -84.805, "min": -329.4, "standardDeviation": 169.11989534055417, "startDate": "2022-07-24", "sum": -708.64 }, { "beginningValue": 321, "count": 31, "endDate": "2022-08-31", "endingValue": -43.64, "max": 646, "mean": 19.563548387096777, "median": 0, "min": -923.38, "standardDeviation": 251.584474289762, "startDate": "2022-08-01", "sum": 606.47 }, { "beginningValue": 0, "count": 30, "endDate": "2024-06-30", "endingValue": 0, "max": 3390, "mean": -50.952, "median": 0, "min": -4974.33, "standardDeviation": 1117.177412711036, "startDate": "2024-06-01", "sum": -1528.56 }, { "beginningValue": 0, "count": 24, "endDate": "2024-07-24", "endingValue": 0, "max": 3390, "mean": -62.34708333333333, "median": 0, "min": -4974.33, "standardDeviation": 1254.1757580473845, "startDate": "2024-07-01", "sum": -1496.33 } ], "timeIntervalType": "MONTHLY_CALENDAR" } ] } ], "streams": [ { "cadence": 0, "id": "d0bbf017-2c98-4eb1-835c-66dbe0998b02", "payee": "verizon", "payor": "NSF USER", "recency": 589, "transactionIds": [ "101402234898" ] }, { "cadence": 5, "id": "0139e287-041d-4c45-b51d-108d204c05e2", "payee": "Account Owner (Name Unavailable)", "payor": "capital1 bob jones", "recency": 4, "transactionIds": [ "101402235180" ] }, { "cadence": 73, "id": "071c8894-460c-4b55-a0dd-783d420be32d", "payee": "murphy express", "payor": "Roberta Prohaska", "recency": 307, "transactionIds": [ "101402235534" ] }, { "cadence": 122, "id": "649504d3-f9ef-4476-9743-ebf45563158d", "payee": "renttrk-inco", "payor": "Roberta Prohaska", "recency": 322, "transactionIds": [ "101402235506" ] } ] }, "gseEnabled": true } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a Cash Flow Analytics report: [Cash_Flow_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Cash_Flow_Analytics_HTR.pdf) (4MB) ## Reading a Cash Flow Analytics JSON Report {#reading-a-cash-flow-analytics-json-report} This section provides a detailed description of the structure and format of the JSON version of Cash Flow Analytics. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. ### Cashflow Analytics Attributes {#cashflow-analytics-attributes} The above sample demonstrates some, if not all, Cashflow Analytics attributes from the following table:
| Attribute | Definition | Type | |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | NSF_FEE_CHARGES | Fees charged to the customer, by their financial institution - resulting from a lack of sufficient funds or low balance to cover a purchase. | Transactional | | NSF_FEE_REVERSALS | Credit transaction of an NSF fee charged earlier. | Transactional | | CASH_INFLOW | Credit transactions in a customer's account | Transactional | | CASH_OUTFLOW | Debit/Spend transactions in a customer's account | Transactional | | ALL_CASH_FLOWS | This is an umbrella attribute which sums: - CASH_INFLOW - CASH_OUTFLOW | Transactional | | NET_CASH_FLOW | Total Credits less Total Debits over a period of time and across all accounts owned by an individual or business. Calculation of net cash flow into or out of a customer's account(s). | State | | | | | #### Time Interval Types {#time-interval-types} A report supports up to two time interval types currently. If you request more than two interval types, the endpoint returns an error `More than 2 intervalTypes passed request`. If the time interval type is not specified, the default is `MONTHLY_CALENDAR`. The following table shows all possible time interval types you can request a report for: | Time Interval Type | Description | First (Earliest) period may be partial | First (Most Recent) period may be partial | Shortest possible period length | Longest possible period length | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------| | DAILY | The report will be broken up into one period for every calendar date in the report time period | NO | NO | 1 | 1 | | WEEKLY_CALENDAR | The report time period will be broken up into periods of 7 calendar dates, each beginning on Monday and ending on Sunday, except the first and last periods which may be partial | YES | YES | 1 | 7 | | WEEKLY_ROLLING_7 | The report time period will be broken up into periods of 7 calendar dates, counting backwards from the report end date | YES | NO | 1 | 7 | | BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, each beginning on a Monday and ending on the 2nd subsequent Sunday, except the first and last periods which may be partial | YES | YES | 1 | 14 | | BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date | YES | NO | 1 | 14 | | SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly 2 periods per calendar month, where both the first and last period may be partial, and periods will alternate between representing the 1st-15th and the 16th-end of the month | YES | YES | 1 | 16 | | MONTHLY_CALENDAR | The report time period will be broken up into 1 period per calendar month | YES | YES | 1 | 31 | | MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by 1 period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 36 | | QUARTERLY_CALENDAR | The report time period will be broken up into 1 period per 3 calendar months, where both the first and last period may be partial | YES | YES | 1 | 92 | | QUARTERLY_ROLLING_90 | The report time period will be broken up into 3 periods of 90 calendar dates followed by 1 period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date | YES | NO | 1 | 96 | | ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date | YES | NO | 1 | 366 | | HISTORICALLY | The report time period will be represented by exactly 1 period covering the duration of report data | NO | NO | 1 | Duration of report data | The following JSON snippet shows an example of how time interval type is requested: * Json ```json { "analyticsReportData": { "timeIntervalTypes": [ "MONTHLY_CALENDAR", "ANNUALLY" ] } } ``` ### JSON Report Structure - Analytics Section {#json-report-structure---analytics-section} Analytics will be provided at both the account level, grouped by (financial) institution, and at an aggregated customer level, similar to how most other Lend and OBB products work today. The following examples show a customer with two accounts that contain transactions. * Json ```json "accounts": [ { "id": 1065737689 }, { "id": 1065737690 } ] ``` The analytics section is divided into 3 sections: 1. Transactional attributes 2. State attributes 3. Streams #### Account-Level Analytics Structure {#account-level-analytics-structure} * Json ```json "analytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ``` Note: This section will be for each of the customer accounts. #### Customer-Level Analytics Structure {#customer-level-analytics-structure} * Json ```json "customerAnalytics": { "transactionalAttributes": [... ], "stateAttributes": [... ], "streams": [... ] } ``` ### Transactional Attributes {#transactional-attributes} Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. As an example, an attribute called DWELLING_EXPENSES may be a classification of all transactions that we assume to be a customer paying towards a mortgage, rent, home insurance, etc. Transactional attributes will be reported by one of the below time interval type specified in the constraints by the requesting partner. The following JSON snippets are for transactional attributes on accounts and customer level. Please note the following: 1. For demonstration purposes, the below snippets show transaction data of 1 month for MONTHLY_CALENDAR time interval type. The actual report will have all transaction stats for all the months. 2. The period array for ANNUALLY will show aggregated data for all the months between the specified start and end dates. 3. Not all attributes are showcased. Please access the attribute table above to see all the Cashflow Analytics attributes. 4. The data in the below snippets are for *Cashflow_Analytics* report which is attached above.
* Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": -12.11, "mean": -12.21, "median": -12.21, "min": -12.31, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": -24.42, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 18, "endDate": "2024-06-23", "max": -1.2, "mean": -6.9911111111111115, "median": -7.140000000000001, "min": -12.31, "standardDeviation": 3.617743672656446, "startDate": "2023-06-24", "sum": -125.84, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "ae6bec67-e1a0-4ff4-8220-8439398a373e" ], "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": 12.21, "mean": 12.11, "median": 12.11, "min": 12.01, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": 24.22, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 19, "endDate": "2024-06-23", "max": 12.21, "mean": 6.6352631578947365, "median": 6.24, "min": 1.1, "standardDeviation": 3.5608962174353, "startDate": "2023-06-24", "sum": 126.07, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_INFLOW", "streamIds": [ "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4" ], "transactionIds": [ "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 4, "endDate": "2023-12-31", "max": 12.21, "mean": -0.04999999999999982, "median": -0.04999999999999982, "min": -12.31, "standardDeviation": 14.041633333293769, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 37, "endDate": "2024-06-23", "max": 12.21, "mean": 0.006216216216216155, "median": 1.1, "min": -12.31, "standardDeviation": 7.75851587731949, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "ALL_CASH_FLOWS", "streamIds": [ "ae6bec67-e1a0-4ff4-8220-8439398a373e", "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4" ], "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829", "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ], "projectedValues": [], "streamConfidences": null } ] ``` * Json ```json "transactionalAttributes": [ { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": -12.11, "mean": -12.21, "median": -12.21, "min": -12.31, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": -24.42, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 18, "endDate": "2024-06-23", "max": -1.2, "mean": -6.9911111111111115, "median": -7.140000000000001, "min": -12.31, "standardDeviation": 3.617743672656446, "startDate": "2023-06-24", "sum": -125.84, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_OUTFLOW", "streamIds": [ "9ef16f42-baa9-47ba-a936-564ce19fb9ee" ], "transactionIds": [ "128512270962", "128512270955", "128512270954", "128512270956", "128512268805", "128512270976", "128512270940", "128512270960", "128512268803", "128512268800", "128512268799", "128512270943", "128512270942", "128512270938", "128512268808", "128512268807", "128512268793", "128512270953" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 2, "endDate": "2023-12-31", "max": 12.21, "mean": 12.11, "median": 12.11, "min": 12.01, "standardDeviation": 0.14142135623731025, "startDate": "2023-12-01", "sum": 24.22, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 19, "endDate": "2024-06-23", "max": 12.21, "mean": 6.6352631578947365, "median": 6.24, "min": 1.1, "standardDeviation": 3.5608962174353, "startDate": "2023-06-24", "sum": 126.07, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "CASH_INFLOW", "streamIds": [ "2efb4258-4457-4391-8f40-4bfd973af49a" ], "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ], "projectedValues": [], "streamConfidences": null }, { "aggregatedByTimePeriods": [ { "periods": [ { "count": 4, "endDate": "2023-12-31", "max": 12.21, "mean": -0.04999999999999982, "median": -0.04999999999999982, "min": -12.31, "standardDeviation": 14.041633333293769, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "count": 37, "endDate": "2024-06-23", "max": 12.21, "mean": 0.006216216216216155, "median": 1.1, "min": -12.31, "standardDeviation": 7.75851587731949, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "attributeName": "ALL_CASH_FLOWS", "streamIds": [ "9ef16f42-baa9-47ba-a936-564ce19fb9ee", "2efb4258-4457-4391-8f40-4bfd973af49a" ], "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ], "projectedValues": [], "streamConfidences": null } ] ``` ##### JSON Fields Description {#json-fields-description} | Key (Datatype) | Description | Applicable for Cashflow Analytics | |-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------| | **aggregatedByTimePeriods** (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes | | **periods** (object) | Statistics of aggregated transactions over some time period. | Yes | | **count** (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes | | **endDate** (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes | | **max** (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes | | **mean** (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for monthly time interval, mean will be shown for each month of a year. | Yes | | **median** (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for monthly time interval, median will be shown for each month of a year. | Yes | | **min** (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for monthly time interval, min will be shown for each month of a year. | Yes | | **standardDeviation** (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for monthly time interval, standardDeviation will be shown for each month of a year. | Yes | | **startDate** (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for monthly time interval, startDate will be shown for each month of a year. | Yes | | **sum** (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for monthly time interval, sum will be shown for each month of a year. | Yes | | **comparedToCohorts** (object) | An array of elements comparing the customer's spending during a time period to the average customer's spending in various cohorts, such as postal code, during the same time period. | No | | **cohortType** (string) | Describes the type of cohort being compared to for this period, e.g. POSTAL_CODE | No | | **totalDifferenceToCohort** (number) | Reflects the difference between the customer's spending for the period minus that of the average spending in this cohort. | No | | **percentageDifferenceToCohort** (number) | Reflects the percentage difference between the customer's sum value for the period and the average of the cohort | No | | **timeIntervalType** (string) | See *Time Interval Types* above for how each period is defined. | Yes | | **cohortBenchmarkPeriods** (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the spending of cohorts in the customer's zip code during that period for an attribute. | Yes | | **startDate** (string) | The first day of the cohort benchmark period. | Yes | | **endDate** (string) | The final day of the cohort benchmark period. | Yes | | **cohortValues** (object) | An object that contains type and value of a cohort benchmark period. | No | | **cohortType** (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, e.g. POSTAL_CODE. | No | | **value** (number) | For each cohort benchmark period, the average spending of the cohort during this time period. | No | | **attributeName** (string) | Name of the attribute that we are reporting the numbers for. Refer to the attributes list above. | Yes | | **streamIds** | List of stream IDs associated with the attribute. See more details about "Streams" below | Yes | | **transactionIds** (object) | List of transaction IDs associated with the attribute. | Yes | | **projectedValues** (object) | List of projection objects, where each object indicates the projected sum value of the attribute over some coming period of time. | No | | **timeUnit** (string) | The unit of time being described, e.g. MONTHS | No | | **timeValue** (number) | The number of timeUnit units for which we are projecting, e.g. 12 (for 12 months) | No | | **projectionValue** (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. | No | | **streamConfidences** (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | No | | **streamId** (string) | The stream ID we are reporting the confidence for. | No | | **confidence** (number) | A float value between 0 and 100 indicating the confidence over whether a stream is correctly associated to an income attribute | No | ### State Attributes {#state-attributes} The unit of data for state attributes is some generic "state" at a point in time. Whereas transactional attributes are based on specific events (the posting of a transaction), state attributes make some inference about a point in time based on some assembly of underlying data. Examples of state attributes might include something like the balance of an account over time, a calculation based on underlying transactions in a time period (e.g. net cash flow), or some other calculation such as a debt to income ratio. The following JSON snippets for transactional attributes on accounts and customer level. Please note the following: 1. For demonstration purposes, the below snippets show transaction data of 1 month for MONTHLY_CALENDAR time interval type. The actual report will have all transaction stats for all the months. 2. The period array for ANNUALLY will show aggregated data for all the months between the specified start and end dates. 3. The data in the below snippets are for *Cashflow_Analytics* report which is attached above.
* Json ```json "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 12.01, "count": 31, "endDate": "2023-12-31", "endingValue": -12.31, "max": 12.21, "mean": -0.006451612903225784, "median": 0.0, "min": -12.31, "standardDeviation": 4.44038703147004, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 6.24, "count": 366, "endDate": "2024-06-23", "endingValue": 0.0, "max": 12.21, "mean": 0.000628415300546442, "median": 0.0, "min": -12.31, "standardDeviation": 2.436596410931794, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 12.01, "count": 31, "endDate": "2023-12-31", "endingValue": -12.31, "max": 12.21, "mean": -0.006451612903225784, "median": 0.0, "min": -12.31, "standardDeviation": 4.44038703147004, "startDate": "2023-12-01", "sum": -0.1999999999999993, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 6.24, "count": 366, "endDate": "2024-06-23", "endingValue": 0.0, "max": 12.21, "mean": 0.000628415300546442, "median": 0.0, "min": -12.31, "standardDeviation": 2.436596410931794, "startDate": "2023-06-24", "sum": 0.22999999999999776, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` * Json ```json "stateAttributes": [ { "attributeName": "NET_CASH_FLOW", "reportedByTimePeriods": [ { "periods": [ { "beginningValue": 24.02, "count": 31, "endDate": "2023-12-31", "endingValue": -24.62, "max": 24.42, "mean": -0.012903225806451568, "median": 0.0, "min": -24.62, "standardDeviation": 8.88077406294008, "startDate": "2023-12-01", "sum": -0.3999999999999986, "comparedToCohorts": [] } ], "timeIntervalType": "MONTHLY_CALENDAR", "cohortBenchmarkPeriods": [ { "startDate": "2023-12-01", "endDate": "2023-12-31", "cohortValues": [] } ] }, { "periods": [ { "beginningValue": 12.48, "count": 366, "endDate": "2024-06-23", "endingValue": 0.0, "max": 24.42, "mean": 0.001256830601092884, "median": 0.0, "min": -24.62, "standardDeviation": 4.873192821863588, "startDate": "2023-06-24", "sum": 0.4599999999999955, "comparedToCohorts": [] } ], "timeIntervalType": "ANNUALLY", "cohortBenchmarkPeriods": [ { "startDate": "2023-06-24", "endDate": "2024-06-23", "cohortValues": [] } ] } ], "projectedValues": [] } ] ``` #### JSON Fields Description {#json-fields-description-1} While most of the keys overlap with transactional attributes, the following are state attributes-specific keys: | Key (Datatype) | Description | |------------------------------------|------------------------------------------------------------------------| | **reportedByTimePeriods** (object) | Value of the "state" over some time periods | | **beginningValue** (number) | Value of the "state" as reported on the `startDate` of the period | | **endingValue** (number) | Value of the "state" as reported on the `endDate` of the period | | **count** (number) | Occurrences of the "state" between specified `startDate` and `endDate` | ### Streams {#streams} Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between two parties (or accounts, if the same entity owns both the source and destination of funds). Examples of streams include: bi-weekly paychecks from an employer to an employee, a customer's monthly phone bill paid to a telecom provider, a customer's monthly transfer from a checking account to an investment account, etc. Since a stream is just a group of transactions, a transactional attribute can assign a list of streams to itself if the transactions in that stream all fit the same classification being described by the attribute. * Json ```json "streams": [ { "cadence": 20, "id": "ae6bec67-e1a0-4ff4-8220-8439398a373e", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829" ] }, { "cadence": 20, "id": "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "9ef16f42-baa9-47ba-a936-564ce19fb9ee", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270962", "128512270955", "128512270954", "128512270956", "128512268805", "128512270976", "128512270940", "128512270960", "128512268803", "128512268800", "128512268799", "128512270943", "128512270942", "128512270938", "128512268808", "128512268807", "128512268793", "128512270953" ] }, { "cadence": 20, "id": "2efb4258-4457-4391-8f40-4bfd973af49a", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ] } ] ``` * Json ```json "streams": [ { "cadence": 20, "id": "ae6bec67-e1a0-4ff4-8220-8439398a373e", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270764", "128512270796", "128512270747", "128512270771", "128512270746", "128512270756", "128512270773", "128512270780", "128512270798", "128512270758", "128512268825", "128512270797", "128512270776", "128512268830", "128512268821", "128512268816", "128512268815", "128512268829" ] }, { "cadence": 20, "id": "e6ea8ff3-6995-440f-8c6e-9d26bb61b2a4", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270757", "128512270751", "128512268827", "128512270770", "128512270769", "128512268812", "128512268817", "128512268819", "128512270752", "128512270753", "128512270790", "128512270792", "128512270768", "128512268824", "128512268828", "128512270791", "128512270772", "128512270783", "128512270784" ] }, { "cadence": 20, "id": "9ef16f42-baa9-47ba-a936-564ce19fb9ee", "payee": "walmart", "payor": "JOHN DOE", "recency": 20, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "active", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512270962", "128512270955", "128512270954", "128512270956", "128512268805", "128512270976", "128512270940", "128512270960", "128512268803", "128512268800", "128512268799", "128512270943", "128512270942", "128512270938", "128512268808", "128512268807", "128512268793", "128512270953" ] }, { "cadence": 20, "id": "2efb4258-4457-4391-8f40-4bfd973af49a", "payee": "JOHN DOE", "payor": "walmart", "recency": 30, "earliestObservedDate": null, "latestObservedDate": null, "count": null, "sum": null, "status": "inactive", "min": null, "max": null, "mean": null, "median": null, "standardDeviation": null, "minimumCadence": null, "maximumCadence": null, "medianCadence": null, "modeCadence": null, "standardDeviationCadence": null, "transactionIds": [ "128512268809", "128512270973", "128512270963", "128512270935", "128512268798", "128512270951", "128512270961", "128512270941", "128512270972", "128512268801", "128512270959", "128512270932", "128512270939", "128512268794", "128512270967", "128512270952", "128512270946", "128512270948", "128512268802" ] } ] ```
#### JSON Fields Description {#json-fields-description-2} While most of the keys overlap with transactional attributes, the following are stream attributes-specific keys: | Key (Datatype) | Description | |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | **cadence** (number) | The average number of days elapsed between consecutive transactions in the stream | | **id** (string) | A randomly generated UUID to uniquely identify the stream | | **payee** (string) | The party that is receiving the funds | | **payor** (string) | The party that is sending the funds | | **recency** (number) | The number of days elapsed since the most recent transaction in the stream | | **earliestObservedDate** (string) | The date-time of the first observed transaction in the stream | | **latestObservedDate** (string) | The date-time of the last observed transaction in the stream | | **status** (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence | | **minimumCadence** (number) | The smallest observed duration of time elapsed between any 2 consecutive transactions in the stream | | **maximumCadence** (number) | The largest observed duration of time elapsed between any 2 consecutive transactions in the stream | | **medianCadence** (number) | The median number of days elapsed between consecutive transactions in the stream | | **modeCadence** (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream | | **standardDeviationCadence** (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream | | **transactionIds** (object) | A list of all the transaction IDs that were assigned to the stream | ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Data Connect Components Web SDK source: https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md The Mastercard Data Connect Components SDK provides a collection of custom web components that can be used to build login forms for legacy institutions, initiate OAuth authentication flow for institutions, and render Multi-Factor Authorization (MFA) challenges encountered during legacy institution login. This section describes how to integrate Data Connect Components with different Financial Institutions (FIs), how to set up MFA so end users can connect to their FI securely, and how Data Connect Components elements and events can be used to create a clean interface through the authentication process. * [First Steps](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#first-steps) * [Login Form Usage](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#login-form-usage) * [OAuth Usage](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#oauth-usage) * [Data Connect Components Styling Interface](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#data-connect-components-styling-interface) * [Elements](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#elements) * [Events](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#events) ## First Steps {#first-steps} The implementation steps depend on whether you are using login forms or an OAuth URL (in other words, whether the FI is a legacy or OAuth connection): * [Login Form Usage](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#login-form-usage) - For connections that do not leverage direct connectivity (such as OAuth), a means to create and embed a login form is provided. * [OAuth URL Usage](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#oauth-usage) - For OAuth connections, the handling of credentials is facilitated directly by the FI. An API is provided to obtain a suitable URL. See also the [Legacy and OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md#legacy-and-oauth-connections) part of the [Data Connect Components Flows](https://developer.mastercard.com/open-finance-us/documentation/connect/components/flows/index.md) section. ### Configuration Objects (Optional) {#configuration-objects-optional} If you want to control which account types the user can connect with, you must first specify a configuration object. To do this, call the following endpoint and provide an array of the account types you want to allow. API Reference: `POST /connect-components/configurations` The response includes a configuration ID value which you can use when creating either a login form or OAuth URL. We provide the following endpoint to query what configuration objects have already been created: API Reference: `GET /connect-components/configurations` To query the details of an existing configuration use the following: API Reference: `GET /connect-components/configurations/{configuration\_id}` You can delete an unwanted configuration using this endpoint: API Reference: `DELETE /connect-components/configurations/{configuration_id}` ## Login Form Usage {#login-form-usage} For connections that do not use OAuth (legacy connections), the first step is to create a login form. If you created a configuration object in the previous step, then you should pass the configuration ID in the request body. API Reference: `POST /connect-components/institutions/{institution_id}/login-forms` The response from the Data Connect Components API to *create a login form* looks like this: ```json { "id": "8d9d8f5e-2c5f-4f49-bf9b-276a7df0367f", "eventStreamId": "8859489f-12aa-4fd3-bcf5-ba0249e643a3", "elements": [ { "id": "26410b1f-0347-4d57-bb03-f44d00e785e2", "label": "username", "sortOrder": 0 }, { "id": "f2ce62c2-877f-4c26-9935-d1ab6084e6d0", "label": "password", "sortOrder": 1 } ] } ``` This response must be provided to the Data Connect Components SDK to render the login form elements. Each item in the `elements` property represents a single `` for a customer to interact with. Note: Input Element Quantities Vary. It is important to note that the names and quantities of form elements in the create login form response depend entirely on what is required by 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. **Take care to account for variations in the number of Elements, and for different labels for each element.** ### Render Login Form {#render-login-form} The above response would be rendered using the SDK with the `` and `` elements. Notice that the top level `id` and `eventStreamId` properties from the response are attributes on the `mastercard-form` element. Additionally, each `id` from the items in the elements array should be used as the `id` attribute for separate `` elements. These `id` attributes provide the SDK with all of the information needed to render the login form. The `sortOrder` property indicates the ascending order the elements are displayed on the original bank login form. ```html ``` ### Submit Login Form {#submit-login-form} To submit this `` and initiate the connection to the customer's financial institution, the correct SDK submit method must be called. The following example shows the method as expressed in simple Javascript: ```javascript const mastercardForm = document.querySelector('mastercard-form'); const submitButton = document.querySelector('#submit-credentials'); submitButton.addEventListener('click', browserClickEvent => { browserClickEvent.preventDefault(); mastercardForm.submit(); }); ``` Once the `.submit()` method has been called on the `` element, the SDK handles sending the customer's credentials to Mastercard to begin the process of connecting to the customer's financial institution. For your application to know how the connection is progressing, you need to have event listeners for `success`, `error`, and `mfaChallenge`. To add an event listener, call the `addEventListener()` method on the `mastercard-form` element's `events` property. ```javascript const mastercardForm = document.querySelector('mastercard-form'); mastercardForm.events.mfaChallengeEvent('success', successEvent => { // This simple example handles the done event by posting the event payload // to the application's server and displaying a dialog to the user. const successfulConnection = new Request(`https://app.example.com/customers/${customerId}/success`, { method: 'POST', body: JSON.stringify(successEvent) }) fetch(successfulConnection) .then(response => response.json()) .then(serverMessage => { const notificationElement = document.querySelector('#customer-notification'); const userDialog = `

${serverMessage.customerSuccessNotification}

` notificationElement.setHTML(userDialog); }) .catch(console.error); }); mastercardForm.events.addEventListener('error', errorEvent => { // This example handles the error event by posting the error payload to the // application's server and notifying the customer that an error has occurred. const errorDuringLogin = new Request(`https://app.example.com/customers/${customerId}/error`, { method: 'POST', body: JSON.stringify(errorEvent) }) fetch(errorDuringLogin) .then(response => response.json()) .then(serverMessage => { const notificationElement = document.querySelector('#customer-notification'); const userDialog = `

${serverMessage.customerErrorNotification}

` notificationElement.setHTML(userDialog); }) .catch(console.error); }); mastercardForm.events.addEventListener('mfaChallenge', successEvent => { // The types of MFA challenges differ, refer to the MFA Required For Connection section below for more details. }); ``` ### Successful Financial Institution Connection {#successful-financial-institution-connection} If the connection to the financial institution is successful, the `success` [event](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#events) payload contains these fields: `customerId`, `institutionId`, `accountId`, and `institutionLoginId`. Detailed documentation for these fields can be found in the main [US Open Finance API Reference](https://developer.mastercard.com/drafts/open-finance-us/components-mfa-updates/documentation/api-reference/): * [customerId](https://developer.mastercard.com/drafts/open-finance-us/components-mfa-updates/documentation/api-reference/?view=model#Customer) * [institutionId](https://developer.mastercard.com/drafts/open-finance-us/components-mfa-updates/documentation/api-reference/?view=model#Institutions) * [accountId](https://developer.mastercard.com/drafts/open-finance-us/components-mfa-updates/documentation/api-reference/?view=model#CustomerAccount) * [institutionLoginId](https://developer.mastercard.com/drafts/open-finance-us/components-mfa-updates/documentation/api-reference/?view=api#GetCustomerAccountsByInstitutionLogin) With these values, your application's server can request the customer's financial information from the Mastercard Open Finance API. ```json [{ "customerId": "", "institutionId": "", "accountId": "", "institutionLoginId": "" }] ``` #### MFA Required for Connection {#mfa-required-for-connection} If an MFA challenge is encountered during connection, the [`mfaChallenge`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#mfachallenge-legacy-login-only) event is emitted. There are five types of [MFA challenges](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#mfa-challenge-types) that a financial institution can choose to send: * [`TFA_TEXT`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#tfa_text) * [`TFA_CHOICE`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#tfa_choice) * [`TFA_MULTI`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#tfa_multi) * [`TFA_IMAGE`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#tfa_image) * [`TFA_IMAGE_PROMPT`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#tfa_image_prompt). The `mfaChallenge` event payload contains an array of one or more challenge objects. The `mfaType` determines what properties are present in each challenge object. All challenge objects contain the following properties: `id`, `eventStreamId`, `mfaType`, `prompt`, and `choiceIds`. `TFA_IMAGE_PROMPT` challenges also contain a `promptImage` property. Note: The MFA challenge renderings below are provided to illustrate how the challenge could look. The final styling is up to your application. Please refer to the [Data Connect Components Styling Interface](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#data-connect-components-styling-interface) section for guidance. ##### TFA_TEXT {#tfa_text} The `TFA_TEXT` challenge type presents a single input box to the customer and is commonly used for things like One-Time Passwords. Below is the expected response for this type: ```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" ], }] ``` The following is an example of the HTML to render the challenge: ```html ``` This is a styled example of the `TFA_TEXT` challenge. Your application's rendering depends on the styling passed to the Styling Interface: ![Security Question Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_text_1.png) ![One-Time Password Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_otp_1.png) ##### TFA_CHOICE {#tfa_choice} The `TFA_CHOICE` object represents a multiple-choice question and answer selection. Below is the expected response for this type: ```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" ] }] ``` The following is an example of the HTML to render the challenge: ```html ``` This is a styled example of the `TFA_CHOICE` challenge. Your application's rendering depends on the styling passed to the Styling Interface: ![Multiple-Choice Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_choice_1.png) ##### TFA_MULTI {#tfa_multi} The `TFA_MULTI` challenge type presents the customer with multiple images to select from. Below is the expected response for this type: ```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" ], }] ``` The following is an example of the HTML to render the challenge: ```html ``` This is a styled example of the `MFA_MULTI` challenge. Your application's rendering depends on the styling passed to the Styling Interface: ![Multiple Image Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_multi_1.png) ##### TFA_IMAGE {#tfa_image} The `TFA_IMAGE` challenge presents a CAPTCHA-style image the customer needs to decipher. The `prompt` for this challenge is a [base64 URI encoded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) image, with a single choice element that is a text box to enter the unscrambled image text into. Following is the expected response for this type: ```json [{ "id": "2f7069e5-751d-47c4-9f41-4f00089c0c56", "prompt": "", "mfaType": "TFA_IMAGE", "choiceIds": [ "89427fa8-1383-43b0-87c0-6df9d9709247" ], "eventStreamId": "38d75027-cc9e-4aaa-b828-86cace5bf2df" }] ``` The following is an example of the HTML to render the challenge: ```html ``` This is a styled example of the `TFA_IMAGE` challenge. Your application's rendering depends on the styling passed to the Styling Interface: ![Decode Image](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_image_1.png) ##### TFA_IMAGE_PROMPT {#tfa_image_prompt} The `TFA_IMAGE_PROMPT` challenge type presents an image prompt in addition to a text prompt. Below is the expected response for this type: ```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" ], }] ``` The following is an example of the HTML to render the challenge: ```html

Choose the correct response.

 ``` This is a styled example of the `TFA_IMAGE_PROMPT` challenge. Your application's rendering depends on the styling passed to the Styling Interface: ![Image Prompt](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_image_prompt_2.png) #### Submit MFA Challenge {#submit-mfa-challenge} Submitting the MFA challenge is nearly identical to [submitting the login form](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#submit-login-form). ```javascript const mastercardForm = document.querySelector('mastercard-form'); const submitButton = document.querySelector('#submit-mfa'); submitButton.addEventListener('click', (browserClickEvent) => { browserClickEvent.preventDefault(); mastercardForm.submit(); }); ``` #### Error Occurred During Connection Attempt {#error-occurred-during-connection-attempt} If the connection to the financial institution fails, an `error` event is emitted. The payload contains the information needed to guide the customer through error resolution, if possible. Potential errors are described in the [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) and [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/index.md) sections. Based on the error code, you can determine the best method to guide the customer through the error resolution process. ```json { "code": 103 } ``` ## OAuth Usage {#oauth-usage} The OAuth implementation path begins with a call to **Create OAuth URL**. If you created a configuration object in the previous step then you should pass the configuration ID in the request body. API Reference: `POST /connect-components/institutions/{institution_id}/oauth-urls` ```curl curl --location --request POST ' /connect-components/institutions/{institution\_id}/oauth-urls' \ --header 'Finicity-App-Key: ' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: ' \ --data-raw '{ "redirectURI": "https://oauth.example.com/redirect", "customerId": "6021877507", "customerViewedAcceptedTermsPolicies": "true" }' ``` Note: The `redirectURI` is required for popup and redirection flows. The response includes the OAuth URL, a session ID, and an event stream ID: ```json { "id": "c315dc0d-fa08-488c-9601-77dea69acaeb", "url": "https://bank.example.com/oauth/login", "eventStreamId": "8859489f-12aa-4fd3-bcf5-ba0249e643a3" } ``` With the `url` value, there are two ways to navigate the customer to their FI's OAuth authentication page: * [Popup](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#popup) * [Redirection](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#redirection) Regardless of the method that is used to direct the customer to the OAuth authentication flow, the application will need to listen for the [`loggedIn`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#login-oauth-only) event describe above. ### Popup {#popup} The `url` can be opened into a popup window using the [`open()` method](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) on the window object of the browser: ```javascript const mastercardForm = document.querySelector('mastercard-form'); /** Call to Data Connect Component API to create a oauth url */ const oauthUrlResponse = requestOauthUrl(); /** Save the target name as a secondary way to get a reference to the popup window */ const targetName = 'financialInstitutionOauthLoginPage'; function openOauthUrl(url, target){ const windowFeatures = 'popup=true,width=320,height=320'; return window.open(url, target, windowFeatures); } /** Save a reference to the popup window returned by window.open. */ const oauthPopupRef = openOauthUrl(oauthUrlResponse.url, targetName); mastercardForm.events.addEventListener('loggedIn', loginEvent => { let popupWindow = oauthPopupRef; if (!popupWindow){ popupWindow = window.open('', targetName); } if (popupWindow && popupWindow.closed !== true){ popupWindow.close(); } oauthPopupRef = undefined; }); ``` Tip: The [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) of the OAuth url will be different than your application's origin. This means that your application will have [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) restrictions on how your application can interact with it. While limiting your ability to manipulate the popup, it is an inherent security feature of the OAuth authentication flow. Once the customer has completed the OAuth authentication flow with their institution and the institution has provided the OAuth token or error to the Data Connect Component API, the SDK emits the [`loggedIn`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#login-oauth-only) event. In the `loggedIn` event handler, your application needs to close the popup. ### Redirection {#redirection} Like the popup method, the redirection method starts with the call to **create an OAuth url**. ```curl curl --location --request POST ' /connect-components/institutions/{institution\_id}/oauth-urls' \ --header 'Finicity-App-Key: ' \ --header 'Accept: application/json' \ --header 'Finicity-App-Token: ' \ --data-raw '{ "redirectURI": "https://oauth.example.com/redirect", "customerId": "6021877507", "customerViewedAcceptedTermsPolicies": "true" }' ``` Your application redirects to the `url` from the create OAuth url request. Redirecting to the OAuth flow url could look like this: ```javascript window.location.replace(oauthUrlResponse.url); ``` When the OAuth authentication process is complete, the Data Connect Components API redirects to the `uri` that was provided as the value of the `redirectURI` property on the original request to create the OAuth url. It is **your application's responsibility** to ensure that the Data Connect Components Web SDK is loaded with the page that it is redirected to. This is vital, as the Web SDK is needed so that you can also initialize event listeners to receive the [`success`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#success) or [`error`](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#error) events emitted by the SDK and move the customer through the remainder of your customer flow. Again, it is *vital* that the page that the customer is redirected to does the following: 1. Loads the Data Connect Components Web SDK. 2. Creates a `` element with the appropriate `event-stream-id` attribute. 3. Adds event listeners for the `success` and `error` events. 4. Adds an event listener for `loggedIn` if using the popup flow. Below is a basic example of what is required on the redirection page for the SDK to properly listen for the `success` event, which is emitted after account discovery has been completed. `index.html`: ```html ``` `script.js`: ```javascript window.addEventListener('DOMContentLoaded', () => { const mastercardForm = document.querySelector('mastercard-form'); mastercardForm.events.addEventListener('success', successData => { // handle success here }); mastercardForm.events.addEventListener('error', errorData => { // handle errors here }); }); ``` Note: The value of `event-stream-id` is provided in the URL as a query parameter during the redirection at the end of the OAuth flow, in addition to a `code` indicating the status of the OAuth flow (`200` or `202` indicating success). Using the above example data, Data Connect Components would redirect to [https://oauth.example.com/redirect?event-stream-id=8859489f-12aa-4fd3-bcf5-ba0249e643a3\&code=200](https://oauth.example.com/redirect?event-stream-id=8859489f-12aa-4fd3-bcf5-ba0249e643a3&code=200) if the login was successful. ## Data Connect Components Styling Interface {#data-connect-components-styling-interface} Internally, the Data Connect Components Web SDK leverages iFrames to create a secured, sandboxed environment. Because of this, extra considerations must be made in regard to styling the Data Connect Component elements. ### Understanding Outer Components and Inner Elements {#understanding-outer-components-and-inner-elements} Styling the outer components (that is, `` and ``) can be done in much the same way as any other native HTML element using standard CSS concepts and frameworks. Attributes such as box-sizing, position, display, width, and height should be set here. Below is an example: ```css mastercard-input { display: block; height: 45px; width: 100%; } ``` The inner elements, such as the underlying text boxes, labels, and images used in the Legacy Login Forms and various MFA challenges cannot be styled directly and may only be styled using the provided Styling Interface. The `` and `` elements accept a `component-styles` attribute. This attribute must be a stringified JSON object. The JSON object must contain one or more of the following top-level properties: * `image` * `radio` * `label` * `input` * `image.tfa_multi` * `image.tfa_image` * `image.tfa_image_prompt` * `radio.tfa_multi` * `radio.tfa_choice` * `radio.tfa_image_prompt` * `label.tfa_choice` * `input.tfa_image` * `input.tfa_text` Each top-level property represents a selector for the inner element that will be styled. The value of each top-level property is another JSON object that contains key-value pairs representing CSS properties and their values. Below is an example: ```html ``` Note: The Styling Interface does not provide a means for cascading style rules. For example, if both `input` and `input.tfa_text` are provided, only the more appropriate rule will be applied (`input.tfa_text` in the case of a `TFA_TEXT` challenge, or `input` otherwise). The `component-styles` attribute is reactive and the inner elements re-render when a change to this attribute is detected. Any user generated content (such as `username`) persist between renders. The following baseline formatting is applied to the inner elements by default: ```css body { box-sizing: border-box; margin: 0; height: 100%; width: 100%; display: block; padding: 0; } label { display: block; height: 100%; width: 100%; } img { box-sizing: border-box; } input { box-sizing: border-box; } ``` ### Allowed Properties {#allowed-properties} The Styling Interface accepts the following allowed CSS properties. Please note that sanitization is performed on all incoming values and values that rely on CSS functions (for example, `calc()`) may not work as intended and are subject to removal in future SDK updates. * backgroundColor * border * borderBottom * borderBottomLeftRadius * borderBottomRightRadius * borderLeft * borderRadius * borderRight * borderTop * borderTopLeftRadius * borderTopRightRadius * bottom * boxSizing * color * cursor * display * fontFamily * fontKerning * fontSize * fontStretch * fontWeight * height * left * letterSpacing * lineHeight * margin * marginBottom * marginLeft * marginRight * marginTop * maxHeight * maxWidth * opacity * outline * padding * paddingBottom * paddingLeft * paddingRight * paddingTop * position * right * textAlign * textIndent * textShadow * textTransform * top * verticalAlign * width * writingMode * zIndex ### Examples {#examples} In many cases, it may be appropriate to only pass in styles needed to render the elements currently being displayed. ```html ``` The SDK also supports larger, re-usable objects that contain multiple styles. In these cases, the SDK uses the most appropriate top-level style object. ```html ``` ## Elements {#elements} All elements are custom [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) and provide a framework-agnostic way to encapsulate logic needed for each element. These elements enable developers to have complete control over the customer experience. * Mastercard Form * Mastercard Input * Mastercard MFA Choice ### Mastercard Form {#mastercard-form} ```html ``` The custom form element is responsible for brokering `postMessage` connections to the `` and `` elements. The element requires the `id` and `event-stream-id` attributes to be set and match the `id` and `eventStreamId` properties returned from the Data Connect Components API. #### Mastercard Input {#mastercard-input} ```html ``` These elements provide the core functionality for **legacy** institution login forms. There needs to be one `` for each of the login form inputs that is returned by the Data Connect Components API. This is typically just `username` and `password`, but there are some login forms that have a third or even fourth required input. Each `` element should have a single `id` attribute so the Data Connect Components SDK can render the correct login form data. This `id` must match the `elements[].id` property returned from the Data Connect Components API. ### Mastercard MFA Choice {#mastercard-mfa-choice} ```html ``` This is the element type that is used to capture a response from a customer. It can be an image or text box and depends on the MFA Challenge response. All that is needed from the calling application is an `id` attribute on the `mastercard-mfa-choice` so the Data Connect Components SDK can render the correct MFA challenge data. This `id` attribute must match the `choices[]` value returned from the Data Connect Components `mfaChallenge` event body. Note: MFA Challenge The MFA challenge will use the same `mastercard-form` element as the login forms. All of the `` elements should be children of a single `mastercard-form` element. ```html ``` ## Events {#events} ### `formStateChange` (*Legacy login only*) {#formstatechange-_legacy-login-only_} When a login form is initially rendered, the state of the form is 'isReady=false', as no user input has been entered. After all necessary fields have been entered, the state of the form will change to 'isReady=true'. This value changes again if the user clears one or more required fields on the login form or MFA challenge. This event can be used to determine if the user should be allowed to proceed. The only information provided by this event is the `isReady` flag. ```json { "isReady": "true" } ``` ### `focus` (*Legacy login only*) {#focus-_legacy-login-only_} This event behaves the same as the native Javascript focus event and may be used to modify the UI to reflect user interactions. The payload of this event contains the `id` of the element (login form or MFA challenge choice) that the user has selected. ```json { "elementId": "string" } ``` ### `blur` (*Legacy login only*) {#blur-_legacy-login-only_} This event behaves the same as the native Javascript blur event and may be used to modify the UI to reflect user interactions. The payload of this event contains the `id` of the element (login form or MFA challenge choice) that the user has navigated away from. ```json { "elementId": "string" } ``` ### `loggedIn` (OAuth only) {#loggedin-oauth-only} This event is triggered once the customer has completed the **OAuth** login flow with their financial institution. At this point, the calling application may close the **OAuth** popup window. An `id` is provided in the `loggedIn` event payload and is unique to each `loggedIn` event emitted. ```json { "id": "f1ec72c0-8376-44b3-99ec-f8f1ac0ae77d" } ``` ### `success` {#success} When the Mastercard Data Connect Components API has successfully connected to a customer's account(s), the `success` event is emitted. The payload for this event is an array of objects. Each object represents a single successful account connection. ```json [ { "customerId": "6021877507", "institutionId": "101732", "institutionLoginId": 6018508414, "accountId": "6038699817" } ] ``` ### `error` {#error} When an error is encountered during the login process, this error is captured and returned in the `error` event. The event payload scales down the needed information to enable your application to guide the customer in resolving the error, if resolvable. The payload on the `error` event contains a `code` property: ```json { "code": 103 } ``` For further information about error codes see the [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) section. ### `mfaChallenge` (*Legacy login only*) {#mfachallenge-_legacy-login-only_} While attempting to connect to customer accounts, a financial institution may send back a multi-factor challenge that the customer must complete to continue the login process. When an MFA Challenge is raised by an institution, an `mfaChallenge` event will be emitted. The `mfaChallenge` payload is an array of objects. Each object represents a single MFA challenge that needs to be resolved by the customer. The `mfaChallenge` event payload will contain an array of one or more challenge objects. The `mfaType` determines what properties are present in each challenge object. All challenge objects contain the following properties: `id`, `eventStreamId`, `mfaType`, `prompt`, and `choiceIds`. The `TFA_IMAGE_PROMPT` challenge type also contains a `promptImage` property. ```json [{ "id": "3ea29b1a-0c2c-4052-a3e1-0cdb856163e8", "eventStreamId": "da03e052-915b-4ddc-9098-1ecbcc757bea", "mfaType": "TFA_TEXT", "prompt": "What is your favorite color", "choiceIds": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] } ] ``` #### MFA Challenges Types {#mfa-challenges-types} There are five types of MFA challenges that may be returned. Note: The MFA challenge renderings below are provided to illustrate how the challenge could look. The final styling is up to your application. Please refer to the [Data Connect Components Styling Interface](https://developer.mastercard.com/open-finance-us/documentation/connect/components/integration/ccwebsdk/index.md#data-connect-components-styling-interface) section for guidance. ##### `TFA_TEXT` {#tfa_text-1} A `TFA_TEXT` challenge type presents a prompt and a single input box to the customer. These are commonly used for One-Time Passwords or challenge questions. Example of rendered `TFA_TEXT` challenge: ![Security Question Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_text_1.png) ![One-Time Password Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_otp_1.png) ##### `TFA_CHOICE` {#tfa_choice-1} A `TFA_CHOICE` challenge type presents a question and a multiple-choice answer selection. Example of rendered `TFA_CHOICE` challenge: ![Multiple-Choice Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_choice_1.png) ##### `TFA_MULTI` {#tfa_multi-1} A `TFA_MULTI` challenge type presents the customer with multiple images to select from. The prompt for this challenge is text, with multiple-choice elements that the customer needs to select. Example of rendered `TFA_MULTI` challenge: ![Multiple Image Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_multi_1.png) ##### `TFA_IMAGE` {#tfa_image-1} A `TFA_IMAGE` challenge presents a CAPTCHA-style image that the customer needs to decipher. The prompt for this challenge is an image, rendered by applying the payload to an `` element, with a `` element being a text box where the customer enters the deciphered image text. Example of rendered `TFA_IMAGE` challenge: ![Decode Image Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_image_1.png) ##### `TFA_IMAGE_PROMPT` {#tfa_image_prompt-1} A `TFA_IMAGE_PROMPT` challenge type presents an image prompt in addition to a text prompt. The prompt for this challenge is an image, with multiple-choice elements that the customer needs to select. Example of rendered `TFA_IMAGE_PROMPT` challenge: ![Image Prompt Challenge](https://static.developer.mastercard.com/content/open-finance-us/uploads/cc_tfa_image_prompt_2.png) --- # Verification of Income and Employment - Paystub (with TXVerify) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md The Verification of Income and Employment -- Paystub with Transaction Verify (VOIE-Paystub with TXVerify) product provides insights into the consumer's income and employment. The report includes digitized pay statement details, account information, and may include up to twenty-four months of income stream credit transaction history, and details of the matching of the pay statement details to the direct deposit transaction(s). Learn more about Mastercard's [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Deposit Income Streams**: Provides the full 24 months of deposit history as available. Defaults to only include Moderate and High confidence income streams, but can be adjusted to include Low confidence streams as well * **Digitized Paystub Details:** Includes pay statement, employer, and employee details using our OCR technology * **Estimated Monthly Income:** Estimates for base, bonus, and other pay types * **Transaction Verify - Income and Employment Matching Summary:** Results of the matching of the digitized paystub details to the direct deposit transaction(s) ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance **FI Certification Type** : Verification of Income (VOI). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 6 minutes * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. This report may also be refreshed as a Verification of Employment (VOE) Transactions product. * **Supported Account Types**: Checking, Savings, Money Market ### Use Cases {#use-cases} The VOIE -- Paystub (with TXVerify) product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. The product also requires access to the customer's paystub, which can be uploaded via the Data Connect application, or collected by the client and shared via the API (see below for details). * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#data-connect-flows)
## Generate VOIE -- Paystub (With TXVerify) Report {#generate-voie----paystub-with-txverify-report} Refer to [Generating Reports Using the API](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-the-api) for general information on report generation. There are two ways to generate a VOIE -- Paystub (with TXVerify) report: * automated report generation at the end of a Data Connect Full session * client-initiated API report generation There are some specific nuances for client-initiated API VOIE -- Paystub (with TXVerify) report generation that are described below. To generate or refresh a VOIE -- Paystub (with TXVerify) report, use the following steps: **1. Data Connect Bank Accounts** Have the consumer connect to their bank account(s) where they deposit their pay. Find more information on account connection in [Generating Reports Using Data Connect](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-data-connect). If the consumer has already connected accounts previously, move to the next step. **2. Collect the consumer's recent paystub** File requirements: * Upload the most recent paystub for each employer (limit is 3 files) * One file can only contain the details for one paystub * Acceptable file types: `pdf`, `png`, or `jpeg` * The file size limit is 25 MB * No bank statements or non-paystub images * No password-protected PDF files
**3. Store the consumer's paystub and get an asset ID** API Reference: `POST /aggregation/v1/customers/{customerId}/payStatements` **4. Generate the VOIE -- Paystub (with TXVerify) report** API Reference: `POST /decisioning/v2/customers/{customerId}/voieTxVerify/withInterview` The response includes the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * The assetId returned in step 3 is used to indicate which paystub files should be included in the report. * Use the `fromDate` parameter to customize the transaction history included in the report, up to 24 months maximum. By default, 2 months of history will be aggregated as available. The income stream transactions will always show the full history, up to 24 months as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * Customize the income streams returned in this report based on the confidence level. This input is called `incomeStreamConfidenceMinimum`. All income streams whose confidence level is greater than or equal to the number requested are provided. By default, the report will default to only include Moderate and High confidence income streams. * High confidence levels correspond to `confidence` values of 75 and 100. * Moderate confidence levels correspond to a `confidence` value of 50 * Low confidence levels correspond to `confidence` values of 0 and 25 * Streams with confidence levels of Moderate or High are considered income. Streams with a confidence level of Low are considered non-income. Receiving all income streams may be desirable based on the use case. ## Get VOIE -- Paystub (w/ TXVerify) Report {#get-voie----paystub-w-txverify-report} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "2f3z55zuwewm-voietxverify", "customerId": 1275320, "consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "consumerSsn": "6789", "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "7a7qyps2iy", "type": "voieTxVerify", "status": "success", "createdDate": 1579819592, "title": "Verification of Income and Employment - Paystub (with TXVerify)", "constraints": { "accountIds": [ "1000535275", "6001966284" ], "fromDate": 1620322948, "voieWithInterviewData": { "txVerifyInterview": [ { "assetId": "6f8fb0a0-e882-4f57-b672-cf53f1397581", "accounts": [] } ], "extractEarnings": true, "extractDeductions": false, "extractDirectDeposit": true }, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true } ], "incomeStreamConfidenceMinimum": 50 }, "customerType": "active", "portfolioId": "9qud7dtuzbew-13-port", "numberOfBillableAssets": 1, "reportStyle": "voieWithInterview", "assetIds": [ "6f8fb0a0-e882-4f57-b672-cf53f1397581" ], "payStatements": { "payPeriod": "LastPayPeriod", "billable": true, "assetId": "6f8fb0a0-e882-4f57-b672-cf53f1397581", "payDate": 1559241000, "startDate": 1557513000, "endDate": 1558722600, "netPayCurrent": 1802.22, "netPayYTD": 36000, "grossPayCurrent": 24200, "grossPayYTD": 72600, "matchType": "NET_PAY_MATCH", "employer": { "name": "Rocket Surgery" }, "employee": { "name": "Patrick Purchaser" }, "payStat": { "name": "regular 1", "type": "regular", "description": "regular income", "amountCurrent": 6000, "amountYTD": 18000 }, "directDeposits": [ { "fiName": "America First", "accountType": "Checking", "amountCurrent": 1744.61, "description": "Payroll" } ], "monthlyIncome": { "estimatedMonthlyBasePay": 2000, "estimatedMonthlyOvertimePay": 50, "estimatedMonthlyBonusPay": 20, "estimatedMonthlyCommissionPay": 50, "estimatedMonthlyOtherPay": 150, "estimatedMonthlyTotalPay": 2120 }, "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAsOfDate": 1577986990, "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "name": "Checking", "type": "checking", "availableBalance": 123.45, "aggregationStatusCode": 0, "balance": 123.45, "balanceDate": 1588350276, "averageMonthlyBalance": 301.45, "transactions": [], "details": { "interestMarginBalance": -50000, "availableCashBalance": 1500, "vestedBalance": 300000, "currentLoanBalance": 0, "availableBalanceAmount": 2000 }, "incomeStream": { "id": "dens28i3vsch-voitxverify2", "name": "none", "status": "ACTIVE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 180 }, "netAnnual": 110475.7, "projectedNetAnnual": 0, "estimatedGrossAnnual": 0, "projectedGrossAnnual": 151609, "incomeStreamMonths": 24, "averageMonthlyIncomeNet": 9206.31, "transactions": [ { "id": 100000527471, "amount": 1802.22, "postedDate": 1559241000, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck", "payStatementMatchTypes": [ "DATE", "NET_AMOUNT", "DIRECT_DEPOSIT_AMOUNT", "EMPLOYER_NAME", "INCOME_STREAM_PAYCHECK" ] } ] }, "incomeStreams": [ { "id": "dens28i3vsch-voitxverify2", "name": "none", "status": "ACTIVE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 180 }, "netAnnual": 110475.7, "projectedNetAnnual": 0, "estimatedGrossAnnual": 0, "projectedGrossAnnual": 151609, "incomeStreamMonths": 24, "averageMonthlyIncomeNet": 9206.31, "transactions": [ { "id": 100000527471, "amount": 1802.22, "postedDate": 1559241000, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck", "payStatementMatchTypes": [ "DATE", "NET_AMOUNT", "DIRECT_DEPOSIT_AMOUNT", "EMPLOYER_NAME", "INCOME_STREAM_PAYCHECK" ] } ] } ] } } }, "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": [ { "id": 1000023996, "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1577986990, "name": "Checking", "number": "1111", "type": "checking", "aggregationStatusCode": 0, "incomeStreams": [ { "id": "dens28i3vsch-voietxverify", "name": "none", "status": "ACTIVE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 180 }, "netMonthly": [ { "month": 1522562400, "net": 2004.77 } ], "netAnnual": 110475.7, "projectedNetAnnual": 0, "estimatedGrossAnnual": 0, "projectedGrossAnnual": 151609, "averageMonthlyIncomeNet": 9206.31, "incomeStreamMonths": 24, "transactions": [ { "id": 100000527471, "amount": 1802.22, "postedDate": 1559241000, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck" } ] } ], "balance": 123.45, "averageMonthlyBalance": 301.45, "transactions": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "investmentTransactionType": "dividend", "normalizedPayee": "Finicity", "institutionTransactionId": "100000000", "category": "Paycheck", "bestRepresentation": "FINICITY INC PAYROLL" } ], "details": { "interestMarginBalance": -50000, "availableCashBalance": 1500, "vestedBalance": 300000, "currentLoanBalance": 0, "availableBalanceAmount": 1000, "marginBalance": 100, "currentBalance": 1000 }, "position": { "id": 637054, "currency": "USD", "symbol": "MCD", "securityName": "Common Stock", "units": 5, "marketValue": 1403.55, "currentPrice": 280.71, "securityType": "Stock" }, "availableBalance": 123.45 } ] } } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a VOIE -- Paystub (with TXVerify) report: [VOIE_Paystub_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOIE_Paystub_Report_HTR.pdf) (1MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported VOIE -- Paystub (w/ TXVerify) account types and has a test paystub file download option, such as [Jess Sea](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#paystub-profiles). --- # Data Enrichment API source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/api/index.md This section explains how to use [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) via API. We also have a [Batch Processing](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/batch/index.md) solution. ## How It Works - API {#how-it-works---api} For most use cases we recommend using Transaction Data Enrichment via the API. The API can handle up to 5,000 calls per hour. Each call can contain up to 1000 transactions, so up to 5 million transactions per hour can be handled by the API. Note: When testing in Sandbox, you can perform up to 50 calls a day, with a maximum of 10 transactions to be enriched per call. Contact your Customer Success Manager (CSM) to be moved to Test Drive Premium for testing with higher volumes against our production environment. Test Drive Premium requires a contract to be signed and will be available for 30 days. 1. **Generate the required credentials to call the API** See the [API Basics](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) section for details of how to create a project and obtain the required credentials (partner ID, partner secret, and app key). 2. **Create an Access Token** All requests sent to Mastercard Open Finance must include a `Finicity-App-Token` HTTP header. Use the following endpoint to generate a new access token: API Reference: `POST /aggregation/v2/partners/authentication` * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/partners/authentication' \ --header 'Content-Type: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --data-raw '{ "partnerId": "{{partnerId}}", "partnerSecret": "{{partnerSecret}}" }' ``` * Expected response: ```json { "token": "YBh22Sb9Es6e66Q7lWdt" } ``` See [Partner Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) for more details. 3. **Call the Transaction Data Enrichment endpoint** Use the following endpoint to send the transaction data you want to enrich. API Reference: `POST /data-enrichment/transactions` You will need to include your `Finicity-App-Token` created in the last step in the request header, along with the `Finicity-App-Key` created when you set up your Open Finance US project on Mastercard Developers. You can include up to 1000 transactions in the request payload. * Command: ```sh curl --location --request POST 'https://api.finicity.com/data-enrichment/transactions' \ --header 'Content-Type: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --header 'Accept: application/json' \ --data-raw '{ "transactions": [ ... ] }' ``` Note that the `externalCustomerId` and `externalAccountId` fields enable you to map the transactions back to your data. **Do not send Mastercard plaintext representations of customer or account IDs**. The representative IDs must be obfuscated through cryptographically strong hashing (we recommend using SHA-2 or SHA-3 methods). The response payload will consist of the same list of transactions, enhanced with additional details such as transaction category, merchant name, logo, website, and address. It will also provide information about any platform or payment processor involved in the transaction. ## Sequence Diagram {#sequence-diagram} Diagram data-enrichment-api ## API Example {#api-example} The following example shows how the transaction data provided in the API request is enhanced with additional information about the merchant, payment processor, platform or intermediary, and other information which Data Enrichment has been able to provide about each transaction. **Request** Provide the transaction data you have in the request body with the details you have of the transactions. You should include as much data as you can about the transactions (many of the request fields are optional for this reason---populate the optional fields where you can, omit them where you don't have the data). Warning: The `externalCustomerId` and `externalAccountId` fields are to allow you to map the transactions back to your data. **Do not send Mastercard plaintext representations of customer or account IDs**. The representative IDs must be obfuscated through cryptographically strong hashing (we recommend using SHA-2 or SHA-3 methods). For example, the following shows a single transaction as it might be presented in the request body (normally you would pass more transactions in the array): * Json ```json { "transactions": [ { "externalCustomerId": "1005061234", "externalAccountId": "1005061234", "accountType": "checking", "externalTransactionId": "MAC1005061233", "postedTimestamp": "2024-07-26T11:00:00Z", "transactionTimestamp": "2024-07-26T11:00:00Z", "description": "STARBUCKS STORE 06565 LITTLETON CO 07/26", "memo": "debit", "amount": -13.26, "transactionFee": 0, "type": "DEBIT", "directionIndicator": "Debit", "additionalDetails": { "key1": "value1" } }, { // further transaction data } ] } ``` **Response** The response will consist of the same array of transaction data, appended with additional information such as the transaction category, an `entities` array, and also potentially an `address` object. The `entities` data contains the additional information about the merchant, and potentially other entities involved in an individual transaction, such as a payment processor or other platform. Each entity is shown as belonging to a certain `category` in the response. Some categories (such as "Coffee Shops" or "Fast Food") are obvious and relate to the business which the merchant is involved with. Other categories relate to the role that an intermediary plays in the transaction, such as a Payment Processor or Platform. Some illustrative examples are shown in the table below. | Entity Category | Meaning | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | BNPL Provider | A financing service that allows consumers to purchase goods or services immediately and pay for them over time, often in interest-free installments. Examples include: Affirm, Afterpay, Klarna, Sezzle, Sunbit, Zip. | | Delivery Service | A platform that coordinates the purchase and delivery of goods from third-party merchants to consumers, such as DoorDash, Grubhub, Instacart, Postmates, Shipt, or Uber Eats. | | Digital Wallet | A financial application that allows users to store funds, send and receive money, make transactions, and track payment history on mobile or online applications. Examples include: Apple Cash, Apple Pay, Cash App, Venmo, Zelle. | | Financial Institution | The financial institution associated with the transaction. | | Marketplace | A platform that facilitates transactions between consumers and independent third-party sellers or service providers, such as Etsy, Airbnb, or Symphony Commerce. | | Payment Network | A system that facilitates the transfer of funds between issuing banks, acquiring banks, merchants, and consumers by routing payment transactions, such as Mastercard. | | Payment Processor | A payment processor manages the transaction process for an entity. Examples include: Adyen, PayPal, Square, Stripe, Toast. | | Platform | Financial, payment, and business enablement solutions, such as ADP, Shopify, or Wix. | For example, in the response below, the Starbucks transaction provided has been enhanced with business details for Starbucks, as well as the address of the outlet concerned. The transactions are also categorized, and for each transaction and entity a confidence score between 0 and 100 is provided, with 100 being a high degree of confidence. * Json ```json { "transactions": [ { "externalCustomerId": "1005061234", "externalAccountId": "1005061234", "accountType": "checking", "externalTransactionId": "MAC1005061233", "postedTimestamp": "2024-07-26T11:00:00Z", "transactionTimestamp": "2024-07-26T11:00:00Z", "description": "STARBUCKS STORE 06565 LITTLETON CO 07/26", "memo": "debit", "amount": -13.26, "transactionFee": 0, "transactionCategory": "Coffee Shops", "transactionCategoryScore": 45, "transactionCategoryGroup": "Groceries & Dining", "type": "DEBIT", "directionIndicator": "Debit", "entities": [ { "id": "MTc1ODA5NDU0MTYwNjM1OTA0MA== ", "name": "Starbucks", "category": "Coffee Shops", "group": "Cafe", "website": "https://starbucks.com", "logoUrl": "https://institution-branding-assets-cf.openbanking.mastercard.com/MTc1ODA5NDU0MTYwNjM1OTA0MA==/logo.svg", "entityStandardizationConfidenceScore": 91 } ], "address": { "line1": "10278 W", "line2": "Centennial Rd", "city": "Littleton", "state": "CO", "postalCode": "80127", "country": "US", "latitude": 39.567229, "longitude": -105.11126, "phoneNumber": "8017339340" }, "additionalDetails": { "key1": "value1" } }, { // further enhanced transaction data } ] } ``` --- # Connect Transfer Mobile SDKs source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md We provide the following SDKs to help you add Deposit Switch and Bill Pay Switch functionality to your mobile applications: * **Connect Transfer iOS SDK** * [GitHub](https://github.com/Mastercard/connect-transfer-ios-sdk) * [Installation and use](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#ios-installation-and-use) (on this page) * **Connect Transfer Android SDK** * [GitHub](https://github.com/Mastercard/connect-transfer-android-sdk) * [Installation and use](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#android-installation-and-use) (on this page) * **Connect Transfer React Native SDK** * [GitHub](https://github.com/Mastercard/connect-transfer-react-native-sdk) * [Installation and use](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#react-native-installation-and-use) (on this page) Warning: These SDKs are to help with the Connect Transfer functionality (for Deposit Switch and Bill Pay Switch) only. They do not support the regular Mastercard Data Connect flow, which requires the standard Data Connect SDK for [iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md), [Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md) or [React Native](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/react-native-sdk/index.md). The Connect Transfer SDKs require you to provide a generated Connect Transfer URL. These SDKs provide a new class which you will need to use, and generate events for which you need to provide listeners/delegate functions. ## iOS Installation and Use {#ios-installation-and-use} Note: You will need to use the following: * Xcode 16 or later * iOS 15.6 or later * Swift 5 * MacOS 14.5 or later Install the Connect Transfer iOS SDK in one of the following ways: * Swift Package Manager To install the Connect Transfer iOS SDK do the following steps in your project in Xcode. If you've previously used CocoaPods, remove them from the project with the `pod deintegrate` command. 1. Add a package by selecting **File → Add Packages...** in Xcode's menu bar. 2. Search for the Connect Transfer iOS SDK using the repo's URL: `https://github.com/Mastercard/connect-transfer-ios-sdk` 3. Next, set the **Dependency Rule** to be **Up to Next Major Version** to get the latest Data Connect SDK. 4. Then, click **Add Package**.
* CocoaPods (Deprecated) Include the following in your Podfile: ```html use_frameworks! pod 'MastercardOpenBankingConnectTransfer' ``` Warning: CocoaPods support is deprecated. We will continue publishing to the CocoaPods Trunk while we are able to, ideally through November 2026. However, deployments to Trunk have become unreliable, and we cannot guarantee that new versions will continue to be published there. We strongly recommend migrating to Swift Package Manager if you have not already. The timeline for CocoaPods becoming read-only is described here: * Manual Install Download the [Connect Transfer iOS SDK](https://github.com/Mastercard/connect-transfer-ios-sdk) from GitHub. Open your project in Xcode and drag the `ConnectTransfer.xcframework` folder into your project. In the build settings for the target folder, select the **General** tab. Scroll down to the **Frameworks, Libraries, and Embedded Content** section, and select `ConnectTransfer.xcframework`. Under the Embed column, select **Embed \& Sign** from the menu drop-down list if it is not already selected.
### Integrating Using UIKit {#integrating-using-uikit} Add `import ConnectTransfer` to all your source files that make calls to the Connect Transfer iOS SDK: ```swift import UIKit import ConnectTransfer ``` You will then need to do the following: * Generate a valid Connect Transfer URL. * Create an instance of the `ConnectTransferViewController` class and assign `ConnectTransferEventDelegate` to `ConnectTransferViewController`. Use the Connect Transfer URL in the load function. * Create callback/delegate functions for the `onInitializeConnectTransfer`, `onTermsAndConditionsAccepted`, `onLaunchTransferSwitch`, `onTransferEnd`, and `onUserEvent` events. These callback functions will have a `NSDictionary?` parameter that contains data about the event. * In the `onLoad` callback delegate method, present the `ConnectTransferViewController` using a `UINavigationController` with the `ConnectTransferViewcontroller` as its `rootViewController`. Tip: The `ConnectTransferViewController` automatically dismisses when the Connect Transfer flow is completed, cancelled early by the user, or when an error occurs. The following is an example of the delegate functions and their usage: * Swift ```swift class ViewController: UIViewController { @IBOutlet weak var activityIndicator: UIActivityIndicatorView! var transferViewController: ConnectTransferViewController! var connectNavController: UINavigationController! func launchConnectTransferAction(_ sender: Any) { if let connectTransferUrl = pdsURLInput.text { self.transferViewController = ConnectTransferViewController( connectTransferURLString: connectTransferUrl) self.transferViewController.delegate = self self.connectNavController = UINavigationController(rootViewController: self.transferViewController) if(UIDevice.current.userInterfaceIdiom == .phone){ self.connectNavController.modalPresentationStyle = .fullScreen } else { self.connectNavController.modalPresentationStyle = .automatic } self.present(self.connectNavController, animated: true) } } } extension ViewController: ConnectTransferEventDelegate { func onInitializeConnectTransfer(_ data: NSDictionary?) { print(data as Any) } func onTermsAndConditionsAccepted(_ data: NSDictionary?) { print(data as Any) } func onLaunchTransferSwitch(_ data: NSDictionary?) { print(data as Any) } func onTransferEnd(_ data: NSDictionary?) { print(data as Any) self.transferViewController = nil self.connectNavController = nil } func onUserEvent(_ data: NSDictionary?) { print(data as Any) } func onErrorEvent(_ data: NSDictionary?) { print(data as Any) } } ``` ### Integrating Using SwiftUI {#integrating-using-swiftui} Add preview page link on main page mentioned in this confluence - Task status update / SDK Event names and parameter names finalizations with Audit service integrations 1. Add `import ConnectTransfer` to all your source files that make calls to the Data Connect iOS SDK: ```swift import SwiftUI import ConnectTransfer ``` 2. Generate a valid Connect Transfer URL. 3. Create an instance of the `ConnectTransferView` with the Connect Transfer URL and assign `ConnectTransferViewEventDelegate` as `self` to get the events. 4. Create callback/delegate functions for the `onInitializeConnectTransfer`, `onTermsAndConditionsAccepted`, `onLaunchTransferSwitch`, `onTransferEnd`, and `onUserEvent` events. These callback functions will have an `NSDictionary?` parameter that contains data about the event. The following is an example of the delegate functions and their usage. * Swift ```swift struct ContentView: View { @State var connectTransferUrl: String = "" @State var presentConnectTransfer: Bool = false var body: some View { VStack { //.... Your View ....// } .fullScreenCover(isPresented: $presentConnectTransfer) { ConnectTransferView(connectTransferUrl: connectTransferUrl, delegate: self) } } } extension ContentView: ConnectTransferViewEventDelegate { func onInitializeConnectTransfer(_ data: NSDictionary?) { print(data as Any) } func onLaunchTransferSwitch(_ data: NSDictionary?) { print(data as Any) } func onErrorEvent(_ data: NSDictionary?) { print(data as Any) } func onTermsAndConditionsAccepted(_ data: NSDictionary?) { print(data as Any) } func onTransferEnd(_ data: NSDictionary?) { print(data as Any) } func onUserEvent(_ data: NSDictionary?) { print(data as Any) } } ``` ## Android Installation and Use {#android-installation-and-use} Note: You will need to use the following: * Android 7.0 (Nougat) or later * Android SDK level 24 or later Install the Data Connect Android SDK using Maven Central Modify your root-level Gradle file (`build.gradle`) as follows: ```groovy allprojects { repositories { { google() mavenCentral() } } ``` Modify your app-level Gradle file (`build.gradle`) as follows: ```groovy android { defaultConfig { minSdkVersion 24 // or greater } } dependencies { // ... implementation 'com.mastercard.openbanking.connect:connect-transfer-sdk:' } ``` The latest version of the Connect Transfer Android SDK can be found in [Maven Central](https://central.sonatype.com/artifact/com.mastercard.openbanking.connect/connect-transfer-sdk). The Connect Transfer Android SDK requires internet access to connect to Mastercard's servers, so you need to add internet permissions to the `AndroidManifest.xml` file: ```xml ``` The Connect Transfer Android SDK's main component is the `ConnectTransfer` class. This class contains a static `start` method, which runs an activity that connects with the `ConnectTransferEventListener`. To access the APIs in the SDK include the following imports: ```java import com.mastercard.openbanking.connect.transfer.ui.activity.ConnectTransfer; import com.mastercard.openbanking.connect.transfer.events.ConnectTransferEventListener; ``` The `ConnectTransfer.start()` method launches the activity, requiring: * A valid `Context`. * The Connect Transfer URL. * An instance of `ConnectTransferEventListener` to handle SDK events. * Java * Kotlin ```java ConnectTransfer.start(context, url, new ConnectTransferEventListener() { @Override public void onInitializeConnectTransfer(JSONObject data) { Log.d("ConnectTransfer", "onInitializeConnectTransfer: " + data.toString()); } @Override public void onTermsAndConditionsAccepted(JSONObject data) { Log.d("ConnectTransfer", "onTermsAndConditionsAccepted: " + data.toString()); } @Override public void onLaunchTransferSwitch(JSONObject data) { Log.d("ConnectTransfer", "onLaunchTransferSwitch: " + data.toString()); } @Override public void onTransferEnd(JSONObject data) { Log.d("ConnectTransfer", "onTransferEnd: " + data.toString()); } @Override public void onUserEvent(JSONObject data) { Log.d("ConnectTransfer", "onUserEvent: " + data.toString()); } @Override public void onErrorEvent(JSONObject data) { Log.d("ConnectTransfer", "onErrorEvent: " + data.toString()); } }); ``` ```kotlin ConnectTransfer.start(context, url, object : ConnectTransferEventListener { override fun onInitializeConnectTransfer(data: JSONObject) { Log.d("ConnectTransfer", "onInitializeConnectTransfer: ${data.toString()}") } override fun onTermsAndConditionsAccepted(data: JSONObject) { Log.d("ConnectTransfer", "onTermsAndConditionsAccepted: ${data.toString()}") } override fun onLaunchTransferSwitch(data: JSONObject) { Log.d("ConnectTransfer", "onLaunchTransferSwitch: ${data.toString()}") } override fun onTransferEnd(data: JSONObject) { Log.d("ConnectTransfer", "onTransferEnd: ${data.toString()}") } override fun onUserEvent(data: JSONObject) { Log.d("ConnectTransfer", "onUserEvent: ${data.toString()}") } override fun onErrorEvent(data: JSONObject) { Log.d("ConnectTransfer", "onErrorEvent: ${data.toString()}") } }) ``` Throughout Connect Transfer's flow, events about the state of the application are sent as `JSONObjects` to the `ConnectTransferEventListener` methods. The `onInitializeConnectTransfer`, `onTermsAndConditionsAccepted`, `onLaunchTransferSwitch`, `onTransferEnd`, and `onUserEvent` callback functions will have a `JSONObject` parameter that contains data about the event. ### Parameters {#parameters} | Parameter | Type | Description | |----------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `context` | Context | The context from which the function is called, typically an Activity or Fragment context. | | `connectTransferUrl` | String | The Connect Transfer URL required to initiate the Connect Transfer flow. | | `listener` | ConnectTransferEventListener | An instance of `ConnectTransferEventListener` to receive callbacks for various events, such as when the transfer is initialized, terms are accepted, and the transfer is completed. | * Java * Kotlin ```java public static void start(Context context, String connectTransferUrl, ConnectTransferEventListener listener) ``` ```kotlin fun start(context: Context,connectTransferUrl: String, listener: ConnectTransferEventListener) ``` ## React Native Installation and Use {#react-native-installation-and-use} Note: You will need to use the following: * Android: * Android 7.0 (Nougat) or later * Android SDK level 24 or later * iOS 15.1 or later ### Dependencies {#dependencies} The Connect Transfer React Native SDK has the following `peerDependencies`: * [react](https://www.npmjs.com/package/react) \>= 19.2.3 * [react-native](https://www.npmjs.com/package/react-native) \>= 0.84.1 * [@atomicfi/transact-react-native](https://www.npmjs.com/package/@atomicfi/transact-react-native) = 3.16.0 * [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler) = 2.31.1 * [react-native-inappbrowser-reborn](https://www.npmjs.com/package/react-native-inappbrowser-reborn) = 3.7.1 * [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated) = 4.3.0 (requires React Native New Architecture) * [react-native-safe-area-context](https://www.npmjs.com/package/react-native-safe-area-context) = 5.7.0 If your application does not include the packages mentioned above as dependencies, you can install them from: * [@atomicfi/transact-react-native](https://github.com/atomicfi/atomic-transact-react-native) * [react-native-gesture-handler](https://github.com/software-mansion/react-native-gesture-handler) * [react-native-inappbrowser-reborn](https://github.com/proyecto26/react-native-inappbrowser) * [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) * [react-native-safe-area-context](https://github.com/AppAndFlow/react-native-safe-area-context) The Connect Transfer React Native SDK has been tested with: * `@atomicfi/transact-react-native` version 3.16.0 * `react-native-gesture-handler` version 2.31.1 * `react-native-inappbrowser-reborn` version 3.7.1 * `react-native-reanimated` version 4.3.0 * `react-native-safe-area-context` version 5.7.0 ### Install Connect Transfer React Native SDK {#install-connect-transfer-react-native-sdk} The easiest way to install the SDK is to use npm or yarn: * `npm install connect-transfer-react-native-sdk` * `yarn add connect-transfer-react-native-sdk`
On iOS, CocoaPods needs this additional step: `$ cd ios && pod install && cd ..` Note: The Connect Transfer React Native SDK supports React Native 0.84 and later. Linking the package manually is not required as it uses [Autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). ### Update Android Application Settings {#update-android-application-settings} The Connect Transfer React Native SDK requires internet access to connect to Mastercard's servers, so you need to add internet permissions to the `AndroidManifest.xml`file: ```xml ``` ### Usage {#usage} #### Parameters {#parameters-1} | Parameter | Description | |-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `connectTransferUrl` *(required)* | The Connect Transfer URL required to initiate the Connect Transfer flow. | | `eventHandlers` *(required)* | `ConnectTransferEventListener` interface to receive callbacks for various events, such as when the transfer is initialized, terms are accepted, and the transfer flow is completed. | ```tsx import { ConnectTransfer, ConnectTransferEventHandler } from 'connect-transfer-react-native-sdk'; const TestComponent = () => { const eventHandlers: ConnectEventHandlers = { onInitializeConnectTransfer: (event: any) => {}, onTermsAndConditionsAccepted: (event: any) => {}, onLaunchTransferSwitch: (event: any) => {}, onUserEvent: (event: any) => {}, onTransferEnd: (event: any) => {}, onErrorEvent: (event: any) => {}, }; return ( ); }; ``` ## Connect Transfer SDK Events {#connect-transfer-sdk-events} The event listeners you implement when using the Connect Transfer SDKs are listed here. | Event | Description | |--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `onInitializeConnectTransfer` | Sent when the Connect Transfer SDK is initialized. | | `onTermsAndConditionsAccepted` | Sent when the user accepts the T\&Cs. | | `onLaunchTransferSwitch` | Sent when the user begins the Connect Transfer flow. | | `onUserEvent` | Sent when a user performs various actions during the Data onnect Transfer flow. User events provide insight into which screen or action in the flow the user is interacting with. | | `onTransferEnd` | Sent when the Connect Transfer flow ends. | | `onErrorEvent` | Sent if an error or exception occurs in the SDK. | ### Initialise Connect Transfer {#initialise-connect-transfer} The event message received by `onInitializeConnectTransfer()` will be in the following form in the case of Deposit Switch: { action = InitializeTransfer; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } In the case of Bill Pay Switch the event message will be as follows: { action = InitializeTransfer; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742453181603; ttl = 1742539581603; type = transferBillPaySwitch; } ### Terms and Conditions Accepted {#terms-and-conditions-accepted} The event message received by `onTermsAndConditionsAccepted()` will be in the following form in the case of Deposit Switch: { action = TermsAccepted; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } In the case of Bill Pay Switch the event message will be as follows: { action = TermsAccepted; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742453810773; ttl = 1742540210773; type = transferBillPaySwitch; } ### Initialize Deposit Switch {#initialize-deposit-switch} The event message received by `onLaunchTransferSwitch()` will be in the following form in the case of Deposit Switch: { action = InitializeDepositSwitch; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; product = deposit; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Initialize Bill Pay Switch {#initialize-bill-pay-switch} The event message received by `onLaunchTransferSwitch()` will be in the following form in the case of Bill Pay Switch: { action = InitializeBillPaySwitch; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; product = switch; sessionId = SESSION_ID; timestamp = 1742453181603; ttl = 1742539581603; type = transferBillPaySwitch; } ### End Connect Transfer {#end-connect-transfer} The event message received by `onTransferEnd()` will be in the following form in the case of Deposit Switch: { action = End; code = 200; company = { "_id" = COMPANY_ID; branding = { color = "#F96302"; logo = { url = "https://cdn-public.atomicfi.com/b2ad42c5-1348-4bfd-a19d-250583791e8c.png"; }; }; name = "The Home Depot"; }; customerId = CUSTOMER_ID; distributionAmount = 222; distributionType = fixed; identifier = CUSTOMER_ID; partnerId = PARTNER_ID; reason = complete; sessionId = SESSION_ID; taskId = 6789ef56fe459a9cc2fafc43; taskWorkflowId = 6789ef56fe459a9cc2fafc4a; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } In the case of Bill Pay Switch the event message will be as follows: { action = End; code = 200; company = { "_id" = COMPANY_ID; branding = { color = "#AF6408"; logo = { backgroundColor = "#FF9900"; url = "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png"; }; }; name = Amazon; }; customerId = CUSTOMER_ID; distributionType = total; identifier = CUSTOMER_ID; partnerId = PARTNER_ID; reason = complete; sessionId = SESSION_ID; taskId = 67dd1d819a29dd20f7fade82; taskWorkflowId = 67dd1d819a29dd20f7fade87; timestamp = 1742544226280; ttl = 1742630626280; type = transferBillPaySwitch; } ### ErrorEvent {#errorevent} This event message is sent to `onErrorEvent()` if an error or exception occurs in the SDK: { action = Error; reason = error; code = 400; } ## Connect Transfer User Events {#connect-transfer-user-events} The following user event messages can be received by your implementation of the `onUserEvent()` listener / callback. **Deposit Switch** * [SearchPayrollProvider](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#search-payroll-provider) * [SelectPayrollProvider](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#select-payroll-provider) * [ExternalLink](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#external-login-recovery) * [SubmitCredentials](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#submit-credentials) * [ChangeDefaultAllocation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#change-default-allocation) * [SubmitAllocation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#submit-allocation) * [TaskCompleted](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#task-completed) * [Unauthorized](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#unauthorized) * [SelectedCompanyThroughPayrollProvider](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#selected-company-through-payroll-provider) * [SelectedCompanyThroughFranchisePage](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#selected-company-through-franchise-page) * [ChangeDefaultAllocation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#change-default-allocation)
**Bill Pay Switch** * [ViewSearchPaylinkCompanies](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#view-search-paylink-companies) * [SearchPaylinkCompanies](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#search-paylink-companies) * [SelectPaylinkCompanies](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#select-paylink-companies) * [ChangedPayment](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#changed-payment) * [ViewedLoginPage](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#viewed-login-page) * [UserAuthenticated](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#user-authenticated) * [ReturnToCustomer](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#return-to-customer) * [OnAuthStatusUpdate](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#on-auth-status-update) * [OnTaskStatusUpdate](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#on-task-status-update) * [ZeroSearchResultInSearchCompany](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md#zero-search-result-in-search-company) ### Search Payroll Provider {#search-payroll-provider} This event message is sent to `onUserEvent()` when the user searches by company. For example: { action = SearchPayrollProvider; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; searchTerm = "home depot"; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Select Payroll Provider {#select-payroll-provider} This event message is sent to `onUserEvent()` when the user selects a provider from the Search by Company page. For example: { action = SelectPayrollProvider; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; payrollProvider = Workday; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### External Login Recovery {#external-login-recovery} This event message is sent to `onUserEvent()` when the user clicks the external login recovery link from the login help page. For example: { action = ExternalLink; buttonName = "Login Help "; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Submit Credentials {#submit-credentials} This event message is sent to `onUserEvent()` when the user clicks the button to start authentication. For example: { action = SubmitCredentials; customerId = CUSTOMER_ID; inputType = username; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Change Default Allocation {#change-default-allocation} This event message is sent to `onUserEvent()` when the user clicks Continue from the Percentage Deposit Amount page. For example: { action = ChangeDefaultAllocation; customerId = CUSTOMER_ID; depositAllocation = 222; depositOption = fixed; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Submit Allocation {#submit-allocation} This event message is sent to `onUserEvent()` when the user clicks Continue from the Fixed Deposit Amount page. For example: { action = SubmitAllocation; customerId = CUSTOMER_ID; depositAllocation = 222; depositOption = fixed; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Task Completed {#task-completed} This event message is sent to `onUserEvent()` when the user views the Task Completed page. For example: { action = TaskCompleted; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; status = completed; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Unauthorized {#unauthorized} This event message is sent to `onUserEvent()` when the user views the Unauthorized Access page. For example: { action = Unauthorized; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; code = 401; timestamp = 1737092848275; ttl = 1737179248275; type = transferDepositSwitch; } ### Selected Company Through Payroll Provider {#selected-company-through-payroll-provider} This event message is sent to `onUserEvent()` when the user selects a company from type-ahead search on the Configurable Connector Page. For example: { action = SelectedCompanyThroughPayrollProvider; company = "The Home Depot"; customerId = 7003366104; partnerId = 2445582169622; sessionId = 1c8f7d0bb336f41088de868b144223b5552c699a0ca4901ca3444938c6713643; timestamp = 1751550933856; ttl = 1751637333856; type = transferDepositSwitch; } ### Selected Company Through Franchise Page {#selected-company-through-franchise-page} This event message is sent to `onUserEvent()` when the user selects a company from the Search By Franchise page. For example: { action = SelectedCompanyThroughFranchisePage; company = "DCC LEE Enterprises"; customerId = 7003366104; partnerId = 2445582169622; sessionId = 1c8f7d0bb336f41088de868b144223b5552c699a0ca4901ca3444938c6713643; timestamp = 1751550933856; ttl = 1751637333856; type = transferDepositSwitch; } ### Change Default Allocation {#change-default-allocation-1} This event message is sent to `onUserEvent()` when the user selects total in Adjust Deposit Amount. For example: { action = ChangeDefaultAllocation; customerId = 7003366104; depositOption = total; partnerId = 2445582169622; sessionId = 1c8f7d0bb336f41088de868b144223b5552c699a0ca4901ca3444938c6713643; timestamp = 1751550933856; ttl = 1751637333856; type = transferDepositSwitch; } ### View Search Paylink Companies {#view-search-paylink-companies} This event message is sent to `onUserEvent()` when the user views the Search Paylink Companies page. For example: { action = ViewSearchPaylinkCompanies; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742464469200; ttl = 1742550869200; type = transferBillPaySwitch; } ### Search Paylink Companies {#search-paylink-companies} This event message is sent to `onUserEvent()` when the user searches the Paylink Companies. For example: { action = SearchPaylinkCompanies; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; searchTerm = Amazon; sessionId = SESSION_ID; timestamp = 1742464469200; ttl = 1742550869200; type = transferBillPaySwitch; } ### Select Paylink Companies {#select-paylink-companies} This event message is sent to `onUserEvent()` when the user selects a Paylink Company. For example: { action = SelectPaylinkCompanies; billPayProvider = Amazon; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742464469200; ttl = 1742550869200; type = transferBillPaySwitch; } ### Changed Payment {#changed-payment} This event message is sent to `onUserEvent()` when the user changes the Paylink Company payment method. For example: { action = ChangedPayment; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; paymentMethodType = Amazon; sessionId = SESSION_ID; timestamp = 1742464469200; ttl = 1742550869200; type = transferBillPaySwitch; } ### Viewed Login Page {#viewed-login-page} This event message is sent to `onUserEvent()` when the user continues after selecting a Paylink Company payment method to visit the login page of a Paylink Company. For example: { action = ViewedLoginPage; billPayProvider = Amazon; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742464469200; ttl = 1742550869200; type = transferBillPaySwitch; } ### User Authenticated {#user-authenticated} This event message is sent to `onUserEvent()` when the user continues after entering credentials for a Paylink Company. For example: { action = UserAuthenticated; billPayUserAuthenticated = Amazon; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742464469200; ttl = 1742550869200; type = transferBillPaySwitch; } ### Return to Customer {#return-to-customer} This event message is sent to `onUserEvent()` when the user presses the Return to Partner button after Paylink Company gets updated. For example: { action = ReturnToCustomer; billPayProvider = Amazon; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; sessionId = SESSION_ID; timestamp = 1742544226280; ttl = 1742630626280; type = transferBillPaySwitch; } ### On Auth Status Update {#on-auth-status-update} { action = onAuthStatusUpdate; customerId = 10000163269; oauthStatus = authenticated; partnerId = 2445582169622; sessionId = bdfae9c5f879e2df4b5a96ef5627a807183f58fa0d83bc5942d965747f3edaf8; timestamp = 1751295868445; transactAuthStatusUpdate = { company = { branding = { color = "#AF6408"; logo = { backgroundColor = "#FF9900"; url = "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png"; }; }; id = 65272c415d8a530008e972df; name = Amazon; }; status = authenticated; }; ttl = 1751382268445; type = transferBillPaySwitch; } ### On Task Status Update {#on-task-status-update} *a. Completed with Bank info* { action = onTaskStatusUpdate; customerId = 10000163301; partnerId = 2445582169622; sessionId = 2be6fb7b39ff0a840d9cc3c80fc2364d0c357ef53641deefd81f28b1badb9c65; switchId = 6862a9ef1507a50adc80f784; switchStatus = completed; timestamp = 1751296204483; transactSwitchStatusUpdate = { company = { branding = { color = "#00A1DC"; logo = { backgroundColor = "#00A1DC"; url = "https://cdn-public.atomicfi.com/e9939fb6-f56c-4bfb-af25-c876dab8c554.png"; }; }; id = 65298dfc2c00c70008a87746; name = "AT&T"; }; product = switch; status = completed; switchData = { paymentMethod = { accountNumberEndsWith = 1111; accountType = checking; bankIdentifier = 222222222; id = 6862a8cd7a34ea6407da644d; title = sam; type = bank; }; }; switchId = 6862a9ef1507a50adc80f784; }; ttl = 1751382604483; type = transferBillPaySwitch; } *b. Processing with Card info* { action = onTaskStatusUpdate; customerId = 10000163269; partnerId = 2445582169622; sessionId = bdfae9c5f879e2df4b5a96ef5627a807183f58fa0d83bc5942d965747f3edaf8; switchId = 6862a7d97a34ea6407da63fa; switchStatus = processing; timestamp = 1751295868445; transactSwitchStatusUpdate = { company = { branding = { color = "#AF6408"; logo = { backgroundColor = "#FF9900"; url = "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png"; }; }; id = 65272c415d8a530008e972df; name = Amazon; }; product = switch; status = processing; switchData = { paymentMethod = { brand = mastercard; endsWith = 4444; id = 6862a77d0d86f86215790d69; title = "Mastercard Elite Credit Card"; type = card; }; }; switchId = 6862a7d97a34ea6407da63fa; }; ttl = 1751382268445; type = transferBillPaySwitch; } *c. Failed* { action = onTaskStatusUpdate; customerId = 10000163301; partnerId = 2445582169622; sessionId = 2be6fb7b39ff0a840d9cc3c80fc2364d0c357ef53641deefd81f28b1badb9c65; switchFailReason = "subscription-inactive"; switchId = 6862ab887a34ea6407da6587; switchStatus = failed; timestamp = 1751296204483; transactSwitchStatusUpdate = { company = { branding = { color = "#AF6408"; logo = { backgroundColor = "#FF9900"; url = "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png"; }; }; id = 65272c415d8a530008e972df; name = Amazon; }; failReason = "subscription-inactive"; product = switch; status = failed; switchData = { paymentMethod = { brand = mastercard; endsWith = 4444; id = 6862a8cd7a34ea6407da644c; title = "Mastercard Elite Credit Card"; type = card; }; }; switchId = 6862ab887a34ea6407da6587; }; ttl = 1751382604483; type = transferBillPaySwitch; } ### Zero Search Result in Search Company {#zero-search-result-in-search-company} This event message is sent to `onUserEvent()` when the user searches for a Paylink company but does not find any relevant results. For example: { action = ZeroSearchResultInSearchCompany; customerId = CUSTOMER_ID; partnerId = PARTNER_ID; searchTerm = kjvbdfjhvbdskjfhbhj; sessionId = SESSION_ID; timestamp = 1775456541286; ttl = 1775542941286; type = transferBillPaySwitch; } ## Connect Transfer Error Codes {#connect-transfer-error-codes} | Error Code | Reason | |------------|----------------------------------| | 10039 | Unauthorized Data Connect Access | | 10010 | Field Validation Error | | 1440 | Timeout | | 401 | Invalid Link | | 500 | Atomic Error | | 100 | User Initiated Exit | | 400 | Exception or Error | --- # Verification of Assets (VOA) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voa/index.md The Verification of Assets (VOA) product provides insights into the customer's assets, balances, and transaction history via a verification report. Learn more about Mastercard's [Assets and Balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction. * **Assets Summary:** Provided as a balance summary across all accounts, and includes the current balance, the average 2-month daily balance, and the average 6-month daily balance. * **Data History:** Up to 12 months of transaction data based on availability from the FI. Length of history is customizable using `fromDate` and defaults to 2 months. * **Non-Sufficient Funds (NSF) Summary:** The presence of NSFs can be a key indicator of financial distress. ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **FI Certification Type:** Verification of Assets (VOA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 20 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. * **Supported Account Types:** Checking, Savings, Money Market, CD, Investment account types, Education Savings, Health Savings Account * **Supported Report Format:** JSON and PDF ### Use Cases {#use-cases} The VOA product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Consumer/Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate VOA Report {#generate-voa-report} To generate or refresh a VOA report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voa` The response includes the status of the report generation and a report ID. A webhook notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history provided in the report, up to 12 months maximum. By default, 2 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types connected by the customer. * If you don't want the Non-Sufficient Funds (NSF) information, set the `showNsf` parameter to `false`. ## Get VOA Report {#get-voa-report} Once the report generation is finished, you can then retrieve the report. See [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "u4hstnnak45g", "customerId": 1000006677, "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "consumerDetails": { "id": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "firstName": "John", "middleName": "Doe", "lastName": "Jane", "address": "123 Marple Street", "city": "Anytown", "state": "PA", "zip": "17101", "phone": "5551234567", "ssn": "1234", "email": "john.doe@example.com" }, "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "sfb7xp439w", "type": "voa", "status": "success", "createdDate": 1588350269, "constraints": { "accountIds": [ "1000535275", "1000535276" ], "fromDate": 1577986990, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true }, { "label": "loanType", "value": "car", "shown": false }, { "label": "vendorID", "value": "1613aa23", "shown": true }, { "label": "vendorName", "value": "PSC Finance", "shown": false } ], "showNsf": false }, "customerType": "active", "title": "Mastercard Open Banking Verification of Assets", "startDate": 1572625469, "endDate": 1588350269, "days": 180, "seasoned": false, "consolidatedAvailableBalance": 2345, "portfolioId": "dyr6qvqd2yhb-1-port", "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1588350276, "name": "Checking", "type": "checking", "availableBalance": 501.24, "aggregationStatusCode": 0, "balance": 501.24, "balanceDate": 1588350276, "averageMonthlyBalance": 501.02, "totNumberInsufficientFundsFeeDebitTxAccount": 0, "totNumberInsufficientFundsFeeDebitTxOver2MonthsAccount": 0, "totNumberDaysSinceMostRecentInsufficientFundsFeeDebitTxAccount": 120, "transactions": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "investmentTransactionType": "dividend", "normalizedPayee": "Finicity", "institutionTransactionId": "100000000", "category": "Paycheck", "bestRepresentation": "FINICITY INC PAYROLL" } ], "details": { "interestMarginBalance": -50000, "availableCashBalance": 1500, "vestedBalance": 300000, "currentLoanBalance": 0, "availableBalanceAmount": 1000, "marginBalance": 100, "currentBalance": 1000 }, "position": [ { "id": 637054, "currency": "USD", "symbol": "MCD", "securityName": "Common Stock", "units": 5, "marketValue": 1403.55, "currentPrice": 280.71, "securityType": "Stock" } ], "asset": { "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 } } }, "assets": { "type": "checking", "availableBalance": 1000, "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 } } ``` A human-readable PDF version of the report is available, which is great for underwriters or any other manual viewing of the report. How to read a VOA report: [VOA_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOA_Report_HTR.pdf) (1MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Verification of Assets and Income (VOAI) source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voai/index.md Verification of Assets and Income (VOAI) combines asset verification with deposit-based income analysis in a single report. It aggregates balances across accounts (with 2- and 6-month average balance views), identifies income streams from deposits (up to 24 months as available), and includes signals such as NSF presence. Learn more about Mastercard's Assets and Balances [Assets and Balances](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#assets-and-balances) and [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Assets Summary**: Provided as a balance summary across all accounts, and includes the current balance, the average 2-month daily balance, and the average 6-month daily balance * **Data History**: Length of history is customizable up to 24 months (defaults to 2 months) * **Deposit Income Streams**: Always provides the full 24 months of deposit history as available. Defaults to only include Moderate and High confidence income streams, but can be adjusted to include Low confidence streams as well. * **Non-Sufficient Funds (NSF) Summary:** The presence of NSFs can be a key indicator of financial distress ### Additional Product Information {#additional-product-information} * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance. * **FI Certification Type** : Verification of Income (VOI). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Refreshes**: This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. This report can also be refreshed as a Verification of Employment (VOE) Transactions. * **Supported Account Types**: Checking, Savings, Money Market, CD, Investment account types, Education Savings, Health Savings Account * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The VOAI product can be used for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md) * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate VOAI Report {#generate-voai-report} To generate or refresh a VOAI report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voaHistory` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report up to 24 months maximum. By default, 2 months of history will be aggregated as available. The income stream transactions will always show the full history up to 24 months as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * If the Non-Sufficient Funds (NSF) information is not desired set the `showNsf` parameter to `false`. * Customize the income streams returned in this report based on the confidence level. This input is called `incomeStreamConfidenceMinimum`. All income streams whose confidence level is greater than or equal to the number requested are provided. By default, the report will default to only include Moderate and High confidence income streams. Receiving all income streams may be desirable based on your implementation and use case. * High confidence levels correspond to `confidence` values of 75 and 100. * Moderate confidence levels correspond to a `confidence` value of 50. * Low confidence levels correspond to `confidence` values of 0 and 25. * Streams with confidence levels of Moderate or High are considered income. Streams with a confidence level of Low are considered non-income. Receiving all income streams may be desirable based on the use case. ## Get VOAI Report {#get-voai-report} Once the report is generated, retrieve the report using one of the Get Report endpoints: [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md). ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like when getting a VOA report. Examples are meant for reference only and may lag production changes. ```json { "id": "u4hstnyak45g", "portfolioId": "dyr6weqd2yhb-1-port", "customerType": "active", "customerId": 1000006677, "requestId": "sfb7x1we9w", "title": "Mastercard Open Banking Verification of Asset and Income - Transactions", "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "consumerDetails": { "id": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "firstName": "John", "middleName": "Doe", "lastName": "Jane", "address": "123 Marple Street", "city": "Anytown", "state": "PA", "zip": "17101", "phone": "5551234567", "ssn": "1234", "email": "john.doe@example.com" }, "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "constraints": { "accountIds": [ "1000535275", "1000535276" ], "fromDate": 1577986990, "incomeFromDate": 1577986990, "reportCustomFields": [ { "label": "loanID", "value": "12345", "shown": true }, { "label": "trackingID", "value": "5555", "shown": true }, { "label": "loanType", "value": "car", "shown": false }, { "label": "vendorID", "value": "1613aa23", "shown": true }, { "label": "vendorName", "value": "PSC Finance", "shown": false } ], "showNsf": false }, "type": "voaHistory", "status": "success", "createdDate": 1588350269, "startDate": 1572625469, "endDate": 1588350269, "days": 230, "seasoned": true, "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 6001966289, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1652114265, "name": "Checking", "type": "checking", "currency": "USD", "aggregationStatusCode": 0, "balance": 509.37, "balanceDate": 1652114265, "averageMonthlyBalance": 507.37, "totNumberInsufficientFundsFeeDebitTxAccount": 0, "totNumberDaysSinceMostRecentInsufficientFundsFeeDebitTxAccount": 0, "transactions": { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "investmentTransactionType": "dividend", "normalizedPayee": "Finicity", "institutionTransactionId": "100000000", "category": "Paycheck" }, "asset": { "type": "checking", "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 }, "details": { "interestMarginBalance": -50000, "availableCashBalance": 1500, "vestedBalance": 300000, "currentLoanBalance": 0, "availableBalanceAmount": 1000, "marginBalance": 100, "currentBalance": 1000 }, "position": [ { "id": 637054, "currency": "USD", "symbol": "MCD", "securityName": "Common Stock", "units": 5, "marketValue": 1403.55, "currentPrice": 280.71, "securityType": "Stock" } ], "incomeStreams": { "id": "dens28i3vsch-voah", "name": "none", "status": "ACTIVE", "estimateInclusion": "MODERATE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 14 }, "netMonthly": [ { "month": 1522562400, "net": 2004.77, "gross": 2400 } ], "netAnnual": 110475.7, "projectedNetAnnual": 0, "estimatedGrossAnnual": 0, "projectedGrossAnnual": 151609, "averageMonthlyIncomeNet": 9206.31, "averageMonthlyIncomeGross": 11300, "incomeStreamMonths": 18, "transactions": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "normalizedPayee": "Finicity", "institutionTransactionId": "100000000", "category": "Paycheck" } ] } } }, "assets": { "currentBalance": 1000, "twoMonthAverage": -1865.96, "sixMonthAverage": -7616.01, "beginningBalance": -17795.6 }, "consolidatedAvailableBalance": 2345, "income": [ { "confidenceType": "MODERATE", "netMonthly": [ { "month": 1522562400, "net": 2004.77, "gross": 2400 } ], "averageMonthlyIncomeNet": 9206.31, "averageMonthlyIncomeGross": 11300, "incomeEstimate": { "netAnnual": 1000.12, "projectedNetAnnual": 1500.23, "estimatedGrossAnnual": 2000.12, "projectedGrossAnnual": 2500.23 } } ] } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a VOAI report: [VOAI_Report_HTR_v7_2.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOAI_Report_HTR_v7_2.pdf) (1MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Verification of Income source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md Verification of Income (VOI) assesses an applicant's income using up to 24 months of a customer's bank transaction data. The service identifies active and historical income streams from deposits, assigns a confidence score and cadence to each stream, and provides summarized historical and projected income. Learn more about Mastercard's [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products. ## Key Product Features {#key-product-features} * **Account Owner:** See the listed account owner name and address to assist in fraud reduction * **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance * **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months * **Deposit Income Streams**: Defaults to include all income streams, but can be adjusted based on your preferences ### Additional Product Information {#additional-product-information} **FI Certification Type** : Verification of Income (VOI). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product. * **Report Generation Time (median):** Less than 25 seconds * **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. * **Supported Account Types**: Checking, Savings, Money Market * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The VOI product is suitable for the following use cases: * Auto * Credit Card Issuance * Credit Line Management * Customer / Portfolio Monitoring * Debt Collection * Personal Financial Management * Personal Lending * Servicing * Small and Medium Business * Tenant Screening ## Prerequisites {#prerequisites} This product is dependent on the customer linking their bank accounts via Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) * [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) * [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers) * [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) * [Generate a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-connect-flow) ## Generate VOI Report {#generate-voi-report} To generate or refresh a VOI report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voi` The response will include the status of the report generation and a report ID. A notification is sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)). #### Implementation Notes {#implementation-notes} * Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available. * Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types. * Customize the income streams returned in this report based on the confidence level. This input is called `incomeStreamConfidenceMinimum`. All income streams whose confidence level is greater than or equal to the number requested are provided. * High confidence levels correspond to `confidence` values of 75 and 100. * Moderate confidence levels correspond to a `confidence` value of 50. * Low confidence levels correspond to `confidence` values of 0 and 25. * Streams with confidence levels of Moderate or High are considered income. Streams with a confidence level of Low are considered non-income. Receiving all income streams may be desirable based on the use case. ## Get VOI Report {#get-voi-report} Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints. ## Example Report {#example-report} The Get Report APIs response contains different data depending on the type of report requested. The following example shows what a successful JSON response could look like for this report. Examples are meant for reference only and may lag production changes. ```json { "id": "u4hstnnaewetr-voi", "customerId": 1000006677, "consumerId": "ac39e237c7619a4ecf014b8d399c0696", "consumerSsn": "6789", "consumerDetails": { "id": "3f7ff2cf0ffb3d0cd59875e070c9b1d4", "firstName": "John", "middleName": "Doe", "lastName": "Jane", "address": "123 Marple Street", "city": "Anytown", "state": "PA", "zip": "17101", "phone": "5551234567", "ssn": "1234", "email": "john.doe@example.com" }, "disputeStatement": "Invalid data present.", "requesterName": "Decisioning API", "endUser": { "name": "ABC Apartments", "address": "123 Main St", "city": "Murray", "state": "UT", "zip": "84123", "phone": "555-2106", "email": "customerservice@example.com", "url": "example.com" }, "requestId": "sfb7xp4wer", "type": "voi", "status": "success", "createdDate": 1588350269, "customerType": "active", "title": "Mastercard Open Banking Verification of Income", "startDate": 1572625469, "endDate": 1588350269, "days": 200, "seasoned": true, "portfolioId": "dyr6qvqd2erw-1-port", "institutions": { "id": 101732, "name": "FinBank", "urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp", "accounts": { "id": 1000023996, "number": "1111", "ownerName": "JOHN DOE", "ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518", "ownerAsOfDate": 1577986990, "name": "Checking", "type": "checking", "aggregationStatusCode": 0, "incomeStreams": { "id": "dens28i3vsch-voi1", "name": "none", "status": "ACTIVE", "estimateInclusion": "MODERATE", "confidence": 70, "cadence": { "startDate": 1577986990, "stopDate": 1587986990, "days": 14 }, "netMonthly": [ { "month": 1522562400, "net": 2004.77, "gross": 2400 } ], "netAnnual": 110475.7, "projectedNetAnnual": 0, "estimatedGrossAnnual": 0, "projectedGrossAnnual": 151609, "averageMonthlyIncomeNet": 9206.31, "averageMonthlyIncomeGross": 11300, "incomeStreamMonths": 18, "transactions": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck" } ] }, "balance": 714.16, "averageMonthlyBalance": 720.75, "transactions": [], "availableBalance": 714.16, "currentBalance": 714.16, "beginningBalance": 714.77, "miscDeposits": [ { "id": 100000527471, "amount": 22.21, "postedDate": 1582286400, "description": "FINICITY INC PAYROLL", "memo": "Finicity amount credit", "institutionTransactionId": "100000000", "category": "Paycheck" } ] } }, "income": [ { "confidenceType": "MODERATE", "netMonthly": [ { "month": 1522562400, "net": 2004.77, "gross": 2400 } ], "averageMonthlyIncomeNet": 9206.31, "averageMonthlyIncomeGross": 11300, "incomeEstimate": { "netAnnual": 1000.12, "projectedNetAnnual": 1500.23, "estimatedGrossAnnual": 2000.12, "projectedGrossAnnual": 2500.23 } } ] } ``` A human-readable PDF version of the report is available which is great for underwriters or any other manual viewing of the report. How to read a VOI report: [VOI_Report_HTR_v7_2.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOI_Report_HTR_v7_2.pdf) (1MB) ## Testing {#testing} Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing). Ensure you use a test profile that contains supported account types such as [Profile_03](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#oauth-connection-profiles). --- # Mastercard Data Connect Route Events source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-route-events/index.md Route events capture the name of the screen that the user is interacting with as they navigate through the Mastercard Data Connect application. ## Landing {#landing} The first screen that the user lands on. ```JSON { "type": "route", "data": { "screen": "landing", "params": {} } } ``` #### Term Details {#term-details} The screen that displays the full documentation of the terms and conditions for users to read. ```JSON { "type": "route", "data": { "screen": "terms-details", "params": {} } } ``` ## Search {#search} The screen that displays the search input where a user can search for a bank. ```JSON { "type": "route", "data": { "screen": "search", "params": {} } } ``` ## Search Results {#search-results} The screen that displays a list of search results after a user has performed a query. ```JSON { "type": "route", "data": { "screen": "search", "params": { "query": "Moul" } } } ``` ## Sign In {#sign-in} The screen that displays once a user has signed in and it authorizing the sharing of their data. ```JSON { "type": "route", "data": { "screen": "sign-in", "params": { "institutionId": "101732" } } } ``` ## Login {#login} The screen that displays login inputs for username and password. ```JSON { "type": "route", "data": { "screen": "login", "params": { "institutionId": "101732" } } } ``` ## Loading {#loading} The screen that displays during loading operations. ```JSON { "type": "route", "data": { "screen": "loading", "params": { "institutionId": "101732" } } } ``` ## MFA {#mfa} The screen that displays during a multi factor authentication (MFA) challenge. ```JSON { "type": "route", "data": { "screen": "mfa", "params": { "institutionId": "101732" } } } ``` ## Select Accounts {#select-accounts} The screen that displays when a user is selecting which account information to share. ```JSON { "type": "route", "data": { "screen": "select-accounts", "params": { "institutionId": "101732" } } } ``` ## Review Accounts {#review-accounts} The screen that displays when a user is reviewing their selected accounts before submitting permission to share data from the accounts. ```JSON { "type": "route", "data": { "screen": "review-accounts", "params": {} } } ``` ## Done {#done} The screen that displays when a user has submitted the accounts they wish to share. ```JSON { "type": "route", "data": { "screen": "done", "params": {} } } ``` --- # Connect Web SDK Events source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-websdk-events/index.md ## Load {#load} | Event | Description | |-------|--------------------------------------------------------| | Load | When the Data Connect application starts (no payload). | ## Cancel {#cancel} | Event | Description | |--------|---------------------------------------------------------------------| | Cancel | The customer clicks Exit to cancel out of the Data Connect session. | ```JSON { "code": 100, "reason": "exit" } ``` ## Error / Timeout Events {#error--timeout-events} | Event | Description | |---------|--------------------------------------------------------------------------| | Timeout | The customer is forced to exit Data Connect after the session times out. | ```JSON { "code": 1440, "reason": "timeout" } ``` | Event | Description | |------------------|------------------------------------------------------------| | Unexpected error | The customer exits Data Connect after an unexpected error. | ```JSON { "code": 500, "reason": "error" } ``` ## Success {#success} | Event | Description | |---------|--------------------------------------------------------------------------------------| | Success | The customer successfully completes the Data Connect app and submits their accounts. | ```JSON { "reason": "complete", "code": 200, "reportData": [ { "portfolioId": "puukbn68n9kf-6-port", "type": "voi", "reportId": "ubjqshpkcsru-voi" }, { "portfolioId": "puukbn68n9kf-6-port", "type": "transactions", "reportId": "9d0kr7s5h4th-transactions" } ] } ``` --- # Mastercard Data Connect User Events source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md User events provide full visibility into the customer's actions while they're interacting with the Connect Data Connect Lite, or Data Connect Fix applications (apps). These events are compatible with analytics tools, allowing you to build web analytics dashboards to evaluate conversions, success rates, and error rates. ## AddAccounts {#addaccounts} | Name | Data Connect Support | Description | |-------------|---------------------------------------|-----------------------------------------------------| | AddAccounts | Data Connect Full / Data Connect Lite | Sent when a customer attempt to add their accounts. | This event is sent two times. The first event is sent when the customer attempts to add their bank accounts. The return includes: * A null value for the `success`, `accounts`, and `errorCode` fields. * The second event sent provides the details about the attempt. The customer successfully added their accounts if: * `accounts` = populated * `success` = true * `errorCode` = null The customer failed to add their accounts if: * `accounts` = null * `success` = false * `errorCode` = populated Note: If the first event is received, but the second event never arrives, then the customer ended the attempt to add accounts before Data Connect could successfully add the accounts. **Example response (first event):** ```JSON { "action": "AddAccounts", "institutionId": 123, "institutionLoginId": null, "accounts": null, "accountIds": [], "success": null, "errorCode": null } ``` **Example response (second event success):** ```JSON { "action": "AddAccounts", "institutionId": 123, "institutionLoginId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": null } ``` **Example response (second event fail):** ```JSON { "action": "AddAccounts", "institutionId": 123, "institutionLoginId": null, "accounts": null, "accountIds": [], "success": false, "errorCode": 500 } ``` ## CredentialedPayrollAccountConnection {#credentialedpayrollaccountconnection} | Name | Data Connect Support | Description | |--------------------------------------|----------------------|------------------------------------------------------------------------------| | CredentialedPayrollAccountConnection | Data Connect Full | Sent when the customer completes the add credentialed payroll accounts flow. | **Example response:** ```JSON { "action": "CredentialedPayrollAccountConnection", "institutionId": 123, "accounts": 1, "payrollAccountIds": [ "0193d0ab-9473-3e6d-58d2-039d6dafda45" ], "customerId": 12345, "success": true, "errorCode": null } ``` ## DisplayAlert {#displayalert} | Name | Data Connect Support | Description | |--------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | DisplayAlert | Data Connect Full / Data Connect Lite / Data Connect Fix | Sent when a customer receives an alert within a Data Connect session. The return includes: * The error code * The error code message | Note: These fields are only sent if an alert occurs for an FI: * `institutionId` * `institutionName` **Example response:** ```JSON { "action": "DisplayAlert", "alertType": "ERROR", "title": "Error", "message": "An error occurred.", "errorCode": 500, "data": { "details": "Invalid input" } } ``` ## End {#end} | Name | Data Connect Support | Description | |------|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | End | Data Connect Full / Data Connect Fix | Sent when a customer ends a Data Connect session. See [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md). | Note: Used to indicate how many customers have left a Data Connect session within your own product applications. **Example response:** ```JSON { "action": "End", "reason": "complete", "customerId": 12345, "partnerId": 67890, "timestamp": 1717132800000, "ttl": 1717140000000, "experience": "550e8400-e29b-41d4-a716-446655440000", "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4", "code": 200, "type": "full", "product": "aggregation" } ``` ## FixMfaAttempt {#fixmfaattempt} | Name | Data Connect Support | Description | |---------------|----------------------|-----------------------------------------------------------| | FixMfaAttempt | Data Connect Fix | Sent when a customer attempts to answer an MFA challenge. | This event is sent two times. The first event is sent when the customer attempts to answer an MFA challenge question while signing in to their bank. The return includes: * A null value for the `success`, `accounts`, and `errorCode` fields. A second event sent provides the details about the attempt. The customer successfully signed in to their accounts if: * `accounts` = populated * `success` = true * `errorCode` = null The customer encountered another MFA challenge if: * `accounts` = null * `success` = true * `errorCode` = null The customer failed to sign in to their accounts if: * `success` = false * `errorCode` = populated **Example response (first event):** ```JSON { "action": "FixMfaAttempt", "institutionId": 123, "institutionLoginId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": null, "errorCode": null } ``` **Example response (second event success):** ```JSON { "action": "FixMfaAttempt", "institutionId": 123, "institutionLoginId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": null } ``` **Example response (second event fail):** ```JSON { "action": "FixMfaAttempt", "institutionId": 123, "institutionLoginId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308","7079115309", "7079115310" ], "success": false, "errorCode": 185 } ``` ## FixSignInAttempt {#fixsigninattempt} | Name | Data Connect Support | Description | |------------------|----------------------|-------------------------------------------------------------------------------------------| | FixSignInAttempt | Data Connect Fix | Sent when a customer tries attempts to sign in when fixing a connection to their account. | This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes: * A null value for the `success`, `accounts`, and `errorCode` fields. A second event sent provides the details about the attempt. The customer successfully fixed the sign in for the account if: * `accounts` = populated * `success` = true * `errorCode` = null The customer encountered an MFA challenge if: * `accounts` = null * `success` = true * `errorCode` = null The customer failed to fix the sign in for their account if: * `success` = false * `errorCode` = populated Note: If the first event is received, but the second event never arrives, then the customer ended the attempt to fix their sign-in before Data Connect could successfully connect to the FI. **Example response (first event):** ```JSON { "action": "FixSignInAttempt", "institutionId": 456, "institutionLoginId": 789, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": null, "errorCode": null } ``` **Example response (second event success):** ```JSON { "action": "FixSignInAttempt", "institutionId": 456, "institutionLoginId": 789, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": null } ``` **Example response (second event fail):** ```JSON { "action": "FixSignInAttempt", "institutionId": 456, "institutionLoginId": 789, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": false, "errorCode": 103 } ``` ## Initialize {#initialize} | Name | Data Connect Support | Description | |------------|--------------------------------------|-------------------------------------------------| | Initialize | Data Connect Full / Data Connect Fix | Sent when a user starts a Data Connect session. | **Example response:** ```JSON { "action": "Initialize", "customerId": 12345, "partnerId": 67890, "timestamp": 1717132800000, "ttl": 1717140000000, "type": "full", "experience": "550e8400-e29b-41d4-a716-446655440000", "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4", "product": "aggregation", "borrowerType": "primary" } ``` ## LaunchOAuth {#launchoauth} | Name | Data Connect Support | Description | |-------------|----------------------|---------------------------------------------------------| | LaunchOAuth | Data Connect Full | Sent when the customer opens an OAuth window for an FI. | See [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md). Note: If no other OAuth events are received after this event, then the customer most likely closed the OAuth window. **Example response:** ```JSON { "action": "LaunchOAuth", "institutionId": 789, "success": true, "errorCode": null } ``` ## LaunchCredentialedPayrollPopUp {#launchcredentialedpayrollpopup} | Name | Data Connect Support | Description | |--------------------------------|----------------------|-----------------------------------------------------------------------------------------| | LaunchCredentialedPayrollPopUp | Data Connect Full | Sent when the customer launches the credentialed payroll account connection experience. | **Example response:** ```JSON { "action": "LaunchCredentialedPayrollPopUp", "institutionId": 123, "accounts": 1, "customerId": 1013916100, "success": true, "errorCode": null } ``` ## MfaAttempt {#mfaattempt} | Name | Data Connect Support | Description | |------------|----------------------------------------------------------|-------------------------------------------------------------| | MfaAttempt | Data Connect Full / Data Connect Lite / Data Connect Fix | Sent when the customer attempts to answer an MFA challenge. | This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes: * A null value for the `success`, `accounts`, and `errorCode` fields. A second event sent provides the details about the attempt. The customer successfully signed in to their accounts if: * `accounts` = populated * `success` = true * `errorCode` = null The customer encountered another MFA challenge if: * `accounts` = null * `success` = true * `errorCode` = null The customer failed to sign in to their accounts if: * accounts= null * success= false * errorCode= populated **Example response (first event):** ```JSON { "action": "MfaAttempt", "institutionId": 123, "accounts": null, "accountIds": [], "success": null, "errorCode": null } ``` **Example response (second event success):** ```JSON { "action": "MfaAttempt", "institutionId": 123, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": null } ``` **Example response (second event fail):** ```JSON { "action": "MfaAttempt", "institutionId": 123, "accounts": null, "accountIds": [], "success": null, "errorCode": 185 } ``` ## OAuthAddAccounts {#oauthaddaccounts} | Name | Data Connect Support | Description | |------------------|----------------------|--------------------------------------------------------------------| | OAuthAddAccounts | Data Connect Full | Sent when the customer attempts to add an OAuth account for an FI. | See [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md). **Example response:** ```JSON { "action": "OAuthAddAccounts", "institutionId": 123, "institutionLoginId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": null } ``` ## OAuthSignInAttempt {#oauthsigninattempt} | Name | Data Connect Support | Description | |--------------------|----------------------|---------------------------------------------------------------------------| | OAuthSignInAttempt | Data Connect Full | Sent when the customer attempts to sign in to an OAuth account for an FI. | See [OAuth Connections](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/oauth-connections/index.md). **Example response:** ```JSON { "action": "OAuthSignInAttempt", "institutionId": 456, "success": true, "errorCode": null } ``` ## RemoveAccounts {#removeaccounts} | Name | Data Connect Support | Description | |----------------|----------------------|------------------------------------------------------| | RemoveAccounts | Data Connect Full | Sent when a customer tries to remove their accounts. | This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes: * A null value for the `success`, `accounts`, and `errorCode` fields. A second event is sent with the results about the customer's attempt to remove their accounts: * Successfully removes accounts * Failed to remove accounts Note: If the first event is received, but the second event never arrives, then the customer ended the attempt to remove their accounts before Data Connect could successfully remove them. **Example response (first event):** ```JSON { "action": "RemoveAccounts", "institutionId": 123, "institutionLoginId": null, "accounts": null, "accountIds": [], "success": null, "errorCode": null } ``` **Example response (second event success):** ```JSON { "action": "RemoveAccounts", "institutionId": 123, "institutionLoginId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": null } ``` **Example response (second event fail):** ```JSON { "action": "RemoveAccounts", "institutionId": 123, "institutionLoginId": null, "accounts": null, "accountIds": [], "success": false, "errorCode": 500 } ``` ## SearchInstitutions {#searchinstitutions} | Name | Data Connect Support | Description | |--------------------|----------------------|--------------------------------------| | SearchInstitutions | Data Connect Full | Sent when a user searches for an FI. | The return includes: * The customer's query search words. * The number of matching search results. * The number of times the customer attempted to search. Note: The event is only sent if this condition occurs: at least three letters are typed and the customer pauses after typing for 300 ms. **Example response:** ```JSON { "action": "SearchInstitutions", "searchTerm": "Bank of America", "resultCount": 5 } ``` ## SelectInstitution {#selectinstitution} | Name | Data Connect Support | Description | |-------------------|----------------------|-----------------------------------------------------| | SelectInstitution | Data Connect Full | Sent when the customer selects an FI to sign in to. | The return includes: * The institution ID the customer selected. * If the FI is supported for the product. **Example response:** ```JSON { "action": "SelectInstitution", "institutionId": 123, "supported": true } ``` ## SessionTimeout {#sessiontimeout} | Name | Data Connect Support | Description | |----------------|----------------------------------------------------------|-----------------------------------------------------------------| | SessionTimeout | Data Connect Full / Data Connect Lite / Data Connect Fix | Sent when a customer's session has timed out due to inactivity. | **Example response:** ```JSON { "action": "SessionTimeout", "customerId": 12345, "partnerId": 67890, "timestamp": 1717132800000, "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4" } ``` ## SignInAttempt {#signinattempt} | Name | Data Connect Support | Description | |---------------|----------------------|---------------------------------------------------------| | SignInAttempt | Data Connect Full | Sent when a customer attempts to sign in to an account. | This event is sent two times. The first event is sent when the customer attempts to sign in to their bank. The return includes: * A null value for the `success`, `accounts`, and `errorCode` fields. A second event sent provides the details about the attempt. The customer successfully signed in to their accounts if: * `accounts` = populated * `success` = true * `errorCode` = null The customer encountered an MFA challenge if: * `accounts` = null * `success` = true * `errorCode` = null The customer failed to sign in to their accounts if: * `accounts` = null * `success` = false * `errorCode` = populated Note: If the first event is received, but the second event never arrives, then the customer ended the attempt before Data Connect successfully connected to the FI. **Example response (first event):** ```JSON { "action": "SignInAttempt", "institutionId": 456, "accounts": null, "accountIds": [], "success": null, "errorCode": null } ``` **Example response (second event success):** ```JSON { "action": "SignInAttempt", "institutionId": 456, "accounts": 5, "accountIds": [ "7079115306", "7079115307", "7079115308", "7079115309", "7079115310" ], "success": true, "errorCode": 0 } ``` **Example response (second event fail):** ```JSON { "action": "SignInAttempt", "institutionId": 456, "accounts": null, "accountIds": [], "success": false, "errorCode": 103 } ``` ## SubmitAccounts {#submitaccounts} | Name | Data Connect Support | Description | |----------------|----------------------|-----------------------------------------------------------| | SubmitAccounts | Data Connect Full | Sent when the customer attempts to submit their accounts. | The return includes: * The accounts This user event indicates: * The customer attempted to submit their accounts. * The account number if the customer's attempt to submit accounts was successful. **Example response:** ```JSON { "action": "SubmitAccounts", "customerId": 12345, "partnerId": 67890, "timestamp": 1717132800000, "ttl": 1717140000000, "type": "full", "experience": "550e8400-e29b-41d4-a716-446655440000", "sessionId": "7035b169d6f13306a240e7291bf7eab1a28010af26b57249ca1ccf5c49a30ce4", "product": "aggregation" } ``` --- # Data Connect Android SDK Migration Guide source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk-migration/index.md This migration guide provides step-by-step instructions for migrating from Data Connect Android SDK version 1.x to version 3.x and version 2.x to version 3.x. Follow the outlined changes carefully to ensure a smooth transition. We recommend using the latest version of the SDK whenever possible. ## Migrating From v1.x to v3.x {#migrating-from-v1x-to-v3x} To upgrade your app from the old v1.x Finicity Connect SDK to v3.x Mastercard Open Finance Data Connect SDK for Android, follow these steps. ### Step 1: Repository URL Update {#step-1-repository-url-update} Update your root-level `build.gradle` file as follows: **v1.x** buildscript { repositories { ... maven { url "https://finicity.jfrog.io/artifactory/finicity-connect-gradle-release-local" } } } **v3.x** buildscript { repositories { ... google() mavenCentral() } } ### Step 2: Library Dependency Update {#step-2-library-dependency-update} **v1.x** In your app-level build.gradle file, the implementation dependency for Data Connect SDK version 1.x.x used to be specified as: dependencies { // ... implementation 'com.finicity.connect:connect-sdk:1.x.x' } **v3.x** In version 3.x, update the implementation dependency in your app-level `build.gradle` file to the following (replace `` with the latest version of the SDK): dependencies { // ... implementation 'com.mastercard.openbanking.connect:connect-sdk:' } ### Step 3: Interface Method Name Update {#step-3-interface-method-name-update} **v1.x** In version 1.x, The `EventHandler` interface used to have the following method signatures: public interface EventHandler { void onLoaded(); void onDone(JSONObject doneEvent); void onCancel(); void onError(JSONObject errorEvent); void onRouteEvent(JSONObject routeEvent); void onUserEvent(JSONObject userEvent); } **v3.x** In version 3.x, update the method names in the EventHandler interface as follows: public interface EventHandler { void onLoad(); void onDone(JSONObject doneEvent); void onCancel(JSONObject cancelEvent); void onError(JSONObject errorEvent); void onRoute(JSONObject routeEvent); void onUser(JSONObject userEvent); } If you have previously used `EventListener` make sure you use the new `EventHandler` interface. ### Step 4: Additional Parameter in Connect.start {#step-4-additional-parameter-in-connectstart} In version 3.x, an optional `redirectUrl` parameter has been added to the `Connect.start` method to support app to app authentication. Include this parameter when initiating the app to app authentication. * Java * Kotlin ```java public static void start(Context context, String connectUrl, String redirectUrl, EventHandler eventHandler) ``` ```kotlin fun start(context: Context, connectUrl: String?, redirectUrl: String?, eventHandler: EventHandler?) ``` ## Migrating From v2.x to v3.x {#migrating-from-v2x-to-v3x} In version 3.x, an optional redirectUrl parameter has been added to the `Connect.start` method to support app to app authentication. If you have used the `deepLinkUrl` for this previously, update your code to use `redirectUrl` instead, as this supports both deep links and app links. We recommend using app links instead of deep links. **v2.x** * Java * Kotlin ```java public static void start(Context context, String connectUrl, String deepLinkUrl, EventHandler eventHandler) ``` ```kotlin fun start(context: Context, connectUrl: String?, deepLinkUrl: String?, eventHandler: EventHandler?) ``` **v3.x** * Java * Kotlin ```java public static void start(Context context, String connectUrl, String redirectUrl, EventHandler eventHandler) ``` ```kotlin fun start(context: Context, connectUrl: String?, redirectUrl: String?, eventHandler: EventHandler?) ``` --- # Using the Web SDK via CDN source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/web-sdk-cdn/index.md This page explains what need to know about implementing our Data Connect Web SDK in your web application using our CDN (Content Delivery Network, a system of distributed servers that delivers web content to users based on their geographic location). Using the CDN method means you don't need to install the SDK via a package manager (npm). The advantages of this are: * You will not need to manage dependencies and build processes as this will be done for you - the CDN will host up to date versions of the SDK with all the necessary dependencies. * No package manager access issues - in some cases your development processes may mean that access to npm is restricted which could slow down integration. * Reduced load times - your application won't need to install the SDK, which if done at run-time could affect the application performance. ## CDN URL Structure {#cdn-url-structure} Our CDN URLs follow this pattern: `https://cdn.openbanking.mastercard.com/js/connect-web-sdk@{version}/mastercard-connect-esm.min.js` We use semantic versioning (semver) for our releases. This means the {version} number follows a pattern of MAJOR.MINOR.PATCH (e.g., 2.1.0), where: * MAJOR: Changed when we make incompatible API changes * MINOR: Added when we introduce new features in a backward-compatible manner * PATCH: Increased when we make backward-compatible bug fixes Tip: CDN distribution of the SDK is only available from version 2.1.0 onwards. We recommend using 2.2.0 or later. ## Understanding Our Build Types {#understanding-our-build-types} When you look at our CDN, you'll notice different files with names like `mastercard-connect-esm.min.js` or `mastercard-connect-umd.min.js`. Each build type is minified (compressed) for faster loading. Let's understand what these different files are and when to use them. ### Our Build Types {#our-build-types} We provide three different types of builds, each serving a specific purpose: 1. ESM (ECMAScript Modules) 2. UMD (Universal Module Definition) 3. IIFE (Immediately Invoked Function Expression) #### How to Choose the Right Build {#how-to-choose-the-right-build} 1. For modern web applications: * Use the ESM build (`mastercard-connect-esm.min.js`) * Benefits: Better tree-shaking, clearer dependency management 2. For maximum compatibility: * Use the UMD build (`mastercard-connect-umd.min.js`) * Benefits: Works everywhere, fallback support 3. For direct browser usage without build tools: * Use the IIFE build (`mastercard-connect-iife.min.js`) * Benefits: Simplest to integrate, no module system needed ## Implementation Guides {#implementation-guides} Click the tabs below based on whichever build you want to implement/integrate in your app. ### What Is ESM? {#what-is-esm} ESM represents the modern approach to JavaScript modules. ESM lets you write code in separate files (modules) that can be combined when needed. Each module can contain variables, functions, or classes that can be shared with other parts of your application. ### Why Use ESM? {#why-use-esm} ESM offers several compelling advantages that make it the preferred choice for modern web development: 1. Native Browser Support - Modern browsers understand ESM naturally, without needing extra tools. 2. Better Code Organization - ESM lets you split your code into smaller, focused files. 3. Tree Shaking - This is a special feature where the browser only loads the code you actually use. Imagine packing for a trip; instead of taking your entire wardrobe, you only pack what you'll wear. This makes your application faster and more efficient. 4. Clear Dependencies ### Implementation {#implementation} The CDN URL for the ESM build is as follows: `https://cdn.openbanking.mastercard.com/js/connect-web-sdk@2.2.0/mastercard-connect-esm.min.js` You need to add the SDK to your HTML file. With ESM, there are two ways to do this: * Directly import the SDK from the CDN into your HTML * Create a separate JavaScript file which imports the SDK from the CDN, then import that file in your HTML #### Method 1: Using type="module" in HTML (Recommended) {#method-1-using-typemodule-in-html-recommended} ```html Your Application ``` #### Method 2: Using a Separate JavaScript File {#method-2-using-a-separate-javascript-file} First, create a file named `connect-integration.js`: ```JavaScript // connect-integration.js import { Connect } from 'https://cdn.openbanking.mastercard.com/js/connect-web-sdk@2.2.0/mastercard-connect-esm.min.js'; // Define your event handlers const eventHandlers = { onDone: (event) => { // This function is called when the connection is successful console.log('Connection successful!'); }, onCancel: (event) => { // This function is called if the user cancels the process console.log('User cancelled'); }, onError: (event) => { // This function is called if an error occurs console.log('Error occurred'); } }; // Function to launch Connect export function launchConnect() { Connect.launch( 'YOUR_CONNECT_URL', eventHandlers, { popup: true, popupOptions: { width: 520, // Width in pixels height: 720 // Height in pixels } } ); } ``` Then in your HTML, import your `connect-integration.js` file: ```html Your Application ``` ### What Is UMD? {#what-is-umd} Universal Module Definition (UMD) is like a universal translator for JavaScript modules. Think of it as a smart package that can automatically adapt to different environments - whether you're using it in a browser, with Node.js, or with module bundlers like Webpack. It's the "one size fits all" solution in the JavaScript world. ### Why Use UMD? {#why-use-umd} The UMD build is perfect when: * You're not sure about the environment where your code will run * You need maximum compatibility across different systems * You want one solution that works everywhere * You're working with older systems or mixed environments ### Implementation {#implementation} The CDN URL for the UMD build is as follows: `https://cdn.openbanking.mastercard.com/js/connect-web-sdk@2.2.0/mastercard-connect-umd.min.js` The following basic integration example shows how you can load the SDK in your code. ```html Connect SDK - UMD Example ``` ### What Is IIFE? {#what-is-iife} IIFE (Immediately Invoked Function Expression) is like a self-contained package that runs as soon as it's loaded. Think of it as a ready-to-use box that immediately puts everything you need into the global scope. It's the simplest way to add our SDK to a webpage with no extra setup required. ### Why Use IIFE? {#why-use-iife} The IIFE build is best when: * You want the simplest possible integration * You're not using any module bundlers or build tools * You want to add the SDK directly to an HTML page * You're working on a simple website without complex build processes #### Implementation {#implementation} The CDN URL for the IIFE build is as follows: `https://cdn.openbanking.mastercard.com/js/connect-web-sdk@2.2.0/mastercard-connect-iife.min.js` The following basic integration example shows how you can load the SDK in your code. ```html Connect SDK - IIFE Example ``` ## App to App Support {#app-to-app-support} We support App to App for all build types (ESM / UMD / IIFE) by default. In order to return control back to your application after a customer completes an FI's OAuth flow, you must provide a `redirectUrl` value. This URL is used to redirect back to your mobile app after completing an FI's OAuth flow, and should be a [Universal Link](https://developer.apple.com/ios/universal-links/) on iOS or an [App Link](https://developer.android.com/training/app-links#android-app-links) on Android). Here is an example of a universal link `redirectUrl` within your code: ```JavaScript connectOptions: ConnectOptions = { popup: true, popupOptions: { width: 600, height: 600, top: window.top.outerHeight / 2 + window.top.screenY - (600 / 2), left: window.top.outerWidth / 2 + window.top.screenX - (600 / 2) }, redirectUrl = "https://link.example.com"; }; Connect.launch(connectURL, connectEventHandlers, connectOptions ); ``` For more information on App to App integration for Data Connect Web-SDK, see [App to App Support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#app-to-app-support). ## Security Best Practices {#security-best-practices} * Always use HTTPS (our CDN URLs enforce this) * Implement proper error handling ## Getting Help {#getting-help} If you encounter any issues: 1. Check your browser's console for error messages 2. Verify your CDN URL is correct 3. Ensure all event handlers are properly implemented 4. Contact Mastercard support with: * Your SDK version number * Browser version * Error messages (if any) * Steps to reproduce the issue ## Updates and Maintenance {#updates-and-maintenance} To stay up to date: * Regularly check the npm registry for new versions * Read the changelog before upgrading * Test thoroughly in a development environment before updating production * Keep your CDN URL version number specific Tip: The SDK is designed to be straightforward to implement while handling complex security and communication features behind the scenes. Start with the basic implementation and add more features as needed. --- # Data Connect Web SDK Migration Guide source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/websdk-migration/index.md The `connect-web-sdk` package is a rebranded and updated version of the older `finicity/connect-web-sdk package`. It offers the same functionality for launching a Data Connect experience within your application, either through an iframe or a popup window. However, there are some notable differences in terms of naming conventions, code organization, and accessibility improvements. The `connect-web-sdk` differs from the old `finicity/connect-web-sdk package` in the following ways. 1. **Naming changes** The following naming changes have been introduced in `connect-web-sdk`: * The main class/object has been renamed from `FinicityConnect` to `Connect`. * The interface `FinicityConnectProps` has been renamed to `ConnectProps`. 2. **Dynamic styles addition** In `finicity/connect-web-sdk`, the styles for the iframe element were applied unconditionally. However, in `connect-web-sdk`, the styles are added dynamically if they don't already exist in the document. This change ensures that the styles are only applied when necessary, reducing potential conflicts with existing styles in your application. 3. **Accessibility improvements** The `connect-web-sdk` package introduces accessibility improvements by adding the following attributes to the iframe element: * `aria-label`: Set to "Launching Modal" * `title`: Set to "Launching Modal" These attributes improve the accessibility of the Data Connect experience for users who rely on assistive technologies. 4. **Optional redirect URL (required for app to app)** In `connect-web-sdk`, an optional `redirectUrl` property can be passed in the `ConnectOptions` interface. If provided, this URL will be included in the `PING_EVENT` data sent to the Data Connect application. This feature allows the Data Connect application to handle redirects more effectively, if needed. This is the URL to redirect back to your mobile app after completing an FI's OAuth flow (universal link on iOS, app link on Android). ## Upgrade Your Installation {#upgrade-your-installation} To upgrade your project from the `finicity/connect-web-sdk package` to `connect-web-sdk`, follow these steps (depending on whether you are using npm or yarn). * **Using npm** 1. Open your terminal or command prompt and navigate to your project directory. 2. Run the following command to remove the `@finicity/connect-web-sdk` package: npm uninstall @finicity/connect-web-sdk 3. Once the uninstall is complete, run the following command to install the `connect-web-sdk` package: npm install connect-web-sdk * **Using yarn** 1. Open your terminal or command prompt and navigate to your project directory. 2. Run the following command to remove the `@finicity/connect-web-sdk` package: yarn remove @finicity/connect-web-sdk 3. Once the removal is complete, run the following command to install the `connect-web-sdk` package: yarn add connect-web-sdk ## Update Your Code {#update-your-code} To migrate from `@finicity/connect-web-sdk` to `connect-web-sdk`, follow these steps: ### Step 1: Update Import Statement {#step-1-update-import-statement} Update the import statement in your client code to import from the new package name `connect-web-sdk` instead of `@finicity/connect-web-sdk`. // Before import { FinicityConnect } from '@finicity/connect-web-sdk'; // After import { Data Connect } from 'connect-web-sdk'; ### Step 2: Update Class/Object Reference {#step-2-update-classobject-reference} Replace all instances of FinicityConnect with Data Connect in your client code. // Before FinicityConnect.launch(...); // After Connect.launch(...); ### Step 3: Update Interface Names (If Used) {#step-3-update-interface-names-if-used} If you are using the `FinicityConnectProps` interface in your code, update your code to use `ConnectProps`. // Before const props: FinicityConnectProps = { ... }; // After const props: ConnectProps = { ... }; ### Step 4: Optional Redirect URL (If Needed) for App to App {#step-4-optional-redirect-url-if-needed-for-app-to-app} If you need to support the optional `redirectUrl` feature, update your client code to pass the `redirectUrl` property in the `ConnectOptions` object when launching the Data Connect SDK. This parameter is only required for App to App. This is the URL to redirect back to your mobile app after completing an FI's OAuth flow (universal link on iOS, app link on Android). Connect.launch(url, eventHandlers, { redirectUrl: 'https://example.com' }); ### Step 5: Accessibility Improvements {#step-5-accessibility-improvements} The connect-web-sdk package includes accessibility improvements by adding aria-label and title attributes to the iframe element. This change should not require any modifications to your client code, but it's worth noting as an improvement. ## Testing and Deployment {#testing-and-deployment} After completing the migration steps, we recommend that you test the integration with the `connect-web-sdk` package in a non-production environment. Once you have verified that everything is working as expected, you can proceed with deploying the changes to your production environment. --- # Secure Web Containers on iOS source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/websdk-ios/index.md The following section explains the steps to load your WebApp via the Data Connect WebSDK in your iOS Mobile App inside a secure web container (`SFSafariViewController`), and seamlessly transition control to your Mobile app using the same `SFSafariViewController` (which either loads the FI OAuth login page or launches the FI's Mobile app if it is installed on the user's device). This documentation also includes the Universal link Link/Deep Link configuration, as well as details on customizing the `WebViewClient` and secure web container (`SFSafariView Controller`) for enhanced control and handling of web interactions. These are the steps which occur when launching: * Launch your web app (integrated with the Data Connect WebSDK) URL address in a secure web container inside your mobile app. * Select an option or link which will open the Data Connect experience in same Secure Container (note this option should have redirectUrl code integrated already). * After successful FI OAuth account addition control returns to the your app. If the secure container case is launched, dismiss the secure container pop up using UISceneDelegate event of the universal link of the `redirectUrl`. The following scenarios need to be handled: * Scenario 1: FI's app is installed - the FI's app will launch and the OAuth session will occur in the FI's app. * Scenario 2: FI's app is not installed - the FI OAuth login page will open in an SFSafariViewController. Note: In order to support App to App authentication make sure you pass a suitable `redirectUrl` parameter via the Data Connect Web SDK. See [Data Connect Web SDK App to App support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#app-to-app-support). ## iOS Project Setup {#ios-project-setup} Make sure you have set up the following in your XCode project: * Under your Project target, select the **Signing and Capabilities** section: * Under this section click on **+Capability** to add a new capability, and select **Associated Domains** . Add your domain here. Under the **Signing** section, make sure you have set the development team correctly (or leave the team value as **None**). * This will create the entitlement file `YourProject.entitlements`: ```xml com.apple.developer.associated-domains applinks:*.example.com ``` For further details on app to app setup see [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#app-to-app-support). ## Loading Your Web URL Inside the Secure Web Container {#loading-your-web-url-inside-the-secure-web-container} Add a close function and code to launch a Safari View Controller in the existing `ViewController` to help open the FI OAuth login screen (or to open the FI app for OAuth Login): ```swift class ViewController : UIViewController, SFSafariViewControllerDelegate { var sfSafariViewController:SFSafariViewController? = nil override func viewDidAppear(_ animated: Bool) { launchSafari(url: "https://example.com") } func launchSafari(url:String){ let sfSafariViewController:SFSafariViewController = SFSafariViewController(url: URL.init(string: url)!) sfSafariViewController.delegate = self self.present(sfSafariViewController, animated: true, completion: nil) } func closeChildWebViewOrPopUp(){ if(self.presentedViewController != nil){ self.dismiss(animated: true) } } } ``` ## Closing the Secure Web Container {#closing-the-secure-web-container} Add the following code in the SceneDelegate class to handle the closure of the secure web container: ```swift // Scene delegate functions to close secure web container / webview pop up class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { self.closeSecureContainerPopUp(url: userActivity.webpageURL) } func closeSecureContainerPopUp(url:URL?) { var viewController:ViewController = ViewController() if((self.window?.rootViewController?.children.count)! > 0) { viewController = self.window?.rootViewController?.children.last as! ViewController } else if (self.window?.rootViewController is ViewController) { viewController = self.window?.rootViewController as! ViewController } DispatchQueue.main.asyncAfter(deadline: .now() + 0.005) { viewController.closeChildWebViewOrPopUp() } } } ``` --- # Using the Web SDK via Package Manager source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md You can either use npm to install the SDK, or download our starter pack and use the code provided (this will install what it needs). If you prefer not to download or install anything via package manager, you can reference it as needed [via our CDN](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/web-sdk-cdn/index.md) (using the ESM, UMD, or IIFE module formats). ## Installation Options {#installation-options} If you have an existing web project that uses a module compiler, such as Webpack or Babel, or you want to start from scratch, install the SDK direct from npm. If you haven't used a module compiler before, or want to get started with some helpful scaffolding code, download the Starter Code. Click the tabs below depending on your preference. The Data Connect Web SDK is available for installation via Node Package Manager (npm). You will need Node.js and npm in order to install the Web SDK. If you are not familiar with this process, see the [npm docs](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). 1. If you don't already use node modules in your project you can create a `package.json` file using the following terminal command: `npm init -y` 2. Then, to install the Open Finance Web SDK you can use the following commands: * For Open Finance Web SDK version 1.x: `npm install connect-web-sdk core-js --save` * For Open Finance Web SDK version 2.0 or higher: `npm install connect-web-sdk --save` Note: `core-js` is a peer dependency for the Open Bank Web SDK which you must install if you are installing a version of the Open Finance Web SDK which is earlier than 2.0.0. From version 2.0.0 on, `connect-web-sdk` no longer requires CoreJS as a peer dependency. This change might affect projects that relied on our package to provide CoreJS functionality. Since we are no longer supporting IE and older browsers, we have removed the `core-js` peer dependency and `core-js-pure` dependency. If you were installing CoreJS solely because of our package's peer dependency, you may now remove it from your project if it is not needed for other purposes. Once you have installed the SDK refer to the [example code](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#example-code) below to see how to launch a Data Connect instance. Tip: You can view the SDK source code on [Github](https://github.com/Mastercard/connect-web-sdk). The starter code demonstrates using the Web SDK in `TypeScript`, using [`webpack`](https://webpack.js.org/) as a module bundler. 1. Download the starter code: [openfinance-webpack.zip](https://static.developer.mastercard.com/content/open-finance-us/code/openfinance-webpack.zip) (64KB). 2. After downloading, install the node modules by navigating to the folder the code resides in and running the following command: `npm i`. Note that this will install `connect-web-sdk` and `core-js` so you don't have to run the command mentioned in the installation instructions when using this starter code. Once all the modules have downloaded, visit the `index.ts` page, which contains the code that uses the Data Connect Web SDK. All you need to do is add the URL that you received when [generating a Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) into the `connectURL` variable. ## SDK Parameters {#sdk-parameters} | Parameter | Description | |---------------------------------|----------------------------------------------------------------------------------| | connectURL (required) | The SDK loads the Data Connect URL provided to show the Data Connect experience. | | connectEventHandlers (required) | A class implementing the EventHandler interface. | | connectOptions (optional) | Additional options that can be passed. | ### Additional SDK Options {#additional-sdk-options} The SDK provides the following additional Data Connect options. You do not need to set any of these options unless you want to change some aspect of the default behavior. Note that some options are mutually exclusive. | Option | Description | |--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | overlay | Changes the overlay color where the Data Connect modal is displayed (only for iframe, defaults to rgba(0,0,0,0.8)). Not applicable if Data Connect is displayed in a popup. | | selector | CSS selector in which Data Connect should be embedded. Data Connect will expand to fill the container's dimensions, the element's position must not be static. Data Connect will be displayed in a modal by default. Not applicable if Data Connect is displayed in a popup. | | node | Element in which Data Connect should be embedded. Data Connect will expand to fill the container's dimensions, the element's position must not be static. Data Connect will be displayed in a modal by default. Not applicable if Data Connect is displayed in a popup. | | popup | Indicates if Data Connect should be displayed in a popup (defaults to false). | | popupOptions | If Data Connect is being displayed in a popup (see the popup boolean value above) then this option can be used to configure the popup's width/height and positioning (top/left). | | redirectUrl | The URL to redirect back to your mobile app after completing an FI's OAuth flow (universal link on iOS, app link on Android). This parameter is only required for App to App. **Note:** This parameter is not applicable for [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md). | Ensure that you do not also pass `redirectUri` in your generate URL call if you are using `redirectUrl` in WebSDK. ## Callback Events {#callback-events} The Web SDK provides the following events which you must provide handlers for: | Event | Description | |----------|-------------------------------------------------------------------------| | onDone | Sent when the user successfully completes the Data Connect application. | | onCancel | Sent when the user cancels the Data Connect application. | | onError | Sent when there is an error during the Data Connect application. | Optionally, you can also provide handlers for the following events: | Event | Description | |---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | onLoad | Sent when the Data Connect web page is loaded and ready to display. | | onRoute | Sent when the user navigates to a new route or screen in Data Connect, | | onUser | Sent when a user performs an action. User events provide visibility into what action a user could take within the Data Connect application. | | onUrl | Sent when a popup is triggered from the Data Connect application. This allows for custom handling of URL events, so that the partner application can handle the the popup. **Note:** This event is not used in the [Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#using-deposit-switch-with-the-data-connect-web-sdk) flow. | Warning: If you provide a handler for the onUrl event you must manage popups gracefully. The Data Connect SDK will not handle popups for you if this handler is provided. Only provide a handler for this event if you want to diverge from the default behavior. The onUrl handler accepts two parameters: 1. `type`: A string literal that can be either `OPEN` or `CLOSE`. * `OPEN`: Indicates that a URL should be opened. * `CLOSE`: Indicates that a URL event should be closed. 2. `url`: An optional string parameter that is only present when type is `OPEN`. This represents the URL to be opened. ## Example Code {#example-code} The following example code shows how to intercept various events and log them. Replace these minimal event handlers with code that is appropriate to your application. * TypeScript ```TypeScript import { Connect, ConnectEventHandlers, ConnectOptions, ConnectDoneEvent, ConnectCancelEvent, ConnectErrorEvent, ConnectRouteEvent } from 'connect-web-sdk'; const connectURL = 'replace with your generated connect url'; const connectEventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => { console.log(event); }, onCancel: (event: ConnectCancelEvent) => { console.log(event); }, onError: (event: ConnectErrorEvent) => { console.log(event); }, onRoute: (event: ConnectRouteEvent) => { console.log(event); }, onUser: (event: any) => { console.log(event); }, onLoad: () => { console.log('loaded'); }, }; const connectOptions: ConnectOptions = { overlay: 'rgba(199,201,199, 0.5)' }; Connect.launch( connectURL, connectEventHandlers, connectOptions ); ``` If you choose to handle the `onUrl` event, then you would also need to add something like the following to your `ConnectEventHandlers` implementation: * TypeScript ```TypeScript const connectEventHandlers: ConnectEventHandlers = { ..., onUrl: (type, url) => { if (type === 'OPEN' && url) { console.log(`Opening URL: ${url}`); // Custom logic to open a URL window.open(url, 'targetWindow', 'width=600,height=600'); } else if (type === 'CLOSE') { console.log('Closing..'); // Custom logic to close } } } ``` After adding your Data Connect URL you can create a build using the starter code with the following command `npm run build`. This will use webpack to create a JavaScript distribution bundle that the `index.html` file loads. Once the build is successful you can load the html file in the `dist` folder, using a local server, and you will see the Data Connect experience load. ### Using a Popup Window {#using-a-popup-window} As per the Data Connect options, you have the choice of starting the Data Connect experience in a popup window. When doing so you must supply the `redirectUri` in the [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) request body to supply a web page to redirect Data Connect users to when they are finished. Here is an example of a request to generate a Data Connect URL using the `redirectUri` parameter: ```JSON { "partnerId": "{{PARTNER_ID}}", "customerId": "{{CUSTOMER_ID}}", "consumerId": "{{CONSUMER_ID}}", "redirectUri": "https://example.com/redirectHandler", "webhook": "{{WEBHOOK}}", "webhookContentType": "application/json" } ``` With the returned Data Connect URL you can open the experience in a new window as follows: * TypeScript ```TypeScript import { Connect, ConnectEventHandlers, ConnectOptions, ConnectDoneEvent, ConnectCancelEvent, ConnectErrorEvent, ConnectRouteEvent } from 'connect-web-sdk'; const connectURL = 'https://connect2.finicity.com/?customerId=5025447962&origin=url&partnerId=2445583330983&redirectUri=https://example.com/redirectHandler&signature=2eb1bc83fd04b89d2ba0cfd9d2dcca572f76d59afc47f4654299cab1a230b34b×tamp=1653319208065&ttl=1653326408065&webhook=https://webhook.site/a787d273-87b8-452b-b05a-b52a92e5b266&webhookContentType=application/json'; const connectEventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => { console.log(event); }, onCancel: (event: ConnectCancelEvent) => { console.log(event); }, onError: (event: ConnectErrorEvent) => { console.log(event); }, onRoute: (event: ConnectRouteEvent) => { console.log(event); }, onUser: (event: any) => { console.log(event); }, onLoad: () => { console.log('loaded'); } }; const connectOptions: ConnectOptions = { popup: true, popupOptions: { width: 600, height: 600, top: window.top.outerHeight / 2 + window.top.screenY - (600 / 2), left: window.top.outerWidth / 2 + window.top.screenX - (600 / 2) } }; Connect.launch( connectURL, connectEventHandlers, connectOptions ); ``` When the user finishes with Data Connect, they will be redirected to the web page that was supplied in the `redirectUri` parameter. After the user completes Data Connect, report data is also returned through the `redirectUri` parameter specified: ```sh https://example.com/redirectHandler/?success=true&reasonCode=OK&id=quu1svkssc89&portfoliold=90w9y4t1eq5f-port&requestld=jhrsmfrkgf&consumerld=8c58c61c257e3e257a1d19d4d06f5e0b&consumerSsn=6789&type=voa&status=inProgress&source=Finicity%2520Connect&reportld=quu1svkssc89 ``` ## App to App Support {#app-to-app-support} To provide the best app to app authentication experience for your customers, you should send a universal link URL in the redirectUrl parameter when using Data Connect, Before installing the Data Connect Web SDK for use with app to app authentication, complete the following: * Create your domain's `redirectUrl` (iOS universal link, Android app link) * Configure your `redirectUrl` ### iOS: Create Your Domain's redirectUrl {#ios-create-your-domains-redirecturl} For information on how to create a [Universal Link](https://developer.apple.com/ios/universal-links/) to be used as the redirectUrl in your application, see Apple's Allowing apps and websites to [link to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) documentation. For information on how to configure your server, see [supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) in the Apple developer documentation. Tip: In order to provide the best app to app authentication customer experience, you should use a universal link for redirectUrl. We do not recommend using a deep link (custom URL scheme) for redirectUrl since deep links lack the security that Apple's Universal Links provide through the two-way association between your app and your website. A deep link will also trigger an alert on iOS devices which can add friction to the customer experience, requesting permission to redirect back to the Partner's app. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any other application that has registered the same URL scheme. ### Android: Create Your Domain's redirectUrl {#android-create-your-domains-redirecturl} For information on how to create an [App Link](https://developer.android.com/training/app-links#android-app-links) as redirectUrl in your application, see [Add Android App Links](https://developer.android.com/studio/write/app-link-indexing) in the Android developer documentation. Tip: In order to provide the best app to app authentication customer experience, you should use an app link for redirectUrl. We do not recommend using a deep link (custom URL scheme) for redirectUrl since deep links lack the security that Android App Links provide through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from Android. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any other application that has registered the same URL scheme. ### Configuring Your redirectUrl {#configuring-your-redirecturl} In order to return control back to your application after a customer completes an FI's OAuth flow, you must specify a redirectUrl value. This URL is used to redirect back to your mobile app after completing an FI's OAuth flow (this should be a universal link on iOS or an app link on Android). Here is an example of a universal link redirectUrl within your code: ```JavaScript connectOptions: ConnectOptions = { popup: true, popupOptions: { width: 600, height: 600, top: window.top.outerHeight / 2 + window.top.screenY - (600 / 2), left: window.top.outerWidth / 2 + window.top.screenX - (600 / 2) }, redirectUrl = "https://link.example.com"; }; Connect.launch(connectURL, connectEventHandlers, connectOptions ); ``` #### Cleanup {#cleanup} When the user of your application is finished with Data Connect you need to make sure to clean up the Data Connect instance by calling the `destroy` method. For example, if you have a ReactJS application you would call `destroy` in the `unmount` of your component. * TypeScript ```TypeScript Connect.destroy() ``` ## App to App Implementation {#app-to-app-implementation} The steps needed to implement app to app via the Web SDK depends whether you are using webviews or secure web containers (i.e., Safari View Controllers on iOS or Chrome Custom Tabs on Android). If your application uses WebViews, see the following sections for implementation details: * [App to app using webviews with the Web SDK on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/ios-webviews/index.md) * [App to app using webviews with the Web SDK on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/android-webviews/index.md) If your application uses secure web containers, see the following sections for implementation details: * [Using secure web containers with Web SDK on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/websdk-ios/index.md) * [Using secure web containers with Web SDK on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/websdk-android/index.md) --- # Using Webviews with the Web SDK on Android source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/android-webviews/index.md This page outlines steps to load your web app via the Data Connect WebSDK inside your mobile app using a WebView. It also explains how to seamlessly transition control to your mobile app using Chrome Custom Tabs for the FI's OAuth Login (if the FI banking app is not installed on the user's device), or redirecting to the FI app (if the FI app is present on the user's device). This documentation also includes App Link / deep link configuration, as well as details on customizing the WebViewClient and WebChromeClient for enhanced control and handling of web interactions. These are the steps which occur when launching: 1. Launch your web app (integrated with the Data Connect Web SDK) URL address in a webView inside your mobile app. 2. Select an option or link which will open the Data Connect experience in a WebView (this option should have the `redirectUrl` code integrated already). 3. After successful addition of the FI OAuth account, control is returned to your app's Activity via the AppLink/DeepLink specified as the `redirectUrl` and declared in the `AndroidManifest.xml` file. Tip: See also the [Secure Web Containers on Android](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/websdk-ios/index.md) page for more information on loading your URL inside a secure container (Chrome Custom Tab) and closing the secure container when complete. Secure containers are mandatory in some situations (for example, Chase does not allow their consent URL to be launched from within insecure webviews). The following scenarios need to be handled: * Scenario 1: FI's app is installed - The FI's app will launch and the OAuth session will occur in the FI's app. * Scenario 2: FI's app is not installed - The FI OAuth login page will open in Chrome Custom Tabs. Note: In order to support App to App authentication make sure you pass a suitable `redirectUrl` parameter via the Data Connect Web SDK. See [Data Connect Web SDK App to App support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#app-to-app-support). ## Project Setup {#project-setup} Modify your app-level Gradle file (build.gradle) as follows: ```groovy dependencies { // ... implementation 'androidx.browser:browser:' } ``` Find the latest version here - The Android App needs the `INTERNET` permission to access the WebView. Include this permission in the `AndroidManifest.xml` file. ```xml ..... ``` ## Layout Configuration {#layout-configuration} Include the `WebView` component in your layout XML file. ```xml ``` ## WebView Initialization {#webview-initialization} Create an Activity and create the following variables globally in your Activity. * Java * Kotlin ```java private WebView webView; private Context context; ``` ```kotlin private lateinit var webView : WebView private lateinit var context : Context ``` Initialize webView and context in your Activity's `onCreate` using the following code. Create the `ConnectWebViewClient` and `OauthWebChromeClient` class within the same Activity. Create the ConnectWebViewClient \& OauthWebChromeClient class within the same Activity. * Java * Kotlin ```java context = this; webView = findViewById(R.id.webView); webView.getSettings().setJavaScriptEnabled(true); webView.getSettings().setAllowFileAccess(true); webView.getSettings().setSupportMultipleWindows(true); webView.setWebViewClient(new ConnectWebViewClient()); webView.setWebChromeClient(new OauthWebChromeClient()); webView.loadUrl("Pass Your Data Connect WebSDK integrated URL"); ``` ```kotlin context = this webView = findViewById(R.id.webView) webView.settings.javaScriptEnabled = true webView.settings.allowFileAccess = true webView.settings.setSupportMultipleWindows(true) webView.webViewClient = ConnectWebViewClient() webView.webChromeClient = OauthWebChromeClient() webView.loadUrl("Pass Your Data Connect WebSDK integrated URL") ``` ## Loading Your Web URL Inside the WebView {#loading-your-web-url-inside-the-webview} The `ConnectWebViewClient` class extends `WebViewClient` and handles URL loading in the main WebView. Customize the `shouldOverrideUrlLoading` method within `ConnectWebViewClient` to control how URLs are loaded in the main WebView. * Java * Kotlin ```java // this class handles the loading of the urls inside the WebView. private class ConnectWebViewClient extends WebViewClient { @Override public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) { String url = request.getUrl().toString(); view.loadUrl(url); return true; } } ``` ```kotlin // this class handles the loading of the urls inside the WebView. private inner class ConnectWebViewClient : WebViewClient() { override fun shouldOverrideUrlLoading(view: WebView?, request: WebResourceRequest?): Boolean { val url = request?.url.toString() view?.loadUrl(url) return true } } ``` ## Handling OAuth Login URL and App to App {#handling-oauth-login-url-and-app-to-app} In order for App to App authentication to work, the `OauthWebChromeClient` class extends `WebChromeClient` and manages the creation of a new `WebView` for handling Financial Institution OAuth events. Customize the `shouldOverrideUrlLoading` method within `OauthWebChromeClient` to handle specific OAuth URLs and load them into the Chrome Custom Tabs. When the FI's OAuth process is completed by the user, the FI page in the Chrome Custom Tab will automatically close itself as per the Activity configured via AppLink or DeepLink which is mentioned in the `AndroidManifest.xml` file (see [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-link-support)). Control then returns to your app's Activity which runs Data Connect in the background with an add accounts screen. * Java * Kotlin ```java // this class handles the opening of the OAuth Login page OauthWebChromeClient private class OauthWebChromeClient extends WebChromeClient { @Override public boolean onCreateWindow(WebView view, boolean isDialog, boolean isUserGesture, Message resultMsg) { Webview mWebviewPop = new WebView(context); WebView.WebViewTransport transport = (WebView.WebViewTransport) resultMsg.obj; transport.setWebView(mWebviewPop); resultMsg.sendToTarget(); mWebviewPop.setWebViewClient(new WebViewClient() { @Override public boolean shouldOverrideUrlLoading( WebView view, WebResourceRequest webResourceRequest) { Uri oauthURL = webResourceRequest.getUrl(); // to open in CCT (Chrome Custom Tabs) CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder(); CustomTabsIntent intent = builder.build(); intent.launchUrl(context, oauthURL); return true; } }); return true; } } ``` ```kotlin // this class handles the opening of the OAuth Login page private inner class OauthWebChromeClient : WebChromeClient() { override fun onCreateWindow(view: WebView?, isDialog: Boolean, isUserGesture: Boolean, resultMsg: Message?): Boolean { val mWebviewPop = WebView(context) val transport = resultMsg?.obj as WebView.WebViewTransport transport.webView = mWebviewPop resultMsg.sendToTarget() mWebviewPop.webViewClient = object : WebViewClient() { override fun shouldOverrideUrlLoading(view: WebView?, webResourceRequest: WebResourceRequest?): Boolean { val oauthURL = webResourceRequest?.url // to open in CCT (Chrome Custom Tabs) val builder = CustomTabsIntent.Builder() val intent = builder.build() intent.launchUrl(context, oauthURL) return true } } return true } } ``` --- # Using Webviews with the Web SDK on iOS source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/webviews/ios-webviews/index.md This page outlines steps to load your WebApp via the Data Connect WebSDK in your iOS Mobile App inside a WebView. It also explains how to seamlessly transition control to your mobile app using a Safari View Controller for the FI's OAuth Login (if the FI banking app is not installed on the user's device), or redirecting to the FI app (if the FI app is present on the user's device). This documentation also includes Universal Link and deep link configuration, as well as details on customizing the WebViewClient and secure container (SFSafariViewController) for enhanced control and handling of web interactions. These are the steps which occur when launching: 1. Launch your web app (integrated with the Data Connect WebSDK) URL address in a secure web container inside your mobile app. 2. Select an option or link which will open the Data Connect experience in a WebView (this option should have the `redirectUrl` code integrated already). 3. After successful FI OAuth account addition, control returns to your app. Tip: See also the [Secure Web Containers on iOS](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/websdk-ios/index.md) page for more information on loading your URL inside a secure container (SFSafariViewController) and closing the secure container when complete. Secure containers are mandatory in some situations (for example, Chase does not allow their consent URL to be launched from within insecure webviews). The following scenarios need to be handled: * Scenario 1: FI's app is installed - the FI's app will launch and the OAuth session will occur in the FI's app. * Scenario 2: FI's app is not installed - the FI OAuth login page will open in an SFSafariViewController. Note: In order to support App to App authentication make sure you pass a suitable `redirectUrl` parameter via the Data Connect Web SDK. See [Data Connect Web SDK App to App support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#app-to-app-support). ## iOS Project Setup {#ios-project-setup} Make sure you have set up the following in your XCode project: * Under your Project target, select the **Signing and Capabilities** section: * Under this section click on **+Capability** to add a new capability, and select **Associated Domains** . Add your domain here. Under the **Signing** section, make sure you have set the development team correctly (or leave the team value as **None**). * This will create entitlement file `YourProject.entitlements`: ```xml com.apple.developer.associated-domains applinks:*.example.com ``` For further details on app to app setup see [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#app-to-app-support). ## WebView Initialization {#webview-initialization} In your view controller, create a `WKWebView` (named `webView `in the following example) to load your domain URL integrated with WebSDK in it. Then, add setup steps for the `WKWebView` in the `viewDidAppear` function within which `WKPreferences`, `WKWebViewConfiguration` and delegates (`uiDelegate` and `navigationDelegate`) are added to the view controller. ```swift import UIKit import WebKit import SafariServices import Foundation class ViewController: UIViewController, SFSafariViewControllerDelegate { var webView: WKWebView! override func viewDidAppear(_ animated: Bool) { setupWebView() loadUrlInWebView() } // Add this function if not added already in basic XCode project installation steps. func setupWebView() { let preferences = WKPreferences() preferences.javaScriptCanOpenWindowsAutomatically = true let configuration = WKWebViewConfiguration() configuration.preferences = preferences webView = WKWebView(frame: view.bounds, configuration: configuration) webView.autoresizingMask = [.flexibleWidth, .flexibleHeight] webView.uiDelegate = self webView.navigationDelegate = self view.addSubview(webView) } ``` ## Loading Your Web URL Inside the WebView {#loading-your-web-url-inside-the-webview} Call the `loadUrlInWebView()` function to load your domain URL in the webView. ```swift func loadUrlInWebView(){ if let url = URL(string: "https://example.com") { // Load domain URL where connect web sdk is already embeded let urlRequest = URLRequest(url: url) webView.load(urlRequest) } } ``` ## Handling OAuth Login URL and App to App {#handling-oauth-login-url-and-app-to-app} Add WKUIDelegate extension and mentioned code in it which listens FI OAuth Event in Data Connect and open Secure Container or FI App. Add SafariVIewController delegate to listen to manual closing of secure container. ```swift func closeChildWebViewOrPopUp(){ if(self.presentedViewController != nil){ self.dismiss(animated: true) } } } extension WKWebContainerViewController: SFSafariViewControllerDelegate { public func safariViewControllerDidFinish(_ controller: SFSafariViewController) { controller.dismiss(animated: true, completion: nil) self.closeChildWebViewOrPopUp() } } extension ViewController: WKUIDelegate { func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? { var popupWebView = WKWebView(frame: view.bounds, configuration: configuration) popupWebView!.autoresizingMask = [.flexibleWidth, .flexibleHeight] popupWebView!.navigationDelegate = self popupWebView!.uiDelegate = self popupWebView?.isHidden = true if let url = navigationAction.request.url { OpenUniversalLink.inAnyNativeWay(url: url) { success in // Creation of OpenUniversalLink class is in Step no. 3 if !success { let sfSafariViewController:SFSafariViewController = SFSafariViewController(url:url) sfSafariViewController.delegate = self self.present(sfSafariViewController, animated: true, completion: nil) } } } return popupWebView! } ``` Add the following code in SceneDelegate class for control to close already opened secure container. ```swift // Scene delegate functions to Close Secure Container / Webview Pop Up class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, continue userActivity: NSUserActivity){ self.closeSecureContainerPopUp(url: userActivity.webpageURL) } func closeSecureContainerPopUp(url:URL?) { var viewController:ViewController = ViewController() if ((self.window?.rootViewController?.children.count)! > 0) { viewController = self.window?.rootViewController?.children.last as! ViewController } else if (self.window?.rootViewController is ViewController) { viewController = self.window?.rootViewController as! ViewController } DispatchQueue.main.asyncAfter(deadline: .now() + 0.005) { viewController.closeChildWebViewOrPopUp() } } } ``` Create a new OpenUniversalLink class using the following code. This will open the FI app using the universal link if the app is present on the device. ```swift // Sample Open link class import Foundation import UIKit import SafariServices public class OpenUniversalLink { typealias completionHandler = (_ success:Bool) -> Void static func inAnyNativeWay(url: URL, dontPreferEmbeddedBrowser: Bool = false,completion: @escaping completionHandler) { // OPEN AS UNIVERSAL LINK IF EXISTS else : EMBEDDED or EXTERNAL if #available(iOS 10.0, *) { // Try to open with owner universal link app UIApplication.shared.open(url, options: [UIApplication.OpenExternalURLOptionsKey.universalLinksOnly : true]) { (success) in if !success { completion(false) } } } else { completion(false) } } } ``` --- # Secure Web Containers on Android source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/websdk-android/index.md The following section explains the steps to load your WebApp via the Data Connect WebSDK in your mobile App utilizing Chrome Custom Tabs. The FI's OAuth login page will use the same Chrome Custom Tabs when the FI's app is not installed on the user's device, or it will redirect to the FI's mobile app if the app is present on the user's mobile device. This documentation also includes the App Link/Deep Link configuration. These are the steps which occur when launching: * Launch your web app (integrated with the Data Connect WebSDK) URL address in a secure web container inside your mobile app. * Select an option or link which will open the Data Connect experience in same Secure Container (Note this option should have redirectUrl code integrated already) * After successful FI OAuth account addition control returns to the your app's Activity via AppLink/DeepLink of the `redirectUrl` declared in the `AndroidManifest.xml` file. The following scenarios need to be handled: * Scenario 1: FI's app is installed - the FI's app will launch and the OAuth session will occur in the FI's app. * Scenario 2: FI's app is not installed - the FI OAuth login page will open in Chrome Custom Tabs. Note: In order to support App to App authentication make sure you pass a suitable `redirectUrl` parameter via the Data Connect Web SDK. See [Data Connect Web SDK App to App support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#app-to-app-support) ## Android Project Setup {#android-project-setup} Modify your app-level Gradle file (build.gradle) as follows: ```groovy dependencies { // ... implementation 'androidx.browser:browser:' } ``` You can find the latest version of the library here: The Android App needs Internet permission to access the WebView. Include this permission in the `AndroidManifest.xml` file. ```xml ..... ``` ## Loading Your Web URL Inside the Secure Web Container {#loading-your-web-url-inside-the-secure-web-container} To open Chrome Custom Tabs, use the `openLinkInChromeCustomTabs` function. This function takes the String URL as a parameter and relies on a context instance typically representing your `Activity`. * Java * Kotlin ```java // pass your web url here for example "https://example.com" private void openLinkInChromeCustomTabs(String url) { try { // To open Chrome Custom Tabs CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder(); CustomTabsIntent customTabsIntent = builder.build(); customTabsIntent.intent.setPackage("com.android.chrome"); customTabsIntent.launchUrl(context, Uri.parse(url)); } catch (Exception exception) { Log.d("Connect", "Something went wrong, please check if Chrome Browser is installed"); } } ``` ```kotlin // pass your web url here for example "https://example.com" fun openLinkInChromeCustomTabs(url: String) { try { // To open Chrome Custom Tabs val builder = CustomTabsIntent.Builder() val customTabsIntent = builder.build() customTabsIntent.intent.setPackage("com.android.chrome") customTabsIntent.launchUrl(this, Uri.parse(url)) } catch (ignore:Exception) { Log.d("Connect","Something went wrong, please check if Chrome Browser is installed") } } ``` ## Handling OAuth Login URL and App to App {#handling-oauth-login-url-and-app-to-app} No extra code is required to handle OAuth events. Chrome Custom Tabs will handle the events automatically. It does this by opening another page in the same Chrome Custom Tab when the financial institution's app is not present, or it will open the app if present on the user's device. When the FI's OAuth process is completed by the user, the FI page in the Chrome Custom Tabs will automatically close itself as per the Activity configured via AppLink or DeepLink which is mentioned in the `AndroidManifest.xml` file (see [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-link-support)). Control then returns to your app's Activity which runs Data Connect in the background with an add accounts screen. Note: To maintain the Chrome Custom Tabs session when redirecting back to your app, it is necessary to create an additional Activity and listen for your AppLinks / DeepLinks in that Activity. This ensures a seamless user experience, preventing any disruption in the flow of the application and the closure of the Chrome Custom Tabs. Create an Activity named `ConnectRedirectActivity` and finish the Activity in its `onCreate` method to handle redirection back to the original Activity from which you initially launched the Chrome Custom Tabs. * Java * Kotlin ```java public class ConnectRedirectActivity extends Activity { @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); finish(); } } ``` ```kotlin class ConnectRedirectActivity : Activity() { override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) { super.onCreate(savedInstanceState, persistentState) finish() } } ``` Listen to your AppLinks / DeepLinks to the `ConnectRedirectActivity` in the `AndroidManifest.xml` file. ```xml ``` --- # Using the Data Connect Android SDK source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md The Mastercard Data Connect Android SDK is distributed as a compiled binary in Maven Central which allows you to easily integrate our SDK into your development projects. Maven central is Android's officially supported format for distributing binary libraries to multiple platforms and architectures in a single bundle. Note: Chase bank (JPMorgan Chase) has removed support for certain types of WebView traffic. This will impact the Chase OAuth flow if your SDK integration is not using the most recent version of our SDKs. The latest version will support secure web containers, e.g., Custom Tabs. For more information see the [Chase Developer documentation](https://developer.chase.com/products/aggregation-consent/guides/launching-the-oauth-flow-in-a-secure-container/) Warning: The Data Connect Android SDK does not support the Connect Transfer flow (for Deposit Switch and Bill Pay Switch). We provide a separate Connect Transfer Android SDK for this purpose. See the [Deposit Switch and Bill Pay Switch documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) for details. ## Compatibility {#compatibility} * Android 5.0 (Lollipop) or later, Android SDK level 21 or later: Warning: Support for deepLinkUrl parameters is deprecated from version 3.0.0 of the Data Connect Android SDK. Going forward you should use the `redirectUrl` parameter, which supports both universal and deep links. See our [Github changelog entry](https://github.com/Mastercard/connect-android-sdk/blob/main/CHANGELOG.md#300-august-10-2023). * Android 15 or later, Android SDK level 35 or later: Note: Starting from version 3.0.6, the Data Connect Android SDK will handle the redirect internally via a fallback mechanism if you do not specify a `redirectUrl` via the SDK or a `redirectUri` from [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) (this fixes a problem seen on Android 15+ where the OAuth popup might not dismiss automatically). See our [Github changelog entry](https://github.com/Mastercard/connect-android-sdk/blob/main/CHANGELOG.md#306-october-7-2025). For best results, we recommend you specify an app link via `redirectUrl` as described in the [App to App Support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-to-app-support) section or use a `redirectUri`. Otherwise, you should update your code to use version 3.0.6 or later of the SDK. ## Install the Data Connect Android SDK {#install-the-data-connect-android-sdk} Install the Data Connect Android SDK using Maven Central or manually from GitHub. ### Maven Central {#maven-central} Modify your root-level Gradle file (`build.gradle`) as follows: ```gradle allprojects { repositories { google() mavenCentral() } } ``` Modify your app-level Gradle file (`build.gradle`) as follows: ```html android { defaultConfig { minSdkVersion 21 // or greater } } dependencies { // ... implementation 'com.mastercard.openbanking.connect:connect-sdk:' } ``` **Note** : The latest version of the Data Connect Android SDK can be found in [Maven Central](https://central.sonatype.com/artifact/com.mastercard.openbanking.connect/connect-sdk/2.3.0/versions). ### Manual Install {#manual-install} Import the `connect-sdk` module into your project as follows: 1. Clone the Data Connect Android SDK from [Github](https://github.com/Mastercard/connect-android-sdk) 2. On your Android project, click on **File** \> **New** \> **Import Module** , select the folder you cloned the Data Connect Android SDK into, then click **Finish**. 3. Modify the [build.gradle](https://github.com/Mastercard/connect-android-sdk/blob/main/connect-sdk/build.gradle) file in the `connect-sdk` module to remove the following lines: apply from: "$project.rootDir/sonar.gradle" apply from: "${rootProject.projectDir}/sonatype-publish.gradle" 4. Clean and build the project. ## Update Android Application Settings {#update-android-application-settings} The Data Connect Android SDK requires internet access to connect with our servers, so you need to add internet permissions to the `AndroidManifest.xml` file: ```xml ``` ### App Link Support {#app-link-support} Add the following activity to the **AndroidManifest.xml** file. Tip: In order to have the best app to app authentication experience, you should use an App link URL in the `redirectUrl` parameter shown in example below. We do not recommend using deep links (custom URL schemes). ```html ``` ### Deep Link Support {#deep-link-support} Add the following activity to the **AndroidManifest.xml** file. ```html ``` Note: `{deep_link_app_name}` is case sensitive and should only use lower-case characters. ## Add Code to Start the Data Connect Android SDK {#add-code-to-start-the-data-connect-android-sdk} ### Data Connect Class {#data-connect-class} The Data Connect class contains a start method that when called, starts an activity with the supplied event listener. The SDK only allows a single instance of the Data Connect activity to run. If you start Data Connect while a Data Connect activity is already running, a RuntimeException is thrown. The Data Connect Android SDK's main component is the Data Connect class that contains a static start method, which runs an activity that connects with the EventHandler. To access the APIs in the SDK include the following imports: ```Java import com.mastercard.openbanking.connect.Connect; import com.mastercard.openbanking.connect.EventHandler; ``` **App Link Support** ```Java Connect.start(this, url, "https://example.com/connect", eventHandler); ``` **Deep Link Support** ```Java Connect.start(this, url, "{deep_link_app_name}://", eventHandler); ``` * Java * Kotlin ```java public static void start(Context context, String connectUrl, String redirectUrl, EventHandler eventHandler) ``` ```kotlin fun start(context: Context, connectUrl: String?, redirectUrl: String?, eventHandler: EventHandler?) ``` #### Parameters {#parameters} | Parameter | Description | |-------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | context (required) | The Android Context is referenced by Data Connect when an activity starts. | | connectUrl (required) | The SDK loads the Data Connect URL. | | redirectUrl (optional) | App Links URL to redirect back to your mobile app after completing an FI's OAuth flow. This parameter is only required for App to App. | | eventHandler (required) | A class implementing the EventHandler interface. | ### EventHandler Interface {#eventhandler-interface} Throughout Data Connect's flow, events about the state of the web application are sent as JSONObjects to the EventHandler methods. The onUserEvent handler will not return anything unless you're specifically targeting Data Connect. * Java * Kotlin ```java public interface EventHandler { void onLoaded(); void onDone(JSONObject doneEvent); void onCancel(JSONObject cancelEvent); void onError(JSONObject errorEvent); void onRouteEvent(JSONObject routeEvent); void onUserEvent(JSONObject userEvent); } ``` ```kotlin interface EventHandler { fun onLoaded() fun onDone(doneEvent: JSONObject?) fun onCancel(cancelEvent JSONObject?) fun onError(errorEvent: JSONObject?) fun onRouteEvent(routeEvent: JSONObject?) fun onUserEvent(userEvent: JSONObject?) } ``` #### Callback Events {#callback-events} See [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md#callback-events) for details on the events via their callback interface. **Note** : The onDone, onError, onRoute, and onUser callback functions will have a **JSONObject** parameter that contains data about the event. ## App to App Support {#app-to-app-support} To provide the best app to app authentication experience for your customers, you should send an App link in the `redirectUrl` parameter when using Data Connect. See [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) for more details, including [how to test](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#how-to-test-app-to-app-authentication). Before installing the Data Connect Android SDK for use with app to app authentication, complete the following: * Create your domain's `redirectUrl` (App link) * Configure your `redirectUrl` Note: Starting from version 3.0.6, the Data Connect Android SDK will handle the redirect internally via a fallback mechanism if you do not specify a `redirectUrl` via the SDK or a `redirectUri` from [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) (this fixes a problem seen on Android 15+ where the OAuth popup might not dismiss automatically). See our [Github changelog entry](https://github.com/Mastercard/connect-android-sdk/blob/main/CHANGELOG.md#306-october-7-2025). For best results, we recommend you specify an app link via `redirectUrl` as described in this section or use a `redirectUri`. Otherwise, you should update your code to use version 3.0.6 or later of the SDK. ### Create Your Domain's redirectUrl {#create-your-domains-redirecturl} For information on how to create a [App Links](https://developer.android.com/training/app-links#android-app-links) as redirectUrl in your application, see [adding Android App Links](https://developer.android.com/studio/write/app-link-indexing) for details. Tip: In order to provide the best app to app authentication customer experience, you should use an app link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security of App Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from Android. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any arbitrary application that has registered the same URL scheme. ### Configuring Your redirectUrl {#configuring-your-redirecturl} The `redirectUrl` URL is used to redirect back to your mobile app after completing the FI's OAuth flow (this should be an app link). Here is an example of an app link redirectUrl within your code: Connect.start(this, url, "https://example.com/mastercardConnect", eventHandler); For information on how to configure your server to support App Links see [Verify Android App Links](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc) in the Android documentation. ### Manually Stop a Data Connect Activity {#manually-stop-a-data-connect-activity} The Data Connect activity will automatically finish on done, cancel, and error events. You can manually finish a Data Connect activity by invoking: ```java Connect.finishCurrentActivity() ``` If there isn't a current Data Connect activity running, then the method will throw a RuntimeException. --- # Data Connect iOS SDK Migration Guide source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk-migration/index.md This migration guide provides step-by-step instructions for migrating from Data Connect iOS SDK version 1.x to version 3.x and version 2.x to version 3.x. Follow the outlined changes carefully to ensure a smooth transition. We recommend using the latest version of the SDK whenever possible. ## Migrating From v1.x to v3.x {#migrating-from-v1x-to-v3x} To upgrade your app from the old v1.x Finicity Connect SDK to v3.x Mastercard Open Finance Data Connect SDK for iOS, follow these steps. ### Step 1: Update Your Pod File {#step-1-update-your-pod-file} Update your pod file as follows: **v1.x** use_frameworks! pod 'FinicityConnect' **v3.x** use_frameworks! pod 'MastercardOpenBankingConnect' Warning: CocoaPods support is deprecated. We will continue publishing to the CocoaPods Trunk while we are able to, ideally through November 2026. However, deployments to Trunk have become unreliable, and we cannot guarantee that new versions will continue to be published there. We strongly recommend migrating to Swift Package Manager if you have not already. The timeline for CocoaPods becoming read-only is described here: See [Using the Data Connect iOS SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md) for details of how to install the latest SDK version via either Swift Package Manager or manually via GitHub. ### Step 2: Use the Connect Event Delegate {#step-2-use-the-connect-event-delegate} In version 1.x, call-back functions have the following method declarations: ```swift func openConnect(url: String) { let config = ConnectViewConfig ( connectUrl: url, loaded: self.connectLoaded, done: self.connectDone, cancel: self.connectCancelled, error: self.connectError, route: self.connectRoute, userEvent: self.connectUserEvent ) self.connectViewController = ConnectViewController() self.connectViewController.load(config: config) } func connectLoaded() { self.connectNavController = UINavigationController( rootViewController: self.connectViewController ) self.connectNavController.modalPresentationStyle = .automatic self.present(self.connectNavController, animated: false) } func connectDone(_ data: NSDictionary?) { // Data Connect flow completed } func connectCancelled() { // Data Connect flow exited prematurely } func connectError(_ data: NSDictionary?) { // Error encountered in Data Connect flow } func connectRoute(_data: NSDictionary?) { // Data Connect route changed } func connectUserEvent(_ data: NSDictionary?) { // Data Connect user event fired in response to user action } ``` In version 3.x, update the method names which are defined in the Data Connect event delegate as follows: ```swift ViewController: UIViewController, ConnectEventDelegate { @IBOutlet var activityIndicator: UIActivityIndicatorView! // Declaration of View and Navigation controllers var connectViewController: ConnectViewController! var connectNavController: UINavigationController! var connectUrl: String? // For regular Data Connect flow use below openConnect function func openConnect(connectUrl: String) { self.connectViewController = ConnectViewController() self.connectViewController.delegate = self self.connectViewController.load(connectUrl!) } // For App to App Data Connect flow use below openConnect function func openConnect(connectUrl: String) { self.connectViewController = ConnectViewController() self.connectViewController.delegate = self self.connectViewController.load(connectUrl,redirectUrl: "https://example.com/connect") } // Data Connect Delegate Methods func onCancel(_ data: NSDictionary?) { // Data Connect flow exited prematurely } func onDone(_ data: NSDictionary?) { // Data Connect flow completed } func onError(_ data: NSDictionary?) { // Error encountered in Data Connect flow } func onLoad() { // Data Connect User Experience loaded completely print("onLoad:") self.connectNavController = UINavigationController(rootViewController: self.connectViewController) if #available(iOS 13.0, *) { self.connectNavController.modalPresentationStyle = .automatic self.connectNavController.isModalInPresentation = true } else { // Fallback on earlier versions } self.connectNavController.presentationController?.delegate = self self.present(self.connectNavController, animated: true) } func onRoute(_ data: NSDictionary?) { // Data Connect route changed } func onUser(_ data: NSDictionary?) { // Data Connect user event fired in response to user action } func displayData(_ data: NSDictionary?) { print(data?.debugDescription ?? "no data in callback") } } ``` If you have previously used call-back functions make sure you use the new `ConnectEventDelegate`. ### Step 3: Loading the View Controller {#step-3-loading-the-view-controller} In version 1.x, `connectViewController` is loaded with the `ConnectViewConfig` object which contains `connectUrl` in parameter and call-back methods. **v1.x** ```swift func openConnect(url: String) { let config = ConnectViewConfig(connectUrl: url, loaded: self.connectLoaded, done: self.connectDone, cancel: self.connectCancelled, error: self.connectError, route: self.connectRoute, userEvent: self.connectUserEvent) self.connectViewController = ConnectViewController() self.connectViewController.load(config: config) } func connectLoaded() { self.connectNavController = UINavigationController(rootViewController: self.connectViewController) self.connectNavController.modalPresentationStyle = .automatic self.present(self.connectNavController, animated: false) } ``` In version 3.x, `connectViewController` is loaded with `connectUrl` and call back events are handled via delegate methods. The view controller which is loading `connectViewController` must conform to `ConnectEventDelegate`. **v3.x** ```swift ViewController: UIViewController, ConnectEventDelegate { // Declaration of View and Navigation controllers var connectViewController: ConnectViewController! var connectNavController: UINavigationController! var connectUrl: String? // For regular Data Connect flow use below openConnect function func openConnect(connectUrl: String) { self.connectViewController = ConnectViewController() self.connectViewController.delegate = self self.connectViewController.load(connectUrl!) } // For App to App Data Connect flow use below openConnect function func openConnect(connectUrl: String) { self.connectViewController = ConnectViewController() self.connectViewController.delegate = self self.connectViewController.load(connectUrl,redirectUrl: "https://example.com/connect") } } ``` ## Migrating From v2.x to v3.x {#migrating-from-v2x-to-v3x} In version 3.x.x, an optional `redirectUrl` parameter has been added to the `connectViewController.load` method to support app to app authentication. If you have used the `deepLinkUrl` for this previously, update your code to use `redirectUrl` instead, as this supports both deep links and app links. We recommend using app links instead of deep links. --- # Using the Data Connect iOS SDK source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md The Data Connect iOS SDK is distributed as a compiled binary in XCFramework format which allows you to easily integrate our SDK into your development projects. Our Data Connect iOS SDK has full Bitcode support so that you don't have to disable it in your applications when integrating with the SDK. The XCFramework format is Apple's officially supported format for distributing binary libraries to multiple platforms and architectures in a single bundle. Note: Chase bank (JPMorgan Chase) has removed support for certain types of WebView traffic. This will impact the Chase OAuth flow if your SDK integration is not using the most recent version of our Data Connect iOS SDK. The latest version will support secure web containers, for example, `SFSafariviewcontroller`. For more information, see the [Chase Developer documentation](https://developer.chase.com/products/aggregation-consent/guides/launching-the-oauth-flow-in-a-secure-container/) Warning: The Data Connect iOS SDK does not support the Connect Transfer flow (for Deposit Switch and Bill Pay Switch). We provide a separate Connect Transfer iOS SDK for this purpose. See the [Deposit Switch and Bill Pay Switch documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) for details. ## Compatibility {#compatibility} * Supports iOS 15.6 or later. Warning: Support for deepLinkUrl parameters is deprecated from version 3.0.0 of the Data Connect iOS SDK. Going forward you should use the `redirectUrl` parameter, which supports both universal and deep links. For more information [see our Github documentation](https://github.com/Mastercard/connect-ios-sdk/blob/main/README.md) ## Install the Data Connect iOS SDK {#install-the-data-connect-ios-sdk} Install the Data Connect iOS SDK using the Swift Package Manager, CocoaPods, or by manually dragging` Connect.xcframework` into your Xcode project. Tip: If you are currently using the legacy iOS framework, you must [migrate to XCFramework](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#migrate-from-framework-to-xcframework) before installing the Data Connect iOS SDK. ### Swift Package Manager {#swift-package-manager} To install the Data Connect iOS SDK do the following steps in your project in Xcode. If you've previously used CocoaPods, remove them from the project with the `pod deintegrate` command. 1. Add a package by selecting **File → Add Packages...** in Xcode's menu bar. 2. Search for the Data Connect iOS SDK using the repo's URL: `https://github.com/Mastercard/connect-ios-sdk` 3. Next, set the **Dependency Rule** to be **Up to Next Major Version** to get the latest Data Connect SDK. 4. Then, click **Add Package**. ### CocoaPods (Deprecated) {#cocoapods-deprecated} To install the Data Connect iOS SDK include the following in your Podfile. ```html use_frameworks! pod 'MastercardOpenBankingConnect' ``` Warning: CocoaPods support is deprecated. We will continue publishing to the CocoaPods Trunk while we are able to, ideally through November 2026. However, deployments to Trunk have become unreliable, and we cannot guarantee that new versions will continue to be published there. We strongly recommend migrating to Swift Package Manager if you have not already. The timeline for CocoaPods becoming read-only is described here: ### Manual Install {#manual-install} 1. Download the Data Connect iOS SDK from [Github](https://github.com/Mastercard/connect-ios-sdk). 2. Open your project in Xcode and drag the Connect.xcframework folder into your project. 3. In the build settings for the target folder, select the General tab. 4. Scroll down to the Frameworks, Libraries, and Embedded Content section, and select Connect.xcframework. 5. Under the Embed column, select Embed \& Sign from the menu drop-down list if it is not already selected. ## Integrating Using UIKit {#integrating-using-uikit} 1. Add `import Connect` to all your source files that make calls to the Data Connect iOS SDK: ```swift import UIKit import Connect ``` 2. Generate a valid URL (see [Generate Data Connect URL APIs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md)). 3. Create an instance of the `ConnectViewController` class and assign `ConnectEventDelegate` to `ConnectViewController`. Use the Data Connect URL in the load function (see `connectUrl` in the following code example). 4. Create callback/delegate functions for `onLoad`, `onDone`, `onCancel`, `onError`, `onRoute`, and `onUser` events. These callback functions will have a `NSDictionary?` parameter that contains data about the event. For more information see the list of [Data Connect callback events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md#callback-events). 5. In the `onLoad` callback delegate method, present the `ConnectViewController` using a `UINavigationController` with the `ConnectViewcontroller` as its `rootViewController`. **Note** : The `ConnectViewController` automatically dismisses when the Data Connect flow is completed, cancelled early by the user, or when an error occurs. ### Example {#example} The following is an example of the delegate functions and their usage. ```swift ViewController: UIViewController, ConnectEventDelegate { @IBOutlet var activityIndicator: UIActivityIndicatorView! // Declaration of View and Navigation controllers var connectViewController: ConnectViewController! var connectNavController: UINavigationController! var connectUrl: String? // For regular Data Connect flow use below openConnect function func openConnect(connectUrl: String) { self.connectViewController = ConnectViewController() self.connectViewController.delegate = self self.connectViewController.load(connectUrl!) } // For App to App Data Connect flow use below openConnect function func openConnect(connectUrl: String) { self.connectViewController = ConnectViewController() self.connectViewController.delegate = self self.connectViewController.load(connectUrl,redirectUrl: "https://example.com/connect") } // MastercardOpenBankingConnect Delegate Methods func onCancel(_ data: NSDictionary?) { print("onCancel:") displayData(data) self.activityIndicator.stopAnimating() // Needed to trigger deallocation of ConnectViewController self.connectViewController = nil self.connectNavController = nil } func onDone(_ data: NSDictionary?) { print("onDone:") displayData(data) self.activityIndicator.stopAnimating() // Needed to trigger deallocation of ConnectViewController self.connectViewController = nil self.connectNavController = nil } func onError(_ data: NSDictionary?) { print("onError:") displayData(data) self.activityIndicator.stopAnimating() // Needed to trigger deallocation of ConnectViewController self.connectViewController = nil self.connectNavController = nil } func onLoad() { print("onLoad:") self.connectNavController = UINavigationController(rootViewController: self.connectViewController) if #available(iOS 13.0, *) { self.connectNavController.modalPresentationStyle = .automatic self.connectNavController.isModalInPresentation = true } else { // Fallback on earlier versions } self.connectNavController.presentationController?.delegate = self self.present(self.connectNavController, animated: true) } func onRoute(_ data: NSDictionary?) { print("onRoute:") displayData(data) } func onUser(_ data: NSDictionary?) { print("onUser:") displayData(data) } func displayData(_ data: NSDictionary?) { print(data?.debugDescription ?? "no data in callback") } ``` ## Integrating Using SwiftUI {#integrating-using-swiftui} 1. Add `import Connect` to all your source files that make calls to the Data Connect iOS SDK: ```swift import SwiftUI import Connect ``` 2. Generate a valid URL (see [Generate Data Connect URL APIs](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md)). 3. Create an instance of the `ConnectView` with the Data Connect URL and assign `ConnectViewEventDelegate` as `self` to get the events (see `connectUrl` in the following code example). 4. Create callback/delegate functions for `onLoad`, `onDone`, `onCancel`, `onError`, `onRoute`, and `onUser` events. These callback functions will have a `NSDictionary?` parameter that contains data about the event. For more information see the list of [Data Connect callback events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/index.md#callback-events). ### Example {#example-1} The following is an example of the delegate functions and their usage. ```swift struct ContentView: View { @State var connectUrl: String = "" @State var presentConnect: Bool = false var body: some View { VStack { //.... Your View ....// } .fullScreenCover(isPresented: $presentConnect) { // For regular Data Connect flow use below initialiser ConnectView(connectUrl: connectUrl, delegate: self) // OR // For App to App Data Connect flow use below initialiser ConnectView(connectUrl: connectUrl, redirectUrl: "https://example.com/connect", delegate: self) } } func displayData(_ data: NSDictionary?) { print(data?.debugDescription ?? "no data in callback") } } // MastercardOpenBankingConnect Delegate Methods extension ContentView: ConnectViewEventDelegate{ func onCancel(_ data: NSDictionary?) { print("onCancel:") displayData(data) // Needed to dismiss the ConnectView presentConnect = false } func onDone(_ data: NSDictionary?) { print("onDone:") displayData(data) // Needed to dismiss the ConnectView presentConnect = false } func onError(_ data: NSDictionary?) { print("onError:") displayData(data) // Needed to dismiss the ConnectView presentConnect = false } func onLoad() { print("onLoad:") } func onRoute(_ data: NSDictionary?) { print("onRoute:") displayData(data) } func onUser(_ data: NSDictionary?) { print("onUser:") displayData(data) } } ``` ## App to App Support {#app-to-app-support} To provide the best app to app authentication experience for your customers, you should send a universal link URL in the `redirectURL` parameter when using Data Connect. See [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) for more details, including [how to test](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#how-to-test-app-to-app-authentication). Before installing the Data Connect iOS SDK for use with app to app authentication, complete the following: * Create your domain's `redirectUrl` (universal link) * Configuring your `redirectUrl` ### Create Your Domain's redirectUrl {#create-your-domains-redirecturl} For information on how to create a universal Link to be used as redirectUrl in your application, see [Apple's Allowing apps and websites to link to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) for details. Tip: In order to provide the best app to app authentication customer experience, you should use a universal link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security of universal Links through the two-way association between your app and your website. A deep link will also trigger an alert on iOS devices that can add friction to the customer experience, requesting permission to redirect back to the Partner's app. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any arbitrary application that has registered the same URL scheme. ### Configuring Your redirectUrl {#configuring-your-redirecturl} The `redirectUrl` URL is used to redirect back to your mobile app after completing the FI's OAuth flow (this should be a universal link). Here is an example of a universal link redirectUrl within your code: `self.connectViewController.load(connectUrl,redirectUrl: "https://example.com/mastercardConnect")` For information on how to configure your server see [supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) ## Sample App {#sample-app} [Github](https://github.com/Mastercard/connect-ios-sdk) contains a sample Swift application called ConnectWrapper (requires Xcode 11 or greater) that demonstrates integration and use of the Data Connect iOS SDK. ## Migrate From Framework to XCFramework {#migrate-from-framework-to-xcframework} The Data Connect iOS SDK uses the XCFramework format which allows you to easily integrate the SDK into your development projects. Our iOS SDK has full bitcode support so that you don't have to disable bitcode in your applications. ### Delete Connect.framework From Your Project {#delete-connectframework-from-your-project} If you're currently using framework in your projects, then you need to remove it before you start using the XCFramework. This ensures that the `connect.framework` won't interfere with the new XCFramework while you're trying to compile your source code. Warning: Before deleting your existing framework, test the new XCFramework, and make sure it is working correctly so that you don't accidentally delete your source files. 1. Open your project in Xcode. 2. Click the General tab. 3. Scroll down to the **Frameworks** , **Libraries** , and **Embedded Content** section. 4. Select connect.framework. 5. To delete the framework, click (--) minus. ### Remove the Connect.framework Reference {#remove-the-connectframework-reference} 1. From **Project Navigator** on the left pane, select **Framework** and press **Delete**. 2. Click **Remove Reference** (recommended) Note: This is the safest option to preserve your source files. ### Remove Run Script {#remove-run-script} If you've incorporated our script for stripping out the X86 simulator before submitting your application to the Apple App Store, you can remove the run script. It's no longer needed with the XCFramework. Only customers that create a run script to incorporate with the connect-sdk-iOS-v1.2.0.zip need to do this step. 1. From Xcode in the right pane, select your **Targets**. 2. On the **Build Phase** tab, scroll down to **Run Script** 3. To remove the script, click the x. Once you have migrated from the legacy framework to the new XCFramework, you can install the Data Connect iOS SDK via [CocoaPods](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#cocoapods)