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.

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:

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