Finicity (Mastercard) SDKs & Libraries: Integration Guides (2026)

SDKs overview

Finicity, an open banking platform owned by Mastercard, offers a suite of APIs designed to enable financial data access, payment initiation, and credit decisioning services. To simplify developer interaction with these APIs, Finicity provides official Software Development Kits (SDKs) for multiple programming languages. These SDKs are designed to abstract the complexities of direct HTTP requests, authentication, and response parsing, allowing developers to focus on integrating Finicity's functionalities into their applications with fewer lines of code.

The Finicity developer experience emphasizes a sandbox environment for testing and a comprehensive API documentation portal. SDKs typically handle common tasks such as API key management, token refreshing, and error handling, adhering to best practices for secure and efficient API communication. While Finicity primarily offers RESTful APIs for its core products, including data aggregation and payment initiation, the SDKs provide a language-specific interface to these operations.

Developers integrating with Finicity can utilize these SDKs to access a range of financial data points, including transaction history, account balances, and loan details, subject to consumer consent. The SDKs also facilitate workflows for initiating payments and verifying accounts, which are critical for applications in lending, personal financial management, and fraud detection. The approach to API integration for open banking platforms often involves adherence to security standards such as OAuth 2.0 for authorization, a protocol widely adopted across the industry, as detailed in the OAuth 2.0 specification.

Official SDKs by language

Finicity maintains official SDKs for popular programming languages to streamline integration. These SDKs are developed and supported directly by Finicity, ensuring compatibility with the latest API versions and features. The table below outlines the key official SDKs available, along with their respective package managers and typical installation commands.

For detailed information on each SDK, including specific versioning, method signatures, and advanced configuration options, developers should refer to the official Finicity documentation.

Installation

Installing Finicity's official SDKs typically follows standard practices for each respective language's package management system. Below are general installation guidelines for the most commonly used SDKs. Specific version numbers and prerequisites may vary, so always consult the Finicity API documentation for the most up-to-date instructions.

Python SDK

To install the Python SDK, use pip, the Python package installer:

pip install finicity-python-sdk

It is recommended to use a virtual environment to manage dependencies for your project.

Java SDK

For Java projects, you can add the Finicity Java SDK as a dependency using Maven or Gradle. For Maven, add the following to your pom.xml:

<dependencies>
    <dependency>
        <groupId>com.finicity</groupId>
        <artifactId>finicity-java-sdk</artifactId>
        <version>1.x.x</version> <!-- Replace with the latest version -->
    </dependency>
</dependencies>

For Gradle, add to your build.gradle:

dependencies {
    implementation 'com.finicity:finicity-java-sdk:1.x.x' // Replace with the latest version
}

Node.js SDK

Install the Node.js SDK using npm or yarn:

npm install finicity-node-sdk
# or
yarn add finicity-node-sdk

Ruby SDK

Add the Finicity Ruby SDK to your Gemfile:

gem 'finicity-ruby-sdk'

Then run bundle install from your terminal.

PHP SDK

Install the PHP SDK using Composer:

composer require finicity/php-sdk

Quickstart example

This Python example demonstrates how to initialize the Finicity SDK and make a basic API call to retrieve a list of institutions. Before running, ensure you have your Finicity API credentials (App Key, App ID, and Partner Secret) configured, ideally through environment variables or a secure configuration management system.

import os
from finicity_python_sdk import FinicityClient
from finicity_python_sdk.exceptions import FinicityException

# Configure API credentials from environment variables
FINICITY_APP_KEY = os.getenv('FINICITY_APP_KEY')
FINICITY_APP_ID = os.getenv('FINICITY_APP_ID')
FINICITY_PARTNER_SECRET = os.getenv('FINICITY_PARTNER_SECRET')

if not all([FINICITY_APP_KEY, FINICITY_APP_ID, FINICITY_PARTNER_SECRET]):
    print("Error: Finicity API credentials not set in environment variables.")
    exit(1)

try:
    # Initialize the Finicity client
    client = FinicityClient(
        app_key=FINICITY_APP_KEY,
        app_id=FINICITY_APP_ID,
        partner_secret=FINICITY_PARTNER_SECRET,
        # For sandbox environment, use FinicityClient.SANDBOX_BASE_URL
        # For production, use FinicityClient.PRODUCTION_BASE_URL
        base_url="https://api.finicity.com"
    )

    # Generate an access token (required for most API calls)
    access_token = client.authenticate()
    print(f"Successfully authenticated. Access Token: {access_token[:10]}...")

    # Example: List institutions
    # The 'search' parameter can be used to filter institutions (e.g., 'Bank of America')
    # The 'country' parameter can be used to specify the country (e.g., 'US', 'CA')
    institutions_response = client.institutions.get_all_institutions(
        search=None, 
        country='US'
    )

    print("\n--- Top 5 Institutions ---")
    if institutions_response and institutions_response.institutions:
        for i, institution in enumerate(institutions_response.institutions[:5]):
            print(f"ID: {institution.id}, Name: {institution.name}, URL: {institution.url}")
    else:
        print("No institutions found.")

except FinicityException as e:
    print(f"Finicity API Error: {e.message} (Status Code: {e.status_code})")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

This example demonstrates basic authentication and fetching a list of institutions. For more complex operations, such as adding customers, retrieving account details, or initiating payments, developers would use other methods available within the client object, as detailed in the Finicity API reference.

Community libraries

While Finicity provides official SDKs, the broader developer community may also contribute open-source libraries, wrappers, or tools that interact with the Finicity APIs. These community-driven projects can sometimes offer alternative approaches, support for less common languages, or specialized functionalities not found in the official SDKs. However, it is important to note that community libraries may not always be officially supported or maintained by Finicity and might not guarantee the latest features, security updates, or compatibility with new API versions.

Developers considering community libraries should evaluate their active maintenance, community support, and alignment with the official Finicity API specifications. Resources like GitHub and other open-source repositories are common places to discover such contributions. When using third-party libraries, always review the source code and consider the implications for security and reliability. Mastercard itself, as the parent company of Finicity, also supports various developer initiatives, including Mastercard Developer SDKs, which may offer broader financial service integrations beyond Finicity's specific open banking focus.

For critical applications, relying on the official Finicity SDKs and direct API calls is generally recommended to ensure full support and adherence to Finicity's operational standards.