API Testing

Overview

The Finicity Aggregation API provides the ability to test your implementation of the API. Using these testing accounts under the Test Drive plan, you can build and validate your entire Finicity API integration before upgrading to one of the commercial service plans.

Test Drive Account

In order to start using the Finicity API you will need to register for a Finicity API account. To do so, simply visit Finiciy’s website at https://www.finicity.com and click the orange “Test Drive the API” button. Then fill out the sign-up form being sure to read and agree to the Terms of Use and Privacy Policy. When you sign up you will be automatically enrolled for a Test Drive plan.

Once you have registered for the Test Drive plan login to the Developer Portal (Finicity Home Page > Login > Developer Portal) with the email address or username and password you used to register on the sign-up form.

While in test drive you may only add test customers and not any active customers. Once your integration to the Finicity API is complete you can upgrade through contract to any of the paid plans. After upgrade to a paid plan you can add active customers to activate real-world institutions and accounts for your customers.

Using Test Customers Instead Of Live Customers

The Finicity API uses testing profiles in production instead of a user acceptance testing (UAT) environment. While developing and testing your application you will be creating testing customers that are used to interface with testing or “mock” Financial Institutions (FIs), called “FinBanks”. Testing customers are not allowed to connect to live, “real world” FIs and data. Likewise, real or active customers are intended to be used when connecting to live FIs and accounts, and an active customer cannot add FinBank accounts. A few transactions are generated for each FinBank account every day, to permit testing of the entire API. See the article “Add Testing Customer” for details on creating a test customer.

It’s recommended that your application retain the ability to create test customers after going into production (FinBank is still available under paid plans.) This is so that you can continue to test your application with the FinBank accounts, which will prevent you from incurring additional costs associated with connecting to live institutions. Additionally, it will eliminate the need to use real credentials, for live institutions, and the associated security and compliance risks.

Testing Customer Limitations

There is a limit of 100 testing customers per partner. Each testing customer is limited to 20 testing accounts. A combination of FinBank profiles can be added to a single testing customer during the Finicity Connect flow. If you hit either of these limits, both testing customers and testing accounts can be deleted to make more room. See articles “Delete Customer” and “Delete Institution Login” for details on deleting customers and accounts”

Using The Various Finbanks For General Testing

In Finicity Connect, at the institution search screen, start entering text “Finbank” and you will see FinBank and Finbank Profiles A. Select any of these and you will be prompted to enter credentials. The tables included in the sections below show different username and password sets that will present different use case scenarios for the corresponding Finbank.

Finbank (101732)

Standard “FinBank” is used primarily to test certain authentication flows and error scenarios while adding accounts. The discovery and activation responses may contain one of several different multi-factor authentication (MFA) challenges based on the credentials given.

For testing accounts, any text can be provided as the MFA answer, except for the special cases described below for tfa_text and tfa_choice.

usernamepasswordMFA Type Note
demogo
demoOne of these codes: 123, 125, 127, 128, 130Service will fail with error code given in password.
invalid_user goError 103 (Invalid Credentials) will be returned.
tfa_textgoText based MFA If the answer to the MFA challenge is mfa, the
response will be another MFA challenge.

[MFA example]

tfa_imagegoImage captcha [MFA example]
tfa_choicegoMultiple text optionsIf the answer to the MFA challenge is fail, the call will
fail with code 187 (Invalid MFA). [MFA example]
tfa_multigoSame as MFA with image choice (style 1), below [MFA example]
demoimagechoiceMFA with image choice (style 1) [MFA example]
demoimagechoice2 MFA with image choice (style 2) [MFA example]
discovertimeoutgoCalls to Add All Accounts and Discover Accounts will take more than 180 seconds, for testing the client app’s asynchronous handling.
activatetimeoutgoCalls to Refresh Accounts and Load HistoricTransactions will take more than 180 seconds, for testing the client app’s asynchronous handling.

Finbank Profiles (102105 and 102168)

Finbank Profiles is much better for testing the actual data scenarios you would encounter in the real world. Many have anonymous real transaction data and many different combinations of accounts types. There are two Finbank Profiles financial institutions. The first is Finbank Profiles A (102105) and the second Finbank Profiles B (102168). Both institutions behave the same but because there are two distinct institutions it allows you to test scenarios where you need to test with two financial institution accounts present.

