SVEA HOSTED SERVICE SPECIFICATION V1.13

Transcription

1 SVEA HOSTED SERVICE SPECIFICATION V1.13 Table of Contents Abstract... 2 Modes of operation... 2 Interactive Mode details... 2 Integration... 2 Input parameters... 3 Output parameters... 8 Error Codes... 9 Svea s Payment Methods Auriga s Payment Methods Supported Languages Supported Countries Supported Currencies

2 Abstract Svea Hosted Service is a web application provided by SveaWebPay. Svea Hosted Service aggregates different types of payment methods such as payment by invoice, by credit card, installment plan and more. The Service greatly simplifies management and handling of on-line payments and allows web shops to take advantage of new payment methods as they become available. Modes of operation Svea Hosted Service supports two modes of operation: interactive and pass-through. The interactive mode allows a customer to select a payment method in a GUI. In pass-through mode a merchant s web shop is responsible for selecting a payment method, either by providing the customer with a selection choice or by other means. The payment method is then sent to the Hosted Service as an optional parameter. Interactive Mode details As a customer, using a web browser, proceeds to check out from a merchant s web shop, the web shop directs the web browser to Svea Hosted Service. The customer is presented with a choice of selecting different payment methods. Once the customer has selected a payment method and paid the order, Svea Hosted Service registers the transaction and directs the customer back to the web shop. Integration Integration of merchants web shops can be done by sending a HTTP GET or POST method to the following URL: with parameters describing a payment as specified below. 2

3 Input parameters Input parameters are sent to Svea Hosted Service by a merchant s webshop. Parameter Type Mandatory Default Description Encoding 1 string(20) NO UTF-8 One of: UTF-7 UTF-8 ISO windows-1252 Username string(100) YES Merchant s username as per SveaWebPay account. Row#AmountExVAT 2 number(15,2) YES Order row, amount excluding VAT. Row#VATPercentage 2 number(2) YES Order row, VAT percentage of the amount. Row#Description 2 string(40) YES Order row, description of the merchandise. Row#Quantity 2 number(7,2) YES Order row, the number of units being purchased. OrderId string(30) YES A string uniquely identifying an order within merchant s web shop. PaymentMethod string(20) NO One of: internetbank card invoice partpayment If not specified, the user is presented with an interactive GUI prompting to select the appropriate payment method. ResponseURL 3 URL YES Encoded URL to which a customer s web browser is directed once payment transaction is completed. CancelURL 4 URL NO Encoded URL to which a customer s web browser is directed when the customer cancels/aborts a transaction. CallbackURL 5 URL NO Encoded URL used for Server to Server communication. TestMode string(5) NO false One of: true false Specifies whether a payment is carried out in test mode. Should be used during test only. Language 6 string(2) NO As per ISO alpha-2. Country 7 string(2) NO As per ISO alpha-2. Currency string(3) YES As per ISO Version number(1) NO 2 Communication protocol version. Presently 2. MD5 8 string(32) YES Authentication checksum. Table 1.1: Svea Hosted Service input parameters. 3

4 Important: When using the HTTP GET method, the maximum length of the query string is limited to 1024 characters in Internet Explorer. Therefore it is recommended that HTTP POST is used in order to support orders containing a large amount of items or long item descriptions. Notes: 1) If not specified, encoding is retrieved from the HTTP session. For a full list of supported encodings and their respective names see: 2) Row#AmountExVAT, Row#VATPercentage, Row#Description and Row#Quantity specify numbered order items. For each order row substitute the # with a number starting with 1. 3) ResponseURL must be a valid URL provided by merchant s web shop to which the end-user s web browser is re-directed by Svea Hosted Service once payment transaction is completed. Both successful and failed transactions are redirected to the ResponseURL. 4) CancelURL must be a valid URL provided by merchant s web shop to which the end-user s web browser is re-directed by Svea Hosted Service when the user cancels the transaction. 5) CallbackURL is an optional URL provided by merchant s web shop. It is used by Svea Hosted Service to asynchronously (using Server to Server POST) communicate the following events: a. A completed transaction (with the same parameters as sent to the ResponseURL). b. A cancelled transaction (with the same parameters as sent to the CancelURL). c. An error within Svea Hosted Service (such as e.g. insufficient funds, a technical error, etc) which prevents the user from proceding to comlete the transaction. The user is presented with an error message within the GUI and the error event is communicated through the CallbackURL with the relevant parameters such as ErrorCode. 6) For more information and a list of valid language codes see: Defaults to browser language if left empty. If no browser language is found, it defaults to Swedish. 7) For more information and a list of valid country codes see: Defaults to browser language country if left empty. If no browser language is found, it defaults to Sweden. 8) The MD5 checksum is used to sign the URL and parameter list (of both incoming and outgoing requests) to increase the security during communication between a web shop and Svea Hosted Service. Two code examples (for GET and POST, respectively) of how to construct and use an MD5 signed HTTP request is provided below: Generating the MD5 checksum when using HTTP GET: string username = "username"; string password = "password"; const string encoding = "UTF-8"; 4

