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 much needed 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.ee (DigiCert High Assurance EV Root CA), that ensures that client is connecting the 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

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.

Sending request

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 response

GET [base-url]/messages/next
By default always the older 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.
• Filter-Service-Provider - add this optional header to select service provider messages only. 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.

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 (mandatory) - 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

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.

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

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

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 -k -X GET "https://connect.prelive.lhv.eu/heartbeat" --cert yourcert.crt --key yourkey.key --cacert LHV_test_rootca2011.crt

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

// Sandbox - for service providers:
curl -k -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 -k -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>

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 Balance POST [base-url]/account-balance

XML format (camt.060.001.03)

The ISO 20022 Account Report Request camt.060.001.03 standard is used.

Message root

Group header

Sample

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 GMT+3 time zone.
• 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>

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 then one response in the queue.

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

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. Report does not include detailed entry data.

Message root

Group header

Report

Sample

Sample account EE337700771001260958 has balances in EUR, GBP and USD.

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.052.001.06">
	<BkToCstmrAcctRpt>
		<GrpHdr>
			<MsgId>10942452</MsgId>
			<CreDtTm>2019-11-14T16:27:24.775</CreDtTm>
		</GrpHdr>
		<Rpt>
			<Id>10942452EUR</Id>
			<CreDtTm>2019-11-14T16:27:24.775</CreDtTm>
			<FrToDt>
				<FrDtTm>2019-11-14T16:27:24.775</FrDtTm>
				<ToDtTm>2019-11-14T16:27:24.775</ToDtTm>
			</FrToDt>
			<Acct>
				<Id>
					<IBAN>EE337700771001260958</IBAN>
				</Id>
				<Ccy>EUR</Ccy>
			</Acct>
			<Bal>
				<Tp>
					<CdOrPrtry>
						<Cd>ITBD</Cd>
					</CdOrPrtry>
				</Tp>
				<Amt Ccy="EUR">7712.03</Amt>
				<CdtDbtInd>CRDT</CdtDbtInd>
				<Dt>
					<Dt>2019-11-14</Dt>
				</Dt>
			</Bal>
			<Bal>
				<Tp>
					<CdOrPrtry>
						<Cd>ITAV</Cd>
					</CdOrPrtry>
				</Tp>
				<Amt Ccy="EUR">7599.53</Amt>
				<CdtDbtInd>CRDT</CdtDbtInd>
				<Dt>
					<Dt>2019-11-14</Dt>
				</Dt>
			</Bal>
		</Rpt>
		<Rpt>
			<Id>10942452GBP</Id>
			<CreDtTm>2019-11-14T16:27:24.775</CreDtTm>
			<FrToDt>
				<FrDtTm>2019-11-14T16:27:24.775</FrDtTm>
				<ToDtTm>2019-11-14T16:27:24.775</ToDtTm>
			</FrToDt>
			<Acct>
				<Id>
					<IBAN>EE337700771001260958</IBAN>
				</Id>
				<Ccy>GBP</Ccy>
			</Acct>
			<Bal>
				<Tp>
					<CdOrPrtry>
						<Cd>ITBD</Cd>
					</CdOrPrtry>
				</Tp>
				<Amt Ccy="GBP">1000.00</Amt>
				<CdtDbtInd>CRDT</CdtDbtInd>
				<Dt>
					<Dt>2019-11-14</Dt>
				</Dt>
			</Bal>
			<Bal>
				<Tp>
					<CdOrPrtry>
						<Cd>ITAV</Cd>
					</CdOrPrtry>
				</Tp>
				<Amt Ccy="GBP">1000.00</Amt>
				<CdtDbtInd>CRDT</CdtDbtInd>
				<Dt>
					<Dt>2019-11-14</Dt>
				</Dt>
			</Bal>
		</Rpt>
		<Rpt>
			<Id>10942452USD</Id>
			<CreDtTm>2019-11-14T16:27:24.775</CreDtTm>
			<FrToDt>
				<FrDtTm>2019-11-14T16:27:24.775</FrDtTm>
				<ToDtTm>2019-11-14T16:27:24.775</ToDtTm>
			</FrToDt>
			<Acct>
				<Id>
					<IBAN>EE337700771001260958</IBAN>
				</Id>
				<Ccy>USD</Ccy>
			</Acct>
			<Bal>
				<Tp>
					<CdOrPrtry>
						<Cd>ITBD</Cd>
					</CdOrPrtry>
				</Tp>
				<Amt Ccy="USD">1751.20</Amt>
				<CdtDbtInd>CRDT</CdtDbtInd>
				<Dt>
					<Dt>2019-11-14</Dt>
				</Dt>
			</Bal>
			<Bal>
				<Tp>
					<CdOrPrtry>
						<Cd>ITAV</Cd>
					</CdOrPrtry>
				</Tp>
				<Amt Ccy="USD">1751.20</Amt>
				<CdtDbtInd>CRDT</CdtDbtInd>
				<Dt>
					<Dt>2019-11-14</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

