Specification for LHV Banklink

General

A Bank Link query means an HTTP POST query with specified parameters. Each query contains the service number. A list of parameters and a query processing algorithm has been assigned to each service. Queries from the Merchant to the Bank are directed to the URL https://www.lhv.ee/banklink.

Payment queries

Conforms to updated technical specification.

Query 1011

The Merchant sends the Bank the information for the signed payment order, which the Customer cannot change in the online bank. Query “1111” is prepared after a successful payment, whereas query “1911” is prepared after a failed payment for the Merchant.

No Field Digits Description
1 VK_SERVICE 4 Service number (1011).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_SND_ID 15 Query submitter’s (Merchant’s) ID.
4 VK_STAMP 20 Query ID.
5 VK_AMOUNT 12 Payment amount. Decimals and cents separated with a dot “.”. No thousands separator.
6 VK_CURR 3 Payment currency (EUR).
7 VK_ACC 34 Payee’s account number.
8 VK_NAME 70 Name of payee.
9 VK_REF 35 Payment order reference number.
10 VK_MSG 95 Payment order details.
11 VK_RETURN 255 URL for a response on a successfully completed transaction.
12 VK_CANCEL 255 URL for a response on a failed transaction.
13 VK_DATETIME 24 Date and time of query initiation in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).

Query 1012

The Merchant sends the Customer’s Transaction request to the Bank. The payee’s name and account number are taken from the Agreement between the Bank and the Merchant. Query “1111” is prepared after a successful payment, whereas query “1911” is prepared after a failed payment for the Merchant.

No Field Length Description
1 VK_SERVICE 4 Service number (1012).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_SND_ID 15 Query recipient’s (Merchant’s) ID.
4 VK_STAMP 20 Query ID.
5 VK_AMOUNT 12 Amount payable. Decimals and cents separated with a dot “.”. No thousands separator.
6 VK_CURR 3 Payment currency (EUR).
7 VK_REF 35 Payment order reference number.
8 VK_MSG 95 Payment order details.
9 VK_RETURN 255 URL for a response on a successfully completed transaction.
10 VK_CANCEL 255 URL for a response on a failed transaction.
11 VK_DATETIME 24 Date and time of query initiation in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).

Response query 1111

Used for notification of a successful payment order.

No Field Length Description
1 VK_SERVICE 4 Service number (1111).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_SND_ID 15 Query submitter’s (Bank’s) ID.
4 VK_REC_ID 15 Query recipient’s (Merchant’s) ID.
5 VK_STAMP 20 Query ID.
6 VK_T_NO 20 Payment order number.
7 VK_AMOUNT 12 Amount paid. Decimals and cents separated with a dot “.”. No thousands separator.
8 VK_CURR 3 Payment currency (EUR).
9 VK_REC_ACC 34 Payee’s account number.
10 VK_REC_NAME 70 Name of payee.
11 VK_SND_ACC 34 Payer’s account number.
12 VK_SND_NAME 70 Name of payer.
13 VK_REF 35 Payment order reference number.
14 VK_MSG 95 Payment order details.
15 VK_T_DATETIME 24 Date and time of payment order in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).
- VK_AUTO 1 Y = automatic response by the Bank. N = response with redirection to merchant’s self.

Response query 1911

Used for notification of an unsuccessful transaction.

No Field Length Description
1 VK_SERVICE 4 Service number (1911).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_SND_ID 15 Query submitter’s (Bank’s) ID.
4 VK_REC_ID 15 Query recipient’s (Merchant’s) ID.
5 VK_STAMP 20 Query ID.
6 VK_REF 35 Payment order reference number.
7 VK_MSG 95 Payment order details.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).
- VK_AUTO 1 Y = automatic response by the Bank. N = response with redirection to merchant’s self.

Authentication queries

Conforms to updated technical specification.

Response query 3012

Information of the identified user is forwarded to the Merchant by the Bank. For the sake of security, the message recipient should check, in addition to the signature (VK_MAC), also the message recipient’s ID (VK_REC_ID) and the time and date of message generation (VK_DATETIME), which may vary from the current one by no more than ±5 minutes at the time of checking.

No Field Length Description
1 VK_SERVICE 4 Service number (3012).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_USER 16 Agreed user identifier.
4 VK_DATETIME 24 Date and time of message generation in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
5 VK_SND_ID 15 Message submitter’s (Bank’s) ID.
6 VK_REC_ID 15 Message recipient’s (Merchant’s) ID.
7 VK_USER_NAME 140 User name.
8 VK_USER_ID 20 User’s personal identification code.
9 VK_COUNTRY 2 Country of personal identification code (two-letter ISO 3166-1).
10 VK_OTHER 150 Other user information.
11 VK_TOKEN 2 Authentication device identifier code: 1 - ID card; 2 - mobile ID; 5 - one-off codes (except for a PIN calculator); 6 - PIN calculator; 7 - reusable card; 9 – Smart-ID; 12 - Biometric.
12 VK_RID 30 Session-related identifier.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).

