Getting started

This documentation of Aktia’s Open Banking APIs will help you get started. The Sandbox version is a safe and reliable way of testing the APIs. The Sandbox returns test data which is of the same structure as it will be in the live production. You can build your application and test it against the Sandbox, where after you can comfortably move the application to the live production environment. The APIs are following the international Berlin Group’s specifications.

Overview

The following APIs are provided with their own set of endpoints:

  • Accounts - Information about accounts, balances, and transactions.
  • Payments - Initiating payments
  • Confirmation of funds - Real time confirmation of funds
  • TPP Registration - TPP Registration, including re-direct URL

Terminology

The table below describes the terms used in this documentation:

Term Description
Sandbox Live test environment of Aktia’s APIs. No access to real customer data.
TPP Third Party Provider. The service provider and consumer of the APIs.
ASPSP Account Service Payment Service Provider. In this case Aktia.
PSU Payment Service User (consumer or retailer).
AISP Account Information Service Provider. Third party provider who provides services regarding accounts.
PISP Payment Initiation Service Provider. Third party provider who provides services regarding payments.
PIISP Payment Instrument Issuer Service Providers. Third party provider who provides services regarding confirmation of funds.
RTS Regulatory Technical Standards. Commission Delegated Regulation (EU) 2018/389 with regard to regulatory technical standards for strong customer authentication and common and secure open standards of communication.
SCA Strong customer authentication.
eIDAS Electronic identification, authentication and trust services.
PSD2 Directive (EU) 2015/2366 on payment services in the internal market.
Consent Consent is an agreement between the PSU and the TPP, where access to data is defined and for how long.
Authentication Confirming the identity of the user.
Authorisation Granting access to the user’s data or the service.

Connecting to the APIs

You need to do the following things in order to connect to Aktia’s APIs in the Sandbox environment:

  1. Register to the developer portal
  2. Create an application  (Client ID and Client Secret are generated)
  3. Subscribe your application to API products
  4. Get consent to access the customer’s data (in the Sandbox environment consent is always given). The details are described in the API Specific references

Client ID and Client Secret

To connect to the APIs, you need to be registered to the developer portal and create an app. When creating an app, you will get a Client ID and Client Secret, which are needed for you to connect to the APIs. One application can also have several credentials (Client ID and Client Secret) for revocation of one set of credentials and migration to a new set in a managed fashion.

The application is created on the Apps page. The Client ID and Client Secret always needs to be sent in the request, as it is the way the application is identified. Keep in mind that the Client ID and Client Secret are only used and stored by the TPP and should not be given to the end user of the application.

NB! The Client Secret is only shown once, and cannot be requested from Aktia again, as it is not stored in plain text. Save the Client Secret once it is generated and do not share it with anyone outside your developer organization. If you need to reset and get a new Client Secret, you can do it in the App Details page.

The Client ID and Client Secret are also needed in the live production.

TPP re-direct URL registration

With the TPP registration API, you can pre-register positive and negative outcome redirect urls that can be used in payment and account consent confirmation requests. This is not required in the sandbox environment, and is not mandatory in the live production either. The redirect URI is mandatory in the header TPP-Redirect-URI in the payment initiation and create consent requests.

API Swagger Definition and Postman collections

The swagger definition (.yaml files) can be downloaded from the API specific documentation. But the easiest way to get started is to use Postman, as you can download our Postman collection (.json) from the API Products pages.

The collection includes all endpoints including simple tests checking that you are receiving the correct response code. You can also download a pre-configured test environment and a list of test data, also found in the links above. The Postman environment consists of:

  • X-IBM-Client-ID 
  • X-IBM-Client-Secret
  • URL (pre-configured)
  • Consent-ID  (pre-configured)
  • Account-ID (pre-configured)
  • X-Request-ID (pre-configured)
  • transactionID (pre-configured)
  • Payment-ID (pre-configured)
  • Authorization-ID (pre-configured)

NB! In the requests where a body is required, there's a prefilled body that you might want to edit. The Postman collection is also not updated as frequently as the endpoints, so check the API references first if you encounter some issues.

API HTTP Methods

Aktia’s RESTful APIs uses HTTP methods to perform operations. Below is listed all methods supported by Aktia’s APIs.

  • GET - Reads a resource and returns it.
  • POST - Creates a new resource.
  • DELETE - Deletes the resource identified by URI.

API Responses and Response Codes

Aktia’s APIs both consume and returns JSON (JavaScript Object Notation). The JSON objects are defined in more detail in the reference part of this documentation.

API Response Codes

