Pangalingi tehniline spetsifikatsioon

Üldine

Pangalingi päringute all on mõeldud HTTP POST päringut spetsifitseeritud parameetritega. Iga päring sisaldab endas teenuse numbrit. Igale teenusele vastab oma loetelu parameetritest ja päringu käsitlemise algoritm. Päringud Kaupmehelt Pangale suunatakse URLile: https://www.lhv.ee/banklink.

Maksepäringud

Vastavuses uuendatud tehnilise spetsifikatsiooniga.

Päring 1011

Kaupmees saadab Panka allkirjastatud maksekorralduse andmed, mida Klient internetipangas muuta ei saa. Peale edukat makset koostatakse Kaupmehele päring “1111”, ebaõnnestunud makse puhul “1911”.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (1011).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_SND_ID 15 Päringu koostaja (Kaupmehe) ID.
4 VK_STAMP 20 Päringu ID.
5 VK_AMOUNT 12 Maksmisele kuuluv summa. Komakohad ja sendid eristatud punktiga “.”. Tuhandete eraldajat ei asutata.
6 VK_CURR 3 Makse valuuta (EUR).
7 VK_ACC 34 Saaja konto number.
8 VK_NAME 70 Saaja nimi.
9 VK_REF 35 Maksekorralduse viitenumber.
10 VK_MSG 95 Maksekorralduse selgitus.
11 VK_RETURN 255 URL, kuhu vastatakse edukal tehingu sooritamisel.
12 VK_CANCEL 255 URL, kuhu vastatakse ebaõnnestunud tehingu puhul.
13 VK_DATETIME 24 Päringu algatamise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03- 13T07:21:14+0200.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).

Päring 1012

Kaupmees saadab panka Kliendi sooviavalduse Tehingu tegemiseks. Makse saaja nimi ja konto number võetakse Panga ja Kaupmehe vahelisest lepingust. Peale edukat makset koostatakse Kaupmehele päring “1111”, ebaõnnestunud makse puhul “1911”.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (1012).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_SND_ID 15 Päringu koostaja (Kaupmehe) ID.
4 VK_STAMP 20 Päringu ID.
5 VK_AMOUNT 12 Maksmisele kuuluv summa. Komakohad ja sendid eristatud punktiga “.”. Tuhandete eraldajat ei kasutata.
6 VK_CURR 3 Makse valuuta (EUR).
7 VK_REF 35 Maksekorralduse viitenumber.
8 VK_MSG 95 Maksekorralduse selgitus.
9 VK_RETURN 255 URL, kuhu vastatakse edukal tehingu sooritamisel.
10 VK_CANCEL 255 URL, kuhu vastatakse ebaõnnestunud tehingu puhul.
11 VK_DATETIME 24 Päringu algatamise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).

Vastuspäring 1111

Kasutatakse vastamiseks maksekorralduse toimumisest

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (1111).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_SND_ID 15 Päringu koostaja (Panga) ID.
4 VK_REC_ID 15 Päringu vastuvõtja (Kaupmehe) ID.
5 VK_STAMP 20 Päringu ID.
6 VK_T_NO 20 Maksekorralduse number.
7 VK_AMOUNT 12 Makstud summa. Komakohad ja sendid eristatud punktiga “.”. Tuhandete eraldajat ei kasutata.
8 VK_CURR 3 Makse valuuta (EUR).
9 VK_REC_ACC 34 Saaja konto number.
10 VK_REC_NAME 70 Saaja nimi.
11 VK_SND_ACC 34 Maksja konto number.
12 VK_SND_NAME 70 Maksja nimi.
13 VK_REF 35 Maksekorralduse viitenumber.
14 VK_MSG 95 Maksekorralduse selgitus.
15 VK_T_DATETIME 24 Maksekorralduse kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).
- VK_AUTO 1 Y = panga poolt automaatselt saadetud vastus. N = vastus kliendi liikumisega kaupmehe lehele.

Vastuspäring 1911