usernamepasswordAccount Types Supported Products
Anyprofile_02Savings, IRA, 401k, Credit Card ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_03Checking, Personal Investment, 401K, Roth, Savings
(Joint Account owners)
ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_04Checking, 403B, 529, Rollover, Mortgage ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_05Checking, Investment, Stocks, UGMA, UTMA
(Joint Account owners)

ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_06Checking, Retirement, KEOGH, 457, Credit Card ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_07Checking, Stocks, CD, Investment Tax Deferred, Employee Stock ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_08 Checking, Primary Savings, Money Market, 401A, Line of credit ach, aha, state_agg, trans_agg, voa, voi
Anyprofile_09Checking, Savings, Checking
Failed Report. Errors returned in the report include, 102, 103, 185.

ach, voa (failed report), voi (failed report)

Using Finbanks For VOIE Testing

In Finicity Connect, do the following to test VOIE:

  • 1

    At the institution search screen, start entering text “Finbank” and you will see FinBank and Finbank Profiles A.

  • 2

    Select Finbank Profiles A.

  • 3

    Enter the credentials of the VOIE testing profile that produces the desired testing scenario

  • 4

    Choose a PDF file that corresponds to the profile chosen for testing

In the section below, there are different username and password sets that will present different use case scenarios specific to VOIE for the corresponding Finbank profile. In addition, the PDF files corresponding to each VOIE testing profile can also be found below.

VOIE Finbank Profiles (102105 and 102168)

The FinBank profiles described below are best used to test VOIE scenarios that would occur in the real world

usernamepasswordAccount Types Supported Products
Scenario
profile_1022profile_1022 CheckingvoieTxVerifySalary Pay
profile_1023 profile_1023CheckingvoieTxVerifyHourly Pay
profile_1024profile_1024 CheckingvoieTxVerifyHourly Pay with Overtime
profile_1025profile_1025CheckingvoieTxVerifySalary Pay with Quarterly Bonus
profile_1026profile_1026CheckingvoieTxVerifySalary Pay with Commission
profile_1027profile_1027Checking, Savings voieTxVerifySalary Pay with Split Direct Deposits

FinPay Pay Statement PDFs for VOIE Profile Testing

VOIE testing profiles have corresponding testing FinPay (Finicity’s Fake Payroll Company) Pay Statement PDFs that allow for flexible testing. Use the links below to download a specific profile’s testing FinPay Pay Statement PDFs:

How To Test OAuth Using Finbank Oauth

  • 1

    At the institution search screen, start entering text “Finbank” and you will see FinBank and Finbank Profiles A.

  • 2

    Select Finbank Profiles A.

  • 3

    Enter the credentials of the VOIE testing profile that produces the desired testing scenario

  • 4

    Choose a PDF file that corresponds to the profile chosen for testing

Read the following guide for Oauth institutions to understand better what they are and how they work. The table included in the section below shows different username and password sets that will present different use case scenarios for testing OAuth.

Finbank OAuth Profiles (102176)

FinBank OAuth Profiles is much better for testing the actual data scenarios you would encounter in the real world. Many have anonymous real transaction data and many different combinations of accounts types. These profiles will allow you to go through the OAuth flow and test different simulated scenarios.

usernamepasswordAccount Types Supported Products
profile_02profile_02Savings, IRA, 401k, Credit Card ach, aha, state_agg, trans_agg, voa, voi
profile_03profile_03Checking, Personal Investment, 401K, Roth, Savings
(Joint Account owners)

ach, aha, state_agg, trans_agg, voa, voi
profile_04profile_04Checking, 403B, 529, Rollover, Mortgage ach, aha, state_agg, trans_agg, voa, voi
profile_05profile_05Checking, Investment, Stocks, UGMA, UTMA
(Joint Account owners)

ach, aha, state_agg, trans_agg, voa, voi
profile_06profile_06 Checking, Retirement, KEOGH, 457, Credit Card ach, aha, state_agg, trans_agg, voa, voi
profile_07profile_07Checking, Stocks, CD, Investment Tax Deferred, Employee Stock ach, aha, state_agg, trans_agg, voa, voi
profile_08profile_08Checking, Primary Savings, Money Market, 401A, Line of credit ach, aha, state_agg, trans_agg, voa, voi
profile_09 profile_09Checking, Savings, Checking
Failed Report. Errors returned in the report include, 102, 103, 185.

ach, voa (failed report), voi (failed report)

Testing Your Finicity API Implementation

As you follow the rest of the Finicity guides simply use the Finicity test customer and test financial institutions any time the guide mentions creating a live customer and adding accounts. Then as you plan to go live with your application in production all you will need to do is start creating active customers instead of testing customers and using live FI’s instead of testing FI’s.