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

DATECHANGE
24.09.2024New Webhook service! Subscribe to Webhook endpoint and upon a new message, we will notify you via the webhook, enabling you to fetch the message immediately
05.08.2024Pain.002 now provides information when payment has been suspended using StsRsnInf.Rsn.Code = NARR and StsRsnInf.Rsn.AddtlInf = "The payment has been suspended".
Only ISO country codes are now allowed in pain.001 country fields.
All dates used in pain.001 must be later than 01-01-1900.
Creditor name can be 255 characters for payments to LHV accounts. 70 character limit for payments to other banks.
27.06.2024Payment initiation v3 (pain.001.001.03) support is extended until 31.10.2025.
10.06.2024LHV Bank (UK) has moved its API documentation to a new portal: https://docs.lhv.com/connect.
18.03.2024Additional ValueDate tag with DateTime is added to transaction level entry in camt.054.001.02 and camt.053.001.02 messages. In camt.054.001.02 message new tag reflects transaction date with time and offset. In camt.053.001.02 message new tag reflects transaction date and time without offset.
01.02.2024From 01.03.2024 payment scheme TARGET2 can be used then initiated a payment. Postal Address - In case of TARGET2 payment address information is mandatory. Please see updated rules of Postal Address usage. TARGET2 payments can be returned, see https://partners.lhv.ee/en/connect/#initiating-return-payments.
Changes on automatic/manual scheme selection.
01.12.2023Pain.001 transitional period has been extended from 31.01.2024 to 30.06.2024. >>> Not applicable for Payment Service Providers! Please contact your account manager for further details.
05.10.2023Pain.001 transitional period has been extended from 03.07.2023 to 30.06.2024. >>> Not applicable for Payment Service Providers! Please contact your account manager for further details.
12.07.2023Added information for Agency Account Synchronization changes related to LHV UK Bank migration
03.07.2023Breaking change warning for customers operating UK accounts! Added information for LHV UK Bank migration and related changes to Connect
10.05.2023Breaking change warning! Descriptions updated for the upcoming payment message version changes (ISO20022 2019 version released in November 2023).
* pain.001.001.03 will be replaced with pain.001.001.09 (payment initiation)
* pain.008.001.02 will be replaced with pain.008.001.08 (payment collection initiation)
* pain.002.001.03 will be replaced with pain.002.001.10 (payment initiation response)

See timeline and details here: Upcoming transition to new iso messaging standard in november 2023
01.03.2023Added samples of ACSP responses
30.12.2022Added timezone information to communication test.
15.08.2022Added samples for Payment Service Provider payments use cases.
04.08.2022Added samples for FPSPOO (Payments Originated Overseas in UK Faster Payments scheme).
03.05.2022Account Balance service now optionally also contains Payment Limits data. More details and samples below.
29.04.2022Added specification for Payment Collection Services and SEPA Direct Debit. This is a new service currently in pilot and will be significantly improved and updated.
14.03.2022Added new Bulk Delete service for managing API messages - combining it with messages list service now enables even more options for parallel processing.
09.03.2022Added new options for reading your API messages - messages list and number of pending messages services now enable parallel execution and improved performance. More at messaging chapter.
07.03.2022Possible breaking change! We shall start providing additional data for payment pending on manual intervention. This data will be provided in the payment response messages PAIN.002 with PDNG status and additional description. Manual intervention can be triggered by different events like sanctions screening matches or payment data quality issues. Please make sure your integrations can handle these messages.
26.01.2022Added new Bank transaction codes for Indirect Scheme Access payments:
* PMNT / ICDT / FICT - PSP issued credit transfer
* PMNT / RCDT / FICT - PSP received credit transfer
25.01.2022Added manual processing info to Payment Response Messages. This is a new feature to provide information about human intervention in the payment flow - for example sanctions screening matches. Feature is currently piloted and will be rolled out for all customers by 2022.02.28. Possible breaking change depending on customer and integrations solution.
17.12.2021Updated structures and samples for Foreign Exchange services. FX is now fully live and ready to use!
10.12.2021Contracts List service now contains filter for changed date. It can be also used to get recently closed contracts.
01.12.2021Merchant Payment Report will now return errStatement_PeriodInvalid (Data not ready for selected period) error when previous day data calculations are not finished.
24.09.2021Added information about FPSPOO (Payments Originated Overseas in UK Faster Payments scheme). Additional information required for these payments can be provided at the UltimateRemitter block. More details at the XML specification. Also updated the LHV custom pain.001.001.03.xsd payments XML schema file.
Minor changes coming up to Debit Credit Notification camt.054.001.02 messages by the end of September. All messages will contain now empty UltmtDbtr and UltmtCdtr tags. Also bank data in FinInstnId will contain address data in the PstlAdr block. Similar change already appeared in the account stament file previously. This is not a breaking change and is still matching the common XSD schema.
28.07.2021Added improved full samples for different payment schemes and use cases.
22.06.2021Added first specification for Foreign Exchange services.
04.12.2020Added info on SEPA Credit Transfers and Instant Credit Transfers for Indirect Scheme Access.
Agency Account Synchronization allows synchronizing Estonian region IBANs.
Added scheme reject and return codes for SEPA Credit and Instant Transfers inappendix and information about initiating return payments.
01.12.2020Added ClientReference to Virtual IBAN services. It is an optional field that service provider can use for mapping their internal system ID's to Virtual Accounts and also avoid duplicates when opening new accounts.
20.11.2020Several smaller updates and changes will be done to Account Statement. Release is planned to December 2020:
Account statement creation time at CreDtTm will also contain milliseconds. For example:2020-10-01T21:00:00.227
XML declaration will not include encoding="UTF-8" part as it is Java default and does not need to be declared. Document encoding is still UTF-8.
When using DATETIME for statement period and FrTm=0:00:00 - then actual starting balance will be shown instead of 0. Also all statement blocks for all currencies on the account will be included.
05.11.2020Added update functionality for Agent Account Synchronization Request. Added optional Status field to request. DUPLICATE_ACCOUNT and ACCOUNT_EXISTS errors removed.
09.10.2020Added return initiation for UK Faster Payments scheme: Instruction for Debtor Agent inpayment initiation (index 2.85) is used for referencing return payment.
Ignore non-IBAN account numbers for other regions than 'GB' in Agent Account Synchronization Request.
Added rule: debtor name in pain.001.001.03 index 2.19 is mandatory if payment is initiated from indirect agent's existing accounts.
Estonian Banking Association pain.001.001.03 XSD is replaced with custom XSD. See XML Format inpayment initiation.
Added FPS reject code list in appendix, they appear in payment initiation response pain.002 Additional Info (index 3.25).
Added Non-IBAN account identification to payment initiation response pain.002 (index 3.122).
Added information: if not enough funds or daily/monthly limits, payments will be canceled immediately unless otherwise agreed. Payment initiation reject status 'No rights to remitter’s account.' moved to group level.
29.09.2020Now Virtual IBAN data can be modified with a valid reason. More info at Virtual IBAN Modify service.
14.09.2020We are changing the format of transaction reference in payment and account info messages. So far it has also included date information, but will be replaced with a random string of 32 characters. It impacts AcctSvcrRef tags in PAIN.002, CAMT.053 and CAMT.054 messages. Old format example: 202009081020678875-016192782. New format example: D9C8845A4BBAEA11910E00155DBDB777. Please make sure this change does not impact your integration. Change is planned for release on 2020.10.14 (in one month).
26.05.2020Added new optional parameters Filter-Response-Type for selecting messages by service type and Filter-Service-Provider for selecting messages for service provider. See more at messaging.
15.05.2020Added information about Indirect Scheme Access account management services. These are services for Indirect Account management for service providers with a valid Agency agreement. Updated payment initiation debtor account: added Othr.Id for non-IBAN accounts; added agency rule to Dbtr.PstlAdr and added TwnNm tag. Release planned in June 2020.
15.05.2020Added information about Contract Management Services. These services are meant for Service Providers Connect contract management - info services about existing contracts, creation and modification.
19.02.2020Added information about manual payment scheme selection.

Access and Basics

To start using LHV Connect services you need:

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

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

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

Certificates

Following certificates are needed for using LHV Connect services:

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

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

Optional:

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

Environments

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

Live

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

Sandbox

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

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

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

Clients and connection schemes

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

Single clients

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

Service providers and end users using their services

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

In this scheme there are two kinds of clients:

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

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

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

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

Messaging

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

Typical flow of API requests:

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

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

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

Sending requests

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

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

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

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

Retrieving the responses

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

Get next message
GET [base-url]/messages/next

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

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

Samples

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

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

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

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

The response contains the following important headers:

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

When executing the request you can receive following HTTP responses:

  • 200 - there is a message waiting and there should be some content in the response XML
  • 204 - there are no new messages
Get messages list
GET [base-url]/messages  #list of 10 messages by default
GET [base-url]/messages?limit=100  # list of 100 messages

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

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

List of messages is returned in JSON format:

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

Sample:

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

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

GET [base-url]/messages/RES6b9716cbd77441e197383bc3adf132ef
..
GET [base-url]/messages/RES638d6d2b508b4922a61c728d812919fd
..
GET [base-url]/messages/RES08a92e7c2f6a4468b36f49bfc2a749a5
Get number of pending messages
GET [base-url]/messages/count

Use this service to get the number of pending messages.

Sample response:

{
    "count": 36
}

Confirm the successful reading of the response

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

DELETE [base-url]/messages/RES4ab8a01dd7ed4ed792f0605761ae532a

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

Bulk confirm

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

POST [base-url]/messages/delete

Sample body in JSon format:

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

Response body contains the results for all the requests messages.

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

Response sample:

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

Response Codes

CODEDESCRIPTION
503Service UnavailableTechnical error.
403ForbiddenAuthorization or authentication failure. Requested service is not stated in Connect agreement, Connect agreement is not valid or other failure.
500Internal Server ErrorTechnical error.
200OKGET request ok.
202AcceptedPOST request accepted.
429Too many requestsToo many requests in a given amount of time.

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.

INDEXMULT.MESSAGE ELEMENTXML TAGDESCRIPTION
1.0[1..1]Errors<Errors>
1.1[1..n]+Error<Error>
1.2[1..1]++ErrorCode<ErrorCode>For example, see list of Account Statement Request Error Codes.
1.3[1..1]++Description<Description>Description text.
1.4[0..1]++Field<Field>Reference to faulty field.

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

ERROR CODEMESSAGEDESCRIPTION
FORBIDDENCertificate has invalid SERIALNUMBER fieldIf authentication certificate SERIALNUMBER field is not a number
FORBIDDENMissing 'Client-Country' request headerIf request header 'Client-Code' exists but 'Client-Country' header does not
FORBIDDEN'Client-Country' request header value is not in correct format. Length should be 2 characters (i.e. EE)If request header 'Client-Country' length is not 2 characters
FORBIDDENCan't authenticate. No 'Client-Code' header for service providerIf user is service provider or user is using service provider then 'Client-Code' and 'Client-Country' request headers are mandatory
FORBIDDENUser doesn't existIf user identification data was extracted from request but doesn't find such user from Connect system
FORBIDDENUser doesn't have valid contractIf user doesn't have valid contract in active status
FORBIDDENUser doesn't have valid certificate for authenticationIf user contract has no authentication certificate
FORBIDDENUser authentication certificate is different than expectedIf the certificate used for the authentication is different than the certificate indicated in the contract
FORBIDDENCan't create certificate, invalid inputIf user certificate in the contract is in the wrong format and is not readable
FORBIDDENUser authentication certificate is not yet validIf user certificate valid from date is in the future
FORBIDDENUser authentication certificate is expiredIf user certificate valid to date is in the past
FORBIDDENError reading certificate policyIf authentication certificate is issued by SK then it tries to read company policy from certificate and it doesnt find it
FORBIDDENCant read certificate issuer infoIf certificate has invalid issuer field or it doesn't exists
FORBIDDENCertificate file not foundIf SK certificate is used and system is trying to do OCSP request but issuer certificate is not found
FORBIDDENSK OCSP request failedIf SK certificate OCSP request failed for some reason (i.e connection failure)
FORBIDDENSK OCSP service doesn't respondIf SK certificate OCSP response is empty
FORBIDDENCertificate SK OCSP response is not validIf SK certificate OCSP respond that cerficate is not valid
FORBIDDENInvalid certificate subject common nameIf trying to read user identification from certificate common name field (CN) and it fails
FORBIDDENUser has not been granted the requested serviceIf service is not enabled in contract

Language and Code Pages

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

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

For example unstructured payment description submitted in the payment file:

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

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

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

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

Character replacements for all payments

