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. 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 is: 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.

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_STATEMENT (response message for Account Statement request).

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

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
  }
  

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.

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

// 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.crt -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>2016-01-06T11:42:33.491</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>2021-09-13T11:50:25.646758</TimeStamp>
  <AuthorizedUser>
    <Name>Connect Demo Customer 1</Name>
    <Code>12340001</Code>
  </AuthorizedUser>
  <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>2016-01-06T11:42:25.709</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.
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>
                <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>
                <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>
                <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!

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

Payment initiation Request

POST [base-url]/payment

Request message format is Customer to bank Payment Initiation (XML type pain.001.001.03) that covers SEPA, SEPA Instant, UK Faster Payments and other payments schemes and types available at LHV Pank.

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

Payment Status Report (pain.002.001.03) 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 or UK FCA - 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. In addition to legal person or representative signatures we also accept company digital seals (so called crypto-stick). 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".

Payment types and scheme selection

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

• Customers opened bank account (IBAN) with LHV Pank - SEPA Credit Transfer (also SEPA), SEPA Instant Credit Transfer (also SEPA Inst) or SWIFT.
• Customers opened bank account (IBAN) with LHV UK Branch - Faster Payments, Intra-Bank payment (payments to other LHV Bank accounts including EE).

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

Automatic payment scheme selection

Customers opened bank account (IBAN) with LHV Pank:

• 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 Instant payment 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.
• For other EUR payments in the SEPA area, which receiving bank is not reachable via RT1 or TIPS but participant of STEP2 SCT- SEPA Credit transfer. List of STEP2 SCT participants
• Other payments not in EUR or in EUR where receiving bank is not reachable via RT1, TIPS, STEP2 SCT - Swift payment.
• 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 high and fee type SHA).

Customers opened bank account (IBAN) with LHV UK Branch:

• To other LHV accounts (UK-> UK) - internal payment
• To other account in LHV Group (EE-> UK or UK->EE) – group payment
• If payment currency is GBP and the receiving bank is a member of the Faster Payments Service clearing and settlement system - it is sent using Faster Payments. The upper limit of payment amount is 1 000 000 GBP.
  There are different methods to submit the beneficiary account as IBAN or UK domestic account nr with sort code. Examples added below.

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
• FAST - UK Faster Payment / FPS
• 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 Bank - EE and UK both included)
• 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 Payments_Instructions_and_Time_Limits-EN.pdf

Initiating Return Payments

Payment returns can be initiated with PAIN.001 message. Currently it is available for UK Faster Payments scheme (FAST), SEPA and SEPA Instant.
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

LHV is currently 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.

Response

XML format (ISO 20022 Customer Payment Status Report pain.002.001.03)

The ISO 20022 Customer Payment Status Report (pain.002.001.03) message is sent to the client to inform about the status of a payment instruction sent via LHV Connect with Payment Initiation (pain.001.001.03) message.

Header Message-Response-Type: PAYMENT

Customer Payment Status Report refers to the original Payment Initiation message and provides positive, negative and pending status updates to original payments.
There can be many Customer Payment Status Reports per one Payment Initiation message - typically if any of the transactions was not accepted right away for any reason.

Payment status codes and descriptions

Statuses are reported on group level for the whole payment instruction (GrpSts and PmtInfSts tags) and separately for each payment (TxSts tag).
Group level statuses are reported only in the first payment response message after the initial request.
Further responses (if any) shall not contain GrpSts and PmtInfSts tags - you must process the result of every payment entry separately.

Group level statuses (OrgnlGrpInfAndSts.GrpSts and OrgnlPmtInfAndSts.PmtInfSts):

• RJCT – all payments in original pain.001.001.03 Payment Information block have been rejected.
• PDNG - pending, payments are pending on human intervention. Typically, waiting for SCA in the Internet Bank.
• PART – if some of the payments in original pain.001.001.03 Payment Information block have reached one of the accepted statuses (ACSC, ACSP, ACWC), but some also rejected, then status is partially accepted.
• ACSP - all payments in original pain.001.001.03 have reached at least one of the accepted statuses (ACSC, ACSP, ACWC), but not debited yet
• ACSC - all payments in original pain.001.001.03 are debited from client’s account.

