banker

This is a command-line script that downloads transactions and balances from financial institutions using Zombie.js. Currently supported banks:

• PayPal

  • Works regardless of whether the account has opted in to the new PayPal website.

• Avadian Credit Union (formerly Alabama Telco Credit Union)

• Credit unions handled by the new Fiserv software (if your online banking URL starts with https://www.financial-net.com/* or https://www.ea.financial-net.com/vbsts/*)

  • Trust Federal Credit Union
  • Probably others

• Credit unions handled by the old Fiserv software (if your online banking URL starts with https://www.netit.financial-net.com/*)

  • BlueCross BlueShield of Tennessee Employee Credit Union
  • Probably others

• Regions Bank

• Tennessee Valley Federal Credit Union

• Please help add your bank! See below for details.

Installation

Install Node.js, then:

sudo npm install -g banker
banker --help

Usage

banker --config config.json --output data/results.json

Running banker --help shows documentation for other command-line options:

Usage: banker options

Options:
  -b, --banks          Just list the banks that this program can download
                       information from.
  -l, --list           Just list the banks and accounts in the given config
                       file.
  --describe-output    Just list the banks and accounts in the given output
                       file.
  -c, --config         The JSON config file(s) describing the banks and
                       accounts to process.
  -o, --output         The JSON output file with transaction details.
  -s, --skip           Skip the specified bank(s) or account(s).
  --only               Only process the specified bank(s) or account(s) - see
                       --list for valid specifiers.
  -d, --debug-browser  Save pages fetched by the browser (to the same directory
                       as the output file).
  -v, --verbose        Increase verbosity (up to -vvv).

Config filename is required unless '--banks' is specified.

Note that if you are using the --debug-browser option, you should put the --output file in its own directory, since the program will dump a bunch of HTML pages in the same directory. (The directory will be created if it doesn't exist.)

Configuration

Create a JSON configuration file (config.json above) that contains a bank configuration or an array of bank configurations. Bank configurations usually need to contain the following items, see the output of banker --banks for exact settings required for a given bank.

• bankName - the name of the bank. This should be the name of the JavaScript file in lib/banks without the .js extension.

• username - your online banking username.

• password - your online banking password.

• securityQuestions - a hash of security questions and answers, like this:

"securityQuestions" : {
    "What is your favorite color?" : "Black"
}

• accounts - a list of account configurations. The required items vary by bank - use the output of banker --banks to determine which fields are required.

  If you are using the --debug-browser option, specify a filename field for each account, and this value will appear in the filenames of the HTML pages the program saves.

  Also, any additional data that you include in the account configurations will appear in the output file, so you can use this to pass identifier fields etc.

See the output of banker --banks or the files in the configs directory for more details about the configuration file.

Output

The program will write a JSON file to the path specified after --output, with the following structure:

[
    // object for first bank data
    {
        "bank"   : // bank name
        "status" : // may contain a message like "skipped"
        "error"  : // the error message for this bank, if any
        "data"   : [ // list of data objects, one for each account

            // account information (copied from config file)
            "account" : {
                // ...
            },

            // transactions downloaded from this bank
            "transactions" : [
                {
                    "date"        : // self-explanatory
                    "amount"      : // self-explanatory
                    "description" : // self-explanatory
                    "memo"        : // like a "sub-description" (if any)
                    "images"      : /* any images downloaded for this
                                       transaction (encoded as a data: url) */
                    "sourceId"    : /* transaction ID, from bank or
                                       generated from other fields */
                    // (transaction objects may also contain other fields)
                }, {
                    // ... (more transactions)
                }
            ],

            // balances downloaded from this bank
            "balances" : {
                "actual"    : // latest posted balance
                "available" : // available balance
                "fromList"  : /* balance from transaction list (hint: it's
                                 worth checking if this matches the other
                                 balances since some bank software is buggy) */
            }
        ]
    }, {
        // ... (data objects for more banks)
    }
]

Adding Banks

To add a new bank, write a driver for it and put it in the lib/banks directory. The filename of the driver will be the string used to specify that bank in a config file.

Drivers should inherit from BankSession (lib/banks/base.js) and should define the following methods:

MyBankSession.prototype.info = function() {
    // For documentation, return an object like this:
    return {
        description  : // Bank description
        configItems  : // Bank configuration items
        accountItems : // Configuration items needed for each account
    };
};

MyBankSession.prototype.login = function(cb) {
    // Try to log in to the bank website, then call:
    //  - cb(err)  on failure
    //  - cb(null) on success
};

MyBankSession.prototype.getTransactions = function(accountConfig, cb) {
    // Try to get transactions from the given account, and call cb(err) on
    // failure or cb(data) on success, where data is an object like this:
    var data = {
        transactions : // List of transactions downloaded from this bank, in
                       // the same format as the output file described above
        balances : // Balances downloaded from this bank
    };
};

MyBankSession.prototype.logout = function(cb) {
    // Try to log out of the bank website, then call:
    //  - cb(err)  on failure
    //  - cb(null) on success
};

Finally, drivers should export themselves as module.exports:

module.exports = MyBankSession;