Agency Account Synchronization

Service description

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

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

Name	Value
Content-Type	`application/xml`
Client-Code	`customer value`
Client-Country	`customer value`

Content-Type

application/xml

Client-Code

customer value

Client-Country

customer value

Body

2KB

account.agent.sync.xsd.xml

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.

MULT.

MESSAGE ELEMENT

XML TAG

Description

[1..1]

+MessageRoot

[0..1]

++BankCodes

List of LHV bank codes where to sync the account. To be used only for LHV UK Connect API host

[1..2]

+++BankCode

* LHVBEE22 or LHVBEE22XXX - use for LHVEE * LHVBGB2L or LHVBGB2LXXX - use for LHVUK

[1..1]

++Accounts

List of accounts

[1..1]

+++Region

'GB' or ISO country code (SEPA Scheme Country) used in IBAN.

[0..1]

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

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>

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>

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

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

Content-Type

application/xml

X-Bank-Code

LHVUK, LHVEE

Body

Request accepted - no content

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

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>

MESSAGE ELEMENT

XML TAG

Description

+MessageRoot

++Accounts

+++Account

+++Region

+++AccountNo

Filled if existed in request.

+++Iban

<Iban>

Filled if existed in request.

+++Status

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

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.

PreviousIndirect Scheme Access NextRTF - Routing Table Files message

Last updated 3 months ago