Single payment statuses (OrgnlPmtInfAndSts.TxInfAndSts.TxSts):

• RJCT – rejected. Payment has been rejected (final status).
• PDNG - pending. Payment is waiting for human intervention. Options: waiting for SCA in the Internet Bank or being reviewed by the Bank due to sanctions screening or manual corrections. More details below.
• ACSP – accepted, settlement in process. Payment is being processed by the bank, it has not been debited from client account nor sent to clearing system. At least one more status update must follow (either accept or reject).
• ACWC – accepted with change. Payment is being processed by the bank, it is not debited from client account. LHV has changed something about this payment. The reason for change is given in(3.25) tag. The changes are minor and do not harm the client’s intention. At least one more status is sent about this payment (either accept or reject).
• ACSC – accepted, settlement completed and payment has been debited from client account. ACSC is typically the final status. In rare occasions it can be followed by RJCT - then already debited payment is credited back to the payment account.

Pending payments and human intervention

When payment receives PDNG status after ACSP status (payment is accepted by the customer or does not need SCA depening on the contract) it means that the payment needs human intervention and manual review.
Depending on the case it can be a sanctions screening match or some other trigger that caused this. Direct communication with the customer might follow. When possible more details will be provided in the payment message narrative.

      <TxInfAndSts>
        ....
        <TxSts>PDNG</TxSts>
        <StsRsnInf>
          <Rsn>
            <Cd>NARR</Cd>
          </Rsn>
          <AddtlInf>In manual review</AddtlInf>
        </StsRsnInf>

When the manual intervention case is resolved the payment will continue normal flow and get ACSC or RJCT status depending on the decision and conditions.

Payment rejection due to account balance or limits

By default, all payments will be rejected right away when there is not enough free balance or payments limits to execute the payment. Only on special agreement with the customer system will continue to try executing such payments:

• Every day all payments sent 00:00 - 18:00 (Estonian time) and partially accepted will be rejected 18:00+5 minutes (if conditions are not met by this time).
• All payments sent 18:00 – 00:00 (Estonian time) and partially accepted will be rejected 5 minutes after sending.

Message structure

Group Header – mandatory, occurs once. Set of characteristics shared by all individual payments included in the status report message.
Original Group Information And Status – occurs once. Refers to original Payment Initiation Group Level information.
Transaction Information And Status – optional and repetitive. Includes information about the original payment and its status.

Message root

Group header

Error codes

Group level errors

Transaction level errors

Sample