The HTTP response codes are grouped to 2xx Success, 3xx Redirection, 4xx Client errors, and 5xx Server error.

The following table shows the detailed return HTTP codes used by the APIs:

Status Code Description
200 OK The request has succeeded.
201 Created The request has been fulfilled and resulted in a new resource being created.
202 Accepted The request has been accepted for processing, but the processing has not been completed.
204 No Content The server has fulfilled the request but does not need to return an entity-body.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request has not been applied because it lacks valid authentication credentials for the target resource.
403 Forbidden The server understood the request, but is refusing to fulfill it.
404 Not Found The server has not found anything matching the Request-URI.
405 Method Not Allowed The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
408 Request Timeout The client did not produce a request within the time that the server was prepared to wait.
415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
429 Too Many Requests The 429 status code indicates that the user has sent too many requests in a given amount of time (“rate limiting”).
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Request limits

The request limit for the Sandbox environment is set to 1000 requests per day per API subscription. Furthermore, there is a burst limit of 100 request per minute.

Request limits
1000 requests / day
100 requests / minute

There's also technical request and burst limits in the live production. If you need to raise these limits, please feel free to contact us.

FAQ

Frequently asked questions can be found from the FAQ page.

Deviation from Berlin Group Specifications

The APIs follows the Berlin Groups Specifications, with some deviations. The major deviations are listed in the table below. Please note that this is not a comprehensive table, and the APIs are described in detail in the API references.

API Deviation Description
Payments SEPA and non-SEPA payments Default products (SEPA and non-SEPA) are combined into one Aktia specific overall payment product type. The sub-type is deducted internally in Aktia’s services from the payment information.
Payments Periodic payments Periodic payments are posted in the same endpoint as the single payments endpoint. The sub-type is deducted internally in Aktia’s services from the payment information.
Transactions transactionAmount

Usage of transactionAmount in Pending transactions: Field is marked mandatory in BG specifications. TransactionAmount refers to amount in currency of the reported account. In case of pending transaction where currency of the payment differs from currency of the debtor account, transactionAmount is not known.

 

FX rate and thus the final amount in account currency is determined at the moment of booking the transaction. Due to this, transactionAmount is not mandatory field in Transactions-structure. Only insctuctedAmount is returned in these cases.

Accessing the live production

Accessing the live production data at Aktia using the PSD2 endpoints is straight forward and simple. There will be separate API products for the live production, so they are clearly separated from the Sandbox environment.

First of all, you will need to become a registered Third Party Provider. Contact a local Competent Authority (CA) and apply to become a registered TPP. There are three different roles you can apply for; Payment Initiation Service Provider (PISP), Account Information Service Provider (AISP), and Payment Instrument Issuer Service Providers (PIISP, aka. CBPII).

Secondly, you need an PSD2 eIDAS certificate, which you can get from a Qualified Trust Service Provider (QTSP). This certificate is used to identify you as a registered TPP.

Security

HTTP request signature

The following headers are required for the signature of the requests:

  • Digest of the request
  • Signature (eIDAS signature of the request)
  • TPP-Signature-Certificate. The certificate used for signing the request, in base64 encoding

For each HTTP request, Aktia requires a signature (eIDAS signature). The signature is created by combining the headers of the request with the digest of the request's using a standard HMAC-SHA256 keyed hash. The resulting signature is unique to each request and keeps our services secure and prevents misuse.

Mutual TLS handshake

Aktia implements mutual TLS for secure connection. All requests are made over https and TLS version 1.2 is recommended.

Testing the eIDAS certificate

Aktia provides endpoints for testing the eIDAS certificates. The endpoints are:

Payments

https://api.aktia.fi/api/sandbox/cert/psd2/pis/v1/{Endpoint}

Accounts

https://api.aktia.fi/api/sandbox/cert/psd2/ais/v1/{Endpoint}

These operations point to the Sandbox environment and works in the same way as the operations without the certification (where /cert/ is excluded from the path).

Personal Data

You can view and edit your personal data and opt out from any information and updates via email in My Account page.

If you have any questions about the use of your personal data, please contact us at: https://developer.aktia.fi/contact

Road map

Upcoming versions will be informed in advance and Aktia is eager to get feedback from third party developers!

Here’s a list of a few upcoming features in the Sandbox:

  1. Signing basket (possible to authorise several payments at once) - Released 10/04/2019
  2. TPP registration endpoint - Released 10/04/2019
  3. TLS Mutual Client Certificate Authentication for the TPP - Released 10/04/2019
  4. Live production release and piloting - Summer 2019