Specification for LHV CONNECT

Introduction

Welcome to LHV Connect API documentation and info page!

LHV Connect is a public API that our customers can use to integrate different banking services directly into their software. Using these services you can execute payments, query account balances or transaction history and perform many other tasks as part of your own software - without need to log into Internet Bank or use any other time consuming channels.
Technically LHV Connect is RESTful web service with requests and responses in XML format, with high availability and fast processing speeds.

Here you will find all the information to get started with our API, including:

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

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

Latest Updates

Access and Basics

To start using LHV Connect services you need:

• Valid customer agreement with LHV
• Sign an additional Connect agreement
• Connection certificates

The general approach and on-boarding steps, before you can start using the API in Live environment:

• contact the LHV Connect support team at connect@lhv.ee or your client relationship manager
• define the services you expect to use and consult our team when needed
• support team prepares your dedicated Sandbox test environment. We expect it to be similar to your future setup in Live - the list of used services, account setup and other details.
• support team sends you connection certificates for the test environment (not shared with live) and additional instructions
• development and testing of your integrations can start!
• when you are confident are ready to proceed to Live inform the support team and relationship manager
• relationship manager prepares and signs the Connect agreement
• support team sends you instruction for connection certificate generation (more details below)
• Live usage can start!

Certificates

Following certificates are needed for using LHV Connect services:

• Connection certificate - identifies and confirms on transport layer that messages were sent by customer's software to the Bank. LHV will generate this custom made certificate for the customer. It is an SSL Base64 PEM certificate that also requires a key. Certificate generation steps in live are following:
  • LHV sends the customer necessary instructions for generating the certificate request file (request.csr) and certificate key. Only customer itself is the owner of the key and responsible for storing it securely.
  • Customer sends the request file to Connect support team at connect@lhv.ee
  • Our support team sends back the actual certificate
• Public root certificate for Connect.lhv.eu (DigiCert High Assurance EV Root CA), that ensures that client is connecting the right service - root CA is available here. Add new Connect API host Root Certificate to your trust store. You can also check different formats here

To verify your certificates and test the basic connection to the API you can use the heartbeat service in both Live and Sandbox.

Optional:

• Signing certificate - some services offered via LHV Connect need a valid digital signature. Currently we support signing certificates based on non-reproducible physical devices and these are: Estonian digi-ID (ID-card), Estonian Mobiil-ID.

Environments

LHV Connect has Live environment and a dedicated test Sandbox environment. Similar to Live also Sandbox has separate connection certificates, payment accounts and all the same services available.

Live

Live base url: https://connect.lhv.eu/

Sandbox

Sandbox test environment is our free to access testing environment. It can be used to test your integrations when on-boarding or also any additional developments. It is technically also very similar to live environment - the services, messages structure etc. is the same.

Please note, the Sandbox environment does not provide mocked responses, meaning that all interactions and responses will be as they would be in a real-live scenario.

Sandbox base url is: https://connect.prelive.lhv.eu/

Clients and connection schemes

There are two different connection schemes, how clients can connect and use Connect services:

Single clients

Client itself is the sole holder of the authentication certificate and connection software. Certificate provides access to one customer or legal entity only.

Service providers and end users using their services

Service provider scheme grants access to multiple customers or legal entities with a single connection certificate. It is meant typically for accounting software providers and other similar business cases.

In this scheme there are two kinds of clients:

• Service provider itself (software owner, technical aggregator) - they are directly connected to Connect
• End user clients, who use CONNECT through service providers - not directly connected to Connect

Only service provider connection software is using Connect services directly. End users are using the service provider software.
For all requests we also need to know the end user - the actual client that uses the service provider.
For this we require two HTTP headers in addition to regular expected input:

• Client-Code (registration code)
• Client-Country (country code (2 characters); issuing country of registration code)

If these are missing from the request, you will get a corresponding error.

Messaging

The core of Connect API is asynchronous messaging which now supports options for parallel processing and different ways to optimize your integration.
Client message container could be seen as an inbox. Client sends a request to the server and then polls the inbox for a response. If there are any messages in the inbox, by default the oldest unread message is returned. The whole cycle of one message consists of three stages: sending the request, retrieving the response and deleting the response.

Typical flow of API requests:

POST [base-url]/payment                 # submit payment request
GET [base-url]/messages/next            # get response message with first payment status
# process message on customer side
DELETE [base-url]/messages/[Message-Response-Id]    # confirm message received

POST [base-url]/account-statement       # submit account statement request
GET [base-url]/messages/next            # get response message with account statement data status
# process message on customer side
DELETE [base-url]/messages/[Message-Response-Id]    # confirm message received

GET [base-url]/messages/next            # get any other pending messages - additional payment status
# process message on customer side
DELETE [base-url]/messages/[Message-Response-Id]    # confirm message received

Sending requests

POST [base-url]/{service-url}

Sample: POST https://connect.lhv.eu/account-statement (the body should contain the actual request)

After successful posting of the request it returns a HTTP header Message-Request-Id, for example:
Message-Request-Id: REQe38a3875c8a94cc0bf48c558a8c9ee82

The Message-Request-Id HTTP header can be used to map any related response messages to the original request. Some request types might receive more than one response message - for example Payment Initiation.

Retrieving the responses

There are different options and services how to consume the messages.

Get next message

GET [base-url]/messages/next

By default, always the oldest unread (not deleted) message is returned. There are now also additional filter HTTP headers so select different messages as expected by the client:

• Filter-Response-Type - add this optional header to select only specific service messages. This can be any value of Message-Response-Type header (ACCOUNT_STATEMENT, CREDIT_DEBIT_NOTIFICATION, PAYMENT etc.).
  With adding this parameter you could implement parallel threads to request payments responses and debit-credit notifications separately. For example if there are pending thousands notification messages in the queue you can still consume the payment response messages immediately.
• Client-Code - for Service Providers only. Company registration code of the Service Provider or its customer. When using the Service Provider own value also related customers messages are returned by default - see also Filter-Service-Provider for more options.
• Client-Country - for Service Providers only. ISO country code (2 characters) - issuing country of registration code.
• Filter-Service-Provider - add this optional header to select service provider messages only when using Service Provider own value for Client-Code. Values: 1/true (filter is on) or 0/false (filter is off). This can be used by service providers to select only their own company messages in the queue. By default when Client-Code is the service provider itself, it returns the messages of all customers.
  Has no effect when Client-Code is not service provider.

Samples

We have a Service Provider with Client-Code=100100 / Client-Country=EE and two Connected Customer contracts
with Client-Code=200200 / Client-Country=UK and Client-Code=300300 / Client-Country=EE
Use following HTTP header combinations to get messages as expected:

* Get all messages of both Connected Customers and Service Provider itself in a single queue:
Client-Code=100100 / Client-Country=UK

* Get only the messages of Service Provider itself:
Client-Code=100100 / Client-Country=EE / Filter-Service-Provider=1

* Get the messages of one Connected Customer only. NB! Filter-Service-Provider header has no effect in this case:
Client-Code=200200 / Client-Country=UK
Client-Code=300300 / Client-Country=EE

The response contains the following important headers:

• Message-Request-Id (optional) - the same id as the initial request. There are cases where request id can be missing, for example the Debit Credit Notification.
  Sample: Message-Request-Id: REQe38a3875c8a94cc0bf48c558a8c9ee82
• Message-Response-Id - unique response id.
  Sample: Message-Response-Id: RES4ab8a01dd7ed4ed792f0605761ae532a
• Message-Response-Type - type of the response depending on the request or purpose. For example:
  • ACCOUNT_BALANCE (response message for Account Balance request)
  • ACCOUNT_STATEMENT (response message for Account Statement request)
  • ACQ_REPORT
  • AGENT_ACCOUNT_SYNC
  • AGENT_REPORT
  • CREDIT_DEBIT_NOTIFICATION
  • DIRECT_DEBIT_OUTGOING
  • DIRECT_DEBIT_INCOMING
  • DIRECT_DEBIT_INCOMING_COLLECTION_NOTIFICATION
  • DIRECT_DEBIT_INCOMING_CANCEL_NOTIFICATION
  • FX_TRADE_OFFER
  • FX_TRADE_OFFER_CONFIRMATION
  • PAYMENT
  • VIBAN_BULK
  • VIBAN_CLOSE
  • VIBAN_INFO
  • VIBAN_MODIFY
  • VIBAN_OPEN
  • VIBAN_STATUS_NOTIFICATION

When executing the request you can receive following HTTP responses:

• 200 - there is a message waiting and there should be some content in the response XML
• 204 - there are no new messages

Get messages list

GET [base-url]/messages  #list of 10 messages by default
GET [base-url]/messages?limit=100  # list of 100 messages

Use this service to get a list of pending messages. You can use this service to request a number of messages at the same time and actually process them in separate threads.

• by default 10 messages are returned.
• optional limit parameter sets the maximum number of messages in the list. Max value is currently 100.
• messages are ordered starting from the oldest.
• the same header values are accepted as for GET /messages/next service - including Filter-Response-Type and Service Provider options.

List of messages is returned in JSON format:

• messageResponseId - matches the Message-Response-Id header in other services
• messageRequestId - matches the Message-Request-Id header in other services
• messageResponseType - matches the Message-Response-Type header in other services
• clientCode - matches the Client-Code header in other services
• clientCountry - matches the Client-Country header in other services
• messageCreatedTime - message creation time

Sample:

{
    "messages": [
        {
            "messageResponseId": "RES6b9716cbd77441e197383bc3adf132ef",
            "messageRequestId": "REQ190aa98872224310aa0c9912ab4a32e9",
            "messageResponseType": "ACCOUNT_STATEMENT",
            "clientCode": "12340001",
            "clientCountry": "EE",
            "messageCreatedTime": "2022-02-28 05:01:33:067"
        },
        {
            "messageResponseId": "RES638d6d2b508b4922a61c728d812919fd",
            "messageRequestId": "REQ9dbca176f3724dc8854b8b87ef43299a",
            "messageResponseType": "FX_TRADE_OFFER",
            "clientCode": "12340001",
            "clientCountry": "EE",
            "messageCreatedTime": "2022-02-28 09:26:12:470"
        },
        {
            "messageResponseId": "RES08a92e7c2f6a4468b36f49bfc2a749a5",
            "messageRequestId": "REQ2f5331bc9846429bbad08310b1b91bb6",
            "messageResponseType": "ACCOUNT_STATEMENT",
            "clientCode": "12340001",
            "clientCountry": "EE",
            "messageCreatedTime": "2022-03-02 05:01:24:263"
        }
    ]
}

To get the message contents use the messages service with expected messageResponseId. You can execute these requests in parallel for several messages.

GET [base-url]/messages/RES6b9716cbd77441e197383bc3adf132ef
..
GET [base-url]/messages/RES638d6d2b508b4922a61c728d812919fd
..
GET [base-url]/messages/RES08a92e7c2f6a4468b36f49bfc2a749a5

Get number of pending messages

GET [base-url]/messages/count

Use this service to get the number of pending messages.

Sample response:

{
    "count": 36
}

Confirm the successful reading of the response

Confirm that reading the response was successful by deleting the message from your inbox. For this, use the response id.

DELETE [base-url]/messages/RES4ab8a01dd7ed4ed792f0605761ae532a

This step is important, because you can’t retrieve the next message until you confirm reading the previous message. After delete was successful, you can retrieve the next message.
NB! Unread messages older than 5 days are automatically scheduled for deletion.

Bulk confirm

Messages can be confirmed (deleted) from the message box also in bulk. This is more useful when used together with List of Messages service.

POST [base-url]/messages/delete

Sample body in JSon format:

{
"messageResponseIds": [
    "RES08dc836da0284e62bdd1abe6c0078e71",
    "RES86f3c883240e45dbbd82ac52efcb6271"
    ]
}

Response body contains the results for all the requests messages.

• status: 200 - delete successful; 400 - already deleted

Response sample:

{
    "messages": [
        {
            "messageResponseId": "RES08dc836da0284e62bdd1abe6c0078e71",
            "status": 200
        },
        {
            "messageResponseId": "RES86f3c883240e45dbbd82ac52efcb6271",
            "status": 200
        }
    ]
}

Response Codes

Error Handling

Service specific errors to Merchant Settlement Report Request and Account Statement Request are returned with following xml file.

List of error codes can be found at the service description.

Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Errors>
    <Error>
        <ErrorCode>errStatement_PeriodInvalid</ErrorCode>
        <Description>From date cannot be later than to date.</Description>
        <Field>FrDt</Field>
    </Error>
    <Error>
        <ErrorCode>NotNull</ErrorCode>
        <Description>Name can't be null</Description>
        <Field>Name</Field>
    </Error>
</Errors>

General error codes

Language and Code Pages

Several of our core services internally are using the Windows-1257 code page supporting mainly Baltic and a list of other European languages. While the ISO20022 standard messages technically use UTF-8.

In practice in most cases it means that we do technically accept the UTF-8 Unicode characters, but replace them with ? symbols if these characters are not supported by Windows-1257. This rule applies to all API services unless stated differently - including the Payment Initiation.

For example unstructured payment description submitted in the payment file:

//Submitted by customer
Payment description - описание платежа.

//Sent to the payment scheme
Payment description - ???????? ???????.

More info about the code page: https://en.wikipedia.org/wiki/Windows-1257

In addition to code page requirements Connect applies the following character conversions. These conversions apply before codepage restrictions take place.

Character replacements for all payments

Additional replacements based on receiver bank BIC country

• ISO - all countries except for EE and GB
• EE - Estonia
• GB - Great Britain

Dates and Time zones

By default all date and time data uses Estonian (EE) time zone - depending on the season GMT+2 or GMT+3.
More details: https://www.timeanddate.com/time/zone/estonia/tallinn

FAQ and Tips

• Does LHV Connect support multithreading?
  Short answer is no, but we are planning improvements here. You can actually submit requests from multiple client threads with your connection certificate, but you can read your responses with GET /messages/next service from one source at a time only. As the service only returns the oldest non-processed message from the queue until you execute the DELETE /messages/.. request.
• How often can I request to read new messages?
  Every customer and its needs are different, but the most frequent mistake we have noticed is constantly polling with some fixed delay for new messages with GET /messages/next service. For example read a message every 10s one by one. Best practice is to loop through the bigger sets of transactions in batches. You can actually poll through the messages as fast as the interface responds and not lose the precious seconds. Once the current batch of transactions or any other messages pending is processed (HTTP response code 204 means there are no more messages) you can take a bit longer break and then try again. As a result you should get your messages as fast as possible (several per second) and at the same time avoid the constant polling on our interface.
  An example in pseudocode:

  While (active_time==true) { // your business hours
      //loop until you get http result 204 = no content (no new messages)
      While (result != 204) {
          // read next message
          result = GET https://connect.lhv.eu/messages/next
          msgid = result.Message-Response-Id // get the HTTP header Message-Response-Id
  
          ProcessMessage(result) // whatever you do with the message
          DELETE https://connect.lhv.eu/messages/[msgid]
      }
      Sleep 10 min // adjust according to your actual needs
  }
  

LHV UK migration and details

From 2023.08.22 (August 22, referred as Migration Date) all business operations and services related to UK Payment Accounts (customer accounts where IBAN starts with GB...) are migrated from LHV Pank to LHV Bank Limited.
This means that from mentioned date LHV services are provided by two different banks and legal entities:

• LHV Pank AS (LHV EE) - Estonian payment accounts and related services
• LHV Bank Limited (LHV UK) - UK payment accounts and related services

These activities trigger also some important changes to Connect API and integrations.

Key elements and changes:

• Connect API host url for LHV UK is https://connect.lhv.com
• All customers using UK accounts and services must migrate to mentioned new host
• Deadline for this migration is 2023.08.22 (August 22)
• From Migration Date current LHV EE host https://connect.lhv.eu stops providing access to UK accounts or any related services
• Connect UK host will also provide access to LHV EE services before and after Migration Date
• Connect UK host uses existing customer authentication certificates
• API structure, services, authentication logic and message formats are not changing or any changes are minimal (expected to be non-breaking)

More details for these are provided below!

Timeline of activities

• 2023.07.11 - UK host https://connect.lhv.com is ready for use and configuration change. Before switching to the new host please contact your Relationship Manager. We want to follow your activities and provide support in case of any issues. We might also provide you additional customer specific details.
• 2023.08.22 - LHV UK Migration Date. Failing to change the host by that date for your API integrations will result in failed requests for any services related to UK accounts!

During the Rollover process on the night of August 22/23 access to UK Account related services will be restricted. It will affect:

• Account Information Services like Balances and Statements
• Payments services
• VIBAN and Agency account services

During the Rollover we are responding with HTTP response code 503 with following:

<Errors><Error><ErrorCode>503</ErrorCode><Description>Access to service temporarily disabled!</Description><Field/></Error></Errors>

EE Account services during the Rollover are not affected. Also any responses to requests submitted before the Rollover started are still available.

Connect UK host and access to LHV EE services

As mentioned LHV UK host provides access to both LHV UK and LHV EE services before and after Migration Date.
For our customers it means that any changes required are only configuration. No additional actual development or code changes are expected.

List of required changes:

• change Connect API host from https://connect.lhv.eu to https://connect.lhv.com in your integration setup
• add new Connect API host Root Certificate to your trust store (DigiCert Global Root G2):
  • https://www.digicert.com/kb/digicert-root-certificates.htm
  • https://cacerts.digicert.com/DigiCertGlobalRootG2.crt.pem

Other than that the service and anything related is exactly the same from both Hosts before Migration Date.

This also applies to Messages services:

• messages queue content is the same on both hosts - for example the list of GET /messages service is identical when executed at the same time via EE or UK host
• any API request to EE host that creates a response message will also appear on UK host and vice a versa

PS! These conditions only apply until Migration date when EE host does not provide further access to UK services!

Changes to API services

As mentioned above any changes to API services are expected to be minimal and non-breaking.
There are still some changes that you should review and evaluate if these could have any impact on your integrations.
It can depend on:

• if your integration is even using the mentioned services or fields
• components, libraries and business logic is your integration using when processing these

