Python · CSV · IBAN validation

Validate IBANs in a CSV file with Python

Check an exported IBAN list and produce a new CSV containing validation status, bank name and BIC. The downloadable script uses Python's standard library, preserves row order and checks duplicate IBANs only once per run.

This is a local command-line workflow for Python 3.10 or newer. Each distinct, non-empty IBAN is sent to the IBAN-Test API. You need your own API token and sufficient request quota.

Download the CSV validation script

The ZIP contains iban_csv.py, a sample CSV, a README and the automated tests. No Python packages need to be installed.

Download the Python starter package

Test status: Nine local automated tests cover request construction, duplicate and empty rows, validation results, quota protection, failure handling, CSV escaping and file preservation. An authenticated run against the live API has not been performed for this example.

1. Prepare the input file

Export your source data as UTF-8 CSV. Use a lowercase iban header and, optionally, a reference column for matching the results to your records. The script only carries these two input columns into the output; other columns are not included. Keep your original export.

reference,iban
example-valid,DE89 3704 0044 0532 0130 00
example-duplicate,de89370400440532013000
example-invalid-checksum,DE00370400440532013000
example-empty,

These are test examples, not payment instructions. The first two rows become the same normalized IBAN. The blank row receives MISSING without an API request. Store IBANs and references as text when exporting from a spreadsheet.

2. Run a small first check

Extract the package, open a terminal in its directory and check that Python is available:

python3 --version
python3 iban_csv.py sample.csv results.csv

On Windows, use py -3 in place of python3 if that is how Python is installed. The program prompts for your API token without displaying the typed characters. Obtain the token from your IBAN-Test account's API overview. The token is not written to the CSV.

The default limit is 10 distinct, non-empty IBANs. The script counts them before making a request and stops if the list exceeds the limit. The sample above needs two API requests, provided both complete normally.

When the run succeeds, the program prints the row count and request count. It creates the output file only after every requested IBAN has a usable validation result. An API failure therefore does not leave a partially checked result CSV.

3. Read the output

Column	Meaning
`reference`, `iban`	Your original reference and input, with spreadsheet formula protection where needed.
`iban_normalized`	Uppercase IBAN with whitespace removed.
`status`	`VALID`, `INVALID` or `MISSING`.
`code`, `message`	The API result code and explanatory message. Use the code, not the message text, for automated decisions.
`bank`, `bic`	Available bank details; fields may be empty.
`checked_at_utc`	UTC timestamp recorded after that IBAN's response. Duplicates share a result and timestamp; empty inputs have no timestamp.

VALID requires code 2100 and error: false. Codes 3100, 3101 and 3102 with error: true produce INVALID. Authentication failures, exhausted quota, server errors and unexpected responses stop the program with a non-zero exit code.

4. Handle different exports and larger lists

For a semicolon-separated export, choose the delimiter explicitly. It applies to both input and output:

python3 iban_csv.py customers.csv checked-customers.csv --delimiter ";"

After checking your remaining API allowance, raise the per-run request cap as needed:

python3 iban_csv.py customers.csv checked-customers.csv --max-requests 100

This sends individual requests in sequence; it is not a REST batch endpoint. A failed run may already have consumed requests. Running it again also checks the list again: deduplication applies within a run, not across separate runs. There are no automatic retries or resumable checkpoints in this starter.

For unattended execution, provide IBAN_TEST_API_TOKEN through your job runner's secret configuration. Do not put a real token in source control or pass it as a command-line argument. The interactive hidden prompt is the simplest option for a manual run.

Common problems

“CSV must have an iban header”: check the exact header spelling, encoding and delimiter. XLSX is not CSV.
“Choose a new output filename”: the script refuses to overwrite an existing file or its input. Use a new filename for each run.
HTTP 401 or API code 4002: verify your token. Do not repeatedly retry an authentication failure.
API code 4003: the quota is exhausted. Stop the job and review your allowance before rerunning.
Network failure or invalid JSON: the run stops. Investigate connectivity or API availability; a transport error says nothing about the IBAN's validity.

Protect the exported data

Only the IBAN is sent to the API; the reference stays in your local workflow. Keep input and output files in an appropriate private location. The script prefixes potentially executable spreadsheet values with an apostrophe to reduce formula-injection risk. That protection can change the literal representation of a reference such as =1+1; preserve the original export for exact reconciliation.

A valid IBAN does not prove account existence, ownership, balance or payment success. For scheme-specific information, see checking a bank's SEPA participation. If you prefer a visual workflow, use the n8n guide.

Run the included offline tests

python3 -m unittest -v

These tests use controlled responses and do not consume API requests. They exercise the program's decisions; they do not verify your token or current bank data.

References: IBAN-Test API documentation, Python CSV reference, Python HTTP request reference.

Create an API account Compare API quotas