Specification for LHV Banklink

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.

NoFieldDigitsDescription
1VK_SERVICE4Service number (1011).
2VK_VERSION3Crypto algorithm used (008).
3VK_SND_ID15Query submitter’s (Merchant’s) ID.
4VK_STAMP20Query ID.
5VK_AMOUNT12Payment amount. Decimals and cents separated with a dot ".". No thousands separator.
6VK_CURR3Payment currency (EUR).
7VK_ACC34Payee’s account number.
8VK_NAME70Name of payee.
9VK_REF35Payment order reference number.
10VK_MSG95Payment order details.
11VK_RETURN255URL for a response on a successfully completed transaction.
12VK_CANCEL255URL for a response on a failed transaction.
13VK_DATETIME24Date 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_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired 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.

NoFieldLengthDescription
1VK_SERVICE4Service number (1012).
2VK_VERSION3Crypto algorithm used (008).
3VK_SND_ID15Query recipient’s (Merchant’s) ID.
4VK_STAMP20Query ID.
5VK_AMOUNT12Amount payable. Decimals and cents separated with a dot ".". No thousands separator.
6VK_CURR3Payment currency (EUR).
7VK_REF35Payment order reference number.
8VK_MSG95Payment order details.
9VK_RETURN255URL for a response on a successfully completed transaction.
10VK_CANCEL255URL for a response on a failed transaction.
11VK_DATETIME24Date 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_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired language of communication (EST, ENG or RUS).

Response query 1111

Used for notification of a successful payment order.

NoFieldLengthDescription
1VK_SERVICE4Service number (1111).
2VK_VERSION3Crypto algorithm used (008).
3VK_SND_ID15Query submitter’s (Bank’s) ID.
4VK_REC_ID15Query recipient’s (Merchant’s) ID.
5VK_STAMP20Query ID.
6VK_T_NO20Payment order number.
7VK_AMOUNT12Amount paid. Decimals and cents separated with a dot ".". No thousands separator.
8VK_CURR3Payment currency (EUR).
9VK_REC_ACC34Payee’s account number.
10VK_REC_NAME70Name of payee.
11VK_SND_ACC34Payer’s account number.
12VK_SND_NAME70Name of payer.
13VK_REF35Payment order reference number.
14VK_MSG95Payment order details.
15VK_T_DATETIME24Date 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_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired language of communication (EST, ENG or RUS).
-VK_AUTO1Y = automatic response by the Bank. N = response with redirection to merchant’s self.

Response query 1911

Used for notification of an unsuccessful transaction.

NoFieldLengthDescription
1VK_SERVICE4Service number (1911).
2VK_VERSION3Crypto algorithm used (008).
3VK_SND_ID15Query submitter’s (Bank’s) ID.
4VK_REC_ID15Query recipient’s (Merchant’s) ID.
5VK_STAMP20Query ID.
6VK_REF35Payment order reference number.
7VK_MSG95Payment order details.
-VK_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired language of communication (EST, ENG or RUS).
-VK_AUTO1Y = 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.

NoFieldLengthDescription
1VK_SERVICE4Service number (3012).
2VK_VERSION3Crypto algorithm used (008).
3VK_USER16Agreed user identifier.
4VK_DATETIME24Date 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.
5VK_SND_ID15Message submitter’s (Bank’s) ID.
6VK_REC_ID15Message recipient’s (Merchant’s) ID.
7VK_USER_NAME140User name.
8VK_USER_ID20User's personal identification code.
9VK_COUNTRY2Country of personal identification code (two-letter ISO 3166-1).
10VK_OTHER150Other user information.
11VK_TOKEN2Authentication device identifier code: 1 - ID card; 2 - mobile ID; 5 - one-off codes (except for a PIN calculator); 6 - PIN calculator; 7 - reusable card.
12VK_RID30Session-related identifier.
-VK_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired 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.

NoFieldLengthDescription
1VK_SERVICE4Service number (3013).
2VK_VERSION3Crypto algorithm used (008).
3VK_DATETIME24Date 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.
4VK_SND_ID15Message submitter’s (Bank’s) ID.
5VK_REC_ID15Message recipient’s (Merchant’s) ID.
6VK_NONCE50Copy of nonce in query.
7VK_USER_NAME140User name.
8VK_USER_ID20User's personal identification code.
9VK_COUNTRY2Country of personal identification code (two-letter ISO 3166-1).
10VK_OTHER150Other user information.
11VK_TOKEN2Authentication 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.
12VK_RID30Session-related identifier.
-VK_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired 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.

NoFieldLengthDescription
1VK_SERVICE4Service number (4011).
2VK_VERSION3Crypto algorithm used (008).
3VK_SND_ID15Message submitter’s (Merchant’s) ID.
4VK_REPLY4Expected response package code (3012).
5VK_RETURN255Merchant’s URL for a response.
6VK_DATETIME24Date 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.
7VK_RID30Session-related identifier.
-VK_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired 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.

NoFieldLengthDescription
1VK_SERVICE4Service number (4012).
2VK_VERSION3Crypto algorithm used (008).
3VK_SND_ID15Message submitter’s (Merchant’s) ID.
4VK_REC_ID15Message recipient’s (Bank’s) ID.
5VK_NONCE50Random nonce generated by query submitter.
6VK_RETURN255Merchant’s URL for a response.
7VK_DATETIME24Date 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.
8VK_RID30Session-related identifier.
-VK_MAC700Verification code, i.e. signature.
-VK_ENCODING12Message encoding. ISO-8859-1 or UTF-8 (default) or WINDOWS-1257.
-VK_LANG3Desired 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. Only version 008 is currently applied. The signature VK_MAC is sent in BASE64 encoding, 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).

  • 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