Listing the changes:

Additional HTTP headers

• All API services shall include additional HTTP response header X-Bank-Code. You can use this to understand which LHV Bank entity is actually responding for any request. Possible values are:
  • LHVEE - default for all services before Migration date and for EE accounts services from the Migration date
  • LHVUK - for UK accounts services from the Migration date

Localization and time formats

As from Migration date we are actually providing the services from two different entities we also provide the datetime timezone offset information where applicable.

• Today by default all messages are using local EE time zone GMT+2 or GMT+3 for Daylight saving time.
• From Migration date you will start seeing also UK time zone GMT+0 or GMT+1 for Daylight saving time for API requests on UK accounts.

Common format for UK datetime values shall be following:

YYYY-MM-DDTHH:mm:ss.sss+hh:mm
# offset can change from +00:00 to 01:00 depending on Standard or Summer Daylight Saving Time
# second fractions precision is 3 decimals or milliseconds

For example:
2023-08-07T16:26:28.351+01:00

Details and samples of time formats are described below under services.

Heartbeat service

• GET /heartbeat service TimeStamp value will include the current datetime value with timezone offset specific for LHV EE or UK:

-- From UK Host
# Before Migration date by default from LHV EE
<HeartBeatResponse>
    <TimeStamp>2023-07-03T10:36:54.322+03:00</TimeStamp>
</HeartBeatResponse>

# After Migration date by default from LHV UK
<HeartBeatResponse>
    <TimeStamp>2023-07-03T08:40:11.078+01:00</TimeStamp>
</HeartBeatResponse>


-- From EE Host
# Timestamp is already today with offset
<HeartBeatResponse>
    <TimeStamp>2023-08-09T11:27:04.626144+03:00</TimeStamp>
</HeartBeatResponse>

Messages service

• GET /messages service messageCreatedTime value will include the current datetime value with timezone offset specific for LHV EE or UK:

-- from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# All messages include offest information
    ...
        {
            "messageResponseId": "RESd99662d537fa47ff878093b7e6f7bd41",
            "messageRequestId": "REQ85be92ff2b774675b778ffbb13678328",
            "messageResponseType": "ACCOUNT_BALANCE",
            "messageCreatedTime": "2023-09-02T13:48:45.533+03:00",
            "bankCode": "LHVEE"
        }


    ...
        {
            "messageResponseId": "RESd99662d537fa47ff878093b7e6f7bd42",
            "messageRequestId": "REQ85be92ff2b774675b778ffbb13678329",
            "messageResponseType": "ACCOUNT_BALANCE",
            "messageCreatedTime": "2023-09-02T11:48:45.533+01:00"
            "bankCode": "LHVUK"
        }

-- from EE Host
# Format is not changed for the time being and there is no offset information. All datetimes are in EE time zone.

    ...
        {
            "messageResponseId": "RES02a9d219189a423582035fc3748ab175",
            "messageResponseType": "CREDIT_DEBIT_NOTIFICATION",
            "messageCreatedTime": "2023-08-09 11:42:56:873"
        }

Payments Initiation

No general technical changes are made to the formats of Payment Initiation messages. There are some limitations coming up related to Migration activities.

Time formats

-- Responses from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# Both LHV UK and LHV EE messages will include offest information

-- EE Responses
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">
  <CstmrPmtStsRpt>
    <GrpHdr>
      <MsgId>323873273</MsgId>
      <CreDtTm>2023-08-06T17:27:22.937+03:00</CreDtTm>

-- UK Responses
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">
    <CstmrPmtStsRpt>
        <GrpHdr>
            <MsgId>1000000076</MsgId>
            <CreDtTm>2023-08-07T14:30:39.244+01:00</CreDtTm>

-- Responses from EE Host
# Payment response already include offset information

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">
  <CstmrPmtStsRpt>
    <GrpHdr>
      <MsgId>323873273</MsgId>
      <CreDtTm>2023-08-06T17:27:22.937+03:00</CreDtTm>

Submitting both EE and UK account payments in a single file

Currently it is possible to submit payments both from EE and UK accounts in a single PAIN.001 XML file - in differentblocks. From Migration Date it is not technically possible:

• Payment file shall be processed based on the firstblock and payment account.
• If the firstblock contains EE accounts these shall be processed, but any UK account payments shall be rejected.
• If the firstblock contains UK accounts these shall be processed, but any EE account payments shall be rejected.
• Customers should ensure that EE and UK account payments are submitted in separate requests.

Account Statements

Time formats

-- Responses from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# Only LHV UK messages will include offest information

-- LHV EE Responses - format does not change with Migration

<Document ... camt.053.001.02.xsd">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>324075229</MsgId>
      <CreDtTm>2023-08-07T05:01:10.07370879</CreDtTm>
    </GrpHdr>
    <Stmt>
      <Id>324075229GBP</Id>
      <CreDtTm>2023-08-07T05:01:10.07370879</CreDtTm>
      <FrToDt>
        <FrDtTm>2023-08-06T00:00:00</FrDtTm>
        <ToDtTm>2023-08-06T23:59:59</ToDtTm>
      </FrToDt>

-- LHV UK Responses - offset will be included

<?xml version="1.0" ?>
<Document ... camt.053.001.02.xsd">
    <BkToCstmrStmt>
        <GrpHdr>
            <MsgId>1833</MsgId>
            <CreDtTm>2023-08-07T16:26:28.351+01:00</CreDtTm>
        </GrpHdr>
        <Stmt>
            <Id>1833GBP</Id>
            <CreDtTm>2023-08-07T16:26:28.351+01:00</CreDtTm>
            <FrToDt>
                <FrDtTm>2023-08-01T01:00:00.000+01:00</FrDtTm>
                <ToDtTm>2023-08-30T23:59:00.000+01:00</ToDtTm>
            </FrToDt>

-- Responses from EE Host - Response do not include offset information

<Document ... camt.053.001.02.xsd">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>324075229</MsgId>
      <CreDtTm>2023-08-07T05:01:10.07370879</CreDtTm>
    </GrpHdr>
    <Stmt>
      <Id>324075229GBP</Id>
      <CreDtTm>2023-08-07T05:01:10.07370879</CreDtTm>
      <FrToDt>
        <FrDtTm>2023-08-06T00:00:00</FrDtTm>
        <ToDtTm>2023-08-06T23:59:59</ToDtTm>
      </FrToDt>

Debit-Credit Notifications

Time formats

-- Responses from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# Only LHV UK messages will include offest information

-- LHV EE Responses - format does not change with Migration

<Document ... camt.054.001.02.xsd">
  <BkToCstmrDbtCdtNtfctn>
    <GrpHdr>
      <MsgId>324241606</MsgId>
      <CreDtTm>2023-08-07T12:52:33.646843941</CreDtTm>
    </GrpHdr>
    <Ntfctn>
      <Id>324241606GBP</Id>
      <CreDtTm>2023-08-07T12:52:33.646843941</CreDtTm>

-- LHV UK Responses - offset will be included

<?xml version="1.0" ?>
<Document ... camt.054.001.02.xsd">
    <BkToCstmrDbtCdtNtfctn>
        <GrpHdr>
            <MsgId>1bd1017bd63f4f25aef99dbdc2630e3e</MsgId>
            <CreDtTm>2023-08-03T10:58:06.016+01:00</CreDtTm>
        </GrpHdr>
        <Ntfctn>
            <Id>1bd1017bd63f4f25aef99dbdc2630e3eGBP</Id>
            <CreDtTm>2023-08-03T10:58:06.016+01:00</CreDtTm>

-- Responses from EE Host
# Response do not include offset information

<Document ... camt.054.001.02.xsd">
  <BkToCstmrDbtCdtNtfctn>
    <GrpHdr>
      <MsgId>324241606</MsgId>
      <CreDtTm>2023-08-07T12:52:33.646843941</CreDtTm>
    </GrpHdr>
    <Ntfctn>
      <Id>324241606GBP</Id>
      <CreDtTm>2023-08-07T12:52:33.646843941</CreDtTm>

Account balance

Time formats

-- Responses from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# Only LHV UK messages will include offest information

-- LHV EE Responses - format does not change with Migration

<Document ... camt.052.001.06.xsd">
    <BkToCstmrAcctRpt>
        <GrpHdr>
            <MsgId>2949e83626e040e5b84b310f24ea73ca</MsgId>
            <CreDtTm>2023-08-09T13:15:49.239657145</CreDtTm>
        </GrpHdr>
        <Rpt>
            <Id>2949e83626e040e5b84b310f24ea73caZAR</Id>
            <CreDtTm>2023-08-09T13:15:49.239657145</CreDtTm>
            <FrToDt>
                <FrDtTm>2023-08-09T13:15:49.239657145</FrDtTm>
                <ToDtTm>2023-08-09T13:15:49.239657145</ToDtTm>
            </FrToDt>

-- LHV UK Responses - offset will be included

