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.
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.
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.
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:
- Send a POST request to the consent API
- 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.
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.
- Account information service API
GET User Account List
GET User Account Details
GET Account balances
GET User Transaction List
- Payments initiation services API
POST SEPA payment initiation request
GET status of a payment
POST to start the authorisation process for a payment request
GET SCA status of the payment authorisation
- Confirmation of funds service API
POST Funds Confirmation