The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Finance-Bank-Halifax-Sharedealing-0.03
River stage zero No dependents
++
/ Finance::Bank::Halifax::Sharedealing

NAME

Finance::Bank::Halifax::Sharedealing - access Halifax Sharedealing accounts from Perl.

VERSION

Version 0.03

SYNOPSIS

    use Finance::Bank::Halifax::Sharedealing;

    # Set up the login details
    my $sd = Finance::Bank::Halifax::Sharedealing->new(
        username => 'myusername',
        password => 'mysecretpassword',
        security_mother_first_name => 'Alice',
        security_father_first_name => 'Bob',
        security_school_name => 'Somewheretown Primary School',
        security_birthplace => 'Somewheretown',
    );

    $sd->log_in();

    # Get the user's accounts and print a brief statement for each one.
    my %accounts = $sd->get_all_accounts();
    foreach my $account_id (keys(%accounts)) {
        $sd->set_account($account_id);
        print "Account: " . $accounts{$account_id} . "\n";
        print "Available to invest: " . $sd->get_available_cash() . "\n";

        my @portfolio = $sd->get_portfolio();
        if (@portfolio) {
            print "Share\tValuation\n";
            foreach my $share (@portfolio) {
                print $share->{'symbol'} . "\t";
                print $share->{'valuation'} . "\n";
            }
        }
        print "\n";
    }

    $sd->log_out();

DESCRIPTION

This module provides an interface to the Halifax online share dealing service at https://www.halifaxsharedealing-online.co.uk/. It requires WWW::Mechanize, HTML::TokeParser, and either Crypt::SSLeay or IO::Socket::SSL.

METHODS

new(username => $u, password => $p, security_mother_first_name => $m, security_father_first_name => $f, security_school_name => $s, security_birthplace => $b)

Returns a new Sharedealing object.

The required arguments are the user's login details as a list of key/value pairs. Answers are required for all the possible security questions, as we don't know in advance which one the site will ask us.

log_in()

Log in, using the security details that were passed to new(). This will set the currently-selected account to the user's default account.

Returns true if logging in was successful.

log_out()

Log out by clicking the 'Sign Out' button.

Returns true if logging out was successful.

get_all_accounts()

Get all the accounts that can be managed from this user's login.

Returns a hash with account IDs (e.g. "D12345678") as the keys, and account names (e.g. "MR J SMITH, Halifax ShareBuilder 01") as the values.

set_account($account)

Set or change the account we're using.

$account: the account ID of the account to switch to.

Returns true if the account was successfully set, otherwise false.

get_account()

Get the ID of the account we're currently using.

Returns the account ID of the currently-selected account (or an empty string if there isn't a selected account yet).

get_portfolio()

Get a portfolio statement for the currently-selected account.

Returns an array. Each element of the array is a hash with the keys:

 symbol: the ticker symbol of the stock.
 exchange: the exchange on which the stock is listed.
 quantity: the number of shares owned.
 avg_cost: the average cost per share (in pence).
 latest_price: the latest quoted price per share (in pence).
 change: result of subtracting avg_cost from latest_price (in pence)
 book_cost: total cost of the holding (in pounds)
 valuation: value of the holding at the latest market price (in pounds).
 profit_loss_absolute: the profit or loss on the holding in pounds.
 profit_loss_percent: the profit or loss on the holding in percent.

All hash values are the raw contents of the data cell - you should not assume that any of them will be valid numbers.

get_available_cash()

Get the uninvested cash balance for the currently-selected account.

Returns the uninvested cash balance as a (ISO-8859-1) string, with currency symbol.

WARNING

Taken from Simon Cozens' Finance::Bank::LloydsTSB, because it's just as relevant here:

This is code for online banking, and that means your money, and that means BE CAREFUL. You are encouraged, nay, expected, to audit the source of this module yourself to reassure yourself that I am not doing anything untoward with your banking data. This software is useful to me, but is provided under NO GUARANTEE, explicit or implied.

AUTHOR

Rayner Lucas, <cpan at magic-cookie.co.uk>

BUGS

Please report any bugs or feature requests to bug-finance-bank-halifax-sharedealing at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Finance-Bank-Halifax-Sharedealing. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Finance::Bank::Halifax::Sharedealing

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to the CPAN authors whose modules made this one possible, and to Simon Cozens for Finance::Bank::LloydsTSB.

LICENSE AND COPYRIGHT

Copyright 2011 Rayner Lucas.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.