<Document ... camt.052.001.06.xsd">
    <BkToCstmrAcctRpt>
        <GrpHdr>
            <MsgId>7a388863ff404f1c8de308cc95745298</MsgId>
            <CreDtTm>2023-08-09T11:17:43.227+01:00</CreDtTm>
        </GrpHdr>
        <Rpt>
            <Id>GBP7a388863ff404f1c8de308cc95745298</Id>
            <CreDtTm>2023-08-09T11:17:43.227+01:00</CreDtTm>
            <FrToDt>
                <FrDtTm>2023-08-09T11:17:43.227+01:00</FrDtTm>
                <ToDtTm>2023-08-09T11:17:43.227+01:00</ToDtTm>
            </FrToDt>

-- Responses from EE Host
# Response do not include offset information

<Document ... camt.052.001.06.xsd">
    <BkToCstmrAcctRpt>
        <GrpHdr>
            <MsgId>2949e83626e040e5b84b310f24ea73ca</MsgId>
            <CreDtTm>2023-08-09T13:15:49.239657145</CreDtTm>
        </GrpHdr>
        <Rpt>
            <Id>2949e83626e040e5b84b310f24ea73caZAR</Id>
            <CreDtTm>2023-08-09T13:15:49.239657145</CreDtTm>
            <FrToDt>
                <FrDtTm>2023-08-09T13:15:49.239657145</FrDtTm>
                <ToDtTm>2023-08-09T13:15:49.239657145</ToDtTm>
            </FrToDt>

Agency Account Synchronization

Depending on customer's setup Agency Accounts can be synced either to LHV EE, LHV UK or both entities. To support different combinations we have added new optional Bank Codes element to the request.
More info and details at Agency Account Synchronization.

Testing and preparations

In general no specific testing should be needed for any changes described above. Providing some details and tips for approaching these:

• At this point we do not provide a UK specific Sandbox environment
• We suggest validating your readiness for the new UK host before actually switching your Live integrations:
  • use your Live certificates in any of your suitable environments to make sure that any firewall rules or policies do not block connections
  • check any of your services and compare responses from both EE and UK host. For example any specific message with the same Message-Response-Id should give the same output from both hosts.
• If you evaluate that you need further testing or consultations for any of these please contact our support

Live Proving

Before going live with your API integrations we should first verify if everything is done according to our specification and good practices - to ensure that customers will get the best experience from the API.
This checklist is also useful when making any changes to your connection or any other activities that could have some impact.
If there are relevant issues with any of the topics mentioned below and it causes problems to our API we might be forced to not allow you to go Live or suspend your existing connection.

Polling and request frequency - You should execute API requests with reasonable frequency - as often as needed for your solution, but not overflow the API with requests that have no actual value. Typical issues:

• constant polling of messages with GET /messages/next service
• trying to use several threads at once and getting the same first message multiple times

Syntax and integrity - Please make sure that all requests contain relevant parameters in proper formats. Typical issues:

• encoding issues
• using incorrect or not existing account numbers in your requests
• leading and trailing spaces or incorrect symbols in different parameters like names, addresses etc.

Account statements and periods - You should execute Account Statements for relevant time periods and frequency. You shouldn't request Account Statements for longer periods too often or when you have already requested the data that does not change anymore. Typical issues:

• asking for full day or even several days statements when actually needing the latest transactions from last 10 minutes or other small period

Error processing - You should have adequate error processing in place. Make sure that your system is able to read the possible error codes and explanations and react on these. Typical issues:

• not reading your HTTP response codes
• not reading the payments service RJCT statuses and explanations

Testing activities in Live

To preserve the integrity of data in the production environment, all testing activities (aka penny testing) need to be done with actual and KYC'd individuals.
This applies most importantly to Payments and VIBAN services. Meaning no dummy data should be used when execution payments, opening VIBAN accounts and relevant KYC documentation has to be on file as per your internal procedures.

Upcoming transition to new ISO messaging standard in November 2025

New ISO20022 messaging standard will be adopted by payment service providers and payment schemes. This means that also payment initiation messages will be upgraded as follows:

• pain.001.001.03 -> pain.001.001.09
• pain.008.001.02 -> pain.008.001.08
• pain.002.001.03 -> pain.002.001.10

LHV will provide transition period between 03.07.2023 and 31.10.2025 so everyone can start migrating to new messages while both new and old messages are supported in parallel. New messages allow to send additional payment details and have breaking changes in XSD structure.

Summary of changes

pain.001.001.09 and pain.008.001.08

1. Added detailed sructured address fields. Unstructured address cannot be used after 31.10.2025.
2. Payment execution time now supports date and date+time. LHV only the date part is used.
3. BicOrBei elements are replaced with AnyBIC.
4. BIC field elements are replaced with BICFI.
5. LEI code is now supported for identifying entities.
6. UETR (Unique End-to-end Transaction Reference) field has been added (pain.001 only). Usage is recommended.
7. Additional data can be provided with payment (see LHV supplementary data schema and description).
8. XSD technical structure changes which will not have an impact on the forwarded data.

pain.002.001.10

1. OrgnlUETR is added.
2. XSD technical structure changes which will not have an impact on the forwarded data.

Timeline for upgrade

Contact and Support

Please use following contacts for different requests you might have:

• connect@lhv.ee - Connect API team: questions about technical details, issues with integration
• fpsoprations@lhv.ee - Payment Operations team: specific payment related matters, payment confirmations, tracing of payments
• fi-support@lhv.co.uk - Relationship Managers team: general onboarding and relationship questions, contractual and legal matters, general billing

When submitting support requests for technical help or incident resolving, please follow these guidelines:

• Specify the involved services
• Specify the timeframe - when exactly did the issue occur, problematic payment was initiated etc.
• Provide request and response ID's that help us trace the issue. Best option is the Message-Request-Id and Message-Response-Id header values mentioned here.
• Provide exact error messages you received or additional logs you have related to the issue.

Providing this valuable information and details helps us resolve your questions faster and better!

CONNECT Services

Following services are available in the Connect API.

Communication Test

Heartbeat service

GET [base-url]/heartbeat

Service for testing if system is up and connection certificate is configured correctly. Returns current system time.
For testing purposes we also recommend first using Curl, Postman or some other API testing tool. Sample Curl statements below - replace yourcert.crt and yourkey.key with your PEM certificate and key files:

// Sandbox:
curl -X GET "https://connect.prelive.lhv.eu/heartbeat" --cert yourcert.crt --key yourkey.key --cacert LHV_test_rootca2011.cer

// Live:
curl -X GET "https://connect.lhv.eu/heartbeat" --cert yourcert.crt --key yourkey.key --cacert DigiCertHighAssuranceEVRootCA.crt.pem

// Sandbox - for service providers:
curl -X GET "https://connect.prelive.lhv.eu/heartbeat" --cert yourcert.crt --key yourkey.key --cacert LHV_test_rootca2011.cer -H "Client-Code: 012345678" -H "Client-Country: GB"

// Live - for service providers:
curl -X GET "https://connect.lhv.eu/heartbeat" --cert yourcert.crt --key yourkey.key --cacert DigiCertHighAssuranceEVRootCA.crt.pem -H "Client-Code: 012345678" -H "Client-Country: GB"

Sample response

<HeartBeatResponse>
    <TimeStamp>2022-12-30T09:58:40.6002618+02:00</TimeStamp>
</HeartBeatResponse>

GET [base-url]/heartbeat/mq

Similar service to regular GET /heartbeat, but will create a response message in the queue that you can read with GET/messagest/next. Response also contains additional information about the user. You can use this service to simulate and play through the general messaging logic without more complex Account Information or Payments requests.

Sample response

<HeartBeatResponse>
  <TimeStamp>2022-12-30T09:58:40.6002618+02:00</TimeStamp>
  <AuthorizedUser>
    <Name>Connect Demo Customer 1</Name>
    <Code>12340001</Code>
  </AuthorizedUser>
  <Certificates>
        <Certificate>
            <SerialNumber>10539549</SerialNumber>
            <ValidFrom>2021-09-09T10:22:26</ValidFrom>
            <ValidTo>2024-06-05T10:22:26</ValidTo>
        </Certificate>
  <Certificates>
  <Signatures />
  <UserRequest>&lt;root&gt;Content&lt;/root&gt;</UserRequest>
</HeartBeatResponse>

POST [base-url]/heartbeat

Service for testing your BDOC request.

Request should contain signed BDOC containing request.xml file. Service takes authenticated user info, extracts BDOC signature data and request.xml content and composes response xml like below.

