Agency Account Synchronization

Service description

This service is used to synchronise existing account numbers of a third-party service provider with LHV.

For use with the Confirmation of Payee service, refer to version 2 of the account synchronisation service.

Request

POST https://connect.lhv.com/agent/account/synchronize

The request supports bulk submission of multiple accounts.

  • A maximum of 1,000 accounts (Accounts.Account blocks) can be included per request.

  • The service adds new accounts or updates the status of existing ones. Duplicate entries are not checked—existing data is overwritten.

  • Valid requests result in immediate account activation by LHV.

  • If any entry in the request is invalid, the entire bulk is rejected and an appropriate error code is returned.

  • A valid agency agreement must be in place for the service provider.

Usage of Bank Codes

The Bank Codes field is an optional list of one or two codes that indicate whether an account number should be synchronised with LHV Estonia (LHV EE), LHV United Kingdom (LHV UK), or both. This depends on the customer’s setup and business requirements.

  • This feature is available only when connected to the LHV UK Connect API host.

  • If no Bank Codes are provided, synchronisation is performed with LHV EE.

  • If the Bank Code includes LHVBEE22 or LHVBEE22XXX, the account is synchronised with LHV EE.

  • If the Bank Code includes LHVBGB2L or LHVBGB2LXXX, the account is synchronised with LHV UK.

  • If the Bank Codes list includes both an LHV EE code (LHVBEE22 or LHVBEE22XXX) and an LHV UK code (LHVBGB2L or LHVBGB2LXXX) as two separate entries, the account is synchronised with both entities.

  • If an unsupported Bank Code is provided, the request defaults to LHV UK, but account synchronisation will be rejected.

Headers

Name
Value

Content-Type

application/xml

Client-Code

customer value

Client-Country

customer value

Body

2KB
account.agent.sync.xsd.xml
XML schema

XML structure description:

MULT.
MESSAGE ELEMENT
XML TAG
Description

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

Examples

Without Bank Code tag <BankCodes> routed to EE

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

Response

Headers

Name
Value

Content-Type

application/xml

X-Bank-Code

LHVUK, LHVEE

Body

Request accepted - no content

Response message

Response message is created and can be requests by the Messages services - Messages Services

HTTP Header Message-Response-Type: AGENT_ACCOUNT_SYNC

Body

2KB
account.agent.sync.xsd.xml
XML schema

Message structure

MESSAGE ELEMENT
XML TAG
Description

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

Examples

<?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 codes

Error codes are subject to change.

ERROR CODE
DESCRIPTION

​INVALID_REGION

Invalid Region.

INVALID_ACCOUNT_NO_OR_IBAN

Account number invalid.

ACCOUNT_NO_AND_IBAN_MISMATCH

AccountNo and AccountNoIban mismatch.

INVALID_IBAN

Invalid IBAN.

MASTER_ACCOUNT_NOT_FOUND

Master account not found.

TECHNICAL_ERROR

Technical error.

INVALID_REQUEST

Invalid request.

Account Synchronization v2

This service is used for synchronizing third-party service provider's existing account numbers with LHV. In this updated version, the service now utilizes JSON format for data exchange and includes additional mandatory fields required for Confirmation of Payee (CoP) compliance. These fields are: name, account category, and opt-out status.

More information about Confirmation of Payee service can be found here.

Request

POST https://connect.lhv.com/v2/agent/account/synchronize

Headers

Name
Value

Content-Type

application/json

Client-Code

customer value

Client-Country

customer value

Body

Field
M/O
Description

BankCodes

O

List of LHV bank codes where to sync the account. LHVBGB2L or LHVBGB2LXXX - use for LHVUK

Accounts.Country

​M

Allowed value is ISO country code.

Accounts.Identification

M

For 'GB' regions: UK sort code + account no (14 characters) or IBAN.

Other than 'GB': IBAN country code must match the value of Region. The BIC code to which the IBAN refers must have a valid Agency agreement.

Accounts.Status

O

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.

Accounts.Name

O

Mandatory when CoP responder service is enabled.

If AccountCategory = BUSINESS then legal user name.

If AccountCategory = PERSONAL then private person full name.

Accounts.AccountCategory

O

Mandatory when CoP responder service is enabled.

Account classification - PERSONAL or BUSINESS

Accounts.CoPOptOut

O

True - account is opted out from Confirmation of Payee

False - default

Example

{
    "BankCodes": [
        "LHVBGB2L"
    ],
    "Accounts": [
        {
            "Country": "GB",
            "Identification": "12345612345678",
            "Status": "ACTIVE",
            "Name": "Account Name First",
            "AccountCategory": "PERSONAL",
            "CopOptOut": false
        },
        {
            "Country": "GB",
            "Identification": "12345687654321",
            "Status": "CLOSED",
            "Name": "Account Name LTD",
            "AccountCategory": "BUSINESS",
            "CopOptOut": true
        }
    ]
}

Response

Headers

Name
Value

Content-Type

application/xml

X-Bank-Code

LHVUK, LHVEE

Body

Request accepted - no content

Response message

Body

Field
M/O
Description

OriginalMsgId

M

AcceptanceStatus

M

Status of the file process

OK - all accounts are processed successfully

PARTIAL - some of the accounts failed to process

FAILED - the file was failed to process

Accounts.Data.Country

M

Country from request​

Accounts.Data.Identification

M

AccountNo or IBAN from request

Accounts.Data.Status

M

Account status

Accounts.Data.Name

O

Name from request

Accounts.Data.AccountCategory

O

Account category from request

Accounts.Data.CoPOptOut

O

Opt out status

Accounts.Confirmed

M

Status of the account process

true - account was processed successfully

false - account was failed to process

Accounts.ErrorInfo.ErrorCode

O

Error code, see the list of error codes and descriptions here

Accounts.ErrorInfo.ErrorDescription

O

Error description, see the list of error codes and descriptions here

Examples

{
  "OriginalMsgId": "",
  "AcceptanceStatus": "OK",
  "Accounts" : [
    {
      "Data": {
        "Country": "GB",
        "Identification": "12345612345678",
        "Status": "ACTIVE",
        "Name": "Account Name First",
        "AccountCategory": "PERSONAL",
        "CopOptOut": false
      },
      "Confirmed": true
    }

Error codes

ErrorCode
ErrorDescription

​INVALID_REGION

Invalid Region.

INVALID_ACCOUNT_NO_OR_IBAN

Account number invalid.

INVALID_IBAN

Invalid IBAN.

IBAN_AND_REGION_MISMATCH

IBAN and region must match.

MASTER_ACCOUNT_NOT_FOUND

Master account not found.

TECHNICAL_ERROR

Technical error.

INVALID_JSON_REQUEST

Invalid request.

ACCOUNTS_OVER_MAXIMUM_ALLOWED_LIMIT

Maximum 1000 accounts allowed in the file.

IBAN_MUST_EXIST_FOR_THIS_REGION

IBAN must exist for this region.

CONFIRMATION_OF_PAYEE_NAME_NOT_PROVIDED

Confirmation of Payee name not provided.

CONFIRMATION_OF_PAYEE_ACCOUNT_CATEGORY_NOT_PROVIDED

Confirmation of Payee account category (PERSONAL, BUSINESS) not provided.

DUPLICATE_ACCOUNT

Duplicate account.

INVALID_ACCOUNT_STATUS

Account status must be ACTIVE or CLOSED.

NAME_TOO_LONG

Name can be max 250 characters long.

PreviousIndirect Scheme AccessNextRTF - Routing Table Files message

Last updated

Was this helpful?