Connecting with USAA

Unfortunately USAA have recently made a change that seems to have disabled direct OFX connections, which Moneydance and other software requires to directly communicate with their servers. We are working to resolve this, but I’m afraid the connection is not working correctly at this time.

Stuart Beesley, a Moneydance user and contributor to the support forum, has written a python script that allows you to update your Moneydance dataset with the correct OFX connection settings that USAA requires.

Many thanks to Stuart, @dtd for instructions and testing, and @hleofxquotes for credits and technical OFX input. We really appreciate your contributions!

The script is not guaranteed to work, but the majority of customers who have followed the steps have reported success.

Before following the steps below, take a manual backup of your data file via File —> Export Backup. This will create a .moneydancearchive backup file.

It is estimated the steps below will take around 30 minutes to complete.

If you prefer to use the original PDF document, it can be downloading via the following link -
https://github.com/yogi1967/MoneydancePythonScripts/raw/master/sour...

Step 1 – Get new information from USAA

Since the changes made on 26th January 2021, you must gather three specific items from USAA -

  • clientUid
  • userid
  • userpassword

To retrieve this information -

You will see the following page where we can retrieve your clientUid -
Do not allow Quicken access just yet as that'll direct you to another page

USAA_Website.jpg

On this screen, you should copy all the text in your web browser address bar (see the purple arrow) and paste into a text program like TextEdit, Notepad, Word etc.

The following is an example of the information you'll see -

https://www.usaa.com/inet/ent_oauth_consent/authorize?0&client_id=12345678-abcd-efgh-ijkl-123456789abc&redirect_uri=https://df3cxservices.1fsapi.com/ casm/usaa/connect&scope=usaa.profile.member.read+usaa.bank.aggregation. read&response_type=code&code_challenge=my_challenge&state=my_state&code _challenge_method=plain&session_id=nonothere-nopenope-nope-clientidisit

Within this, you can find your clientUID. This is the information after "client_id".
It is 36 characters consisting of - XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (8-4-4-4-12)

Take note of this clientUid as we'll need it later.
We'd recommend you create a new seperate text file where you can store the details you'll need

Make sure you haven't taken note of the session_id by mistake. We do not need the session_id as it will change

Then open your web browser to the same page as before, and click 'Allow' to authorise access with Quicken. On the next page, you'll see your Access ID and Access PIN

USAA_access_id_and_pin.jpg

The Access ID is your userid and the Access PIN is your userpassword.
Copy both of these fields and enter them in the same document as the clientUid.

At this point, you should have one document that contains your clientUid, userid and userpassword.

After following these steps you will receive an email from USAA stating you've allowed Quicken to access USAA

Step 2 – Get your current account information

Next you'll need your gather your account numbers. You also need the USAA routing number.

The USAA routing number is - 314074269. Add that to the text file that includes your other details.

You should also add the account numbers for your USAA accounts. And include if they are checking, savings, or credit card account numbers.

USAA checking and savings accounts require a ten digit number. If your account number is only 7 or 8 digits, you should add zeroes to the start of the number. For example, if your account number is 12345678, you should use the following - 0012345678.

USAA credit card accounts will use your 16-digit number but there can be issues with this, which are addressed further into the article.

If you have multiple accounts, we recommend you change your account nicknames in USAA. This will allow you to easily recognize them in Moneydance later. To do this, login to the USAA website - go to each account, find the nickname, and make each name unique and recognizable.


At this point, you should have a text file that contains the following information -

  • clientUid, 8-4-4-4-12 characters (36 including hyphens)
    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • userid (access id)
  • userpassword (access pin)
  • USAAroutingnumber
    314074269
  • Checkingaccountnumber – 10 digits
  • Creditcardnumber – 16 digits (15 for Amex)

If you have more accounts, add them too. We will handle the other accounts further into the article.

Step 3 – Get the script

By following the link below, you can download the python script you need -
https://github.com/yogi1967/MoneydancePythonScripts/raw/master/usef...

Depending the web browser you use, when you attempt to download you might see a blank screen, and the file(s) will automatically download to your Downloads folder.

Unpack the .zip file to reveal a folder called 'useful_scripts.zip'.
Open this folder, and look for the following file -

ofx_create_new_usaa_bank_custom_profile.py

Step 4 – Run the script

Before going any further, if you haven't already, you should create a manual backup file via File --> Export Backup.

If you would like to test the script before running it on your actual data file, you can follow the steps below to create a test file -
* Open Moneydance and choose File --> Export Backup, to create a .moneydancearchive file.
* Rename the backup file - TESTUSAA.moneydancearchive
* Open this test file by double clicking it - you'll see a copy of your accounts and transactions, but the data file name will be 'TESTUSAA'.
* Your existing file is not changed, and remains accessible from within Moneydance by choosing File --> Open, where your file names will be listed.

  • Open Moneydance and access your data file - either your original file, or the TESTUSAA file you created earlier.
  • Choose Windows --> Show Moneybot Console
  • In the window that opens, you should see the options 'Open Script' and 'Run' within the left panel. If you don't see both of these options, expand the window and they'll come into view.
  • Select 'Open Script'. Then navigate to and select the file - ofx_create_new_usaa_bank_custom_profile.py
  • Then click 'Run'.

USAA_Run_Script.png

On a Mac you might see two popup warnings about a jffi*.dylib file. You can ignore and cancel these warnings.

  • The script will ask you for all of the details you gathered earlier. Enter them carefully.
    We recommend using copy/paste as this will reduce the risk of typos.
    Make sure you clear the default information from each field before entering your details.

  • Enter/paste all of the requested details and hit proceed.

  • You will be asked a number of questions - including which bank logon/service profile to change - the script will deliberately only provide USAA.

  • You will also be asked if you have multiple USAA logins. For most USAA customer the answer is no. If the answer is yes, you should continue to the end of this article where this is addressed.