Service response can be retrieved via messaging service (GET https://connect.lhv.eu/messages/next).

Sample

<HeartBeatResponse>
    <TimeStamp>2022-12-30T09:58:40.6002618+02:00</TimeStamp>
    <AuthorizedUser>
        <Name>LHV Pank AS</Name>
        <Code>10539549</Code>
    </AuthorizedUser>
    <Signatures>
        <Signature>
            <Name>LHV Pank AS</Name>
            <Code>10539549</Code>
        </Signature>
    </Signatures>
    <UserRequest>Test</UserRequest>
</HeartBeatResponse>

Account Reports

Request Account Report

Account Statement POST [base-url]/account-statement
Account Statement provides a list of incoming and outgoing transactions and payments with additional details. It can be requested for one Customer Account for the specified period.

Account Balance POST [base-url]/account-balance
Account Balance provides actual and free balance information for any existing currencies on Customer account. It can be requested for one Customer Account at a time. Balances are provided real-time on the moment of generating the response.
With optional Prtry parameter now also Payment limits info can be requested - both total and free limits for Daily and Monthly periods.

XML format (camt.060.001.03)

Both Account Statement and Account Balance request share the same ISO 20022 Account Report Request camt.060.001.03 XML format. Example of camt.060.001.03
Depending on the service different values in the Request can be used to get data for different periods or details.
Some of these affect only Statements or Balances responses.

Message root

Group header

Samples

Account Statement

Sample is requesting the account statement for account EE337700771001260958.

• The period is 14th of November 2019 and exact time slot between 16:00 and 17:00 in EE time zone (GMT+2/3 for current date).
• Use Prtry=DATETIME to query exact time slots or Prtry=DATE for the whole day.

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.060.001.03">
	<AcctRptgReq>
		<GrpHdr>
			<MsgId>MSGIDLHVTEST01</MsgId>
			<CreDtTm>2019-11-14T16:15:07.617</CreDtTm>
		</GrpHdr>
		<RptgReq>
			<ReqdMsgNmId>camt.053.001.02</ReqdMsgNmId>
			<Acct>
				<Id>
					<IBAN>EE337700771001260958</IBAN>
				</Id>
			</Acct>
			<AcctOwnr>
				<Pty />
			</AcctOwnr>
			<RptgPrd>
				<FrToDt>
					<FrDt>2019-11-14</FrDt>
					<ToDt>2019-11-14</ToDt>
				</FrToDt>
				<FrToTm>
					<FrTm>16:00:00+02:00</FrTm>
					<ToTm>17:00:00+02:00</ToTm>
				</FrToTm>
				<Tp>ALLL</Tp>
			</RptgPrd>
			<ReqdBalTp>
				<CdOrPrtry>
					<Prtry>DATETIME</Prtry>
				</CdOrPrtry>
			</ReqdBalTp>
		</RptgReq>
	</AcctRptgReq>
</Document>

Account Balance

Sample is requesting the Account Balance for account EE477700771001388940.

• Use Prtry=PAYMENT_LIMITS to also include Payment Limits information
• Date parameters currently do not have any effect on the response - balances are taken real-time.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.060.001.03">
    <AcctRptgReq>
        <GrpHdr>
            <MsgId>MSGIDLHVTEST01</MsgId>
            <CreDtTm>2022-05-02T16:15:07.617</CreDtTm>
        </GrpHdr>
        <RptgReq>
            <ReqdMsgNmId>camt.053.001.02</ReqdMsgNmId>
            <Acct>
                <Id>
                    <IBAN>EE477700771001388940</IBAN>
                </Id>
            </Acct>
            <AcctOwnr>
                <Pty/>
            </AcctOwnr>
            <RptgPrd>
                <FrToDt>
                    <FrDt>2022-05-02</FrDt>
                    <ToDt>2022-05-02</ToDt>
                </FrToDt>
                <FrToTm>
                    <FrTm>16:00:00+03:00</FrTm>
        			<ToTm>17:00:00+03:00</ToTm>
                </FrToTm>
                <Tp>ALLL</Tp>
            </RptgPrd>
			<ReqdBalTp>
				<CdOrPrtry>
					<Prtry>PAYMENT_LIMITS</Prtry>
				</CdOrPrtry>
			</ReqdBalTp>
        </RptgReq>
    </AcctRptgReq>
</Document>

Error codes

Response Account Statement

XML format (ISO 20022 Account Statement Message camt.053.001.02)

The ISO 20022 Account Statement Message camt.053.001.02 standard is used to report account booked transactions and balances of a selected time period. The message includes information about the opening balance, the closing balance, and the available balance together with all booked transactions of a reporting period. The ISO 20022 format allows to include information that is not supported by LHV. That information is not provided by LHV.

Header Message-Response-Type: ACCOUNT_STATEMENT

Message structure

Group Header – mandatory, occurs once.
Statement – mandatory and repetitive per currency.
Balance – mandatory and repetitive. Contains elements such as Opening Booked Balance and Closing Booked Balance.
Entry – included in the Statement block. Contains information related to an entry on the account.
Entry Details – included in the Entry block. Contains detailed information related to the entry.

Message root

Group header

Statement

Sample

<?xml version="1.0" ?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02 camt.053.001.02.xsd">
    <BkToCstmrStmt>
        <GrpHdr>
            <MsgId>10001115</MsgId>
            <CreDtTm>2016-03-15T13:04:55.123</CreDtTm>
        </GrpHdr>
        <Stmt>
            <Id>10001115EUR</Id>
            <CreDtTm>2016-03-15T13:04:55</CreDtTm>
            <FrToDt>
                <FrDtTm>2016-03-10T00:00:00</FrDtTm>
                <ToDtTm>2016-03-15T13:04:55</ToDtTm>
            </FrToDt>
            <Acct>
                <Id>
                    <IBAN>EE457700771000676899</IBAN>
                </Id>
                <Ccy>EUR</Ccy>
                <Svcr>
                    <FinInstnId>
                        <BIC>LHVBEE20XXX</BIC>
                        <Nm>AS LHV Pank</Nm>
                        <PstlAdr>
                            <AdrTp>BIZZ</AdrTp>
                            <StrtNm>Tartu mnt.</StrtNm>
                            <BldgNb>2</BldgNb>
                            <PstCd>10145</PstCd>
                            <TwnNm>Tallinn</TwnNm>
                            <CtrySubDvsn>Harjumaa</CtrySubDvsn>
                            <Ctry>EE</Ctry>
                        </PstlAdr>
                    </FinInstnId>
                </Svcr>
            </Acct>
            <Bal>
                <Tp>
                    <CdOrPrtry>
                        <Cd>OPBD</Cd>
                    </CdOrPrtry>
                </Tp>
                <Amt Ccy="EUR">4497512.65</Amt>
                <CdtDbtInd>CRDT</CdtDbtInd>
                <Dt>
                    <Dt>2016-03-10</Dt>
                </Dt>
            </Bal>
            <Bal>
                <Tp>
                    <CdOrPrtry>
                        <Cd>CLBD</Cd>
                    </CdOrPrtry>
                </Tp>
                <Amt Ccy="EUR">4497505.65</Amt>
                <CdtDbtInd>CRDT</CdtDbtInd>
                <Dt>
                    <Dt>2016-03-15</Dt>
                </Dt>
            </Bal>
            <TxsSummry>
                <TtlCdtNtries>
                    <NbOfNtries>0</NbOfNtries>
                    <Sum>0.00</Sum>
                </TtlCdtNtries>
                <TtlDbtNtries>
                    <NbOfNtries>2</NbOfNtries>
                    <Sum>2.00</Sum>
                </TtlDbtNtries>
            </TxsSummry>
            <Ntry>
                <Amt Ccy="EUR">1.00</Amt>
                <CdtDbtInd>DBIT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2016-03-10</Dt>
                </BookgDt>
				<ValDt>
					<DtTm>2016-03-10T10:11:53.000</DtTm>
				</ValDt>
                <AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB777</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>CCRD</Cd>
                            <SubFmlyCd>FEES</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>INTERNAL</Cd>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <Refs>
                            <AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB777</AcctSvcrRef>
                        </Refs>
                        <AmtDtls>
                            <InstdAmt>
                                <Amt Ccy="EUR">1.00</Amt>
                            </InstdAmt>
                            <TxAmt>
                                <Amt Ccy="EUR">1.00</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <RltdPties>
                            <Dbtr></Dbtr>
                            <Cdtr></Cdtr>
                        </RltdPties>
                        <RltdAgts></RltdAgts>
                        <RmtInf>
                            <Ustrd>Card (..6748) monthly fee</Ustrd>
                        </RmtInf>
                    </TxDtls>
                </NtryDtls>
            </Ntry>
            <Ntry>
                <Amt Ccy="EUR">1.00</Amt>
                <CdtDbtInd>DBIT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2016-03-11</Dt>
                </BookgDt>
				<ValDt>
					<DtTm>2016-03-11T10:11:53.000</DtTm>
				</ValDt>
                <AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB779</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>ICDT</Cd>
                            <SubFmlyCd>OTHR</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>INTERNAL</Cd>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <Refs>
                            <AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB779</AcctSvcrRef>
                            <InstrId>94</InstrId>
                        </Refs>
                        <AmtDtls>
                            <InstdAmt>
                                <Amt Ccy="EUR">1.00</Amt>
                            </InstdAmt>
                            <TxAmt>
                                <Amt Ccy="EUR">1.00</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <RltdPties>
                            <Dbtr>
                                <Nm>Silver Kullassepp</Nm>
                                <PstlAdr>
                                    <Ctry>EE</Ctry>
                                </PstlAdr>
                                <Id>
                                    <PrvtId>
                                        <Othr>
                                            <Id>48107090295</Id>
                                            <SchmeNm>
                                                <Cd>NIDN</Cd>
                                            </SchmeNm>
                                        </Othr>
                                    </PrvtId>
                                </Id>
                            </Dbtr>
                            <DbtrAcct>
                                <Id>
                                    <IBAN>EE457700771000676899</IBAN>
                                </Id>
                            </DbtrAcct>
                            <Cdtr>
                                <Nm>Test Client</Nm>
                            </Cdtr>
                            <CdtrAcct>
                                <Id>
                                    <IBAN>EE867700771000681884</IBAN>
                                </Id>
                            </CdtrAcct>
                        </RltdPties>
                        <RltdAgts>
                            <DbtrAgt>
                                <FinInstnId>
                                    <BIC>LHVBEE20XXX</BIC>
                                    <Nm>AS LHV Pank</Nm>
                                </FinInstnId>
                            </DbtrAgt>
                            <CdtrAgt>
                                <FinInstnId>
                                    <BIC>LHVBEE20XXX</BIC>
                                    <Nm>AS LHV Pank</Nm>
                                </FinInstnId>
                            </CdtrAgt>
                        </RltdAgts>
                        <RmtInf>
                            <Ustrd>EUR payment</Ustrd>
                        </RmtInf>
                    </TxDtls>
                </NtryDtls>
            </Ntry>
        </Stmt>
        <Stmt>
            <Id>10001115USD</Id>
            <CreDtTm>2016-03-15T13:04:55</CreDtTm>
            <FrToDt>
                <FrDtTm>2016-03-10T00:00:00</FrDtTm>
                <ToDtTm>2016-03-15T13:04:55</ToDtTm>
            </FrToDt>
            <Acct>
                <Id>
                    <IBAN>EE457700771000676899</IBAN>
                </Id>
                <Ccy>USD</Ccy>
                <Svcr>
                    <FinInstnId>
                        <BIC>LHVBEE20XXX</BIC>
                        <Nm>AS LHV Pank</Nm>
                        <PstlAdr>
                            <AdrTp>BIZZ</AdrTp>
                            <StrtNm>Tartu mnt.</StrtNm>
                            <BldgNb>2</BldgNb>
                            <PstCd>10145</PstCd>
                            <TwnNm>Tallinn</TwnNm>
                            <CtrySubDvsn>Harjumaa</CtrySubDvsn>
                            <Ctry>EE</Ctry>
                        </PstlAdr>
                    </FinInstnId>
                </Svcr>
            </Acct>
            <Bal>
                <Tp>
                    <CdOrPrtry>
                        <Cd>OPBD</Cd>
                    </CdOrPrtry>
                </Tp>
                <Amt Ccy="USD">1216.13</Amt>
                <CdtDbtInd>CRDT</CdtDbtInd>
                <Dt>
                    <Dt>2016-03-10</Dt>
                </Dt>
            </Bal>
            <Bal>
                <Tp>
                    <CdOrPrtry>
                        <Cd>CLBD</Cd>
                    </CdOrPrtry>
                </Tp>
                <Amt Ccy="USD">1215.13</Amt>
                <CdtDbtInd>CRDT</CdtDbtInd>
                <Dt>
                    <Dt>2016-03-15</Dt>
                </Dt>
            </Bal>
            <TxsSummry>
                <TtlCdtNtries>
                    <NbOfNtries>0</NbOfNtries>
                    <Sum>0.00</Sum>
                </TtlCdtNtries>
                <TtlDbtNtries>
                    <NbOfNtries>1</NbOfNtries>
                    <Sum>1.00</Sum>
                </TtlDbtNtries>
            </TxsSummry>
            <Ntry>
                <Amt Ccy="USD">1.00</Amt>
                <CdtDbtInd>DBIT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2016-03-15</Dt>
                </BookgDt>
				<ValDt>
					<DtTm>2016-03-15T10:11:53.000</DtTm>
				</ValDt>
                <AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB781</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>ICDT</Cd>
                            <SubFmlyCd>OTHR</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>SWIFT</Cd>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <Refs>
                            <AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB781</AcctSvcrRef>
                            <InstrId>17793</InstrId>
                        </Refs>
                        <AmtDtls>
                            <InstdAmt>
                                <Amt Ccy="USD">1.00</Amt>
                            </InstdAmt>
                            <TxAmt>
                                <Amt Ccy="USD">1.00</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <RltdPties>
                            <Dbtr>
                                <Nm>Silver Kullassepp</Nm>
                                <PstlAdr>
                                    <Ctry>EE</Ctry>
                                    <AdrLine>Tartu mnt, Tallinn, 11111</AdrLine>
                                </PstlAdr>
                            </Dbtr>
                            <DbtrAcct>
                                <Id>
                                    <IBAN>EE457700771000676899</IBAN>
                                </Id>
                            </DbtrAcct>
                            <Cdtr>
                                <Nm>John Smith</Nm>
                            </Cdtr>
                            <CdtrAcct>
                                <Id>
                                    <Othr>
                                        <Id>440532013000</Id>
                                    </Othr>
                                </Id>
                            </CdtrAcct>
                        </RltdPties>
                        <RltdAgts>
                            <DbtrAgt>
                                <FinInstnId>
                                    <BIC>LHVBEE20XXX</BIC>
                                    <Nm>AS LHV Pank</Nm>
                                </FinInstnId>
                            </DbtrAgt>
                            <CdtrAgt>
                                <FinInstnId>
                                    <BIC>DEUTDEBBXXY</BIC>
                                </FinInstnId>
                            </CdtrAgt>
                        </RltdAgts>
                        <RmtInf>
                            <Ustrd>USD payment</Ustrd>
                        </RmtInf>
                    </TxDtls>
                </NtryDtls>
            </Ntry>
        </Stmt>
    </BkToCstmrStmt>
</Document>

For long account statements containing larger number of transactions pagination can be used - one Account Statement response receives more than one response in the queue.
Currently the pagination limit per message is 10 000 transactions. Total amount of transactions in any response is 100 000 - in 10 separate response messages.

First response message header part:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02 camt.053.001.02.xsd">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>12397887</MsgId>
      <CreDtTm>2020-03-30T21:00:03</CreDtTm>
      <MsgPgntn>
        <PgNb>1</PgNb>
        <LastPgInd>false</LastPgInd>
      </MsgPgntn>
    </GrpHdr>
    ...

Second and final response message header part:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02 camt.053.001.02.xsd">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>12397888</MsgId>
      <CreDtTm>2020-03-30T21:00:03</CreDtTm>
      <MsgPgntn>
        <PgNb>2</PgNb>
        <LastPgInd>true</LastPgInd>
      </MsgPgntn>
    </GrpHdr>
    ...

Response Account Balance

XML format (ISO 20022 Account Report Message camt.052.001.06)

The ISO 20022 Account Report Message camt.052.001.06 is used to report current account balance and optionally payment limits. The report returns two balances: current booked balance (without reservations) and current available balance (with reservations). If client has no balance in any currency, then 0 EUR balance is returned.

Payment limits are provided only for company based API limits. Personalized limits for company representatives are not provided here and available in the Internet Bank.

Header Message-Response-Type: ACCOUNT_BALANCE

Message structure

Group Header - mandatory, occurs once.
Report - mandatory and repetitive per currency. Includes zero to many Balance blocks.

Message root

Group header

Report

Sample

Sample account EE477700771001388940 has balances in EUR and GBP. Payment limits are in EUR.

<Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iso:std:iso:20022:tech:xsd:camt.052.001.06" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:camt.052.001.06 camt.052.001.06.xsd">
  <BkToCstmrAcctRpt>
    <GrpHdr>
      <MsgId>e6bddc758ae4449d9f0f147708eb8e25</MsgId>
      <CreDtTm>2022-05-02T16:02:17.543126</CreDtTm>
    </GrpHdr>
	<Rpt>
      <Id>e6bddc758ae4449d9f0f147708eb8e25EUR</Id>
      <CreDtTm>2022-05-02T16:02:17.543126</CreDtTm>
      <FrToDt>
        <FrDtTm>2022-05-02T16:02:17.543126</FrDtTm>
        <ToDtTm>2022-05-02T16:02:17.543126</ToDtTm>
      </FrToDt>
      <Acct>
        <Id>
          <IBAN>EE477700771001388940</IBAN>
        </Id>
        <Ccy>EUR</Ccy>
      </Acct>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>ITBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">110003428.63</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>ITAV</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">109998795.38</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Prtry>PAYMENT_LIMIT_MONTHLY_TOTAL</Prtry>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">100000.00</Amt>
        <CdtDbtInd>DBIT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Prtry>PAYMENT_LIMIT_MONTHLY_FREE</Prtry>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">99995.00</Amt>
        <CdtDbtInd>DBIT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Prtry>PAYMENT_LIMIT_DAILY_TOTAL</Prtry>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">10000.00</Amt>
        <CdtDbtInd>DBIT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Prtry>PAYMENT_LIMIT_DAILY_FREE</Prtry>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">9995.00</Amt>
        <CdtDbtInd>DBIT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
    </Rpt>
	<Rpt>
      <Id>e6bddc758ae4449d9f0f147708eb8e25GBP</Id>
      <CreDtTm>2022-05-02T16:02:17.543126</CreDtTm>
      <FrToDt>
        <FrDtTm>2022-05-02T16:02:17.543126</FrDtTm>
        <ToDtTm>2022-05-02T16:02:17.543126</ToDtTm>
      </FrToDt>
      <Acct>
        <Id>
          <IBAN>EE477700771001388940</IBAN>
        </Id>
        <Ccy>GBP</Ccy>
      </Acct>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>ITBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="GBP">110000037.12</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>ITAV</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="GBP">110000037.12</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <Dt>2022-05-02</Dt>
        </Dt>
      </Bal>
    </Rpt>
  </BkToCstmrAcctRpt>
</Document>

Debit Credit Notification

XML format (ISO 20022 Bank To Customer Debit Credit Notification camt.054.001.02)

The ISO 20022 Bank To Customer Debit Credit Notification camt.054.001.02 standard is used to report customer of payments on the account. Both credit and debit transactions are included.
The message does not include balance information.

Header Message-Response-Type: CREDIT_DEBIT_NOTIFICATION

Debit Credit Notification message does not include the Message-Request-Id HTTP header!

camt.054.001.02.xsd

Message structure

Group Header – mandatory, occurs once.
Notificaton – mandatory and repetitive per account number and currency. One notification block can include many entries.
Entry – optional and repetitive. Contains information about single entry.

Message root

Group header

Sample

This sample matches the sample payment under Payment Initiation - from customer "LHV Connect Demo 1" to customer "LHV Connect Demo 2".
It is the outgoing payment from "LHV Connect Demo 1" account EE337700771001260958.

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.054.001.02">
	<BkToCstmrDbtCdtNtfctn>
		<GrpHdr>
			<MsgId>10942444</MsgId>
			<CreDtTm>2019-11-14T16:01:40.074</CreDtTm>
		</GrpHdr>
		<Ntfctn>
			<Id>10942444EUR</Id>
			<CreDtTm>2019-11-14T16:01:40.074</CreDtTm>
			<Acct>
				<Id>
					<IBAN>EE337700771001260958</IBAN>
				</Id>
				<Ccy>EUR</Ccy>
				<Ownr>
					<Nm>LHV Connect Demo 1</Nm>
					<Id>
						<OrgId>
							<Othr>
								<Id>96811884</Id>
							</Othr>
						</OrgId>
					</Id>
				</Ownr>
				<Svcr>
					<FinInstnId>
						<BIC>LHVBEE22</BIC>
						<Nm>AS LHV Pank</Nm>
					</FinInstnId>
				</Svcr>
			</Acct>
			<Ntry>
				<Amt Ccy="EUR">2.50</Amt>
				<CdtDbtInd>DBIT</CdtDbtInd>
				<Sts>BOOK</Sts>
				<BookgDt>
					<Dt>2019-11-14</Dt>
				</BookgDt>
				<ValDt>
					<DtTm>2019-11-14T10:11:53.000+02:00</DtTm>
				</ValDt>
				<AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB781</AcctSvcrRef>
				<BkTxCd>
					<Domn>
						<Cd>PMNT</Cd>
						<Fmly>
							<Cd>ICDT</Cd>
							<SubFmlyCd>OTHR</SubFmlyCd>
						</Fmly>
					</Domn>
                    <Prtry>
                        <Cd>INTERNAL</Cd>
                    </Prtry>
				</BkTxCd>
				<NtryDtls>
					<TxDtls>
						<Refs>
							<AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB781</AcctSvcrRef>
							<InstrId>INSTRIDLHVTEST01A</InstrId>
							<EndToEndId>ENDTOENDIDLHVTEST01A</EndToEndId>
						</Refs>
						<AmtDtls>
							<InstdAmt>
								<Amt Ccy="EUR">2.50</Amt>
							</InstdAmt>
							<TxAmt>
								<Amt Ccy="EUR">2.50</Amt>
							</TxAmt>
						</AmtDtls>
						<RltdPties>
							<Cdtr>
								<Nm>LHV Connect Demo 2</Nm>
							</Cdtr>
							<CdtrAcct>
								<Id>
									<IBAN>EE267700771001260987</IBAN>
								</Id>
							</CdtrAcct>
						</RltdPties>
						<RltdAgts>
							<DbtrAgt>
								<FinInstnId>
									<BIC>LHVBEE20</BIC>
									<Nm>AS LHV Pank</Nm>
								</FinInstnId>
							</DbtrAgt>
							<CdtrAgt>
								<FinInstnId>
									<BIC>LHVBEE20</BIC>
									<Nm>AS LHV Pank</Nm>
								</FinInstnId>
							</CdtrAgt>
						</RltdAgts>
						<RmtInf>
							<Ustrd>Payment Description LHVTEST01A</Ustrd>
							<Strd>
								<CdtrRefInf>
									<Tp>
										<CdOrPrtry>
											<Cd>SCOR</Cd>
										</CdOrPrtry>
									</Tp>
									<Ref>700170939</Ref>
								</CdtrRefInf>
							</Strd>
						</RmtInf>
					</TxDtls>
				</NtryDtls>
			</Ntry>
		</Ntfctn>
	</BkToCstmrDbtCdtNtfctn>
</Document>

Payment Initiation

Service for executing payments.

Glossary

SEPA - Single Euro Payments Area (SEPA). List of countries belonging to the area.

EEA - European Economic Area country

SEPA Credit Transfer - also referred to as SEPA payment, European payment. Payment in EUR to a bank within the SEPA area that is a member of STEP2 SCT or T2 payment clearing and settlement system. List of STEP2 SCT participants and list of T2 participants. In LHV Pank (EE) product name is European payment

SEPA Instant Credit Transfer - also referred to as instant payment. A payment in EUR to a bank within the SEPA area which is a member of RT1 or TIPS payment clearing and settlement system. List of RT1 and TIPS participants.

T2 - List on T2 participants. If T2 payment initiation goes to SEPA country and beneficiary bank is reachable via T2 system, then SEPA rules apply. If T2 payment initiation goes to SEPA country and beneficiary bank is not reachable via T2 system, then SWIFT rules apply. If T2 payment initiation goes to non SEPA country and beneficiary bank is reachable via T2 system, then SWIFT rules apply.

Swift - in LHV Pank (EE) product name is Foreign Payment. Swift payment is a) Payment in another currency than EUR. b) Payment in EUR but cannot be settled on RT1, TIPS, STEP2 SCT. If receiving bank is not located in SEPA area but payment currency is EUR then payment is settled if possible in T2 and swift payment fees apply.