There are different authentication methods to send payments via Connect:

Pending Payments

Payment files are sent by plain XML. Payments are not processed immediately. All sent payments are seen at Internet bank under Pending payments and can be signed and confirmed only there. 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 BDOC container. Internet bank daily and monthly limits and acceptance rate is applied. If payment requires more than one signature, all signatures must be included in the BDOC container and limit usage is taken into account for the last 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".

Direct Processing

Payment files are sent by plain XML and processed without additional user actions or confirmations. This option is 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/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

Payment types and scheme selection

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

• Estonian Accounts - SEPA Instant (SCT Inst), SEPA or SWIFT.
• UK Accounts - 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

Estonian accounts:

• To other LHV accounts (both EE and UK) - Bank internal payment
• If payment currency is EUR and the receiving bank is a member of the RT1 clearing and settlement system for Instant payments - payment is sent as SEPA Instant. List of participants can be found here.
• If Instant payment cannot be processed for different reasons it is changed to SEPA. First you will receive payment initiation response with status ACWC and description "Payment processed as SEPA" intag. Then additional response about the actual SEPA payment.
• For other EUR payments in the EAA (European Economic Area) - SEPA payment.
• Other payments not in EUR or where beneficiary bank is not in the EEA - Swift payment.
• If customer initial wish was to process payment as Instant/SEPA and it is not possible, then payment is processed as SWIFT (with priority high and fee type SHA).

UK Accounts:

• To other LHV accounts (both EE and UK) - Bank internal 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 250000 GBP.
  There are different methods to submit the beneficiary account as IBAN or UK domestic account nr with sort code. Examples added below.
• For Intra-Bank payment also other currencies are available, beneficiary account must belong to LHV UK or Estonian branch.

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 Payment / SCTInst
• SEPA - SEPA Payment / 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 FAST (UK Faster Payments scheme). SEPA and SEPA Instant are in development.
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

Typical EUR payment - including two payments in single file:

• Remitter (debitor) is "LHV Connect Demo" with account EE337700771001260958
• Beneficiaries (creditor) are "LHV Connect Demo 2" with account EE337700771001260958 and "Incorrect Customer" with account EE427700771001260990
• Multiple payments from the same account can have oneblock for creditor details and different/blocks for debitor details.
• The sample under payment initiation response description is related to current sample.

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
	<CstmrCdtTrfInitn>
		<GrpHdr>
			<MsgId>MSGIDLHVTEST01-1</MsgId>
			<CreDtTm>2019-11-14T14:30:04.482</CreDtTm>
			<NbOfTxs>2</NbOfTxs>
			<CtrlSum>7.50</CtrlSum>
			<InitgPty>
				<Nm>LHV Connect Demo</Nm>
			</InitgPty>
		</GrpHdr>
		<PmtInf>
			<PmtInfId>PMTINFIDLHVTEST01</PmtInfId>
			<PmtMtd>TRF</PmtMtd>
			<BtchBookg>false</BtchBookg>
			<NbOfTxs>2</NbOfTxs>
			<CtrlSum>7.50</CtrlSum>
			<ReqdExctnDt>2019-11-14</ReqdExctnDt>
			<Dbtr>
				<Nm>LHV Connect Demo</Nm>
			</Dbtr>
			<DbtrAcct>
				<Id>
					<IBAN>EE337700771001260958</IBAN>
				</Id>
			</DbtrAcct>
			<DbtrAgt>
				<FinInstnId>
					<BIC>LHVBEE22XXX</BIC>
				</FinInstnId>
			</DbtrAgt>
			<ChrgBr>SHAR</ChrgBr>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>INSTRIDLHVTEST01A</InstrId>
					<EndToEndId>ENDTOENDIDLHVTEST01A</EndToEndId>
				</PmtId>
				<PmtTpInf>
					<LclInstrm>
						<Prtry>EXPR</Prtry>
					</LclInstrm>
				</PmtTpInf>
				<Amt>
					<InstdAmt Ccy="EUR">2.50</InstdAmt>
				</Amt>
				<ChrgBr>SHAR</ChrgBr>
				<CdtrAgt>
					<FinInstnId>
						<BIC>LHVBEE22XXX</BIC>
					</FinInstnId>
				</CdtrAgt>
				<Cdtr>
					<Nm>LHV Connect Demo 2</Nm>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>EE267700771001260987</IBAN>
					</Id>
				</CdtrAcct>
				<RmtInf>
					<Ustrd>Payment Description LHVTEST01A</Ustrd>
					<Strd>
						<CdtrRefInf>
							<Tp>
								<CdOrPrtry>
									<Cd>SCOR</Cd>
								</CdOrPrtry>
							</Tp>
							<Ref>700170939</Ref>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>INSTRIDLHVTEST01B</InstrId>
					<EndToEndId>ENDTOENDIDLHVTEST01B</EndToEndId>
				</PmtId>
				<PmtTpInf>
					<LclInstrm>
						<Prtry>EXPR</Prtry>
					</LclInstrm>
				</PmtTpInf>
				<Amt>
					<InstdAmt Ccy="EUR">5.00</InstdAmt>
				</Amt>
				<ChrgBr>SHAR</ChrgBr>
				<CdtrAgt>
					<FinInstnId>
						<BIC>LHVBEE22XXX</BIC>
					</FinInstnId>
				</CdtrAgt>
				<Cdtr>
					<Nm>Incorrect Customer</Nm>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>EE427700771001260990</IBAN>
					</Id>
				</CdtrAcct>
				<RmtInf>
					<Ustrd>Payment Description LHVTEST01B</Ustrd>
				</RmtInf>
			</CdtTrfTxInf>
		</PmtInf>
	</CstmrCdtTrfInitn>
