Metadata-Version: 2.4
Name: bsb-validate
Version: 1.0.0
Summary: Validate, format, decode and look up Australian BSB (Bank State Branch) numbers. Offline validation plus optional lookups via the free BSBFinder API.
Author: Ujwal Jayendran
License: MIT
Project-URL: Homepage, https://bsbfinder.com
Project-URL: API Docs, https://bsbfinder.com/api
Project-URL: Repository, https://github.com/lactustech/bsb-validate
Project-URL: Bug Tracker, https://github.com/lactustech/bsb-validate/issues
Keywords: bsb,australia,australian,bank,banking,bsb-number,bank-state-branch,validation,validator,fintech,payments,becs,swift,auspaynet
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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](https://bsbfinder.com)
- 🧩 **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

```bash
pip install bsb-validate
```

## Quick start

```python
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](https://bsbfinder.com) — 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**](https://bsbfinder.com), a free tool that indexes every active Australian BSB code (sourced from AusPayNet). BSBFinder also offers:

- A free [BSB lookup API](https://bsbfinder.com/api)
- A [BSB validator](https://bsbfinder.com/validate) web tool
- [SWIFT/BIC code lookup](https://bsbfinder.com/swift) 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`](https://www.npmjs.com/package/bsb-validate).

## License

MIT © Ujwal Jayendran

---

Built alongside [BSBFinder.com](https://bsbfinder.com) — free Australian bank code tools.
