Introduction to LHV Open Banking

Introduction

Welcome to LHV Open Banking & PSD2 API page!
Here you will find all the needed information to get started with our API, including:

• access and usage
• environments
• introduction to services and details

Our PSD2 API covers the features listed in PSD2 regulation, including:

• Account Information Service (AIS)
• Payment Initiation service (PIS)
• Confirmation on the Availability of Funds Service (FCS or AIIS)

Our API is a REST API interface based on the Berlin Group Standard. You can obtain the full documentation here.

LHV Status Page - information and announcements about LHV services status and any interruptions.

Latest Updates

Access and Usage

You can integrate with our API if you are:

• third Party Payment Service Provider aka TPP - a company who is developing some app or system which requests access to private or corporate LHV customers accounts
• other bank or credit institution aka ASPSP.

To start using the Open Banking API in live you should first obtain a valid licence from the authorities - Estonian Finance Inspection.
Banks (ASPSPs) hold this licence already by default.
More information here.

To verify if you are authorized to use the services you can check the EBA online database: https://euclid.eba.europa.eu/register/

We also provide a Sandbox testing environment which you can use when preparing for your live integration or just trying out the Open Banking features.
It is also free to use by everybody and no licence is required.

Access Certificates

Our API is using the PSD2 compliant eIDAS QWAC transport layer certificate for identifying and verifying the TPP. eIDAS QSEAL certificate is not required or supported for now.
No other methods or certificate types are supported currently.

You can order the QWAC certificate from a number of different providers across Europe - provided you are holding the TPP licence mentioned above.
You can read about these here.

Some key principles about certificates and validation:

• the key of identifying any TPP is the PSD2 ID in the certificate. It is normally in the Subject (2.5.4.97) field. For example LHV is NTREE-10060701. All the OAuth tokens, consents etc. are related to this ID value.
• we do support using multiple valid certificates in parallel. This is especially important when any existing certificate is going to expire soon and TPP wants to start using a new one. Then it is possible to use both during their validity for testing purposes and backup - on the condition that the PSD2 ID is the same.
• we are constantly monitoring lists of valid CA providers to validate your QWAC certificates - based on the eIDAS Trusted Lists Browser: https://webgate.ec.europa.eu/tl-browser/#/
• when TPP starts using a new certificate and PSD2 TPP ID remains the same there is no need to register the new certificate with LHV. It should be accepted automatically.

Opening access and first usage

We do not require signing any agreements or have extra validation procedures when granting access to live.

It is not required to send us your PSD2 eIDAS certificates manually. We will receive your certificate automatically when you make a request to our dedicated TPP registration service GET /v1/tpp-verification.
After making the successful request please contact us at openbanking@lhv.ee and we will grant you access in a few hours.

The service provides also additional info like your TPP name, ID and enabled roles.

• Request - GET /v1/tpp-verification

HTTP headers:

• Sample response - certificate technical validation succeeded. Connection still not enabled and waiting for support team validation.

{
    "access": "BLOCKED",
    "tppId": "PSDEE-LHVTEST-402383",
    "name": "PSD2 Test",
    "roles": [
        "AIS",
        "PIS",
        "PIIS"
    ]
}

• Sample response - everything validated and connection enabled

{
    "access": "ENABLED",
    "tppId": "PSDEE-FI-10539549",
    "name": "AS LHV Pank",
    "roles": [
        "AIS",
        "PIS",
        "PIIS"
    ]
}

• Sample response - certificate not valid

{
    "tppMessages": [
        {
            "category": "ERROR",
            "code": "CERTIFICATE_INVALID"
        }
    ]
}

Environments

Live

As described below in Access and Usage section you can get live access only with official licencing and production QWAC certificate.

Live base url is: https://api.lhv.eu/psd2/v1

Sandbox

Sandbox test environment is our free to access testing environment. It is technically also very similar to live environment - the services, JSon structure etc. is the same.

Link to Sandbox - https://api.sandbox.lhv.eu/psd2/swagger-ui/index.html?configUrl=/psd2/documentation/api-docs/swagger-config

There is no dedicated developers portal or account required to start using the Sandbox. You can use Sandbox directly in Swagger or similar to live -
executing the API endpoints directly using your own developed client application or some testing tool like Postman.

Base url of Sandbox is: https://api.sandbox.lhv.eu/psd2/v1

Access certificate

Sandbox is not using production QWAC certificates, but custom testing certificates which you can generate automatically.
Create your own certificate here.
Store the Private key and Certificate contents as *.key and *.crt files. You can use these like you would use official certificate and key in production.
Please extract your TPP id from the certificate file. It should be visible on Subject > 2.5.4.97 field and should look like PSDEE-LHVTEST-[random combination]
For example - PSDEE-LHVTEST-c1dec9
Use this value in your OAuth request client_id. For example: https://api.sandbox.lhv.eu/psd2/oauth/authorize?scope=psd2&response_type=code&client_id=PSDEE-LHVTEST-c1dec9&redirect_uri=http%3A%2F%2Flocalhost%2Fapi&state=st1

