„bank link“ technical specifications · 2018. 11. 20. · „bank link“ technical...

„Bank link“ Technical specifications

Information for programmers

2017 11 15

Content

Rules of services........................................................................................................................................... 3

Queries ..................................................................................................................................................... 3

Queries from the merchant to the bank .................................................................................................... 4

Queries from the bank to the merchant .................................................................................................... 4

Finding the VK_MAC control code ......................................................................................................... 4

Query specifications .................................................................................................................................... 5

Query “1002“ ........................................................................................................................................... 5

Query “1101” ........................................................................................................................................... 5

Query “1901” ........................................................................................................................................... 6

Digital signing .............................................................................................................................................. 7

Instructions for generating digital key ..................................................................................................... 7

Examples ................................................................................................................................................. 8

VK_MAC control code calculation ....................................................................................................... 11

The use of Logo and references ................................................................................................................. 12

2

Rules of services

Queries

Queries are HTTP GET or POST queries with specified parameters. Each query contains a service number. Each

service has a unique list of parameters and its own algorithm for handling the query. By content, the service

number is the algorithm number of query handling. All parameters whose field names do not begin with “VK_”

must be ignored.

In the amount parameters dot “.” Is used as decimal separator. Thousands separator is not used.

Dates are presented in the format "DD.MM.YYYY," e.g. 17.02.2001

The time is indicated in the format "hh24:min:sec," e.g. 17:02:59

The length of the value of the parameter must not exceed that which is prescribed in the

specifications. Upon exceeding the length, a query is not processed.

The values of parameters can be shorter than the permitted maximum length. Missing places are not filled

in. The spaces at the beginning and at the end of the value of a parameter are removed.

An error message is sent in reply to queries that do not match the specifications and are invalid.

Operations to be performed on the basis of a query are carried out pursuant to the general

requirements of the service (requirements of payment orders, etc.).

Merchant specifies the query encoding using VK_ENCODING parameter, supported encodings are UTF-8

and ISO-8859-13. Bank always replies using the encoding specified by merchant. If encoding is not

explicitly specified, ISO-8859-13 is used by default.

Queries can be divided into merchant or bank queries according to their originator. Queries can be divided into

those that require a reply and that do not require a reply.

Using HTTP_POST and HTTP_GET type of request:

HTTP_POST type of request is used when the payer push the “Go back to Merchant” button (when the

payment is successful and the payer gets the payment confirmation text with the above- mentioned text)

HTTP_GET type of request ir used with all automatic answers (automatic answer: VK_AUTO=Y)

For the smooth service working merchant system must be able to use both types of requests.

3

Queries from the merchant to the bank

Queries from the merchant to the bank are meant for the direction and/or assistance of the customer in the

performance of an operation, e.g. a payment order. Each query corresponds to one service. The presented

parameters are verified according to the service. The list of parameters of a query and the order depends on the

service used. The bank replies to the queries that require a reply after having completed the customer's operation.

As a rule, a reply contains the details of the operation and a notice about whether it was successful.

Queries from the merchant to the bank are directed to the URL:

https://ib.swedbank.lt/banklink

Queries from the bank to the merchant

As a rule, queries from the bank to the merchant are replies to the previous queries of the merchant. At the same

time the client may initiate a query from the Bank to a merchant by entering the merchant's page through the E-

services page on the Internet bank.

Finding the VK_MAC control code

Verification of the electronic signature used in queries, VK_MAC, takes place on the basis of the agreed

algorithm VK_VERSION. Only version 008 is currently used.

VK_MAC is given as the query’s parameter value in the BASE64 encoding.

4

https://ib.swedbank.lt/banklink

Query specifications

A URL with parameters cannot be used in the VK_RETURN field.

Query “1002“

The merchant sends to the Bank the details of a signed payment order which the client cannot change on the

Internet bank. After a successful payment the query “1101” is made for the merchant, in the case of a failed

payment the “1901” package. The details of the recipient are taken from a “Bank link” agreement.

No. Field Length Description

1 VK_SERVICE 4 Service number (1002)

2 VK_VERSION 3 Used encryption algorithm (008)