• Current sample is related to the sample under payment initiation description
• There are two payments - first one (InstrId = INSTRIDLHVTEST101A) was successful with status ACSC and the second one (InstrId = INSTRIDLHVTEST101B) failed with status RJCT
• As only part of the payments were successful the group statusis PART

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">
	<CstmrPmtStsRpt>
		<GrpHdr>
			<MsgId>10942445</MsgId>
			<CreDtTm>2019-11-14T16:01:40.102+02:00</CreDtTm>
			<InitgPty>
				<Id>
					<OrgId>
						<BICOrBEI>LHVBEE20XXX</BICOrBEI>
					</OrgId>
				</Id>
			</InitgPty>
		</GrpHdr>
		<OrgnlGrpInfAndSts>
			<OrgnlMsgId>MSGIDLHVTEST01-1</OrgnlMsgId>
			<OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId>
			<GrpSts>PART</GrpSts>
		</OrgnlGrpInfAndSts>
		<OrgnlPmtInfAndSts>
			<OrgnlPmtInfId>PMTINFIDLHVTEST01</OrgnlPmtInfId>
			<PmtInfSts>PART</PmtInfSts>
			<TxInfAndSts>
				<OrgnlInstrId>INSTRIDLHVTEST01A</OrgnlInstrId>
				<TxSts>ACSC</TxSts>
				<AcctSvcrRef>D9C8845A4BBAEA11910E00155DBDB781</AcctSvcrRef>
				<OrgnlTxRef>
					<Amt>
						<InstdAmt Ccy="EUR">2.50</InstdAmt>
					</Amt>
					<ReqdExctnDt>2019-11-14</ReqdExctnDt>
					<PmtTpInf>
						<SvcLvl>
							<Prtry>INTERNAL</Prtry>
						</SvcLvl>
					</PmtTpInf>
					<Dbtr>
						<Nm>LHV Connect Demo 1</Nm>
					</Dbtr>
					<DbtrAcct>
						<Id>
							<IBAN>EE337700771001260958</IBAN>
						</Id>
					</DbtrAcct>
					<DbtrAgt>
						<FinInstnId>
							<BIC>LHVBEE20</BIC>
						</FinInstnId>
					</DbtrAgt>
					<CdtrAgt>
						<FinInstnId>
							<BIC>LHVBEE22</BIC>
						</FinInstnId>
					</CdtrAgt>
					<Cdtr>
						<Nm>LHV Connect Demo 2</Nm>
					</Cdtr>
					<CdtrAcct>
						<Id>
							<IBAN>EE267700771001260987</IBAN>
						</Id>
					</CdtrAcct>
				</OrgnlTxRef>
			</TxInfAndSts>
			<TxInfAndSts>
				<OrgnlInstrId>INSTRIDLHVTEST01B</OrgnlInstrId>
				<TxSts>RJCT</TxSts>
				<StsRsnInf>
					<Rsn>
						<Cd>NARR</Cd>
					</Rsn>
					<AddtlInf>Vigane saaja nimi.</AddtlInf>
				</StsRsnInf>
				<OrgnlTxRef>
					<Amt>
						<InstdAmt Ccy="EUR">5.00</InstdAmt>
					</Amt>
					<ReqdExctnDt>2019-11-14</ReqdExctnDt>
					<Dbtr>
						<Nm>LHV Connect Demo 1</Nm>
					</Dbtr>
					<DbtrAcct>
						<Id>
							<IBAN>EE337700771001260958</IBAN>
						</Id>
					</DbtrAcct>
					<DbtrAgt>
						<FinInstnId>
							<BIC>LHVBEE20</BIC>
						</FinInstnId>
					</DbtrAgt>
					<CdtrAgt>
						<FinInstnId>
							<BIC>LHVBEE22</BIC>
						</FinInstnId>
					</CdtrAgt>
					<Cdtr>
						<Nm>Incorrect Customer</Nm>
					</Cdtr>
					<CdtrAcct>
						<Id>
							<IBAN>EE427700771001260990</IBAN>
						</Id>
					</CdtrAcct>
				</OrgnlTxRef>
			</TxInfAndSts>
		</OrgnlPmtInfAndSts>
	</CstmrPmtStsRpt>
</Document>

Payment Collection Services

Services for different payment collection schemes and options.

Currently in active development and piloting phase - specification will be updated and improved without further notice.

SEPA Direct Debit

Overview

SEPA Direct Debit enables creditor to collect money in euros from debtors within SEPA countries. LHV Pank is a participant in the SEPA Direct Debit CORE system. The SEPA CORE direct debit scheme is intended to collect funds from debtors that may be businesses or private persons.

List of participants and reachable banks in SEPA Direct Debit CORE scheme: EBA Clearing STEP2 SDD Core Participants.

LHV offers 2 services: receiving collections and sending out collections (incl indirect Scheme Access)

Glossary

Creditor - An originator who initiates SEPA Direct Debit transactions for collection of funds from debtors (payers). In LHV the creditor can be only business.

Debtor - The legal person or business who pays the direct debit and has signed the SEPA Direct Debit mandate.

Target2 Working Day - The system is closed on the following days:

• 1 January (New Year's Day)
• Good Friday
• Easter Monday
• 1 May (Labour Day)
• 25 December (Christmas Day)
• 26 December

Due Date - Due date of the collection is the day when the payment of the debtor is due to the creditor.

Settlement Date - The general rule is that the key dates: Due date and settlement date are the same dates, but if the due date falls on a day that is not a Target2 day, then the settlement date will be the next Target2 Day.

Account Service Provider - Debtor's bank

Mandate - In order to receive a collection, the mandate agreement must be signed with creditor. The debtor is to give the signed written mandate directly to the creditor. The creditor is liable for safekeeping the mandate. The debtor agrees with the creditor on changes in the mandate and on its cancellation. The debtor bank does not have in its possession the mandates or their details given by the debtor to the creditor. This means that when the bank executes a direct debit payment order submitted by the creditor it does not check that the mandate given by the debtor corresponds to the direct debit payment order given by the creditor.

Pre-Notification - By Direct Debit rules, the debtor should receive at least 14 days before the due date a pre-notification. The pre-notification may for example be an invoice, if not otherwise agreed between debtor and creditor. In the case of recurring collections, the pre-notification may be sent only once when it includes the amounts and due dates.

Should the debtor have objections concerning a debit referred to in the pre-notification, the debtor must contact the creditor.

Mandate Reference - Unique Mandate Reference (UMR)

Receiving Collections

Businesses or private persons, also referred as debtor can receive the collection.

To receive collection the mandate agreement must be signed with creditor. To receive collection there is no agreement on bank side. Collections can be received on any current account opened for client.

If debtor wishes not to receive collections on a specific current account the account service provider must be contacted.

If debtor wishes to amend or terminate the mandate, debtor must always contact the creditor.

Receiving Collections: Reception and Execution of Direct Debit Collection

Direct Debit collection is received only on Target2 working days. Collections can be sent to debtor at the earliest 14 calendar days before due date and latest at 1 Target2 working day before due date.

Collections are sent to debtor's bank 7 times per Target2 working day, after controls are made the collection info is sent/made available to the debtor. See cut-offs.

Received collections are seen in LHV's internet bank, mobile app as pending outgoing payments. Connect's clients receive information by XML file (see messages). Please contact your account manager to enable the functionality.

The outgoing payment processing starts on the settlement date. Bank tries to make the payment several times but if there is not enough money or limit the payment is cancelled. No partial payments are made. See cut-offs.

Outgoing payment settlement happens at 11:30 CET, if it is done transaction entry will be seen on the account statement. If debtor is Connect user also debit/credit notification is sent.

Receiving Collections: Processing Exceptions

Debtor may cancel payment, reject collection or request for refund.

Reject collection

If the debtor wants the rejection to be permanent then an account service provider must be contacted. Otherwise, see Refusal.

Refusal

Debtor can cancel the payment until the settlement date. No settlement entries will follow. See cut-offs.

If debtor bank handles Refusal after Settlement, Refusal is processed as a Return. Settlement entries will take place.

If refusal is sent by debtor after settlement, see Request for refund.

Request for Refund

If the payment is settled debtor can't cancel the payment but request for refund. Debtor may claim a refund at any time up to 13 months after the settlement date.

If settlement took place less than 8 weeks ago. If the request is sent before 10.30 CET on Target2 day the payment is refunded at the same day. Otherwise on next Target2 day.

If 8 weeks after the settlement date is passed Debtor still may claim the refund. Debtor must provide such evidence to prove that the SEPA direct debit payment in question was unauthorised. Debtor´s bank will contact Creditor´s bank and decides whether the request will be sent or not. The whole process may take 30 calendar days.

Sending Out Collections

In LHV, business customers can send out the Direct Debit collection notices. Collections are sent to bank via Connect.

Sending Out Collections: Pre-Conditions

• Creditor Identifier code
• Direct Debit agreement with LHV
• Connect agreement with LHV
• Signed mandate with Debtor

In case of indirect Scheme access additional requirements must be followed. Details can provide your account manager.

Creditor Identifier code

Creditor Identifier is a unique identifier of a creditor. Each Direct Debit creditor is given just one Creditor Identifier. The Direct Debit creditor can, however, use the Creditor Business Code to flag specific units in his business where credit positions are collected via direct debit.

LHV generates CI code for Estonian companies and companies registered in UK. If the company is registred in other country you should contact the Bank/authority. Details can provide your account manager.

In case of Indirect Scheme access: LHV will not generate any codes. The process is managaed by service provider who has signed the Indirect Sheme Access Service agreement.

Mandate

To send out collection the mandate agreement must be signed with debtor. The debtor is to give the signed written mandate directly to the creditor. The creditor is liable for safekeeping the mandate. The debtor agrees with the creditor on changes in the mandate and on its cancellation.

The creditor or the debtor can amend the mandate at any time. If mandate is amended the information must be sent also to bank with new collection. When an amendment is made to any one of the four key mandate fields below, a flag must be raised to mark the mandate field as amended on the direct debit file. The flag is raised by setting the 'Amendment Indicator' tag to TRUE. Changes to the following fields represent an amended mandate:

• Debtor IBAN - If account service provider does not change then the original debtor IBAN should not be referenced, instead, the text ‘SMNDA’ should be included as the Original debtor Account. TRUE excemption: If account service provider changes the mandate details should be amended with new debtor IBAN details and mandate should be sent as first collection.
• Unique Mandate reference (UMR)
• Creditor Name
• Creditor ID

The cancellation of the Mandate is carried out by the creditor and the debtor without the involvement of either of their banks.

If a creditor does not present a collection on a mandate for 36 months, this mandate is considered cancelled and no longer valid. No further collections can be initiated on this cancelled mandate. In these cases, or where a debtor has cancelled their mandate and wishes to provide further debit authority to the creditor, a new mandate must be completed and UMR applied.

Mandate Reference

Unique Mandate Reference (UMR) is a free text field of up to 35 characters which must be the same for the first direct debit payment and each subsequent direct debit payment.

If the UMR cannot be provided on the mandate form before the customer signs the mandate, then the UMR must be provided separately to the customer before the first collection.

Debit types

There are four types of direct debit messages with different processing rules for each type.

• First Debits – the initial debit in a recurring series .
• Recurring Debits – which can recur regularly (e.g. monthly, quarterly, yearly, etc) or on an irregular basis, and are distinct from both the First Debit and the Last Debit.
• Final Debit – the last debit in a recurring series, which has the effect of terminating the mandate.
• One-off Debits – which represent a single, non-repeatable transaction

The First, Recurrent, and Final Debit follow the lifecycle of a series of direct debit messages, and they will therefore have the same mandate eference.

If collection has been handled exceptionally after settlement creditor may re-send the collection but must change the type of Collection.

Pre-notification

Creditor must send a pre-notification to the debtor before sending the collection to the creditor bank. A pre-notification may for example be an invoice, which must be sent to the debtor at least 14 calendar days before the due date, if not otherwise agreed between the debtor and the creditor. In case of recurring collections, the pre-notification may be sent only once when it includes the amounts and due dates.

Pre-notification should include:

• Creditor Identifier
• Mandate reference, which can also be informed later but latest before collection
• Amount to be debited
• Due date

The Pre-notification could also include:

• The schedule of payments for recurring direct debits for an agreed period of time
• An individual advice of a collection for collection on a specified due date

Sending Out Collections: Reception and Execution of Direct Debit Collection

Before creditor sends collection to debtor creditor must have:

• Signed mandate with debtor
• Pre-notification sent to debtor

Direct Debit collection is sent to debtor only on Target2 working day. Creditor can send collection to LHV on any calendar day but due date and cut-off rules must be followed.

Collections can be sent to debtor at the earliest 14 calendar days before due date and latest at 1 Target2 working day before due date.

LHV sends collection to scheme 7 times per Target2 day. See cut-offs.

Sending Out Collections: Processing Exceptions

If a creditor does not present a collection on a mandate for 36 months, this mandate is considered cancelled and no longer valid.

Cancel collection

Request of cancellation can be sent until due date. See cut-offs.

If creditor bank handles after Settlement, it is processed as a Reversal. Settlement entries will take place.

Reversal collection

If the creditor wants to return collection payment after settlement we recommend to use credit payment functionality.

If the creditor wants to return the payment as Direct Debit payment the bank must be contacted (manual process).

Request of refund

Debtor may claim a refund at any time up to 13 months after the settlement date.

If settlement took place less than 8 weeks ago. There is no appeal process and refund.

If 8 weeks after the settlement date is passed debtor still may claim the refund. Debtor bank collects evidence and decides whether process or not the refund. If refund request is sent out there is no appeal process.

Cut-offs

Messages

Direct Debit Initiation Request

POST [base-url]/direct-debit/collection

Request message format is Customer Direct Debit Collection Initiation (XML type pain.008.001.02) that covers SEPA Direct Debit scheme.

One collection initiation message may contain up to 1500 single collections.

Payment Status Report (pain.002.001.03) is returned to inform about the status of imported collections. More than one status may be returned for one collection.

XML Format

LHV is currently using custom version of pain.008.001.02.xsd and has less restrictions than EPC implementation of pain.008.001.02.

Message structure

Message root

Group header

Payment information