Sandbox Swagger is using built-in default access certificate with client_id value PSDEE-LHVTEST-01AAA

This TPP id value is similar and used the same way as your id in production. For example LHV Pank TPP id is PSDEE-FI-10539549.

Accounts and data

Sandbox has the following default OAuth access tokens and accounts available:

• bearer Liis-MariMnnik: EE717700771001735865, EE277700771001735881, EE457700779900289935. PSU-Corporate-ID value for customer verification is EE47101010033.
• bearer Donaldduck: EE857700771001735904

You can use these access tokens and accounts in combination provided or use the same account numbers with your own access tokens.

Services

Our API has two main sets of services:

• OAuth 2.0 services for user identification. OAuth token is needed to get access to other services.
• services covering the NextGenPSD2 specification of Berlin Group standard.

All our services are using SCA (strong customer authentication) based on redirect method!

OAuth

OAuth 2.0 services are used for user identification and authentication. The acquired access token must be used to get access to actual NextGenPSD2 services.

We are supporting Redirect and Decoupled SCA methods.

Redirect method and OAuth User Interface

To begin the authentication process you must first redirect your customer to the login UI page.

Use the URI https://api.lhv.eu/psd2/oauth/authorize with the following GET query parameters:

The same authentication options are available as in LHV Internet Bank - Smart-ID, Mobile-ID, Biometrics, ID Card and PIN Calculator. When authentication succeeds, user is redirected to TPP system defined in the redirect_uri parameter with an additional access code (GET parameter "code").

Sample links:

• sandbox: https://api.sandbox.lhv.eu/psd2/oauth/authorize?scope=psd2&response_type=code&client_id=PSDEE-LHVTEST-01AAA&redirect_uri=https://tppsystem.com/callback&state=1
• production: https://api.lhv.eu/psd2/oauth/authorize?scope=psd2&response_type=code&client_id=PSDEE-FI-10539549&redirect_uri=https://tppsystem.com/callback&state=1

After authentication the user will be redirected back to the URI specified in redirect_uri and the address will be appended with the following query parameters:

Decoupled method

Start Decoupled Authorisation

To begin the authorisation process you must execute the Authorisations service: POST /v1/oauth/authorisations
Upon incoming request the username and another value (depending on the selected method) will be matched and if a correct match is found then an authorisation process is started and a verification code is returned for Biometrics, Smart-ID and Mobile-ID.

• Request

HTTP headers:

Body:

• Sample - BIO:

POST https://api.lhv.eu/psd2/v1/oauth/authorisations
Content-Type: application/json
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
PSU-ID: Liis-MariMnnik
Date: Sun, 06 Aug 2017 15:02:37 GMT

{
    "authenticationMethodId": "BIO"
}

• Sample - MID:

POST https://api.lhv.eu/psd2/v1/oauth/authorisations
Content-Type: application/json
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
PSU-ID: Liis-MariMnnik
Date: Sun, 06 Aug 2017 15:02:37 GMT

{
    "authenticationMethodId": "MID",
    "scaAuthenticationData": "+3725127862"
}

• Sample - SID:

POST https://api.lhv.eu/psd2/v1/oauth/authorisations
Content-Type: application/json
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
PSU-ID: Liis-MariMnnik
PSU-Corporate-ID: EE47101010033
Date: Sun, 06 Aug 2017 15:02:37 GMT

{
    "authenticationMethodId": "SID"
}

• Response

HTTP headers:

Body:

• Sample:

HTTP/1.x 201 Created
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
Date: Sun, 06 Aug 2017 15:02:42 GMT
Content-Type: application/json
{
    "authorisationId": "245074d5-cf8d-4823-8164-a311b33b0ed0",
    "scaStatus": "scaMethodSelected",
    "chosenScaMethod": {
        "authenticationType": "SMS_OTP",
        "authenticationMethodId": "MID"
    },
    "challengeData": {
        "data": "1234",
        "additionalInformation": "Authenticate user"
    },
    "_links": {
        "scaStatus": {
            "href": "https://api.lhv.eu/psd2/v1/oauth/authorisations/245074d5-cf8d-4823-8164-a311b33b0ed0"
        }
    }
}

Check Decoupled Authorisation status

GET /v1/oauth/authorisations/:authorisationId

This service is used to check the status of an authentication and to retrieve authentication code which can be exchanged for a token. Also shows the available roles if the authentication was successful. Once the code is used and a token is generated the next request will change the status to SPENT and the TPP will no longer be able to see information about selected or available roles.

• Request

authorisationId - authorisationId returned by Start Decoupled Authorisation service

HTTP headers:

Sample:

GET https://api.lhv.eu/psd2/v1/oauth/authorisations/99391c7e-ad88-49ec-a2ad-99ddcb1f7722
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
Date: Sun, 06 Aug 2017 15:02:37 GMT

