First Hand Experiences with Open Banking APIs

A while ago I posted a general overview of the Open Banking scenery in Finland. This article is all about getting my hands dirty with the PSD2 APIs that are available from Finnish banks: I wanted to build something on top Nordea and OP developer interfaces. The results are summarised below, and those of you with a Xcode and Mac combo can run my small sample iOS application in simulator or an iPhone/iPad. Source code for my app available at github.com/sitomani/ExamineSpending.

Ultimately my motivation was to take the initiative and delve into open banking myself. To bring it to a head: I believe there are a number of companies looking into it, probably working hard to build new innovative ways to add value for users by getting access to these new data volumes. I trust that this effort is done with the best intentions in mind, but in the end my financials are my financials. If my bank opens new interfaces, who would be better suited to build value for me than myself?

Couple of Messages Up Front

Before jumping in, just that you know: to run my sample app or to experiment with the OP and Nordea APIs in their beta/sandbox environments, you don’t need to have an account at these banks.

As a small gamification element I will be assigning ‘ +’ signs to each bank’s developer program features that I particularly like, and counting them up in the end of the article.

This article will cover my general experiences with the OP and Nordea developer portals, and on the PSD2 front specifically Account Information Services (AIS) APIs. Payment initiation services will not be touched on this time.

Registering

To start developing with OP Developer program, navigate to https://op-developer.fi. You can easily register an account with just a few clicks, and after confirming the registration through an automated email you can create your first app.

The Nordea Developer Program registration is done at https://developer.nordeaopenbanking.com. I had a small problem with the account activation mail (part of the query string was cut out of the link, might be due to the mail app used) but managed to activate it by copying the link directly to browser. Once you’ve activated your account, it is easy to create the first application.

+ The Nordea Developer portal also supports creating teams for sharing work with multiple developers.

Creating your first app

Both Nordea and OP have quite similar approach for creating applications that make use of the provided APIs. Once you select to create an App, you get to select Application Name, Authentication Redirect URI and the desired API products for your app. In the following image you can see the new application creation forms available through the developer portals.

+ OP has a number of additional interfaces to choose from, e.g. related to funds and holdings, and branch information.

Note that on OP Create New App form the Authentication Callback URL field can be left empty. It is documented elsewhere on the site that callback url and API secrets are not in use at the moment. In practice this means that authentication towards OP APIs is hard-coded through a set of simulated authentication tokens.

Nordea’s application creation form requires a https authentication callback URL to be given. In general, the authentication flow with Nordea Developer APIs is OAuth2 style, but for quickly getting to work with the interfaces you can bypass this by setting your callback URL to https://httpbin.org/get and using a specific request header in the authentication code request. The full OAuth2 flow simulation used to work in Nordea’s API Console, but it has been removed from the console in 2018.

Finding your way around the resources

The banks provide documentation for their open banking interfaces in various forms, and I recommend delving into the material with due diligence, it is well worth the while.

Nordea has published an substantial set of resources for developers under https://developer.nordeaopenbanking.com/app/resources. You can find links to sample projects, a postman collection for testing the APIs and a series of tutorial videos (with a bit uncanny synthetic voiceover – guess they couldn’t get Morgan Freeman so they decided to go for a robot instead :P). In general, the material is well written and presented, and there is a relatively active blog with interesting guest writers.

+ Nordea has released their interface spec in Postman format, which saves a good amount of time from any developer that wants to learn the ropes with a readily available request collection. 

OP’s developer portal documentation at https://op-developer.fi/docs is also quite extensive with github samples, comprehensive API docs and other relevant information e.g. about security considerations and risk level assessment. There is also a blog where new posts are coming in regularly. OP does not have an API console to for testing requests at the time of writing this.

+ OP has also released a Javascript SDK in NPM for helping web developers to tap into their APIs.

 

Implementing Authentication

As I already mentioned above, the OP developer portal has a predefined set of authentication tokens that can be used to call the other APIs. There is no description of the production authentication flow available, but I’d expect a somewhat standard OAuth2. For the time being, as long as you’re developing on the sandbox data, you can only rely on the given hard-coded tokens. Thus, implementing Authentication for OP API is not necessary. In my sample application I have created a placeholder login worker class just to prepare for a real authentication implementation when the APIs will be published.

Nordea API documentation has a specific section about implementing authentication in the sandbox. While the documentation illustrates end user’s login and consent granting through Codes App look-a-like UI, there is no direct mention of the endpoint of this web service that resides at http://oauth.nordeaopenbanking.com/oauth/. In my test application I have implemented simulated OAuth2 flow through a webview, but it is no longer working due to changes in the API console. The option to skip the consent granting step by adding the X-Response-Scenarios=AuthenticationSkipUI header in the first call to get auth code works.

+ Nordea sandbox authentication flow appears to be quite close to the expected production flow – migration to production should not bring big surprises

Once your app is authenticated, it is possible to start calling the data interfaces.

OP has two versions of the Accounts API currently available in their sandbox (1.0 and 2.0). I originally implemented my test application on top of V1 API, and migrated to V2 in a later commit to the repository.

Nordea’s Accounts endpoint has two versions available as well (1.2 and 2.2). In my test application I use v2 APIs. Nordea accounts response has a bit more finalised looking JSON structure, even though it is not as detailed as Berlin Group’s NextGenPSD2 draft specification.