Internal - Payment account opened in LHV Pank (EE) to account opened in LHV Pank (EE)

Group - Payment from/to LHV Pank (EE) to/from LHV Bank (UK)

Payment initiation Request

POST [base-url]/payment

Request message format is Customer to bank Payment Initiation (pain.001 message) that covers SEPA, SEPA Instant and other payments schemes and types available at LHV Pank. See the whole list

One payment initiation message may contain up to 1500 single payments.

Payment Status Report (pain.002) is returned to inform about the status of imported payments. More than one status may be returned for one payment.

Authentication methods

According to regulations and especially PSD2 by default all payments should be confirmed by the customer using SCA (Strong Customer Authentication). Depending on the customer and contract conditions there are different options and also exceptions.

LHV Connect currently supports following options:

Direct Processing

Payment files are submitted in XML format and processed instantly, without additional user actions or confirmations. No SCA is needed. This option is typically available only for Service Providers licensed by Estonian FI - including those from the EU and EEA.

Separate daily and monthly limits for Connect payments are followed. Virtual or Agency account payments are possible only using this option. Also additional contract appendix must be signed to use this possibility and additional security measures are agreed with the customer.

header Content-Type: application/xml

Pending Payments

Payment files are submitted in XML format, but not processed instantly. Payments must be confirmed in the Internet bank under Pending payments section and can be signed and confirmed only there. This follows the typical SCA process and is mostly used by companies not holding any PSP license. Only after confirmation the payments are processed and debited from the account. Internet Bank daily and monthly limits and acceptance rate is applied.

