PSD2 Interface

Last updated

Holvi PSD2 API

The purpose of this documentation is to introduce the draft specification of API that will be available for accessing the Holvi customer accounts in line with PSD2 requirements. This documentation can significantly change during the following months. Before the API is ready for production, we will provide a PSD2 compliant screen scraping facilities that could also be used as a fallback mechanism for the API in the future.

The API currently follows the Berlin Group specifications XS2A Interface Interoperability Framework and may be extended to cover further information, beyond what is covered by the PSD2 regulation. Current implementation and services that exist are based on 1.3 release of the Berlin Group X2SA specification.

Explore Berlin Group X2SA and Implementation Guidelines and Swagger schema.

The exposure of data is done through RESTful services and for the most part both requests and responses are in JavaScript Object Notation (JSON) format.


API Overview

The API consists of three core services:

  • Account Information Services (AIS) as defined by article 67 in the PSD2 Directive.
  • Payment Initiation services (PIS) as defined by Article 66 in the PSD2 Directive.  
  • Confirmation on the availability of funds as defined by Article 65 in the PSD2 Directive. Security and consent services (SEC) to create consent and request an oauth token.


Holvi is following the Berlin Group API specification and where it is needed extensions can be made to cover the full set of requirements needed for the service. The communication between the Third Party Provider (TPP) and Holvi is always secured by using TLS version 1.2 or higher. Later when the RTS is implemented additional checks against a TPP certificate will be implemented but at the time of this writing the requirements are not fixed.


Using API

To be able to use the API there are the following requirements:  

  • Proving in the request header Authorization with a value of Bearer (token authentication). This value will be validated in all the requests.  
  • X-Request-ID must be unique per request. This is a mandatory header throughout the API.  
  • Date must be added to request header. This is a mandatory header throughout the API.

In order to get access to Holvi customer’s resource the resource owner (Holvi customer) grants the permission for the TPP application (consumer of the API) to use API resources. This permission is given by giving the consent after authentication.


Error Codes

Every response returned by this API has a response code. Response codes can be used to check the result of the requests, e.g, success or fail.


Success reason codes:

Redirect reason codes:


Failure reason codes:



Authentication and security


There are two steps to getting the consent of a user for TPPs:

  1. Send a POST request to the consent API
  2. Invoke the OAuth2.0 flow to have the customer confirming the consent with strong customer authorization.

After this the TPP can collect the OAuth token to use as the authentication mechanism to use on behalf of the PSU when using the PSD2 API. Such token will expire in 90 days.

API endpoints

The API endpoints URLs can be changed in the future and only an overview of available methods is provided in this chapter. The examples for these methods can be found in Berlin Group X2SA Implementation Guidelines.


  1. Account information service API

GET User Account List


GET User Account Details{AccountResourceID}

GET Account balances{AccountResourceID}/balances

GET User Transaction List{AccountResourceId}/transactions

  1. Payments initiation services API

POST SEPA payment initiation request

GET status of a payment{PaymentResourceId}/status

POST to start the authorisation process for a payment request{PaymentResourceId}/authorisations

GET SCA status of the payment authorisation{PaymentResourceId}/authorisations/{AuthorisationResourceID}

  1. Confirmation of funds service API

POST Funds Confirmation

Was this article helpful?

2 out of 2 found this helpful