One of my current projects I work on in my sparetime is Pecunia, which is an OSX app to manage multiple online banking accounts, organize financial data and provide answers about your money (e.g. monthly income and where it is spent). Pecunia is open source on Github and also available free of charge from the OSX appstore. Read in the README.md file why this is mostly useful for german users only and hence the Pecunia homepage is german-only.

One part of this application is a Swift library to managed IBANs (International Bank Account Numbers) and related data (like the BIC and other financial institutes data, e.g. the name, address etc.). It helps to create valid IBANs for bank codes and account numbers and helps with their validation. The name of this library is IBANtools and in this blog post I’m going to explain it and how it can be used (not only for german users).

What Is This About?

The IBANtools library was created out of the need to manage IBANs properly and especially help with the transition of the old traditional bank account numbers to the new SEPA system. SEPA had been started to simplify money transfers especially in the european area. Read more about this on Wikipedia. In order to avoid confusion let me explicitly mention this: since this library is part of a macOS project, it has been written in Apple’s Swift language. This has nothing to do with the SWIFT organisation.

The IBANtools library is open source under the GPL and hosted on Github as well.

IBANs are large numbers that not only have to maintain a specific structure, but also (sometimes) have to follow country specific rules. Hence IBANtools has been designed in a way that allows the general algorithm for IBAN generation + validation to be used whereever possible, but at the same time let country specific classes to add their share, if required. To make this work the library uses a plugin mechanism that allows to implement country specific parts in own classes, which are automatically picked up, if they follow the right naming scheme. There are 3 parts where a country specific class can be added for:

• Account verification (check sums, special account conversions, general validation checks)
• IBAN creation and verification (institute specific rules + account verification)
• Testing (country specific tests)

The naming scheme is very simply and allows for easy addition of support for countries other than Germany (which is the only country in the library that is supported with its special rules, currently). The name of the classes consist of a base name part + the country two-letter code, here exemplarily for Germany:

• DEAccountCheck (for account verification)
• DERules (for IBAN generation + verification)
• IBANtoolsDETests + AccountCheckDETests (for testing)

It is not necessary to implement all of those classes. The test classes also are not loaded dynamically, but will be executed as part of general testing in XCode, as soon as these test classes are added to the project.

The library uses no account verification and the standard rule to generate valid IBANs if there is no country specific data available. Supporting country specific rules is often a non-trivial task. For instance for Germany there are no less then 81 PDF pages filled with account validation rules + almost 60 IBAN creation rules. Each country class can use additional data files where needed. For the DE classes I used official data provided by the Deutsche Bundesbank in addition to the list of all european financial institutes provided by the European Central Bank (ECB), available free of charge from their website or via e-mail subscription.

IBANtools API

All the functionality in the library is provided by a single class: IBANtools in the Converter.swift file. On class initialization it loads the ECB data file from a default location. You can tell it to use a different location, however (e.g. your app bundle) via the useResourcePath(path: String) function. A set of class functions is available, which are documented in the code. Since this library is also to be used from Objective-C a number of wrapper function have been added that convert the usually returned tuple into a dictionary. As a user of the IBANtools library this is all you need to look at. The functions usually return a status code that tell you what happened (all fine, invalid account etc.) which you can use in your application to ask the user for assistance if something went wrong. All the functions (except for the Obj-C wrappers) are tested in the unit test files, which you can find in the Tests group in the XCode project. These are also good examples that show how to use the class functions.

Other Countries

Since it is not easy to get specific informations for a country you don’t live in, I need your help, if you want support for your country. I welcome everybody to help extending this library for other countries that support IBANs (which is not only Europe).