header Content-Type: application/xml

Signed Payments in DigiDoc Container

Payment files are sent in Estonian standard BDOC or ASIC-E container. This method also follows the standard SCA rules, but can provide a smoother user experience and faster processing - depending on the Customers interface where container is created. Internet bank daily and monthly limits and signature rights are followed. If payment requires more than one signature, all signatures must be included in the container. Limit usage is taken into account for the latest signer.

header Content-Type: application/vnd.etsi.asic-e+zip

XML message has to be signed and the created BDOC has to be put into the body of the message. Whoever signed the document has to have adequate limits and rights for the execution of the payment. XML file needs to be named as "request.xml".

In addition to legal person or representative signatures we also accept company digital seals (so called crypto-stick) but this option is available only for financial institutions.

Payment types and scheme selection

Following payment schemes are supported for payments initiated through LHV Connect:

• SEPA Credit Transfer (also SEPA), SEPA Instant Credit Transfer (also SEPA Inst) or SWIFT.

Payment scheme selection decisions can be done automatically (the default option) or submitted in the XML instructions.

Automatic payment scheme selection

• To other LHV accounts (EE -> EE) - internal payment
• To other account in LHV Group (EE -> UK or UK -> EE) – group payment
• If payment currency is EUR and the receiving bank is a member of the RT1 or TIPS clearing and settlement system - payment is sent as SEPA Instant Credit Transfer. List of RT1 and TIPS participants.
• If payment currency is EUR and the receiving bank is not reachable via RT1 or TIPS but is a member of the STEP2 SCT clearing and settlement system - payment is sent as SEPA Credit Transfer.
  • If SEPA Instant Credit Transfer cannot be processed for different reasons it is changed to SEPA Credit Transfer. First you will receive payment initiation response with status ACWC and description "Payment processed as SEPA" in tag. Then additional response about the actual SEPA payment.
