Quickstart¶
Sign up as TPP via Onboarding API. See Prerequisites for learning about prerequisites to register as TPP.
Prepare request headers to access the API.
Get an access token via 2fa-login.
Read Services to start using the Holvi PSD2 API.
Prerequisites¶
The first public version of the Holvi PSD2 API uses the screen-scraping method to provide access to its data. We do not provide a sandbox environment and test certificates for testing purposes at the moment. TPPs must provide their eIDAS QSEAL client certificate during the onboarding process before starting to integrate with our API.
Onboarding API¶
-
POST
https://psd2.holvi.com/v1/onboarding/signup/
¶ Creates a new user to start TPP onboarding process.
Example request:
POST /v1/onboarding/signup/ HTTP/1.1 Accept: application/json { "email": "john@example.com", "first_name": "John", "last_name": "Doe", "password": "a-highly-secure-password" }
Example response:
HTTP/1.1 201 CREATED Vary: Accept Content-Type: application/json { "id": "d83da416-2f23-4f74-b366-c2682494f3f5", "email": "john@example.com", "first_name": "John", "last_name": "Doe" }
cURL command:
curl \ -H "Content-Type: application/json" \ -d '{"email":"john@example.com","first_name":"John","last_name":"Doe","password":"a-highly-secure-password"}' \ https://psd2.holvi.com/v1/onboarding/signup/
- Status Codes
201 Created – TPP user successfully created
400 Bad Request – invalid input
400 Bad Request – user already exists
-
POST
https://psd2.holvi.com/v1/onboarding/login/
¶ Logs in a TPP user and returns a JWT token to be used for future requests.
Example request:
POST /v1/onboarding/login/ HTTP/1.1 Accept: application/json { "email": "john@example.com", "password": "a-highly-secure-password" }
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "token_type": "Bearer", "id_token": "...", "expires_in": 300 }
cURL command:
curl \ -H "Content-Type: application/json" \ -d '{"email":"john@example.com","password":"a-highly-secure-password"}' \ https://psd2.holvi.com/v1/onboarding/login/
- Response JSON Object
id_token (string) – JWT token to be used for authentication
expires_in (integer) – expiration interval in seconds
- Status Codes
200 OK – TPP user successfully logged in
400 Bad Request – invalid input
-
POST
https://psd2.holvi.com/v1/onboarding/applications/
¶ Creates a new TPP application.
Example response:
HTTP/1.1 201 CREATED Vary: Accept Content-Type: application/json { "id": "6656d2df-8297-4802-847b-e1174395ccc9", "organisation_name": "Example Organization v2", "organisation_url": "https://www.example.com/", "is_approved": false, "tpp_client_id" :null, "tpp_client_secret": null }
cURL command:
curl \ -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer testJWTAccessToken" \ -F "client_certificate=@path-to-your-client-certificate.pem" \ -F "organisation_name=Example Organization" \ -F "organisation_url=https://www.example.com/" \ https://psd2.holvi.com/v1/onboarding/applications/
- Request Headers
Authorization – JWT token to authenticate
- Status Codes
201 Created – application successfully created
400 Bad Request – certificate is already registered
401 Unauthorized – unsuccessful authentication
-
GET
https://psd2.holvi.com/v1/onboarding/applications/
¶ Lists all TPP applications submitted by the owner of the token.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json [ { "id": "0d1fbc44-621b-4ff8-8fc7-a968d0a8b65b", "organisation_name": "Example Organization", "organisation_url": "https://www.example.com/", "is_approved": true, "tpp_client_id": "4bae5812c969c0ea5c2453b60c2ee3fa", "tpp_client_secret": "..." } ]
cURL command:
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer testJWTAccessToken" \ https://psd2.holvi.com/v1/onboarding/applications/
- Request Headers
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
-
GET
https://psd2.holvi.com/v1/onboarding/applications/
(string: application_uuid)/
¶ Retrieves TPP application specified as application_uuid.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "id": "0d1fbc44-621b-4ff8-8fc7-a968d0a8b65b", "organisation_name": "Example Organization", "organisation_url": "https://www.example.com/", "is_approved": true, "tpp_client_id": "4bae5812c969c0ea5c2453b60c2ee3fa", "tpp_client_secret": "..." }
cURL command:
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer testJWTAccessToken" \ https://psd2.holvi.com/v1/onboarding/applications/0d1fbc44-621b-4ff8-8fc7-a968d0a8b65b/
- Parameters
application_uuid – UUID of the TPP application that can be fetched from
GET https://psd2.holvi.com/v1/onboarding/applications/
- Request Headers
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
404 Not Found – TPP application given by application_uuid cannot found
Certificate renewal¶
A certificate can be renewed at any time for an application using the following endpoint:
-
POST
https://psd2.holvi.com/v1/renew-certificate/
¶ Renews a certificate for the given application_uuid.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "application_id": "d83da416-2f23-4f74-b366-c2682494f3f5", "new_certificate": "-----BEGIN CERTIFICATE-----...", }
cURL command:
curl \ -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer testJWTAccessToken" \ -F "new_certificate=@path-to-your-client-certificate.pem" \ -F "application_id=d83da416-2f23-4f74-b366-c2682494f3f5" \ https://psd2.holvi.com/v1/renew-certificate/
- Status Codes
200 OK – certificate renewed correctly
400 Bad Request – invalid certificate
400 Bad Request – unknown application id
400 Bad Request – certificate file too big
Accessing API¶
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.
|
Except for Onboarding API. |
X-Holvi-Client-Secret |
Client Secret provided by Holvi,
authentication credentials of TPP.
|
Except for Onboarding API. |
Authorization |
Access token retrieved in /v1/consent/initiate/usernamepassword/ |
Except for Onboarding API and /v1/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:
GET request headers example:
GET /screen-scraping/v1/accounts/testing/transactions?state=paid 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",signature="gi5sv23GbvRXzF0mBWQ0q9nuDx6DyBG3VqEzVbG8CEI2vYHJUaf2Q88e8kEm6coAQKlp4iy7cHk0JL7s5zPA121j7OIDomDSenRBeFcEkWkeKYYaE1UtJji2vb7xvqcxTP1xkVQ0tJcMAqttWOAKMh/nYa0Jcdtwe3Qkpv/gION9AfC5ZJ+mhFcyWzuDF0x0kDKtlWriOe7gBl/I42jsMOuuQxBtLPEwrGK65mzsHS/r2GFGuuEybXhlkR5mJzQuFeEWdkgkgw1NTezkahebNYwlfptmLGso8YyAdzhGCnsGL6VuUj1gpyl5J4vzzxvpnmqXwFSPT1AouRLtE11AYw=="
X-Holvi-Client-Id: testkeyid
X-Holvi-Client-Secret: test_client_secret
Authorization: Bearer testJWTAccessToken
POST request headers example:
POST /screen-scraping/v1/testing/debt/ 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="CXe6Rkdq3aN8qrCGlYRW/Am0ImD/ezPu8+fzHOHcz7bhe0kvWv55cI+bN5kiJTBJpsEKfoW3+sQTRF7+O4y83aAyBuK8gnftqOeWcqFs+yoEvWIuTJGtEFcBbMQ87J2JkKfPW1fPfezTmVN90aT0RuB1HbHCB2sqycSeLgfpvvUStNgpmQMhpiIhH5IpQnKkUEziPNukYYeLN0NIHTa6wcikr/USZ6lMxwh94CyWFNRCfc7WzUP9e+N+oBdgU0sJ8WMbVZiHRTUzN+9LuxuqScUrtvbUP5HXYhbvJ/dot9Nl53klgc3MefK+Hl8GhgwVJYO8D700dTn57w+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
https://psd2.holvi.com/v1/consent/initiate/usernamepassword/
¶ See Accessing API for the full list of headers required to use this endpoint.
Example request:
POST /v1/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" }
- Response JSON Object
id (uuid) – token must be passed as token_uuid in
GET https://psd2.holvi.com/v1/consent/token/(string:token_uuid)/exchange/
- Status Codes
201 Created – no error
400 Bad Request – invalid credentials or user cannot use SCA flow
401 Unauthorized – unsuccessful authentication
-
GET
https://psd2.holvi.com/v1/consent/token/
(string: token_uuid)/exchange/
¶ Issues a JWT token to be used for accessing the API on behalf of a PSU.
See Accessing API 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
POST https://psd2.holvi.com/v1/consent/initiate/usernamepassword/
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
404 Not Found – token_uuid not found, user has not given authorisation (or declined)
Services¶
Note
The current implementation of the PSD2 API uses the screen scraping method, which would result in returning information that is only needed for internal usage.
Account Information Service¶
-
GET
https://psd2.holvi.com/screen-scraping/v1/accounts/
¶ Returns a list of accounts for the given JWT token issued for a PSU.
See Accessing API for the full list of headers required for this endpoint.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json [ { "code": "a645038bc51a711dd5850e379bda845e", "name": "How-Do", "handle": "testing", "vat_liable": true, "iban": "FI6379977992025523", "gb_sort_code": "", "gb_account_number": "", "image_url": null, "account_balance": "27971.00", "account_blocked_balance": "0", "account_fees_payables_balance": "0", "account_available_balance": "27971.00", "budgetingperiod_profit": "-23888.20", "url": "/group/testing+how-do/", "archived": false, "name_slug": "how-do", "currency": "EUR", "payment_account_state": "active", "payment_account_state_reason": null } ]
- Request Headers
Host – must be psd2.holvi.com
Date – must follow the format described in 7.1.1.1 of RFC 7231
Signature – see Accessing API for more details
X-Holvi-Client-Id – client ID provided by Holvi
X-Holvi-Client-Secret – client secret provided by Holvi
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
-
GET
https://psd2.holvi.com/screen-scraping/v1/accounts/
(string: pool_handle)/
¶ Returns an account information from pool_handle.
See Accessing API for the full list of headers required to use this endpoint.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "code": "a645038bc51a711dd5850e379bda845e", "name": "How-Do", "handle": "testing", "vat_liable": true, "iban": "FI6379977992025523", "gb_sort_code": "", "gb_account_number": "", "image_url": null, "account_balance": "27971.00", "account_blocked_balance": "0", "account_fees_payables_balance": "0", "account_available_balance": "27971.00", "budgetingperiod_profit": "-23888.20", "url": "/group/testing+how-do/", "archived": false, "name_slug": "how-do", "currency": "EUR", "payment_account_state": "active", "payment_account_state_reason": null }
- Parameters
pool_handle – handle of the pool that can be fetched from
GET https://psd2.holvi.com/screen-scraping/v1/accounts/
- Request Headers
Host – must be psd2.holvi.com
Date – must follow the format described in 7.1.1.1 of RFC 7231
Signature – see Accessing API for more details
X-Holvi-Client-Id – client ID provided by Holvi
X-Holvi-Client-Secret – client secret provided by Holvi
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
-
GET
https://psd2.holvi.com/screen-scraping/v1/accounts/
(string: pool_handle)/transactions/
¶ Returns a list of transactions for pool_handle.
See Accessing API for the full list of headers required to use this endpoint.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "count": 306, "next": "https://psd2.holvi.com/screen-scraping/v1/accounts/testing/transactions/?page=2", "previous": null, "results": [ { "uuid": "c31fc2f1-e9d2-47e3-a7ed-1fa33ef5ea14", "pool": "testing", "creditor": { "name": "How-Do", "firstname": "", "lastname": "", "iban": "FI6379977992025523", "bic": "HOLVFIHH", "gb_sort_code": "", "gb_account_number": "", "street": "", "city": "", "postcode": "", "country": "", "email": "", "phone": "", "company": "Demo company", "eu_vat_identifier": "FI00000000", "display_name": "How-Do" }, "debtor": { "name": "John's toolshop", "firstname": "", "lastname": "", "iban": "", "bic": "", "gb_sort_code": "", "gb_account_number": "", "street": "", "city": "", "postcode": "", "country": "", "email": "", "phone": "", "company": "", "eu_vat_identifier": "", "display_name": "John's toolshop" }, "counterparty": { "name": "John's toolshop", "firstname": "", "lastname": "", "iban": "", "bic": "", "gb_sort_code": "", "gb_account_number": "", "street": "", "city": "", "postcode": "", "country": "", "email": "", "phone": "", "company": "", "eu_vat_identifier": "", "display_name": "John's toolshop" }, "amount": "800.00", "currency": "EUR", "ux_timestamp": "2014-01-23T00:00:00Z", "execution_timestamp": "2014-01-23T00:00:00Z", "booking_date": "2014-01-23", "due_date": null, "state": "paid", "method": "sepa", "type": "push", "direction": "in", "unstructured_reference": "", "structured_reference": "", "end_to_end_id": "", "execution_for_debt": null, "identifier": "OSXYICNM84TQ", "generic_description": "IBAN Payment", "submethod": "" }, ] }
Note
The response is shortened for brevity.
- Parameters
pool_handle – handle of the pool that can be fetched from
GET https://psd2.holvi.com/screen-scraping/v1/accounts/
state – one of paid, scheduled
- Request Headers
Host – must be psd2.holvi.com
Date – must follow the format described in 7.1.1.1 of RFC 7231
Signature – see Accessing API for more details
X-Holvi-Client-Id – client ID provided by Holvi
X-Holvi-Client-Secret – client secret provided by Holvi
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
- Response JSON Array of Objects
state (string) – Payment state constants
-
GET
https://psd2.holvi.com/screen-scraping/v1/accounts/
(string: pool_handle)/transactions/
(string: transaction_id)/
¶ Returns a transaction specified by transaction_id for pool_handle.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "uuid": "c31fc2f1-e9d2-47e3-a7ed-1fa33ef5ea14", "pool": "testing", "creditor": { "name": "How-Do", "firstname": "", "lastname": "", "iban": "FI6379977992025523", "bic": "HOLVFIHH", "gb_sort_code": "", "gb_account_number": "", "street": "", "city": "", "postcode": "", "country": "", "email": "", "phone": "", "company": "Demo company", "eu_vat_identifier": "FI00000000", "display_name": "How-Do" }, "debtor": { "name": "John's toolshop", "firstname": "", "lastname": "", "iban": "", "bic": "", "gb_sort_code": "", "gb_account_number": "", "street": "", "city": "", "postcode": "", "country": "", "email": "", "phone": "", "company": "", "eu_vat_identifier": "", "display_name": "John's toolshop" }, "counterparty": { "name": "John's toolshop", "firstname": "", "lastname": "", "iban": "", "bic": "", "gb_sort_code": "", "gb_account_number": "", "street": "", "city": "", "postcode": "", "country": "", "email": "", "phone": "", "company": "", "eu_vat_identifier": "", "display_name": "John's toolshop" }, "amount": "800.00", "currency": "EUR", "ux_timestamp": "2014-01-23T00:00:00Z", "execution_timestamp": "2014-01-23T00:00:00Z", "booking_date": "2014-01-23", "due_date": null, "state": "paid", "method": "sepa", "type": "push", "direction": "in", "unstructured_reference": "", "structured_reference": "", "end_to_end_id": "", "execution_for_debt": null, "identifier": "OSXYICNM84TQ", "generic_description": "IBAN Payment", "submethod": "" }
- Parameters
pool_handle – handle of the pool that can be fetched from
GET https://psd2.holvi.com/screen-scraping/v1/accounts/
transaction_id – transaction identifier that can be fetched from the identifier field in
GET https://psd2.holvi.com/screen-scraping/v1/accounts/(string:pool_handle)/transactions/
- Request Headers
Host – must be psd2.holvi.com
Date – must follow the format described in 7.1.1.1 of RFC 7231
Signature – see Accessing API for more details
X-Holvi-Client-Id – client ID provided by Holvi
X-Holvi-Client-Secret – client secret provided by Holvi
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
- Response JSON Object
state (string) – Payment state constants
Payment Initiation Service¶
-
POST
https://psd2.holvi.com/screen-scraping/v1/
(string: account_identifier)/debt/
¶ Creates a new payment.
See Accessing API for the full list of request headers required for this endpoint.
Example request:
POST /screen-scraping/v1/testing/debt/ HTTP/1.1 Accept: application/json Authorization: Bearer testJWTAccessToken { "iban": "FI1979981000891140", "bic": "HOLVFIHH", "receiver": { "name": "Jane Doe" }, "due_date": "2019-10-03", "items": [ { "description": "Item description", "detailed_price": { "net": 100, "gross": 100 } } ], "pool_handle": "testing", "unstructured_reference": "UNST-REF-123", "end_to_end_id": "ab8c9e20-848a-11ee-b962-0242ac120002" }
Example response:
HTTP/1.1 201 CREATED Vary: Accept Content-Type: application/json { "uuid": "311c480c-943c-4ef0-988f-fe1214bb6a97", "type": "outboundpayment", "subtype": "outbound", "items": [ { "uuid": "10f760d5-2ca1-4507-91af-98b35a29c290", "type": "line_item", "debt": "c2e96c161aa1d7e1d6d6dff2ef3e09b7", "payment": null, "category": "d0b641dd49762d4a4d4e16c1700d6bb6", "detailed_price": { "net": "100.00", "gross": "100.00", "vat_rate": "f6ab22c4147884623abcd5298997f9b1", "currency": "EUR" }, "quantity": "1", "description": "Item description", "timestamp": "2019-09-06T12:39:32.479Z", "approved": null, "product": null, "product_name": "", "product_type": "default", "receipt_message": "", "detailed_original_price": null, "discount_code": null, "active": true, "attachments": [], "vat_status": "", "detailed_total_price": { "net": "100.00", "gross": "100.00", "vat_rate": "f6ab22c4147884623abcd5298997f9b1", "currency": "EUR" }, "vat_calculation_rule": "legacy", "unit": "", "unit_label": "" } ], "status": "unverified", "subject": "", "issue_date": "2019-09-06", "due_date": "2019-09-20", "recurrence": null, "original_standing_order": null, "message": "", "iban": "FI1979981000891140", "bic": "HOLVFIHH", "currency": "EUR", "gb_sort_code": null, "gb_account_number": null, "sender": null, "receiver": { "code": "ba6446ec532a89b3588f8037990ec328", "name": "BigBon", "street": "", "city": "", "postcode": "", "country": "", "email": "", "einvoice_address": "", "firstname": "", "lastname": "", "phone": "", "company": "", "eu_vat_identifier": "", "iban": "", "bic": "", "einvoice_scheme": null, "gb_sort_code": "", "gb_account_number": "", "business_identifier": "", "einvoice_operator": null, "save_to_contacts": true, "contact": null }, "year": null, "number": null, "number_prefix": "", "number_creditnote": null, "fi_reference": "", "rf_reference": "", "unstructured_reference": "UNST-REF-123", "end_to_end_id": "", "structured_reference": "", "structured_reference_type": "", "attachments": [], "comments": [], "outbound_payment": "c2e96c161aa1d7e1d6d6dff2ef3e09b7", "code": "c2e96c161aa1d7e1d6d6dff2ef3e09b7", "timestamp": "2019-09-06T12:39:32.317Z", "links": {}, "tags": [], "invoicing_lang": "", "delivery_date_from": null, "delivery_date_to": null, "value": "100.00", "settled_value": "0", "non_settled_value": "100.00", "adjusted_value": "100.00", "non_settled_adjusted_value": "100.00", "footer_text": null, "buyer_reference": null, "order_reference": null, "external_identifier": "", "vat_breakdown": [], "special_type": null }
- Parameters
account_identifier –
this value can either be:
the handle of the pool, which can be fetched from the following endpoint:
GET https://psd2.holvi.com/screen-scraping/v1/accounts/
the IBAN of the account.
- Request JSON Object
iban (string) – account IBAN
bic (string) – (optional) account BIC
receiver (json) – payment receiver
due_date (string) – ISO 8601 date string
items (json) – payment items
pool_handle (string) – payment pool handle
unstructured_reference (string) – max length of 140 characters
end_to_end_id (string) – (optional) max length of 36 characters
- Request Headers
Host – must be psd2.holvi.com
Date – must follow the format described in 7.1.1.1 of RFC 7231
Digest – see Accessing API for more details
Signature – see Accessing API for more details
X-Holvi-Client-Id – client ID provided by Holvi
X-Holvi-Client-Secret – client secret provided by Holvi
Authorization – JWT token to authenticate
- Status Codes
201 Created – no error
401 Unauthorized – unsuccessful authentication
- Response JSON Object
status (string) – Payment state constants
-
POST
https://psd2.holvi.com/screen-scraping/v1/debt/confirm/
¶ Starts confirmation of a payment.
See Accessing API for the full list of request headers required for this endpoint.
Example request:
POST /screen-scraping/v1/debt/confirm/ HTTP/1.1 Accept: application/json Authorization: Bearer testJWTAccessToken { "debt_uuid": "8dc3fbc1-a60c-4445-9eb3-4233d8cfec64" }
Example successful response:
HTTP/1.1 201 CREATED Vary: Accept Content-Type: application/json { "status": "success" }
- Request JSON Object
debt_uuid (string) – UUID of the debt object
- Status Codes
201 Created – no error
400 Bad Request – invalid input
401 Unauthorized – unsuccessful authentication
404 Not Found – debt cannot found
-
GET
https://psd2.holvi.com/screen-scraping/v1/
(string: account_identifier)/debt/
(string: debt_uuid)/
¶ Returns details of debt_uuid.
See Accessing API for the full list of request headers required for this endpoint.
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "uuid": "e6bf0210-2241-469b-a5a2-668f65d3f4ad", "type": "outboundpayment", "subtype": "outbound", "items": [ { "uuid": "6672c55a-1984-42a5-87dd-135e08f88410", "type": "line_item", "debt": "7f5e1bf1f2fd7feee162f17229652619", "payment": null, "category": "254e3fe714528c63ce45bcbd2344d1a3", "detailed_price": { "net": "18.55", "gross": "23.00", "vat_rate": "94af9c0b796f6d2fe2af8e5e6519a4f3", "currency": "EUR" }, "quantity": "1", "description": "Equipment / tools", "timestamp": "2019-08-21T21:05:36.935Z", "approved": null, "product": null, "product_name": "", "product_type": "default", "receipt_message": "", "detailed_original_price": null, "discount_code": null, "active": true, "attachments": [], "vat_status": "", "detailed_total_price": { "net": "18.55", "gross": "23.00", "vat_rate": "94af9c0b796f6d2fe2af8e5e6519a4f3", "currency": "EUR" }, "vat_calculation_rule": "legacy", "unit": "", "unit_label": "" } ], "status": "notenoughbalance", "subject": "Equipment / tools", "issue_date": "2019-08-21", "due_date": null, "recurrence": null, "original_standing_order": null, "message": "", "iban": "FI1979981000891140", "bic": "HOLVFIHH", "currency": "EUR", "gb_sort_code": null, "gb_account_number": null, "sender": { "code": "f8169ce721f3e0f36d00d3d53cf5864b", "name": "How-Do", "street": "", "city": "", "postcode": "", "country": "", "email": "", "einvoice_address": "", "firstname": "", "lastname": "", "phone": "", "company": "No name company", "eu_vat_identifier": "FI00000000", "iban": "FI6379977992025523", "bic": "HOLVFIHH", "einvoice_scheme": null, "gb_sort_code": "", "gb_account_number": "", "business_identifier": "", "einvoice_operator": null, "save_to_contacts": true, "contact": null }, "receiver": { "code": "d96f325412a115e5ae5d2183102206d2", "name": "Lauren Scott", "street": "", "city": "", "postcode": "", "country": "", "email": "", "einvoice_address": "", "firstname": "", "lastname": "", "phone": "", "company": "", "eu_vat_identifier": "", "iban": "FI1979981000891140", "bic": "HOLVFIHH", "einvoice_scheme": null, "gb_sort_code": "", "gb_account_number": "", "business_identifier": "", "einvoice_operator": null, "save_to_contacts": true, "contact": null }, "year": null, "number": null, "number_prefix": "", "number_creditnote": null, "fi_reference": "1070", "rf_reference": "", "unstructured_reference": "", "end_to_end_id": "", "structured_reference": "", "structured_reference_type": "", "attachments": [], "comments": [], "outbound_payment": "7f5e1bf1f2fd7feee162f17229652619", "code": "7f5e1bf1f2fd7feee162f17229652619", "timestamp": "2019-08-21T21:05:36.898Z", "links": { "card_profile": null }, "tags": [], "invoicing_lang": "", "delivery_date_from": null, "delivery_date_to": null, "value": "23.00", "settled_value": "0", "non_settled_value": "23.00", "adjusted_value": "23.00", "non_settled_adjusted_value": "23.00", "footer_text": null, "buyer_reference": null, "order_reference": null, "external_identifier": "", "vat_breakdown": [ [ "24.00", "4.45" ] ], "special_type": null, "last_payment_timestamp": "2019-08-21T21:05:36.898Z" }
- Parameters
account_identifier –
this value can either be:
the handle of the pool, which can be fetched from the following endpoint:
GET https://psd2.holvi.com/screen-scraping/v1/accounts/
the IBAN of the account.
debt_uuid – UUID of the debt
- Request Headers
Host – must be psd2.holvi.com
Date – must follow the format described in 7.1.1.1 of RFC 7231
Signature – see Accessing API for more details
X-Holvi-Client-Id – client ID provided by Holvi
X-Holvi-Client-Secret – client secret provided by Holvi
Authorization – JWT token to authenticate
- Status Codes
200 OK – no error
401 Unauthorized – unsuccessful authentication
404 Not Found – debt cannot found
- Response JSON Object
status (string) – Payment state constants
Glossary¶
- AISP
account information service provider
- ASPSP
account servicing payment service provider
- PSP
payment service provider
- PISP
payment initiation service provider
- PSP
payment services providers
- PSU
payment service user
- TPP
third party provider