</Document>

UK Faster Payments - with beneficiary account as IBAN:

...
<CdtrAcct>
    <Id>
        <IBAN>GB29LHVB60161331921111</IBAN>
    </Id>
</CdtrAcct>
...

UK Faster Payments - with beneficiary account as UK sort code and domestic account number concatenated (CdtrAcct.Id.Othr.Id - 14 char):

...
<CdtrAcct>
    <Id>
        <Othr>
            <Id>12345612345678</Id>
            <SchmeNm>
                <Cd>BBAN</Cd>
            </SchmeNm>
        </Othr>
     </Id>
</CdtrAcct>
...

UK Faster Payments - with beneficiary account as UK Sort Code and domestic account number as separate values (CdtrAgt.FinInstnId.ClrSysMmbId.MmbId - 6 char + CdtrAcct.Id.Othr.Id - 8 char):

...
<CdtrAgt>
    <FinInstnId>
        <ClrSysMmbId>
            <ClrSysId>
                <Cd>GBDSC</Cd>
            </ClrSysId>
            <MmbId>123456</MmbId>
        </ClrSysMmbId>
    </FinInstnId>
</CdtrAgt>
...
<CdtrAcct>
    <Id>
        <Othr>
            <Id>12345678</Id>
        </Othr>
    </Id>
</CdtrAcct>
...

UK Faster Payments reference information - adding reference is mandatory:

        <RmtInf>
          <Ustrd>payment description 123</Ustrd>
          <Strd>
            <CdtrRefInf>
              <Ref>Payment reference</Ref>
            </CdtrRefInf>
          </Strd>
        </RmtInf>

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.

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 payments 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 waiting for confirmation in 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 – payment has been rejected (final status).
• PDNG - pending. Payment is waiting for confirmation in Internet Bank.
• 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.

By default all payments will be rejected right away when there is not enough funds or payments limits left. 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>

Virtual IBAN Services

Virtual IBAN Open

POST [base-url]/viban/open

Service is used to request new Virtual IBAN opening. Only one Virtual IBAN can be opened with one service request.
It is mandatory to fill in minimal data set about Virtual IBAN owner and request message structure is slightly different for private and legal persons.
After receiving the request, background check is done by LHV for Virtual IBAN owner (the check is done in less than a second).

• If check is OK, then Virtual IBAN is activated at once.
• If check is not OK, then Virtual IBAN will remain in status ON_HOLD until decision about Virtual IBAN opening is made. CONNECT customer will be informed about the decision (status ACTIVE or REJECTED) via service Status notification.

Request

• viban.open.request.xsd
• viban.common.xsd

Message structure

Sample

Private person

<?xml version="1.0" encoding="UTF-8"?>
<VibanOpenRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <ClientReference>12345678</ClientReference>
  <User>
    <Person>
      <Name>Donald Duck</Name>
      <BirthDate>1908-11-29</BirthDate>
      <BirthCountry>DE</BirthCountry>
      <Residency>DE</Residency>
      <DocumentNumber>A942819</DocumentNumber>
    </Person>
    <Address>
      <Country>EE</Country>
      <StreetNo>Majaka 47-10</StreetNo>
      <CityCounty>Xiao, Neverland</CityCounty>
    </Address>
  </User>
</VibanOpenRequest>

Legal person

