bsb-validate (Python)

Validate, format, decode, and look up Australian BSB (Bank State Branch) numbers in Python.

• ✅ Offline validation — no network call needed to check format
• 🔎 Full lookups — bank, branch, address and payment capabilities via the free BSBFinder API
• 🧩 Zero dependencies (standard library only)
• 🐍 Python 3.8+

BSB numbers are the six-digit codes that route domestic bank transfers in Australia. This library helps you validate them before submitting a payment, decode their structure, and fetch full branch details on demand.

Install

pip install bsb-validate

Quick start

from bsb_validate import validate_bsb, format_bsb, decode_bsb, lookup_bsb

# Offline: validate format
validate_bsb("062-000")
# → {'valid': True, 'formatted': '062-000'}

validate_bsb("62")
# → {'valid': False, 'formatted': None, 'reason': 'BSB must contain exactly 6 digits'}

# Offline: normalise messy input
format_bsb(" 062 000 ")   # → '062-000'
format_bsb("062000")      # → '062-000'

# Offline: decode the structural parts
decode_bsb("062-000")
# → {'formatted': '062-000', 'bank_code': '06', 'state_code': '2', 'branch_code': '000'}

# Online: full details via the BSBFinder API
details = lookup_bsb("062-000")
print(details["bank"], details.get("branch"), details.get("address"))

API

validate_bsb(value) -> dict

Checks whether a value is a structurally valid BSB (six digits). Works fully offline. Returns {"valid", "formatted", "reason"?}.

This validates format, not whether the BSB is currently active in the AusPayNet register. For that, use lookup_bsb().

format_bsb(value) -> str | None

Normalises any 6-digit input ("062000", "062-000", " 062 000 ", 123456) to canonical NNN-NNN form. Returns None if it can't be reduced to six digits.

decode_bsb(value) -> dict | None

Breaks a BSB into its parts: bank_code (institution), state_code (state/territory), and branch_code. Returns None on invalid input.

lookup_bsb(value, timeout=10.0) -> dict

Fetches full details for a BSB from the free BSBFinder API — bank name, branch, address, SWIFT code and payment methods (BECS/NPP).

Raises InvalidBSBError for malformed input and BSBNotFoundError if the BSB isn't in the register.

Data source

Full lookups are powered by BSBFinder.com, a free tool that indexes every active Australian BSB code (sourced from AusPayNet). BSBFinder also offers:

• A free BSB lookup API
• A BSB validator web tool
• SWIFT/BIC code lookup for Australian banks
• Bulk BSB lookup

The API is free to use for reasonable volumes and requires no authentication.

A JavaScript/Node version of this library is also available on npm as bsb-validate.

License

MIT © Ujwal Jayendran

Built alongside BSBFinder.com — free Australian bank code tools.