Kasutatakse ebaõnnestunud tehingust teatamiseks.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (1911).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_SND_ID 15 Päringu koostaja (Panga) ID.
4 VK_REC_ID 15 Päringu vastuvõtja (Kaupmehe) ID.
5 VK_STAMP 20 Päringu ID.
6 VK_REF 35 Maksekorralduse viitenumber.
7 VK_MSG 95 Maksekorralduse selgitus.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).
- VK_AUTO 1 Y = panga poolt automaatselt saadetud vastus. N = vastus kliendi liikumisega kaupmehe lehele.

Autentimispäringud

Vastavuses uuendatud tehnilise spetsifikatsiooniga.

Vastuspäring 3012

Kaupmehele edastatakse Panga poolt tuvastatud kasutaja andmed. Turvalisuse huvides peab sõnumi saaja lisaks allkirjale (VK_MAC) kontrollima ka sõnumi saaja ID-d (VK_REC_ID) ning sõnumi genereerimise kuupäeva ja kellaaega (VK_DATETIME), mis tohib erineda kontrollimise hetkel kehtivast maksimaalselt ±5 minutit.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (3012).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_USER 16 Kokkuleppeline kasutaja identifikaator.
4 VK_DATETIME 24 Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
5 VK_SND_ID 15 Sõnumi koostaja (Panga) ID.
6 VK_REC_ID 15 Sõnumi saaja (Kaupmehe) ID.
7 VK_USER_NAME 140 Kasutaja nimi.
8 VK_USER_ID 20 Kasutaja isikukood.
9 VK_COUNTRY 2 Isikukoodi riik (kahetäheline ISO 3166-1).
10 VK_OTHER 150 Muu info kasutaja kohta.
11 VK_TOKEN 2 Autentimisvahendi identifikaatori kood: 1 - ID-kaart; 2 - Mobiil-ID; 5 - ühekordsed koodid (v.a. PIN-kalkulaator); 6 - PIN-kalkulaator; 7 - korduvkasutusega kaart; 9 – Smart-ID; 12 - Biomeetria.
12 VK_RID 30 Sessiooniga seotud identifikaator.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).

Vastuspäring 3013

Kaupmehele edastatakse vastusena päringule 4012 Panga poolt tuvastatud kasutaja andmed ja nonssi koopia. Turvalisuse huvides peab sõnumi saaja lisaks allkirjale (VK_MAC) ja nonssile (VK_NONCE) kontrollima ka sõnumi saaja ID-d (VK_REC_ID) ning sõnumi genereerimise kuupäeva ja kellaaega (VK_DATETIME), mis tohib erineda kontrollimise hetkel kehtivast maksimaalselt ±5 minutit.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (3013).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_DATETIME 24 Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
4 VK_SND_ID 15 Sõnumi koostaja (Panga) ID.
5 VK_REC_ID 15 Sõnumi saaja (Kaupmehe) ID.
6 VK_NONCE 50 Päringus olnud nonssi koopia.
7 VK_USER_NAME 140 Kasutaja nimi.
8 VK_USER_ID 20 Kasutaja isikukood.
9 VK_COUNTRY 2 Isikukoodi riik (kahetäheline ISO 3166-1).
10 VK_OTHER 150 Muu info kasutaja kohta.
11 VK_TOKEN 2 Autentimisvahendi identifikaatori kood: 1 - ID-kaart; 2 - Mobiil-ID; 5 - ühekordsed koodid (v.a. PIN-kalkulaator); 6 - PIN-kalkulaator; 7 - korduvkasutusega kaart; 9 – Smart-ID; 12 - Biomeetria.
12 VK_RID 30 Sessiooniga seotud identifikaator.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).

Päring 4011

Kaupmehe poolt Pangale saadetav päring kasutaja tuvastamiseks. Teenus avatud vastava lepingu sõlminud kaupmeestele. Vastuspäringu kood 3012.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (4011).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_SND_ID 15 Sõnumi koostaja (Kaupmehe) ID.
4 VK_REPLY 4 Oodatava vastuspaketi kood (3012).
5 VK_RETURN 255 Kaupmehe URL, kuhu vastatakse.
6 VK_DATETIME 24 Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
7 VK_RID 30 Sessiooniga seotud identifikaator.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).