Character(s)Replacement for all receiver BIC countries
\/
] })
[(
_ ~-
` ’'
Ę Ē É ĖE
ę ē é ėe
Ć ČC
ć čc
ĢG
ģg
Į ĪI
į īi
ĶK
ķk
Ļ ŁL
ļ łl
Ń ŅN
ń ņn
[character code 160]space
E
Ą Ā ÅA
æ ą ā åa
Ó Ō ØO
ó ō øo
Ū ŲU
ū ųu
ŚS
ś ßs
Ź ŻZ
ź żz

Additional replacements based on receiver bank BIC country

  • ISO - all countries except for EE and GB
  • EE - Estonia
  • GB - Great Britain
Original Character(s)ReplacementApplies to
{(ISO, EE
;čISO, EE
ÄAISO, GB
äaISO, GB
Õ ÖOISO, GB
õ öoISO, GB
ÜUISO, GB
üuISO, GB
ŠSISO, GB
šsISO, GB
ŽZISO, GB
žzISO, GB

Dates and Time zones

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

FAQ and Tips

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

LHV UK migration and details

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

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

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

Key elements and changes:

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

More details for these are provided below!

Timeline of activities

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

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

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

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

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

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

Connect UK host and access to LHV EE services

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

List of required changes:

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

This also applies to Messages services:

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

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

Changes to API services

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

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

Listing the changes:

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

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

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

Common format for UK datetime values shall be following:

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

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

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

Heartbeat service
  • GET /heartbeat service TimeStamp value will include the current datetime value with timezone offset specific for LHV EE or UK:
-- From UK Host
# Before Migration date by default from LHV EE
<HeartBeatResponse>
    <TimeStamp>2023-07-03T10:36:54.322+03:00</TimeStamp>
</HeartBeatResponse>

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


-- From EE Host
# Timestamp is already today with offset
<HeartBeatResponse>
    <TimeStamp>2023-08-09T11:27:04.626144+03:00</TimeStamp>
</HeartBeatResponse>
Messages service
  • GET /messages service messageCreatedTime value will include the current datetime value with timezone offset specific for LHV EE or UK:
-- from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# All messages include offest information
    ...
        {
            "messageResponseId": "RESd99662d537fa47ff878093b7e6f7bd41",
            "messageRequestId": "REQ85be92ff2b774675b778ffbb13678328",
            "messageResponseType": "ACCOUNT_BALANCE",
            "messageCreatedTime": "2023-09-02T13:48:45.533+03:00",
            "bankCode": "LHVEE"
        }


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

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

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

Payments Initiation

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

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

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

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

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

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

Submitting both EE and UK account payments in a single file

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

  • Payment file shall be processed based on the firstblock and payment account.
  • If the firstblock contains EE accounts these shall be processed, but any UK account payments shall be rejected.
  • If the firstblock contains UK accounts these shall be processed, but any EE account payments shall be rejected.
  • Customers should ensure that EE and UK account payments are submitted in separate requests.
Account Statements
Time formats
-- Responses from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# Only LHV UK messages will include offest information

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

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

-- LHV UK Responses - offset will be included

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

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

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

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

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

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

-- LHV UK Responses - offset will be included

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

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

<Document ... camt.054.001.02.xsd">
  <BkToCstmrDbtCdtNtfctn>
    <GrpHdr>
      <MsgId>324241606</MsgId>
      <CreDtTm>2023-08-07T12:52:33.646843941</CreDtTm>
    </GrpHdr>
    <Ntfctn>
      <Id>324241606GBP</Id>
      <CreDtTm>2023-08-07T12:52:33.646843941</CreDtTm>
Account balance
Time formats
-- Responses from UK Host
# Before Migration date all messages are processed by LHV EE
# After Migration date UK accounts related messages are processed by LHV UK
# Only LHV UK messages will include offest information

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

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

-- LHV UK Responses - offset will be included

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

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

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

Agency Account Synchronization

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

Testing and preparations

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

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

Live Proving

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

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

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

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

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

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

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

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

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

Testing activities in Live

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

Upcoming transition to new ISO messaging standard in November 2025

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

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

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

Summary of changes

pain.001.001.09 and pain.008.001.08

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

pain.002.001.10

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

Timeline for upgrade

Message/elementDateChannelUpcoming change
pain.001.001.0903.07.2023Connect API, Internet BankFirst day when these versions are available to be used.
pain.002.001.10
pain.008.001.08
01.08.2023Connect API, Internet BankFirst day when these versions are available to be used.
Supplementary Data in pain.001.001.0906.07.2023Connect API, Internet BankFirst day when supplementary data is available to be used in pain.001.
Supplementary Data in pain.008.001.0830.09.2023Connect API, Internet BankFirst day when supplementary data is available to be used in pain.008.
pain.002.001.03
pain.001.001.03
pain.008.001.02
31.10.2025Connect API, Internet BankLast day when old message versions can be used.

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.

ServiceDescription and purposeServicesFormats
Generic Services
Communication TestTesting the communication channel
and validity of the connection certificates.
GET /heartbeat
POST /heartbeat
XML
Get messagesGet next message from your inboxGET /messages/nextrp: depends on message
AIS Services
Account StatementGetting an account statement or list
of transactions for a selected period
POST /account-statementXML camt.060.001.03 / camt.053.001.02
Account BalanceGetting account balancesPOST /account-balanceXML camt.060.001.03 / XML camt.052.001.06
Automatic Account StatementAutomatically generated account statement
for a previous day
(only messages)XML camt.053.001.02
Debit Credit NotificationNotification message about single
transactions on account
(only messages)XML camt.054.001.02
PIS Services
Payment InitiationService for Payment initiation. Service is used to initiate return paymentsPOST /paymentXML pain.001.001.03 / pain.002.001.03 (until 31.10.2025)
XML pain.001.001.09 / pain.002.001.10 (from 01.07.2023)
Virtual IBAN Services
Virtual IBAN OpenNew Virtual IBAN openingPOST /viban/openXML
Virtual IBAN BulkBulk opening nameless Virtual IBANsPOST /viban/bulkXML
Virtual IBAN ModifyAdd Virtual IBAN holder data to
nameless Virtual IBANs or modify existing one
POST /viban/modifyXML
Virtual IBAN InfoRequest Virtual IBAN dataPOST /viban/infoXML
Virtual IBAN CloseClose a Virtual IBAN.POST /viban/closeXML
Virtual IBAN Status NotificationNotification message about
Virtual IBAN status changes
(only messages)XML
Indirect Scheme Access
Agency Account SynchronizationSynchronizing existing TPP account numbers with LHV.POST /agent/account/synchronizeXML
Payment Collection Services
Direct Debit InitiationService for Direct Debit initiation.POST /direct-debit/collectionXML pain.008.001.02 / pain.002.001.03 (until 31.10.2025)
XML pain.008.001.08 / pain.002.001.10 (from 01.07.2023)
Foreign Exchange Services
Request FX Trade OfferInitiate new FX trade offer and quotePOST /fx/trade-offerJSON
Confirm FX Trade OfferConfirm the trade offerPOST /fx/trade-offer-confirmationJSON
Merchant Payment Report
Request Merchant Payment ReportGet an overview about customer (merchant) card payments during the specified periodPOST /acq/merchant-reportXML
Response Merchant Payment ReportNotification message about customer (merchant) card payments(only messages)XML camt.054.001.02
Contract Management Services
Request New ContractInitiate new Service Provider
customer contract creation
POST /contractsJSON
Get Contracts ListGet list and information about Service Provider
connected customers
GET /contractsJSON
Webhook subscribeSubscribe to a webhook endpoint and upon a new message, we will notify you via the webhookPOST /notifications/subscribeJSON
Webhook updateFor updating existing (active) webhook subscriptionPUT /notifications/subscriptions/:subscriptionReferenceJSON
Webhook unsubsribeFor unsubscribing from existing webhook subscriptionDELETE /notifications/subscriptions/:subscriptionReferenceJSON
Webhook searchFor searching subscribed (active) webhooksGET /notifications/subscriptionsJSON

Communication Test

Heartbeat service

GET [base-url]/heartbeat

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

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

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

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

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

Sample response

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

GET [base-url]/heartbeat/mq

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

Sample response

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

POST [base-url]/heartbeat

Service for testing your BDOC request.

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

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

Sample

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

Account Reports

Request Account Report

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

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

XML format (camt.060.001.03)

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

Message root

INDEXMESSAGE ELEMENTXML TAG
[1..1]MessageRoot<AcctRptgReq>

Group header

INDEXMULT.MESSAGE ELEMENTXML TAGDESCRIPTION
1.0[1..1]+GroupHeader<GrpHdr>
1.1[1..1]++MessageIdentification<MsgId>Unique message identifier generated by requesting party.
1.2[1..1]++CreationDateTime<CreDtTm>
2.0[1..1]+ReportingRequest<RptgReq>
2.1[0..1]++Identification<Id>
2.2[1..1]++RequestedMessageNameIdentification<ReqdMsgNmId>Supported values: 'camt.053.001.02' BankToCustomerStatement - client request POST https://connect.lhv.eu/account-statement; 'camt.052.001.06' BankToCustomerAccountReport - client request POST https://connect.lhv.eu/account-balance
2.3[1..1]++Account<Acct>
2.3[1..1]+++Identification<Id>
2.3[1..1]++++IBAN<IBAN>IBAN number to which the report request refers. When using Virtual/Agency account services - only master account IBAN must be used here. Virtual/Agency account is only displayed in the account statement report.
2.4[1..1]++AccountOwner<AcctOwnr>
2.4[1..1]+++Party<Pty>Values are ignored.
2.8[1..1]++ReportingPeriod<RptgPrd>
2.9[1..1]+++FromToDate<FrToDt>
2.9[1..1]++++FromDate<FrDt>Account statement from date, ISO date format. FromDate cannot be later than ToDate. For camt.052.001.06 value is ignored and only current day is returned.
2.9[1..1]++++ToDate<ToDt>Account statement to date, ISO date format. For camt.052.001.06 value is ignored and only current day is returned.
2.10[1..1]+++FromToTime<FrToTm>Value is ignored if ReqdBalTp block not added or if ReqdBalTp.CdOrPrtry.Cd.Prtry = DATE. Used when Prtry = DATETIME
2.10[1..1]+++FromTime<FrTm>ISO datetime, inclusive.
2.10[1..1]+++ToTime<ToTm>ISO datetime, exclusive.
2.13[1..1]+++Type<Tp>‘ALLL’.
2.14[0..1]++Requested Balance Type<ReqdBalTp>Provides details on the requested balance reporting.
2.14[1..1]+++Code or Proprietary<CdOrPrtry>
2.14[1..1]++++Code<Cd>Not used
2.14[1..1]++++Proprietary<Prtry>For Account Statement camt.053: 'DATE': return statement based on FromDate and ToDate only; FromTime and ToTime are ignored, 'DATETIME': return statement with FromTime and ToTime support.
For Account Balance PAYMENT_LIMITS will also add Payments Limits info in the response.

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

ERROR CODEDESCRIPTION
errStatement_NoAccessNo access to the account.
errStatement_PeriodLongPeriod is too long.
errStatement_PeriodInvalidFrom date cannot be later than to date.
errStatement_RequestInvalidRequest message fails xsd validation.

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

INDEXMESSAGE ELEMENTXML TAG
[1..1]MessageRoot<BkToCstmrStmt>

Group header

INDEXMULT.MESSAGE ELEMENTXML TAGDESCRIPTION
1.0[1..1]+GroupHeader<GrpHdr>
1.1[1..1]++MessageIdentification<MsgId>Unique message identifier generated by requesting party. Maximum length 35 characters.
1.2[1..1]++CreationDateTime<CreDtTm>Date and time when the account statement message is created at LHV.
1.3[0..1]++MessageRecipient<MsgRcpt>Not used.
1.4[0..1]++MessagePagination<MsgPgntn>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. Then this optional block is used. Current pagination limit is 10k transactions.
1.4[0..1]+++PageNumber<PgNb>Sequence number of current paginated long account statement portion.
1.4[0..1]+++LastPageIndicator<LastPgInd>Indicator if current account statement portion is the last one - true/false.

Statement

INDEXMULT.ORMESSAGE ELEMENTXML TAGDESCRIPTION
2.0[1..n]+Statement<Stmt>
2.1[1..1]++Identification<Id>Unique identification provided by LHV. Identification is generated from the value of GrpHdr.MsgId and the currency for which this Statement block is generated.
2.2[0..1]++ElectronicSequenceNumber<ElctrncSeqNb>Not used.
2.3[0..1]++LegalSequenceNumber<LglSeqNb>Not used.
2.4[1..1]++CreationDateTime<CreDtTm>Date and time when the account statement is generated at LHV.
2.5[1..1]++FromToDate<FrToDt>
[1..1]+++FromDateTime<FrDtTm>Start date of the reporting period.
[1..1]+++ToDateTime<ToDtTm>End date of the reporting period.
2.10[1..1]++Account<Acct>
[1..1]+++Identification<Id>
[1..1]++++IBAN<IBAN>IBAN for which this statement block is generated.
[0..1]+++Currency<Ccy>Account currency for which this statement block is generated.
[0..1]+++Servicer<Svcr>Full information about LHV.
[1..1]++++FinancialInstitutionIdentification<FinInstnId>
[0..1]+++++BIC<BIC>LHVBEE22
[0..1]+++++Name<Nm>LHV Pank
[0..1]+++++PostalAddress<PstlAdr>
[0..1]++++++AddressType<AdrTp>BIZZ
[0..1]++++++StreetName<StrtNm>Tartu mnt
[0..1]++++++BuildingNumber<BldgNb>2
[0..1]++++++PostCode<PstCd>10145
[0..1]++++++TownName<TwnNm>Tallinn
[0..1]++++++CountrySubdivision<CtrySubDvsn>Harjumaa
[0..1]++++++Country<Ctry>EE
2.11[0..1]++RelatedAccount<RltdAcct>Not used.
2.23[1..n]++Balance<Bal>
2.24[1..1]+++Type<Tp>
2.25[1..1]++++CodeOrProprietary<CdOrPrtry>
2.26[1..1]+++++Code<Cd>See the codes in Code Set: Balance.
2.31[0..1]+++CreditLine<CdtLine>Not used.
2.34[1..1]+++Amount<Amt>Balance amount.
2.35[1..1]+++CreditDebitIndicator<CdtDbtInd>See the codes in Code Set: Credit and Debit Code.
2.36[1..1]+++Date<Dt>
[1..1]++++Date<Dt>Balance date
2.43[1..1]++TransactionsSummary<TxsSummry>
2.44[0..1]+++TotalEntries<TtlNtries>Not used.
2.49[1..1]+++TotalCreditEntries<TtlCdtNtries>
2.50[0..1]++++NumberOfEntries<NbOfNtries>Number of credit entries in a given Statement block.
2.51[1..1]++++Sum<Sum>Sum of all credit entries in a given statement block.
2.52[1..1]+++TotalDebitEntries<TtlDbtNtries>
2.53[0..1]++++NumberOfEntries<NbOfNtries>Number of debit ebtries in a given Statement block.
2.54[1..1]++++Sum<Sum>Sum of all debit entries in a given Statement block.
2.76[0..n]++Entry<Ntry>
2.77[0..1]+++EntryReference<NtryRef>Not used.
2.78[1..1]+++Amount<Amt>Transaction amount (may be zero).
2.79[1..1]+++CreditDebitIndicator<CdtDbtInd>See the codes in Code Set: Credit and Debit Code.
2.80[0..1]+++ReversalIndicator<RvslInd>True (1) if credit transaction is return of payment
2.81[1..1]+++Status<Sts>BOOK
2.82[1..1]+++BookingDate<BookgDt>
[1..1]++++Date<Dt>Booking date.
2.83[1..1]+++ValueDate<ValDt>
[1..1]++++DateTime<DtTm>Transaction date with time.
2.84[1..1]+++AccountServicerReference<AcctSvcrRef>Unique payment ID assigned by the bank.
2.91[1..1]+++BankTransactionCode<BkTxCd>
2.92[1..1]++++Domain<Domn>
2.93[1..1]+++++Code<Cd>See the codes in Code Set: Bank Transaction Codes.
2.94[1..1]+++++Family<Fmly>
2.95[1..1]++++++Code<Cd>See the codes in Code Set: Bank Transaction Codes.
2.96[1..1]++++++SubFamilyCode<SubFmlyCd>See the codes in Code Set: Bank Transaction Codes.
2.97[0..1]++++Proprietary<Prtry>
3.21[1..1]+++++Code<Cd>Payment scheme code - Code Set: Payment scheme.
2.101[0..1]+++AdditionalInformationIndicator<AddtlInfInd>Not used.
2.135[1..n]+++EntryDetails<NtryDtls>
2.136[0..1]++++Batch<Btch>Not used.
2.142[0..n]++++TransactionDetails<TxDtls>
2.143[1..1]+++++References<Refs>
2.144[0..1]++++++MessageIdentification<MsgId>Not used.
2.145[0..1]++++++AccountServicerReference<AcctSvcrRef>Unique payment ID assigned by the bank.
2.146[0..1]++++++PaymentInformationIdentification<PmtInfId>Unique identification assigned by a sending party. For outgoing payments reference to the original payment initiation message value PmtInf.PmtInfId.
2.147[0..1]++++++InstructionIdentification<InstrId>Payment order number.
2.148[0..1]++++++EndToEndIdentification<EndToEndId>
2.149[0..1]++++++TransactionIdentification<TxId>Not used.
2.199[0..1]+++++RelatedParties<RltdPties>
2.200[0..1]++++++InitiatingParty<InitgPty>Not used.
2.201[0..1]++++++Debtor<Dbtr>
[0..1]+++++++Name<Nm>Debtor’s name.
[0..1]++++++++Country<Ctry>Debtor’s country ISO code.
[0..7]++++++++AddressLine<AdrLine>Debtor’s address.
[0..1]+++++++Identification<Id>If account statement was requested for Virtual/Agency account master account this tag will be empty for debit transaction.
[1..1]{Or++++++++OrganisationIdentification<OrgId>
[0..1]+++++++++BICOrBEI<BICOrBEI>Debtor’s BIC or BEI.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Debtor’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[0..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++++++BirthDate<BirthDt>Debtor’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Debtor’s city of birth.
[1..1]++++++++++CountryOfBirth<CtryOfBirth>Debtor’s country of birth.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Debtor’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.202[0..1]++++++DebtorAccount<DbtrAcct>If account statement was requested for Virtual/Agency account master account, Virtual/Agency account account number is displayed here for debit transaction.
[1..1]+++++++Identification<Id>
[1..1]{Or++++++++IBAN<IBAN>Debtor’s IBAN.
[1..1]Or}++++++++Other<Othr>
[1..1]+++++++++Identification<Id>Debtor’s bank account number which is not IBAN. For Faster Payments (incoming): UK sort code + account nr (14 characters)
2.203[0..1]++++++UltimateDebtor<UltmtDbtr>
[0..1]+++++++Name<Nm>Ultimate debtor’s name.
[0..1]+++++++Identification<Id>
[1..1]{Or++++++++OrganisationIdentification<OrgId>
[0..1]+++++++++BICOrBEI<BICOrBEI>Ultimate debtor’s BIC or BEI.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Ultimate debtor’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[0..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++++++BirthDate<BirthDt>Ultimate debtor’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Ultimate debtor’s city of birth.
[1..1]++++++++++CountryOfBirth<CtryOfBirth>Ultimate debtor’s country of birth.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Ultimate debtor’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.204[0..1]++++++Creditor<Cdtr>
[0..1]+++++++Name<Nm>Creditor’s name.
[0..1]+++++++PostalAddress<PstlAdr>
[0..1]++++++++Country<Ctry>Creditor’s country ISO code.
[0..1]++++++++AddressLine<AdrLine>Creditor’s address.
[0..1]+++++++Identification<Id>If account statement was requested for Virtual/Agency account master account this tag will be empty for credit transaction
[1..1]{Or++++++++OrganisationIdentification<OrgId>
[0..1]+++++++++BICOrBEI<BICOrBEI>Creditor’s BIC or BEI.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Creditor’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[0..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++++++BirthDate<BirthDt>Creditor’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Creditor’s city of birth.
[1..1]++++++++++CountryOfBirth<CtryOfBirth>Creditor’s country of birth.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Creditor’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.205[0..1]++++++CreditorAccount<CdtrAcct>If account statement was requested for Virtual/Agency account master account, Virtual/Agency account account number is displayed here for credit transaction
[1..1]+++++++Identification<Id>
[0..1]{Or++++++++IBAN<IBAN>Creditor’s IBAN. UK Faster Payments (outgoing) - when also payment request contained IBAN.
[0..1]Or}++++++++Other<Othr>
[1..1]+++++++++Identification<Id>Creditor’s account number which is not IBAN. UK Faster Payments (outgoing) - when also payment request contained sort code + domestic account nr. For Faster Payments (incoming): UK sort code + account nr (14 characters)
2.206[0..1]++++++UltimateCreditor<UltmtCdtr>
[0..1]+++++++Name<Nm>Ultimate creditor’s name.
[0..1]+++++++Identification<Id>
[1..1]{Or++++++++OrganisationIdentification<OrgId>
[0..1]+++++++++BICOrBEI<BICOrBEI>Ultimate creditor’s BIC or BEI.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Ultimate creditor’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[0..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++++++BirthDate<BirthDt>Ultimate creditor’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Ultimate creditor’s city of birth.
[1..1]++++++++++CountryOfBirth<CtryOfBirth>Ultimate creditor’s country of birth.
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Ultimate creditor’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.211[0..1]+++++RelatedAgents<RltdAgts>
2.212[0..1]++++++DebtorAgent<DbtrAgt>
[1..1]+++++++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++++++BIC<BIC>BIC of the debtor’s bank.
[0..1]++++++++Name<Nm>Name of the debtor’s bank.
2.213[0..1]++++++CreditorAgent<CdtrAgt>
[1..1]+++++++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++++++BIC<BIC>BIC of the creditor’s bank.
[0..1]++++++++Name<Nm>Name of the creditor’s bank.
2.214[0..1]++++++IntermediaryAgent1<IntrmyAgt1>Not used.
2.215[0..1]++++++IntermediaryAgent2<IntrmyAgt2>Not used.
2.216[0..1]++++++IntermediaryAgent3<IntrmyAgt3>
[1..1]+++++++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++++++BIC<BIC>BIC of the creditor’s correspondent bank.
[0..1]++++++++Name<Nm>Name of the creditor’s correspondent bank.
2.224[0..1]+++++Purpose<Purp>
2.225[1..1]{Or++++++Code<Cd>See the codes in Code Set: Purpose.
2.226[1..1]Or}++++++Proprietary<Prtry>
2.227[0..10]+++++RelatedRemittanceInformation<RltdRmtInf>Not used.
2.234[0..1]+++++RemittanceInformation<RmtInf>
2.235[0..n]++++++Unstructured<Ustrd>Payment description.
2.236[0..n]++++++Structured<Strd>
2.256[0..n]+++++++CreditorReferenceInformation<CdtrRefInf>
2.257[0..1]++++++++Type<Tp>
2.258[1..1]+++++++++CodeOrProprietary<CdOrPrtry>
2.259[1..1]{Or++++++++++Code<Cd>SCOR
2.260[1..1]Or}++++++++++Proprietary<Prtry>
2.261[0..1]+++++++++Issuer<Issr>
2.262[0..1]++++++++Reference<Ref>Payment reference number.
2.293[0..1]+++++ReturnInformation<RtrInf>Return information.
2.304[0..1]++++++Reason<Rsn>
2.305[1..1]{Or+++++++Code<Cd>NARR if AdditionalInformation is filled.
2.306[1..1]Or}+++++++Proprietary<Prtry>
2.307[0..n]++++++AdditionalInformation<AddtlInf>Used with Reason/Code NARR. For returned payment reference to original payment message pain.001.001.09 PmtInfId value. Additional rows with format CD:NNNNNNNN refer to payment scheme specific return codes.

Sample

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

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

First response message header part:

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

Second and final response message header part:

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

Response Account Balance

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

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


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

Header Message-Response-Type: ACCOUNT_BALANCE

Message structure

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

Message root

INDEXMESSAGE ELEMENTXML TAG
[1..1]MessageRoot<BkToCstmrAcctRpt>

Group header

INDEXMULT.MESSAGE ELEMENTXML TAGDESCRIPTION
1.0[1..1]+GroupHeader<GrpHdr>
1.1[1..1]++MessageIdentification<MsgId>Unique message identifier generated by LHV.
1.2[1..1]++CreationDateTime<CreDtTm>Date and time when the account statement message is created at LHV.
1.3[0..1]++MessageRecipient<MsgRcpt>Not used.
1.4[0..1]++MessagePagination<MsgPgntn>Not used.

Report

INDEXMULT.MESSAGE ELEMENTXML TAGDESCRIPTION
2.0[1..n]+Report<Rpt>Report block is generated per every account and currency.
2.1[1..1]++Identification<Id>Unique identification generated by LHV.
2.4[1..1]++CreationDateTime<CreDtTm>Creation date and time.
2.5[0..1]++FromToDate<FrToDt>Period for what this report is generated.
2.5[1..1]+++FromDateTime<FrDtTm>From date and time in camt.060.001.02 request.
2.5[1..1]+++ToDateTime<ToDtTm>To date and time in camt.060.001.02 request.
2.10[1..1]++Account<Acct>
2.10[1..1]+++Identification<Id>
2.10[1..1]++++IBAN<IBAN>Account number for what this report is generated.
2.10[0..1]+++Currency<Ccy>Currency of this report block.
2.23[0..n]++Balance<Bal>Report has two balances: current booked balance and current available balance.
2.24[1..1]+++Type<Tp>
2.25[1..1]++++CodeOrProprietary<CdOrPrtry>
2.26[0..1]+++++Code<Cd>ITAV for current available balance;
ITBD for interim booked balance.
2.26[0..1]+++++Proprietary<Prtry>PAYMENT_LIMIT_MONTHLY_TOTAL - total Monthly limit;
PAYMENT_LIMIT_MONTHLY_FREE free Monthly limit.
PAYMENT_LIMIT_DAILY_TOTAL - total Daily limit;
PAYMENT_LIMIT_DAILY_FREE free Daily limit.
2.34[1..1]+++Amount<Amt>Balance amount.
2.35[1..1]+++CreditDebitIndicator<CdtDbtInd>See the codes in Code Set: Credit and Debit Code.
2.36[1..1]+++Date<Dt>
2.36[1..1]++++Date<Dt>Date of the balance.
2.76[0..n]++Entry<Ntry>Entry data is not returned.

Sample

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

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

Debit Credit Notification

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

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

Header Message-Response-Type: CREDIT_DEBIT_NOTIFICATION

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

camt.054.001.02.xsd

Message structure

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

Message root

MULT.MESSAGE ELEMENTXML TAG
[1..1]MessageRoot<BkToCstmrDbtCdtNtfctn>

Group header

INDEXMULT.ORMESSAGE ELEMENTXML TAGDESCRIPTION
1.0[1..1]+GroupHeader<GrpHdr>
1.1[1..1]++MessageIdentification<MsgId>Unique message identifier generated by LHV.
1.2[1..1]++CreationDateTime<CreDtTm>Date and time when the notification message is created at LHV.
2.0[1..n]+Notification<Ntfctn>
2.1[1..1]++Identification<Id>Unique notification identifier generated by LHV.
2.4[1..1]++CreationDateTime<CreDtTm>Date and time when the notification is created at LHV.
2.10[1..1]++Account<Acct>
[1..1]+++ Identification<Id>
[1..1]++++IBAN<IBAN>IBAN for which this notification block is generated. When using Virtual/Agency account services - the master account IBAN is used here, and Virtual/Agency account in debitor and creditor blocks.
[1..1]+++Currency<Ccy>Currency for which this notification block is generated.
[0..1]+++Owner<Ownr>Account owner information.
[1..1]++++Name<Nm>Account owner name.
[1..1]++++Identification<Id>Legal customer registry code or private customer personal code.
[1..1]{Or+++++OrganisationIdentification<OrgId>
[1..1]++++++Other<Othr>
[1..1]+++++++Identification<Id>Legal customer registry code.
[1..1]Or}+++++PrivateIdentification<PrvtId>
[1..1]++++++Other<Othr>
[1..1]+++++++Identification<Id>Private customer personal code.
[1..1]+++Servicer<Svcr>
[1..1]++++BIC<BIC>LHVBEE22.
[1..1]++++Name<Nm>LHV Pank.
2.56[1..1]++Entry<Ntry>Transaction level entry.
2.58[1..1]+++Amount<Amt Ccy="AAA">Transaction amount (may be zero).
2.59[1..1]+++CreditDebitIndicator<CdtDbtInd>Code Set: Credit and debit code. Zero amount is considered a credit amount.
2.60[0..1]+++ReversalIndicator<RvslInd>True (1) if credit transaction is return of payment
2.61[1..1]+++Status<Sts>BOOK.
2.62[1..1]+++BookingDate<BookgDt>
[1..1]++++Date<Dt>Transaction date.
2.63[1..1]+++ValueDate<ValDt>
[1..1]++++DateTime<DtTm>Transaction date with time and offset.
2.64[1..1]+++AccountServicerReference<AcctSvcrRef>Unique payment ID assigned by the bank.
2.71[1..1]+++BankTransactionCode<BkTxCd>
2.72[1..1]++++Domain<Domn>
2.73[1..1]+++++Code<Cd>See the codes in Code Set: Bank Transaction Codes.
2.74[1..1]+++++Family<Fmly>
2.75[1..1]++++++Code<Cd>See the codes in Code Set: Bank Transaction Codes.
2.76[1..1]++++++SubFamilyCode<SubFmlyCd>See the codes in Code Set: Bank Transaction Codes.
2.77[0..1]++++Proprietary<Prtry>
3.78[1..1]+++++Code<Cd>Payment scheme code - Code Set: Payment scheme.
2.115[1..n]+++EntryDetails<NtryDtls>
2.122[1..n]++++TransactionDetails<TxDtls>
2.123[1..1]+++++References<Refs>
2.125[0..1]++++++AccountServicerReference<AcctSvcrRef>Unique payment ID assigned by the bank.
2.126[0..1]++++++PaymentInformationIdentification<PmtInfId>Unique identification assigned by a sending party. For outgoing payments reference to the original payment initiation message value PmtInf.PmtInfId.
2.127[0..1]++++++InstructionIdentification<InstrId>Payment order number.
2.128[0..1]++++++EndToEndIdentification<EndToEndId>
2.136[1..1]+++++AmountDetails<AmtDtls>
[1..1]++++++InstructedAmount<InstdAmt>
[1..1]+++++++Amount<Amt Ccy="AAA">Transaction amount (may be zero).
2.179[0..1]+++++RelatedParties<RltdPties>
2.181[0..1]++++++Debtor<Dbtr>Block is included for: credit transactions; debit transactions for Virtual/Agency account master account
[0..1]+++++++Name<Nm>Remitter’s name.
[0..1]+++++++PostalAddress<PstlAdr>
[0..1]++++++++Country<Ctry>Remitter’s country ISO code.
[0..7]++++++++AddressLine<AdrLine>Remitter’s address.
[0..1]+++++++Identification<Id>
[1..1]{Or++++++++OrganisationIdentification<OrgId>
[0..1]{{Or+++++++++BICOrBEI<BICOrBEI>Remitter’s BIC or BEI.
[0..n]Or}}+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Remitter’s identification.
[0..1]++++++++++Issuer<Issr>
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[0..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++++++BirthDate<BirthDt>
[1..1]++++++++++CityOfBirth<CityOfBirth>
[1..1]++++++++++CountryOfBirth<CtryOfBirth>
[0..n]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Remitter’s personal code.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.182[0..1]++++++DebtorAccount<DbtrAcct>Block is included for: credit transactions; debit transactions for Virtual/Agency account master account
+++++++Identification<Id>
[1..1]{Or++++++++IBAN<IBAN>Remitter’s IBAN for credit transaction and Virtual/Agency account for debit transactions.
[1..1]Or}++++++++Other<Othr>
[1..1]+++++++++Identification<Id>Remitter’s bank account number which is not IBAN. For Faster Payments (incoming): UK sort code + account nr (14 characters)
2.183[0..1]++++++UltimateDebtor<UltmtDbtr>
[0..1]+++++++Name<Nm>Ultimate remitter’s name.
[0..1]+++++++Identification<Id>
[0..7]{Or++++++++OrganisationIdentification<OrgId>
[0..1]{{Or+++++++++BICOrBEI<BICOrBEI>Ultimate remitter’s BIC or BEI.
[1..1]Or}}+++++++++Other<Othr>
[0..1]++++++++++Identification<Id>Ultimate remitter’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[1..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[0..1]++++++++++BirthDate<BirthDt>Ultimate remitter’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Ultimate remitter’s city of birth.
[0..1]++++++++++CountryOfBirth<CtryOfBirth>Ultimate remitter’s country of birth.
[1..1]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Ultlimate remitter’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.184[0..1]++++++Creditor<Cdtr>Block is included for: debit transactions; credit transactions for Virtual/Agency account master account
[0..1]+++++++Name<Nm>Creditor’s name.
[0..1]+++++++PostalAddress<PstlAdr>
[0..1]++++++++Country<Ctry>Remitter’s country ISO code.
[0..7]++++++++AddressLine<AdrLine>Remitter’s address.
[0..1]+++++++Identification<Id>
[0..7]{Or++++++++OrganisationIdentification<OrgId>
[0..1]{{Or+++++++++BICOrBEI<BICOrBEI>Creditor’s BIC or BEI.
[1..1]Or}}+++++++++Other<Othr>
[0..1]++++++++++Identification<Id>Creditor’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[1..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[0..1]++++++++++BirthDate<BirthDt>Creditor’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Creditor’s city of birth.
[0..1]++++++++++CountryOfBirth<CtryOfBirth>Creditor’s country of birth.
[1..1]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Creditor’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.185++++++CreditorAccount<CdtrAcct>Block is included for: debit transactions; credit transactions for Virtual/Agency account master account
+++++++Identification<Id>
[1..1]{Or++++++++IBAN<IBAN>Creditor’s IBAN for debit transaction and Virtual/Agency account for credit transactions. UK Faster Payments - used when also payment request contained IBAN.
[1..1]Or}++++++++Other<Othr>
[1..1]+++++++++Identification<Id>Creditor’s account number which is not IBAN. UK Faster Payments (outgoing) - when also payment request contained sort code + domestic account nr. For Faster Payments (incoming): UK sort code + account nr (14 characters)
2.186[0..1]++++++UltimateCreditor<UltmtCdtr>
[0..1]+++++++Name<Nm>Ultimate creditor’s name.
[0..1]+++++++Identification<Id>
[0..7]{Or++++++++OrganisationIdentification<OrgId>
[0..1]{{Or+++++++++BICOrBEI<BICOrBEI>Ultimate creditor’s BIC or BEI.
[1..1]Or}}+++++++++Other<Othr>
[0..1]++++++++++Identification<Id>Ultimate creditor’s identification.
[1..1]Or}++++++++PrivateIdentification<PrvtId>
[1..1]+++++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[0..1]++++++++++BirthDate<BirthDt>Ultimate creditor’s birth date.
[1..1]++++++++++CityOfBirth<CityOfBirth>Ultimate creditor’s city of birth.
[0..1]++++++++++CountryOfBirth<CtryOfBirth>Ultimate creditor’s country of birth.
[1..1]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Ultimate creditor’s identification.
[0..1]++++++++++SchemeName<SchmeNm>
[1..1]+++++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.191[0..1]+++++RelatedAgents<RltdAgts>
2.192[0..1]++++++DebtorAgent<DbtrAgt>
[1..1]+++++++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++++++BIC<BIC>BIC of the remitter’s bank.
[0..1]++++++++Name<Nm>Name of the remitter’s bank.
2.193[0..1]++++++CreditorAgent<CdtrAgt>
[1..1]+++++++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++++++BIC<BIC>BIC of the creditor’s bank.
[0..1]++++++++Name<Nm>Name of the creditor’s bank.
2.204[0..1]+++++Purpose<Purp>
2.205[1..1]{Or++++++Code<Cd>See the codes in Code Set: Purpose.
2.206[1..1]Or}++++++Proprietary<Prtry>
2.214[0..1]+++++RemittanceInformation<RmtInf>
2.215[0..n]++++++Unstructured<Ustrd>Payment description.
2.216[0..n]++++++Structured<Strd>
2.236[0..1]+++++++CreditorReferenceInformation<CdtrRefInf>
2.237[0..1]++++++++Type<Tp>
2.238[1..1]+++++++++CodeOrProprietary<CdOrPrtry>
2.239[1..1]{Or++++++++++Code<Cd>SCOR
2.240[1..1]Or}++++++++++Proprietary<Prtry>
2.241[0..1]+++++++++Issuer<Issr>
2.242[0..1]++++++++Reference<Ref>Payment reference number.
2.273[0..1]+++++ReturnInformation<RtrInf>Return information.
2.284[0..1]++++++Reason<Rsn>
2.285[1..1]{Or+++++++Code<Cd>NARR if AdditionalInformation is filled.
2.286[1..1]Or}+++++++Proprietary<Prtry>
2.287[0..n]++++++AdditionalInformation<AddtlInf>Used with Reason/Code NARR. For returned payment reference to orignal payment message pain.001.001.09 PmtInfId value. Additional rows with format CD:NNNNNNNN refer to payment scheme specific return codes.

Sample

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

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

Payment Initiation

Service for executing payments.

Glossary

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

EEA - European Economic Area country

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

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

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

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

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

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

Payment initiation Request

POST [base-url]/payment

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

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

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

Authentication methods

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

LHV Connect currently supports following options:

Direct Processing

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

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

header Content-Type: application/xml

Pending Payments

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

header Content-Type: application/xml

Signed Payments in DigiDoc Container

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

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

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

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

Payment types and scheme selection

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

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

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

Automatic payment scheme selection

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

Manual payment scheme selection

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

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

Sample:

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

Additional notes:

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

Clearing times and limitations

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

Payment typeCurrencyCreditor bankChargesPriority
European Payment (Instant, SEPA)EURSEPASLEVEXPR
Cross Border Payment (Swift)EEA CurrencyEEASHARHIGH, EXPR
Cross Border Payment (Swift)Non EEA CurrencyEEASHARNORM, HIGH, EXPR
Cross Border Payment (Swift)EEA + Non EEA CurrencyNon EEASHAR, DEBTNORM, HIGH, EXPR

Initiating Return Payments

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

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

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

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

XML format (new pain.001.001.09 version)

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

XML rules

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

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

Message structure

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

Message root

MULT.MESSAGE ELEMENTXML TAG
[1..1]+MessageRoot<CstmrCdtTrfInitn>

Group header

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[1..1]+GroupHeader<GrpHdr>
[1..1]++MessageIdentification<MsgId>
[1..1]++CreationDateTime<CreDtTm>
[1..1]++NumberOfTransactions<NbOfTxs>Number of payments in all Payment Information blocks included in this message. If this number is not correct, the file upload will be cancelled.
[1..1]++ControlSum<CtrlSum>Control sum of all individual amounts for all Payment Information blocks included in this message, irrespective of currencies. If this number is not correct, the file upload will be cancelled.
[1..1]++InitiatingParty<InitgPty>Party initiating the payment to an agent
[0..1]+++Name<Nm>Initiating party name.
[0..1]+++PostalAddress<PstlAdr>See address structure and details here.
[0..1]+++Identification<Id>
{Or++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBic<AnyBIC>Initiating party BIC code.
[0..1]+++++LEI<LEI>LEI code. Not supported, values ignored
[0..n]+++++Other<Othr>Other identifier. Not supported, values ignored
Or}++++PrivateIdentification<PrvtId>Not supported
[0..1]+++CountryOfResidence<CtryOfRes>Initiating party country of residence
[0..1]++ForwardingAgent<FwdgAgt>Financial institution that receives the instruction from the initiating party and forwards it to the next agent in the payment chain for execution.
[1..1]+++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++BICFI<BICFI>Forwarding agent BIC code.
[0..1]++++LEI<LEI>LEI code. Not supported, values ignored
[0..1]++++Other<Othr>Other identifier. Not supported, values ignored
[0..1]++++Name<Nm>Forwarding agent name.
[0..1]++++PostalAddress<PstlAdr>See address structure and details here.

Payment information

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[1..n]+PaymentInformation<PmtInf>
[1..1]++PaymentInformationIdentification<PmtInfId>Uniquely identifies the payment information group within this message.
[1..1]++PaymentMethod<PmtMtd>Only the value TRF (credit transfer) is allowed here. If any other value is entered, it will be ignored.
[0..1]++BatchBooking<BtchBookg>Not used.
[1..1]++NumberOfTransactions<NbOfTxs>Number of payment included in the current Payment Information block. If this number is not correct, the file upload will be cancelled.
[1..1]++ControlSum<CtrlSum>Control sum of all individual amounts in the current Payment Information block, irrespective of currencies. If this number is not correct, the file upload will be cancelled.
[0..1]++PaymentTypeInformation<PmtTpInf>
[0..1]+++InstructionPriority<InstrPrty>
[0..1]+++ServiceLevel<SvcLvl>
[1..1]++++Code<Cd>
[0..1]+++LocalInstrument<LclInstrm>
{Or++++Code<Cd>
Or}++++Proprietary<Prtry>Payment priority information. The value here applies to all payments included in the current Payment Information block. See the supported values in Code Set: Payment Priority.
[0..1]+++CategoryPurpose<CtgyPurp>
[1..1]++++Code<Cd>See the supported values in Code Set: Category Purpose.
[1..1]++Requested Execution Date<ReqdExctnDt><Dt>Date on which the debtor’s account is debited.
[1..1]++Debtor<Dbtr>Party from whose account the amount of payment is to be debited. If a different party’s information is entered, it will be ignored.
[1..1]+++Name<Nm>Debtor’s name. For Virtual IBAN or indirect agent - the holder name (not the master account owner). Debtor name is mandatory if payment is initiated from indirect agent's existing accounts.
[0..1]+++PostalAddress<PstlAdr>See address structure and details here. If payment is initiated with indirect agent's existing accounts, following rule applies: (Town Name and Country) or (Country and Address Line) are required.
[0..1]+++Identification<Id>For Virtual IBAN - do not use
{Or++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBic<AnyBIC>Debtor BIC code.
[0..1]+++++LEI<LEI>Debtor LEI code.
[0..n]+++++Other<Othr>Other identifier.
[1..1]++++++Identification<Id>Organisation’s identification code.
[0..1]++++++SchemeName<SchmeNm>
[1..1]+++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
Or}++++PrivateIdentification<PrvtId>
{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++BirthDate<BirthDt>Debtor’s birth date. Date must be later than 1900-01-01.
[1..1]++++++CityOfBirth<CityOfBirth>Debtor’s city of birth.
[1..1]++++++CountryOfBirth<CtryOfBirth>Debtor’s birth country ISO code.
Or}+++++Other<Othr>
[1..1]++++++Identification<Id>Debtor’s identification code.
[0..1]++++++SchemeName<SchmeNm>
[1..1]+++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
[1..1]++DebtorAccount<DbtrAcct>Debtor’s account. Can be client account where payment amount is debited, Virtual IBAN, or Indirect Agency account (both LHV and client generated accounts).
[1..1]+++Identification<Id>
{Or++++IBAN<IBAN>Debtor’s IBAN or Virtual IBAN.
{Or++++Other<Othr>Debtor's non-IBAN account number (for example, UK account number).
Or}}+++++Identification<Id>Account number.
[0..1]+++Currency<Ccy>Not required to be filled in. The payment will be made in the currency of the payment amount. If there are not enough funds available on the account, a relevant error message will appear.
[1..1]++DebtorAgent<DbtrAgt>Debtor’s bank information. Not supported and ignored
[0..1]++UltimateDebtor<UltmtDbtr>Used for SEPA or Target2 payments. Third party acting as the actual owner of the funds or initiating the payment. If ultimate debtor information is filled in at the Payment Information level, it will apply to all payments included in this block. Usage rule: Only to be used if different from the debtor.
[0..1]+++Name<Nm>Ultimate debtor’s name.
[0..1]+++PostalAddress<PstlAdr>Ultimate debtor's postal address. See address structure and details here.
[0..1]+++Identification<Id>
{Or++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBic<AnyBIC>Ultimate debtor's BIC code.
[0..1]+++++LEI<LEI>Organisation LEI code.
[0..n]+++++Other<Othr>Other identifier.
[1..1]++++++Identification<Id>Organisation’s identification code.
[0..1]++++++SchemeName<SchmeNm>
[1..1]+++++++Code<Cd>See the supported values in Code Set: Organisation Identification
Or}++++PrivateIdentification<PrvtId>
{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++BirthDate<BirthDt>Ultimate debtor’s birth date. Date must be later than 1900-01-01.
[0..1]++++++ProvinceOfBirth<PrvcOfBirth>Ultimate debtor’s province of birth.
[1..1]++++++CityOfBirth<CityOfBirth>Ultimate debtor’s city of birth.
[1..1]++++++CountryOfBirth<CtryOfBirth>Ultimate debtor’s birth country ISO code.
Or}+++++Other<Othr>
[1..1]++++++Identification<Id>Ultimate debtor’s identification code.
[0..1]++++++SchemeName<SchmeNm>
[1..1]+++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
[0..1]+++CountryOfResidence<CtryOfRes>Ultimate debtor’s country of residence.
[0..1]++ChargesBearer<ChrgBr>See the supported values in Code Set: Charges Bearer.
[0..1]++ChargesAccount<ChrgsAcct>LHV does not support charge debiting from other than debtor’s account.
[1..1]+++Identification<Id>
[1..1]++++IBAN<IBAN>
[0..1]+++Currency<Ccy>
[1..n]++CreditTransferTransactionInformation<CdtTrfTxInf>This block contains a set of elements providing information on the payment(s) included in the message.
[1..1]+++PaymentIdentification<PmtId>
[0..1]++++InstructionIdentification<InstrId>Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction.
[1..1]++++EndToEndIdentification<EndToEndId>Unique identification assigned by the initiating party to unumbiguously identify the transaction.
[0..1]++++UETR<UETR>Unique End-to-end Transaction Reference in UUIDv4 format. Details on Swift page
[1..1]+++PaymentTypeInformation<PmtTpInf>Set of elements used to specify the type of payment.
[1..1]++++ServiceLevel<SvcLvl>Agreement of rules according to which the payment must be processed. Pre-agreed customer-to-bank conditions apply.
[1..1]+++++Prtry<Prtry>Specifies a pre-agreed service or level of service between the parties, as a proprietary code. Allowed values: INST, SEPA, TARGET2, ALL - equals as uploaded without interface type. Other values return validation error.
[0..1]++++LocalInstrument<LclInstrm>
{Or+++++Code<Cd>
Or}+++++Proprietary<Prtry>Payment priority information. The value here applies to the payment included in the current Credit Transfer Transaction Information block. See the supported values in Code Set: Payment Priority.
[0..1]++++CategoryPurpose<CtgyPurp>
[1..1]+++++Code<Cd>See the supported values in Code Set: Category Purpose.
[1..1]+++Amount<Amt>
{Or++++InstructedAmount<InstdAmt>Payment amount and the currency ordered by the initiating party. All currencies accepted by the bank for payment services are allowed. If there are not enough funds available on the account in a given currency, a relevant error message will appear.
Or}++++EquivalentAmount<EqvtAmt>Not used.
[0..1]+++ChargeBearer<ChrgBr>See the supported values in Code Set: Charges Bearer.
[0..1]+++UltimateDebtor<UltmtDbtr>Third party acting as the actual owner of the funds or initiating the payment. If ultimate debtor information is filled in at the Payment Information level, it will apply to all payments included in this block. Usage rule: Only to be used if different from the debtor. Transferred to the respective payment scheme only in cases of SEPA Payments, SEPA Instant Payments or Target2).
[0..1]++++Name<Nm>Ultimate debtor’s name.
[0..1]++++PostalAddress<PstlAdr>See address structure and details here Ultimate debtor's postal address.
[0..1]++++Identification<Id>
{Or+++++OrganisationIdentification<OrgId>
[0..1]++++++AnyBic<AnyBIC>Ultimate debtor's BIC code.
[0..1]++++++LEI<LEI>Organisation LEI code.
[0..n]++++++Other<Othr>
[1..1]+++++++Identification<Id>Organisation’s identification code.
[0..1]+++++++SchemeName<SchmeNm>
[1..1]++++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
Or}+++++PrivateIdentification<PrvtId>
{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]+++++++BirthDate<BirthDt>Ultimate debtor’s birth date. Date must be later than 1900-01-01.
[0..1]+++++++ProvinceOfBirth<PrvcOfBirth>
[1..1]+++++++CityOfBirth<CityOfBirth>Ultimate debtor’s city of birth.
[1..1]+++++++CountryOfBirth<CtryOfBirth>Ultimate debtor’s birth country ISO code.
Or}++++++Other<Othr>
[1..1]+++++++Identification<Id>Ultimate debtor’s identification code.
[0..1]+++++++SchemeName<SchmeNm>
[1..1]++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
[0..1]++++CountryOfResidence<CtryOfRes>Ultimate debtor’s country of residence.
[0..1]+++IntermediaryAgent1..3<IntrmyAgt1..3>Ignored. Information about the creditor’s bank’s correspondent bank.
[0..1]+++CreditorAgent<CdtrAgt>Creditor agent’s information is required for SWIFT payments.
[1..1]++++FinancialInstitutionIdentification<FinInstnId>
[0..1]+++++BICFI<BICFI>Creditor’s bank’s BIC.
[0..1]+++++LEI<LEI>LEI code. Not supported, values ignored
[0..n]+++++Othr<Othr>Other identifier. Not supported, values ignored
[0..1]+++++ClearingSystemMemberIdentification<ClrSysMmbId>
[0..1]++++++ClearingSystemIdentification<ClrSysId>
[1..1]+++++++Code<Cd>For the clearing system’s identification code see the External Code Sets spreadsheet on the ISO website.
[1..1]++++++MemberIdentification<MmbId>Creditor’s bank identification in a clearing system.
[0..1]+++++Name<Nm>Creditor's bank name. Usage rule: The name is limited to 70 characters in length. Used when the BIC or the clearing system’s member identification is not known to the initiating party.
[0..1]+++++PostalAddress<PstlAdr>See address structure and details here
[0..1]+++CreditorAgentAccount<CdtrAgtAcct>Creditor’s bank account at its correspondent bank. Not supported, values ignored.
[1..1]+++Creditor<Cdtr>Creditor’s information.
[1..1]++++Name<Nm>Creditor’s name. Maximum length 255 characters for payments to LHV bank accounts or maximum 70 characters for payments to any other bank.
[0..1]++++PostalAddress<PstlAdr>See address structure and details here
[0..1]++++Identification<Id>Creditor’s identification.
{Or+++++OrganisationIdentification<OrgId>
[0..1]++++++AnyBic<AnyBIC>Creditor's BIC code.
[0..1]++++++LEI<LEI>Organisation LEI code.
[0..n]++++++Other<Othr>Other identifier.
[1..1]+++++++Identification<Id>Organisation’s identification code.
[0..1]+++++++SchemeName<SchmeNm>
[1..1]++++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
Or}+++++PrivateIdentification<PrvtId>
{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]+++++++BirthDate<BirthDt>Creditor’s birth date. Date must be later than 1900-01-01.
[1..1]+++++++CityOfBirth<CityOfBirth>Creditor’s city of birth.
[1..1]+++++++CountryOfBirth<CtryOfBirth>Creditor’s birth country ISO code.
Or}++++++Other<Othr>
[1..1]+++++++Identification<Id>Creditor’s identification.
[0..1]+++++++SchemeName<SchmeNm>
[1..1]++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
[1..1]+++CreditorAccount<CdtrAcct>Creditor’s account.
[1..1]++++Identification<Id>
{Or+++++IBAN<IBAN>Creditor’s IBAN.
Or}+++++Other<Othr>
[1..1]++++++Identification<Id>Creditor’s account number.
[0..1]++++++SchemeName<SchmeNm>Ignored
[0..1]+++UltimateCreditor<UltmtCdtr>SEPA specific information. Ultimate creditor is the ultimate creditor of the payment.
[0..1]++++Name<Nm>Ultimate creditor’s name.
[0..1]++++Identification<Id>
{Or+++++OrganisationIdentification<OrgId>
[0..1]++++++AnyBic<AnyBIC>Ultimate creditor's BIC code.
[0..1]++++++LEI<LEI>Organisation LEI code.
[0..1]++++++Other<Othr>Other identifier.
[1..1]+++++++Identification<Id>Ultimate creditor’s organisation identification.
[0..1]+++++++SchemeName<SchmeNm>
[1..1]++++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
Or}+++++PrivateIdentification<PrvtId>
{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]+++++++BirthDate<BirthDt>Ultimate creditor’s birth date. Date must be later than 1900-01-01.
[1..1]+++++++CityOfBirth<CityOfBirth>Ultimate creditor’s city of birth.
[1..1]+++++++CountryOfBirth<CtryOfBirth>Ultimate creditor’s birth country ISO code.
Or}++++++Other<Othr>
[1..1]+++++++Identification<Id>Ultimate creditor’s identification.
[0..1]+++++++SchemeName<SchmeNm>
[1..1]++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
[0..1]+++InstructionForDebtorAgent><InstrForDbtrAgtUsed for referencing return payment for SEPA, Instant and Target2. Format: 'RTRN:00000002:12345678' where RTRN is code for return; 00000002 is Payment Scheme Return Code; 12345678 is Account Servicer Reference of original incoming payment to be returned.
[0..1]+++Purpose<Purp>SEPA specific information. Reason for the payment.
[1..1]++++Code<Cd>See the supported codes in Code Set: Purpose.
[0..10]+++RegulatoryReporting<RgltryRptg>Information about the declaration of payments. Not supported, values ignored.
[0..1]+++RemittanceInformation<RmtInf>Used to enter the payment description (unstructured) and the reference number (structured). It is mandatory to provide one or the other and both can be present. If both structured and unstructured information are filled in, only 140 characters of combined length is accepted.

Reference number (structured) must comply with Estonian reference standard or Creditor reference
[0..1]++++Unstructured<Ustrd>Payment description is entered here. The bank will deliver only the first 140 characters of the remittance information.
[0..1]++++Structured<Strd>
[0..1]+++++CreditorReferenceInformation<CdtrRefInf>
[0..1]++++++Type<Tp>
[1..1]+++++++CodeOrProprietary<CdOrPrtry>
[1..1]++++++++Code<Cd>Only the value SCOR is allowed here. If any other value is entered, it will be ignored.
[0..1]+++++++Issuer<Issr>
[0..1]++++++Reference<Ref>Payment reference number is entered here.

If Debtor´s bank locates in Estonia then reference number must comply with Estonian reference standard or Creditor reference
[0..n]+++Supplementary Data<SplmtryData>See details in supplementary data section.
[0..1]++++Place and Name<PlcAndNm>Field ignored
[1..1]++++Data Envelope<Envlp>
[1..1]+++++Document<Document>
[0..n]++++++Party Data<PartyData>Additional data block
[1..1]+++++++Party Code<Party>Defines which party this data is related to. Possible values: DEBTOR, CREDITOR, ULTIMATE_DEBTOR, ULTIMATE_CREDITOR
[1..1]+++++++Data Key<Key>Additional data element being sent. Possible values: DATE_OF_BIRTH, MCC, PSP_SCENARIO.
[1..1]+++++++Data Value<Value>Additional data element value

Address structure (PostalAddress)

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

  • Debtor address - For Virtual IBAN or agency banking account - the holder country
  • If creditor´s bank locates outside EEA address information is mandatory from 31.10.2025. The rule applies to all parties (debtor, ultimate debtor, creditor etc).
  • If creditor´s bank locates in EEA but the currency is not official currency in any EEA country (for example USD) - address information is mandatory from 31.10.2025. The rule applies to all parties (debtor, ultimate debtor, creditor etc).
  • If payment is processed as TARGET2 (See https://partners.lhv.ee/en/connect/#code-set-payment-scheme) - address information is mandatory from 01.03.2024. The rule applies to all parties (debtor, ultimate debtor, creditor etc).
MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[0..1]Department<Dept>
[0..1]Sub-department name<SubDebt>
[0..1]Street name<StrtNm>
[0..1]Building number<BldgNb>
[0..1]Building name<BldgNm>
[0..1]Floor number<Flr>
[0..1]Post box<PstBx>
[0..1]Room name<Room>
[0..1]Postal code<PstCd>
[0..1]Town name<TwnNm>
[0..1]Town location name<TwnLctnNm>
[0..1]District name<DstrctNm>
[0..1]Country sub-division<CtrySubDvsn>
[0..1]ISO 2 letter country code<Ctry>
[0..2]Address line<AdrLine>

Supplementary data

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

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

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

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

Supplementary data includes additional data elements defined in 3 fields.

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

Supllementary data key's:

KeyValue/formatUsage description
DATE_OF_BIRTHyyyy-mm-dd (date)Must be filled for if there is no information about the party's city of birth or country and therefore it is not possible to add complete data under the message element date and place of birth (DateAndPlaceOfBirth). Date must be later than 1900-01-01.
MCCnnnn (4 digit number)MCC code is used to classify a business by the types of goods or services it provides. ISO 18245 is an ISO standard concerning the assignment of Merchant Category Codes (MCC) in retail financial services.
Allowed values: List of Merchant Category Codes (https://classification.codes/classifications/industry/mcc/)
PSP_SCENARIOstringFixed value:
"COMBINED_PAYMENT" - Two or more payments are combined into a single payment.

pain.001 supplementary data example:

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

XML format (OLD pain.001.001.03 version)

This format is usable until 31.11.2025.

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

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

XML rules

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

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

Message structure

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

Message root

MULT.MESSAGE ELEMENTXML TAG
[1..1]+MessageRoot<CstmrCdtTrfInitn>

Group header

INDEXMULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
1.0[1..1]+GroupHeader<GrpHdr>
1.1[1..1]++MessageIdentification<MsgId>
1.2[1..1]++CreationDateTime<CreDtTm>
1.6[1..1]++NumberOfTransactions<NbOfTxs>Number of payments in all Payment Information blocks included in this message. If this number is not correct, the file upload will be cancelled.
1.7[1..1]++ControlSum<CtrlSum>Control sum of all individual amounts for all Payment Information blocks included in this message, irrespective of currencies. If this number is not correct, the file upload will be cancelled.
1.8[1..1]++PaymentTypeInformation<PmtTpInf>Set of elements used to specify the type of payment.
1.8[1..1]+++ServiceLevel<SvcLvl>Agreement of rules according to which the payment must be processed. Pre-agreed customer-to-bank conditions apply.
1.8[1..1]++++Prtry<Prtry>Specifies a pre-agreed service or level of service between the parties, as a proprietary code. Allowed values: INST, SEPA, FAST, ALL - equals as uploaded without interface type. Other values return validation error.
1.8[1..1]++InitiatingParty<InitgPty>Party initiating the payment to an agent. In the payment context, this can either be the debtor or a party that initiates the payment on behalf of the debtor or creditor.
1.8[0..1]+++Name<Nm>Initiating party name.
1.8[0..1]+++PostalAddress<PstlAdr>
1.8[0..1]++++TownName<TwnNm>Initiating party address town.
1.8[0..1]++++Country<Ctry>Initiating party address country ISO code.
1.8[0..1]+++Identification<Id>
1.8{Or++++OrganisationIdentification<OrgId>
1.8{{Or+++++BICOrBEI<BICOrBEI>Initiating party BIC code.
1.8Or}}+++++Other<Othr>
1.8[1..1]++++++Identification<Id>
1.8[0..1]++++++SchemeName<SchmeNm>
1.8[1..1]+++++++Code<Cd>
1.8Or}++++PrivateIdentification<PrvtId>
1.8{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
1.8[1..1]++++++BirthDate<BirthDt>Date must be later than 1900-01-01.
1.8[1..1]++++++CityOfBirth<CityOfBirth>
1.8[1..1]++++++CountryOfBirth<CtryOfBirth>
1.8Or}+++++Other<Othr>
1.8[1..1]++++++Identification<Id>
1.8[0..1]++++++SchemeName<SchmeNm>
1.8{Or+++++++Code<Cd>
1.8Or}+++++++Proprietary<Prtry>
1.8[0..1]+++CountryOfResidence<CtryOfRes>Initiating party country of residence
1.9[0..1]++ForwardingAgent<FwdgAgt>Financial institution that receives the instruction from the initiating party and forwards it to the next agent in the payment chain for execution.
1.9[1..1]+++FinancialInstitutionIdentification<FinInstnId>
1.9[0..1]++++BIC<BIC>Forwarding agent BIC code.
1.9[0..1]++++Name<Nm>Forwarding agent name.
1.9[0..1]++++PostalAddress<PstlAdr>
1.9[0..1]+++++TownName<TwnNm>Forwarding agent address town.
1.9[0..1]+++++Country<Ctry>Forwarding agent address country ISO code.

Payment information

INDEXMULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
2.0[1..n]+PaymentInformation<PmtInf>
2.1[1..1]++PaymentInformationIdentification<PmtInfId>Uniquely identifies the payment information group within this message.
2.2[1..1]++PaymentMethod<PmtMtd>Only the value TRF (credit transfer) is allowed here. If any other value is entered, it will be ignored.
2.3[0..1]++BatchBooking<BtchBookg>Not used.
2.4[1..1]++NumberOfTransactions<NbOfTxs>Number of payment included in the current Payment Information block. If this number is not correct, the file upload will be cancelled.
2.5[1..1]++ControlSum<CtrlSum>Control sum of all individual amounts in the current Payment Information block, irrespective of currencies. If this number is not correct, the file upload will be cancelled.
2.6[0..1]++PaymentTypeInformation<PmtTpInf>
2.7[0..1]+++InstructionPriority<InstrPrty>
2.8[0..1]+++ServiceLevel<SvcLvl>
2.9[1..1]++++Code<Cd>
2.11[0..1]+++LocalInstrument<LclInstrm>
2.12{Or++++Code<Cd>
2.13Or}++++Proprietary<Prtry>Payment priority information. The value here applies to all payments included in the current Payment Information block. See the supported values in Code Set: Payment Priority.
2.14[0..1]+++CategoryPurpose<CtgyPurp>
2.15[1..1]++++Code<Cd>See the supported values in Code Set: Category Purpose.
2.17[1..1]++Requested Execution Date<ReqdExctnDt><Dt>Date on which the debtor’s account is debited.
2.19[1..1]++Debtor<Dbtr>Party from whose account the amount of payment is to be debited. If a different party’s information is entered, it will be ignored.
2.19[1..1]+++Name<Nm>Debtor’s name. For Virtual IBAN or indirect agent - the holder name (not the master account owner). Debtor name is mandatory if payment is initiated from indirect agent's existing accounts.
2.19[0..1]+++PostalAddress<PstlAdr>If payment is initiated with indirect agent's existing accounts, following rule applies: (Town Name and Country) or (Country and Address Line) are required.
2.19[0..1]++++TownName<TwnNm>See rule in PostalAddress.
2.19[0..1]++++Country<Ctry>Debtor’s country ISO code. For agency banking account - the holder country. See rule in PostalAddress.
2.19[0..2]++++AddressLine<AdrLine>Debtor’s address. For agency banking account - the holder address. See rule in PostalAddress.
2.19[0..1]+++Identification<Id>For Virtual IBAN - do not use
2.19{Or++++OrganisationIdentification<OrgId>
2.19{{Or+++++BICOrBEI<BICOrBEI>Debtor’s BIC or BEI code.
2.19Or}}+++++Other<Othr>
2.19[1..1]++++++Identification<Id>Organisation’s identification code.
2.19[0..1]++++++SchemeName<SchmeNm>
2.19[1..1]+++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
2.19Or}++++PrivateIdentification<PrvtId>
2.19{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
2.19[1..1]++++++BirthDate<BirthDt>Debtor’s birth date. Date must be later than 1900-01-01.
2.19[1..1]++++++CityOfBirth<CityOfBirth>Debtor’s city of birth.
2.19[1..1]++++++CountryOfBirth<CtryOfBirth>Debtor’s birth country ISO code.
2.19Or}+++++Other<Othr>
2.19[1..1]++++++Identification<Id>Debtor’s identification code.
2.19[0..1]++++++SchemeName<SchmeNm>
2.19[1..1]+++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.20[1..1]++DebtorAccount<DbtrAcct>Debtor’s account. Can be client account where payment amount is debited, Virtual IBAN, or Indirect Agency account (both LHV and client generated accounts).
2.20[1..1]+++Identification<Id>
2.20{Or++++IBAN<IBAN>Debtor’s IBAN or Virtual IBAN.
2.20{Or++++Other<Othr>Debtor's non-IBAN account number (for example, UK account number).
2.20Or}}+++++Identification<Id>Account number.
2.20[0..1]+++Currency<Ccy>Not required to be filled in. The payment will be made in the currency of the payment amount. If there are not enough funds available on the account, a relevant error message will appear.
2.21[1..1]++ DebtorAgent<DbtrAgt>Debtor’s bank information.
2.21[1..1]+++FinancialInstitutionIdentification<FinInstnId>
2.21[1..1]++++BIC<BIC>If the LHV BIC is faulty or missing, it will be replaced with the correct code.
2.23[0..1]++UltimateDebtor<UltmtDbtr>Used for SEPA payments or Faster Payments Payments Originated Overseas (FPSPOO). Third party acting as the actual owner of the funds or initiating the payment. If ultimate debtor information is filled in at the Payment Information level, it will apply to all payments included in this block. Usage rule: Only to be used if different from the creditor.
2.23[0..1]+++Name<Nm>Ultimate debtor’s name.
2.23[0..1]+++PostalAddress<PstlAdr>Ultimate debtor's postal address. In case of FPSPOO, either ultimate debtor town name and country, or country and address line is mandatory.
2.23[0..1]++++TownName<TwnNm>Ultimate debtor's postal address town. In case of FPSPOO and town name is filled, then country must be filled.
2.23[0..1]++++Country<Ctry>Ultimate debtor's address country ISO code. In case of FPSPOO, country is mandatory to fill with either town name or address line.
2.23[0..2]++++AddressLine<AdrLine>Ultimate debtor’s full postal address (street/road, number of house, town up to 140 characters). In case of FPSPOO and address line is filled, country must be filled.
2.23[0..1]+++Identification<Id>
2.23{Or++++OrganisationIdentification<OrgId>
2.23{{Or+++++BICOrBEI<BICOrBEI>Ultimate debtor’s BIC or BEI code. BIC is mandatory in case of FPSPOO - must be owned by the institution which provides the account to the Ultimate debtor and must be a non GB BIC.
2.23Or}}+++++Other<Othr>
2.23[1..1]++++++Identification<Id>Organisation’s identification code. Mandatory in case of FPSPOO - referring to Ultimate debtor’s account number and can be in IBAN or in other format.
2.23[0..1]++++++SchemeName<SchmeNm>
2.23[1..1]+++++++Code<Cd>See the supported values in Code Set: Organisation Identification
2.23Or}++++PrivateIdentification<PrvtId>
2.23{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
2.23[1..1]++++++BirthDate<BirthDt>Ultimate debtor’s birth date. Date must be later than 1900-01-01.
2.23[0..1]++++++ProvinceOfBirth<PrvcOfBirth>Ultimate debtor’s province of birth.
2.23[1..1]++++++CityOfBirth<CityOfBirth>Ultimate debtor’s city of birth.
2.23[1..1]++++++CountryOfBirth<CtryOfBirth>Ultimate debtor’s birth country ISO code.
2.23Or}+++++Other<Othr>
2.23[1..1]++++++Identification<Id>Ultimate debtor’s identification code.
2.23[0..1]++++++SchemeName<SchmeNm>
2.23[1..1]+++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.23[0..1]+++CountryOfResidence<CtryOfRes>Ultimate debtor’s country of residence.
2.24[0..1]++ChargesBearer<ChrgBr>See the supported values in Code Set: Charges Bearer.
2.25[0..1]++ChargesAccount<ChrgsAcct>LHV does not support charge debiting from other than debtor’s account.
2.25[1..1]+++Identification<Id>
2.25[1..1]++++IBAN<IBAN>
2.25[0..1]+++Currency<Ccy>
2.27[1..n]++CreditTransferTransactionInformation<CdtTrfTxInf>This block contains a set of elements providing information on the payment(s) included in the message.
2.28[1..1]+++PaymentIdentification<PmtId>
2.29[0..1]++++InstructionIdentification<InstrId>Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction.
2.30[1..1]++++EndToEndIdentification<EndToEndId>Unique identification assigned by the initiating party to unumbiguously identify the transaction.
1.8[1..1]+++PaymentTypeInformation<PmtTpInf>Set of elements used to specify the type of payment.
1.8[1..1]++++ServiceLevel<SvcLvl>Agreement of rules according to which the payment must be processed. Pre-agreed customer-to-bank conditions apply.
1.8[1..1]+++++Prtry<Prtry>Specifies a pre-agreed service or level of service between the parties, as a proprietary code. Allowed values: INST, SEPA, FAST, ALL - equals as uploaded without interface type. Other values return validation error.
2.36[0..1]++++LocalInstrument<LclInstrm>
2.37{Or+++++Code<Cd>
2.38Or}+++++Proprietary<Prtry>Payment priority information. The value here applies to the payment included in the current Credit Transfer Transaction Information block. See the supported values in Code Set: Payment Priority.
2.39[0..1]++++CategoryPurpose<CtgyPurp>
2.40[1..1]+++++Code<Cd>See the supported values in Code Set: Category Purpose.
2.42[1..1]+++Amount<Amt>
2.43{Or++++InstructedAmount<InstdAmt>Payment amount and the currency ordered by the initiating party. All currencies accepted by the bank for payment services are allowed. If there are not enough funds available on the account in a given currency, a relevant error message will appear.
2.44Or}++++EquivalentAmount<EqvtAmt>Not used.
2.51[0..1]+++ChargeBearer<ChrgBr>See the supported values in Code Set: Charges Bearer.
2.70[0..1]+++UltimateDebtor<UltmtDbtr>Used for SEPA payments or Faster Payments Payments Originated Overseas (FPSPOO). Third party acting as the actual owner of the funds or initiating the payment. If ultimate debtor information is filled in at the Credit Transfer Transaction Information level, it will apply only to the current payment. Usage rule: Only to be used if different from the debtor.
2.70[0..1]++++Name<Nm>Ultimate debtor’s name. Mandatory in case of FPSPOO.
2.70[0..1]++++PostalAddress<PstlAdr>Ultimate debtor's postal address. In case of FPSPOO, either ultimate debtor town name and country, or country and address line is mandatory.
2.70[0..1]+++++TwnNm<TwnNm>Ultimate debtor's postal address town. In case of FPSPOO and town name is filled, then country must be filled.
2.70[0..1]+++++Ctry<Ctry>Ultimate debtor's address country ISO code. In case of FPSPOO, country is mandatory to fill with either town name or address line.
2.70[0..2]+++++AdrLine<AdrLine>Ultimate debtor’s full postal address (street/road, number of house, town up to 140 characters). In case of FPSPOO and address line is filled, country must be filled.
2.70[0..1]++++Identification<Id>
2.70{Or+++++OrganisationIdentification<OrgId>
2.70{{Or++++++BICOrBEI<BICOrBEI>Ultimate debtor’s BIC or BEI code. BIC is mandatory in case of FPSPOO - must be owned by the institution which provides the account to the Ultimate debtor and must be a non GB BIC.
2.70Or}}++++++Other<Othr>
2.70[1..1]+++++++Identification<Id>Organisation’s identification code. Mandatory in case of FPSPOO - referring to Ultimate debtor’s account number and can be in IBAN or in other format.
2.70[0..1]+++++++SchemeName<SchmeNm>
2.70[1..1]++++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
2.70Or}+++++PrivateIdentification<PrvtId>
2.70{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
2.70[1..1]+++++++BirthDate<BirthDt>Ultimate debtor’s birth date. Date must be later than 1900-01-01.
2.70[0..1]+++++++ProvinceOfBirth<PrvcOfBirth>
2.70[1..1]+++++++CityOfBirth<CityOfBirth>Ultimate debtor’s city of birth.
2.70[1..1]+++++++CountryOfBirth<CtryOfBirth>Ultimate debtor’s birth country ISO code.
2.70Or}++++++Other<Othr>
2.70[1..1]+++++++Identification<Id>Ultimate debtor’s identification code.
2.70[0..1]+++++++SchemeName<SchmeNm>
2.70[1..1]++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.70[0..1]++++CountryOfResidence<CtryOfRes>Ultimate debtor’s country of residence.
2.71[0..1]+++IntermediaryAgent1<IntrmyAgt1>Information about the creditor’s bank’s correspondent bank. Used for foreign payments.
2.71[1..1]++++FinancialInstitutionIdentification<FinInstnId>
2.71[0..1]+++++BIC<BIC>Bank’s BIC code.
2.71[0..1]+++++ClearingSystemMemberIdentification<ClrSysMmbId>
2.71[0..1]++++++ClearingSystemIdentification<ClrSysId>
2.71[1..1]+++++++Code<Cd>For the clearing system’s identification code see the External Code Sets spreadsheet on the ISO website.
2.71[1..1]++++++MemberIdentification<MmbId>Identification of the creditor's bank's correspondent bank in a clearing system.
2.71[0..1]+++++Name<Nm>Name of the creditor’s bank’s correspondent bank. Used when the BIC or the clearing system’s member identification is not known to the initiating party.
2.71[0..1]+++++PostalAddress<PstlAdr>
2.71[0..1]++++++Country<Ctry>Country ISO code of the creditor’s bank’s correspondent bank.
2.71[0..2]++++++AddressLine<AdrLine>Country address of the creditor’s bank’s correspondent bank.
2.72[0..1]+++IntermediaryAgent1Account<IntrmyAgt1Acct>Not used.
2.72[1..1]++++Identification<Id>
2.72{Or+++++IBAN<IBAN>
2.72Or}+++++Other<Othr>
2.72[1..1]++++++Identification<Id>
2.77[0..1]+++CreditorAgent<CdtrAgt>Creditor agent’s information is required for SWIFT payments.
2.77[1..1]++++FinancialInstitutionIdentification<FinInstnId>
2.77[0..1]+++++BIC<BIC>Creditor’s bank’s BIC.
2.77[0..1]+++++ClearingSystemMemberIdentification<ClrSysMmbId>
2.77[0..1]++++++ClearingSystemIdentification<ClrSysId>
2.77[1..1]+++++++Code<Cd>For the clearing system’s identification code see the External Code Sets spreadsheet on the ISO website. Use GBDSC when using UK sort code and domestic account nr separately.
2.77[1..1]++++++MemberIdentification<MmbId>Creditor’s bank identification in a clearing system. Use UK sort code when using UK sort code and domestic account nr separately.
2.77[0..1]+++++Name<Nm>Creditor's bank name. Usage rule: The name is limited to 70 characters in length. Used when the BIC or the clearing system’s member identification is not known to the initiating party.
2.77[0..1]+++++PostalAddress<PstlAdr>
2.77[0..1]++++++Country<Ctry>Creditor’s bank’s country ISO code.
2.77[0..2]++++++AddressLine<AdrLine>Creditor’s bank’s address.
2.78[0..1]+++CreditorAgentAccount<CdtrAgt>
2.78[1..1]++++Identification<Id>
2.78{Or+++++IBAN<IBAN>
2.78Or}+++++Other<Othr>
2.78[1..1]++++++Identification<Id>
2.79[1..1]+++Creditor<Cdtr>Creditor’s information.
2.79[1..1]++++Name<Nm>Creditor’s name.
2.79[0..1]++++PostalAddress<PstlAdr>Creditor’s address.
2.79[0..1]+++++Country<Ctry>
2.79[0..2]+++++AddressLine<AdrLine>
2.79[0..1]++++Identification<Id>Creditor’s identification.
2.79{Or+++++OrganisationIdentification<OrgId>
2.79{{Or++++++BICOrBEI<BICOrBEI>Creditor’s BIC or BEI code.
2.79Or}}++++++Other<Othr>
2.79[1..1]+++++++Identification<Id>Organisation’s identification code.
2.79[0..1]+++++++SchemeName<SchmeNm>
2.791..1++++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
2.79Or}+++++PrivateIdentification<PrvtId>
2.79{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
2.79[1..1]+++++++BirthDate<BirthDt>Creditor’s birth date. Date must be later than 1900-01-01.
2.79[1..1]+++++++CityOfBirth<CityOfBirth>Creditor’s city of birth.
2.79[1..1]+++++++CountryOfBirth<CtryOfBirth>Creditor’s birth country ISO code.
2.79Or}++++++Other<Othr>
2.79[1..1]+++++++Identification<Id>Creditor’s identification.
2.79[0..1]+++++++SchemeName<SchmeNm>
2.79[1..1]++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.80[1..1]+++CreditorAccount<CdtrAcct>Creditor’s account.
2.80[1..1]++++Identification<Id>
2.80{Or+++++IBAN<IBAN>Creditor’s IBAN. Omit for Faster Payments when using UK domestic account nr.
2.80Or}+++++Other<Othr>
2.80[1..1]++++++Identification<Id>Creditor’s account number. Use for domestic UK account nr - separate from sort code (8 char) or concatenated (14 char)
2.80[0..1]++++++SchemeName<SchmeNm>
2.80[1..1]+++++++Code<Cd>Use BBAN when using concatenated UK domestic accountr nr (14 characters), omit when using UK account nr and UK sort code separately.
2.81[0..1]+++UltimateCreditor<UltmtCdtr>SEPA specific information. Ultimate creditor is the ultimate creditor of the payment.
2.81[0..1]++++Name<Nm>Ultimate creditor’s name.
2.81[0..1]++++Identification<Id>
2.81{Or+++++OrganisationIdentification<OrgId>
2.81{{Or++++++BICOOrBEI<BICOrBEI>Ultimate creditor’s BIC or BEI.
2.81Or}}++++++Other<Othr>
2.81[1..1]+++++++Identification<Id>Ultimate creditor’s organisation identification.
2.81[0..1]+++++++SchemeName<SchmeNm>
2.81[1..1]++++++++Code<Cd>See the supported values in Code Set: Organisation Identification.
2.81Or}+++++PrivateIdentification<PrvtId>
2.81{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
2.81[1..1]+++++++BirthDate<BirthDt>Ultimate creditor’s birth date. Date must be later than 1900-01-01.
2.81[1..1]+++++++CityOfBirth<CityOfBirth>Ultimate creditor’s city of birth.
2.81[1..1]+++++++CountryOfBirth<CtryOfBirth>Ultimate creditor’s birth country ISO code.
2.81Or}++++++Other<Othr>
2.81[1..1]+++++++Identification<Id>Ultimate creditor’s identification.
2.81[0..1]+++++++SchemeName<SchmeNm>
2.81[1..1]++++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
2.85[0..1]+++InstructionForDebtorAgent><InstrForDbtrAgtUsed for referencing return payment for FPS or SEPA (Inst). Format: 'RTRN:00000002:12345678' where RTRN is code for return; 00000002 is Payment Scheme Return Code; 12345678 is Account Servicer Reference of original incoming payment to be returned.
2.86[0..1]+++Purpose<Purp>SEPA specific information. Reason for the payment.
2.87[1..1]++++Code<Cd>See the supported codes in Code Set: Purpose.
2.89[0..10]+++RegulatoryReporting<RgltryRptg>Information about the declaration of payments.
2.89[0..1]++++Authority<Authrty>
2.89[0..1]+++++Country<Ctry>
2.89[0..n]++++Details<Dtls>
2.89[0..1]+++++Type<Tp>
2.89[0..1]+++++Country<Ctry>
2.89[0..1]+++++Code<Cd>
2.89[0..1]+++++Information<Inf>Specification of the balance of payment code 900.
2.98[0..1]+++RemittanceInformation<RmtInf>Used to enter the payment description (unstructured) and the reference number (structured). It is mandatory to provide one or the other. If both structured and unstructured information is filled in, the creditor reference under the structured information will be lifted to the unstructured information tag in accordance with the EACT standard for unstructured remittance information formatting rules. If the remittance information will, as a result, be longer than 140 characters, the bank will deliver only the first 140 characters of the remittance information. Reference number (structured) must comply with Estonian reference standard or Creditor reference
2.99[0..1]++++Unstructured<Ustrd>Payment description is entered here.
2.100[0..1]++++Structured<Strd>
2.120[0..1]+++++CreditorReferenceInformation<CdtrRefInf>
2.121[0..1]++++++Type<Tp>
2.122[1..1]+++++++CodeOrProprietary<CdOrPrtry>
2.123[1..1]++++++++Code<Cd>Only the value SCOR is allowed here. If any other value is entered, it will be ignored.
2.125[0..1]+++++++Issuer<Issr>
2.126[0..1]++++++Reference<Ref>Payment reference number is entered here. Mandatory for FPS - text value up to 18 symbols long.

Samples

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

CaseNotes and samples
SEPA Instant paymentSEPA Instant payment from EE LHV account to external EE account. With Structured Reference.
- Payment request
- Payment response - ACSP status
SEPA paymentSEPA Instant payment from EE LHV account to external EU account. With Payment Scheme Selection.
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Internal paymentInternal payment from one LHV account to another.
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification - outgoing payment
- Debit Credit Notification - incoming payment
SWIFT payment (IBAN)SWIFT payment to foreign account in IBAN format.
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
SWIFT payment (local format)SWIFT payment to foreign account in local non-IBAN format (BBAN - Basic Bank Account Number)
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
- Debit Credit Notification - payment fee
Bulk paymentMultiple payments in one file - three payments in one PmtInf block. Different payment schemes.
- Payment request
- Payment response 1 - group status for all included payments
- Payment response 2 - additional updates
- Debit Credit Notification - one of the payments
- Debit Credit Notification - one of the payments
VIBAN payment - SEPA InstantPayment from Virtual Account (VIBAN) to external account in SEPA scheme.
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
- Account Statement request
- Account Statement response
Manual reviewPayment is in manual review - PDNG status due to sanctions screening match.
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - PDNG status
PSP Payment use casesDifferent use cases for Payment Service Provider payments and details of party relationships.
Use case 1: PSP’s PaymentPSP initiates his own payments from his own account opened with LHV. More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 2: PSP’s Client PaymentPSP1 initiates the payments of the end customer (PSP1’s client). More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 3: Level2 PSP Client PaymentPSP2 initiates the payments of the end customer (PSP2’s clients) via PSP1. In this case there is another Payment Service Provider (PSP2) between the PSP1 and the end customer (PSP2’s client). More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 4: VIBAN PaymentPSP1 initiates the payments of the VIBAN owners (PSP1’s clients). VIBAN must be in an active status to initiate the payment. More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 5: Level2 VIBAN PaymentPSP2 initiates the payments of VIBAN owners (PSP2’s clients) via PSP1. VIBAN must be in an active status to initiate the payment. More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 6: Level2 VIBAN Payment plus Ultimate DebtorPSP2 initiates the payments of the end customer (PSP2's client) via VIBAN that belongs to the PSP2. More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 7: Indirect Scheme Participant Client PaymentIndirect Scheme Participant (PSP1) initiates the payments of the end customer (PSP1’s client). More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 8: Level2 Indirect Scheme Participant Client PaymentIndirect Scheme Member (PSP1) mediates the payments of the end customers (PSP2’s clients). More details in PDF
- Payment request
- Payment response 1 - ACSP status
- Payment response 2 - ACSC status
- Debit Credit Notification
Use case 9: Payment Collection via Direct Debit by PSPPSP initiates Direct Debit to collect payments to its own account opened with LHV. More details in PDF
Use case 10: Payment Collection via Direct Debit on behalf of PSP's clientPSP initiates Direct Debit to collect payments on behalf of its clients to the account opened with PSP. More details in PDF
Use case 11: Indirect Scheme Participant Payment Collection via Direct DebitIndirect Scheme Member (PSP1) initiates the Direct Debit to collect payments on behalf of the end customer (PSP1’s client). More details in PDF
Use case 12: Level 2 Indirect Scheme Participant Payment Collection via Direct DebitIndirect Scheme Member (PSP1) mediates the Direct Debit to collect payments on behalf of the end customer (PSP2’s client). More details in PDF

Response

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

The ISO 20022 Customer Payment Status Report (pain.002) message is sent to the client to inform about the status of a payment instruction sent via LHV Connect with Payment Initiation (pain.001) 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 or payment has been suspended.
  • PART – if some of the payments in original pain.001 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 have reached at least one of the accepted statuses (ACSC, ACSP, ACWC), but not debited yet
  • ACSC - all payments in original pain.001 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 or payment has been suspended. 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, funds may be suspended 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 (pain.002.001.10/pain.002.001.03)

Response message version depends on the message used to initialize the original payment.

  • If payment is initialized with old pain.001.001.03, then old pain.002.001.03 is provided in response.
  • If payment is initialized with new pain.001.001.09 then new pain.002.001.10 is provided in response.

Pain.002 schema file: pain.002.001.10.xsd.

Note: Old pain.002.001.03 and upcoming version pain.002.001.10 are very similar. Differences are mentioned in "LHV Requirement" column.

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

<CstmrPmtStsRpt>

Group header

MULT.MESSAGE ELEMENTXML TAGLHV Requirement
[1..1]+GroupHeader<GrpHdr>
[1..1]++MessageIdentification<MsgId>Unique message id created by LHV.
[1..1]++CreationDateTime<CreDtTm>Creation date and time.
[0..1]++InitiatingParty<InitgPty>
[0..1]+++Identification<Id>
[0..1]++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBIC<AnyBIC>LHV’s BIC.
Note: In old version of pain.002.001.03 this field is named BIC
[1..1]+OriginalGroupInformationAndStatus<OrgnlGrpInfAndSts>
[1..1]++OriginalMessageIdentification<OrgnlMsgId>Original pain.001.001.09 Group Level Message Id.
[1..1]++OriginalMessageNameIdentification<OrgnlMsgNmId>Value ‘pain.001.001.09’.
[0..1]++GroupStatus<GrpSts>Specifies the Group status of all payments in the original pain.001 message. Status codes explained above.
[0..n]++StatusReasonInformation<StsRsnInf>
[0..1]+++Reason<Rsn>
[1..1]++++Code<Cd>If Group Status is RJCT, then filled with ‘NARR’. In this case, Additional Information is also filled.
[0..n]+++AdditionalInformation<AddtlInf>If Reason Code is filled with ‘NARR’, error description is present here. See Group Level Errors.
[0..n]+OriginalPaymentInformationAndStatus<OrgnlPmtInfAndSts>
[1..1]++OriginalPaymentInformationId<OrgnlPmtInfId>Original pain.001.001.09 Payment Information Id.
[0..1]++PaymentInformationStatus<PmtInfSts>Specifies the Group status of one PmtInf block in the original pain.001 message. Status codes explained Status codes explained above.
[0..n]++TransactionInformationAndStatus<TxInfAndSts>
[0..1]+++OriginalInstructionIdentification<OrgnlInstrId>Original payment order number.
[0..1]+++OriginalEndToEndId<OrgnlEndToEndId>Not used.
[0..1]+++TransactionStatus<TxSts>Payment status. Status codes explained above.
[0..n]+++StatusReasonInformation<StsRsnInf>
[0..1]+++OriginalTransactionReference<OrgnlTxRef>Payment scheme information
[1..1]++++PaymentTypeInformation<PmtTpInf>
[1..1]+++++ServiceLevel<SvcLvl>
[1..1]++++++Proprietary<Prtry>Payment scheme code - Code Set: Payment scheme.
[0..1]++++Reason<Rsn>
[1..1]+++++Code<Cd>If Transaction Status is ACWC or RJCT, then ‘NARR’.
[0..n]++++AdditionalInformation<AddtlInf>If Reason Code is ‘NARR’, then description or scheme reject code is given here. For Transaction Status ‘ACWC’, see Reason for Change; for Transaction Status ‘RJCT’, see Transaction Level Errors. For payment scheme error codes see Code Set: Payment Scheme Reject Codes.
[0..1]+++AccountServicerReference<AcctSvcrRef>Unique payment ID assigned by the bank.
[0..1]+++OriginalTransactionReference<OrgnlTxRef>
[0..1]++++Amount<Amt>
[1..1]+++++InstructedAmount<InstdAmt Ccy="AAA">
[0..1]++++RequestedExecutionDate<ReqdExctnDt>Execution date requested by client.
[0..1]++++Debtor<Dbtr>
[0..1]+++++Pty<Pty>Note: In old version of pain.002.001.03 this element does not exist
[0..1]++++++Name<Nm>Debtor’s name.
[0..1]++++DebtorAccount<DbtrAcct>
[1..1]+++++Identification<Id>
{Or++++++IBAN<IBAN>Debtor’s IBAN or Virtual IBAN.
{Or++++++Other<Othr>Debtor's non-IBAN account number (for example, UK account number).
Or}}+++++++Identification<Id>Account number.
[0..1]++++DebtorAgent<DbtrAgt>
[1..1]+++++FinancialInstitutionId<FinInstnId>
[1..1]++++++BICFI<BICFI>LHV’s BIC.
Note: In old version of pain.002.001.03 this field is named BIC
[0..1]++++CreditorAgent<CdtrAgt>
[1..1]+++++FinancialInstitutionId<FinInstnId>
[1..1]++++++BICFI<BICFI>Creditor’s bank BIC.
Note: In old version of pain.002.001.03 this field is named BIC
[0..1]++++Creditor<Cdtr>
[0..1]+++++Pty<Pty>Note: In old version of pain.002.001.03 this element does not exist
[1..1]++++++Name<Nm>Creditor’s name.
[0..1]++++CreditorAccount<CdtrAcct>
[1..1]+++++Identification<Id>
[0..1]++++++IBAN<IBAN>Creditor’s IBAN. UK Faster Payments - used when also payment request contained IBAN.
[0..1]++++++Other<Othr>
[1..1]+++++++Identification<Id>Creditor’s account number which is not IBAN. UK Faster Payments - used when also payment request contained sort code + domestic account nr.

Error codes

Group level errors

GROUP STATUSADDITIONAL INFORMATIONDESCRIPTION
RJCTDuplicate message.Message with this id already exists.
RJCTDuplicate message.Duplicate payment information block in file.
RJCTUploading file failed. Faulty number of payments in file header.Invalid Number Of Transactions in Header Level.
RJCTUploading file failed. Faulty control sum in file header.Invalid Control Sum in Header Level.
RJCTUploading file failed. Faulty number of payments in Payment Information block.Invalid Number Of Transactions in referenced Payment Information block.
RJCTUploading file failed. Faulty control sum in Payment Information block.Invalid Control Sum in referenced Payment Information block.
RJCTUploading file failed. Faulty sender account [IBAN].At least one IBAN or Virtual IBAN does not exist. First bad number encountered is added to error message.
RJCTCorrupted payment file: [validation error description]XML file doesn’t pass XSD validation. Reference to invalid value is given if possible.
RJCTNo rights to debtor’s account.

Transaction level errors

TRANSACTION STATUSADDITIONAL INFORMATIONDESCRIPTION
RJCTDuplicate payment
RJCTAccount temporarily closed
RJCTAccount closed
RJCTCreditor account is closed
RJCTReason not given
RJCTTechnical problem. Try again
RJCTInvalid creditor address or name
RJCTIncorrect account number
RJCTAccount number is not correct
RJCTInvalid account number or sort code
RJCTCreditor address is missing/not correct
RJCTInvalid creditor name
RJCTMissing or invalid reference
RJCTProblem with amount. Contact bank
RJCTInstant payment forbidden, try European payment
RJCTPayment declined, try European payment
RJCTPayment declined
RJCTPayment declined. Regulatory reasons. Try European payment
RJCTReference number is invalid or returned for no reason, try European payment
RJCTOther reason
RJCTReference number invalid.
RJCTCross-border payments from this account are prohibited.
RJCTInvalid creditor’s name.
RJCTCreditor's Correspondent BIC not valid.
RJCTInvalid client account number / account not found.
RJCTPayments from one Trader account to another are not allowed.
RJCTTrader account. Not allowed currency.
RJCTDescription or reference number must be entered.
RJCTDebtor's organisation identification code is faulty.
RJCTCreditor's Bank BIC not valid.
RJCTCreditor's organisation identification code is faulty.
RJCTCreditor's account number not valid.
RJCTCreditor's private person identification code is faulty.
RJCTInsufficient daily limit available.
RJCTInvalid currency.
RJCTPayment to the same account.
RJCTPayment to receiver account not allowed.
RJCTUltimate debtor's organisation identification code is faulty.
RJCTUltimate debtor's private person identification code is faulty.
RJCTInsufficient monthly limit available.
RJCTCorrespondent Bank BIC not valid.
RJCTAccount and BIC country codes not matching.
RJCTAccount and BIC country codes not matching. Check the account number of the recipient and the BIC number of the recipient bank.
RJCTDebtor's private person identification code is faulty.
RJCTInsufficient funds available.
RJCTSignature weight is less than 100%.
RJCTCreditor account number is incorrect. IBAN is mandatory.
RJCTInvalid payment order no.
RJCTOther reason.
RJCTPayment description is too long. Please use maximumcharacters.
RJCTPlease use Latin characters only.
RJCTThis BIC does not conform to the format. Enter the name and address of the creditor’s bank. Insert the creditor’s bank code (such as ABA or Fedwire) before the name of the creditor’s bank.
RJCTUploading file failed. Faulty sender account.
RJCTTechnical problem. Try again
RJCTRequested by customer
RJCTPayment declined. Regulatory reasons
RJCTIncorrect creditor´s bank data
RJCTUploading file failed. Unparsable value in Instruction for Debtor Agent [InstrForDbtrAgt]
RJCTRUB payment codes missing (INN, VO, KPP)
RJCTDebtor's account not active.Virtual IBAN exists, but is not active
RJCTInvalid debtor's nameVirtual IBAN holder name does not match with payment order (PmtInf.Dbtr.Nm) or debtor name missing if payment is from indirect agent's existing account.
RJCTInvalid return codeInvalid payment scheme return code is used
RJCTOriginal payment not receivedPayment to be returned does not exist

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.10">
    <CstmrPmtStsRpt>
        <GrpHdr>
            <MsgId>10942445</MsgId>
            <CreDtTm>2019-11-14T16:01:40.102+02:00</CreDtTm>
            <InitgPty>
                <Id>
                    <OrgId>
                        <AnyBIC>LHVBEE20XXX</AnyBIC>
                    </OrgId>
                </Id>
            </InitgPty>
        </GrpHdr>
        <OrgnlGrpInfAndSts>
            <OrgnlMsgId>MSGIDLHVTEST01-1</OrgnlMsgId>
            <OrgnlMsgNmId>pain.001.001.09</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>
                        <Dt>2019-11-14</Dt>
                    </ReqdExctnDt>
                    <PmtTpInf>
                        <SvcLvl>
                            <Prtry>INTERNAL</Prtry>
                        </SvcLvl>
                    </PmtTpInf>
                    <Dbtr>
                        <Pty>
                            <Nm>LHV Connect Demo 1</Nm>
                        </Pty>
                    </Dbtr>
                    <DbtrAcct>
                        <Id>
                            <IBAN>EE337700771001260958</IBAN>
                        </Id>
                    </DbtrAcct>
                    <DbtrAgt>
                        <FinInstnId>
                            <BICFI>LHVBEE20</BICFI>
                        </FinInstnId>
                    </DbtrAgt>
                    <CdtrAgt>
                        <FinInstnId>
                            <BICFI>LHVBEE22</BICFI>
                        </FinInstnId>
                    </CdtrAgt>
                    <Cdtr>
                        <Pty>
                            <Nm>LHV Connect Demo 2</Nm>
                        </Pty>
                    </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>
                        <Dt>2019-11-14</Dt>
                    </ReqdExctnDt>
                    <Dbtr>
                        <Pty>
                            <Nm>
                            LHV Connect Demo 1
                            </Nm>
                        </Pty>
                    </Dbtr>
                    <DbtrAcct>
                        <Id>
                            <IBAN>EE337700771001260958</IBAN>
                        </Id>
                    </DbtrAcct>
                    <DbtrAgt>
                        <FinInstnId>
                            <BICFI>LHVBEE20</BICFI>
                        </FinInstnId>
                    </DbtrAgt>
                    <CdtrAgt>
                        <FinInstnId>
                            <BICFI>LHVBEE22</BICFI>
                        </FinInstnId>
                    </CdtrAgt>
                    <Cdtr>
                        <Pty>
                            <Nm>Incorrect Customer</Nm>
                        </Pty>
                    </Cdtr>
                    <CdtrAcct>
                        <Id>
                            <IBAN>EE427700771001260990</IBAN>
                        </Id>
                    </CdtrAcct>
                </OrgnlTxRef>
            </TxInfAndSts>
        </OrgnlPmtInfAndSts>
    </CstmrPmtStsRpt>
</Document>

Payment Collection Services

Services for different payment collection schemes and options.

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

To receive a 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.

Type in original CollectionType in resend Collection
FirstReccurring
RecurringReccurring
FinalCannot resend
One-offCannot resend

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.

Due date (collection)Cut-off (then collection has to be sent to Bank)Settlement
25.12 or 26.1224.12 or earlier (must be a banking day)The first banking day after 26.12
01.0131.12 or 30.12 (must be a banking day)02.01
SaturdayFridayMonday
SundayFridayMonday
MondayFridayMonday
Good Friday, weekend after Good Friday and Easter MondayThursday before Good FridayTuesday after Good Friday
FridayThursdayFriday

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

Collections can be sent to debtor at the earliest 14 calendar days before due date.
Collections must sent to debtor at latest at 1 Target2 working day before due date.
Creditor must send collection to bank at latest at 1 Target2 working day before due date and cut-off 15:30 CET.
Creditors collections are sent to scheme on Target2 working day at 07:00, 09:00, 10:30, 21:00 CET.
Debtor bank receives collection info 7 times per Target2 working day: 07:00, 09:00, 11:00, 16:05, 18:00, 20:00, 22:00 CET.
Payments (outgoing, incoming) settlement on due date - 11:30 CET.
Debtor can cancel (refuse) the payment on due date until 10:30 CET
If Debtor bank will not manage to send the refusal on time. The refusal will be processed as return. On next Target2 working day settlement entries take place.
In case creditor needs to cancel a transaction either as Request for Cancellation before due date or Reversal after due date. If it is done before 10:30 CET on due date no settlement entries will follow.

Messages

XML formatMessage description
pain.008.001.08Direct Debit initiation (outgoing collection)
Direct Debit notification (incoming collection)
pain.002.001.10Response to Direct Debit initiation, collection reversal (outgoing collection)
Response to Direct Debit collection refusal (incoming collection)
pain.007.001.09Direct Debit collection reversal, cancellation (outgoing collection)
Direct Debit collection refusal (incoming collection)

Direct Debit Initiation Request

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

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

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

If Direct Debit collection is cancelled (by Creditor) then the cancellationl process has to be started and Direct Debit exeption request (pain.007) sent.

If Direct Debit collection is reversed (by Creditor) then the reversal process has to be started and Direct Debit exeption request (pain.007) sent

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

XML Format (pain.008.001.08)

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

Note: Old pain.008.001.02 and upcoming versions of pain.008.001.08 are very similar. Differences are mentioned in "LHV Requirement" column.

This message is used for both outgoing collection request and incoming collection notification.

Message structure

MULT.MESSAGE ELEMENTXML TAGCOMMENT
[1..1]+GroupHeader<GrpHdr>Mandatory, occurs once.
[1..n]+PaymentInformation<PmtInf>Mandatory and repetitive. Contains information related to creditor.
[1..n]++DirectDebitTransactionInformation<DrctDbtTxInf>Mandatory and repetitive. Contains information related to the direct debit(s) included in the message.

Message root

MULT.MESSAGE ELEMENTXML TAGCOMMENT
[1..1]+MessageRoot<CstmrDrctDbtInitn>Mandatory, occurs once.

Group header

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[1..1]+GroupHeader<GrpHdr>Mandatory, occurs once.
[1..1]++MessageIdentification<MsgId>
[1..1]++CreationDateTime<CreDtTm>
[1..1]++NumberOfTransactions<NbOfTxs>Number of direct debit transactions in all Payment Information blocks included in this message. If this number is not correct, the file upload will be cancelled.
[1..1]++ControlSum<CtrlSum>
[1..1]++InitiatingParty<InitgPty>Party that submits the Direct Debit Initiation Request to LHV.
[0..1]+++Name<Nm>
[0..1]+++Identification<Id>
{Or++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBic<AnyBIC>
[0..1]+++++LEI<LEI>Field not available in pain.008.001.02
[0..n]+++++Other<Othr>
[1..1]++++++Identification<Id>
[0..1]++++++SchemeName<SchmeNm>
{Or+++++++Code<Cd>
Or}+++++++Proprietary<Prtry>
[0..1]++++++Issuer<Issr>
Or}++++PrivateIdentification<PrvtId>
{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++BirthDate<BirthDt>
[0..1]++++++ProvinceOfBirth<PrvcOfBirth>
[1..1]++++++CityOfBirth<CityOfBirth>
[1..1]++++++CountryOfBirth<CtryOfBirth>
[0..2]Or}+++++Other<Othr>
[1..1]++++++Identification<Id>
[0..1]++++++SchemeName<SchmeNm>
{Or+++++++Code<Cd>
Or}+++++++Proprietary<Prtry>
[0..1]++++++Issuer<Issr>

Payment information

MULT.ORMESSAGE ELEMENTXML TAGLHV Requirement
[1..n]+PaymentInformation<PmtInf>Mandatory and repetitive. Contains information related to creditor.
[1..1]++PaymentInformationIdentification<PmtInfId>Uniquely identifies the payment information group within this message.
[1..1]++PaymentMethod<PmtMtd>Only the value "DD" (Direct Debit) is allowed here. If any other value is entered, it will be ignored.
[0..1]++BatchBooking<BtchBookg>Not used.
[1..1]++NumberOfTransactions<NbOfTxs>Number of Direct Debit transactions included in the current Payment Information block. If this number is not correct, the file upload will be cancelled.
[1..1]++ControlSum<CtrlSum>Control sum of all individual amounts in the current Payment Information block, irrespective of currencies. If this number is not correct, the file upload will be cancelled.
[0..1]++PaymentTypeInformation<PmtTpInf>Set of elements used to specify the type of transaction. 'Payment Type Information' must be present either here or under 'Direct Debit Transaction Information'.
[1..1]+++ServiceLevel<SvcLvl>
{Or++++Code<Cd>Not used.
Or}++++Proprietary<Prtry>See the supported values in Code set: Direct Debit scheme
[0..1]+++LocalInstrument<LclInstrm>
{Or++++Code<Cd>SEPA Direct Debit: only value "CORE" is allowed.
+++SequenceType<SeqTp>SEPA Direct Debit: If 'Amendment Indicator' is 'true', and ‘Original Debtor Account’ is set to 'SMNDA' (Same Mandate with a New Debtor Account), this message element indicates either 'FRST' (First), 'RCUR' (Recurring), 'FNAL' (Final) or 'OOFF' (One-off)
[0..1]+++CategoryPurpose<CtgyPurp>
{Or++++Code<Cd>See the supported values in Code Set: Category Purpose .
Or}++++Proprietary<Prtry>Not used.
[1..1]++RequestedCollectionDate<ReqdColltnDt>Date and time at which the creditor requests that the amount of money is to be collected from the debtor.
[1..1]++Creditor<Cdtr>Party whose account the amount of Direct Debit transaction is to be credited to.
[1..1]+++Name<Nm>Creditor’s name. For indirect agent - the holder name (not the master account owner). Creditor name is mandatory if payment is initiated from indirect agent's existing accounts.
[0..1]+++PostalAddress<PstlAdr>See address structure and details here. If direct debit collection is initiated with indirect agent's existing accounts, country and Address Line are required.
[1..1]++CreditorAccount<CdtrAcct>Creditor's account. Can be client account where to Direct Debit transaction amount is credited or Indirect Agency account (client generated accounts).
[1..1]+++Identification<Id>
{Or++++IBAN<IBAN>Creditor's IBAN.
Or}++++Other<Othr>Not used.
[1..1]+++++Identification<Id>Not used.
[0..1]+++Currency<Ccy>Not required to be filled in. The Direct Debit transaction will be processed in the currency of the transaction amount.
[1..1]++CreditorAgent<CdtrAgt>Creditor’s bank information.
[1..1]+++FinancialInstitutionIdentification<FinInstnId>
[0..1]++++BICFIIf the LHV BIC is faulty or missing, it will be replaced with the correct code.
Note: In old version of pain.008.001.02 this field is named BIC
[0..1]++++Other<Othr>Not used.
[1..1]+++++Identification<Id>Not used.
[0..1]++UltimateCreditor<UltmtCdtr>SEPA specific information. Ultimate party to which an amount of money is due. This data element may be present either at 'Payment Information' or at 'Direct Debit Transaction Information' level.
[0..1]+++Name<Nm>Ultimate creditor’s name.
[0..1]+++Identification<Id>
{Or++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBic<AnyBIC>Ultimate creditor’s BIC. BIC or Othr is required.
[0..1]+++++LEI<LEI>Ultimate creditor’s LEI code
Note: Field not available in old version of pain.008.001.02
[0..1]+++++Other<Othr>
[1..1]++++++Identification<Id>Ultimate creditor’s organisation identification.
[0..1]++++++SchemeName<SchmeNm>
{{Or+++++++Code<Cd>See the supported values in Code Set: Organisation Identification .
Or}}+++++++Proprietary<Prtry>
[0..1]++++++Issuer<Issr>
Or}++++PrivateIdentification<PrvtId>
{Or+++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]++++++BirthDate<BirthDt>Ultimate creditor’s birth date.
[0..1]++++++ProvinceOfBirth<PrvcOfBirth>Ultimate creditor’s city of birth.
[1..1]++++++CityOfBirth<CityOfBirth>Ultimate creditor’s birth country ISO code.
[1..1]++++++CountryOfBirth<CtryOfBirth>
Or}+++++Other<Othr>
[1..1]++++++Identification<Id>Ultimate creditor’s identification.
[0..1]++++++SchemeName<SchmeNm>
{Or+++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
Or}+++++++Proprietary<Prtry>
[0..1]++++++Issuer<Issr>
[0..1]++ChargeBearer<ChrgBr>SEPA Direct Debit: only value "SLEV" is allowed. See the supported values in Code Set: Charges Bearer .
[0..1]++CreditorSchemeIdentification<CdtrSchmeId>It is recommended that all transactions within the same ‘Payment Information’ block have the same ‘Creditor Scheme Identification’. This data element must be present at either ‘Payment Information’ or ‘Direct Debit Transaction’ level.
[1..1]+++Identification<Id>
[1..1]++++PrivateIdentification<PrvtId>
[1..1]+++++Other<Othr>
[1..1]++++++Identification<Id>Creditor Identifier.
[0..1]++++++SchemeName<SchmeNm>
{Or+++++++Code<Cd>Not used.
Or}+++++++Proprietary<Prtry>SEPA Direct Debit: only value "SEPA" is allowed.
[0..1]++++++Issuer<Issr>
[1..n]++DirectDebitTransactionInformation<DrctDbtTxInf>This block contains a set of elements used to provide information on the individual transaction(s) included in the message.
[1..1]+++PaymentIdentification<PmtId>
[0..1]++++InstructionIdentification<InstrId>Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.
[1..1]++++EndToEndIdentification<EndToEndId>Unique identification assigned by the initiating party to unumbiguously identify the transaction.
[0..1]+++PaymentTypeInformation<PmtTpInf>Set of elements used to specify the type of transaction. 'Payment Type Information' must be present either here or directly under 'Payment Information'.
[1..1]++++ServiceLevel<SvcLvl>
{Or+++++Code<Cd>Not used.
Or}+++++Proprietary<Prtry>See the supported values in Code set: Direct Debit scheme)
[0..1]++++LocalInstrument<LclInstrm>
{Or+++++Code<Cd>SEPA Direct Debit: only value "CORE" is allowed.
++++SequenceType<SeqTp>SEPA Direct Debit: If 'Amendment Indicator' is 'true', and ‘Original Debtor Account’ is set to 'SMNDA' (Same Mandate with a New Debtor Account), this message element indicates either 'FRST' (First), 'RCUR' (Recurring), 'FNAL' (Final) or 'OOFF' (One-off).
[0..1]++++CategoryPurpose<CtgyPurp>
{Or+++++Code<Cd>See the supported values in Code Set: Category Purpose .
Or}+++++Proprietary<Prtry>Not used.
[1..1]+++InstructedAmount<InstdAmt>Payment amount and the currency ordered by the initiating party.
[0..1]+++ChargeBearer<ChrgBr>SEPA Direct Debit: only value "SLEV" is allowed. See the supported values in Code Set: Charges Bearer .
[1..1]+++DirectDebitTransaction<DrctDbtTx>Set of elements providing information specific to the direct debit mandate.
[1..1]++++MandateRelatedInformation<MndtRltdInf>Set of elements used to provide further details of the direct debit mandate signed between the creditor and the debtor.
[1..1]+++++MandateIdentification<MndtId>Unique identification, as assigned by the creditor, to unambiguously identify the mandate.
[1..1]+++++DateOfSignature<DtOfSgntr>Date on which the direct debit mandate has been signed by the debtor.
[0..1]+++++AmendmentIndicator<AmdmntInd>Indicator notifying whether the underlying mandate is amended or not.
[0..1]+++++AmendmentInformationDetails<AmdmntInfDtls>List of mandate elements that have been modified. Mandatory if 'Amendment Indicator' is 'true'.
[0..1]++++++OriginalMandateIdentification<OrgnlMndtId>Unique identification, as assigned by the creditor, to unambiguously identify the original mandate. Mandatory if changes occur in 'Mandate Identification', otherwise not to be used.
[0..1]++++++OriginalCreditorSchemeIdentification<OrgnlCdtrSchmeId>Original creditor scheme identification that has been modified.
[0..1]+++++++Name<Nm>Name by which a party is known and which is usually used to identify that party.
[0..1]+++++++Identification<Id>
[1..1]++++++++PrivateIdentification<PrvtId>
[1..1]+++++++++Other<Othr>
[1..1]++++++++++Identification<Id>Creditor Identifier.
[0..1]++++++++++SchemeName<SchmeNm>
{Or+++++++++++Code<Cd>Not used.
Or}+++++++++++Proprietary<Prtry>
[0..1]++++++++++Issuer<Issr>
[0..1]++++++OriginalDebtorAccount<OrgnlDbtrAcct>Original debtor account that has been modified.
[1..1]+++++++Identification<Id>
{Or++++++++IBAN<IBAN>Original debtor IBAN that has been modified.
Or}++++++++Other<Othr>Not used.
[1..1]+++++++++Identification<Id>Not used.
[0..1]+++++++Currency<Ccy>
[0..1]++++++OriginalDebtorAgent<OrgnlDbtrAgt>Original debtor agent that has been modified.
[1..1]+++FinancialInstitutionIdentification<FinInstnId>
[0..1]+++++++BICFIOriginal debtor agent BIC that has been modified.
Note: In old version of pain.008.001.02 this field is named BIC
[0..1]+++++++Other<Othr>Not used.
[1..1]++++++++Identification<Id>Not used.
[0..1]+++++ElectronicSignature<ElctrncSgntr>Not used.
[0..1]++++CreditorSchemeIdentification<CdtrSchmeId>It is recommended that all transactions within the same 'Payment Information' block have the same 'Creditor Scheme Identification'. This data element must be present at either 'Payment Information' or 'Direct Debit Transaction' level.
[1..1]+++++Identification<Id>
[1..1]++++++PrivateIdentification<PrvtId>
[1..1]+++++++Other<Othr>
[1..1]++++++++Identification<Id>Creditor Identifier.
[0..1]++++++++SchemeName<SchmeNm>
{Or+++++++++Code<Cd>Not used.
Or}+++++++++Proprietary<Prtry>SEPA Direct Debit: only value "SEPA" is allowed.
[0..1]++++++++Issuer<Issr>
[0..1]++UltimateCreditor<UltmtCdtr>SEPA specific information. Ultimate party to which an amount of money is due. This data element may be present either at 'Payment Information' or at 'Direct Debit Transaction Information' level.
[0..1]+++Name<Nm>Ultimate creditor’s name.
[0..1]+++Identification<Id>
{Or++++OrganisationIdentification<OrgId>See sub-elements at 2.54.
Or}++++PrivateIdentification<PrvtId>See sub-elements at 2.55.
[1..1]+++DebtorAgent<DbtrAgt>Financial institution servicing an account for the debtor.
[1..1]++++FinancialInstitutionIdentification<FinInstnId>
[0..1]+++++BICFI<BICFI>Debtor agent BIC.
Note: In old version of pain.008.001.02 this field is named BIC
[0..1]+++++Other<Othr>Not used.
[1..1]+++Debtor<Dbtr>Party that owes an amount of money to the (ultimate) creditor.
[1..1]++++Name<Nm>Debtor name.
[0..1]++++Postal Address<PstlAdr>See address structure and details here.
[0..1]++++Identification<Id>
{Or+++++OrganisationIdentification<OrgId>
[0..1]++++++AnyBic<AnyBIC>Debtor's BIC
Note: In old version of pain.008.001.02 this field is named BICorBei
[0..1]++++++LEI<LEI>Debtor's LEI
Note: Field not available in old version of pain.008.001.02
[0..n]++++++Other<Othr>
[1..1]+++++++Identification<Id>Debtor's organisation identification.
[0..1]+++++++SchemeName<SchmeNm>
{{Or++++++++Code<Cd>See the supported values in Code Set: Organisation Identification .
Or}}+++++++Proprietary<Prtry>
[0..1]++++++Issuer<Issr>
Or}+++++PrivateIdentification<PrvtId>
{Or++++++DateAndPlaceOfBirth<DtAndPlcOfBirth>
[1..1]+++++++BirthDate<BirthDt>Debtor's birth date.
[0..1]+++++++ProvinceOfBirth<PrvcOfBirth>Debtor's city of birth.
[1..1]+++++++CityOfBirth<CityOfBirth>Debtor's birth country ISO code.
[1..1]+++++++CountryOfBirth<CtryOfBirth>
Or}++++++Other<Othr>
[1..1]+++++++Identification<Id>Debtor's identification.
[0..1]+++++++SchemeName<SchmeNm>
{Or+++++++Code<Cd>See the supported values in Code Set: Private Person Identification.
Or}+++++++Proprietary<Prtry>
[0..1]++++++Issuer<Issr>
[1..1]+++DebtorAccount<DbtrAcct>Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.
[1..1]++++Identification<Id>
{Or+++++IBAN<IBAN>Debtor's IBAN.
Or}+++++Other<Othr>Not used.
[1..1]++++++Identification<Id>Not used.
[0..1]++++Currency<Ccy>Not required to be filled in. The Direct Debit transaction will be processed in the currency of the transaction amount.
[0..1]+++UltimateDebtor<UltmtDbtr>Ultimate party that owes an amount of money to the (ultimate) creditor.
[0..1]++++Name<Nm>Ultimate debtor's name.
[0..1]++++Identification<Id>
{Or+++++OrganisationIdentification<OrgId>See sub-elements at 2.153.
Or}+++++PrivateIdentification<PrvtId>See sub-elements at 2.154.
[0..1]+++Purpose<Purp>Underlying reason for the payment transaction.
[1..1]++++Code<Cd>See the codes in Code Set: Purpose .
[0..1]+++RemittanceInformation<RmtInf>Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. Either 'Structured' or 'Unstructured', may be present.
[0..1]++++Unstructured<Ustrd>Collection description.
[0..1]++++Structured<Strd>
[0..1]+++++CreditorReferenceInformation<CdtrRefInf>
[1..1]++++++Type<Tp>
[1..1]+++++++CodeOrProprietary<CdOrPrtry>
[1..1]++++++++Code<Cd>SEPA Direct Debit: only value "SCOR" is allowed.
[0..1]+++++++Issuer<Issr>
[1..1]++++++Reference<Ref>Collection reference number. Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.
[0..n]+++Supplementary Data<SplmtryData>See details in supplementary data section.
[0..1]++++Place and Name<PlcAndNm>Field ignored
[1..1]++++Data Envelope<Envlp>
[1..1]+++++Document<Document>
[0..n]++++++Party Data<PartyData>Additional data block
[1..1]+++++++Party Code<Party>Defines which party this data is related to. Possible values: DEBTOR, CREDITOR, ULTIMATE_DEBTOR, ULTIMATE_CREDITOR
[1..1]+++++++Data Key<Key>Additional data element being sent. Possible values: DATE_OF_BIRTH, MCC, PSP_SCENARIO
[1..1]+++++++Data Value<Value>Additional data element value

Address structure (PostalAddress)

Common address structure is used throughout the payment collection message.

Note: pain.008.001.02 does not support all of the following fields. See XSD for details.

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[0..1]Department<Dept>
[0..1]Sub-department name<SubDebt>
[0..1]Street name<StrtNm>
[0..1]Building number<BldgNb>
[0..1]Building name<BldgNm>
[0..1]Floor number<Flr>
[0..1]Post box<PstBx>
[0..1]Room name<Room>
[0..1]Postal code<PstCd>
[0..1]Town name<TwnNm>
[0..1]Town location name<TwnLctnNm>
[0..1]District name<DstrctNm>
[0..1]Country sub-division<CtrySubDvsn>
[0..1]ISO 2 letter country code<Ctry>
[0..2]Address line<AdrLine>

Supplementary data

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

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

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

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

Supplementary data includes additional data elements defined in 3 fields. The number of additional data elements is not limited.

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

pain.001 supplementary data example:

...
<SplmtryData>
    <Envlp>
        <ext:Document>
            <ext:partyData>
                <ext:party>CREDITOR</ext:party>
                <ext:key>DATE_OF_BIRTH</ext:key>
                <ext:value>1980-09-24</ext:value>
            </ext:partyData>
        </ext:Document>
    </Envlp>
</SplmtryData>
...

Direct Debit Initiation Response

The ISO 20022 Customer Payment Status Report (pain.002.001.10) message is sent to the client to inform about the status of a Direct Debit collection sent via LHV Connect with Direct Debit instruction (pain.008.001.08) message.

Customer Payment Status Report refers to the original Direct Debit Initiation message and provides positive, negative and pending status updates to original collections.

There can be many Customer Payment Status Reports per one Direct Debit Initiation message - typically if any of the transactions was not accepted right away for any reason.

Direct Debit Collection Status Codes and Descriptions

Statuses are reported on group level for the whole collection instruction (GrpSts and PmtInfSts tags) and separately for each collection (TxSts tag).

Group level statuses are reported only in the first Direct Debit initiation response message after the initial request.

Further responses (if any) shall not contain GrpSts and PmtInfSts tags - you must process the result of every collection entry separately.

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

CODEDESCRIPTION
RJCTAll Direct Debit collections in original pain.008.001.08 'Payment Information' block have been rejected.
PARTIf some of the Direct Debit collections in original pain.008.001.08 'Payment Information' block have reached one of the accepted statuses (ACCP, ACSC, ACSP), but some also rejected, then status is partially accepted.
PDNGAll Direct Debit collections in original pain.008.001.08 are pending. Further checks and status update will be performed.
ACCPAll Direct Debit collections in original pain.008.001.08 have reached the status ACCP, but neither sent out to clearing system nor credited yet.
ACSPAll Direct Debit collections referred in pain.002.001.03 have reached the status ACSP, but not credited yet.
ACSCAll Direct Debit collections referred in pain.002.001.03 are credited to client’s account.

Single payment statuses (OrgnlPmtInfAndSts.TxInfAndSts.TxSts):

CODEDESCRIPTION
RJCTRejected - Direct Debit collection has been rejected (final status).
PDNGPending - technical validations were successful. Direct Debit collection is pending and processed by LHV. Further checks and status update will be performed.
ACCPAccepted - all validations were successful. Direct Debit collection is being processed by the bank, it has not been credited to client's account nor sent to clearing system.
ACSPAccepted - settlement in process. Direct Debit collection has been sent to clearing system. At least one more status update must follow (either accept or reject).
ACSCAccepted - settlement completed and Direct Debit collection has been credited to client's account. ACSC is typically the final status.

Message structure

MULT.MESSAGE ELEMENTXML TAGCOMMENT
[1..1]+GroupHeader<GrpHdr>Mandatory, occurs once. Set of characteristics shared by all individual direct debit collections included in the status report message.
[1..1]++OriginalGroupInformationAndStatus<OrgnlGrpInfAndSts>Occurs once. Refers to original direct debit initiation 'Group' level information.
[0..n]++OriginalPaymentInformationAndStatus<OrgnlPmtInfAndSts>Optional and repetitive. Refers to original direct debit initiation 'Payment Information' level information.
[0..n]+++TransactionInformationAndStatus<TxInfAndSts>Optional and repetitive. Includes information about the original direct debit collection transaction and its status.

Message root

MULT.MESSAGE ELEMENTXML TAGCOMMENT
[1..1]+MessageRoot<CstmrPmtStsRpt>Mandatory, occurs once.

Group header

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[1..1]+GroupHeader<GrpHdr>Mandatory, occurs once.
[1..1]++MessageIdentification<MsgId>Unique message id created by LHV.
[1..1]++CreationDateTime<CreDtTm>Creation date and time.
[0..1]++InitiatingParty<InitgPty>
[0..1]+++Identification<Id>
[0..1]++++OrganisationIdentification<OrgId>
[0..1]+++++AnyBic<AnyBIC>LHV’s BIC.

Original group information and status

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[1..1]+OriginalGroupInformationAndStatus<OrgnlGrpInfAndSts>
[1..1]++OriginalMessageIdentification<OrgnlMsgId>Original pain.008.001.08 Group Level Message Id.
[1..1]++OriginalMessageNameIdentification<OrgnlMsgNmId>Value ‘pain.008.001.08’.
[0..1]++GroupStatus<GrpSts>Specifies the Group status of all payments in the original pain.008.001.08 message. Status codes explained above.
[0..n]++StatusReasonInformation<StsRsnInf>
[0..1]+++Reason<Rsn>
[1..1]++++Code<Cd>If Group Status is 'RJCT', then filled with 'NARR'. In this case, Additional Information is also filled.
[0..n]+++AdditionalInformation<AddtlInf>If Reason Code is filled with 'NARR', error description is present here. See Group Level Errors

Original payment information and status

MULT.ORMESSAGE ELEMENTXML TAGLHV REQUIREMENT
[0..n]+OriginalPaymentInformationAndStatus<OrgnlPmtInfAndSts>
[1..1]++OriginalPaymentInformationId<OrgnlPmtInfId>Original pain.008.001.08 Payment Information Id.
[0..1]++PaymentInformationStatus<PmtInfSts>Specifies the Group status of one PmtInf block in the original pain.008.001.08 message. Status codes explained Status codes explained above.
[0..n]++StatusReasonInformation<StsRsnInf>
[1..1]+++Reason<Rsn>
[1..1]++++Code<Cd>
[0..n]++TransactionInformationAndStatus<TxInfAndSts>
[0..1]+++OriginalInstructionIdentification<OrgnlInstrId>Original direct debit collection order number.
[0..1]+++OriginalEndToEndId<OrgnlEndToEndId>
[0..1]+++TransactionStatus<TxSts>Direct debit collection status. Status codes explained above.
[0..n]+++StatusReasonInformation<StsRsnInf>
[1..1]+++Reason<Rsn>
[1..1]++++Code<Cd>
[0..1]+++OriginalTransactionReference<OrgnlTxRef>Direct debit scheme information.
[0..1]++++Amount<Amt>
[0..1]++++RequestedCollectionDate<ReqdColltnDt>
[0..1]++++CreditorSchemeIdentification<CdtrSchmeId>
[0..1]++++PaymentTypeInformation<PmtTpInf>
[1..1]++++MandateRelatedInformation<MndtRltdInf>
[0..1]++++RemittanceInformation<RmtInf>
[0..1]++++UltimateDebtor<UltmtDbtr>
[0..1]++++Debtor<Dbtr>
[0..1]++++DebtorAccount<DbtrAcct>
[0..1]++++DebtorAgent<DbtrAgt>
[0..1]++++CreditorAgent<CdtrAgt>
[0..1]++++Creditor<Cdtr>
[0..1]++++CreditorAccount<CdtrAcct>
[0..1]++++UltimateCreditor<UltmtCdtr>

Direct Debit Incoming Collection Notification

For each incoming Direct Debit collection a notification message will be sent (pain.008)

  • Header Message-Response-Type: DIRECT_DEBIT_INCOMING_COLLECTION_NOTIFICATION

See pain.008.001.08 message details here

Direct Debit Refusal Request and Response

For each incoming Direct Debit collection it is possible to send a refusal request using pain.007 message.

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

Refusal request must be sent as pain.007 message (see below). LHV will validate the message and send pain.002 response message to indicate if the refuse or return submission was successful or not.

  • Header Message-Response-Type: DIRECT_DEBIT_INCOMING

When incoming collection is eligible for refusal (before settlement), the cancellation is confirmed with another pain.002 message after the completion of refusal.

  • Header Message-Response-Type: DIRECT_DEBIT_INCOMING_CANCEL_NOTIFICATION

When incoming collection is already settled then LHV tries to return the payment. Connect users receive credit/debit notification (camt.054) when action is completed successfully.

  • Header Message-Response-Type: CREDIT_DEBIT_NOTIFICATION

XML Format (pain.007.001.09)

This message is used for incoming and outgoing collection refusal or return. Only fields intended for the use of incoming collection refusal in LHV are described here.

Message root

INDEXMULT.MESSAGE ELEMENTXML TAGCOMMENT
0.0[1..1]Group Header<GrpHdr>Mandatory, occurs once.
0.0[1..1]Original Payment information and reversal<OrgnlPmtInfAndRvsl>Refused/reversed payment information

Group header

INDEXMULT.MESSAGE ELEMENTXML TAGLHV REQUIREMENT
1.1[1..1]++MessageIdentification<MsgId>Unique message id
1.2[1..1]++CreationDateTime<CreDtTm>Creation date and time.
1.5[1..1]++Number of transactions<NbOfTxs>Must be 1
1.6[1..1]++Control Sum<CtrlSum>Value of payment regardless of currency

Original payment information and reversal

INDEXMULT.MESSAGE ELEMENTXML TAGLHV REQUIREMENT
3.0[1..1]+Original payment to be refused or reversed<OrgnlPmtInfAndRvsl>
3.1[1..1]++Original payment reference<OrgnlPmtInfId>Original pain.008.001.08 Payment Id.
3.2[1..1]++Original payment end to end id<OrgnlEndToEndId>Original pain.008.001.08 end to end id.
3.3[1..1]++Refusal reason code<RvslRsnInf.Rsn.Cd>See usable reject codes for SEPA DD below

Direct Debit Incoming Collection (Outgoing Payment) Notification

Header Message-Response-Type: DIRECT_DEBIT_INCOMING_COLLECTION_NOTIFICATION

If we receive incoming collection (outgoing payment), we will notify the debtor by sending pain.008.001.08 ("Customer Direct Debit Collection Initiation")

No response is required when debtor allows the incoming collection (outgoing payment).

Debtor can request refunds or return up to 8 weeks after payment settlement by sending pain.007 message (see below).

Debtor can request a refund from 8 weeks after the payment settlement date by sending an email to the service provider.

Direct Debit Incoming Collection Refusal Request

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

Debtor can request refunds or return up to 8 weeks after payment settlement by sending pain.007 message.

Debtor can request a refund from 8 weeks after the payment settlement date by sending an email to the service provider.

Pain.002 is provided as a response for refuse or return request where:

  • TxInfAndSts.TxSts = ACCP (in case of no errors), RJCT (in case of errors).
  • OrgnlGrpInfAndSts.OrgnlMsgId references to the MsgId from request (pain.007).

pain.007 XML Message Structure

LHV is currently using pain.007.001.09.

XML TAGREQUIREDCOMMENT
GrpHdr.MsgIdMandatoryMust be filled as required by XSD
GrpHdr.NbOfTxsMandatoryOnly value 1 is supported. Each collection must be refused/returned separately
OrgnlPmtInfAndRvsl.OrgnlPmtInfIdMandatoryUsed for finding collection to be refused. Must be filled as required by XSD
OrgnlPmtInfAndRvsl.TxInf.OrgnlEndToEndIdMandatoryUsed for finding collection to be refused. Must be filled as required by XSD

*Note: All other elements must be filled according to pain.007.001.09 XSD requirements but are not involved in the business process and not validated in LHV.

Examples

Examples of collections and related messages for typical use cases depending on Direct Debit schemes and other details.

CASENOTES AND EXAMPLES
SEPA Direct Debit collectionSEPA Direct Debit collection for EE LHV account.
- Direct Debit Initiation Request

Error Codes

Group Level Errors

GROUP STATUSADDITIONAL INFORMATIONDESCRIPTION
RJCTDuplicate message.
RJCTDuplicate Payment Information block [PmtInf.PmtInfId].
RJCTDuplicate Direct Debit Transaction block [PmtInf.DrctDbtTxInf.PmtId.EndToEndId].
RJCTUploading file failed. Technical error.
RJCTUploading file failed. XML Schema validation error.XML file doesn’t pass XSD validation. Reference to invalid value is given if possible.
RJCTUploading file failed. Faulty number of direct debit transactions in file header.Invalid Number Of Transactions in Header Level.
RJCTUploading file failed. Faulty control sum in file header.Invalid Control Sum in Header Level.
RJCTUploading file failed. Faulty number of direct debit transactions in payment information block [PmtInf.PmtInfId].Invalid Number Of Transactions in referenced Payment Information block.
RJCTUploading file failed. Faulty control sum in payment information block [PmtInf.PmtInfId].Invalid Control Sum in referenced Payment Information block.
RJCTUploading file failed. Creditor Scheme Identification [...SchmeNm.Prtry] not allowed.
RJCTUploading file failed. Routing code not allowed: [PmtInf.PmtInfId.SvcLvl.Prtry]
RJCTUploading file failed. Faulty creditor account [IBAN].At least one IBAN does not exist. First bad number encountered is added to error message.
RJCTUploading file failed. Sending collections from this BIC [IBAN] is not allowed by the scheme.
RJCTUploading file failed. The debtor name field must be filled.
RJCTUploading file failed. The creditor name field must be filled.
RJCTUploading file failed. Faulty debtor account [IBAN].
RJCTNo rights to creditor's account [IBAN].
RJCTInvalid Creditor Identifier [PmtInf.CdtrSchmeId.Id.PrvtId.Othr.Id].

Transaction Level Errors

TRANSACTION STATUSSCHEME REJECT CODE: SEPADDADDITIONAL INFORMATION
RJCTInvalid Requested Collection Date. Date is not within allowed range.
RJCTInvalid Creditor / Debtor IBAN format.
RJCTDebtor Agent not allowed. Debtor Agent must be a member of the Direct Debit scheme selected.
RJCTInvalid Mandate Identification. The Mandate Identification field must be filled.
RJCTInvalid Mandate Amendment Info. The values under Amendment Information Details block should be different.
RJCTOriginal Debtor Agent not allowed when Original Debtor Account is 'SMNDA'.
RJCTAC01Incorrect Account Number
RJCTAC04Closed Account Number
RJCTAC06Blocked Account
RJCTAG01Transaction Forbidden
RJCTAG02Invalid PSP Operation Code/ transaction code/ sequence type incorrect, invalid file format.
RJCTAM02Not Allowed Amount
RJCTAM04Insufficient Funds
RJCTAM05Duplication
RJCTCNORCreditor PSP is not registered under this BIC in the CSM
RJCTDNORDebtor PSP is not registered under this BIC in the CSM
RJCTDT01Invalid Date → This error code is also set when the settlement date is not consistent with the Direct Debit product configuration for the following configuration parameters:
* DD Earliest submission date
* DD Latest date for first or one-off
* DD Latest date for recurring or final
* Latest date for Reversal
* Latest date for Returns
* Latest date for Refund (auth/notauth)
RJCTED05Settlement Failed
RJCTMD01Unauthorized Transaction
RJCTMD02Missing Mandatory Information Mandate
RJCTMD07End Customer Deceased
RJCTMS02Not Specified Reason Customer Generated
RJCTMS03Not Specified Reason Agent Generated
RJCTRC01PSP Identifier Incorrect
RJCTRR01Missing Debtor Account or Identification - Code used by PSPs to indicate a Return for Regulatory Reason
RJCTRR02Missing Debtor Name or Address - Code used by PSPs to indicate a Return for Regulatory Reason
RJCTRR03Missing Creditor Name or Address - Code used by PSPs to indicate a Return for Regulatory Reason
RJCTRR04Regulatory Reason
RJCTSL01Specific Service offered by Debtor PSP
RJCTBE05Unrecognized Initiating Party – Identifier of the Creditor Incorrect
RJCTPY01Unknown BIC in routing table - If the creditor agent is not an RB of the instructing agent or if DP/RB is not present in the routing table
RJCTFF01Operation/transaction code incorrect, invalid file format
RJCTXD19Invalid IBAN format - An IBAN in the transaction has failed the ISO 13616
RJCTXT13Unsupported XML field → The transaction contains at least one unsupported field; At least one mandatory field is not present the transaction. The offending XML tag is present with the error code (if available).
RJCTXT33Invalid data format - The content of at least one XML element is not in the required format. The offending XML tag is present with the error code.
RJCTXT73Invalid country code - The two characters for country code are not a valid ISO3166 country code.
RJCTXT74Invalid original transaction status, action required
RJCTXT75Invalid original transaction status, action not required
RJCTXT77The Interbank Settlement Amount is not the same as the original debit
RJCTXT78Check on compensation amount in refunds failed
RJCTXT79Debtor Agent not allowed to receive DD and consequently to receive Reversal and PCR. It is
also not allowed to send Return/Refund and Reject/Refusal - If the admission profile does not admit the sending of a DD or Participant in RONLY status, or the participant is not allowed to use an option (NLGO/ICMC).
RJCTXT80Creditor Agent not allowed to send DD and consequently to send Reversal and PCR. It is also not allowed to receive Return/Refund and Reject/Refusal - The Creditor Agent is not allowed to send Direct Debit as per the information available in the Routing Table, or the Participant is not allowed to use an option (NLGO/ICMC)
RJCTXT81Field not permitted in SDD Service
RJCTXT87R-Message not following same DP route/ sending DP not identical to Instructing / Instructed Agent of the original transaction
RJCTXT90Invalid use of a Technical BIC
RJCTXT91Creditor Agent or Debtor Agent of the original transaction is not allowed to be part of the SEPACOM Closed User Group

Virtual IBAN Services

Virtual IBAN services are a special solution for financial institutions to issue unique account numbers to underlying customers in their name.

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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanOpenRequest>
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[0..1]++ClientReference<ClientReference>Customer reference defined by Payment Service Provider. Can be used to avoid opening duplicate VIBANs.
[1..1]++User<User>
[0..1]+++Person<Person>Element of choice, used if Virtual IBAN owner is private person.
[1..1]++++Name<Name>First and last name of private person.
[1..1]++++BirthDate<BirthDate>Birth date of private person (YYYY-MM-DD).
[0..1]++++BirthCountry<BirthCountry>Country of birth of private person (ISO 3166-1 alpha-2).
[1..1]++++Residency<Residency>Country of residence of private person (ISO 3166-1 alpha-2).
[0..1]++++DocumentNumber<DocumentNumber>Document number of private person.
[0..1]+++Company<Company>Element of choice, used if Virtual IBAN owner is legal person.
[1..1]++++Name<Name>Name of company.
[1..1]++++CountryOfOrigin<CountryOfOrigin>Country of origin of legal person (ISO 3166-1 alpha-2).
[1..1]++++TaxResidency<TaxResidency>Tax residency of legal person (ISO 3166-1 alpha-2).
[1..1]++++RegistrationNumber<RegistrationNumber>Registration number of legal person.
[1..1]++++Representative<Representative>
[1..1]+++++Name<Name>First and last name of representative.
[1..1]+++++BirthDate<BirthDate>Birth date of representative, YYYY-MM-DD.
[1..1]+++++Residency<Residency>Country of residence of representative (ISO 3166-1 alpha-2).
[1..1]+++Address<Address>Address of virtual IBAN use
[1..1]++++Country<Country>Address country (ISO 3166-1 alpha-2).
[1..1]++++StreetNo<StreetNo>Street address.
[1..1]++++CityCounty<CityCounty>City, county.
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanOpenResponse>
[1..1]++MasterAccount<MasterAccount>
[0..1]++ClientReference<ClientReference>Customer reference defined by Payment Service Provider.
[1..1]++VirtualIBAN<VirtualIBAN>Virtual IBAN that was generated.
[1..1]++User<User>
[0..1]+++Person<Person>Element of choice, used if Virtual IBAN owner is private person.
[1..1]++++Name<Name>First and last name of private person.
[1..1]++++BirthDate<BirthDate>Birth date of private person (YYYY-MM-DD).
[0..1]++++BirthCountry<BirthCountry>Country of birth of private person (ISO 3166-1 alpha-2).
[1..1]++++Residency<Residency>Country of residence of private person (ISO 3166-1 alpha-2).
[0..1]++++DocumentNumber<DocumentNumber>Document number of private person.
[0..1]+++Company<Company>Element of choice, used if Virtual IBAN owner is legal person.
[1..1]++++Name<Name>Name of company.
[1..1]++++CountryOfOrigin<CountryOfOrigin>Country of origin of legal person (ISO 3166-1 alpha-2).
[1..1]++++TaxResidency<TaxResidency>Tax residency of legal person (ISO 3166-1 alpha-2).
[1..1]++++RegistrationNumber<RegistrationNumber>Registration number of legal person.
[1..1]++++Representative<Representative>
[1..1]+++++Name<Name>First and last name of representative.
[1..1]+++++BirthDate<BirthDate>Birth date of representative, YYYY-MM-DD.
[1..1]+++++Residency<Residency>Country of residence of representative (ISO 3166-1 alpha-2).
[1..1]+++Address<Address>
[1..1]++++Country<Country>Address country (ISO 3166-1 alpha-2).
[1..1]++++StreetNo<StreetNo>Street address.
[1..1]++++CityCounty<CityCounty>City, county.
[1..1]++Status<Status>Status of Virtual IBAN: 'ACTIVE' or 'ON_HOLD'.
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanBulkRequest>
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[1..1]++Amount<Amount>Amount of Virtual IBANs to be generated. Must be in range of 1 - 1000.
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanBulkResponse>
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[1..1]++VirtualIBANList<VirtualIBANList>
[1..n]++VirtualIBAN<VirtualIBAN>Virtual IBAN that was generated.
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
  • If Virtual IBAN status is not "PENDING" you must provide the reason for change in the ModifyReason tag.
  • Any modifiactions will trigger re-screening of the Virtual IBAN

Request

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanModifyRequest>
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[0..1]++ClientReference<ClientReference>Customer reference defined by Payment Service Provider. Can be used to avoid opening duplicate VIBANs.
[1..1]++VirtualIBAN<VirtualIBAN>Virtual IBAN (must be nameless Virtual IBAN in PENDING status).
[1..1]++User<User>
[0..1]+++Person<Person>Element of choice, used if Virtual IBAN owner is private person.
[1..1]++++Name<Name>First and last name of private person.
[1..1]++++BirthDate<BirthDate>Birth date of private person (YYYY-MM-DD).
[0..1]++++BirthCountry<BirthCountry>Country of birth of private person (ISO 3166-1 alpha-2).
[1..1]++++Residency<Residency>Country of residence of private person (ISO 3166-1 alpha-2).
[0..1]++++DocumentNumber<DocumentNumber>Document number of private person.
[0..1]+++Company<Company>Element of choice, used if Virtual IBAN owner is legal person.
[1..1]++++Name<Name>Name of company.
[1..1]++++CountryOfOrigin<CountryOfOrigin>Country of origin of legal person (ISO 3166-1 alpha-2).
[1..1]++++TaxResidency<TaxResidency>Tax residency of legal person (ISO 3166-1 alpha-2).
[1..1]++++RegistrationNumber<RegistrationNumber>Registration number of legal person.
[1..1]++++Representative<Representative>
[1..1]+++++Name<Name>First and last name of representative.
[1..1]+++++BirthDate<BirthDate>Birth date of representative, YYYY-MM-DD.
[1..1]+++++Residency<Residency>Country of residence of representative (ISO 3166-1 alpha-2).
[1..1]+++Address<Address>
[1..1]++++Country<Country>Address country (ISO 3166-1 alpha-2).
[1..1]++++StreetNo<StreetNo>Street address.
[1..1]++++CityCounty<CityCounty>City, county.
[0..1]++ModifyReason<ModifyReason>Reason for modification (mandatory if Virtual IBAN is not in PENDING status).
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanModifyResponse>
[0..1]++ClientReference<ClientReference>Customer reference defined by Payment Service Provider.
[1..1]++VirtualIBAN<VirtualIBAN>
[1..1]++User<User>
[0..1]+++Person<Person>Element of choice, used if Virtual IBAN owner is private person.
[1..1]++++Name<Name>First and last name of private person.
[1..1]++++BirthDate<BirthDate>Birth date of private person (YYYY-MM-DD).
[0..1]++++BirthCountry<BirthCountry>Country of birth of private person (ISO 3166-1 alpha-2).
[1..1]++++Residency<Residency>Country of residence of private person (ISO 3166-1 alpha-2).
[0..1]++++DocumentNumber<DocumentNumber>Document number of private person.
[0..1]+++Company<Company>Element of choice, used if Virtual IBAN owner is legal person.
[1..1]++++Name<Name>Name of company.
[1..1]++++CountryOfOrigin<CountryOfOrigin>Country of origin of legal person (ISO 3166-1 alpha-2).
[1..1]++++TaxResidency<TaxResidency>Tax residency of legal person (ISO 3166-1 alpha-2).
[1..1]++++RegistrationNumber<RegistrationNumber>Registration number of legal person.
[1..1]++++Representative<Representative>
[1..1]+++++Name<Name>First and last name of representative.
[1..1]+++++BirthDate<BirthDate>Birth date of representative, YYYY-MM-DD.
[1..1]+++++Residency<Residency>Country of residence of representative (ISO 3166-1 alpha-2).
[1..1]+++Address<Address>
[1..1]++++Country<Country>Address country (ISO 3166-1 alpha-2).
[1..1]++++StreetNo<StreetNo>Street address.
[1..1]++++CityCounty<CityCounty>City, county.
[1..1]++Status<Status>Status of Virtual IBAN: 'ACTIVE' or 'ON_HOLD'.
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanInfoRequest>
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[1..1]++VirtualIBAN<VirtualIBAN>Virtual IBAN (must be issued under MasterAccount specified).
Sample
<?xml version="1.0" encoding="UTF-8"?>
<VibanInfoRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
</VibanInfoRequest>

Response

Header Message-Response-Type: VIBAN_INFO

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanInfoResponse>
[0..1]++ClientReference<ClientReference>Customer reference defined by Payment Service Provider.
[1..1]++VirtualIBAN<VirtualIBAN>
[1..1]++User<User>
[0..1]+++Person<Person>Element of choice, used if Virtual IBAN owner is private person.
[1..1]++++Name<Name>First and last name of private person.
[1..1]++++BirthDate<BirthDate>Birth date of private person (YYYY-MM-DD).
[0..1]++++BirthCountry<BirthCountry>Country of birth of private person (ISO 3166-1 alpha-2).
[1..1]++++Residency<Residency>Country of residence of private person (ISO 3166-1 alpha-2).
[0..1]++++DocumentNumber<DocumentNumber>Document number of private person.
[0..1]+++Company<Company>Element of choice, used if Virtual IBAN owner is legal person.
[1..1]++++Name<Name>Name of company.
[1..1]++++CountryOfOrigin<CountryOfOrigin>Country of origin of legal person (ISO 3166-1 alpha-2).
[1..1]++++TaxResidency<TaxResidency>Tax residency of legal person (ISO 3166-1 alpha-2).
[1..1]++++RegistrationNumber<RegistrationNumber>Registration number of legal person.
[1..1]++++Representative<Representative>
[1..1]+++++Name<Name>First and last name of representative.
[1..1]+++++BirthDate<BirthDate>Birth date of representative, YYYY-MM-DD.
[1..1]+++++Residency<Residency>Country of residence of representative (ISO 3166-1 alpha-2).
[1..1]+++Address<Address>
[1..1]++++Country<Country>Address country (ISO 3166-1 alpha-2).
[1..1]++++StreetNo<StreetNo>Street address.
[1..1]++++CityCounty<CityCounty>City, county.
[1..1]++Status<Status>Status of Virtual IBAN: 'ACTIVE', 'ON_HOLD', 'PENDING', 'REJECTED', 'BLOCKED' or 'CLOSED'.
[0..1]++DateActivated<DateActivated>Optional. Added if Virtual IBAN has been in activated.
[0..1]++DateClosed<DateClosed>Optional. Added if Virtual IBAN has beel closed.
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanCloseRequest>
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[1..1]++VirtualIBAN<VirtualIBAN>Virtual IBAN (must be issued under MasterAccount specified).
Sample
<?xml version="1.0" encoding="UTF-8"?>
<VibanCloseRequest>
  <MasterAccount>EE837700771001625166</MasterAccount>
  <VirtualIBAN>EE717777000200014007</VirtualIBAN>
</VibanCloseRequest>

Response

Header Message-Response-Type: VIBAN_CLOSE

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanCloseResponse>
[1..1]++VirtualIBAN<VirtualIBAN>
[1..1]++Status<Status>'CLOSED'
[1..1]++DateClosed<DateClosed>Date and time of closing.
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

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<VibanStatusNotification>
[0..1]++ClientReference<ClientReference>Customer reference defined by Payment Service Provider.
[1..1]++MasterAccount<MasterAccount>Master account IBAN (must belong to PSP).
[1..1]++VirtualIBAN<VirtualIBAN>Virtual IBAN (must be issued under MasterAccount specified).
[1..1]++User<User>
[0..1]+++Person<Person>Element of choice, used if Virtual IBAN owner is private person.
[1..1]++++Name<Name>First and last name of private person.
[1..1]++++BirthDate<BirthDate>Birth date of private person (YYYY-MM-DD).
[0..1]++++BirthCountry<BirthCountry>Country of birth of private person (ISO 3166-1 alpha-2).
[1..1]++++Residency<Residency>Country of residence of private person (ISO 3166-1 alpha-2).
[0..1]++++DocumentNumber<DocumentNumber>Document number of private person.
[0..1]+++Company<Company>Element of choice, used if Virtual IBAN owner is legal person.
[1..1]++++Name<Name>Name of company.
[1..1]++++CountryOfOrigin<CountryOfOrigin>Country of origin of legal person (ISO 3166-1 alpha-2).
[1..1]++++TaxResidency<TaxResidency>Tax residency of legal person (ISO 3166-1 alpha-2).
[1..1]++++RegistrationNumber<RegistrationNumber>Registration number of legal person.
[1..1]++++Representative<Representative>
[1..1]+++++Name<Name>First and last name of representative.
[1..1]+++++BirthDate<BirthDate>Birth date of representative, YYYY-MM-DD.
[1..1]+++++Residency<Residency>Country of residence of representative (ISO 3166-1 alpha-2).
[1..1]+++Address<Address>
[1..1]++++Country<Country>Address country (ISO 3166-1 alpha-2).
[1..1]++++StreetNo<StreetNo>Street address.
[1..1]++++CityCounty<CityCounty>City, county.
[1..1]++Status<Status>Status of Virtual IBAN: 'ACTIVE', 'ON_HOLD', 'PENDING', 'REJECTED', 'BLOCKED' or 'CLOSED'.
[0..1]++DateActivated<DateActivated>Optional. Added if Virtual IBAN has been in activated.
[0..1]++DateClosed<DateClosed>Optional. Added if Virtual IBAN has beel closed.
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>

Virtual IBAN Error Codes

ErrorCodeDescriptionField
'INVALID_REQUEST'Invalid request.-
'TECHNICAL_ERROR'Technical error.-
'FORBIDDEN'Unauthorized master account.<MasterAccount>
'FORBIDDEN'Unauthorized virtual IBAN.<VirtualIBAN>
'INVALID_ACCOUNT'Account does not exist.<MasterAccount>
'INVALID_BIRTH_DATE'Birth date format is YYYY-MM-DD.
Birth date cannot be in the future.
<BirthDate>
'INVALID_COUNTRY'Unknown country.<BirthCountry>
<Residency>
<CountryOfOrigin>
<TaxResidency>
<Country>
'INVALID_STATUS'Virtual IBAN has to be in ACTIVE / PENDING / BLOCKED status.
Virtual IBAN has to be in ACTIVE / PENDING / ON_HOLD status.
<VirtualIBAN>
'INVALID_VIBAN'Virtual IBAN does not exist.<VirtualIBAN>
'MASTER_ACCOUNT_AGREEMENT_MISSING'Active master account agreement is missing.<MasterAccount>
'INVALID_REASON'Reason for the change is missing.
Reason for the change is not allowed when status is PENDING.
<ModifyReason>
'INVALID_USER_TYPE'Changing user type is not allowed.<User>
'INVALID_CLIENT_REFERENCE'Client reference number must be unique.
Client reference number change is not allowed.
<ClientReference>

Indirect Scheme Access

Services for Indirect Scheme Access Account management for service providers with a valid Indirect Scheme Access Service agreement.

We offer this service for FPS (Faster Payments scheme) for customers opened bank account (IBAN) with LHV UK branch and following SEPA schemes for customers opened bank account (IBAN) with LHV Pank: SEPA Credit Transfers (scheme STEP2 SCT), SEPA Instant payments (Scheme RT1 and TIPS), SEPA direct debits (scheme STEP2 SDD CORE ).

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.

Usage of Bank Codes

Bank Codes is optional list of one or two Codes that indicate if any account number should by synced with LHV EE, LHV UK or both! This depends on the customer setup and business case.
This can be used only when connected to LHV UK Connect API host.

  • when Bank Codes list is not added, it is processed in LHV EE
  • when Bank Code contains LHVBEE22 or LHVBEE22XXX, it is processed in LHV EE
  • when Bank Code contains LHVBGB2L or LHVBGB2LXXX, it is processed in LHV UK
  • when Bank Code contains bot LHVBGB2L or LHVBGB2LXXX and LHVBGB2L or LHVBGB2LXXX, it is processed both in LHV UK and LHV EE
  • when Bank Code contains is added, but not in the mentioned list, it is processed in LHV UK by default, but account sync is rejected

Request

Message structure
MULT.MESSAGE ELEMENTXML TAGDescription
[1..1]+MessageRoot<AgentAccountSyncRequest>
[0..1]++BankCodes<BankCodes>List of LHV bank codes where to sync the account. To be used only for LHV UK Connect API host
[1..2]+++BankCode<BankCode>* LHVBEE22 or LHVBEE22XXX - use for LHVEE
* LHVBGB2L or LHVBGB2LXXX - use for LHVUK
[1..1]++Accounts<Accounts>List of accounts
[1..1]+++Region<Region>'GB' or ISO country code (SEPA Scheme Country) used in IBAN.
[0..1]+++AccountNo<AccountNo>For 'GB' region UK sort code + account no (14 characters). AccountNo or IBAN or both can exist. AccountNo's for other regions than 'GB' are ignored.
[0..1]+++Iban<Iban>IBAN country code must match the value of Region. The BIC code to which the IBAN refers must have a valid Agency agreement.
[0..1]+++Status<Status>Values 'ACTIVE' or 'CLOSED'. If new account is synced and field is empty, default value 'ACTIVE' is applied. If existing account update and field is empty, existing status is not changed. Status can be changed from ACTIVE to CLOSED and vice versa.

Sample

Synchronization request for UK account numbers

Simplest version where two accounts are opened in default LHV entity:

<?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>
Synchronization request with Bank Codes

Account is synced to LHV UK - BankCode = LHVBGB2L

<?xml version="1.0" encoding="UTF-8"?>
<AgentAccountSyncRequest>
    <BankCodes>
      <BankCode>LHVBGB2L</BankCode>
    </BankCodes>
    <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>

Account is synced both to LHV UK and LHV EE

<?xml version="1.0" encoding="UTF-8"?>
<AgentAccountSyncRequest>
    <BankCodes>
      <BankCode>LHVBGB2L</BankCode>
      <BankCode>LHVBEE22</BankCode>
    </BankCodes>
    <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

Message structure
MESSAGE ELEMENTXML TAGDescription
+MessageRoot<AgentAccountSyncResponse>
++Accounts<Accounts>
+++Account<Account>
+++Region<Region>
+++AccountNo<AccountNo>Filled if existed in request.
+++Iban<Iban>Filled if existed in request.
+++Status<Status><ACTIVE>

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.

ERROR CODEDESCRIPTION
​INVALID_REGIONInvalid Region.
INVALID_ACCOUNT_NO_OR_IBANAccount number invalid.
ACCOUNT_NO_AND_IBAN_MISMATCHAccountNo and AccountNoIban mismatch.
INVALID_IBANInvalid IBAN.
MASTER_ACCOUNT_NOT_FOUNDMaster account not found.
TECHNICAL_ERRORTechnical error.
INVALID_REQUESTInvalid request.

RTF - Routing Table Files

Routing Table Files (RTF) include the set of direct and indirect payment scheme participants.

Header Message-Response-Type: AGENT_REPORT

Messages appear in the Connect message queue depending on payment scheme. Customer cannot request for the files directly.
All files are sent in machine-readable format and are full files. Only RT1 RTF are sent gzip-ed.
Content type property in the message indicates the payment scheme:

  • application/vnd.lhv.step2.in.rtf – STEP2 SCT indirect participants > Example here
  • application/vnd.lhv.step2.di.rtf - STEP2 SCT direct participants > Example here
  • application/vnd.lhv.rt1.in.rtf+gzip - RT1 indirect participants > Example here
  • application/vnd.lhv.rt1.di.rtf+gzip - RT1 direct participants > Example here
  • application/vnd.lhv.sdd.in.rtf - STEP2 SDD CORE indirect participants > Example here
  • application/vnd.lhv.sdd.di.rtf - STEP2 SDD CORE indirect participants > Example here
  • application/vnd.lhv.tips.rtf – TIPS indirect and direct participants > Example here
  • application/vnd.lhv.t2.rtf – all Target2 participants > Example here

RTF files are available for following schemes:

  • RT1 - files are sent each time RTF is updated. Change occurs on a weekly basis. RTFs are sent before each change date. By default, the change date is Tuesday and normally RTFs are sent on Monday.
    For RT1 there will be 2 RTFs- for direct and indirect participants.
    RTF contents: participant BIC, name, date from which BIC is valid, date until which BIC is valid, BIC of the associated direct participant in case of indirect membership, TIPS account owner BIC, current status and payment types allowed.

  • TIPS - RTF is sent every day. There is one file which includes direct and indirect participants.
    RTF contents: participant BIC, name, date from which BIC is valid, date until which BIC is valid, TIPS BIC, TIPS account owner BIC, current status and payment types allowed.

  • STEP2 SCT - files are sent each time RTF is updated. Change occurs once a month. RTFs are sent week before change date. By default the change date is Tuesday and normally RTFs are sent on Monday
    For STEP2 SCT there will be 2 RTFs- for direct and indirect participants.
    RTF contents: participant BIC, name, date from which BIC is valid, date until which BIC is valid, BIC of the associated direct participant in case of indirect membership, settlement BIC, current status and payment types allowed.

  • STEP2 SDD CORE - files are sent each time RTF is updated. Change occurs once a month. RTFs are sent week before change date. By default the change date is Tuesday and normally RTFs are sent on Monday
    For STEP2 SDD CORE there will be 2 RTFs- for direct and indirect participants.
    RTF contents: participant BIC, name, date from which BIC is valid, date until which BIC is valid, BIC of the associated direct participant in case of indirect membership, settlement BIC, current status, admission profile and debit types allowed.

  • Target2 - RTF is sent every business day. There is one file which includes all direct and indirect participants.
    RTF contents: participant BIC, addressee BIC, account BIC, institution name, city, valid from/to, participation type.

Foreign Exchange

Services related to Foreign Exchange (FX).

Current functionality covers FX tenors TODAY and SPOT directly on the customer account.

FX transactions and settlement

  • FX conversion is done directly on customers multi-currency account. The "from" amount in sold currency decreases and "to" amount in bought currency increases.
  • customer should first initiate the FX deal by requesting a quote with Request FX Trade Offer service
  • if all the input parameters are valid and there are enough funds on the account customer can confirm the returned quote with Confirm FX Trade Offer service
  • Sold amount in sold currency is reserved on the account until settlement is completed - reducing the available balance.
  • TODAY settlement is executed in seconds after the confirmation request.
  • SPOT settlement is executed in the first hour of the settlement date according to Estonian time zone.
  • Settled FX transactions on the payment account are visible in Account Statement and Debit-Credit Notification messages.
  • not all provided FX currencies can be transferred to other banks. Please check our payment schemes and correspondent bank networks for this.

FX rates and margin

  • We are using Base currency in the API messages that specifies the explicit direction of the rate - it does not depend on what currency is sold or bought!
For example if base currency is EUR and EUR/USD rate is 1.12:
* FX from 100 EUR to 112 USD: (from amount) x (rate) = (to amount)
* FX from 100 USD to 89.29 EUR: (to amount) x (rate) = (from amount)
  • FX rate is calculated automatically based on real-time FX rates from the market and includes the LHV margin agreed with the customer. FX rate components and calculation is not included in the API messages.

Request FX Trade Offer

POST [base-url]/fx/trade-offer

Initiate creation of new FX trade offer.

  • Validity time (validityTime tag) of the offer depends on the actual deal and pricing conditions from our FX partners, but is typically around 2 minutes. When the time is exceeded the offer cannot be accepted and you must submit a new one.
  • Customer account validity and available balance is checked before providing the quote to the customer

Request

Body in JSON format.

FieldTypeComment
requestReferenceStringCustomer provided request reference. Can be used for uniqueness check
accountIBANStringCustomer account in IBAN format
currencyFromStringSelling currency
currencyToStringBuying currency
amountFromnumberSelling amount - providing one of amountFrom or amountTo is mandatory
amountTonumberBuying amount - providing one of amountFrom or amountTo is mandatory
commentStringComment related to the deal
tenorStringFX deal tenor: TODAY or SPOT
Sample
// Sell TODAY

{
    "requestReference": 1234005,
    "accountIBAN": "EE337700771001260958",
    "currencyFrom": "GBP",
    "currencyTo": "USD",
    "amountFrom": 1,
    "amountTo": null,
    "comment": "test1",
    "tenor": "TODAY"
}

// Buy SPOT

{
    "requestReference": "12345678",
    "accountIBAN": "EE123456781234",
    "currencyFrom": "EUR",
    "currencyTo": "GBP",
    "amountFrom": null,
    "amountTo": 1,
    "comment": "test1",
    "tenor": "SPOT",
}

Response

Response is in JSON format and returned in the common message queue.

FieldTypeComment
requestReferenceStringCustomer reference.
accountIBANStringCustomer account in IBAN format
currencyFromStringSelling currency
amountFromnumberSelling amount
currencyTonumberBuying currency
amountToStringBuying amount
baseCurrencyStringBase currency. Selected automatically based on the currency pair.
orderDateTimeDateTimeTime of submitting the order.
tradeDateDateTimeTrade date (with last minute and second)
settlementDateDateTimeSettlement date (with last minute and second).
tenorStringFX deal tenor
quotenumberOffered quote rate. Direction is based on baseCurrency: baseCurrency amount * quote = quote Currency amount.
tradeOfferStatusStringState of the offer.
* CONFIRMATION_PENDING - deal can be confirmed.
* CANCELLED - error in parameters or processing and deal cannot be confirmed.
commentStringComment related to the deal
accountServicerReferenceStringFX deal reference provided by the Bank
validityTimeDateTimeQuote offer validity time. Offer should be confirmed before this.
Sample
{
	"requestReference": "1234005",
	"accountIban": "EE337700771001260958",
	"currencyFrom": "GBP",
	"amountFrom": 1.0,
	"currencyTo": "USD",
	"amountTo": 1.32,
	"baseCurrency": "GBP",
	"orderDateTime": "2021-12-15T14:35:20.303+02:00",
	"tradeDate": "2021-12-15T23:59:59+02:00",
	"settlementDate": "2021-12-15T23:59:59+02:00",
	"tenor": "TODAY",
	"quote": 1.32031,
	"tradeOfferStatus": "CONFIRMATION_PENDING",
	"comment": "test1",
	"accountServicerReference": "044eeef9-e1f9-46cb-87ae-4cdf85165b19",
	"validityTime": "2021-12-15T14:38:20.658+02:00"
}

Confirm FX Trade Offer

POST [base-url]/fx/trade-offer-confirmation

Confirm the trade offer initiated with POST [base-url]/fx/trade-offer

Request

Body in JSON format.

FieldTypeComment
requestReferenceStringCustomer reference.
confirmString* true - confirm the offer.
* false - reject the offer. It cannot be confirmed anymore even with validity time left.
Sample
{
    "requestReference": "1234005",
    "confirm": true
}

Response

Response is in JSON format and returned in the common message queue.

FieldTypeComment
tradeStatusStringState of the offer.
* SETTLEMENT_PENDING - deal confirmed and waiting for settlement.
* COMPLETED - settlement completed.
* CANCELLED - error in parameters or processing and deal cannot be confirmed.
accountIBANStringCustomer account in IBAN format
requestReferenceStringCustomer reference.
currencyFromStringSelling currency
amountFromnumberSelling amount
currencyTonumberBuying currency
amountToStringBuying amount
baseCurrencyStringBase currency. Selected automatically based on the currency pair.
tenorStringFX deal tenor
quotenumberOffered quote rate. Direction is based on baseCurrency: baseCurrency amount * quote = quote Currency amount.
orderDateTimeDateTimeTime of submitting the order.
tradeDateDateTimeTrade date (with last minute and second)
settlementDateDateTimeSettlement date (with last minute and second).
settlementDoneDateTimeDateTimeFilled in when settlement executed.
commentStringComment related to the deal
accountServicerReferenceStringUnique FX deal reference provided by the Bank
pmtInfIdStringFX deal reference provided by the bank to relate transaction on the account to FX deal. Matches pmtInfId value in Account Statement and Debit-Credit Notification messages.
Sample
{
	"tradeStatus": "COMPLETED",
	"accountIban": "EE337700771001260958",
	"requestReference": "1234005",
	"currencyFrom": "GBP",
	"amountFrom": 1.0,
	"currencyTo": "USD",
	"amountTo": 1.32,
	"baseCurrency": "GBP",
	"tenor": "TODAY",
	"quote": 1.32031,
	"orderDateTime": "2021-12-15T14:35:20.303+02:00",
	"tradeDate": "2021-12-15T23:59:59+02:00",
	"settlementDate": "2021-12-15T23:59:59+02:00",
	"settlementDoneDateTime": "2021-12-15T14:35:49.123+02:00",
	"comment": "test1",
	"accountServicerReference": "044eeef9-e1f9-46cb-87ae-4cdf85165b19",
	"pmtInfId": 10357175
}

Errors

FX messages errors are typically represented on errorcode field in the response messages

  • With technical errors only error message is returned.
  • With business logical errors also trade offer dataset with cancelled status and respective error is returned
Not enough funds for the deal

In this case there is not enough free balance on customers account.

{
    "requestReference": "12345629",
    "accountIban": "EE33770077100xxxxxxx",
    "currencyFrom": "AUD",
    "amountFrom": 100000000.0,
    "currencyTo": "EUR",
    "amountTo": 68965517.24,
    "baseCurrency": "EUR",
    "orderDateTime": "2022-02-14T15:53:39.308254+02:00",
    "tradeDate": "2022-02-14T23:59:59+02:00",
    "settlementDate": "2022-02-14T23:59:59+02:00",
    "tenor": "TODAY",
    "quote": 1.45,
    "tradeOfferStatus": "CANCELLED",
    "comment": "testkommentaar",
    "accountServicerReference": "43eabe9c-0bf8-4543-ac19-e0b4452686d3",
    "errorCode": [
        "Conversion not possible, because there are no funds for currency (100000000.00 AUD -> 68965517.24 EUR, 1.45000)"
    ]
}
Not enough parameters

One or more of the mandatory parameters are missing. In this sample there is no amount from or amount to.

{
  "requestReference": "000111222334455888990011",
  "accountIban": "EE317700771001316284",
  "currencyFrom": "USD",
  "currencyTo": "EUR",
  "baseCurrency": "EUR",
  "orderDateTime": 1642360063.081324000,
  "tradeDate": 1642370399.000000000,
  "tenor": "TODAY",
  "tradeOfferStatus": "CANCELLED",
  "comment": "test",
  "accountServicerReference": "40f04bb2-cc3a-4bc3-8b82-67f55a3421d9",
  "errorCode": [
    "At least one amount for the trade must be given"
  ]
}
Parameter type related errors

In this sample requestReference is not string. Other fields might be also impacted.

{
  "errorCode": [
    "Invalid numeric value: Leading zeroes not allowed\n at [Source: (String)\"{\n  \"requestReference\": 000111222334455,\n  \"accountIBAN\": \"EE317700771001316284\",\n
  \"currencyFrom\": \"USD\",\n  \"amountFrom\": 100,\n  \"currencyTo\": \"EUR\",\n  \"tenor\": \"TODAY\",\n  \"comment\": \"test\"\n}\"; line: 2, column: 24]"
  ]
}
Trade offer quote has expired

Trade offer validity time is expired.

{"errorCode":["Trade offer quote has expired"]}
Account is incorrect or not available

Account does not exist or is not accessible for current customer.

{"errorCode":["Incorrect Account"]}
Pricing not available

In this case the pricing feed is not available. It might be a temporary error and should be retried after a while.

{"errorCode":["Pricing not available, try again later"]}
Other errors

This is typically some internal technical error and please contact our support.

{"errorCode":[""INTERNAL_ERROR"]}

Merchant Payment Report

Request Merchant Payment Report

POST [base-url]/acq/merchant-report

Service can be used to get an overview about customer (merchant) card payments during the specified period.

Request message

MULT.MESSAGE ELEMENTXML TAGDESCRIPTION
[1..1]+MerchantReportRequest<MerchantReportRequest>
[1..1]++Type<Type>CAMT_SETTLEMENT – settlement report CAMT_TRANSACTION – transaction report
[1..1]++PeriodStart<PeriodStart>Maximum period is 35 days by date when transaction was settled or made.
[1..1]++PeriodEnd<PeriodEnd>

Sample

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

Response Merchant Payment Report

XML format - ISO 20022 camt.054.001.02

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

INDEXMESSAGE ELEMENTXML TAG
[1..1]MessageRoot<BkToCstmrDbtCdtNtfctn>

Group header

INDEXMULT.ORMESSAGE ELEMENTXML TAGDESCRIPTION
1.0[1..1]+GroupHeader<GrpHdr>
1.1[1..1]++MessageIdentification<MsgId>Unique message identifier generated by LHV.
1.2[1..1]++CreationDateTime<CreDtTm>Date and time when the message is created at LHV.
2.0[1..n]+Notification<Ntfctn>
2.1[1..1]++Identification<Id>Unique identifier generated by LHV.
2.4[1..1]++CreationDateTime<CreDtTm>Date and time when the message is created at LHV.
2.10[1..1]++Account<Acct>
[1..1]+++ Identification<Id>
[1..1]++++IBAN<IBAN>IBAN for which this notification block is generated.
[1..1]+++Currency<Ccy>Currency for which this notification block is generated.
2.23[0..1]++TransactionSummary<TxsSummry>
2.29[1..1]+++TotalCreditEntries<TtlCdtNtries>
2.30[1..1]++++NumberOfEntries<NbOfNtries>
2.31[1..1]++++Sum<Sum>
2.32[1..1]+++TotalDebitEntries<TtlDbtNtries>
2.33[1..1]++++NumberOfEntries<NbOfNtries>
2.34[1..1]++++Sum<Sum>
2.56[0..n]++Entry<Ntry>Transaction level entry.
2.57[0..1]+++EntryReference<NtryRef>Unique transaction reference.
2.58[1..1]+++Amount<Amt Ccy="AAA">Transaction amount (may be zero).
2.59[1..1]+++CreditDebitIndicator<CdtDbtInd>Zero amount is considered a credit amount.
2.61[1..1]+++Status<Sts>BOOK.
2.62[1..1]+++BookingDate<BookgDt>
[1..1]++++Date<Dt>Transaction date.
2.63[0..1]+++ValueDate<ValDt>
[1..1]++++Date<Dt>Transaction settlement date.
2.64[1..1]+++AccountServicerReference<AcctSvcrRef>Unique transaction reference. Same as 2.57 +++EntryReference.
2.71[1..1]+++BankTransactionCode<BkTxCd>
2.72[1..1]++++Domain<Domn>
2.73[1..1]+++++Code<Cd>See the codes in Code Set: Bank Transaction Codes.
2.74[1..1]+++++Family<Fmly>
2.75[1..1]++++++Code<Cd>See the codes in Code Set: Bank Transaction Codes.
2.76[1..1]++++++SubFamilyCode<SubFmlyCd>See the codes in Code Set: Bank Transaction Codes.
2.77[0..1]++++Proprietary<Prtry>
2.78[1..1]+++++Code<Cd>POS terminal id.
2.115[1..n]+++EntryDetails<NtryDtls>
2.122[1..n]++++TransactionDetails<TxDtls>
2.123[1..1]+++++References<Refs>
2.125[0..1]++++++AccountServicerReference<AcctSvcrRef>Only present if EveryPay Card transaction Order reference is defined or POS-terminal transaction field DE47 subfield 95 is filled with reference, else NULL.
2.131[0..1]++++++ChequeNumber<ChqNb>STAN.
2.133[0..1]++++++Proprietary<Prtry>
2.134[1..1]+++++++Type<Tp>PAN. 7-12 positions are masked.
2.135[1..1]+++++++Reference<Ref>Merchant branch ID (MID).
2.136[1..1]+++++AmountDetails<AmtDtls>
[1..1]++++++TransactionAmount<TxAmt>
2.141[1..1]+++++++Amount<Amt Ccy="AAA">Transaction amount (may be zero).
2.152[0..n]++++++Charges<Chrgs>
2.154[1..1]+++++++Amount<Amt>Transaction fee amount.
2.179[0..1]+++++RelatedParties<RltdPties>
2.181[0..1]++++++Debtor<Dbtr>If CreditDebitIndicator=DBIT, then Debtor block is filled.
[0..1]+++++++Name<Nm>Remitter’s name.
2.182[0..1]++++++DebtorAccount<DbtrAcct>
+++++++Identification<Id>
[1..1]{Or++++++++IBAN<IBAN>Remitter’s account number.
[1..1]Or}++++++++Other<Othr>
[1..1]+++++++++Identification<Id>Remitter’s account number which is not IBAN.
2.184[0..1]++++++Creditor<Cdtr>If CreditDebitIndicator=CRDT, then Creditor block is filled.
[0..1]+++++++Name<Nm>Creditor’s name.
2.185++++++CreditorAccount<CdtrAcct>
+++++++Identification<Id>
[1..1]{Or++++++++IBAN<IBAN>Creditor’s IBAN.
[1..1]Or}++++++++Other<Othr>
[1..1]+++++++++Identification<Id>Creditor’s account number which is not IBAN.
2.191+++++RelatedAgents<RltdAgts>
2.192++++++DebtorAgent<DbtrAgt>
+++++++FinancialInstitutionIdentification<FinInstnId>
++++++++Name<Nm>Financial institution identifier.
2.214+++++RemittanceInformation<RmtInf>
2.215++++++Unstructured<Ustrd>Merchant branch name and location where transaction was made.

Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.054.001.02">
    <BkToCstmrDbtCdtNtfctn>
        <GrpHdr>
            <MsgId>625402016031520160315</MsgId>
            <CreDtTm>2016-03-15T17:17:56</CreDtTm>
        </GrpHdr>
        <Ntfctn>
            <Id>625402016031520160315EUR</Id>
            <CreDtTm>2016-03-15T17:17:56</CreDtTm>
            <FrToDt>
                <FrDtTm>2016-03-15T00:00:00.000</FrDtTm>
                <ToDtTm>2016-03-15T00:00:00.000</ToDtTm>
            </FrToDt>
            <Acct>
                <Id>
                    <IBAN>EE777700771000845879</IBAN>
                </Id>
                <Ccy>EUR</Ccy>
            </Acct>
            <TxsSummry>
                <TtlCdtNtries>
                    <NbOfNtries>1</NbOfNtries>
                    <Sum>84.26</Sum>
                </TtlCdtNtries>
                <TtlDbtNtries>
                    <NbOfNtries>0</NbOfNtries>
                    <Sum>0.00</Sum>
                </TtlDbtNtries>
            </TxsSummry>
            <Ntry>
                <NtryRef>4904</NtryRef>
                <Amt Ccy="EUR">83.030000</Amt>
                <CdtDbtInd>CRDT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2016-01-15</Dt>
                </BookgDt>
                <ValDt>
                    <Dt>2016-03-15</Dt>
                </ValDt>
                <AcctSvcrRef>4904</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>MCDR</Cd>
                            <SubFmlyCd>POSP</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>87654321 001</Cd>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <Refs>
                            <AcctSvcrRef>4904</AcctSvcrRef>
                            <ChqNb>12345</ChqNb>
                            <Prtry>
                                <Tp>532610******3339</Tp>
                                <Ref>1234567</Ref>
                            </Prtry>
                        </Refs>
                        <AmtDtls>
                            <TxAmt>
                                <Amt Ccy="EUR">84.26</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <Chrgs>
                            <Amt Ccy="EUR">1.230000</Amt>
                        </Chrgs>
                        <RltdPties>
                            <Dbtr>
                                <Nm>Legal Merchant</Nm>
                            </Dbtr>
                            <DbtrAcct>
                                <Id>
                                    <IBAN>EE777700771000845879</IBAN>
                                </Id>
                            </DbtrAcct>
                            <Cdtr>
                                <Nm>Legal Merchant</Nm>
                            </Cdtr>
                            <CdtrAcct>
                                <Id>
                                    <IBAN>EE777700771000845879</IBAN>
                                </Id>
                            </CdtrAcct>
                        </RltdPties>
                        <RltdAgts>
                            <DbtrAgt>
                                <FinInstnId>
                                    <Nm>689MC</Nm>
                                </FinInstnId>
                            </DbtrAgt>
                        </RltdAgts>
                        <RmtInf>
                            <Ustrd>www.abcdef.com \Tallinn \10116 ESTEST</Ustrd>
                        </RmtInf>
                    </TxDtls>
                </NtryDtls>
            </Ntry>
        </Ntfctn>
    </BkToCstmrDbtCdtNtfctn>
</Document>

Error codes

ERROR CODEDESCRIPTION
errMerchantReport_TechnicalErrorUnexpected error while composing merchant report response
errMerchantReport_InvalidInputInvalid request xml, can't read it
errStatement_PeriodInvalidData not ready for selected period
errMerchantReport_NotNullMaynot be null. Right format yyyy-MM-dd
errMerchantReport_NotNullMaynot be null
errMerchantReport_NotEmptyMaynot be empty
errMerchantReport_1Wrong report type
errMerchantReport_2Period can't be longer than 35 days
errMerchantReport_3No such user code in ACQ
errMerchantReport_4Error creating merchant report
errMerchantReport_7User not authorized for this report request, no IBAN found for merchant
errMerchantReport_9Period start can't be after end

Contract Management Services

These services are meant for Service Providers Connect contract management - info services about existing contracts, creation and modification.

Request New Contract

POST [base-url]/contracts

Initiate new Service Provider customer contract creation - service provider can use it to create a new pending contract for it's customer:

  • request must contain customers registry code and country
  • pending contract is created on LHV side. Services list is taken automatically from active service provider contract configuration.
  • response returns the pending contract data and BDOC digital container that customer representative can sign. Also e-mail is sent automatically to the representative with the same BDOC container in attachment and instructions for further actions.
    Service providers can use the BDOC container data in the HTTP response to provide the container file also in their interface.
  • contract activation is currently done by LHV Client Services
  • contract status and activation can be monitored using the "Get contracts list" service

Request

Mandatory headers:

  • Client-Code - [service provider registry code]
  • Client-Country - [service provider registry country]

Body in JSON format:

FieldTypeComment
companyCodeStringRegistry code of Service Providers client
companyCodeIssuerStringRegistry code issuer country of Service Providers client
Sample
{
    "companyCode": "12345678",
    "companyCodeIssuer": "EE"
}

Response

Response is in JSON format and returned immediately in HTTP response body - not in the message queue:

FieldTypeComment
companyCodeStringRegistry code of Service Providers client
companyCodeIssuerStringRegistry code issuer country of Service Providers client
contractStatusStringContract status - pending/failed
contractIdStringContract unique id
contractContainerStringBDOC container data in BASE64
Sample
{
    "companyCode": "79536821",
    "companyCodeIssuer": "EE",
    "contractStatus": "pending",
    "contractId": "9adaf57a-a036-462f-9e08-dd201bf36e67",
    "contractContainer": "UEsDBAoAAAgAAJ2IY1CKIfl..."
}

Get Contracts List

GET [base-url]/contracts

Get list and information about Service Provider connected customers, their contracts and enabled services. Both active and pending (waiting for activation) contracts are listed.

Request

Mandatory headers:

  • Client-Code - [service provider registry code]
  • Client-Country - [service provider registry country]

Optional GET parameters:

  • createdAtMin and createdAtMax - for filtering out contracts created between selected dates. For example:
GET https://connect.lhv.eu/contracts?createdAtMin=2020-07-01&createdAtMax=2021-09-01
  • changedAtMin and changedAtMax - for filtering out contracts modified between selected dates. This filter also returns closed contracts if customer for selected service provider does not have active contracts. For example:
GET https://connect.lhv.eu/contracts?changedAtMin=2020-07-01&changedAtMax=2021-09-01

Response

Response is in JSON format and returned immediately in HTTP response body - not in the message queue.

PositionFieldTypeComment
1customersArray
1.1companyCodeStringCompany registry code
1.2companyCodeIssuerStringCompany registry country
1.3nameStringCompany name
1.4contractsArray
1.4.1idStringContract id
1.4.2statusStringContract status - active/pending
1.4.3startDateStringContract start date
1.4.4servicesArrayList of services of the contract
1.4.4.1automaticAccountStatementArrayList of IBAN's where automatic account statements are enabled
1.4.4.2creditDebitNotificationArrayList of IBAN's where credit debit notifications are enabled
Sample

Sample contains 3 different contracts:

  • pending contract for customer "LHV Connect Demo 2"
  • active contract for customer "LHV Connect Demo 2"
  • active contract for customer "LHV Connect Demo 3"
{
    "customers": [
        {
            "companyCode": "80368926",
            "companyCodeIssuer": "EE",
            "name": "LHV Connect Demo 2",
            "contracts": [
                {
                    "id": "ba0d12e8-fd31-4c9f-84ba-801638d25063",
                    "status": "PENDING",
                    "services": [
                        {
                            "name": "ACCOUNT_STATEMENT"
                        },
                        {
                            "name": "CREDIT_DEBIT_NOTIFICATION",
                            "ibans": [
                                "EE267700771001260987",
                                "EE427700771001260990"
                            ]
                        },
                        {
                            "name": "ACCOUNT_BALANCE"
                        },
                        {
                            "name": "PAYMENTS_WITHOUT_SIGNATURE"
                        },
                        {
                            "name": "HEARTBEAT"
                        }
                    ]
                },
                {
                    "id": "0ceb02c9-e455-42b0-9d45-2ba5fd3b8f41",
                    "status": "ACTIVE",
                    "startDate": "2020-02-17",
                    "services": [
                        {
                            "name": "AUTOMATIC_ACCOUNT_STATEMENT",
                            "ibans": [
                                "EE427700771001260990",
                                "EE267700771001260987"
                            ]
                        },
                        {
                            "name": "ACCOUNT_STATEMENT"
                        },
                        {
                            "name": "CREDIT_DEBIT_NOTIFICATION",
                            "ibans": [
                                "EE267700771001260987",
                                "EE427700771001260990"
                            ]
                        },
                        {
                            "name": "ACCOUNT_BALANCE"
                        },
                        {
                            "name": "PAYMENTS_WITHOUT_SIGNATURE"
                        },
                        {
                            "name": "HEARTBEAT"
                        }
                    ]
                }
            ]
        },
        {
            "companyCode": "79536821",
            "companyCodeIssuer": "EE",
            "name": "LHV Connect Demo 3",
            "contracts": [
                {
                    "id": "f89e82f6-f8c6-4d08-8091-51340f0b4661",
                    "status": "ACTIVE",
                    "startDate": "2020-02-28",
                    "services": [
                        {
                            "name": "ACCOUNT_STATEMENT"
                        },
                        {
                            "name": "CREDIT_DEBIT_NOTIFICATION",
                            "ibans": [
                                "EE687700771001283511",
                                "EE087700771001283524",
                                "EE527700771001283993"
                            ]
                        },
                        {
                            "name": "ACCOUNT_BALANCE"
                        },
                        {
                            "name": "PAYMENTS_WITHOUT_SIGNATURE"
                        },
                        {
                            "name": "HEARTBEAT"
                        }
                    ]
                }
            ]
        }
    ]
}

Webhooks

Subscribe to a webhook endpoint and upon a new message, we will notify you via the webhook, enabling you to fetch the
message immediately.
This delivery system enables transitioning from a polling-based model to near real-time notifications.

Webhook subscribe

POST [base-url]/notifications/subscribe

Request

Mandatory headers:

  • Client-Code - End-user (Customer's) registry code. Mandatory for service provider
  • Client-Country - Customer's country code. Mandatory for service provider

Body in JSON format:

FieldTypeComment
urlStringDestination user wishes to receive notification about new message
eventTypeStringAt the moment always "GENERAL_WEBHOOK"
Sample
{
    "url": "https://xxxxx.webhook.office.com/xxxxxxxxx",
    "eventType": "GENERAL_WEBHOOK"
}

Response

FieldTypeComment
subscriptionReferenceStringReference code for created webhook
Sample
{
    "subscriptionReference": "922fa302-4da5-4b9c-acd6-47f0ae65440b"
}

Update webhook subscription

PUT [base-url]/notifications/subscriptions/:subscriptionReference

Endpoint for updating existing (active) webhook subscription with subscriptionReference to the new destination.

Request

Mandatory headers:

  • Client-Code - End-user (Customer's) registry code. Mandatory for service provider
  • Client-Country - Customer's country code. Mandatory for service provider

Body in JSON format:

FieldTypeComment
urlStringDestination user wishes to receive notification about new message
eventTypeStringAt the moment always "GENERAL_WEBHOOK"
Sample

PUT [base-url]/notifications/subscriptions/922fa302-4da5-4b9c-acd6-47f0ae65440b

{
    "url": "https://xxxxx.webhook.office.com/xxxxxxxxx",
    "eventType": "GENERAL_WEBHOOK"
}

Response

On successful webhook update response with the status HTTP 204 OK will be returned (without response body).

Webhook unsubscribe

DELETE [base-url]/notifications/subscriptions/:subscriptionReference

Endpoint for unsubscribing from existing webhook subscription

Request

Mandatory headers:

  • Client-Code - End-user (Customer's) registry code. Mandatory for service provider
  • Client-Country - Customer's country code. Mandatory for service provider
Sample

DELETE [base-url]/notifications/subscriptions/922fa302-4da5-4b9c-acd6-47f0ae65440b

Response

The successful webhook unsubscribing response with the status HTTP 200 OK will be returned.
In the case of HTTP code 200, no response body is used.

Webhook search

GET [base-url]/notifications/subscriptions

Endpoint for searching subscribed (active) webhooks

Request

Mandatory headers:

  • Client-Code - End-user (Customer's) registry code. Mandatory for service provider
  • Client-Country - Customer's country code. Mandatory for service provider
Sample

Response

{
    "subscriptions": [
        {
            "url": "https://xxxxx.webhook.office.com/xxxxxxxxx",
            "subscriptionReference": "922fa302-4da5-4b9c-acd6-47f0ae65440b",
            "eventType": "GENERAL_WEBHOOK"
        }
    ]
}

If there are no active webhooks for the client then response will be with the status HTTP 204 No Content and no response
body is used.

Payload

Webhook payload is a structured data format (JSON) sent with an HTTP request to the subscribed URL specified by the TPP
when the webhook is triggered.
It contains detailed information related to the event that triggered the webhook.

FieldTypeComment
eventIdNumericA unique identifier for a webhook event
subscriptionReferenceString (UUID)A unique identifier for each webhook subscription event
timestampString (ISO-8601 datetime)The time the event was generated
messageResponseIdStringThe ID of this response message. A key field to use to retrieve the actual message body
messageRequestIdStringThe ID of the request message
messageCreatedTimeString (ISO-8601 datetime)The time the message was created
messageTypeStringThe type of the message. See the "Message-Response-Type" list
regCodeStringUser registration code/Client code
regCodeIssuerStringThe country of the client
bankCodeStringEither LHVUK or LHVEE, specifying whether the message originated from the UK or Estonian branch

Sample

{
    "eventId": "1",
    "subscriptionReference": "f868b13b-4632-4f84-864b-9b2ddb7fcc1d",
    "timestamp": "2024-03-25T06:01:02.171+00:00",
    "messageResponseId": "RES5143ba89862b4eb4b7fbf24c3eb7a447",
    "messageRequestId": "REQ82cbcdf79f17473e9efe40778a1c15fa",
    "messageCreatedTime": "2024-03-25T06:01:02.171+00:00",
    "messageType": "ACCOUNT_BALANCE",
    "regCode": "123456",
    "regCodeIssuer": "EE",
    "bankCode": "LHVEE"
}

Appendix

Code Set: Balance

CODEDESCRIPTION
OPBDOpening booked balance.
CLBDClosing booked balance.

Code Set: Credit and debit code

CODEDESCRIPTION
CRDTPositive amount or zero.
DBITNegative amount.

Code Set: Payment scheme

CODEDESCRIPTION
INSTSEPA Instant payment.
Payment initiation: INST must be used for RT1 and TIPS payment. Account reports: INST stands for RT1 payment.
SEPASEPA payment.
SWIFTSWIFT payment.
TARGET2TARGET2 payment.
TIPSTARGET Instant Payment.
Payment initiation: Code cannot be used directly, but using INST
INTERNALLHV internal payment.
GROUPPayments between LHV Group subsidiaries (LHV Pank, LHV Bank).
TRADERTrader payment.
Trader payments cannot be initated via Connect.
SEPADDSEPA direct debit payment.

Code Set: Payment scheme return codes

Codes are subject to change. Use following codes if returning incoming payment with service Initating return payments.

CODEDESCRIPTION
Payment scheme - INST, TIPS, TARGET2, SEPA
If returning TIPS payment use payment scheme code INST.
AC01​Incorrect Account Number
AC04Closed Account Number
AC06Blocked Account
AG01Transaction Forbidden
AG02Invalid Bank Operation Code
AM05Duplication
BE04Missing Creditor Address
CNORCreditor Bank is not registred
ERINERI Option Not Supported
MD07End Customer Deceased
MS02Not Specified Reason Customer Generated
MS03Not Specified Reason Agent Generated
RC01Bank Identifier Incorrect
RR01Missing Debtor Account Or Identification
RR02Missing Debtor Name or Address
RR03Missing Creditor Name or Address
RR04Regulatory Reason
FOCRFollowing Cancellation Request
Payment scheme - GROUP
AC01​Incorrect Account Number
AC04Closed Account Number
AC06Blocked Account
AG01Transaction Forbidden
AM03Not Allowed Currency
AM05Duplication
MS02Not Specified Reason Customer Generated
RR04Regulatory Reason

Code Set: Payment scheme reject codes

Codes are subject to change. Rejection means that payment is rejected or returned by the payment system or receiving bank. We will forward the code with payment.

CODEDESCRIPTION
Payment scheme - GROUP
AC01Incorrect Account Number
AC02Invalid Debtor Account Number
AC04Closed Account Number
AC06Blocked Account
AG01Transaction Forbidden
AM03Not Allowed Currency
MS03Not Specified Reason Agent Generated
Payment scheme - INST, TIPS, TARGET2, SEPA
AB05Clearing process aborted due to timeout at the Creditor PSP (Creditor Agent)
AB06Clearing process aborted due to timeout at Intermediary PSP or CSM (the Instructed Agent). Rejected by the CSM to Originator Bank upon Timeout condition
AB07Agent of message is not online / available. Generic usage if it cannot be determined who exactly is unavailable
AB08Creditor PSP (Creditor Agent) is not online / available
AB09Clearing process aborted due to error at the Creditor PSP (Creditor Agent)
AB10Clearing process aborted due to error at the Intermediary PSP or CSM (the Instructed Agent)
AC01Incorrect Account Number
AC04Closed Account Number
AC06Blocked Account
AG01Transaction Forbidden
AG02Invalid Bank Operation Code
AG09Original payment never received
AG10Agent of message is suspended from the Real-time Payment system. Generic usage if it cannot be determined who exactly is suspended
AG11Creditor PSP (Creditor Agent) of message is suspended from the Real-time Payment system
AM02Not Allowed Amount
AM04Insufficient Funds
AM23Transaction amount exceeds settlement limit
BE04Missing Creditor Address
CNORCreditor bank is not registered. Creditor bank is not registered under this BIC in the CSM
DNORDebtor bank is not registered. Originator bank is not registered under this BIC in the CSM
MD07End Customer Deceased
MS02Not Specified Reason Customer Generated
MS03Not Specified Reason Agent Generated
PY01Unknown BIC in routing table
RC01Bank Identifier Incorrect
RR01Missing Debtor Account Or Identification
RR02Missing Debtors Name Or Address
RR03Missing Creditors Name Or Address
RR04Regulatory Reason
TM01Invalid Cut Off Time. Rejected by the CSM to Creditor Bank upon Timeout condition
XT04Insufficient liquidity for processing the transaction on the System
XT06InvalidAccptTime, Rejected by the CSM to Originator Bank upon exceeding tolerance period for the Acceptance Date&Time
XT79The Debtor Agent is not allowed to send SCT Inst transactions (pacs.008) and consequently to send Investigation (pacs.028) and Recalls (camt.056). It is also not allowed to receive NRR and PRR
XT80The Creditor Agent is not allowed to receive SCT Inst transactions (pacs.008) and consequently to receive Investigation (pacs.028) and Recalls (camt.056). It is also not allowed to send NRR and PRR
XT81Field not Permitted in SCT Inst Service
XT83Participant not allowed to use the Product Id specified
XT86Expired Time limit for Recall
XT87Inconsistent Instructing Agent
XT90Invalid use of a Technical BIC

Code Set: Bank transaction codes

DOMAIN CODEFAMILY CODESUBFAMILY CODEDESCRIPTION
ACMTMDOPFEESPortfolio safekeeping fee
ACMTMDOPTAXEVAT
DERVOTHROTHRGain/loss prior open future positions
FORXMDOPFEESCurrency exchange fee
FORXOTHROTHRCurrency exchange
LDASFTDPINTRTerm deposit interest
LDASFTDPOTHRTerm deposit
LDASMDOPFEESFees related to loan agreement
LDASMDOPTAXEIncome tax on received interest
LDASNTDPINTRInterest payment
LDASNTLNINTRInterest payment
LDASNTLNPPAYCapital payment
LDASOTHROTHROther payments related to loan or rebalance
PMNTCCRDCAJTCard account rebalance
PMNTCCRDCWDLATM withdrawal
PMNTCCRDCDPTATM deposit
PMNTCCRDFEESFees related cards and card payments
PMNTCCRDINTRCredit card interest
PMNTCCRDPOSCPayment between current and limit account
PMNTCCRDPOSDCard payment
PMNTCNTRCWDLCash withdrawal
PMNTCNTRCDPTCash deposit
PMNTDRFTSTLRReservation
PMNTICDTFEESMoney transfer fee
PMNTICDTOTHRIssued payment
PMNTRCDTOTHRReceived payment
PMNTMCOPINTRAccrued interest
PMNTMCDRCHRGACQ merchant chargeback fee
PMNTMCDRCOMEACQ merchant revenue fee
PMNTMCDRCOMTACQ merchant service fee
PMNTMCDRDAJTACQ merchant revenue debit
PMNTMCDRPOSPACQ merchant revenue
PMNTMDOPFEESPayment fee
PMNTOTHROTHROther transaction
PMNTICDTFICTPSP issued credit transfer
PMNTRCDTFICTPSP received credit transfer
PMNTIDDTPMDDIssued Direct Debit
PMNTRDDTPMDDReceived Direct Debit
PMNTIDDTFIDDPSP issued Direct Debit
PMNTRDDTFIDDPSP received Direct Debit
SECUCORPFEESCorporate action fee
SECUCORPOTHRCorporate action
SECUCUSTDVCADividends
SECUMDOPTAXEIncome tax withheld
SECUOTHROTHRTrader rebalance
SECUSETTFEESSecurities commission fee
SECUSETTTRADSecurities buy-sell

Code Set: Purpose

CODEDESCRIPTION
ACCTAccount management.
CASHCash management.
COLLCollection payment.
INTCIntra-company payment.
LIMALiquidity management.
NETTNetting.
AGRTAgricultural payment.
BEXPBusiness expenses.
COMCCommercial payment.
CPYRCopyright.
LICFLicence fee.
GDDSPurchase and sale of goods.
SCVEPurchase and sale of services.
SUBSSubscription.
SUPPSupplier payment.
CHARCharity payment.
HLRPHousing loan repayment.
INSUInsurance premium.
INTEInterest.
LBRILabour insurance.
LIFILife insurance.
LOANLoan to borrower.
LOARLoan to lender.
PPTIProperty insurance.
ADVAAdvance payment.
CCRDCredit card payment.
DCRDDebit card payment.
GOVTGovernment payment.
MSVCMultiple service types.
NOWSNot otherwise specified.
OTHROther.
PADDPreauthorised debit.
RENTRent.
STDYStudy.
DERIDerivatives.
DIVDDividend.
FREXForeign exchange.
SAVGSavings.
SECUSecurities.
TREATreasury payment.
DNTSDental services.
HLTIHealth insurance.
HSPCHospital care.
LTCFLong-term care facility.
MDCSMedical services.
ALMYAlimony payment.
BONUBonus payment.
BECHChild benefit.
COMMCommission.
PENSPension payment.
SALASalary payment.
SSBESocial security benefit.
HSTXHousing tax.
INTXIncome tax.
TAXSTax payment.
VATXVAT payment.
AIRBAir transport.
BUSBBus transport.
FERBFerry transport.
RLWYRailway transport.
CBTVCable TV bill.
ELECElectricity bill.
ENRGEnergies.
GASBGas bill.
NWCHNetwork charge.
NWCMNetwork communication.
OTLCOther telecom related bill.
PHONTelephone bill.
WTERWater bill.
DEBTDeposit.
GDSVPurchase and Sale of Goods and Services
CDBLCredit Card Bill
INVSInvestment and Securities
ALLWAllowance
PAYRPayroll
UBILUtilities

Code Set: Category purpose

CODEDESCRIPTION
CASHCash management.
CORTTrade settlement payment.
DIVIDividends payment.
GOVTGovernment payment.
HEDGHedging.
INTCIntra-company payment.
INTEInterest payment.
LOANTransfer of a loan to a borrower.
PENSPension payment.
SALASalary payment.
SECUSecurities payment.
SSBESocial security benefit payment.
SUPPSupplier payment.
TAXSTax payment.
TRADTrade finance transaction payment.
TREATreasury payment.
VATXVAT payment.
WHLDWithholding tax payment.
OTHROther payment.
EPAYPayment via online banking.
FCOLFee collection.

Code Set: Private person identification

CODEDESCRIPTION
ARNUNumber assigned by a social security agency to identify a non-resident person.
CCPTNumber assigned by an authority to identify the passport number of a person.
CUSTNumber assigned by an issuer to identify a customer.
DRLCNumber assigned by an authority to identify a driver's license.
EMPLNumber assigned by a registration authority to an employee.
NIDNNumber assigned by an authority to identify the national identity number of a person.
SOSENumber assigned by an authority to identify the social security number of a person.
TXIDNumber assigned by a tax authority to identify a person.
TELENumber assigned by a telephone or mobile phone operator to identify a person. A person may have multiple phone numbers.
POIDCommercial identification of the person.

Code Set: Organisation identification

CODEDESCRIPTION
BANKUnique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client.
CBIDA unique identification number assigned by a central bank to identify an organisation.
CHIDA unique identification number assigned by a clearing house to identify an organisation.
COIDCountry authority given organisation identification (e.g., corporate registration number).
CUSTNumber assigned by an issuer to identify a customer. Number assigned by a party to identify a creditor or remitter relationship.
DUNSA unique identification number provided by Dun & Bradstreet to identify an organisation.
EMPLNumber assigned by a registration authority to an employer.
GS1GGlobal Location Number. A non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules. The number is used to retrieve detailed information that is linked to it.
SRENThe SIREN number is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France.
SRETThe SIRET number is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity.
TXIDNumber assigned by a tax authority to identify an organisation.
CINCA unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation.
BDIDIdentifier of the business domain in which the organisation is active.
BOIDOther identification of the organisation.

Code Set: Payment priority

CODEDESCRIPTION
NORMNormal payment.
HIGHUrgent payment.
EXPRExtra urgent payment.

If payment priority is not provided or faulty, default values will be used. For additional information see Payment processing time limits and settlements.

Code Set: Charges bearer

CODEDESCRIPTION
SLEVAllowed only for SEPA payments. Shared charges.
SHARShared charges.
DEBTRemitter pays charges.

If not provided or faulty, default values will be used. For additional information see Payment processing time limits and settlements.

Code Set: Direct Debit scheme

CODEDESCRIPTION
SEPADDSEPA Direct Debit CORE