<?xml version="1.0" encoding="UTF-8"?>
<VibanOpenRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <ClientReference>12345678</ClientReference>
  <User>
    <Company>
      <Name>UK Ltd Version 2.0</Name>
      <CountryOfOrigin>GB</CountryOfOrigin>
      <TaxResidency>GB</TaxResidency>
      <RegistrationNumber>1849203</RegistrationNumber>
      <Representative>
        <Name>Harry Potter</Name>
        <BirthDate>2001-01-01</BirthDate>
        <Residency>GB</Residency>
      </Representative>
    </Company>
    <Address>
      <Country>GB</Country>
      <StreetNo>Waterloo Bridge 13</StreetNo>
      <CityCounty>London, Cold</CityCounty>
    </Address>
  </User>
</VibanOpenRequest>

Response

Header Message-Response-Type: VIBAN_OPEN

• viban.open.response.xsd
• viban.common.xsd

Message structure

Sample

Private person

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VibanOpenResponse>
    <MasterAccount>EE837700771001625166</MasterAccount>
    <ClientReference>12345678</ClientReference>
    <VirtualIBAN>EE867777000202527783</VirtualIBAN>
    <User>
        <Person>
          <Name>Donald Duck</Name>
          <BirthDate>1908-11-29</BirthDate>
          <BirthCountry>DE</BirthCountry>
          <Residency>DE</Residency>
          <DocumentNumber>A942819</DocumentNumber>
        </Person>
        <Address>
            <Country>EE</Country>
            <StreetNo>Majaka 47-10</StreetNo>
            <CityCounty>Xiao, Neverland</CityCounty>
        </Address>
    </User>
    <Status>ACTIVE</Status>
</VibanOpenResponse>

Legal person

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VibanOpenResponse>
    <MasterAccount>EE837700771001625166</MasterAccount>
    <ClientReference>12345678</ClientReference>
    <VirtualIBAN>EE497777000202527770</VirtualIBAN>
    <User>
        <Company>
            <Name>UK Ltd Version 2.0</Name>
            <CountryOfOrigin>GB</CountryOfOrigin>
            <TaxResidency>GB</TaxResidency>
            <RegistrationNumber>1849203</RegistrationNumber>
            <Representative>
                <Name>Harry Potter</Name>
                <BirthDate>2001-01-01</BirthDate>
                <Residency>GB</Residency>
            </Representative>
        </Company>
        <Address>
            <Country>GB</Country>
            <StreetNo>Waterloo Bridge 13</StreetNo>
            <CityCounty>London, Cold</CityCounty>
        </Address>
    </User>
    <Status>ACTIVE</Status>
</VibanOpenResponse>

Virtual IBAN Bulk

POST [base-url]/viban/bulk

Service is used for bulk opening nameless Virtual IBANs. Up to 1000 virtual IBANs can be opened with one request.

Nameless virtual IBANs remain in "PENDING" status and can not be used for making payments until Virtual IBAN owner's personal details are added via service Virtual IBAN Modify.

Request

• viban.bulk.request.xsd

Message structure

Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VibanBulkRequest>
  <MasterAccount>EE737700771001625166</MasterAccount>
  <Amount>2</Amount>
</VibanBulkRequest>

Response

Header Message-Response-Type: VIBAN_BULK

• viban.bulk.response.xsd

Message structure

Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VibanBulkResponse>
    <MasterAccount>EE737700771001625166</MasterAccount>
    <VirtualIBANList>
        <VirtualIBAN>EE717777000200014007</VirtualIBAN>
        <VirtualIBAN>EE507777000200014094</VirtualIBAN>
    </VirtualIBANList>
</VibanBulkResponse>

Virtual IBAN Modify

POST [base-url]/viban/modify
Service is used to:

• add Virtual IBAN holder data to nameless Virtual IBANs allocated with Virtual IBAN Bulk service
• modify existing Virtual IBAN data

Only one Virtual IBAN can be modified with one service request. It is mandatory to fill in minimal data set about Virtual IBAN owner and request message structure is slightly different for private and legal persons. After receiving the request, background check is done by LHV for Virtual IBAN owner.
If check is OK, then Virtual IBAN is activated at once.
If check is not OK, then Virtual IBAN will remain in status "ON_HOLD" until decision about Virtual IBAN opening is made. CONNECT customer will be informed about the decision via service Status notification.

Rules when changing the data of already activated Virtual IBAN:

• Virtual IBAN must never be allocated to a different entity. Valid reasons are:
  
  - Name change - marriage for private persons or company name change for corporates etc.
  
  - Changes to address
  
  - Any other case where corrections are needed, but the assigned customer stays the same
• You must provide the reason for change in the ModifyReason tag
• Any modifiactions will trigger re-screening of the Virtual IBAN

