Authentication#

TPP Authentication#

In order to be able to identify itself TPP must use eIDAS QSEAL client certificate provided in approved Onboarding application together with Client-Id/Client-Secret pair generated by Holvi.

Each request requires a set of mandatory HTTP fields, as tabulated below:

Field	Description	Remarks
Host	HTTP header element for specification of the domain name of the server. Should be psd2.holvi.com for production.
Date	HTTP header element for date and time represented as RFC 7231 Full Dates. Example date: Wed, 24 Apr 2019 14:00:37 EEST	Except for Onboarding API.
Digest	Digest header as defined in RFC 3230 contains a Hash of the message body.	For POST/PATCH/PUT requests. Except for Onboarding API.
Signature	Application-level signature of the request by the TPP, using QSEAL certificate provided during Onboarding.	Except for Onboarding API.
X-Holvi-Client-Id	Client ID provided by Holvi, identifying the TPP Application. `tpp_client_id` field on approved Onboarding application instance.	Except for Onboarding API.
X-Holvi-Client-Secret	Client Secret provided by Holvi, authentication credentials of TPP. `tpp_client_secret` field on approved Onboarding application instance.	Except for Onboarding API.
Authorization	Access token retrieved in /api/v2/consent/initiate/usernamepassword/	Except for Onboarding API and /api/v2/consent/initiate/usernamepassword/

The signing process is made using Draft Cavage HTTP Signature method version 10 RFC defined by ietf.org.

All of the endpoints except of Onboarding require to use Signature header.

The only allowed algorithm is RSA-SHA256.
The key size for the used RSA key pair has to be at least 2048 bit.
The keyId is the Client-Id of your application originating from the approved Onboarding application.
The following headers are required to be used in the signature:
- GET and DELETE request: (request-target) Host Date
- POST, PUT and PATCH request: (request-target) Host Date Content-type Digest
- The request-target header is a combination of the HTTP action verb and the request URI path.

There are some examples how to make a request with required headers:

Python script

GET request headers example:

GET /api/v2/payment-accounts/ HTTP/1.1
Host: psd2.holvi.com
Date: Tue, 17 Sep 2019 15:00:58 GMT
Signature: keyId="testkeyid",algorithm="rsa-sha256",headers="(request-target) host date content-type digest",signature="CXe6Rkdq3aN8qrCGl...VJYO8D700dTn57w+jQ1L9Yw=="
X-Holvi-Client-Id: testkeyid
X-Holvi-Client-Secret: test_client_secret
Authorization: Bearer testJWTAccessToken

POST request headers example:

POST /api/v2/payment-initiation/ HTTP/1.1
Host: psd2.holvi.com
Date: Tue, 17 Sep 2019 15:00:58 GMT
Content-Type: application/json
Digest: SHA-256=6BP9BVkp4trTFi9Yjs2cnsHuWN21CpCrVvceSP/XQHI=
Signature: keyId="testkeyid",algorithm="rsa-sha256",headers="(request-target) host date content-type digest",signature="CXe6Rkdq3aN8qrCGl...VJYO8D700dTn57w+jQ1L9Yw=="
X-Holvi-Client-Id: testkeyid
X-Holvi-Client-Secret: test_client_secret
Authorization: Bearer testJWTAccessToken

Error codes#

The API returns the following HTTP status codes:

Code	Description
400 Bad Request	The request is invalid.
401 Unauthorized	The request headers are invalid or the certificate is not valid.
404 Not Found	The requested resource could not be found.
405 Method Not Allowed	The endpoint did not support the request method.
500 Internal Server Error	We had a problem with our servers. Please try again later.

User Authentication#

To authenticate a Payment Service User (PSU), direct them to the login endpoint and process the callback response as outlined below.

Initiating User Authentication#

Redirect the user to the following login URL:

https://psd2.holvi.com/login/

This endpoint accepts the following query parameters:

Parameter	Description	Remarks
`client_id`	A unique identifier for your application, obtained during onboarding.	Required. Can be retrieved from your onboarding application details.
`redirect_uri`	A preconfigured callback URL to which the user will be redirected after authentication.	Required. Must match one of the URIs specified in your onboarding or your TPP profile.

Example Login URL:

https://psd2.holvi.com/login/?client_id=testkeyid&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

After Authentication#

Once the user successfully logs in, they will be redirected to the specified redirect_uri with the following query parameter appended:

code: A unique authorization code to be exchanged for a JWT token.

Exchanging the Authorization Code for a Token#

To obtain a token, make a POST request to the /api/v2/consent/token/(string:code)/exchange/ endpoint with the authorization code.