• Response

HTTP headers:

Body:

• Sample - authorisation started:

HTTP/1.x 200 OK
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
Content-Type: application/json
Date: Sun, 06 Aug 2017 15:02:42 GMT
{
    "scaStatus": "started"
}

• Sample - Failed status with TPP message:

HTTP/1.x 200 OK
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
Content-Type: application/json
{
    "scaStatus": "failed",
    "tppMessages": [
        {
            "category": "ERROR",
            "code": "WRONG_VC",
            "text": "External service returned an error. Please refer to the external service public specification for details."
        }
    ]
}

• Sample - Finalised status with role selection:

HTTP/1.x 200 OK
X-Request-ID: 39db509c-7e0f-4f47-9d91-38980e9f0cf6
Date: Sun, 06 Aug 2017 15:02:42 GMT
Content-Type: application/json
{
    "scaStatus": "finalised",
    "authorisationCode": "AA532908s",
    "selectedRole": {
        "id": "EE39800929832",
        "name": "Jaan Jaanson"
    },
    "availableRoles": [
        {
            "id": "EE39800929832",
            "name": "Jaan Jaanson"
        },
        {
            "id": "EE223452",
            "name": "Jaana Jaanson"
        },
        {
            "id": "LV289032",
            "name": "AS Läti Õlu"
        }
    ]
}

• Sample - Spent status example:

HTTP/1.x 200 OK
X-Request-ID: 39db509c-7e0f-4f47-9d91-38980e9f0cf6
Date: Sun, 06 Aug 2017 15:02:42 GMT
Content-Type: application/json
{
    "scaStatus": "spent"
}

Change Decoupled Authorisation role

PATCH /v1/oauth/authorisations/:authorisationId

This service is used to change the role the user is requesting access to - if user has access to any other legal entity or person accounts. This section behaves similarly to the selection screen in the OAuth UI. Changing the role can only be done when the authorisation code is not yet used.

• Request

authorisationId - authorisationId returned by Start Decoupled Authorisation service

HTTP headers:

Body:

• Sample:

PATCH https://api.lhv.eu/psd2/v1/oauth/authorisations/99391c7e-ad88-49ec-a2ad-99ddcb1f7722
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
Date: Sun, 06 Aug 2017 15:02:37 GMT
Content-Type: application/json
{
    "selectedRole": {
        "id": "LV289032"
    }
}

• Response

HTTP headers:

Body:

• Sample - selected successfully:

HTTP/1.x 204 No Content
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
Date: Sun, 06 Aug 2017 15:02:42 GMT

• Sample - Incorrect role id provided by TPP:

HTTP/1.x 400 Bad Request
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7722
Content-Type: application/json
{
    "tppMessages": [
        {
            "category": "ERROR",
            "code": "ROLE_UNAVAILABLE",
            "text": "The provided role id is not available for this user."
        }
    ]
}

OAuth Token Service

Use the code retrieved from authentication to generate the actual OAuth 2.0 access token and refresh token.
Service POST /oauth/token returns the tokens:

• access_token - token with short lifetime of 3600 seconds
• refresh_token - token with long lifetime of 180 days. It can be used to generate a fresh access token.

Sample request:

{
    curl --location --request POST 'https://api.sandbox.lhv.eu/psd2/oauth/token' \
     --H 'Content-Type: application/x-www-form-urlencoded' \
     --d 'client_id=PSDEE-LHVTEST-60f0a7' \
     --d 'grant_type=authorization_code' \
     --d 'redirect_uri=https://tppsystem.com/callback' \
     --d 'code=yfdn_4xNsDcyjh9alRSE2stoPjJGpyOP-qt8ni6C-5GhyBb4E59AtMBLIfzcI6qr32RjzZ2-PeE_e1MvtnoymoCkj32OFTktpTJMjkP7MDeSNSOxWdYTbwB-Ae5U4_FV'
}

Note: information is sent in the body of the request

Sample response:

{
      "access_token": "U2YPxu_XofCVxow37CyO8i6pkmW8fyCCaq0PGJdPMbDCIUnyo3wOk4u0ttBSsGCJ0Mp_nshfMntgJnirIn0Z1q7PlXnFZd2ppeqaBY0-uHFMInKJFdaVRdBoq0QmuZUC",
      "token_type": "bearer",
      "refresh_token": "Aw3bcFrT64jKrnf-GOaT5Znre96d4g51p4AIzsdH_ybuZ3JG2SVV7QTZwHQMkLZZQ_k1OfWd3oiM0KTzb-iZyl9bwK5mW-OEd490v4q1oGUinhaIIgbNdJOkVZfAKIR4",
      "expires_in": 3599,
      "scope": "psd2"
}

A key point:

• Token service POST /oauth/token always creates a new pair of access and refresh token when grant_type = authorization_code

OAuth Token Revocation Service