Request

• viban.modify.request.xsd
• viban.common.xsd

Message structure

Sample

Private person

<?xml version="1.0" encoding="UTF-8"?>
<VibanModifyRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <ClientReference>12345678</ClientReference>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <User>
    <Person>
      <Name>Donald Mouse</Name>
      <BirthDate>1908-11-29</BirthDate>
      <BirthCountry>DE</BirthCountry>
      <Residency>DE</Residency>
      <DocumentNumber>A942819</DocumentNumber>
    </Person>
    <Address>
      <Country>EE</Country>
      <StreetNo>Majaka 47-10</StreetNo>
      <CityCounty>Xiao, Neverland</CityCounty>
    </Address>
  </User>
  <ModifyReason>Name legally changed to Donald Mouse</ModifyReason>
</VibanModifyRequest>

Legal person

<?xml version="1.0" encoding="UTF-8"?>
<VibanModifyRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <ClientReference>12345678</ClientReference>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <User>
    <Company>
      <Name>UK Ltd Version 2.0</Name>
      <CountryOfOrigin>GB</CountryOfOrigin>
      <TaxResidency>GB</TaxResidency>
      <RegistrationNumber>1849203</RegistrationNumber>
      <Representative>
        <Name>John Connor</Name>
        <BirthDate>2010-01-01</BirthDate>
        <Residency>GB</Residency>
      </Representative>
    </Company>
    <Address>
      <Country>GB</Country>
      <StreetNo>Waterloo Bridge 13</StreetNo>
      <CityCounty>London, Cold</CityCounty>
    </Address>
  </User>
  <ModifyReason>New company representative</ModifyReason>
</VibanModifyRequest>

Response

Header Message-Response-Type: VIBAN_MODIFY

• viban.modify.response.xsd
• viban.common.xsd

Message structure

Sample

Private person

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VibanModifyResponse>
  <ClientReference>12345678</ClientReference>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
    <User>
        <Person>
          <Name>Donald Duck</Name>
          <BirthDate>1908-11-29</BirthDate>
          <BirthCountry>DE</BirthCountry>
          <Residency>DE</Residency>
          <DocumentNumber>A942819</DocumentNumber>
        </Person>
        <Address>
            <Country>EE</Country>
            <StreetNo>Majaka 47-10</StreetNo>
            <CityCounty>Xiao, Neverland</CityCounty>
        </Address>
    </User>
  <Status>ACTIVE</Status>
</VibanModifyResponse>

Legal person

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VibanModifyResponse>
  <ClientReference>12345678</ClientReference>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
    <User>
        <Company>
            <Name>UK Ltd Version 2.0</Name>
            <CountryOfOrigin>GB</CountryOfOrigin>
            <TaxResidency>GB</TaxResidency>
            <RegistrationNumber>1849203</RegistrationNumber>
            <Representative>
                <Name>Harry Potter</Name>
                <BirthDate>2001-01-01</BirthDate>
                <Residency>GB</Residency>
            </Representative>
        </Company>
        <Address>
            <Country>GB</Country>
            <StreetNo>Waterloo Bridge 13</StreetNo>
            <CityCounty>London, Cold</CityCounty>
        </Address>
    </User>
  <Status>ACTIVE</Status>
</VibanModifyResponse>

Virtual IBAN Info

POST [base-url]/viban/info

Service is used to request Virtual IBAN data.
Response message structure is slightly different for private and legal persons.

Request

• viban.info.request.xsd
• viban.common.xsd

Message structure

Sample

<?xml version="1.0" encoding="UTF-8"?>
<VibanInfoRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
</VibanInfoRequest>

Response

Header Message-Response-Type: VIBAN_INFO

• viban.info.response.xsd
• viban.common.xsd

Message structure

Sample

Private person

<?xml version="1.0" encoding="UTF-8"?>
<VibanInfoResponse>
  <ClientReference>12345678</ClientReference>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <User>
  	<Person>
  	  <Name>Donald Duck</Name>
  	  <BirthDate>1908-11-29</BirthDate>
  	  <BirthCountry>DE</BirthCountry>
  	  <Residency>DE</Residency>
  	  <DocumentNumber>A942819</DocumentNumber>
  	</Person>
  	<Address>
  		<Country>EE</Country>
  		<StreetNo>Majaka 47-10</StreetNo>
  		<CityCounty>Xiao, Neverland</CityCounty>
  	</Address>
  </User>
  <Status>ACTIVE</Status>
  <!--Optional:-->
  <DateActivated>2018-01-01+02:00</DateActivated>
  <!--Optional:-->
  <DateClosed>2018-05-22+03:00</DateClosed>