5 const string serviceurl = " const string responseurl = " Dictionary<string, string> container = new Dictionary<string, string>(); container.add("encoding", encoding); container.add("username", username); container.add("responseurl", responseurl); container.add("testmode", "True"); container.add("language", "SV"); container.add("country", "SE"); container.add("currency", "SEK"); // add other payment params... // flatten the request parameters into a string and // apply the proper Encoding to the parameter values string parameters = ""; foreach(keyvaluepair<string, string> pair in container) parameters += pair.key + "=" + HttpUtility.UrlEncode(pair.Value, Encoding.GetEncoding(encoding)) + "&"; parameters = parameters.remove(parameters.lastindexof('&')); // construct HTTP target URL with request parameters // and compute MD5 checksum for it string url = serviceurl + "?" + parameters; string target = url + "&MD5=" + Util.MD5.compute(url + password); // go to the target URI Response.Redirect(target); 5

6 Generating the MD5 checksum when using HTTP POST: The checksum is calculated from a concatenated string all of the values of the following parameters in this exact order: Encoding Username Language Country Currency OrderId CancelURL ResponseURL CallbackURL Testmode Then, for each row number i, the values of: RowiAmountexvat RowiVatpercentage RowiQuantity RowiDescription And finally: Paymentmethod Password Example: Post.aspx.cs: string username = "username"; string password = "password"; const string encoding = "UTF-8"; const string responseurl = " Dictionary<string, string> postdatacontainer = new Dictionary<string, string>(); postdatacontainer.add("encoding", encoding); postdatacontainer.add("username", username); postdatacontainer.add("language", "SV"); postdatacontainer.add("country", "SE"); postdatacontainer.add("currency", "SEK"); // add the rest of the payment parameters... // the following string will be used for calculating the MD5 checksum string postdatavalues = container["encoding"] + container["username"] 6

7 + container["language"] + container["country"] + container["currency"] + container["orderid"] + container["cancelurl"] + container["responseurl"] + (container.containskey("callbackurl")? container["callbackurl"] : "") + container["testmode"]; foreach (KeyValuePair<string, string> row in container) { if (row.key.startswith("row")) MD5string += row.value; } string postmd5 = Util.MD5.compute(postDataValues + password); postdatacontainer.add("md5", postmd5); // add form fields to the page which can then be submitted via POST protected void Page_Load(object sender, EventArgs e) { foreach (KeyValuePair<string, string> pair in postdatacontainer) ClientScript.RegisterHiddenField(pair.Key, pair.value); } Post.aspx: <body> <!--- page content goes here --> <form id="postform" runat="server" enctype="application/x-www-formurlencoded" action=" epayment.aspx"> </form> <!--- rest of the page content --> </body> The form postform will be submitted to the payment gateway with the POST data fetched from the dictionary. In this example the data is placed within hidden HTML form fields. Note that in this example we are using a proprietary MD5 class for hashing, but it is equivalent to the built-in C# System.Security.Cryptography.MD5CryptoServiceProvider class. Remarks: Most input parameters are processed by Svea Hosted Service in a case-insensitive manner. For instance, parameters TestMode=true and testmode=true are synonymous. The exceptions are Username, Password, OrderId and Row#Description. The input URL must be in normalized form, i.e. it may not contain reserved characters such as e.g. spaces. This is to ensure that the MD5 value computed during the request from a client s web shop 7

