IBAN adventures

I have been hired to develop free software to refund traveling costs for Boy and Girl Scouts. Wire transfer being quite widespread, the participants are asked for an IBAN (International Bank Account Number) where the money will be transferred.

This post will first take a glance at the mathematics inside such numbers, then look at the existing options that were at my disposal, before finally re-inventing the wheel and contacting the Liechtenstein Bankers Association...

The math inside the IBAN

An IBAN is composed of:

two country letters (ISO 3166-1 alpha-2 code)

two check digits

between 11 and 30 alphanumerics characters (BBAN: Basic Bank Account Number)

The two check digits are computed from the rest of the IBAN, to ensure that the number does not contain "simple" errors (missing or swapped characters). This allows for a local/offline sanity check, which should prevent most mistakes. I won't go on explaining the algorithm, which is nicely described on Wikipedia.

IBAN Algorithms - Wikipedia

To go further, one can also perform checks on the BBAN, depending on the country. Each country has a specific format and length. Some countries also have a specific checksum.

> Fun fact: because the BBAN checksum of a French account is very similar to the IBAN checksum, all numerical French IBANs start with FR76.

Business Identifier Codes (BIC)

Usually, to make a transfer, the BIC is also required. The BIC identifies the Bank of the recipient. However, within the BBAN, the first characters already indicate a "Bank Code" for most countries. Unfortunately, there is no mathematical relation between the Bank Code and the BIC. So to deduce the BIC from the IBAN, one must compile mapping for each country.

It would have been too boring if such lists were easily available. Here is an overview of what I ended up parsing per country:

AT: csv file provided by oenb.at

BE: xlsx file provided by nbb.be

CH: json file provided by six-group.com 🎉 (this one was boring :)

DE: txt zipped-file provided by bundesbank.de

ES/FR: gzipped csv file where the bank code is smuggled inside the RIAD code provided by ecb.europa.eu

LI: html page of bankenverband.li

LU: xlsx file provided by abbl.lu

MC: html table of amaf.mc

NL: xlsx file provided by betaalvereniging.nl

Re-inventing the wheel

I wanted a Go package with would make the mathematical validation of the IBAN as well as the BIC deduction for some countries (DE & FR at least). Searching on pkg.go.dev yielded some results, but (obviously) I found none of them satisfying (and I probably have an NIH syndrome):

they didn't provide any IBAN -> BIC mapping

used an external API call to validate the IBAN or provide the BIC mapping

So I created a Go module that validates the IBAN checksum as well as provides an automatic deduction of the BIC for the countries listed above (the BIC mapping is in the subpackage "bic"):

code.pfad.fr/swift - check IBAN validity and deduce BIC

Duty Calls

To ensure ease of update, I generate a good part of the code based on remote files. In this quest, I identified a couple of mistakes...

xkcd: Duty Calls

I contacted the Liechtenstein Bankers Association to let them know that 3 codes of the member's page were wrong (they didn't reply, but they corrected the codes within 24 hours)

I contacted the SWIFT organization to let them know that a couple of examples IBANs of the registry are not valid (and that Iceland is not part of SEPA in the CSV listing)

Evangelization

I am using this package with success in my commissioned software and proposed adding it to the Codeberg registration server. Let's see how it goes (to be polite, my first PR for this project consisted of repairing the tests. If it gets accepted, I will create a PR to use my swift package :).

📅 2023-11-21

Back to the index

Send me a comment or feedback