</VibanInfoResponse>

Legal person

<?xml version="1.0" encoding="UTF-8"?>
<VibanInfoResponse>
  <ClientReference>12345678</ClientReference>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <User>
  	<Company>
  		<Name>UK Ltd Version 2.0</Name>
  		<CountryOfOrigin>GB</CountryOfOrigin>
  		<TaxResidency>GB</TaxResidency>
  		<RegistrationNumber>1849203</RegistrationNumber>
  		<Representative>
  			<Name>Harry Potter</Name>
  			<BirthDate>2001-01-01</BirthDate>
  			<Residency>GB</Residency>
  		</Representative>
  	</Company>
  	<Address>
  		<Country>GB</Country>
  		<StreetNo>Waterloo Bridge 13</StreetNo>
  		<CityCounty>London, Cold</CityCounty>
  	</Address>
  </User>
  <Status>ACTIVE</Status>
  <!--Optional:-->
  <DateActivated>2018-01-01+02:00</DateActivated>
  <!--Optional:-->
  <DateClosed>2018-05-22+03:00</DateClosed>
</VibanInfoResponse>

Virtual IBAN Close

POST [base-url]/viban/close

Service is used to close a Virtual IBAN.
Once Virtual IBAN is closed, it cannot be activated again.

Request

• viban.close.request.xsd

Message structure

Sample

<?xml version="1.0" encoding="UTF-8"?>
<VibanCloseRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
</VibanCloseRequest>

Response

Header Message-Response-Type: VIBAN_CLOSE

• viban.close.response.xsd

Message structure

Sample

<?xml version="1.0" encoding="UTF-8"?>
<VibanCloseResponse>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <Status>CLOSED</Status>
  <DateClosed>2018-05-22+03:00</DateClosed>
</VibanCloseResponse>

Virtual IBAN Status Notification

Service is used to send information to CONNECT customers about Virtual IBAN status changes. Notification messages are created for status changes not initiated directly by user - for example when account with screening match is activated (status changes from ON_HOLD to ACTIVE).

Header Message-Response-Type: VIBAN_STATUS_NOTIFICATION

XSD

• viban.status.notification.xsd
• viban.common.xsd

Message structure

Sample

Private person

<?xml version="1.0" encoding="UTF-8"?>
<VibanStatusNotification>
  <ClientReference>12345678</ClientReference>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <User>
  	<Person>
  	  <Name>Donald Duck</Name>
  	  <BirthDate>1908-11-29</BirthDate>
  	  <BirthCountry>DE</BirthCountry>
  	  <Residency>DE</Residency>
  	  <DocumentNumber>A942819</DocumentNumber>
  	</Person>
  	<Address>
  		<Country>EE</Country>
  		<StreetNo>Majaka 47-10</StreetNo>
  		<CityCounty>Xiao, Neverland</CityCounty>
  	</Address>
  </User>
  <Status>ACTIVE</Status>
  <!--Optional:-->
  <DateActivated>2018-01-01+02:00</DateActivated>
  <!--Optional:-->
  <DateClosed>2018-05-22+03:00</DateClosed>
</VibanStatusNotification>

Legal person

<?xml version="1.0" encoding="UTF-8"?>
<VibanStatusNotification>
  <ClientReference>12345678</ClientReference>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
  <User>
  	<Company>
  		<Name>UK Ltd Version 2.0</Name>
  		<CountryOfOrigin>GB</CountryOfOrigin>
  		<TaxResidency>GB</TaxResidency>
  		<RegistrationNumber>1849203</RegistrationNumber>
  		<Representative>
  			<Name>Harry Potter</Name>
  			<BirthDate>2001-01-01</BirthDate>
  			<Residency>GB</Residency>
  		</Representative>
  	</Company>
  	<Address>
  		<Country>GB</Country>
  		<StreetNo>Waterloo Bridge 13</StreetNo>
  		<CityCounty>London, Cold</CityCounty>
  	</Address>
  </User>
  <Status>ACTIVE</Status>
  <!--Optional:-->
  <DateActivated>2018-01-01+02:00</DateActivated>
  <!--Optional:-->
  <DateClosed>2018-05-22+03:00</DateClosed>
</VibanStatusNotification>

Indirect Scheme Access

Services for Indirect Scheme Access Account management for service providers with a valid Agency agreement.
We offer this service for FPS (Faster Payments scheme) with UK accounts and SEPA Credit Transfers and Instant payments.

Agency Account Synchronization

POST [base-url]/agent/account/synchronize

Service is used for synchronizing third party service provider's existing account numbers with LHV.
Request supports multiple accounts in bulk.

