Finicity (Mastercard) Getting Started: Quick Integration Guide (2026)

Getting started overview

Integrating with Finicity (Mastercard) for financial data aggregation and payment initiation involves a structured process, moving from account creation to making live API calls. The initial phase focuses on setting up a developer account, securing API credentials, and familiarizing oneself with the sandbox environment. This allows for testing integrations without impacting live financial data or transactions. Finicity's APIs are designed to support various use cases, including credit decisioning, personal financial management (PFM) applications, and account verification services Finicity API documentation. Developers typically interact with RESTful endpoints, authenticating requests using a combination of a Partner ID, an Application Key, and an Application Secret.

The development workflow begins in a dedicated sandbox environment, providing simulated data and responses to ensure proper integration logic before transitioning to a production environment. This approach is standard practice in financial API integrations, similar to how other fintech platforms provide testing environments for developers PayPal REST API overview. Understanding the available endpoints and the required request/response structures is crucial for a successful integration. Finicity provides comprehensive documentation covering various API calls for data access, reports, and payments.

Create an account and get keys

To begin using Finicity's services, you must first register for a developer account. This account provides access to the developer portal, documentation, and the necessary API credentials. Follow these steps:

1. Register for a Developer Account: Navigate to the Finicity developer portal and complete the registration process. This typically involves providing contact information and agreeing to terms of service.
2. Access API Credentials: Once your account is active, you will be granted a set of unique API credentials. These typically include:
• Partner ID: A unique identifier for your developer account.
• Application Key (App Key): Used to identify your specific application.
• Application Secret (App Secret): A confidential key used to authenticate your application's requests. This key should be stored securely and never exposed in client-side code.
3. Understand Credential Usage: These credentials are fundamental for all API interactions. The Partner ID and App Key are often included in API request headers or as query parameters, while the App Secret is used to generate authentication tokens or sign requests, ensuring the integrity and authenticity of your calls.
4. Sandbox Environment Setup: The developer portal will also guide you on how to access and configure your sandbox environment. This environment mirrors the production API but uses simulated data, allowing you to test all API functionalities without affecting real user accounts.

Quick Reference for Setup:

Your first request

After acquiring your API credentials, the next step is to make your first successful API call to the Finicity sandbox environment. This typically involves obtaining an authentication token and then using that token to retrieve some initial data. For demonstration, we'll outline a common first request: retrieving a list of institutions available in the sandbox.

1. Obtain an Access Token

All Finicity API requests require an access token. This token is generated by exchanging your Partner ID, App Key, and App Secret. The process involves making a POST request to the authentication endpoint.

curl -X POST 'https://api.finicity.com/agg/v2/partners/authentication' \
  -H 'Finicity-App-Key: YOUR_APP_KEY' \
  -H 'Finicity-Partner-ID: YOUR_PARTNER_ID' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"partnerId":"YOUR_PARTNER_ID", "partnerSecret":"YOUR_APP_SECRET"}'

Replace YOUR_APP_KEY, YOUR_PARTNER_ID, and YOUR_APP_SECRET with your actual credentials. The response will include an accessToken and an expiresIn value. Store this accessToken securely, as it will be used in subsequent requests.

2. List Institutions (Sandbox)

Once you have an access token, you can make authenticated calls. A good starting point is to fetch a list of institutions, which can help you understand the data structure and verify your authentication. This example uses the /institution endpoint.

curl -X GET 'https://api.finicity.com/institution' \
  -H 'Finicity-App-Key: YOUR_APP_KEY' \
  -H 'Finicity-Partner-ID: YOUR_PARTNER_ID' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Finicity-Access-Token: YOUR_ACCESS_TOKEN'

Again, replace YOUR_APP_KEY, YOUR_PARTNER_ID, and YOUR_ACCESS_TOKEN with your valid values. A successful response will return a JSON array of institution objects, each containing details like the institution's ID, name, and URL. This confirms your setup is working correctly within the sandbox.

Common next steps

After successfully making your first API calls in the sandbox, consider these common next steps to further your integration:

1. Explore Finicity Connect: Finicity Connect is a user-facing module that simplifies the process of securely linking consumer financial accounts. It handles the UI/UX for institution selection, credential input, and multi-factor authentication (MFA). Implementing Connect is often a prerequisite for live data access and is crucial for a smooth user experience Finicity Connect integration guide.
2. Add a Customer Account: Use the /customers endpoint to create a test customer in the sandbox. This involves providing a unique customer identifier and can be done prior to using Finicity Connect.
3. Aggregate Account Data: Once a customer is created and an institution is linked (via Connect or direct API calls), you can use endpoints like /customers/{customerId}/accounts to retrieve detailed account information, including balances and transaction histories.
4. Generate Reports: Finicity offers various report types, such as credit decisioning reports (e.g., Asset Report, Income Verification). Learn how to request and retrieve these reports, which aggregate and analyze financial data for specific purposes.
5. Implement Webhooks: For real-time notifications about account updates, transaction changes, or report generation completion, set up webhooks. This pushes information to your application rather than requiring constant polling Finicity webhooks documentation. Webhooks are a common pattern for event-driven architectures across many API providers Stripe webhooks guide.
6. Error Handling and Logging: Develop robust error handling mechanisms to gracefully manage API failures, network issues, and data inconsistencies. Implement comprehensive logging to monitor API usage and troubleshoot problems effectively.
7. Review Security Best Practices: Understand and apply Finicity's security recommendations for storing credentials, handling sensitive data, and securing your application infrastructure. This includes client-side security for applications that interact with financial data.
8. Transition to Production: Once your sandbox integration is stable and thoroughly tested, follow Finicity's guidelines for requesting access to the production environment. This typically involves a review process to ensure compliance and readiness.

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here are some troubleshooting tips for your first Finicity API request:

• Check API Credentials: Double-verify your Partner ID, App Key, and App Secret. Typographical errors are a frequent cause of authentication failures. Ensure they are correctly placed in the request headers or body as specified in the Finicity API reference.
• Verify Access Token: Ensure the Finicity-Access-Token header is present and contains a valid, unexpired token. If your token has expired (check the expiresIn value from the authentication response), request a new one.
• Endpoint URL: Confirm you are using the correct sandbox API endpoint URL (e.g., https://api.finicity.com/...). Mistaking sandbox for production or vice versa will result in errors.
• HTTP Headers: Ensure all required HTTP headers are correctly set, including Finicity-App-Key, Finicity-Partner-ID, Accept: application/json, and Content-Type: application/json for POST requests.
• Request Body Format: For POST requests, verify that the JSON request body is correctly formatted and contains all necessary parameters. Malformed JSON will lead to parse errors.
• Network Connectivity: Confirm that your development environment has unrestricted outbound access to Finicity's API endpoints. Firewall or proxy settings can sometimes block requests.
• Review Error Messages: Pay close attention to the HTTP status codes and the JSON error responses returned by the API. Finicity's error messages are typically descriptive and can point you directly to the problem. For example, a 401 Unauthorized often indicates an issue with your credentials or access token, while a 400 Bad Request might suggest problems with your request body or parameters. Consult the Finicity status codes documentation for detailed explanations.
• Refer to Documentation: The official Finicity documentation is the most authoritative source for specific endpoint requirements, request parameters, and expected responses. Cross-reference your implementation with the examples provided.
• Community and Support: If you're still stuck, check Finicity's developer forums or contact their support team. Providing detailed request logs and error messages will help them diagnose your issue faster.