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.

Authentication

2FA login with SCA

POST /api//v2/consent/initiate/usernamepassword/

See the authentication documentation for the full list of headers required to use this endpoint.

Example Request:

POST /api/v2/consent/initiate/usernamepassword/ HTTP/1.1
Accept: application/json

{
    "email": "psu@example.com",
    "password": "psu-user-password"
}

Example response:

HTTP/1.1 201 CREATED
Vary: Accept
Content-Type: application/json

{
    "short_code": "S7YG",
    "state": "open",
    "creation_time": "2019-11-15T05:07:41.299915Z",
    "id": "be2bc8d9-c2b8-4d12-ac6f-5d5c1f353378",
    "expiration_time": "2019-11-15T08:27:41.280062Z"
}

Parameters

• <uuid> id: Token must be passed as token_uuid in /api/v2/consent/token/(string:token_uuid)/exchange/

Status Codes:

• 201: No error

• 400: Invalid credentials or user cannot use SCA flow

• 401: Unsuccessful authentication

POST /api/v2/consent/token/(string:token_uuid)/exchange/

Issues a JWT token to be used for accessing the API on behalf of a PSU (payment service user).

See the :doc:authentication documentation</authentication> for the full list of headers required to use this endpoint.

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "token_type": "Bearer",
    "id_token": "...",
    "expires_in": 7750774
}

Parameters

• token_uuid: Token UUID can be retrieved from the id field of the POST response.

Status Codes

• 200: No error

• 401: Unsuccessful authentication

• 404: token_uuid not found, user has not given authorization (or declined)