antoineaugusti/moduluschecking

Check that a UK bank account number is valid using the VocaLink UK specification

Modulus checking

Modulus checking is a procedure for validating sort code and account number combinations. It doesn't confirm that an account belongs to a customer or supports Direct Debit.

If you want to know more about modulus checking, read this GoCardless guide.

Validity

This package follows the Vocalink specification, version 5.50, that will be live on 18/03/2019. More information about the specification can be seen on the Vocalink website.

API

If you prefer to send request to a web service, take a look at the package moduluschecking-api that offers an API to validate UK bank account numbers, supporting authentication and rate limits.

Institution covered

The following institutions are supported:

• Allied Irish
• Bank of England
• Bank of Ireland
• Bank of Scotland
• Barclays
• Bradford and Bingley Building Society
• Charity Bank
• Citibank
• ClearBank
• Clydesdale
• Co-Operative Bank
• Contis Financial Services
• Coutts
• First Trust
• HSBC
• HSBC
• Halifax
• Hoares Bank
• Lloyds
• Metro Bank
• NatWest
• Nationwide Building Society
• Northern
• Orwell Union Ltd
• Royal Bank of Scotland
• Santander
• Secure Trust
• Starling Bank
• TSB
• Tesco Bank
• Ulster Bank
• Unity Trust Bank
• Virgin Bank
• Woolwich
• Yorkshire Bank

Included data files

This package ships with the latest version of the modulus weight table data and the sorting code substitution data. Both files can be found in the data folder.

Getting started

You can grab this package with the following command:

go get github.com/AntoineAugusti/moduluschecking/...

Usage

If you wanna use the default file parser:

package main

import (
    "fmt"

    "github.com/AntoineAugusti/moduluschecking/models"
    "github.com/AntoineAugusti/moduluschecking/parsers"
    "github.com/AntoineAugusti/moduluschecking/resolvers"
)

func main() {
    // Read the modulus weight table and the sorting
    // code substitution table from the folder data
    parser := parsers.CreateFileParser()

    // The resolver handles the verification of the validity of
    // bank accounts according to the data obtained by the parser
    resolver := resolvers.NewResolver(parser)

    // This helper method handles special cases for
    // bank accounts from:
    // - National Westminster Bank plc (10 or 11 digits with possible presence of dashes, for account numbers)
    // - Co-Operative Bank plc (10 digits for account numbers)
    // - Santander (9 digits for account numbers)
    // - banks with 6 or 7 digits for account numbers
    bankAccount := models.CreateBankAccount("089999", "66374958")

    // Check if the created bank account is valid against the rules
    fmt.Println(resolver.IsValid(bankAccount))
}

Benchmark

On my personal laptop (MacBook Pro, Core i5 2.5 Ghz, 8 GB of RAM with a SSD):

• reading data files from the filesytem by creating the parser and the resolver: ~350 ms
• checking the validity of 1,000 bank account numbers: ~7 ms

moduluschecking's Issues

README link for modulus checking

The links has changed to https://www.vocalink.com/tools/modulus-checking/

Incorrect handling of 9 digit account numbers for non-Santander sort codes

Hi, I am leaving an issue on a few of the modulus checking libraries on Github as they all seem to have the same issue (including our implementation at Monzo Bank). While the Vocalink modulus checking requirements specifically call out that Santander is the only bank that has 9 digit account numbers we have noticed that in practice other banks may also use 9 digit account numbers.

Specifically Coventry Building Society has this information in their FAQ

We use 9 digit account numbers - simply remove the first digit when giving your account number

The best way we thought of handling this would be to specifically use the documented logic in the modulus checking requirements only for sort codes used by Santander. For other 9 digit account numbers we simply remove the leading digit.

Based on this page we have defined this range as

090000-091900
720000-729999
890000-892999
165710

I hope this information helps, let me know if you have any other questions!

Check bank account alone(no sortcode)

Would be possible to check the validity of a bank account without a sortcode? (perhaps returning a confidence level)