Integrating with the Erste Banking API

Intro

As a part of a larger project, we had to integrate with the Erste PSD2 API. Although it's mostly your standard OAuth flow, there are a few "gotchas" along the way. This post will guide you to getting authenticated and pulling transactions.

Developer Portal

Before you can start writing any code, you will need an Erste developer account. You can open one on the Erste developers portal where you will be able to choose the branch of the bank you will be integrating with and which of the APIs you will be using. Take note that the only API you can use without certification is the Corporate API. Luckily this was exactly the one we needed and didn't have to go through the certification process.

Among many options that are available on the portal dashboard, the only three that you are going to need to get started are OAuth settings, credentials, and the certificates section.

In the OAuth settings, you are going to set the callback URI, this is the URI to which the authorization code is going to be sent. If you don't have a local server that can accept HTTP requests, you can use something like RequestBin to output the request and get the authorization code.

In the certificates section, you will find the public and private keys which you can download and install to your devices' CA store.

Calling API endpoints

So, once we have the certificates installed and the callback URI setup, we can start calling the Erste API.

Consent ID

The first endpoint that we are going to call is the /consents API which is going to return our consent ID:

curl -X POST \
 https://webapi.developers.erstegroup.com/api/ebc/sandbox/v1/netapi/consents \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: 4774477a-0508-4293-be86-6fca6f67adda' \
  -H 'psu-ip-address: 127.0.0.1' \
  -H 'web-api-key: WEB_API_KEY' \
  -d '{
  "access": {
    "accounts": [],
    "balances": [],
    "transactions": []
  },
  "recurringIndicator": false,
  "validUntil": "2019-06-30",
  "frequencyPerDay": 4,
  "combinedServiceIndicator": false
}'

Where the WEB_API_KEY is the API key in your developer dashboard.
The response will return the consent ID, save it somewhere as it's going to be needed in other requests.

OAuth URL

After we have obtained the consent token, we have to visit the URL with the following structure:

https://webapi.developers.erstegroup.com/api/ebc/sandbox/v1netapi/auth
    ?redirect_uri=REDIRECT_URI
    &client_id=CLIENT_ID
    &response_type=code
    &access_type=offline
    &state=loremipsum
    &code_challenge=loremipsum
    &code_challenge_method=S256
    &scope=AIS:CONSENT_ID%20openid%20offline_access

Where the variables are following:

REDIRECT_URI - the URI you put as the callback in the OAuth setting
CLIENT_ID - client ID from your dashboard
CONSENT_ID - consent ID from the previous request If you put the right details in the URL you will be greeted with an OAuth mocking tool where you can choose what type of user you want to mock, and what access you are going to give for their accounts.

Authorization code

Once you select all the options in the OAuth mocking tool you will be redirected to the URI you put in the OAuth setting. If you are using RequestBin you can now go through the request and get the authorization code from the request.

Bearer token

At this point, once we have obtained the authorization code and the consent token, we can finally call the /token endpoint and receive the Bearer token which will be used to get transactions, accounts, etc.

curl -X POST \
  https://webapi.developers.erstegroup.com/api/ebc/sandbox/v1/netapi/token \
  -H 'Content-Type: application/x-www-form-urlencoded'
  -d 'redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code_verifier=loremipsum&code=AUTHORIZATION_CODE'

Where the variables are following:

REDIRECT_URI - the URI you put as the callback in the OAuth setting
CLIENT_ID - client ID from your dashboard
CLIENT_SECRET - client secret from your dashboard
AUTHORIZATION_CODE - authorization code from the previous request

Calling other endpoints

Once you have the Bearer token you can use standard Bearer auth in the header of your requests. With this token, you can pull transactions and accounts from the sandbox. To go to production, the requirements will vary from country to country. The most common procedure will involve giving your VAT number and the SSL cert for the domain your app will be using.

If you are going to be integrating with the Croatian branch of the Erste bank using PHP take a look at our in-house library to help you get started.