| 1 | =pod | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | Finance::Bank::CooperativeUKPersonal - Access to UK Cooperative personal | ||
| 6 | bank accounts | ||
| 7 | |||
| 8 | =head1 SYNOPSIS | ||
| 9 | |||
| 10 | use Finance::Bank::CooperativeUKPersonal | ||
| 11 | |||
| 12 | my $conf = { | ||
| 13 | sortCode => $sortCode, # numeric, without dashes, | ||
| 14 | accountNumber => $accountNumber, | ||
| 15 | securityCode => $securityCode, | ||
| 16 | memorableDate => $memorableDate, # dd/mm/yyyy | ||
| 17 | memorableName => $memorableName, | ||
| 18 | firstSchool => $firstSchool, | ||
| 19 | lastSchool => $lastSchool, | ||
| 20 | birthPlace => $birthplace | ||
| 21 | }; | ||
| 22 | |||
| 23 | # Connect to bank & login | ||
| 24 | my $bank = Finance::Bank::CooperativeUKPersonal->new($conf); | ||
| 25 | $bank->connect(); | ||
| 26 | |||
| 27 | # get account summary (all accounts table) | ||
| 28 | my $accounts = $bank->accountSummary(); | ||
| 29 | |||
| 30 | # get available statements for an account | ||
| 31 | # includes dated statements & recent items statement | ||
| 32 | my $statements = $bank->availableStatements( $accounts->[0] ); | ||
| 33 | |||
| 34 | # fetch a statement - dated or recent items | ||
| 35 | my $transactions = $bank->statement( $statements->[0] ); | ||
| 36 | |||
| 37 | =head1 DESCRIPTION | ||
| 38 | |||
| 39 | This module provides an interface to the Co-operative UK personal online banking website, | ||
| 40 | with access to recent transactions and statements. | ||
| 41 | |||
| 42 | =head1 METHODS | ||
| 43 | |||
| 44 | =head2 new, connect - combine to start your session | ||
| 45 | |||
| 46 | my $conf = { | ||
| 47 | sortCode => $sortCode, # numeric, without dashes, | ||
| 48 | accountNumber => $accountNumber, | ||
| 49 | securityCode => $securityCode, | ||
| 50 | memorableDate => $memorableDate, # dd/mm/yyyy | ||
| 51 | memorableName => $memorableName, | ||
| 52 | firstSchool => $firstSchool, | ||
| 53 | lastSchool => $lastSchool, | ||
| 54 | birthPlace => $birthplace | ||
| 55 | }; | ||
| 56 | |||
| 57 | # Connect to bank & login | ||
| 58 | my $bank = Finance::Bank::CooperativeUKPersonal->new($conf); | ||
| 59 | $bank->connect(); | ||
| 60 | |||
| 61 | C<new()> configures your connection, C<connect()> connects to the co-op website. The co-op | ||
| 62 | expires sessions after 10 minutes of inactivity, so C<connect()> can be used at any point to | ||
| 63 | reconnect. | ||
| 64 | |||
| 65 | =head2 accountSummary - summary listing of bank accounts | ||
| 66 | |||
| 67 | Parses the initial account summary table shown after logging into the Co-Op bank website. Returns | ||
| 68 | a reference to an array of account hashrefs. e.g. | ||
| 69 | |||
| 70 | $accounts = $bank->accountSummary(); | ||
| 71 | |||
| 72 | returns | ||
| 73 | |||
| 74 | $accounts = [ | ||
| 75 | { | ||
| 76 | 'accountNumber' => $accountNumber, | ||
| 77 | 'sortCode' => $sortCode, | ||
| 78 | 'href' => $href, | ||
| 79 | 'name' => $name, | ||
| 80 | 'availableBalance' => $balance | ||
| 81 | } | ||
| 82 | ]; | ||
| 83 | |||
| 84 | If your balance is in credit, the co-op appends 'CR' to the available balance. I do not know | ||
| 85 | how they indicate overdrawn accounts. | ||
| 86 | |||
| 87 | =head2 availableStatements - list of availalable statements for an account | ||
| 88 | |||
| 89 | Returns a list of available statements for an account as a reference to an array of hashrefs. | ||
| 90 | |||
| 91 | $statements = $bank->availableStatements($accounts->[0]); | ||
| 92 | |||
| 93 | returns | ||
| 94 | |||
| 95 | $statements = [ | ||
| 96 | { | ||
| 97 | 'name' => $name, | ||
| 98 | 'href' => $href | ||
| 99 | } | ||
| 100 | ]; | ||
| 101 | |||
| 102 | In the returned hashref, 'name' is either 'Recent Items' or the statement's issued date in | ||
| 103 | dd/mm/yyyy format. | ||
| 104 | |||
| 105 | =head2 statement - list of transaction rows in a statement | ||
| 106 | |||
| 107 | Returns a list of transactions in a statement as a reference to an array of hashrefs. | ||
| 108 | |||
| 109 | $transactions = $bank->statement($statements->[1]); | ||
| 110 | |||
| 111 | returns | ||
| 112 | |||
| 113 | $transactions = [ | ||
| 114 | { | ||
| 115 | 'reference' => $referenceString, | ||
| 116 | 'date' => $date, # 'dd/mm/yyyy', | ||
| 117 | 'withdrawal' => $withdrawal | ||
| 118 | 'deposit' => $deposit, | ||
| 119 | 'balance' => $balance # not present in recent items statement | ||
| 120 | }, | ||
| 121 | ]; | ||
| 122 | |||
| 123 | If your balance is in credit, the co-op appends 'CR' to the available balance. I do not know | ||
| 124 | how they indicate overdrawn accounts. | ||
| 125 | |||
| 126 | =head1 CAVEATS | ||
| 127 | |||
| 128 | As this module accesses your bank account, you should ensure you store your configuration data | ||
| 129 | and any received transaction information in a secure place. | ||
| 130 | |||
| 131 | =head1 AUTHOR | ||
| 132 | |||
| 133 | Stephen Patterson <steve@patter.me.uk> | ||
| 134 | |||
| 135 | =cut | ||
| 136 | |||
| 137 | package Finance::Bank::CooperativeUKPersonal; | ||
| 138 | |||
| 139 | use strict; | ||
| 140 | use warnings; | ||
| 141 | use Carp qw/croak/; | ||
| 142 | use WWW::Mechanize; | ||
| 143 | use HTML::DOM; | ||
| 144 | use File::Temp; | ||
| 145 | use Data::Dumper; | ||
| 146 | |||
| 147 | # Configure connection | ||
| 148 | sub new { | ||
| 149 | my $class = shift(); | ||
| 150 | my $self = {}; | ||
| 151 | my $params = shift(); | ||
| 152 | |||
| 153 | croak "sortCode required" unless ($params->{sortCode}); | ||
| 154 | croak "invalid sortCode, must be numeric" unless ($params->{sortCode} =~ /^\d+$/); | ||
| 155 | croak "accountNumber required" unless ($params->{accountNumber}); | ||
| 156 | croak "invalid accountNumber, must be numeric" unless ($params->{accountNumber} =~ /^\d+$/); | ||
| 157 | croak "memorableDate required" unless ($params->{memorableDate}); | ||
| 158 | croak "invalid memorableDate, must be dd/mm/yyyy" unless ($params->{memorableDate} =~ m|^\d{2}\/\d{2}\/\d{4}$|); | ||
| 159 | croak "memorableName required" unless ($params->{memorableName}); | ||
| 160 | croak "firstSchool required" unless ($params->{firstSchool}); | ||
| 161 | croak "lastSchool required" unless ($params->{lastSchool}); | ||
| 162 | croak "birthPlace required" unless ($params->{birthPlace}); | ||
| 163 | |||
| 164 | foreach my $key (keys(%{$params})) { | ||
| 165 | $self->{$key} = $params->{$key}; | ||
| 166 | } | ||
| 167 | |||
| 168 | $self->{siteAddress} = 'https://personal.co-operativebank.co.uk'; | ||
| 169 | $self->{linkBase} = $self->{siteAddress} . '/CBIBSWeb/'; | ||
| 170 | $self->{startPage} = $self->{linkBase} . 'start.do'; | ||
| 171 | |||
| 172 | $self->{mech} = new WWW::Mechanize(); | ||
| 173 | return bless $self, $class; | ||
| 174 | } | ||
| 175 | |||
| 176 | # Connect to the Co-op through their multi-factor auth screens | ||
| 177 | sub connect { | ||
| 178 | my $self = shift(); | ||
| 179 | |||
| 180 | ## Step 1, Fetch startpage, fill in sort code & account number | ||
| 181 | $self->{mech}->get($self->{startPage}); | ||
| 182 | my $res = $self->{mech}->submit_form( | ||
| 183 | form_name => 'loginForm', | ||
| 184 | fields => { | ||
| 185 | sortCode => $self->{sortCode}, | ||
| 186 | accountNumber => $self->{accountNumber} | ||
| 187 | }); | ||
| 188 | croak "Couldn't submit login form" unless $res->is_success; | ||
| 189 | |||
| 190 | ## Step 2, fill in security code, see what info we need next | ||
| 191 | if ($self->{mech}->content() =~ m/Enter the (\w+) and (\w+) digits/i) { | ||
| 192 | my $offsets = { | ||
| 193 | first => 0, | ||
| 194 | second => 1, | ||
| 195 | third => 2, | ||
| 196 | fourth => 3 | ||
| 197 | }; | ||
| 198 | |||
| 199 | my $digit1 = substr($self->{securityCode}, $offsets->{$1}, 1); | ||
| 200 | my $digit2 = substr($self->{securityCode}, $offsets->{$2}, 1); | ||
| 201 | |||
| 202 | ## Enter security code digits on form, next page asks for various secure information | ||
| 203 | ## return name of the page | ||
| 204 | my $res = $self->{mech}->submit_form( | ||
| 205 | form_name => 'passCodeForm', | ||
| 206 | fields => { | ||
| 207 | firstPassCodeDigit => $digit1, | ||
| 208 | secondPassCodeDigit => $digit2 | ||
| 209 | }); | ||
| 210 | croak "Couldn't submit security code" unless $res->is_success; | ||
| 211 | |||
| 212 | if ($self->{mech}->content() =~ /Memorable date/) { | ||
| 213 | # Were asked to enter memorable date | ||
| 214 | my ($day, $month, $year) = split('/', $self->{memorableDate}); | ||
| 215 | my $res = $self->{mech}->submit_form( | ||
| 216 | form_name => 'loginSpiForm', | ||
| 217 | fields => { | ||
| 218 | memorableDay => $day, | ||
| 219 | memorableMonth => $month, | ||
| 220 | memorableYear => $year | ||
| 221 | }); | ||
| 222 | croak "Couldn't submit Memorable Date" unless $res->is_success; | ||
| 223 | } elsif ($self->{mech}->content() =~ /firstschool/) { | ||
| 224 | # Were asked to enter first school | ||
| 225 | my $res = $self->{mech}->submit_form( | ||
| 226 | form_name => 'loginSpiForm', | ||
| 227 | fields => { | ||
| 228 | firstSchool => $self->{firstSchool} | ||
| 229 | }); | ||
| 230 | croak "Couldn't submit last school" unless $res->is_success; | ||
| 231 | } elsif ($self->{mech}->content() =~ /lastschool/) { | ||
| 232 | # asked for last school | ||
| 233 | my $res = $self->{mech}->submit_form( | ||
| 234 | form_name => 'loginSpiForm', | ||
| 235 | fields => { | ||
| 236 | lastSchool => $self->{lastSchool} | ||
| 237 | }); | ||
| 238 | croak "Couldn't submit last school" unless $res->is_success; | ||
| 239 | } elsif ($self->{mech}->content() =~ /birthPlace/) { | ||
| 240 | # birthplace | ||
| 241 | my $res = $self->{mech}->submit_form( | ||
| 242 | form_name => 'loginSpiForm', | ||
| 243 | fields => { | ||
| 244 | birthPlace => $self->{birthPlace} | ||
| 245 | }); | ||
| 246 | croak "Couldn't submit birthplace" unless $res->is_success; | ||
| 247 | } elsif ($self->{mech}->content() =~ /memorableName/) { | ||
| 248 | # memorable name | ||
| 249 | my $res = $self->{mech}->submit_form( | ||
| 250 | form_name => 'loginSpiForm', | ||
| 251 | fields => { | ||
| 252 | memorableName => $self->{memorableName} | ||
| 253 | }); | ||
| 254 | croak "Couldn't submit memorable name" unless $res->is_success; | ||
| 255 | } else { | ||
| 256 | croak "The 2-factor authentication requested was not of a recognised type"; | ||
| 257 | } | ||
| 258 | |||
| 259 | # Invalid security info, redo from start | ||
| 260 | if ($self->{mech}->content() =~ /security information.*incorrect/) { | ||
| 261 | croak "invalid security information entered"; | ||
| 262 | } | ||
| 263 | |||
| 264 | # bypass interstitial | ||
| 265 | if ($self->{mech}->content() =~ /linearButtonNavigationForm/) { | ||
| 266 | $self->{mech}->submit_form( | ||
| 267 | #formName => 'linearButtonNavigationForm' | ||
| 268 | ); | ||
| 269 | } | ||
| 270 | } else { | ||
| 271 | croak "Did not receive security code entry page"; | ||
| 272 | } | ||
| 273 | return 1; | ||
| 274 | } | ||
| 275 | |||
| 276 | |||
| 277 | ############################################################################################ | ||
| 278 | ## Inner information pages | ||
| 279 | |||
| 280 | # Account summary table - the 1st page seen after logging in | ||
| 281 | sub accountSummary { | ||
| 282 | my $self = shift(); | ||
| 283 | my @summary = (); | ||
| 284 | |||
| 285 | # to parse via HTML::DOM, need to save content as a file | ||
| 286 | my $fh = File::Temp->new(); | ||
| 287 | print $fh $self->{mech}->content(); | ||
| 288 | my $tmpNam = $fh->filename; | ||
| 289 | $fh->close; | ||
| 290 | |||
| 291 | my $dom = HTML::DOM->new(); | ||
| 292 | $dom->parse_file( $tmpNam ); | ||
| 293 | |||
| 294 | # Descend into content, find table containing summary data | ||
| 295 | # 4th child (table) of <td class="sidebar" width="80%"> | ||
| 296 | my $summaryTable; | ||
| 297 | foreach my $td ($dom->getElementsByTagName('td')) { | ||
| 298 | if ($td->getAttribute('class') eq 'sidebar' && $td->getAttribute('width') eq '80%') { | ||
| 299 | my $rightChildren = $td->getElementsByTagName ( 'table' ); | ||
| 300 | $summaryTable = $rightChildren->[3]->getElementsByTagName('table')->[0]; | ||
| 301 | |||
| 302 | |||
| 303 | foreach my $row ($summaryTable->getElementsByTagName('tr')) { | ||
| 304 | my $account = {}; | ||
| 305 | my $columns = $row->childNodes(); | ||
| 306 | |||
| 307 | for (my $i = 0; $i < $columns->length; ++$i) { | ||
| 308 | my $text = $columns->[$i]->as_text; | ||
| 309 | $text =~ s/\s+//g; | ||
| 310 | $text =~ s/\x{a3}//; | ||
| 311 | chomp($text); | ||
| 312 | if ($i == 1) { | ||
| 313 | $account->{name} = $text; | ||
| 314 | foreach my $node ($columns->[$i]->childNodes()) { | ||
| 315 | #print ref $node, "\n"; | ||
| 316 | if (ref $node eq 'HTML::DOM::Element::A' && | ||
| 317 | $node->getAttribute('href') =~ /^balances\.do/) { | ||
| 318 | $account->{href} = $self->{linkBase} . $node->getAttribute('href'); | ||
| 319 | |||
| 320 | } | ||
| 321 | } | ||
| 322 | } elsif ($i == 3) { | ||
| 323 | #unless($text =~ /CR$/) { | ||
| 324 | # $text = '-' . $text; | ||
| 325 | #} | ||
| 326 | $text =~ s/[A-Z]+$//; | ||
| 327 | $account->{availableBalance} = $text; | ||
| 328 | } elsif ($i == 7) { | ||
| 329 | $text =~ s/-//g; | ||
| 330 | $account->{sortCode} = $text; | ||
| 331 | } elsif ($i == 9) { | ||
| 332 | $account->{accountNumber} = $text; | ||
| 333 | } | ||
| 334 | } | ||
| 335 | push @summary, $account; | ||
| 336 | } | ||
| 337 | } | ||
| 338 | } | ||
| 339 | |||
| 340 | shift(@summary); | ||
| 341 | return \@summary; | ||
| 342 | } | ||
| 343 | |||
| 344 | |||
| 345 | ## Get a list of available statements on an account | ||
| 346 | sub availableStatements { | ||
| 347 | my ($self, $account) = @_; | ||
| 348 | |||
| 349 | $self->{mech}->get($account->{href}); | ||
| 350 | my $links = $self->{mech}->find_link('url_regex' => qr/statementsSummary/); | ||
| 351 | |||
| 352 | # this is the page of an account's statements | ||
| 353 | $self->{mech}->get($links->[0]); | ||
| 354 | |||
| 355 | my @statements; | ||
| 356 | # recent items | ||
| 357 | #my $recent = { | ||
| 358 | # name => 'Recent Items', | ||
| 359 | # href => $account->{href} | ||
| 360 | #}; | ||
| 361 | my $recentLink= $self->{mech}->find_link('url_regex' => qr/domesticRecentItems/); | ||
| 362 | my $tmp = { | ||
| 363 | name => $recentLink->text(), | ||
| 364 | href => $self->{siteAddress} . $recentLink->url() | ||
| 365 | }; | ||
| 366 | push @statements, $tmp; | ||
| 367 | |||
| 368 | # Main statement links | ||
| 369 | my @statementLinks = $self->{mech}->find_all_links('url_regex' => qr/getDomesticStatement/); | ||
| 370 | foreach my $link (@statementLinks) { | ||
| 371 | if ($link->text() =~ m|^\d{2}\/\d{2}\/\d{4}$|) { | ||
| 372 | my $tmp = { | ||
| 373 | name => $link->text(), | ||
| 374 | href => $self->{siteAddress} . $link->url() | ||
| 375 | }; | ||
| 376 | push @statements, $tmp; | ||
| 377 | } | ||
| 378 | } | ||
| 379 | return \@statements; | ||
| 380 | } | ||
| 381 | |||
| 382 | sub statement { | ||
| 383 | my $self = shift(); | ||
| 384 | my $statement = shift(); | ||
| 385 | |||
| 386 | #print "Fetching: ", $statement->{href}, "\n"; | ||
| 387 | $self->{mech}->get($statement->{href}); | ||
| 388 | if (! $self->{mech}->success()) { | ||
| 389 | print "HTTP ", $self->{mech}->status(), "\n"; | ||
| 390 | print Dumper($self->{mech}->response()), "\n"; | ||
| 391 | } | ||
| 392 | |||
| 393 | #print $self->{mech}->content(); | ||
| 394 | |||
| 395 | # to parse via HTML::DOM, need to save content as a file | ||
| 396 | my $fh = File::Temp->new(); | ||
| 397 | print $fh $self->{mech}->content(); | ||
| 398 | my $tmpNam = $fh->filename; | ||
| 399 | $fh->close; | ||
| 400 | |||
| 401 | my $dom = HTML::DOM->new(); | ||
| 402 | $dom->parse_file( $tmpNam ); | ||
| 403 | |||
| 404 | # Descend into content, find table containing summary data | ||
| 405 | # 4th or 5th child (table) of <td class="sidebar" width="80%"> | ||
| 406 | # remember, we're parsing HTML so may change if Co-op regen the pages | ||
| 407 | my $outerTable; | ||
| 408 | my $innerTable; | ||
| 409 | if ($statement->{name} eq 'Recent Items') { | ||
| 410 | $outerTable = 3; | ||
| 411 | $innerTable = 0; | ||
| 412 | } else { | ||
| 413 | $outerTable = 3; | ||
| 414 | $innerTable = 0; | ||
| 415 | #$outerTable = 2; | ||
| 416 | #$innerTable = 2; | ||
| 417 | } | ||
| 418 | |||
| 419 | my @transactions; | ||
| 420 | foreach my $td ($dom->getElementsByTagName('td')) { | ||
| 421 | if ($td->getAttribute('class') eq 'sidebar' && $td->getAttribute('width') eq '80%') { | ||
| 422 | my $rightChildren = $td->getElementsByTagName ( 'table' ); | ||
| 423 | my $summaryTable = $rightChildren->[$outerTable]->getElementsByTagName('table') | ||
| 424 | ->[$innerTable]; | ||
| 425 | |||
| 426 | |||
| 427 | foreach my $row ($summaryTable->getElementsByTagName('tr')) { | ||
| 428 | my $account = {}; | ||
| 429 | my $columns = $row->childNodes(); | ||
| 430 | |||
| 431 | for (my $i = 0; $i < $columns->length; ++$i) { | ||
| 432 | my $text = $columns->[$i]->as_text; | ||
| 433 | $text =~ s/\s+//g; | ||
| 434 | $text =~ s/\x{a3}//; | ||
| 435 | chomp($text); | ||
| 436 | if ($i == 1) { | ||
| 437 | # transaction date | ||
| 438 | $account->{date} = $text; | ||
| 439 | } elsif ($i == 3) { | ||
| 440 | # transaction reference | ||
| 441 | $account->{reference} = $text; | ||
| 442 | } elsif ($i == 5) { | ||
| 443 | # deposit | ||
| 444 | $account->{deposit} = $text; | ||
| 445 | } elsif ($i == 7) { | ||
| 446 | $account->{withdrawal} = $text; | ||
| 447 | } elsif ($i == 9) { | ||
| 448 | $account->{balance} = $text; | ||
| 449 | } | ||
| 450 | } | ||
| 451 | # don't include the table header row in returned results | ||
| 452 | if ($account->{reference} !~ /LastStatement/ | ||
| 453 | && $account->{reference} !~/Transaction/) { | ||
| 454 | push @transactions, $account; | ||
| 455 | } | ||
| 456 | } | ||
| 457 | |||
| 458 | } | ||
| 459 | } | ||
| 460 | |||
| 461 | return \@transactions; | ||
| 462 | } | ||
| 463 | 1; |