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

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.

Samples

Without Bank Code

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>

UK Bank Code

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>

UK and EE

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>

EE Bank Code

Accounts are synced only to EE

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

Response

Headers

Name	Value
Content-Type	application/xml
X-Bank-Code	LHVUK, LHVEE

Body

202

Request accepted - no content

403

Error code and description

<Errors>
    <Error>
        <ErrorCode>FORBIDDEN</ErrorCode>
        <Description>User doesn't exist</Description>
    </Error>
</Errors>

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>

Samples

Successful

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

Error related to Master account

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

Request

POST https://connect.lhv.com/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	'GB', 'IM', 'JE', 'GG' or 'GI'
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

UK Bank Code

{
    "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/json
X-Bank-Code	LHVUK, LHVEE

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

Sample

OK

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

PARTIAL

{
  "OriginalMsgId": "",
  "AcceptanceStatus": "PARTIAL",
  "Accounts" : [
    {
      "Data": {
        "Country": "GB",
        "Identification": "12345612345678",
        "Status": "ACTIVE",
        "Name": "Account Name First",
        "AccountCategory": "PERSONAL",
        "CopOptOut": false
      },
      "Confirmed": true
    },
    {
      "Data": {
        "Country": "GB",
        "Identification": "12345687654321",
        "Status": "CLOSED",
        "Name": "Account Name LTD",
        "AccountCategory": "BUSINESS",
        "CopOptOut": true
      },
      "Confirmed": false,
      "ErrorInfo": {
        "ErrorCode": "NOT_FOUND",
        "ErrorDescription": "Account not found"
      }
    }
  ]
}

FAILED

{
  "OriginalMsgId": "",
  "AcceptanceStatus": "FAILED",
  "Accounts": {
    "IBAN": "GI75NWBK000000000000001234"
  },
  "Errors": [
    {
      "Code": "INVALID_JSON_REQUEST",
      "Description": "JSON validation error"
    }
  ]
}

Error codes

ErrorCode	ErrorDescription
​INVALID_REGION	Invalid Region.
INVALID_ACCOUNT_NO_OR_IBAN	Account number invalid.
INVALID_IBAN	Invalid IBAN.
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.