Connect

Agency Account Synchronization

Service description

Service is used for synchronizing third party service provider's existing account numbers with LHV.

If utilizing the Confirmation of Payee service, please refer to version 2 of the account synchronization service.

Request

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

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

Headers

NameValue

Content-Type

application/xml

Client-Code

customer value

Client-Country

customer value

Body

XML structure description:

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.

Samples

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

NameValue

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

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>

Samples

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

​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/agent/account/synchronize

Headers

NameValue

Content-Type

application/json

Client-Code

customer value

Client-Country

customer value

Body

FieldM/ODescription

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

If AccountCategory = BUSINESS then legal user name.

If AccountCategory = PERSONAL then private person full name.

Accounts.AccountCategory

O

Account classification - PERSONAL or BUSINESS

Accounts.CoPOptOut

O

True - account is opted out from Confirmation of Payee

False - default

Samples

{
    "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

NameValue

Content-Type

application/json

X-Bank-Code

LHVUK, LHVEE

Body

FieldM/ODescription

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

Sample

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

Error codes

ErrorCodeErrorDescription

​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