Bank link technical specifications. Information for programmers

Transcription

1 Bank link technical specifications Information for programmers

2 Content Content...2 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 Query Query Digital signing...7 Instructions for generating digital key...7 Examples...8 VK_MAC control code calculation...11 The use of Logo and references

3 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 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 Bank always replies using the encoding specified by merchant. If encoding is not explicitly specified, ISO 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 abovementioned 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

4 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: 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

5 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 (by default) or UTF-8 Query 1101 Used for replying about the execution of a domestic payment order. No. Field Length Description 1 VK_SERVICE 4 Service number (1101) 2 VK_VERSION 3 Used encryption algorithm (008) 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) 5 VK_STAMP 20 Query 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

6 13 VK_REF 20 Payment order reference number 14 VK_MSG 300 Description of payment order 15 VK_T_DATE 10 Payment order date - VK_MAC 300 Control code or signature - VK_LANG 3 Preferable language of communication (LIT, ENG or RUS) - VK_AUTO 1 Y= reply automatically sent by the Bank. N= reply by moving the customer to the merchant s page. - VK_ENCODING - Message encoding. ISO (by default) or UTF-8 Query 1901 Used for notifying of a failed transaction. No. Field Length Description 1 VK_SERVICE 4 Service number (1901) 2 VK_VERSION 3 Used encryption algorithm (008) 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) 5 VK_STAMP 20 Query ID 6 VK_REF 20 Payment order reference number 7 VK_MSG 300 Description of payment order - VK_MAC 300 Control code or signature - VK_LANG 3 Preferable language of communication (LIT, ENG or RUS) - VK_AUTO 1 N=reply by moving the customer to the merchant s page. - VK_ENCODING - Message encoding. ISO (by default) or UTF-8 6

7 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 ( 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 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 ( Address) = Partners contact address (I.e. info@partnerdomain.lt) CN (Common Name) = FQDN which will use the Banklink service (i.e. 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 ). 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

8 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 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,E6C541BC A UM49jAy/j7b1JTcuaWJzseIQBk+P7ZOWI6Wp9myGiDk+0+AVj4klNaNOWiH1L3kT Fma3rOuKGF80ntoPNWcjEcLgK4Zjte026XXcr2w/yM1E8yVlmjVcrLAjR1l9bfe1 rkigdjvesyujgdi61rdcfeabcso/e5nl4p0m139pev4paog03vnvalnqcmi30ghw BhDK9T2kpwG2rz1ATTf30e7GzpMWvpd7ONMV+39flHAMg7IgRy3GBbERjrwsalxr 8

9 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/ =webmaster@swedbank.lt 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

10 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: (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----- MIICPDCCAaWgAwIBAgICd7wwDQYJKoZIhvcNAQEFBQAwOzELMAkGA1UEBhMCRUUx EjAQBgNVBAoTCUhhbnNhcGFuazEYMBYGA1UEAxMPQVMgSGFuc2FwYW5rIENBMB4X DTEyMTExNTA3MDQyMVoXDTE1MTExNjA3MDQyMVowODELMAkGA1UEBhMCTFQxETAP BgNVBAoTCFN3ZWRiYW5rMRYwFAYDVQQDEw1CYW5rbGluayBIb3N0MIGfMA0GCSqG SIb3DQEBAQUAA4GNADCBiQKBgQDRaR94bIp05bc/o2ccvWmwuUEfN1WFUPL0wMXN 1Wv1rWX68ay7liS/LBzc3gBq9ungBLlFfaYxBohcJf43gNiZPzdUkBcXJnTeDZxd UzuRuzHA+JOyWqbt4lcZ4K1l405LJsl5qaXApendeftIN2RpcCK/59Oqyu6thK05 JB1HRQIDAQABo1IwUDAOBgNVHQ8BAf8EBAMCBPAwHQYDVR0OBBYEFGT0PNTdXiM+ /v9yd2xgd1qdoydzmb8ga1udiwqymbaaflr8h8/fi71r8gcjojotkuvjcvcxma0g CSqGSIb3DQEBBQUAA4GBAJjAuuLMSoK69Xof5SrQ6MPEEulsfr9mvOLvKDsR64L3 Cdsp+UF+fMEcZ9gSr70J2xFnp8V78GRYe5NdP++ujKQ8sS2gJYQiWTX3bg0SDq+j 42A8X2ZVsDwOA+P2uyXbpVDu12xHGQxVUAP49oZNAgf99v60gf74Z5YzrDMp0Fuc -----END CERTIFICATE

11 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(x 1,x 2,,x n ) := RSA( SHA-1(p(x 1 ) x 1 p(x 2 ) x 2 p( x n ) x n ),d,n) Where: is an operation of adding the string x 1, x 2,, x n 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= VK_AMOUNT=1.99 VK_CURR=EUR VK_REF= 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): TRADER EUR Payment for a good XXXXXX in one row: TRADER EUR Payment for a 11

12 good XXXXXX or if the VK_MSG parameter is empty, the result: TRADER EUR 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: Swedbank Logo is designed from two parts: word Swedbank and the symbol, in witch 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 pixels, graphic expression 96 dpi:. 3. Graphic file (colored Bank Logo), witch name is logotyp_webb_180x40.gif, size of the *gif 180X40 pixels, graphic expression 96 dpi:. In all times there must be used colored Logo and always in white or black background. The the background ir colorfull or motley, under the Logo must be drawn white or black rectangular. 12