File Coverage

blib/lib/Business/BankAccount/NZ.pm

Criterion	Covered	Total	%
statement	12	192	6.2
branch	0	54	0.0
condition	0	30	0.0
subroutine	4	16	25.0
pod	4	12	33.3
total	20	304	6.5

package Business::BankAccount::NZ;

# name:     $RCSfile: NZ.pm,v $
# process:  Validates bank account numbers (See below)
# author:   John Bolland, Becky Alcorn, Simon Taylor
# revision: $Id: NZ.pm,v 1.4 2003/01/07 00:29:49 simon Exp $

=head1 NAME

B - validates New Zealand bank account numbers

=head1 SYNOPSIS

  use Business::BankAccount::NZ;

  # Returns a hash table with bank data in it (if specified)
  my $nz = Business::BankAccount::NZ->new(
      bank_no => '030510',
      account_no => '072049700'
  );

  # Or set the bank and account numbers independantly of new()
  my $nz = Business::BankAccount::NZ->new();
  $nz->set_bank_no('086523');
  $nz->set_account_no('1954512001');

  # Either way, you'd validate the account number with...
  $nz->validate() or die "$nz->{error_string}";

  print $nz->{error_string} if ($nz->{error});

  print "The bank name is " . $nz->{bank_name} . "\n";

=head1 DESCRIPTION

This module provides validation on New Zealand bank account numbers.

The extent of the validation is simply that the account number is checked
to ensure that it conforms with the notion of an account number laid out
in the 'Bank Account Number Check Digit Validation Routines' brochure prepared
by the Bank of New Zealand, dated 27 October, 1999.

Thus the module does not tell you whether or not a given bank account number
is an B account known to the bank, just that it is a B number
according to their rules.

The module uses validation code developed by John Bolland.

=head1 METHODS

=cut

require 5;
use Carp;
use strict;
use warnings;
use vars qw($VERSION);
$VERSION = "0.02";
my $module = "NZ.pm";

=head2 new

The minimum invocation is:

  use Business::BankAccount::NZ;
  $nz = Business::BankAccount::NZ->new(
      bank_no => '033565',
      account_no => '384642737'
  );
  $nz->validate();

=cut

sub new
{
    my ($class, %arg) = @_;

    #
    # Bless an anonymous hash for this class and new() will return a
    # reference to it
    #

    my $self = {};
    $self->{bank_no} = $arg{bank_no} if ($arg{bank_no});
    $self->{account_no} = $arg{account_no} if ($arg{account_no});
    $self->{bank_name} = "";
    $self->{res} = '';

    bless($self, $class);

    return $self;
}

=head2 set_bank_no

Sets the bank number against whose rules we wish to validate an account number.

  $nz->set_bank_no('168392');

=cut

sub set_bank_no {
    my ($self, $bank_no) = @_;
    $self->{bank_name} = "";
    $self->{bank_no} = $bank_no;
}

=head2 set_account_no

Sets the account number we wish to validate.

    $nz->set_account_no('02836723000');

=cut

sub set_account_no {
    my ($self, $account_no) = @_;
    $self->{res} = 0;
    $self->{account_no} = $account_no;
}

=head2 validate

  $nz->validate();

This method checks the bank number and validates the account number.

The validation is based rules set out in the 'Bank Account Number Check Digit
Validation Routines' brochure prepared by the Bank of New Zealand,
dated 27 October, 1999.

The "error" and "error_string" attributes are set if validate() fails. The
"bank_name" attribute contains the bank name identified by the bank number.

  $nz->validate() or die "$nz->{error_string}";
  print $nz->{error_string} if ($nz->{error});

  print "The bank name is " . $nz->{bank_name} . "\n";

=cut

