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.
username | password | MFA Type | Note |
---|---|---|---|
demo | go | ||
demo | One of these codes: 123, 125, 127, 128, 130 | Service will fail with error code given in password. | |
invalid_user | go | Error 103 (Invalid Credentials) will be returned. | |
tfa_text | go | Text based MFA | If the answer to the MFA challenge is mfa, the response will be another MFA challenge. [MFA example] |
tfa_image | go | Image captcha | [MFA example] |
tfa_choice | go | Multiple text options | If the answer to the MFA challenge is fail, the call will fail with code 187 (Invalid MFA). [MFA example] |
tfa_multi | go | Same as MFA with image choice (style 1), below | [MFA example] |
demo | imagechoice | MFA with image choice (style 1) | [MFA example] |
demo | imagechoice2 | MFA with image choice (style 2) | [MFA example] |
discovertimeout | go | Calls to Add All Accounts and Discover Accounts will take more than 180 seconds, for testing the client app’s asynchronous handling. | |
activatetimeout | go | Calls 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.
username | password | Account Types | Supported Products |
---|---|---|---|
Any | profile_02 | Savings, IRA, 401k, Credit Card | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_03 | Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners) | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_04 | Checking, 403B, 529, Rollover, Mortgage | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_05 | Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners) | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_06 | Checking, Retirement, KEOGH, 457, Credit Card | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_07 | Checking, Stocks, CD, Investment Tax Deferred, Employee Stock | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_08 | Checking, Primary Savings, Money Market, 401A, Line of credit | ach, aha, state_agg, trans_agg, voa, voi |
Any | profile_09 | Checking, 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
username | password | Account Types | Supported Products | Scenario |
---|---|---|---|---|
profile_1022 | profile_1022 | Checking | voieTxVerify | Salary Pay |
profile_1023 | profile_1023 | Checking | voieTxVerify | Hourly Pay |
profile_1024 | profile_1024 | Checking | voieTxVerify | Hourly Pay with Overtime |
profile_1025 | profile_1025 | Checking | voieTxVerify | Salary Pay with Quarterly Bonus |
profile_1026 | profile_1026 | Checking | voieTxVerify | Salary Pay with Commission |
profile_1027 | profile_1027 | Checking, Savings | voieTxVerify | Salary 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 OAuth.
- 2
Select Finbank OAuth.
- 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.
username | password | Account Types | Supported Products |
---|---|---|---|
profile_02 | profile_02 | Savings, IRA, 401k, Credit Card | ach, aha, state_agg, trans_agg, voa, voi |
profile_03 | profile_03 | Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners) | ach, aha, state_agg, trans_agg, voa, voi |
profile_04 | profile_04 | Checking, 403B, 529, Rollover, Mortgage | ach, aha, state_agg, trans_agg, voa, voi |
profile_05 | profile_05 | Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners) | ach, aha, state_agg, trans_agg, voa, voi |
profile_06 | profile_06 | Checking, Retirement, KEOGH, 457, Credit Card | ach, aha, state_agg, trans_agg, voa, voi |
profile_07 | profile_07 | Checking, Stocks, CD, Investment Tax Deferred, Employee Stock | ach, aha, state_agg, trans_agg, voa, voi |
profile_08 | profile_08 | Checking, Primary Savings, Money Market, 401A, Line of credit | ach, aha, 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, 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.