• Request may contain up to 1000 accounts (Accounts.Account blocks).
• Request adds new account or updates existing account status. Duplicity is not checked, existing accounts data is overwritten.
• For valid requests, accounts are activated immediately by LHV.
• For any invalid entry in request, entire bulk is rejected and relevant error code is returned.
• Service provider must have a valid agency agreement.

Request

• agent.account.sync.request.xsd
• agent.account.sync.common.xsd

Message structure

Sample

Synchronization request for UK account numbers

<?xml version="1.0" encoding="UTF-8"?>
<AgentAccountSyncRequest>
    <Accounts>
        <Account>
            <Region>GB</Region>
            <AccountNo>12345612345678</AccountNo>
            <Status>ACTIVE</Status>
        </Account>
        <Account>
            <Region>GB</Region>
            <AccountNo>12345612345679</AccountNo>
            <Status>ACTIVE</Status>
        </Account>
    </Accounts>
</AgentAccountSyncRequest>

Response

Header Message-Response-Type: AGENT_ACCOUNT_SYNC

• agent.account.sync.response.xsd
• agent.account.sync.common.xsd

Message structure

Sample

Synchronization response for UK account numbers

<?xml version="1.0" encoding="UTF-8"?>
 <AgentAccountSyncRequest>
     <Accounts>
         <Account>
             <Region>GB</Region>
             <AccountNo>12345612345678</AccountNo>
             <Status>ACTIVE</Status>
         </Account>
         <Account>
             <Region>GB</Region>
             <AccountNo>12345612345679</AccountNo>
             <Status>ACTIVE</Status>
         </Account>
     </Accounts>
 </AgentAccountSyncRequest>

Error response sample

<?xml version='1.0' encoding='UTF-8'?>
<Errors>
    <Error>
        <ErrorCode>MASTER_ACCOUNT_NOT_FOUND</ErrorCode>
        <Description>Master account not found.</Description>
        <Field>account[1].AccountNo, account[1].Iban</Field>
    </Error>
</Errors>

Error codes

Error codes are subject to change.

Agency Account Open

POST [base-url]/agent/account/open

Service is used for opening accounts for third party service providers at LHV.
One account can be opened with one request. After receiving the request, background check is done by LHV for third party's account owner (the check is done in less than a second).

• If check is OK, account is activated.
• If check is not OK, the account remains in status ON_HOLD until decision about the account opening is made. Status update (ACTIVE or REJECTED) is sent to CONNECT customers via Agent Account Status Notification.
• Service provider must have a valid agency agreement.

Request

• agent.account.open.request.xsd
• agent.account.open.common.xsd

Message structure

Sample

Agency account open request for private person

<?xml version="1.0" encoding="UTF-8"?>
<AccountOpenRequest>
  <MasterAccount>GB27LHVB04030000003349</MasterAccount>
  <User>
    <Person>
      <Name>Donald Duck</Name>
      <BirthDate>1908-11-29</BirthDate>
      <BirthCountry>DE</BirthCountry>
      <Residency>DE</Residency>
      <DocumentNumber>A942819</DocumentNumber>
    </Person>
    <Address>
      <Country>EE</Country>
      <StreetNo>Majaka 47-10</StreetNo>
      <CityCounty>Xiao, Neverland</CityCounty>
    </Address>
  </User>
</AccountOpenRequest>

Agency account open request for legal person

<?xml version="1.0" encoding="UTF-8"?>
<AccountOpenRequest>
  <MasterAccount>GB27LHVB04030000003349</MasterAccount>
  <User>
    <Company>
      <Name>UK Ltd Version 2.0</Name>
      <CountryOfOrigin>GB</CountryOfOrigin>
      <TaxResidency>GB</TaxResidency>
      <RegistrationNumber>1849203</RegistrationNumber>
      <Representative>
        <Name>Harry Potter</Name>
        <BirthDate>2001-01-01</BirthDate>
        <Residency>GB</Residency>
      </Representative>
    </Company>
    <Address>
      <Country>GB</Country>
      <StreetNo>Waterloo Bridge 13</StreetNo>
      <CityCounty>London, Cold</CityCounty>
    </Address>
  </User>
</AccountOpenRequest>

Response

Header Message-Response-Type: AGENT_ACCOUNT_OPEN

• agent.account.open.response.xsd
• agent.account.open.common.xsd

Message structure

Agency account open response for private person

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccountOpenResponse>
    <MasterAccount>GB27LHVB04030000003349</MasterAccount>
    <IBAN>GB70LHVB04030400003512</IBAN>
    <AccountNo>04030400003512</AccountNo>
    <User>
        <Person>
          <Name>Donald Duck</Name>
          <BirthDate>1908-11-29</BirthDate>
          <BirthCountry>DE</BirthCountry>
          <Residency>DE</Residency>
          <DocumentNumber>A942819</DocumentNumber>
        </Person>
        <Address>
            <Country>EE</Country>
            <StreetNo>Majaka 47-10</StreetNo>
            <CityCounty>Xiao, Neverland</CityCounty>
        </Address>
    </User>
    <Status>ACTIVE</Status>