Examine the Moneybot Console screen on the left. You will either see errors, or it will state that the script has run successfully.

Then close Moneydance and restart. This is necessary.

For each account you have entered in the script, click on the account, and then select
Online --> Download AccountName Transactions.


If the script has worked, the transactions for your checking/savings account will download.

The credit card transactions may also download, but don’t be concerned if you see an error - we will address this in step 5.

Unfortunately if downloading does not work at all, you may need to revisit the whole process (i.e. start over).


If you see the 2000 error, this is a general error. You should create a new support request and provide details of the error you're seeing and messages displayed along side this.

If you see the 2003 error, this means 'Account not found'. This error is a response from the bank, advising you the banks server could not find the account you've specified.
The changes you've made have worked, as Moneydance is now communicating with your banks server. So there is likely an issue with the details you've input. You should check the details you've entered are correct.

If you see the 2015 error, this means 'Date too far in future'. To fix this, select the account and choose Online --> Setup Online Banking. In this window, select 'Reset Sync'. Then attempt to download your transactions again.

If you see the 403 FORBIDDEN error, there are a few causes. If you are outside the U.S., you may encounter this, and must use a VPN to “be in the U.S.”. If you are in the US, you may have attempted to connect too many times quickly. This is a temporary connection ban that should be lifted after a few hours.

If you encounter problems at this point, choose Help --> Console Window. This will open the console messages window. Keep this window open and attempt to download again. Information relating to the download will appear in the console window. You should copy the text from this window, and include it with your support request.

Step 5 – Adjust for new credit card numbers

If you are able to download transactions from your checking account, but your credit card isn’t found - it's likely USAA have a different credit card in their database. To determine the number you need -

USAA_Change.png

  • Open Moneydance, select the credit card account and choose Online --> Setup Online Banking.
  • Select 'Change', choose 'USAA Custom Profile' and select 'Next'.
  • Verify you are viewing the credit card account (or move to the credit card), hit 'Next' again, and you should see the userid you previously entered.
  • You will be prompted for your password again.

In this window, you may see multiple items.
You may also see a credit card that you don’t recognize.

If you have multiple cards, you must choose the number that matches your current card, even if it
is a different number. If you previously changed the nicknames for your USAA accounts this will make matching easier. If you haven't done this, it can be tricky to match - especially if you have multiple accounts and multiple “different” numbers.

If you have one card, you should be able to distinguish checking account from credit cards.
Pick the card offered, choose 'Next', 'Finish' and then 'Done.
Then select the account and choose Online --> Download AccountName Transactions.

Step 6 – Add other accounts

This script was initially designed to fix one checking account and one credit card, but we understand some of our customer have more accounts with USAA.

If the process has been successful to this point, your USAA profile has now been fixed.
You should open Moneydance, choose Online --> Setup Online Banking, and select 'Change'.

You'll find your other accounts in the list and you can properly assign your other Moneydance accounts to your multiple USAA accounts.

Pay attention to which numbers go to which accounts.
If you get the matching wrong, change the accounts again to attach to the correct accounts.
If the matching was wrong initially, you may have to delete any transactions that have downloaded incorrectly.

You can use the TESTUSAA file you created earlier to check which account is which. Create a brand new account, and link it to an account number you don't recognise.
Download your transactions to this new account, and take check to transactions to determine which account you're using. Then take note of which account is which.
Repeat if necessary. Then once you have determined which account is which, you can move to your real data file.

Step 7 - Multiple Login Accounts for USAA (specific to only some users)

Some customers have multiple USAA logins (spouse, children, etc.) however most won't need this final step. When the script asks, “Do you have multiple DIFFERENT credentials where you wish to ‘prime’ the default UUID into (Root’s) profile”, just select “NO (Skip this)”.

If you do have multiple logins, you should get one account working first on a test system. This is so that you have the necessary knowledge before undertaking this extra set of steps.

  • Follow steps 1 and 2 to gather another set of logon credentials for the second USAA account.
  • When running the script, select YES – PRIME SECOND ACCOUNT. You will then be asked for the second account’s ClientUUID and the second User ID
    We have seen that often the second Client UUIID is identical to the first user’s Client ID – this is OK.
  • Proceed with the rest of the script as normal.

This script will not actually configure the second account - instead it will get it ready for use with the
second Client UUID and UserID.

At this point, download your accounts (using the primaryUserID).
Once that works, use Online --> Setup Online Banking, and select 'Change'. This will allow you to configure the second user’s account details, then attempt to connect again.

If the problems persist, create a support request including as much details as possible about the issues you've encountered.

Handling the downloaded transactions -

You may notice some changes to the way your USAA transactions download into Moneydance -

For checking accounts, you may now see a “0” in the check number field of some transactons.

The description and memo fields are cruder, mostly caps, and near identical.

The “don’t download me again” field (which is hidden) has in some cases been reset, so you may get many months of duplicate transactions that have to be dealt with.

If you’ve been entering USAA transactions manually since the connection problems began, then you will need to go through the confirmation process and merge the duplicates transactions.
If you prefer you can set moneydance to do this automatically - within your preferences, choose the 'Network' tab, where you can enable 'Automatically Merge Downloaded Transactions'.

If you have duplicate transactions that you cannot seem to merge, then you should keep the new downloaded transaction, not the original one. By keeping the newer transaction, Moneydance will recognise the transaction ID and it won't download again.
You may wish to transfer over the memo field from the original entry, category, etc. before deleting the original.