Autentimispäring 4012

Kaupmehe poolt Pangale saadetav päring kasutaja tuvastamiseks. Teenus avatud vastava lepingu sõlminud kaupmeestele.
Vastuspäringu kood 3013.

Jrk Väljanimi Pikkus Kirjeldus
1 VK_SERVICE 4 Teenuse number (4012).
2 VK_VERSION 3 Kasutatav krüptoalgoritm (008 või 009).
3 VK_SND_ID 15 Sõnumi koostaja (Kaupmehe) ID.
4 VK_REC_ID 15 Sõnumi saaja (Panga) ID.
5 VK_NONCE 50 Päringu koostaja poolt genereeritud juhuslik nonss.
6 VK_RETURN 255 Kaupmehe URL, kuhu vastatakse.
7 VK_DATETIME 24 Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
8 VK_RID 30 Sessiooniga seotud identifikaator.
- VK_MAC 700 Kontrollkood e. allkiri.
- VK_ENCODING 12 Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
- VK_LANG 3 Soovitav suhtluskeel (EST, ENG või RUS).

Avalikud võtmed

  • LHV aktsepteerib sertifikaadipäringut ehk n-ö self-signed sertifikaati. Pangalingi lepingu sõlmimisel saadab pank kaupmehele avaliku võtme sertifikaadi, mille klient peab sisestama oma süsteemi ning sellega valideeritakse panga poolt saadetud pakette.

  • Klient peab genereerima omale avaliku ja salajase võtmepaari. Võtme loomisel soovitame lähtuda järgmistest tingimustest:

    • Signature algorithm - sha1RSA
    • Public key - RSA(2048 Bits)
    • Kehtivusaeg mitte üle 10 aasta

    Kasutame X.509 standardile vastavaid .PEM formaadis võtmeid/sertifikaate st. sisu on BASE64 kodeeringus ning märgendite –BEGIN… – ja –END… – vahel. Kliendi poolt genereeritud salajase võtme minimaalne pikkus peab olema 2048 bitti.
    Võtmepaari saab genereerida käsurealt openssl utiliidi abil:

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

    Avalik võti tuleb panka tagasi saata ning seejärel pangalink aktiveeritakse.

Kontrollkoodi VK_MAC leidmine

Päringutes kasutatava elektroonse allkirja VK_MAC arvutus toimub kokkuleppelise algoritmi alusel. Algoritmi versiooni määrab päringu parameeter VK_VERSION. Allkiri VK_MAC edastatakse päringutes BASE64 kodeerituna. Kasutusel kaks versiooni:

  1. VK_MAC(MAC008) arvutatakse kasutades avaliku võtme algoritmi RSA ning räsialgoritmi SHA-1. MAC008(x1,x2,…,xn) := RSA( SHA-1(p(x1)|| x1|| p(x2)|| x2 || … ||p( xn )||xn), d, n).
  2. VK_MAC(MAC009) arvutatakse kasutades avaliku võtme algoritmi RSA ning räsialgoritmi SHA-512. MAC009(x1,x2,…,xn) := RSA( SHA-512(p(x1)|| x1|| p(x2)|| x2 || … ||p( xn )||xn), d, n).

Selgitused:

  • x1, x2, …, xn on päringu parameetrid.
  • p on uuele spetsifikatsioonile vastavate päringute puhul (1011, 1012, 1111, 1911, 3012, 3013, 4011, 4012) funktsioon parameetri pikkusest sümbolites. Pikkus on formateeritud kolmekohalise stringi kujul. Ehk siis pikkus 1 on “001”. Tühjade väljade pikkus on “000”.
  • d on RSA salajane eksponent.
  • n on RSA modulus.
  • || - stringide liitmistehe.