</AccountOpenResponse>

Agent account open response for legal person

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccountOpenResponse>
    <MasterAccount>GB27LHVB04030000003349</MasterAccount>
    <IBAN>GB70LHVB04030400003512</IBAN>
    <AccountNo>04030400003512</AccountNo>
    <User>
        <Company>
            <Name>UK Ltd Version 2.0</Name>
            <CountryOfOrigin>GB</CountryOfOrigin>
            <TaxResidency>GB</TaxResidency>
            <RegistrationNumber>1849203</RegistrationNumber>
            <Representative>
                <Name>Harry Potter</Name>
                <BirthDate>2001-01-01</BirthDate>
                <Residency>GB</Residency>
            </Representative>
        </Company>
        <Address>
            <Country>GB</Country>
            <StreetNo>Waterloo Bridge 13</StreetNo>
            <CityCounty>London, Cold</CityCounty>
        </Address>
    </User>
    <Status>ON_HOLD</Status>
</AccountOpenResponse>

Error codes

Error codes are a subject to change.

Agency Account Status Notification

Service is used to update service providers about agent account status changes. Notification messages are created for status changes not initiated directly by user - for example when account with screening match is activated (status changes from ON_HOLD to ACTIVE).

Header Message-Response-Type: AGENT_ACCOUNT_STATUS_NOTIFICATION

Message

• agent.account.status.notification.xsd
• agent.account.open.common.xsd

Message structure

Sample

Agency account status notification for private person

<?xml version="1.0" encoding="UTF-8"?>
<AgentAccountStatusNotification>
  <MasterAccount>GB27LHVB04030000003349</MasterAccount>
  <IBAN>GB70LHVB04030400003512</IBAN>
  <AccountNo>04030400003512</AccountNo>
  <User>
  	<Person>
  	  <Name>Donald Duck</Name>
  	  <BirthDate>1908-11-29</BirthDate>
  	  <BirthCountry>DE</BirthCountry>
  	  <Residency>DE</Residency>
  	  <DocumentNumber>A942819</DocumentNumber>
  	</Person>
  	<Address>
  		<Country>EE</Country>
  		<StreetNo>Majaka 47-10</StreetNo>
  		<CityCounty>Xiao, Neverland</CityCounty>
  	</Address>
  </User>
  <Status>ACTIVE</Status>
  <!--Optional:-->
  <DateActivated>2018-01-01+02:00</DateActivated>
  <!--Optional:-->
  <DateClosed>2018-05-22+03:00</DateClosed>
</AgentAccountStatusNotification>

Legal person

<?xml version="1.0" encoding="UTF-8"?>
<AgentAccountStatusNotification>
  <MasterAccount>GB27LHVB04030000003349</MasterAccount>
  <IBAN>GB70LHVB04030400003512</IBAN>
  <AccountNo>04030400003512</AccountNo>
  <User>
  	<Company>
  		<Name>UK Ltd Version 2.0</Name>
  		<CountryOfOrigin>GB</CountryOfOrigin>
  		<TaxResidency>GB</TaxResidency>
  		<RegistrationNumber>1849203</RegistrationNumber>
  		<Representative>
  			<Name>Harry Potter</Name>
  			<BirthDate>2001-01-01</BirthDate>
  			<Residency>GB</Residency>
  		</Representative>
  	</Company>
  	<Address>
  		<Country>GB</Country>
  		<StreetNo>Waterloo Bridge 13</StreetNo>
  		<CityCounty>London, Cold</CityCounty>
  	</Address>
  </User>
  <Status>ACTIVE</Status>
  <!--Optional:-->
  <DateActivated>2018-01-01+02:00</DateActivated>
  <!--Optional:-->
  <DateClosed>2018-05-22+03:00</DateClosed>  
</AgentAccountStatusNotification>

Merchant Payment Report

Request Merchant Payment Report

POST [base-url]/merchant-report

Request message

Sample

<MerchantReportRequest>
    <Type>CAMT_SETTLEMENT</Type>
    <PeriodStart>2015-12-22</PeriodStart>
    <PeriodEnd>2015-12-22</PeriodEnd>
</MerchantReportRequest>

Response Merchant Payment Report

Message description

Message is used to get an overview about customer (merchant) card payments during the specified period.

Header Message-Response-Type: ACQ_REPORT

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