UkModulus

UK bank account modulus checking for Elixir. Validates UK sort code and account number combinations using the official Vocalink algorithm.

Features

• Validates UK bank account numbers against sort codes
• Ships with official Vocalink data (1,151 weight rules)
• Supports MOD10, MOD11, and DBLAL algorithms
• Handles all Vocalink exceptions (1-14)
• Fast concurrent access via ETS
• Optional auto-update from Vocalink's website

Installation

Add uk_modulus to your list of dependencies in mix.exs:

def deps do
  [
    {:uk_modulus, "~> 0.1.0"}
  ]
end

Usage

Basic Validation

# Returns {:ok, true} if valid, {:ok, false} if invalid
UkModulus.validate("20-00-00", "12345678")
# => {:ok, true} or {:ok, false}

# Simple boolean check
UkModulus.valid?("200000", "12345678")
# => true or false

Format Handling

The library accepts sort codes in various formats:

UkModulus.validate("200000", "12345678")   # Plain 6 digits
UkModulus.validate("20-00-00", "12345678") # With dashes
UkModulus.validate("20 00 00", "12345678") # With spaces

Account numbers can be 6, 7, or 8 digits (shorter numbers are zero-padded):

UkModulus.validate("200000", "12345678")  # 8 digits
UkModulus.validate("200000", "1234567")   # 7 digits (padded to 01234567)
UkModulus.validate("200000", "123456")    # 6 digits (padded to 00123456)

Error Handling

UkModulus.validate("123", "12345678")
# => {:error, :invalid_sort_code_format}

UkModulus.validate("200000", "123")
# => {:error, :invalid_account_number_format}

Unknown Sort Codes

Sort codes not in the Vocalink data return {:ok, true} to allow validation by downstream payment processors:

UkModulus.validate("999999", "12345678")
# => {:ok, true}

Configuration

Auto-Update (Optional)

By default, the library uses bundled Vocalink data. To enable automatic updates from Vocalink's website:

# config/config.exs
config :uk_modulus, auto_update: true

When enabled, the library checks for updates every 30 days.

Manual Refresh

Force a refresh of data from Vocalink:

UkModulus.refresh()

How It Works

The library implements the UK Modulus Checking algorithm as specified by Vocalink (now part of Mastercard). This algorithm validates that a sort code and account number combination could be legitimate.

Algorithms

• MOD10: Standard modulus 10 check
• MOD11: Standard modulus 11 check
• DBLAL: Double alternate (Luhn-like) algorithm

Data Source

The weight table data comes from Vocalink's official modulus checking specification. The library ships with this data bundled in priv/data/.

• valacdos.txt - Weight table with 1,151 rules
• scsubtab.txt - Sort code substitution table for exception handling

Official source: https://www.vocalink.com/tools/modulus-checking/

Limitations

• This validation catches typos and obvious errors but does not guarantee the account exists
• Some valid accounts may fail validation due to exceptions not yet implemented
• Always use this as a first-pass check before sending to your payment processor

License

MIT License. See LICENSE for details.

Acknowledgments

• Vocalink/Mastercard for the modulus checking specification and data
• Inspired by similar libraries in other languages