Pangalingi tehniline spetsifikatsioon

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

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (1011).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_SND_ID15Päringu koostaja (Kaupmehe) ID.
4VK_STAMP20Päringu ID.
5VK_AMOUNT12Maksmisele kuuluv summa. Komakohad ja sendid eristatud punktiga ".". Tuhandete eraldajat ei asutata.
6VK_CURR3Makse valuuta (EUR).
7VK_ACC34Saaja konto number.
8VK_NAME70Saaja nimi.
9VK_REF35Maksekorralduse viitenumber.
10VK_MSG95Maksekorralduse selgitus.
11VK_RETURN255URL, kuhu vastatakse edukal tehingu sooritamisel.
12VK_CANCEL255URL, kuhu vastatakse ebaõnnestunud tehingu puhul.
13VK_DATETIME24Päringu algatamise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03- 13T07:21:14+0200.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav 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”.

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (1012).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_SND_ID15Päringu koostaja (Kaupmehe) ID.
4VK_STAMP20Päringu ID.
5VK_AMOUNT12Maksmisele kuuluv summa. Komakohad ja sendid eristatud punktiga ".". Tuhandete eraldajat ei kasutata.
6VK_CURR3Makse valuuta (EUR).
7VK_REF35Maksekorralduse viitenumber.
8VK_MSG95Maksekorralduse selgitus.
9VK_RETURN255URL, kuhu vastatakse edukal tehingu sooritamisel.
10VK_CANCEL255URL, kuhu vastatakse ebaõnnestunud tehingu puhul.
11VK_DATETIME24Päringu algatamise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav suhtluskeel (EST, ENG või RUS).

Vastuspäring 1111

Kasutatakse vastamiseks maksekorralduse toimumisest

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (1111).
2VK_VERSION3Kasutatav krüptoalgoritm 008.
3VK_SND_ID15Päringu koostaja (Panga) ID.
4VK_REC_ID15Päringu vastuvõtja (Kaupmehe) ID.
5VK_STAMP20Päringu ID.
6VK_T_NO20Maksekorralduse number.
7VK_AMOUNT12Makstud summa. Komakohad ja sendid eristatud punktiga ".". Tuhandete eraldajat ei kasutata.
8VK_CURR3Makse valuuta (EUR).
9VK_REC_ACC34Saaja konto number.
10VK_REC_NAME70Saaja nimi.
11VK_SND_ACC34Maksja konto number.
12VK_SND_NAME70Maksja nimi.
13VK_REF35Maksekorralduse viitenumber.
14VK_MSG95Maksekorralduse selgitus.
15VK_T_DATETIME24Maksekorralduse kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav suhtluskeel (EST, ENG või RUS).
-VK_AUTO1Y = panga poolt automaatselt saadetud vastus. N = vastus kliendi liikumisega kaupmehe lehele.

Vastuspäring 1911

Kasutatakse ebaõnnestunud tehingust teatamiseks.

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (1911).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_SND_ID15Päringu koostaja (Panga) ID.
4VK_REC_ID15Päringu vastuvõtja (Kaupmehe) ID.
5VK_STAMP20Päringu ID.
6VK_REF35Maksekorralduse viitenumber.
7VK_MSG95Maksekorralduse selgitus.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav suhtluskeel (EST, ENG või RUS).
-VK_AUTO1Y = 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.

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (3012).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_USER16Kokkuleppeline kasutaja identifikaator.
4VK_DATETIME24Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
5VK_SND_ID15Sõnumi koostaja (Panga) ID.
6VK_REC_ID15Sõnumi saaja (Kaupmehe) ID.
7VK_USER_NAME140Kasutaja nimi.
8VK_USER_ID20Kasutaja isikukood.
9VK_COUNTRY2Isikukoodi riik (kahetäheline ISO 3166-1).
10VK_OTHER150Muu info kasutaja kohta.
11VK_TOKEN2Autentimisvahendi identifikaatori kood: 1 - ID-kaart; 2 - Mobiil-ID; 5 - ühekordsed koodid (v.a. PIN-kalkulaator); 6 - PIN-kalkulaator; 7 - korduvkasutusega kaart; 9 – Smart-ID.
12VK_RID30Sessiooniga seotud identifikaator.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav 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.

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (3013).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_DATETIME24Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
4VK_SND_ID15Sõnumi koostaja (Panga) ID.
5VK_REC_ID15Sõnumi saaja (Kaupmehe) ID.
6VK_NONCE50Päringus olnud nonssi koopia.
7VK_USER_NAME140Kasutaja nimi.
8VK_USER_ID20Kasutaja isikukood.
9VK_COUNTRY2Isikukoodi riik (kahetäheline ISO 3166-1).
10VK_OTHER150Muu info kasutaja kohta.
11VK_TOKEN2Autentimisvahendi identifikaatori kood: 1 - ID-kaart; 2 - Mobiil-ID; 5 - ühekordsed koodid (v.a. PIN-kalkulaator); 6 - PIN-kalkulaator; 7 - korduvkasutusega kaart.
12VK_RID30Sessiooniga seotud identifikaator.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav 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.

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (4011).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_SND_ID15Sõnumi koostaja (Kaupmehe) ID.
4VK_REPLY4Oodatava vastuspaketi kood (3012).
5VK_RETURN255Kaupmehe URL, kuhu vastatakse.
6VK_DATETIME24Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
7VK_RID30Sessiooniga seotud identifikaator.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav 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.

JrkVäljanimiPikkusKirjeldus
1VK_SERVICE4Teenuse number (4012).
2VK_VERSION3Kasutatav krüptoalgoritm (008).
3VK_SND_ID15Sõnumi koostaja (Kaupmehe) ID.
4VK_REC_ID15Sõnumi saaja (Panga) ID.
5VK_NONCE50Päringu koostaja poolt genereeritud juhuslik nonss.
6VK_RETURN255Kaupmehe URL, kuhu vastatakse.
7VK_DATETIME24Sõnumi genereerimise kuupäev ja kellaaeg ISO 8601 formaadis sekundi täpsusega koos ajatsooni infoga. Nt 2013-03-13T07:21:14+0200.
8VK_RID30Sessiooniga seotud identifikaator.
-VK_MAC700Kontrollkood e. allkiri.
-VK_ENCODING12Sõnumi kodeering. ISO-8859-1 või UTF-8 (vaikeväärtus) või WINDOWS-1257.
-VK_LANG3Soovitav 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. Hetkel on kasutusel ainult versioon 008. Allkiri VK_MAC edastatakse päringutes BASE64 kodeerituna, 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).

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