Account and Transaction Maintenance
Pulling Accounts Daily
After successfully adding accounts to a customer, Finicity will automatically update and aggregate transactions from those accounts every night in our nightly batch aggregation. This transaction data can be accessed daily by the Partner, allowing them to maintain an accurate record of those accounts, and consume them in their services.
Assuming the accounts have status code 0 (account ready for aggregation), they will be current according to updates at the Financial Institution hosting the account. The Partner can call this updated account data using the API endpoints, Get Customer Transactions or Get Customer Account Transactions’.
The Get Customer Transactions endpoint returns transactions for all customer accounts. If the Partner wants transaction data for only specified customer accounts, the Partner will instead use the Get Customer Account Transactions endpoint, which limits the returned transactions to the customer accounts specified in the body of the call. Use the Get Customer Accounts endpoint to get a list of current customer accounts, or the Get Customer Accounts by Institution endpoint, to aid in specifying customer accounts.
Best practices are to pull account transactions to maintain current account data, and perform a deduplication on the new data, preventing duplication of data in the Partner’s database. When pulling account transaction data, a period of 15 days is recommended. It is common for a Financial Institution to alter transaction data as far back as 15 days, to resolve balance changes, pending status, transaction errors, etc.
Another option is to subscribe to TxPush notifications, which allows Finicity to send changes or additions to accounts or transactions to the Partners event listener. Articles have been included below to help setup your TxPush listener service and how to subscribe to TxPush events.
Understanding Account Aggregation Status
As accounts are aggregated every night or upon a refresh, an aggregation status code is placed in the account status field. Accounts can have conditions preventing the nightly batch aggregation, indicated by the account status, such as:
MFA challenges (What was the name of your first pet? What is your Mother’s maiden name?), status code 185.
Changing the username or password causing a credential mismatch, status code 103.
Security prompt to send a code to a mobile number to pass a security check, status code 185.
Prompt to accept new terms and conditions, before viewing account details, status code 108.
If a condition exists that prevents the batch aggregation, the borrower / user needs to be contacted by the Partner and brought back to the flow to clear the challenge preventing account transaction aggregation.
Using Connect Fix
Using Connect Fix will allow for end users to fix their account credentials or MFA when an account is in a supported error state. When an account or accounts are in a supported error state, call Get Connect URL with type fix to get the URL that allows the end user to fix the problem.
List of Supported Errors
| Code | Connect Message | Error Description |
|---|---|---|
| 103 | Invalid username and/or password. If you continue to receive this error, please log into your bank’s website to ensure access, then come back and try again. | During add account process this means that the customer has entered the wrong credentials. If the customer continues to enter the password incorrectly it could help to have them login directly to their financial institution site to confirm and/or update their username/password. On an already added account means that the credentials have changed and need to be updated. Consumer credentials can be updated by presenting the connect fix flow to the consumer for the accounts for the institutionLoginId set |
| 185 | One of your security questions (e.g. name of your first pet) needs has expired and needs to be answered | You will not see this error on the add account process. On an already added account it means that the FI is prompting the customer for additional authentication information. There may not be an answer or an incorrect answer stored for the security question. Consumer MFA can be updated by presenting the connect fix flow to the consumer for the accounts for the institutionLoginId set. |
| 945 | The account is migrated but not consented on OAuth. | This error code indicates that the account is not capable of being added to the API. Please open a support ticket. |
| 946 | Bank returned no record for request. | 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 Connect Fix and/or a refresh. If that fails, please submit a Support Ticket. |
| 947 | Your token is invalid or has expired, Please re-authenticate. | Invalid token. This should not apply to the add account process, but can be triggered shortly afterward. Please re-authenticate, and if the issue persists, raise a Support Ticket. |
| 948 | The account is in migration status, the user needs to do OAuth. | The account has been migrated to OAuth and is waiting for the customer to authenticate. |
The end user will follow the connect flow and update their credentials (status code 103) and/or answer any MFA required (status code 185). If successful, the accounts will then be in an aggregation status code 0 indicating aggregation was successful. The accounts could be placed in an additional error state after the accounts have been authenticated. If this occurs, look at the error code and follow documentation. If the customers accounts are in an aggregation status that is not supported by Connect Fix as listed below, or if after following the flow for supported error codes several times does not solve the issue then you can submit a ticket to the Finicity support team to resolve the issue.
With or Without Financial Institution login ID
To fix accounts under a specific set of login credentials, institutionLoginId, not all of a particular customer’s accounts, you’ll need to include the institutionLoginId. The returned Connect Fix URL will only fix accounts associated with that institutionLoginId.
To fix all accounts across multiple FI’s, simply do not populate the institutionLoginId. All accounts associated with the customerId will be accessible through the returned Connect Fix URL.