#
# Returns 0 and an error message if failed, or 1 and '' if success
#
sub validate {
    my ($self, $account_no) = @_;

    $self->{error} = 0;
    $self->{error_string} = "";
    $self->{res} = '';

    # Check for an account number
    if (!$account_no && !$self->{account_no}) {
	$self->{error} = 1;
	$self->{error_string} = "No account number specified";
        return 0;
    }

    # Check the length of the account number
    my $len = length($self->{account_no});
    if ($len < 8 || $len > 10) {
	$self->{error} = 1;
	$self->{error_string} =
     "Account number must be from 8 to 10 characters long: $self->{account_no}";
	return 0;
    }

    # Check for a bank number
    if (!$self->{bank_no}) {
	$self->{error} = 1;
	$self->{error_string} = "No bank number specified";
	return 0;
    }

    # Check length of bank number
    if (length ($self->{bank_no}) != 6) {
	$self->{error} = 1;
	$self->{error_string} =
           "Bank number must be six characters long: $self->{bank_no}";
	return 0;
    }


    # $self->{bank} is bk
    # $self->{branch} is br
    # $self->{account} is ac
    # $self->{suffix} is as

    # Determine the bank and do initial validation
    $self->{bank} = substr($self->{bank_no}, 0, 2);
    # Minor validation of bank number
    if (($self->{bank} < 0) || ($self->{bank} > 32 && $self->{bank} != 38)) {
	$self->{error} = 1;
	$self->{error_string} = "The bank must be a valid bank number: $self->{bank}";
	return 0;
    }
    # Determine the branch and do initial validation
    ($self->{branch} = $self->{bank_no}) =~ s/^.{2}//;
    # Determine the account (minus suffix) and do initial validation
    $self->{account} = substr($self->{account_no},0, 7);
    # Determine the suffix and do initial validation
    ($self->{suffix} = $self->{account_no}) =~ s/^.{7}//;

    # Choose the bank and validate accordingly
    if ($self->{bank} eq '08') {
	$self->{bank_name} = "National Australia Bank";
	nab_account($self);
	return 0 if ($self->{error});
    } elsif ($self->{bank} eq '09') {
	$self->{bank_name} = "Reserve Bank";
	rb_account($self);
	return 0 if $self->{error};
    } elsif ($self->{bank} eq '29') {
	$self->{bank_name} = "United Bank";
	ub_account($self);
	return 0 if ($self->{error});
    } elsif ($self->{bank} eq '25') {
	$self->{bank_name} = "CountryWide and Rural Banks";
	cwrb_account($self);
	return 0 if ($self->{error});
    } elsif ($self->{bank} eq '04' || $self->{bank} eq '05' ||
             $self->{bank} eq '07' || $self->{bank} eq '10' ||
             $self->{bank} eq '26' || $self->{bank} eq '28' ||
             $self->{bank} eq '33') {
	# Not supported banks
	$self->{error} = 2;
	$self->{error_string} = "This bank not supported: $self->{bank}";
	return 0;
    } else {
	# Anything else (including Bank of NZ)
	$self->{bank_name} = "Other Banks";
	other_account($self);
	return 0 if ($self->{error});
    }

    return 1;
}

#-------------------------------------------------------------------------
# Subroutines for validating the various account numbers
#

# National Australia Bank
#
# Each digit is multiplied by a corresponding value in the @vals array
# and added to the total.  The total is then divided by 11.  If there
# is a remainer then the account number is invalid.
#
sub nab_account($) {
    my ($self) = @_;
    # Get account digits in an array
    my @acc = get_acc_array($self->{account_no});
    # Values by which to multiply the digits
    my @vals = (7, 6, 5, 4, 3, 2, 1);
    my $res = 0;
    # The suffix
    my $suff = $self->{suffix};

    # We only deal with suffixes 3 digits long
    if (length($suff) == 3) {
	# Multiply each values and add to result
        for (my $i = 0; $i < scalar(@vals); $i++) {
	    $res += ($acc[$i] * $vals[$i]);
        }

	# For debugging purposes
	$self->{res} = $res;

	# Mod the result by 11
        #$res = ($res / 11) - int($res / 11);
	$res = $res % 11;
    } else {
	# Suffix not 3 digits long
	$self->{error} = 3;
	$self->{error_string} = "Invalid suffix: $suff";
	return 0;
    }

    # If the result is 0 the its a valid account number
    if ($res == 0) {
        return 1;
    } else {
	# Result was not 0 so return an error
	$self->{error} = 1;
	$self->{error_string} = "Invalid account number: $self->{account_no}";
	return 0;
    }
}