+ Nordea sandbox allows creation of test data through sandbox-only POST endpoints for Accounts and Transactions, i.e. you can create whatever set of dummy data for your application.

 

Getting Transaction Data

Retrieving transaction data for an account is a walk in the park after getting the Accounts. The accounts response contains the account id (and in Nordea’s case HATEOAS style resource identifiers) for getting the transactions with.

When I started working with my sample application I quickly noticed that in order to provide multi-bank experience, a significant harmonisation effort is needed. PSD2 does not specify the format of the data to be provided, which results in rather colourful output. Just to mention a couple of observations:

 

• In order for a client to use data from multiple banks APIs, it is necessary to either choose one bank’s object properties as master and map others to it, or generate an abstraction to map all different banks’ object data to. In my sample app I have chosen the latter approach.
• Nordea transaction API returns about 100-300 transactions per day, which is not exactly realistic scenario for an average person’s account. OP Transaction API on the other hand has no mechanism for specifying a past date range to fetch transactions from at the time of writing this. What I noticed with my own app is that working with just one bank’s API will very likely drive your development towards a suboptimal solutions due to data scarcity and bias. If you’re planning to work on PSD2 interfaces, I certainly recommend picking a number of banks instead of one to avoid this pitfall.

+ OP Accounts with AI API has neat machine-learning enriched features for automatic transaction categorisation

OP V1 API has a response schema specification, but no optionality information. Accounts API V2 documentation quite bluntly refers to “Object containing the details of an transaction” in the API response specifications, and provides no optionality/conditionality information in for individual fields in sample response JSON. Some fields have a status indicator “Proposal”, to indicate that they might be included in a later API version.

Nordea API documentation has more detailed per-field descriptions on each request and response, and optionality is given. However, while implementing my sample app I noticed that certain fields are sometimes excluded e.g. in account data even though there is no mention of optionality (one of the test accounts has no balance information). Nordea API specs also mention which fields are only available in beta, and which are deprecated, so there is certain level of guidance on the implementation.

Putting it all together…

My sample application was a rather random idea about volumetric visualisation of account transactions. When looking for references online, I bumped into a treemap style data display component from Yahoo called YMTreeMap and decided to build the example app around that.

After getting the hang of the APIs with Postman first, I implemented a quick navigation scheme in Xcode storyboard where user can first choose which bank’s API to “login” with. Then the accounts are presented in a treemap where block size is respective to the balance of the account. User can then tap into each account and view the transactions grouped first into income and expenditure groups, and then into debtor/creditor specific collections that can contain the individual transactions. The screenshots below illustrate the navigation path in the app.

I started the application first with Nordea API, and once I decided to add OP sandbox to the same application, I had to do a number of adjustments in the data architecture of the application to cater for two rather different JSON structures that still carry conceptually identical information. With a touch of protocol-oriented programming, I managed to build an architecture that would fit the cause and most probably work also if I want to add support for additional banks in the future.

Since this application does not actually connect to a real account, and because I have not applied for FSA license which is a prerequisite for getting access to production environments, it is not feasible to publish it through the App Store. However, as stated in the beginning I have uploaded the code in GitHub so that you can take a look an run it locally in simulator and also install it to a device using Xcode developer signing. I’d love to hear what you think, and pull requests are welcome. I’m planning to be extend the skeleton with other PSD2 interfaces within this repository later on to get a feel of the Payment Initiation Services as well.

…With a little help from my friends

While implementing the ExamineSpending demo app I have been in touch with a number of Open Banking representatives from different banks, and received very encouraging support from them. Particularly I’d like to mention Jan Stoltzenberg and Agnija Gailane from Nordea and Arto Oinonen from OP who have been prompt and friendly to answer my questions. I believe that my feedback has also helped them to build even better Open Banking APIs.

+ Nordea Developer Portal has a forum for discussing API features and other related topics.

Final Verdict

The sum up of the quotes above results in the score Nordea 5 – 3 OP. Don’t take this too seriously – we’re in the first stage in football terms and one match won’t make or break it yet. It was rather tongue in cheek approach trying identify different competitive edges in the Open Banking scene for an individual developer.

Coming back to where I started: If I want to be my own added-value-provider, building my own financial data aggregation service, would Nordea and OP APIs work for that? My opinion is that there’s definitely promise, as there has been number of API releases and improvements through the first half of 2018 that indicate that the PSD2 is getting more and more attention in the service offering of both banks. Just the same, the APIs in their current form are a bit sketchy to some proportion, and I doubt that it would be feasible to build a full blown PFM app on top of those just yet. Now is a perfect time to hop on the wagon though, and start developing in a collaborative effort.

What I’d like to leave for you as a takeaway from this article is that

1. the PSD2 deadline on 2019 September will be upon us before we know it, and it’s vital that banks will get into a lively feedback loop with developers to ensure the feasibility and maturity of their API offering early enough. It won’t happen automatically for anyone, and the more people participate in the API development in a way or another, the better Open Banking ecosystem we have in the end.
2. I would like to advocate for personal financial app development – it is not everybody’s cup of tea, but I’d love to see banks open their authentication APIs for personal use without applying for a FSA license. Throw out the T in TPP and be your own Party Provider!

Boogie Software Oy is a private Finnish company headquartered in Oulu, Finland. Our unique company profile builds upon top level software competence, entrepreneurial spirit and humane work ethics. The key to our success is close co-operation with the most demanding customers, understanding their business and providing accurate software solutions for complex problems.