POST /oauth/revoke service allows the user to revoke an existing refresh and/or access token.

Request headers

Request body

Note that:

• If the request provides a token_type_hint parameter, then before revocation, the given token will be validated and assured that it matches the token_type_hint parameter value
• If token_type_hint was not provided to the request, then the given token is matched to all revocable token types
• If a refresh token is provided with the request then, if possible, both refresh token and the corresponding access token will be revoked
• If an access token is provided with the request, then only the given access token will be revoked

Response HTTP status codes

Error response codes

Sample token revocation request:

{
    curl --location --request POST 'https://api.sandbox.lhv.eu/psd2/oauth/revoke' \
     --H 'Content-Type: application/x-www-form-urlencoded' \
     --d 'client_id=PSDEE-LHVTEST-12a3b4' \
     --d 'token=iqfkMHLK5EvrgvukmlWCVf9zIZw' \
     --d 'token_type_hint=refresh_token'
}

Sample successful or nonexistent token revocation response:

HTTP/1.x 200 OK
Date Thu, 21 Apr 2022 08:27:05 GMT

Sample unauthorized response:

HTTP/1.x 401 Unauthorized
Date Thu, 21 Apr 2022 08:27:05 GMT
Content-Type: application/json
{
    "error": "unauthorized_client"
}

Sample request validation error response:

HTTP/1.x 400 Bad Request
Date Thu, 21 Apr 2022 08:27:05 GMT
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "The type of the requested token does not match with the request's token type hint"
}

Sample technical error response:

HTTP/1.x 500 Internal Server Error
Date Thu, 21 Apr 2022 08:27:05 GMT
Content-Type: application/json
{
    "error": "server_error",
    "error_description": "The authorization server encountered an unexpected error which prevented it from fulfilling the request"
}

Account Information - AIS

With account information services TPP will get access to accounts list and information, account balances and lists of transactions (account statements).
Link to Swagger specification.

Some key points for LHV accounts and how they are provided in the API:

• access to more than 90-days account statements is provided by short-term consents. More info under Consents services.
• LHV Accounts are multi-currency - they can hold several currencies at a time on one IBAN. If someone makes a payment to the accounts in different currencies like EUR, GBP or DDK, they will all show up there.

Account Information Consents

Account information consent is required to execute any of the account information services.
Link to Swagger specification.

There are two main types of consents from the perspective of life-cycle:

• long-term consents - provides access to account information for a longer period, typically for 180 days. It is used for cases where customer interaction is longer
  like providing account balances in some 3rd party app. There can be one long-term consent at a time for one user per TPP and older ones are closed automatically.
  It also provides access to list of transactions up to 90 days in the past following the SCA requirements of PSD2. Long-term consent is created with POST /consents service parameter "recurringIndicator": true.
• short-term consents - provides access to account information for 30 minutes only. It is used for cases where customer interaction is short like getting the accounts list before payment initiation or customer data analysis.
  It also provides access to list of transactions more than 90 days in the past following the SCA requirements of PSD2. Short-term consent is created with POST /consents service parameter "recurringIndicator": false.

Notes about consent parameters:

• access.availableAccounts - add parameter value "allAccounts" to select all available accounts by default
• access.balances and access.iban - add list of account IBAN's selected by default
• combinedServiceIndicator - mandatory tag, no actual use currently
• frequencyPerDay - limits how many requests can be done without PSU activity. Counter is used when executing "Read Account Balances" or "Read Account's Transactions List" services without PSU-IP-Address parameter. If limit is used up these services will respond with error ACCESS_EXCEEDED.
• recurringIndicator - long-term (true) or short-term (false) consent.
• validUntil - consent validity end date. Relevant for long-term consents.

Consent Confirmation UI

Consent Confirmation UI is the redirect based UI where user can grant or deny the TPP request to get access to accounts data. User can see and verify exactly what services and accounts shall be included in the consent.

Account and services selection logic:

• if "availableAccounts": "allAccounts" was provided in the consent request then all available accounts and both "balances" and "transaction list" services are selected by default. If it is not added, then these are not selected. User can still change the checkboxes.

• if actual account numbers are provided in the "balances" or "transactions" blocks of the consent request then the matching accounts and services are also selected in the UI. User cannot change these checkboxes and only has an option to decline.

• it is not possible pre-select only one of the services checkboxes without knowing the account numbers beforehand.

• Decoupled

Decoupled authorisation links are always returned and can be used both when Redirect headers are provided or not.
Consent Initiation response contains the _links.startAuthorisationWithAuthenticationMethodSelection.href value - API endpoint to start the Decoupled authorisation process.

  "_links": {
    ...
    "startAuthorisationWithAuthenticationMethodSelection": {
      "href": "https://api.lhv.eu/psd2/v1/consents/11b503d2-e0df-4861-bebf-07d2096f5f77/authorisations"
    }
  }