# Reserve Bank
#
# Each digit is multiplied by a corresponding value in the @vals array.
# If the result is more than 1 digit long then the digits are added together
# and that result is added to the total.  The total is then divided by 11.  If there
# is a remainer then the account number is invalid.
#
sub rb_account($) {
    my ($self) = @_;
    # Get the account number digits
    my @acc = get_acc_array($self->{account_no});
    # The suffix
    my $suff = $self->{suffix};
    # The values by which the account number digits are multiplied
    my @vals = (0, 0, 0, 5, 4, 3, 2);
    my $res = 0;
    # We only deal with suffixes of one digit
    if (length($suff) == 1) {
	# Do the multiplications and if a number is larger than one digit
        # then add the digits together.
	for (my $i = 0; $i < scalar(@vals); $i++) {
	    $res += multi_add($acc[$i], $vals[$i]);
 	}

	# Add the suffix to the result
	$res += $suff;

	# For debugging
	$self->{res} = $res;

	# Modules the result by 11
        #$res = ($res / 11) - int($res / 11);
	$res = $res % 11;
    } else {
	# Suffix was not 1 digit
	$self->{error} = 5;
	$self->{error_string} = "Invalid suffix: $suff";
	return 0;
    }

    # If the result is 0 then its a valid account number
    if ($res == 0) {
        return 1;
    } else {
	# Result was not 0 so return an error
	$self->{error} = 1;
	$self->{error_string} = "Invalid account number: $self->{account_no}";
	return 0;
    }
}

# United Bank
# NOTE: uses multi_add2 not multi_add
#
# Each digit of the account number and the suffix is multiplied by a corresponding
# value in the @vals or @vals2 arrays.  If the result is more than 1 digit long then
# the digits are added together until the result is only 1 digit long, and that result
# is added to the total.  The total is then divided by 10.  If there is a remainer
# then the account number is invalid.
#
sub ub_account($) {
    my ($self) = @_;
    # Get the digits of the account number
    my @acc = get_acc_array($self->{account_no});
    # The suffix
    my $suff = $self->{suffix};
    # Get the digits of the suffix
    my @suffs = get_acc_array($suff);
    # Values to multiply the account number digits by
    my @vals = (1, 3, 7, 1, 3, 7, 1);
    # Values to multiply the suffix digits by
    my @vals2 = (3, 7, 1);
    my $res = 0;

    # Validate the suffix
    if (length($suff) == 3) {
	# Do the multiplications and if a number is larger than one digit
        # then add the digits together until there is only one digit.

	# Account number digits
	for (my $i = 0; $i < scalar(@vals); $i++) {
	    $res += multi_add2($acc[$i], $vals[$i]);
 	}
	# Suffix digits
	for (my $i = 0; $i < scalar(@vals2); $i++) {
	    $res += multi_add2($suffs[$i], $vals2[$i]);
 	}

	# For debugging
	$self->{res} = $res;

	# Modules the result by 10
        #$res = ($res / 10) - int($res / 10);
	$res = $res % 10;

    } else {
	# Suffix wasn't 3 digits, so error
	$self->{error} = 3;
	$self->{error_string} = "Invalid suffix: $suff";
        return 0;
    }

    # If the result was zero then the account number is good
    if ($res == 0) {
        return 1;
    } else {
	# Result was not zero so error
	$self->{error} = 1;
	$self->{error_string} = "Invalid account number: $self->{account_no}";
	return 0;
    }

}

