Every system that stores bank accounts needs IBAN test data: seed rows for a development database, fixtures for integration tests, sample files for an import feature, a few hundred accounts for a load test. The two shortcuts people take, copying real IBANs from production and typing plausible-looking ones by hand, both fail. Real IBANs are personal data that do not belong in a test environment, and hand-typed ones fail the MOD-97 check, so your own validation rejects your own fixtures.
This post is about doing it properly: picking a useful mix of countries, getting the IBANs into a file format your tooling understands, loading that file from a factory or fixture, and storing the values in a way that will not cause bugs later.
Why generated IBANs
A generated test IBAN has the right length and character pattern for its country and correct check digits, so it passes every structural check. No bank issued it. https://generaterandomiban.com/en/ibanpedia/test-ibans covers the trade-offs in detail; the short version for fixtures is:
- Use realistic mode (the default on this site) when your code looks up the bank code: the IBAN then carries the code of a real bank with a random account number, and a bank directory lookup succeeds.
- Use random mode when you want to exercise the "unknown bank" path or need letters wherever the country's format allows them.
- Never use a generated IBAN for an actual payment. A realistic one could match an existing account by chance.
Choosing countries for the fixture set
One country is not enough, even if your customers are all in one place. Length, character classes and national check digits vary, and a fixture set that covers the extremes catches the bugs a single-country set hides. A reasonable minimum:
| Country | Length | Why it belongs in the set |
|---|---|---|
| Germany (DE) | 22 | Digits only, the most common format in European test suites |
| Netherlands (NL) | 18 | Four-letter bank code (NL91ABNA...), breaks digits-only regexes |
| United Kingdom (GB) | 22 | Letters plus a sort code; also a non-euro SEPA country |
| France (FR) | 27 | National check digits (clé RIB) and alphanumeric account positions |
| Norway (NO) | 15 | The shortest IBAN; tests lower-bound length handling |
| Malta (MT) | 31 | One of the longest; tests column widths and display wrapping |
Add Brazil or Saudi Arabia if you process payments outside Europe, and add your own country if it is missing. https://generaterandomiban.com/en/ibanpedia/iban-formats-by-country has the full list of lengths and patterns.
Downloading fixtures: CSV, JSON, SQL or TXT
The "Generate a list" option on the generator produces 5 to 100 IBANs for one country and lets you download them. Behind it is a plain GET endpoint that needs no API key, so a script or a Makefile target can fetch fixtures directly:
GET /export/{country}?format=csv|json|sql|txt&count=1..100&realistic=0|1
GET /export/{country}.{format}?count=...&realistic=...
The defaults are format=csv, count=10 and realistic=1. The response is served as an attachment named after the request, for example test-ibans-de-50.csv, or test-ibans-de-50-random.csv when realistic mode is off. Unknown countries or formats return 404; a count outside 1 to 100 returns 422 with a plain-text message. The endpoint is limited to 30 downloads per minute per IP, which is plenty for fetching fixtures and not meant for generating IBANs at request time.
curl -o fixtures/ibans-de.csv "https://generaterandomiban.com/export/de?format=csv&count=50"
curl -o fixtures/ibans-nl.json "https://generaterandomiban.com/export/nl.json?count=25"
curl -o fixtures/ibans-fr.sql "https://generaterandomiban.com/export/fr?format=sql&count=25"
Every row has the same fixed columns, then one column per segment of that country's BBAN, named after the segment's role: bank, branch, account, type, currency and so on. National check digits are exported as national_check, because CHECK is a reserved word in SQL. If a role appears twice, as in Hungary with its two national check digits, the columns are numbered: national_check_1, national_check_2.
CSV
RFC 4180 style: a header row, CRLF line breaks, fields quoted only when they need it (they never do for IBAN data, so the file is also safe to split on commas). Three German rows as produced by the endpoint:
iban,iban_print,country,check_digits,bank,account
DE23700202708645524076,DE23 7002 0270 8645 5240 76,DE,23,70020270,8645524076
DE24120300006992883058,DE24 1203 0000 6992 8830 58,DE,24,12030000,6992883058
DE05100100106853936169,DE05 1001 0010 6853 9361 69,DE,05,10010010,6853936169
A French export has two more columns, branch and national_check:
iban,iban_print,country,check_digits,bank,branch,account,national_check
FR7630066100218390851323042,FR76 3006 6100 2183 9085 1323 042,FR,76,30066,10021,83908513230,42
JSON
An array of objects with the same keys, pretty-printed:
[
{
"iban": "DE23700202708645524076",
"iban_print": "DE23 7002 0270 8645 5240 76",
"country": "DE",
"check_digits": "23",
"bank": "70020270",
"account": "8645524076"
}
]
SQL
A header comment, a commented-out CREATE TABLE with the right VARCHAR width per column, then one INSERT per row. The statements use only single-quoted strings and run unchanged on MySQL, PostgreSQL, SQLite and SQL Server.
-- 3 test IBANs for Netherlands (NL), realistic mode, generated by generaterandomiban.com on 2026-10-04.
-- Test data only. These IBANs were not issued by any bank. Never use them for payments.
-- Realistic mode: real bank codes with random account numbers, so an IBAN could match a real account by chance.
--
-- CREATE TABLE test_ibans (
-- iban VARCHAR(34) NOT NULL,
-- iban_print VARCHAR(42) NOT NULL,
-- country VARCHAR(2) NOT NULL,
-- check_digits VARCHAR(2) NOT NULL,
-- bank VARCHAR(4) NOT NULL,
-- account VARCHAR(10) NOT NULL
-- );
INSERT INTO test_ibans (iban, iban_print, country, check_digits, bank, account) VALUES ('NL52ASNB7782378805', 'NL52 ASNB 7782 3788 05', 'NL', '52', 'ASNB', '7782378805');
INSERT INTO test_ibans (iban, iban_print, country, check_digits, bank, account) VALUES ('NL66INGB0568172937', 'NL66 INGB 0568 1729 37', 'NL', '66', 'INGB', '0568172937');
Uncomment the CREATE TABLE the first time, or map the columns onto your own table. We loaded exactly this file into SQLite with sqlite3 test.db < ibans-nl.sql and queried it back; the bank width is per country (4 for the Netherlands, 8 for Germany), so a shared table across countries should use the widest value you import, or simply VARCHAR(34) for everything.
TXT
One IBAN per line in electronic format, nothing else. The right input for a shell loop or a load-testing tool.
Wiring the file into factories and fixtures
Commit the downloaded file and read it from your test code. Two examples, both run before publication.
Laravel factory
use Illuminate\Database\Eloquent\Factories\Factory;
class BankAccountFactory extends Factory
{
protected $model = BankAccount::class;
private static ?array $ibans = null;
public function definition(): array
{
self::$ibans ??= json_decode(
file_get_contents(base_path('tests/fixtures/ibans.json')), true
);
$row = self::$ibans[array_rand(self::$ibans)];
return [
'holder' => fake()->name(),
'iban' => $row['iban'], // electronic format, as exported
'country' => $row['country'],
];
}
}
When a test needs the same rows in the same order every time, replace the random pick with a Sequence built from the file:
use Illuminate\Database\Eloquent\Factories\Sequence;
$rows = json_decode(file_get_contents(base_path('tests/fixtures/ibans.json')), true);
$accounts = BankAccount::factory()
->count(count($rows))
->state(new Sequence(...array_map(
fn (array $r) => ['iban' => $r['iban'], 'country' => $r['country']],
$rows,
)))
->make();
Faker's own iban('DE') is an alternative when you do not care which bank: it computes valid MOD-97 check digits. It does not use real bank codes, and it does not compute national check digits; the French IBAN it gave us passed MOD-97 and failed the clé RIB. Use it for throwaway data and the exported file for anything a bank-code lookup or a national check will see.
pytest fixture
In tests/conftest.py:
import json
from pathlib import Path
import pytest
FIXTURES = Path(__file__).parent / "fixtures"
@pytest.fixture(scope="session")
def test_ibans() -> list[dict]:
"""IBANs generated once and committed: the same rows in every run."""
with open(FIXTURES / "ibans.json", encoding="utf-8") as fh:
return json.load(fh)
@pytest.fixture
def german_iban(test_ibans) -> str:
return next(row["iban"] for row in test_ibans if row["country"] == "DE")
And in a test module next to it:
def normalise(raw: str) -> str:
return "".join(raw.split()).upper()
def test_normalise_accepts_pasted_print_format(german_iban):
pasted = " ".join(german_iban[i:i + 4] for i in range(0, 22, 4)).lower()
assert normalise(pasted) == german_iban
The session scope reads the file once per run; conftest.py makes the fixtures available to every test module in the directory.
Keeping fixtures deterministic
- Commit the file and do not fetch at test time. Tests that download fixtures depend on the network and change their data on every run. Regenerate the file on purpose, review the diff and commit it.
- Prefer sequences over random picks for tests that assert on specific values. A random pick is fine for bulk seeding.
- Seed the random source where you keep randomness. Faker's
seed()makes names and the rest reproducible; a committed IBAN file does the same for the account numbers. - Keep one known value per country for documentation and examples: the registry examples, such as
DE89370400440532013000, are stable and appear in every library's test suite.
Storing IBANs correctly
The seed data is only as good as the column it lands in. Rules that save pain later:
- Store the electronic format: uppercase, no spaces, no separators. Format for display at render time; the export's
iban_printcolumn exists so that a UI prototype can show a formatted value without implementing the grouping. - Use a string column,
VARCHAR(34)or wider. ISO 13616 caps the IBAN at 34 characters. Never a numeric type: IBANs contain letters, and BBANs may start with zeros. - Normalise on input. Strip all whitespace, including non-breaking spaces, and uppercase before validation and storage, so that equality comparisons and unique indexes work.
- Keep the country code queryable, either in a separate column, as in the export, or through an expression index on the first two characters, so that per-country validation and reporting do not need string functions everywhere.
- Do not derive the BIC or the bank name at insert time from a hard-coded list. Bank directories change; look them up when needed.
When 100 per download is not enough
For larger or automated needs, the REST API returns up to 100 IBANs per request for any of the 91 supported countries and validates IBANs too (GET /api/v1/generate/DE?count=100, GET /api/v1/validate/DE89370400440532013000); it needs a free key, requested by email, and the https://generaterandomiban.com/en/apis/docs describe every endpoint. AI coding assistants can call the public MCP server at /mcp without a key. For a load test, generate once, write the file and have the test read it, so that the test suite itself never calls the generator.
Sources
- SWIFT IBAN Registry: the length and BBAN structure of every country used in the examples.
- ISO 13616-1:2020: the IBAN structure and the 34-character maximum.
- RFC 4180: the CSV conventions followed by the export (header row, CRLF, quoting).
- Laravel documentation, Eloquent: Factories:
definition(),fake()andSequence. - pytest documentation, How to use fixtures: fixture scopes and
conftest.py. - FakerPHP, payment formatters: the
iban()formatter.