When executing the POST /consents/{consentId}/authorisations service you should provide the Decoupled authentication method.
Authorisation process on the selected device is started automatically!
If authorisation failed it is possible to execute it again until the validity time is expired.

To use Smart-ID:

• authenticationMethodId - SID
• Customer national ID code is automatically taken from OAuth data

{
    "authenticationMethodId": "SID"
}

To use Mobile-ID:

• authenticationMethodId - MID
• scaAuthenticationData - telephone number

{
    "authenticationMethodId": "MID",
    "scaAuthenticationData": "+372512345678"
}

Response to POST /consents/{consentId}/authorisations contains the information about selected Decoupled method and Authorisation status endpoint

• challengeData.data - challenge code that should be displayed to the PSU. For Smart-ID it is the challenge code choice that user must select in the Smart-ID app.
• challengeData.additionalInformation - short description about what is being signed.
• _links.scaStatus.href - authorisation status uri

{
    "authorisationId": "80426ecc-4d5a-4734-953a-3e59f93aa230",
      "scaStatus": "scaMethodSelected",
      "chosenScaMethod": {
        "authenticationType": "SMS_OTP",
        "authenticationMethodId": "MID"
    },
    "challengeData": {
        "data": "1234",
        "additionalInformation": "Confirm access to accounts"
    },
    "_links": {
        "scaStatus": {
            "href": "https://api.lhv.eu/psd2/v1/consents/11b503d2-e0df-4861-bebf-07d2096f5f77/authorisations/80426ecc-4d5a-4734-953a-3e59f93aa230""
        }
    }
}

To check the authorisation status execute the GET /consents/{consentId}/authorisations/{authorisationId} service. The response contains information about the authorisation process at scaStatus value:

{
    "scaStatus": "finalised"
}

Possible scaStatus values are:

• scaMethodSelected - Method is selected
• started - Authorisation process is started on the device and waiting for user input
• finalised - Authorisation is completed. Consent is then signed automatically, and you can use the Consent Status service (GET /consents/{consentId}/status) to check the execution status.
• failed - Authorisation failed. With failed status also additional information is provided. For example:

{
    "scaStatus": "failed",
    "tppMessages": [
        {
            "category": "ERROR",
            "code": "WRONG_VC",
            "text": "External service returned an error. Please refer to the external service public specification for details."
        }
    ]
}

Accounts List services

Accounts list with consent

POST /v1/accounts is the standard Accounts List service according to Berlin Standard that requires a previous consent.

• Possible to hide closed accounts with parameter onlyActive

Link to Swagger specification.

Accounts list without previous consent

Returns basic accounts list - list of customer payment accounts and nicknames. Very useful service for Payment Service Providers to get the usable payments account list and provide smoother user experience. This service does not require AIS Consent and is available for TPPs with AIS, PIS and PIISP licences and is usable with valid OAuth authorisation.

• Possible to hide closed accounts with parameter onlyActive

Link to Swagger specification.

NB! Service is not part of standard Berlin Standard set of services, but very much expected feature for TPPs and also legal according to PSD2 regulation. Future additions to Berlin Standard might bring changes to this feature.

Payments - PIS

Payments API Covers different options for Payment Initiation Services (PIS).

Link to Swagger specification for initiating payments via JSON.

Link to Swagger specification for initiating payments via XML.

Payment Methods and Schemes

Our payments services support several payment schemes:

• SEPA and SEPA Instant for EUR payments (JSon and XML format)
• SWIFT International payments (XML Format)
• UK Faster Payments (FPS) for UK accounts (XML Format).

Major rules for payment schemes:

• payment to another LHV Pank account is done instantly (Internal payments)
• payment to another account in SEPA Instant RT1 payments system will be executed automatically as a SEPA Instant payment
• if target account is not in the RT1 payments system or SEPA Instant fails for some other reason it is processed as a regular SEPA payment
• international payments are only available through XML files

Payment initiation with JSon format

Payment Initiation service with JSon format is done with service POST payments/sepa-credit-transfers

Sample request:

{
    "instructedAmount": {"currency": "EUR", "amount": "123.50"},
    "debtorAccount": {"iban": "EE717700771001735865"},
    "creditorName": "Donald Duck",
    "creditorAccount": {"iban": "EE857700771001735904"},
    "remittanceInformationUnstructured": "Sample payment 1 to Donald Duck"
}

Sample response:

{
    "transactionStatus": "RCVD",
    "paymentId": "ac8bab09-fdda-4b6d-8776-3a0583df574a",
    "scaMethods": [
        {
            "authenticationType": "SMS_OTP",
            "authenticationMethodId": "MID",
            "name": "Mobile-ID"
        },
        {
            "authenticationType": "PUSH_OTP",
            "authenticationMethodId": "SID",
            "name": "Smart-ID"
        }
    ],
    "_links": {
        "scaRedirect": {
            "href": "https://api.lhv.eu/psd2/ui/v2/payment/sepa/ac8bab09-fdda-4b6d-8776-3a0583df574a"
        },
        "startAuthorisationWithAuthenticationMethodSelection": {
            "href": "/v1.1/payments/sepa-credit-transfers/ac8bab09-fdda-4b6d-8776-3a0583df574a/authorisations"
        },
        "self": {
            "href": "/v1.1/payments/sepa-credit-transfers/ac8bab09-fdda-4b6d-8776-3a0583df574a"
        },
        "status": {
            "href": "/v1.1/payments/sepa-credit-transfers/ac8bab09-fdda-4b6d-8776-3a0583df574a/status"
        }
    }
}

Payment statuses

Typical payment statuses in transactionStatus tag are:

• RVCD - payment parameters are validated and ready for SCA
• PATC - payment is partially accepted. More than one signature is required (XML only).
• ACSP - SCA is completed, payments is waiting for execution but not completed yet. Typically, ACSP is followed by ACSC in minutes, but in some cases it can stay there for longer periods - typically when payment must be sent out as regular SEPA instead of SEPA Instant or there is some manual intervention needed, compliance related actions etc.
• ACWC - there were some minor changes done to the payment automatically - like correction to receiver name etc. Payment processing will continue.
• ACSC - it is a final status. Payment is debited from the payers account and submitted to the payment scheme. For instant payment schemes like SEPA Instant it also means thay payment is credited to the receiver. For batch based schemes like SEPA or SWIFT it means that payment is waiting for clearing.
• RJCT - it is a final status. Payment is rejected due to any of the following reasons - parameters were not valid, payment is not authorized in time or there were processing errors in next steps.
• CANC - it is a final status. Currently, only applies for periodic payment service. Payment is canceled due to user having used DELETE /v1/periodic-payments/sepa-credit-transfers/{paymentId} endpoint.

Multiple signatures

Some payments might need more than one signature in the SCA process. Typically this is the case with corporate payment accounts where one representative can have only 50% signature weight. This can only be done when using XML Payments.
When first user confirms the payment it receives PATC status in stead of ACSP or any other typical statuses.
In PATC status additional signatures can be added with the original Payment confirmation url or decouples authorization services.
When enough users have signed the payment it continues the regular flow automatically.

To simulate the multi-signing feature in Sandbox please add "multisigning" to payment description on remittanceInformationUnstructured field.

Payment Cancellation

Payments can be cancelled by PSP only before customer has completed the SCA process. This can be used to avoid any additional authorizations by the customer after unsuccessful attempts.

Service for cancellation is DELETE /payments/sepa-credit-transfers/{paymentId}/cancel.

Other notes and information

• the reference number (tag "remittanceInformationStructured") is an optional value. If it is provided it should match the Estonian reference number requirements.
• since 2022.07 debtorAccount is an optional field. When it is not submitted the payment account selection is available for the customer in the redirect UI only! This allows skipping the account selection using Accounts List service prior to the Payment Initiation request.

XML payments

Payment Initiation service with XML format is done with service POST /v1/payments/pain.001-credit-transfers

When using XML files for payments instead of JSON there are a couple of notes:

• XML ISO standard pain.001.001.03 (as of november 2023 pain.001.001.09) files used to initiate payments are identical to the ones LHV uses in our CONNECT API. Please see the different samples for Bulk Payments, different payment schemes and other use cases.
• XML files can be used to initiate and authorise multiple payments at the same time.
• XML files allow the choice for payment scheme selection. If not used then the bank will decide the scheme on its own.
• information request will return Payment Status Report pain.002.001.03
• XML payments will remain in PDNG status until signed

Since XML files can include a number of different payments the processing of the file might take some time. In that cases some services will return response 200 with a warning PAYMENT_PROCESSING:

{
    "tppMessages": [
        {
            "category": "WARNING",
            "code": "PAYMENT_PROCESSING",
            "text": "The payment is still being processed - please try again later"
        }
    ]
}

Periodic payment

Periodic payment is done with service POST /v1/periodic-payments/sepa-credit-transfers
It acts similar to ordinary SEPA payment but additional period must be set for how long these payments are made and the frequency of the payments made

Sample request:

{
    "instructedAmount": {"currency": "EUR", "amount": "123.50"},
    "debtorAccount": {"iban": "EE717700771001735865"},
    "creditorName": "Donald Duck",
    "creditorAccount": {"iban": "EE857700771001735904"},
    "remittanceInformationUnstructured": "Sample payment 1 to Donald Duck"
    "startDate": "2099-10-21",
    "endDate": "2199-11-22",
    "frequency": "Monthly"
}

Additionally, periodic payments can be canceled with service DELETE /v1/periodic-payments/sepa-credit-transfers/{paymentId}
This will change the status of the payment to CANC and no further payments for that paymentId will be made.

Payment Authorisation and SCA

By default, every payment must be authorized by the customer with SCA (Strong Customer Authorisation). SCA exemptions are described below.

