Metadata-Version: 2.5
Name: ibanchecker
Version: 0.1.0
Summary: Official Python client for the ibanchecker.cash IBAN validation API: validate IBANs across 92 countries, extract IBANs from text, and look up SWIFT/BIC codes.
Project-URL: Homepage, https://ibanchecker.cash
Project-URL: Documentation, https://ibanchecker.cash/api-docs
Project-URL: API Reference, https://ibanchecker.cash/api-docs
Project-URL: OpenAPI Spec, https://ibanchecker.cash/openapi.json
Project-URL: Source, https://github.com/koraykoylu/ibanchecker-python
Project-URL: Issue Tracker, https://github.com/koraykoylu/ibanchecker-python/issues
Author-email: "ibanchecker.cash" <api@ibanchecker.cash>
License-Expression: MIT
License-File: LICENSE
Keywords: banking,bic,fintech,iban,iban-checker,iban-validation,payments,sepa,swift
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# ibanchecker

Official Python client for the [ibanchecker.cash](https://ibanchecker.cash) IBAN validation API.

Validate IBANs across 92 countries, validate up to 100 IBANs per request, extract IBANs from free text, look up country format specifications, and resolve SWIFT/BIC codes. No IBAN data is stored or logged; all validation runs in memory at the edge.

## Install

```bash
pip install ibanchecker
```

## Quick start

```python
from ibanchecker import IbanChecker

client = IbanChecker()  # no API key needed for light use (100 requests/hour per IP)

result = client.validate("DE89 3704 0044 0532 0130 00")
if result:                      # ValidationResult is truthy when valid
    print(result.country_name)  # "Germany"
    print(result.bank_name)     # "Commerzbank AG Cologne"
    print(result.bic)           # "COBADEFFXXX"
else:
    print(result.error)         # human-readable reason
    print(result.error_code)    # e.g. "INVALID_LENGTH"
```

## Authentication

An API key is optional. Without one, requests are limited to 100 per hour per IP. With a key, requests count against your plan quota. Get a free key at [ibanchecker.cash/api-docs](https://ibanchecker.cash/api-docs).

```python
client = IbanChecker("iban_your_api_key")
```

The client can also be used as a context manager so the underlying HTTP session is closed cleanly:

```python
with IbanChecker("iban_your_api_key") as client:
    result = client.validate("GB29 NWBK 6016 1331 9268 19")
```

## Methods

| Method | Description |
| --- | --- |
| `validate(iban)` | Validate a single IBAN. Returns a `ValidationResult`. |
| `validate_bulk(ibans)` | Validate up to 100 IBANs. Returns a `BatchResult`. |
| `extract(text)` | Find and validate IBANs in free text (up to 50,000 chars). Returns a `BatchResult`. |
| `get_format(country)` | IBAN format spec for an ISO country code. Returns a `FormatSpec`. |
| `lookup_bic(bic)` | Resolve an 8 or 11 character BIC. Returns a `BankRecord`. |

### Bulk validation

```python
batch = client.validate_bulk([
    "DE89370400440532013000",
    "GB29NWBK60161331926819",
    "XX00",
])
print(batch.valid_count, "of", batch.count, "valid")
for r in batch:                 # iterate results in input order
    print(r.iban, r.valid)
```

### Extract from text

```python
batch = client.extract("Please wire to DE89 3704 0044 0532 0130 00 by Friday.")
for r in batch:
    print(r.iban, r.bank_name)
```

### Country format and BIC lookup

```python
fmt = client.get_format("DE")
print(fmt.length, fmt.example)          # 22 'DE89370400440532013000'

bank = client.lookup_bic("DEUTDEFF")
print(bank.bank_name, bank.city)        # 'Deutsche Bank AG Frankfurt' 'FRANKFURT AM MAIN'
```

## Error handling

A malformed IBAN is **not** an exception: `validate()` returns a `ValidationResult` with `valid=False`. Exceptions are raised only for transport, authentication, and rate-limit problems:

```python
from ibanchecker import IbanChecker, AuthenticationError, RateLimitError, NotFoundError

client = IbanChecker("iban_your_api_key")
try:
    bank = client.lookup_bic("ZZZZZZZZ")
except NotFoundError:
    print("No bank for that BIC")
except RateLimitError as e:
    print("Slow down:", e.message)
except AuthenticationError:
    print("Check your API key")
```

All exceptions derive from `IbanCheckerError` and carry `.status`, `.error_code`, and `.response`.

## Links

- Website: https://ibanchecker.cash
- API documentation: https://ibanchecker.cash/api-docs
- OpenAPI spec: https://ibanchecker.cash/openapi.json
- Free online tools: https://ibanchecker.cash/tools

## License

MIT