8 and the MD5 computed by Svea Hosted Service of the received URL can be matched successfully. See RFC1738 ( for more information. The input URL may not contain any HTML tags, SQL queries or other strings that can be considered potentially dangerous by Svea Hosted Service. For instance, specifying a string such as <b>rabatt</b> in description input parameter will result in rejection of the entire request by Internet Information Server (IIS). Output parameters Output parameters are sent to a webshop s ResponseURL, CancelURL and CallbackURL once a payment transaction is completed: Parameter Type Always present Description Success string YES One of: true false Indicates whether the payment transaction was successful. ErrorCode number NO An error code specifying the reason of a failed transaction. Only present when Success=false. See table 2.1 below for a list of error codes. PaymentMethod string YES One of Svea s or Auriga s Payment Method codes (see tables below) used diring transaction. OrderId string YES A string uniquely identifying an order within merchant s web shop. Firstname string NO The first name of the customer. Available only when using PaymentMethod invoice or partpayment. Lastname string NO The last name of the customer. Available only when using PaymentMethod invoice or partpayment. AddressLine1 string NO The address of the customer. Available only when using PaymentMethod invoice or partpayment. AddressLine2 string NO As above. PhoneNumber string NO The phone number of the customer, if any. Available only when using PaymentMethod invoice or partpayment. PostArea string NO The post area of the customer, if any. Available only when using PaymentMethod invoice or partpayment. PostCode number NO The post code of the customer, if any. Available only when using PaymentMethod invoice or partpayment. SecurityNumber string NO Identification number of the legal entity (person or company) that made the purchase. This parameter is only sent out if the specified ResponseURL resides on an SSL secured server (i.e. the Uri scheme is HTTPS). 8

9 Version number YES Communication protocol version. Presently 2. MD5 string YES Authentication checksum. Table 1.2: Svea Hosted Service output parameters. Error Codes Error Code Description 0xx payment result errors 1 The payment has been cancelled by the user before the transaction was completed. 2 Invalid or incorrect information was provided by the user (such as personal identification number etc). 3 Payment was rejected by the bank (the user lacks credit, reported as abusive etc). 4 Internal system error such as databases are down, resources not available etc. 5 External system error. A third party system was unable to service the payment request and reported an error. 1xx - missing/malformed input parameters 100 Malformed input parameter 'Encoding'. 101 Missing mandatory input parameter 'OrderId'. 102 Missing mandatory input parameter 'ResponseURL'. 103 Missing mandatory input parameter 'CancelURL'. 104 Malformed input parameter 'TestMode'. 105 Missing mandatory input parameter 'Currency'. 106 Missing mandatory input parameter 'Username'. 107 Missing mandatory input parameter 'MD5'. 108 Malformed input parameter 'Row#AmountExVat'. 109 Malformed input parameter 'Row#VATPercentage'. 110 Malformed input parameter 'Row#Quantity'. 111 Missing mandatory input parameter 'Row#Description'. 112 No Order rows specified. 130 Missing mandatory response parameter 'Status'. 131 Missing mandatory response parameter 'Status_code'. 132 Malformed response parameter 'Status_code'. 133 Missing mandatory response parameter 'Transaction_id'. 134 Malformed response parameter 'Transaction_id'. 2xx - internal system errors 200 Localization Manager does not support the specified language '<languageorlocale>' or country/region '< country>'. 201 Invalid payment method. 202 Invalid payment method specified as input parameter. 204 Operation not supported for this type of payment method. 205 None of the available payment methods can be used with the specified order amount. The amount is either too low or too high. 5xx - invalid credentials/authentication and user rights errors 500 Invalid username '<username>'. 501 Specified and computed authentication codes mismatch. 502 Specified and computed authentication codes mismatch. 503 Selected payment method not allowed. 504 Selected payment method not allowed. 9

10 505 Selected payment method can not be used. 511 Invalid context: the session has expired or you are not authorized to access this page. 512 Invalid context: unknown response server IP (if valid it must be added to 'ResponseServerWhitelist' in web.config)! Table 2.1: Error Codes. Svea s Payment Methods Payment Method PARTPAYMENTSE INVOICESE Table 2.2: Svea s Payment Methods. Description Payment plan Invoice Auriga s Payment Methods Payment Method AKTIA BANKAXNO EKOP FSPA GIROPAY INVOICE KORTABSE KORTINDK KORTINFI KORTINNO KORTINSE NETELLER NORDEADK NORDEAFI NORDEASE OP PAYSONSE SAMPO SEBFTG SEBPRV SHB SHBNP Table 2.3: Auriga s Payment Methods. Description Aktia Bank Finland Direktbetalning Norge eköp (PlusGirot/Nordea) Swedbank Direktbetalning tyska banker Fakturabetalning Kortbetalning Abonnemang Sverige Kortbetalning Danmark PBS Kortbetalning Finland Luottokunta Kortbetalning Norge BBS Kortbetalning Sverige Plånbok NETELLER Nordea Bank Denmark Nordea Bank Finland Nordea Bank Sweden OP-Gruppen Finland Payson i Sverige Sampo Bank Finland SE-Banken för Företag SE-Banken för privatpersoner Handelsbanken Delfinansiering via HSB:s Netpay 10

11 Supported Languages For more information see e.g.: Language Code SV NB FI DA EN Table 3.1: Supported Languages. Language name Swedish Norwegian Bokmål Finnish Danish English Supported Countries For more information see e.g.: Country Code SE NO FI DK Table 3.2: Supported Countries. Country name Sweden Norway Finland Denmark Supported Currencies For more information see e.g.: Currency Code SEK NOK EUR DKK Table 3.3: Supported Currencies. Currency name Swedish krona Norwegian krone Euro (European Union countries) Danish krone 11