Response query 3013

In response to query 4012, information of the identified user and a copy of the nonce are forwarded to the Merchant by the Bank.
For the sake of security, the message recipient should check, in addition to the signature (VK_MAC) and nonce (VK_NONCE), also the message recipient’s ID (VK_REC_ID) and the time and date of message generation (VK_DATETIME), which may vary from the current one by no more than ±5 minutes at the time of checking.

No Field Length Description
1 VK_SERVICE 4 Service number (3013).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_DATETIME 24 Date and time of message generation in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
4 VK_SND_ID 15 Message submitter’s (Bank’s) ID.
5 VK_REC_ID 15 Message recipient’s (Merchant’s) ID.
6 VK_NONCE 50 Copy of nonce in query.
7 VK_USER_NAME 140 User name.
8 VK_USER_ID 20 User’s personal identification code.
9 VK_COUNTRY 2 Country of personal identification code (two-letter ISO 3166-1).
10 VK_OTHER 150 Other user information.
11 VK_TOKEN 2 Authentication device identifier code: 1 - ID card; 2 - mobile ID; 5 - one-off codes (except for a PIN calculator); 6 - PIN calculator; 7 - reusable card; 9 – Smart-ID; 12 - Biometric.
12 VK_RID 30 Session-related identifier.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).

Query 4011

Query sent to the Bank by the Merchant for identifying the user. Service open for merchants that have concluded the relevant agreement. Response query code 3012.

No Field Length Description
1 VK_SERVICE 4 Service number (4011).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_SND_ID 15 Message submitter’s (Merchant’s) ID.
4 VK_REPLY 4 Expected response package code (3012).
5 VK_RETURN 255 Merchant’s URL for a response.
6 VK_DATETIME 24 Date and time of message generation in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
7 VK_RID 30 Session-related identifier.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).

Authentication query 4012

Query sent to the Bank by the Merchant for identifying the user. Service open for merchants that have concluded the relevant agreement. Response query code 3013.

No Field Length Description
1 VK_SERVICE 4 Service number (4012).
2 VK_VERSION 3 Crypto algorithm used (008 or 009).
3 VK_SND_ID 15 Message submitter’s (Merchant’s) ID.
4 VK_REC_ID 15 Message recipient’s (Bank’s) ID.
5 VK_NONCE 50 Random nonce generated by query submitter.
6 VK_RETURN 255 Merchant’s URL for a response.
7 VK_DATETIME 24 Date and time of message generation in the ISO 8601 format to within a second including time zone information. Eg 2013-03-13T07:21:14+0200.
8 VK_RID 30 Session-related identifier.
- VK_MAC 700 Verification code, i.e. signature.
- VK_ENCODING 12 Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
- VK_LANG 3 Desired language of communication (EST, ENG or RUS).

Public keys

  • LHV accepts certificate queries or so-called self-signed certificates. Upon conclusion of the banklink agreement, the bank sends public key certificate to the merchant. This needs to be inserted to the client’s system and it is used to validate queries submitted by the bank.

  • Client must generate a public and private key-pair. We recommend adhering to the following:

    • Signature algorithm – sha1RSA
    • Public key – RSA(2048 Bits)
    • Validity – not more than 10 years

    We apply X.509-compliant .PEM format keys/certificates – i.e. the content is in BASE64 encoding and fit between –BEGIN… – and –END… – tags. The private key generated by the Customer must be at least 2,048 bits.
    The keys can be generated from a command line via the openssl utility.

    openssl genrsa 2048 > privkey.pem
openssl req -new -key privkey.pem -out cert-req.pem

    Public key must be sent to the bank and thereupon banklink agreement is activated.

Calculating the verification code VK_MAC

VK_MAC, the electronic signature used in the queries, is calculated based on a previously agreed algorithm. The algorithm version is determined by the query parameter VK_VERSION. The signature VK_MAC is sent in BASE64 encoding. Two versions are currently applied:

  1. VK_MAC(MAC008) is calculated by using the public key algorithm and the secure hashing algorithm SHA-1. MAC008(x1,x2,…,xn) := RSA( SHA-1(p(x1)|| x1|| p(x2)|| x2 || … ||p(xn )||xn), d, n).
  2. VK_MAC(MAC009) is calculated by using the public key algorithm and the secure hashing algorithm SHA-512. MAC009(x1,x2,…,xn) := RSA( SHA-512(p(x1)|| x1|| p(x2)|| x2 || … ||p(xn )||xn), d, n).

Description:

  • x1, x2, …, xn are the query parameters
  • in case of queries compliant to the new specifications (1011, 1012, 1111, 1911, 3012, 3013, 4011, 4012), p is a function of the length of the parameter in symbols. The length is formatted to a three-digit string. Thus, length 1 ’ “001”. Empty fields have a length of “000”.
  • d is the RSA secret exponent
  • n on RSA modulus
  • || - adding-up of strings