• authorisation must be completed in 10 minutes after submitting a payment via JSON. For XML payments the authorisation time is increased to 24h.
• user can retry SCA multiple times in the timeframe - for example when Smart-ID or Mobile-ID failed due to technical reasons.
• authorisation methods for JSON and XML payments are identical.

We support following authorisation methods:

• Redirect

To use Redirect method Payment Initiation service POST payments/sepa-credit-transfers expects following HTTP headers:

• TPP-Redirect-Preferred=true or null.
• TPP-Redirect-URI - the TPP uri where to redirect user after successful authorisation. When not provided - only Decoupled authorisation links are returned.
• TPP-Nok-Redirect-URI - the TPP uri where to redirect user after unsuccessful or rejected authorisation. When not provided - TPP-Redirect-URI will be used instead.

In our API for Redirect you do not have to use additional authorisation endpoints. Payment Initiation response contains the _links.scaRedirect.href value - UI uri where to redirect the PSU for Authorisation:

  "_links": {
    ...
    "scaRedirect": {
      "href": "https://api.lhv.eu/psd2/ui/v2/payment/sepa/ff27a963-e486-4d63-8ad1-7d4f12345678"
    }
  }

When user completes the authorisation in the UI the payment is executed automatically, and you can use the Payment Status service (GET /payments/sepa-credit-transfers/{paymentId}/status) to check the execution status.

• Decoupled

Decoupled authorisation links are always returned and can be used both when Redirect headers are provided or not.
Payment Initiation response contains the _links.startAuthorisationWithAuthenticationMethodSelection.href value - API endpoint to start the Decoupled authorisation process.

  "_links": {
    ...
    "startAuthorisationWithAuthenticationMethodSelection": {
      "href": "https://api.lhv.eu/psd2/v1/payments/sepa-credit-transfers/035f028f-fed8-4db2-ba4f-dfbe12345678/authorisations"
    }
  }

When executing the POST /payments/sepa-credit-transfers/{paymentId}/authorisations service you should provide the Decoupled authentication method.
Authorisation process on the selected device is started automatically!
If authorisation failed it is possible to execute it again until the validity time is expired.

To use Smart-ID:

• authenticationMethodId - SID
• Customer national ID code is automatically taken from OAuth data

{
    "authenticationMethodId": "SID"
}

To use Mobile-ID:

• authenticationMethodId - MID
• scaAuthenticationData - telephone number

{
    "authenticationMethodId": "MID",
    "scaAuthenticationData": "+372512345678"
}

Response to POST /payments/sepa-credit-transfers/{paymentId}/authorisations contains the information about selected Decoupled method and Authorisation status endpoint

• challengeData.data - challenge code that should be displayed to the PSU. For Smart-ID it is the challenge code choice that user must select in the Smart-ID app.
• challengeData.additionalInformation - short additional information about the payment including the amount and part of the account nr.
• _links.scaStatus.href - authorisation status uri

{
    "authorisationId": "245074d5-cf8d-4823-8164-a31123456780",
    "scaStatus": "scaMethodSelected",
    "chosenScaMethod": {
        "authenticationType": "SMS_OTP",
        "authenticationMethodId": "MID"
    },
    "challengeData": {
        "data": "1234",
        "additionalInformation": "Payment 123.52 EUR EE...2564"
    },
    "_links": {
        "scaStatus": {
            "href": "https://api.lhv.eu/psd2/v1/payments/sepa-credit-transfers/035f028f-fed8-4db2-ba4f-dfbe12345678/authorisations/245074d5-cf8d-4823-8164-a31123456780"
        }
    }
}

To check the authorisation status execute the GET /payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} service. The response contains information about the authorisation process at scaStatus value:

{
    "scaStatus": "finalised"
}

Possible scaStatus values are:

• scaMethodSelected - Method is selected
• started - Authorisation process is started on the device and waiting for user input
• finalised - Authorisation is completed. Payment is then executed automatically, and you can use the Payment Status service (GET /payments/sepa-credit-transfers/{paymentId}/status) to check the execution status.
• failed - Authorisation failed. With failed status also additional information is provided. For example:

{
    "scaStatus": "failed",
    "tppMessages": [
        {
            "category": "ERROR",
            "code": "WRONG_VC",
            "text": "External service returned an error. Please refer to the external service public specification for details."
        }
    ]
}

SCA Exemptions

There are number of possible SCA Exemptions under the PSD2 regulation. Currently, we have implemented the following:

• Payment between customers own accounts - when payment debit and credit accounts belong to the same customer. With SEPA payment v1.1 you can test ACSC response in sandbox when initiating a payment between existing demo accounts EE717700771001735865 and EE277700771001735881.
• Low-value payments - this is applied to payments not exceeding 30 EUR and a list of additional internal validations. The common logic is shared with our Internet Bank.

When payment matches the SCA Exemption rules it reaches the final status ACSC right after payment initiation request and the response does not contain scaMethods or scaRedirect blocks.