• If payment currency is EUR and the receiving bank is not reachable via RT1, TIPS, or STEP2 SCT but is a member of T2 clearing and settlement system- payment is sent as SEPA Credit Transfer or Swift.
  • If receiving bank is located in SEPA area then SEPA Credit Transfer rules and fees apply.
  • If receiving bank is located outside SEPA area the Swift rules and fees apply.
  • If customer initial wish was to process payment as SEPA Instant/SEPA and it is not possible, then payment is processed as SWIFT (with priority normal and fee type SHA).

Manual payment scheme selection

Manual selection of payment scheme is done using optional tags in the XML structure - PmtInf.PmtTpInf.SvcLvl.Prtry for group level or CdtTrfTxInf.PmtTpInf.SvcLvl.Prtry for every payment individually.
Only if these tags are added system tries to use the provided scheme. If not added, then it will work as before – best scheme is selected automatically. Possible values are:

• INST – SEPA Instant Credit Transfer. Payments is processed in RT1 or TIPS.
• SEPA - SEPA Credit Transfer. Payment is processed in STEP2 SCT
• TARGET2 - Payment is processed in T2, value will stay TARGET2 but payments will be processed as SEPA or SWIFT payment.
• ALL - automatic selection, the same outcome as not providing the tag at all. Can also be used to select SWIFT payments.

Sample:

<PmtInf> //Group setting
    ...
    <PmtTpInf>
        <SvcLvl>
            <Prtry>SEPA</Prtry>
        </SvcLvl>
    </PmtTpInf>
    ...
    <CdtTrfTxInf>
    ...
        <PmtTpInf> //Single payment setting
            <SvcLvl>
                <Prtry>ALL</Prtry>
            </SvcLvl>
        </PmtTpInf>

Additional notes:

• If any Prtry value is not valid, the whole file is rejected.
• CdtTrfTxInf.PmtTpInf block setting takes priority over PmtInf.PmtTpInf if both are added
• All payments are still processed as Bank Internal Payments when possible (both accounts are in LHV Pank)
• If Bank Internal Payment cannot be used and also selected scheme cannot be used it will be rejected – every payment separately
• If payment is initiated, but there is insufficient daily or monthly limit, or insufficient funds available, it is canceled immediately unless otherwise agreed with LHV

Clearing times and limitations

See also: https://www.lhv.ee/en/payments and https://www.lhv.ee/en/payments_instructions_and_time_limits

Initiating Return Payments

Payment returns can be initiated with pain.001 message. Currently, it is available for SEPA (Instant) Credit Transfer, Group payment, and Swift if it is processed via T2.
Instruction for Debtor Agent tag (index 2.85) is used to refer to the Account Servicer Reference and return reason code of the payment to be returned.
Return must contain correct scheme return code found in appendix.

• If incorrect return code is used, return payment is rejected with error 'Invalid return code'.
• If payment to be returned cannot be found via Account Servicer Reference, return payment is rejected with error 'Original payment not received'.
  LHV does not match return payment data to the original payment.

Return as a Positive Response to Cancellation Request in SEPA Credit and Instant Transfer Schemes

• For SEPA Instant Credit Transfers, cancellation request by counterparty financial institution must precede return payment and only one return code can be used: FOCR - following cancellation request. If instant return is created without existing cancellation request, ordinary instant payment is created.
• For SEPA Credit Transfers, if return is created as a positive response to payment cancellation request, return code FOCR must be used. If other codes are used, LHV replaces them with code FOCR. Payments without existing cancellation request and with correct return code are forwarded unchanged.

XML format (new pain.001.001.09 version)

LHV is using custom version of pain.001.001.09.xsd.

XML rules

Multiplicity (MULT.) Informs how many times an element can or must be used, as defined by ISO standard.

1. 1..1 One occurrence (required)
2. 1..n One or several occurrences (value for “n” represents total number of occurrences)
3. 1..3 Minimum one occurrence must be used and maximum 3 occurrences can be used. Note: True value of “n” represents unlimited number of occurrences.
4. 0..1 None or one occurrence to be used (optional)
5. 0..n None or several occurrences can be used (value for “n” represents total number of occurrences). Note: True value of “n” represents unlimited number of occurrences.

Message structure

Group Header – mandatory, occurs once.
Payment Information – mandatory and repetitive. Contains information related to mostly the debit side of the payment.
Credit Transfer Transaction Information – mandatory and repetitive. Contains information related to the payment(s) included in the message.

Message root

Group header

Payment information

Address structure (PostalAddress)

Common address structure is used throughout the payment initiation message.
If PostalAddress is used then minimum Country and Town Name must be present.
Some additional requirements apply:

• Debtor address - For Virtual IBAN or agency banking account - the holder country
• If creditor´s bank locates outside EEA address information is mandatory from 31.10.2025. The rule applies to all parties (debtor, ultimate debtor, creditor etc).
• If creditor´s bank locates in EEA but the currency is not official currency in any EEA country (for example USD) - address information is mandatory from 31.10.2025. The rule applies to all parties (debtor, ultimate debtor, creditor etc).
• If payment is processed as TARGET2 (See https://partners.lhv.ee/en/connect/#code-set-payment-scheme) - address information is mandatory from 01.03.2024. The rule applies to all parties (debtor, ultimate debtor, creditor etc).

Supplementary data

Additional data can be added to the payment using SplmtryData element.
Supplementary data block is encapsulated in XSD envelope (field Envlp) which may contain any additional structure of data.

   <xs:complexType name="SupplementaryDataEnvelope1">
       <xs:sequence>
           <xs:any namespace="##any" processContents="lax"/>
       </xs:sequence>
   </xs:complexType>

LHV uses additional structure defined in supl.001.001.01.xsd.
For proper XML validation the schema reference should be provided in pain.001.001.09 XML message header.
For example:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09"
	xmlns:ext="urn:iso:std:iso:20022:tech:xsd:supl.001.001.01"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09 ../../XSD/pain.001.001.09.xsd urn:iso:std:iso:20022:tech:xsd:supl.001.001.01 ../../XSD/supl.001.001.01.xsd">

Supplementary data includes additional data elements defined in 3 fields.

1. party - party that given data element is related to (e.g. CREDITOR, DEBTOR)
2. key - data element key (see below for supported values)
3. value - value for given data element (e.g. 1986-02-05)

Supllementary data key's:

pain.001 supplementary data example:

...
<SplmtryData>
    <Envlp>
        <ext:Document>
            <ext:partyData>
                <ext:party>DEBTOR</ext:party>
                <ext:key>DATE_OF_BIRTH</ext:key>
                <ext:value>1980-09-24</ext:value>
            </ext:partyData>
            <ext:partyData>
                <ext:party>DEBTOR</ext:party>
                <ext:key>MCC</ext:key>
                <ext:value>0763</ext:value>
            </ext:partyData>
            <ext:partyData>
                <ext:party>DEBTOR</ext:party>
                <ext:key>PSP_SCENARIO</ext:key>
                <ext:value>COMBINED_PAYMENT</ext:value>
            </ext:partyData>
        </ext:Document>
    </Envlp>
</SplmtryData>
...

XML format (OLD pain.001.001.03 version)

This format is usable until 31.11.2025.

LHV is using custom version of pain.001.001.03.xsd, which is compliant with and has less restrictions than 1.4 version of the Estonian Banking Association implementation of pain.001.001.03. See more at XML B2C & C2B communication messages. LHV custom XSD is more restrictive that generic ISO 20022 XSD.
Any XML file valid according to LHV custom XSD is also valid to generic pain.001.001.03.

Generic pain.001.001.03 message xml schema file is available at www.iso20022.org.

XML rules

Multiplicity (MULT.) Informs how many times an element can or must be used, as defined by ISO standard.

1. 1..1 One occurrence (required)
2. 1..n One or several occurrences (value for “n” represents total number of occurrences)
3. 1..3 Minimum one occurrence must be used and maximum 3 occurrences can be used. Note: True value of “n” represents unlimited number of occurrences.
4. 0..1 None or one occurrence to be used (optional)
5. 0..n None or several occurrences can be used (value for “n” represents total number of occurrences). Note: True value of “n” represents unlimited number of occurrences.

Message structure

Group Header – mandatory, occurs once.
Payment Information – mandatory and repetitive. Contains information related to mostly the debit side of the payment.
Credit Transfer Transaction Information – mandatory and repetitive. Contains information related to the payment(s) included in the message.

Message root

Group header

Payment information

Samples

Samples of payments and related messages for typical use cases depending on payment schemes and other details.