# CountryWide and Rural banks
#
# Each digit is multiplied by a corresponding value in the @vals array
# and the result is added to the total.  The total is then divided by 10.  If there
# is a remainer then the account number is invalid.
#
sub cwrb_account($) {
    my ($self) = @_;
    # The account number digits
    my @acc = get_acc_array($self->{account_no});
    # The suffix
    my $suff = $self->{suffix};
    # The values to multiply with
    my @vals = (1, 7, 3, 1, 7, 3, 1);
    my $res = 0;

    # Validate the suffix
    if (length($suff) == 3) {
	# Do the multiplications
	for (my $i = 0; $i < scalar(@vals); $i++) {
	    $res += ($acc[$i] * $vals[$i]);
 	}

	# Debugging
	#self->{res} = $res;

	# Mod the result
        #$res = ($res / 10) - int($res / 10);
	$res = $res % 10;
    } else {
	# Suffix wasn't 3 digits, so error
	$self->{error} = 3;
	$self->{error_string} = "Invalid suffix: $suff";
        return 0;
    }

    # If the result is 0 then the account number is good
    if ($res == 0) {
        return 1;
    } else {
	# The result wasn't 0, so error
	$self->{error} = 1;
	$self->{error_string} = "Invalid account number: $self->{account_no}";
	return 0;
    }

}

# The normal case (21 banks)
#
# Each digit of the account number and the branch is multiplied by a corresponding
# value in the @vals or @vals2 arrays and the result is added to the total.  The
# total is then divided by 11.  If there is a remainer then the account number
# is invalid.
#
# Banks include:
# 01, 02, 03, 06, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 27, 30 and 31
sub other_account($) {
    my ($self) = @_;
    # Get the account number digits
    my @acc = get_acc_array($self->{account_no});
    # Get the branch number digits
    my @branch = get_acc_array($self->{branch});
    # Get the suffix
    my $suff = $self->{suffix};
    # Values to multiply the branch digits with
    my @vals = (6, 3, 7, 9);
    # Values to multiply the account digits with
    my @vals2 = (0, 10, 5, 8, 4, 2, 1);
    my $res = 0;

    # Validate the suffix
    if (length($suff) == 2) {
	# Do the multiplications
	# Branch
	for (my $i = 0; $i < scalar(@vals); $i++) {
	    $res += ($branch[$i] * $vals[$i]);
 	}
	# Account
	for (my $i = 0; $i < scalar(@vals2); $i++) {
	    $res += ($acc[$i] * $vals2[$i]);
 	}

	# Debugging
	$self->{res} = $res;

	# Mod the result with 11
        #$res = ($res / 11) - int($res / 11);
	$res = $res % 11;
    } else {
	# The suffix was not 2 digits, so error
	$self->{error} = 4;
	$self->{error_string} = "Invalid suffix: $suff";
        return 0;
    }

    # If the result was 0 the the account number is valid
    if ($res == 0) {
        return 1;
    } else {
	# Result was not zero so error
	$self->{error} = 1;
	$self->{error_string} = "Invalid account number: $self->{account_no}";
	return 0;
    }
}

# Return the account number as an array
sub get_acc_array($) {
    my ($acc_no) = @_;
    return split('', $acc_no);
}

# Multiply the two numbers together and add up any extra digits once.
sub multi_add($$) {
    my ($a, $b) = @_;
    my $prod = $a * $b;
    my $res = 0;
    my @nums = split('', $prod);

    foreach my $c (@nums) {
	$res += $c;
    }
    return $res;
}

# Multiply the two numbers together and add up any extra digits
# until you have only one digit.
sub multi_add2($$) {
    my ($a, $b) = @_;
    my $prod = $a * $b;
    my $res = $prod;
    my @nums = split('', $prod);
    while($#nums >= 1) {
	$res = 0;
	foreach my $c (@nums) {
	    $res += $c;
	}
	@nums = split('', $res);
    }
    return $res;
}
1;

=head1 DISCLAIMER

This program is distributed in the hope that it will be useful,
but B; without even the implied warranty of
B or B.

But do let us know if it gives you any problems.

=head1 AUTHORS

    Becky Alcorn, Unisolve Pty Ltd
    Simon Taylor, Unisolve Pty Ltd
    John Bolland, Mainzeal Property and Construction Ltd

Copyright 2002, Unisolve Pty Ltd All rights reserved

This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

Address bug reports and comments to: [e-mail]

=head1 SEE ALSO

Business::CreditCard

=cut

__END__