Sample response:

HTTP/1.x 201 Created
x-request-id: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
date: Fri,16 Jul 2021 08:11:39 GMT
location: https://api.lhv.eu/psd2/v1.1/payments/sepa-credit-transfers/b770cfa-6779-4d6b-8e1d-6934a06f6691
content-type: application/hal+json;charset=UTF-8
{
    "transactionStatus": "ACSC",
    "paymentId": "3b770cfa-6779-4d6b-8e1d-6934a06f6691",
    "_links": {
        "self": {
            "href": "https://testapi.lhv.ee/psd2/v1.1/payments/sepa-credit-transfers/3b770cfa-6779-4d6b-8e1d-6934a06f6691"
        },
        "status": {
            "href": "https://testapi.lhv.ee/psd2/v1.1/payments/sepa-credit-transfers/3b770cfa-6779-4d6b-8e1d-6934a06f6691/status"
        }
    }
}

Confirmation of Funds - PIIS

Confirmation of funds services can be used to query if there is enough funds on payment account for payment servicing.
To use this service TPP must first request a consent from PSU.

Link to Swagger specification.

Confirmation of Funds Consents

Link to Swagger specification.

Additional topics and FAQ

Account owner verification

TPPs might need to verify if account owner is actually the expected person or company - for example in situations, where there is a risk that Account Information access is actually given by some other person than claimed. Or to prevent accidental payments from company accounts by end user who has access to different legal entities.

This can be done by using optional HTTP header PSU-Corporate-ID - if this header is provided then executed service is checking if the submitted value is matching the actual payment account holder. If header value does not correspond to expected value service is not executed with error:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "ROLE_INVALID",
      "text": "PSU-Corporate-ID does not match the expected customer registry code or number."
    }
  ]
}

PSU-Corporate-ID value must be [ISO two-letter country code] + [private person national ID or corporation registration ID].

Samples:

• EE10539549 - Estonian company, where EE is the country code and 10539549 is the company ID (LHV Pank)
• EE382******** - Estonian private person, where EE is the country code and 382******** is the national ID.

Account owner verification is supported at following services:

• AIS consent creation - POST /v1/consents
• PIS payment initiation - POST /v1.1/payments/sepa-credit-transfers
• Accounts list (with consent) - GET /v1/accounts
• Accounts list (without consent) - GET /v1/accounts-list

User Interfaces

Shared topics for User Interfaces - OAuth, Consent and Payment confirmations.

Language selection

Default language for all UI pages is English. Users can select their language in the top right corner from English, Estonian and Russian.
This selection is stored in a cookie.

When customers language is known by the TPP beforehand it can also be selected with URL parameter "lang=en/et/ru" (en - English / et - Estonian / ru - Russian).

Example for payment confirmation - Sandbox and Estonian language:

https://api.sandbox.lhv.eu/psd2/ui/v2/payment/sepa/92cf93b3-0bd8-425c-b6fe-849bb16917c5?lang=et

Sandbox and SCA methods

In Sandbox, you can use PIN Calculator option to complete the SCA - any random 4 digit combination like 0000 or 1234. Other methods typically are not usable and only work in live environment.

Browser compatibility

Similar to Internet Bank we have the same principles for Internet Browser compatibility. This applies mainly for the SCA screens using the Redirect Method. Our Open Banking platform is designed to be as available as our other channels. The key principles for supported browsers:

• browser must have at least 5% market share
• two latest major versions
• official unmodified versions only

We do not ensure full compatibility and proper operation when using older versions, alternative builds, embedded versions, 3rd party plugins etc. This also includes usage of IFrames - LHV url must be visible to the user as it is one of the key ways how customer can be sure this is a secure interface and actually provided by the Bank.
Using such Browsers or additions might be technically successful, but we cannot provide proper support in case of any issues.

Open Banking interface statistics

Open Banking and PSD2 dedicated interface uptime and performance statistics. Also includes comparison statistics for our Internet Bank interface.

• Uptime % - calculated as 100% minus downtime
• Downtime % - percentage of downtime for the given day. Calculated as the period where the interface was not able to respond to at least five requests in a row (the response took at least 30s, never arrived or gave HTTP 5xx errors). Also the downtime not possible to extract from logs and discovered by monitoring.
• Downtime s - total downtime in seconds for the given day.
• AIS - average response time in milliseconds of account information services requests (account list, balances and transactions list services).
• PIS - average response time in milliseconds of payments services requests (payment initiation and payment information).
• PIIS - average response time in milliseconds of confirmation of funds services requests.
• Error % - percentage of all requests that were not successful according to the same criterias described in downtime calculation.

Period: 01.01.2024 - 31.03.2024

Period: 01.10.2023 - 31.12.2023

Period: 01.07.2023 - 30.09.2023

Period: 01.04.2023 - 30.06.2023

Period: 01.01.2023 - 31.03.2023