3 VK_SND_ID 10 ID of the author of the query (merchant's ID)

4 VK_STAMP 20 Query ID

5 VK_AMOUNT 17 Amount payable

6 VK_CURR 3 Name of the currency in the ISO 4217 format (EUR, etc.)

7 VK_REF 20 Payment order reference number

8 VK_MSG 300 Description of payment order

- VK_MAC 700 Control code or signature

- VK_RETURN 150 URL where the transaction response query is sent (1101, 1901)

- VK_LANG 3 Preferable language of communication (LIT, ENG or RUS)

- VK_ENCODING - Message encoding. ISO- 8859-13 (by default) or UTF-8

Query “1101”

Used for replying about the execution of a domestic payment order.




3 VK_SND_ID 10 ID of the author of the query (Bank's ID)

4 VK_REC_ID 10 ID of the author of the query (merchant's ID)


6 VK_T_NO 300 Payment order number

7 VK_AMOUNT 17 Amount paid

8 VK_CURR 3 Name of the currency in the ISO 4217 format (EUR, etc.)

9 VK_REC_ACC 34 Recipient’s invoice number

10 VK_REC_NAME 70 Recipient’s name

11 VK_SND_ACC 34 Remitter's account number

12 VK_SND_NAME 40 Remitter's name

5



15 VK_T_DATE 10 Payment order date



- VK_AUTO 1 Y= reply automatically sent by the Bank. N= reply by moving the customer to the

merchant’s page.


Query “1901”

Used for notifying of a failed transaction.




3 VK_SND_ID 10 ID of the author of the query (Bank's ID)

4 VK_REC_ID 10 ID of the author of the query (merchant's ID)






- VK_AUTO 1 N=reply by moving the customer to the merchant’s page.


6

Digital signing

Instructions for generating digital key

For the service of “Bank Link” separate set of keys is recommended which should be different from the

WWW server certificate keys.

We recommend using OPENSSL (http://www.openssl.org) in order to generate the 1024 bit long private key for

“Bank Link” service. This key should be used to make a certificate request. Certificate request should be sent via e-

mail to your Swedbank Account Manager. Received Certificate request will be signed by Swedbank and certificate

file will be created.

The private key can be generated using this command:

openssl genrsa -out privkey.pem 1024

And certificate request can be made like this:

openssl req -new -key privkey.pem -out request.pem

The certificate request DN (distinguished name) should have the following form:

E (Email Address) = Partners contact email address (I.e. [email protected])

CN (Common Name) = FQDN which will use the Banklink service (i.e.

www.partnerdomain.lt)

OU (Organizational Unit Name) = “BankLink”

O (Organization Name) = Partners registered name (i.e. Company name UAB)

C (Country Name) = “LT”

L (location) = Partners registration location (i.e. Vilnius)

The outputs of these commands are 2 files: “privkey.pem” contains the private key (do not reveal this file content

to anybody) and “request.pem” contains the certificate request (which should be sent to the bank via email).

How you create private key and certificate request (open SSL):

openssl req -new -config <way to openssl.cnf> -out cert_request.pem -keyout private_key.pem

-You will be asked to create password for private key.

- You will be asked to enter data for certificate request (as described above in).

You can review created request by:

7

http://www.openssl.org/

mailto:[email protected]

http://www.partnerdomain.lt/

openssl req -in cert_request.pem -text -noout

You can save private key in noncoded form:

openssl rsa -in private_key.pem -out new_private_key.pem

You can review SSL certificate by:

openssl x509 -in cert.pem -text -noout

You can find step by step example here

http://www.modssl.org/docs/2.8/ssl_faq.html#ToC28

Examples

RSA private key, noncoded:

-----BEGIN RSA PRIVATE KEY-----

MIICXgIBAAKBgQCvqlkOMrYxGw85j7rkF+KNChajMJL+o6pwGK2bt1IRP/VQxWyB

4AqrljzcUDn1wWTmEzISEJqxF9t/WN8jWcdFCO1Zws5inYt0+WZqkZW+MXVCf+8g

sn8Tbdt7C69++ZH6MUqjJj+Q5EjauchXDmPWPg2v07HBZBIvAhTFDVE1ZwIDAQAB

AoGAMj3OarkmUrUijZwGH+aU7THNd68U26+Dt7vXK4oq9rQMPaW5ewvRAXJexcRM

T3WYnhUvZOtK0wu3w5xvdXTgAOz+Y7ZIIziQCut0+Uy4QERLnKGXZ4830DDh+M7m

oXeF3e+Eur4vx6Whg38jbZs+WyaRJqB2DgNnHhtakyZb/IECQQDkr2KKE6GSJT8h

FXih5Ux2boiN85ehZmN9Maprxviz3V90leyINL6dXapmBDBXClGV2QCDDOMqMEcw

nfqI31HJAkEAxKXBLrvveJ3G5YnOL0IhlGdpBURJtr7h3Pd6E9exdLJ0NBesaour

oj7eJ0+5CSHtCz9ST7S7WgtnguVGaERlrwJBANe8ZRehgXEf1jhdyxnf+YxYplZU

ER3gO8cljYJziLgWBTE1JpkwOQq4DEKFfRz/zQuyVftLsxpfxSkmP+3Tz5ECQQCs

f75rkX5qrvS3i9/rQraUKPZOIW4MOXuFyy0yVMYc2SHoRFABko23oDBeCagGI9V9

RUmeE6s5PMHLZ/YQJtePAkEAn/0DCozbYbz+xlGwhg7kHvH0LqCB6sITxfzMaFQb

T8EGmloj4wIkgvEImgBTyJ3xIZulcDwFpT9qApIKmcCm3Q==

-----END RSA PRIVATE KEY-----

The same RSA private key encoded with password "kala" (without quotes):

-----BEGIN RSA PRIVATE KEY-----

Proc-Type: 4,ENCRYPTED

DEK-Info: DES-EDE3-CBC,E6C541BC0138209A

UM49jAy/j7b1JTcuaWJzseIQBk+P7ZOWI6Wp9myGiDk+0+AVj4klNaNOWiH1L3kT

Fma3rOuKGF80ntoPNWcjEcLgK4Zjte026XXcr2w/yM1E8yVlmjVcrLAjR1l9bfe1

rKigDJVEsyUjGDI61rDcfEAbCSO/E5nl4P0M139PeV4paoG03VnvALNQcmI30gHW

BhDK9T2kpwG2rz1ATTf30e7GzpMWvpd7ONMV+39flHAMg7IgRy3GBbERjrwsalxr

8

http://www.modssl.org/docs/2.8/ssl_

http://www.modssl.org/docs/2.8/ssl_

dCMdhYyGvrnrBDQDmKuV95jZJu8siTeFDKlFINRS7DsLmhYXCIj50wOUizPLKvxV

dFvAZLiEVXWJ8UoZMn1+QYPNrEty1ox/0rFVM4o1rxK6zSyDoMAoNH6ynoWlLGDx

+nokFgobIWXvKZ2zHhm4+TUbF1cavOXX45yZ837/7udgDnQQ4P02vqpgI0w3oVGG

+5S4gU4ZCjUaax3L3UDAgYRagPY9kJGYcSiJ3399j6gUgcin7ebFAAhfKsi6ioRQ

GadiqhlACMKs30H2oxXJ+4rjNIP6zKlHvkYb3HFrpKOGdArN9KEX7qrOkWDpQaLS

pNlTjR1rKbzsLoqk9cbnRINf+8/Y0BHtnmhISmR0AM4uKYiAfcoCtwwfXMWG5oFT

OMF9oVCGLXFlNpPA60PpLvfYEwZuSEuLr2kJAMOfkSeJyDbInbztwKERRaB2LikC

LxGvpBBphCf48fR8EIQSN9VH7fSLLd3DohkLi5XupUZxxp58TG2WyqBz0isQPfp0

wGvz5ATJ5xtZQ6thrIZlayKV40zUiDSXu9N6ugRG/YJLCncaw8xrWg==

-----END RSA PRIVATE KEY-----

Certificate request in PEM format:

-----BEGIN CERTIFICATE REQUEST-----

MIIB+TCCAWICAQAwgY8xCzAJBgNVBAYTAkxUMRAwDgYDVQQHEwdWaWxuaXVzMRww

GgYDVQQKExNBQiBiYW5rYXMgSGFuc2EtTFRCMREwDwYDVQQLEwhCYW5rTGluazEa

MBgGA1UEAxMRYmFua2xpbmsuaGFuc2EubHQxITAfBgkqhkiG9w0BCQEWEndlYm1h

c3RlckBoYW5zYS5sdDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAr6pZDjK2

MRsPOY+65BfijQoWozCS/qOqcBitm7dSET/1UMVsgeAKq5Y83FA59cFk5hMyEhCa

sRfbf1jfI1nHRQjtWcLOYp2LdPlmapGVvjF1Qn/vILJ/E23bewuvfvmR+jFKoyY/

kORI2rnIVw5j1j4Nr9OxwWQSLwIUxQ1RNWcCAwEAAaApMCcGCSqGSIb3DQEJDjEa

MBgwCQYDVR0TBAIwADALBgNVHQ8EBAMCBPAwDQYJKoZIhvcNAQEEBQADgYEALdf7

7J/GLfGZE27vXRLJrqAvjZeeV3/QlJMQTjhFihVb8N9h6Z+s7e+VbgEpKq5feVot

gbN8oPPbSYC0TVPOdRpKIi7+IzfVWWFgSZxUGKqdkypaGcRM4qa+wgPFsUi6syhZ

c5gJDvcjp+lEUvOett2/KT7KLFiQs9o/glY8PEI=

-----END CERTIFICATE REQUEST-----

The same certificate request in text format:

Certificate Request:

Data:

Version: 0 (0x0)

Subject: C=LT, L=Vilnius, O=Swedbank AB, OU=BankLink,

CN=ib.swedbank.lt/[email protected]

Subject Public Key Info:

Public Key Algorithm: rsaEncryption

RSA Public Key: (1024 bit)

Modulus (1024 bit):

00:af:aa:59:0e:32:b6:31:1b:0f:39:8f:ba:e4:17:

e2:8d:0a:16:a3:30:92:fe:a3:aa:70:18:ad:9b:b7:

52:11:3f:f5:50:c5:6c:81:e0:0a:ab:96:3c:dc:50:

39:f5:c1:64:e6:13:32:12:10:9a:b1:17:db:7f:58:

9

mailto:[email protected]

df:23:59:c7:45:08:ed:59:c2:ce:62:9d:8b:74:f9:

66:6a:91:95:be:31:75:42:7f:ef:20:b2:7f:13:6d:

db:7b:0b:af:7e:f9:91:fa:31:4a:a3:26:3f:90:e4:

48:da:b9:c8:57:0e:63:d6:3e:0d:af:d3:b1:c1:64:

12:2f:02:14:c5:0d:51:35:67

Exponent: 65537 (0x10001)

Attributes:

Requested Extensions:

X509v3 Basic Constraints:

CA:FALSE

X509v3 Key Usage:

Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment

Signature Algorithm: md5WithRSAEncryption

2d:d7:fb:ec:9f:c6:2d:f1:99:13:6e:ef:5d:12:c9:ae:a0:2f:

8d:97:9e:57:7f:d0:94:93:10:4e:38:45:8a:15:5b:f0:df:61:

e9:9f:ac:ed:ef:95:6e:01:29:2a:ae:5f:79:5a:2d:81:b3:7c:

a0:f3:db:49:80:b4:4d:53:ce:75:1a:4a:22:2e:fe:23:37:d5:

59:61:60:49:9c:54:18:aa:9d:93:2a:5a:19:c4:4c:e2:a6:be:

c2:03:c5:b1:48:ba:b3:28:59:73:98:09:0e:f7:23:a7:e9:44:

52:f3:9e:b6:dd:bf:29:3e:ca:2c:58:90:b3:da:3f:82:56:3c:

3c:42

„Swedbank“, AB „Bank Link“ certificate:

-----BEGIN CERTIFICATE-----

MIIEDjCCAvagAwIBAgITVwAAAh/PBfcG6yBi9gAAAAACHzANBgkqhkiG9w0BAQUF

ADBOMQswCQYDVQQGEwJTRTEXMBUGA1UEChMOU3dlZGJhbmsgR3JvdXAxJjAkBgNV

BAMTHVN3ZWRiYW5rIEczIElzc3VpbmcgQ0EgVGllciBBMB4XDTE3MTEwNjA5MTAw

OVoXDTIwMTEwNTA5MTAwOVowODELMAkGA1UEBhMCTFQxETAPBgNVBAoTCFN3ZWRi

YW5rMRYwFAYDVQQDEw1CYW5rbGluayBIb3N0MIGfMA0GCSqGSIb3DQEBAQUAA4GN

ADCBiQKBgQDRaR94bIp05bc/o2ccvWmwuUEfN1WFUPL0wMXN1Wv1rWX68ay7liS/

LBzc3gBq9ungBLlFfaYxBohcJf43gNiZPzdUkBcXJnTeDZxdUzuRuzHA+JOyWqbt

4lcZ4K1l405LJsl5qaXApendeftIN2RpcCK/59Oqyu6thK05JB1HRQIDAQABo4IB

fTCCAXkwHQYDVR0OBBYEFGT0PNTdXiM+/v9Yd2xGD1qDoYdzMB8GA1UdIwQYMBaA

FAihXNOvBjSLItpZ/Qg6KAQ9wIRpMFQGA1UdHwRNMEswSaBHoEWGQ2h0dHA6Ly9p

bmZyYS5zd2VkYmFuay5jb20vcGtpL2NybC9Td2VkYmFua19HM19Jc3N1aW5nX0NB

X1RpZXJfQS5jcmwwXwYIKwYBBQUHAQEEUzBRME8GCCsGAQUFBzAChkNodHRwOi8v

aW5mcmEuc3dlZGJhbmsuY29tL3BraS9jcnQvU3dlZGJhbmtfRzNfSXNzdWluZ19D

QV9UaWVyX0EuY3J0MAsGA1UdDwQEAwIHgDA9BgkrBgEEAYI3FQcEMDAuBiYrBgEE

AYI3FQiD+8FigsjKGYf1jQeCwoAkgebsfGCCo+dNg/3yXAIBZAIBAzAVBgNVHSUE

DjAMBgorBgEEAYI3CgMMMB0GCSsGAQQBgjcVCgQQMA4wDAYKKwYBBAGCNwoDDDAN

BgkqhkiG9w0BAQUFAAOCAQEAPLcOnG0E3TH6w7wNu8TMsHGAy5jVo/KDQIwnFc1r

Wib679AWpNLkW9aiVghs+9xa+7Al2JFO83fbAwnwSCacif4UGodmdj7drAwwINsI

m4QiMBRY0c34FmokUxB88N8G/+qzKLMMZDL7ljEWtz8KZY31If4RTXTylMcLpU1r

2Y9lH/HH+fr+5wDXt/t+ikvbc2tEH6b+rByfjts7CGMXThb9QLRHnz5WwihYHmiC

iaXXIZr5BBYjzTQIgv9GD0JziRvhaD28Oeym394ICzxZJl3XzG25dY2KJNm1HWLu

u8n2e1CNTanCBA1Bv1S4V0OdyidLaTuJZ0y7ODa3+8trFQ==

-----END CERTIFICATE-----

10

VK_MAC control code calculation

VK_MAC, for electronic signature, using in the request, for checking and confirming used version of the

algorithm, indicated in the parameter VK_VERSION. In this time version 008 is used.

VK_MAC is presented as a request parameter in BASE64 coding.

Version 008

The value of the MAC008 function is calculated using the public key algorithm RSA. Values of empty fields are

taken into account as well – “000”.

MAC008(x1,x2,…,xn) := RSA( SHA-1(p(x1 )|| x1|| p(x2 )|| x2 || … ||p( xn )||xn),d,n)

Where:

|| is an operation of adding the string

x1, x2, …, xn are the query parameters

p is a function of the parameter length. The length is a number in the form of a three-digit string

d is the RSA secret exponent n

is the RSA modulus

The signature is calculated in accordance with the PKCS1 standard (RFC 2437).

Example:

Let us take a query with the following parameters:

VK_SERVICE=1002

VK_VERSION=008

VK_SND_ID=TRADER

VK_STAMP=1234567890

VK_AMOUNT=1.99

VK_CURR=EUR

VK_REF=01012001-001

VK_MSG=Payment for a good XXXXXX

The signature is calculated from the following data row which comprises the following elements (the

number of the symbols of the parameter values and the value of the parameter itself):

0041002

003008

006TRADER

0101234567890

0041.99

003EUR

01201012001-001

025Payment for a good XXXXXX

in one row:

“0041002003008006TRADER01012345678900041.99003EUR01201012001-001025Payment for a

11

good XXXXXX”

or if the VK_MSG parameter is empty, the result:

“0041002003008006TRADER01012345678900041.99003EUR01201012001-001000”

The use of Logo and references

By placing all banks general conditions corresponding GIF in internet store Merchant informs about possibility to

pay over „Swedbank“, AB and in the same time this GIF performs the function of the reference and turn Client to

the banks indicated internet page where the Client can meet all the information about “Bank Link” service. This

reference must direct to this Bank URL address: http://www.swedbank.lt/lt/pages/verslo/banklink

„Swedbank“ Logo is designed from two parts: word „Swedbank“ and the symbol, in which there is draw an oak.

These two parts always has to be used together.

Merchant must use these all banks general conditions corresponding *gif:

1. Graphic file (colored Bank Logo), witch name is „logotyp_webb_100x22.gif“, size of the *gif – 100X22

pixels, graphic expression – 96 dpi:

.

2. Graphic file (colored Bank Logo), witch name is „ logotyp_webb_150x34.gif“, size of the *gif – 150X34


.

3. Graphic file (colored Bank Logo), witch name is „ logotyp_webb_180x40.gif“, size of the *gif – 180X40


.

In all times there must be used coloured Logo and always in white or black background. The the background and

colourful or motley, under the Logo must be drawn white or black rectangular.

12

http://www.swedbank.lt/lt/pages/verslo/banklink

„bank link“ technical specifications · 2018. 11. 20. · „bank link“ technical...

Documents