Quickstart

  1. Sign up as TPP via Onboarding API. See Prerequisites for learning about prerequisites to register as TPP.

  2. Prepare request headers to access the API.

  3. Get an access token via 2fa-login.

  4. 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.

Contact

You can reach out to our team to get support on using the PSD2 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
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
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
Status Codes
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
Status Codes
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
Request Headers
Status Codes

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

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. 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 /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
Status Codes

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
Status Codes

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
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
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
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
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
Response JSON Array of Objects
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
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
Response JSON Object

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
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
Response JSON Object
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
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
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
Response JSON Object

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