GestPay Security with Encryption Technical Specifications

Transcription

1 GestPay Security with Encryption Technical Specifications Page 1 of 46

2 Summary Document information...3 Version information Introduction System Architecture Description of Process Phases Phase I: Transaction Data Encryption Phase II: Payment Page Call Phase III: Communication of Transaction Result Response to Merchant Response to Buyer Phase IV: Decryption of Transaction Result Authentication Structure of Transaction Data Transaction Data to Send to GestPay...13 Transaction Data Received by GestPay Merchant s Profile Authentication Configuration Configuration of response url and Configuration of Fields & Parameters Description of GestPayCrypt Object WebService...23 Instructions for use of encryption module with WEBSERVICE interface...23 List of calls available with WSCryptDecrypt webservice Software requirements Buyer browser requirements Merchant server requirements Installation of GestPayCrypt.class (Java) Installation of GestPayCrypt.dll (COM) Example transactions Transaction number Transaction number Examples of implementation Table of errors Table of currency codes Table of language codes Table of Verified by Visa codes Payment orders in test environment Links...46 Page 2 of 46

3 Document Information Project name: Title: Creation date Language: Company: GestPay GestPay - Security with Encryption Technical Specifications Marco Loro English EasyNolo Page 3 of 46

4 Version Information Version Description Date Author Initial version Sellanet Handling of TransactionResult attribute Sellanet Chapter 2, list corrected GestPay url modified Sellanet Document totally revised Sellanet Browser requirements updated Sellanet Server requirements updated Sellanet Custom field requirements updated Sellanet Error Codes updated Sellanet Language Codes updated Sellanet Custom code requirements and gestpay Sellanet parameters updated Currency codes updated Sellanet D Secure Sellanet Errata Corrige Easy Nolo S.p.A Specific domain for test codes Easy Nolo S.p.A. introduced New 3DLevel response parameter Easy Nolo S.p.A. introduced 2.1 Webservice Encryption Specifications EasyNolo S.p.a Payment page URL updated EasyNolo S.p.A. Page 4 of 46

5 1 Introduction The purpose of this document is to illustrate the architectural and functional aspects of the GestPay platform and to provide the necessary indications regarding the interface. The chapter System architecture describes the various components of the system and the modes of interaction between them and between the parties involved (merchant, buyer and GestPay). The chapter Description of process phases details all of the phases that make up the payment process, in particular the information that must be passed to GestPay and the information that will be returned. The chapter Authentication describes how GestPay authenticates the merchant server that makes calls to the system. The chapter Payment transaction data structure describes the information that identifies a payment transaction and the result that GestPay returns after processing the transaction. The chapter Merchant profile describes how to configure the merchant profile that allows GestPay to process transactions correctly. The chapter GestPayCrypt object description examines the use of the component that handles server-to-server communication during the phases in which this kind of communication is sent between the server that receives the virtual shop as guest and GestPay. The chapter WebService focuses on the use of the webservice responsible for handling the encryption and decryption services substituting the GestpayCrypt object described above between the server which hosts the virtual store and GestPay. The chapter Software requirements illustrates the minimum requirements for installation of the software required to interface with GestPay. The chapter Example transactions describes a number of typical transactions, highlighting the information exchanged and the modes of interaction between the various components. In addition, there are some tables that make it possible to code certain information sent by or received from GestPay. Page 5 of 46

6 2 System Architecture Within the system architecture, 3 components can be identified: Buyer client Merchant Server GestPay Server Communication between the various components takes place over the Internet using the http or https protocols (the GestPay server has a 128-bit Verisign digital certificate). The payment process is split into communication steps in which the components interact, exchanging the information needed to complete the transaction. Merchant 1 4 8b Customer 2 7a 9b 3 6 8a 10b PRE-payment POST-payment Request Responses GestPay Architecture scheme 1. The buyer selects the items to buy and decides to proceed with payment. 2. The merchant s server contacts GestPay server via the Internet to encrypt the payment transaction data. 3. GestPay performs the necessary controls to authenticate the merchant s server and validate the transaction data, returning, in the event of an affirmative response, an encrypted parameter string that represents the payment transaction to be processed. 4. The encrypted parameter string is communicated to the customer s browser. The customer is directed to the GestPay server to complete the payment process. 5. The merchant s browser calls back the payment page, passing the encrypted parameter string and the code assigned to the merchant (Shop Login). Data security checks are performed on the transaction: if the checks are passed, the payment page can be displayed and the the data needed to complete the transaction Page 6 of 46

7 can be entered. The following steps describe the process by which the transaction result is communicated both to the merchant and to the buyer. 6. GestPay communicates to the merchant s server an encrypted parameter string which returns the result of the transaction. 7a.The merchant s server contacts the GestPay server via Internet to decrypt the encrypted data string which returns the result of the transaction. 8a.GestPay decrypts the string and returns the parameters which return the result of the transaction in unencrypted form. 7b.GestPay communicates the encrypted parameter string which brings the transaction result to the browser of the customer, who is directed to the merchant s server. 8b.The buyer s browser calls back the response page created by the merchant, passing the encrypted parameter string. 9b.The merchant s server contacts the GestPay server via Internet to decrypt the encrypted data string that returns the transaction result. 10b. GestPay decrypts the string and returns, in unencrypted form, the parameters that return the transaction result, allowing the merchant to provide the buyer with the references required to complete the purchase process. The following scheme analyses the payment process, underlining the chronological order in which the communication steps take place. Notice that in some cases (steps 7 and 8) simultaneous communications are established between the components under consideration when they implement the procedures that must manage the information exchanged between the steps. Components GestPay Server Merchant Server Customer Client Step Page 7 of 46

8 3 Description of Process Phases A payment transaction is made up of 4 basic phases in which there are one or more communication steps. In each phase, the information necessary to process the transaction is exchanged between the various components. 3.1 Phase I: transaction data encryption The information required for the payment is previously communicated to GestPay to be encrypted. To guarantee an optimum security level, no sensitive information is communicated in unencrypted form to the buyer s server. In this phase, the merchant s server requests the encryption service from GestPay, obtaining the encrypted string that represents the transaction to process. The data that identify a transaction and their use will be described in chapter 4. Encryption can be handled in one of two ways: Use of the GestPayCrypt object Server-to-server communication is handled by the GestPayCrypt object released by EasyNolo, which must be previously installed on the merchant s server. The virtual shop pages concerned with handling information required for the payment call the object. Use of the WSCryptDecrypt WebService The use of the webservice does not require any installation on the server, but simply a call to the webservice using the https protocol. The response is in the XML format. If the merchant s authentication checks and validation of transaction data are passed, GestPay returns the encrypted data string to the merchant s server to be sent to the buyer s server to continue the payment process. Otherwise, a specific error code will be returned to allow the problem detected to be identified. 3.2 Phase II: payment page call After obtaining the encrypted data string (as described in the preceding section), the buyer s browser is directed to the payment page on the GestPay server at the following address: string> for test codes: string> The call to the page will be made passing two parameters: a The code identifying the merchant (Shop Login) b The encrypted data string identifying the transaction The payment page will acquire the parameters and verify the identity checks (parameter a must refer to a recognised merchant) and transaction data security (parameter b must Page 8 of 46

9 correspond to the encrypted data string communicated by the merchant during the previous phase). If the checks are passed, the payment page will be displayed to the buyer, who must enter the data required to complete the payment process. If the checks are not passed, the payment page is not displayed and the process passes to the following phase in order to communicate the negative transaction result. Page 9 of 46

10 3.3 Phase III: communication of transaction result GestPay communicates the transaction result both to the merchant and the buyer Response to merchant Notification is forwarded with a server-to-server call to the page specifically configured on the merchant s server (the notification page URL is one of the items of information that make up the merchant s profile, configurable through the GestPay Back Office environment). Call syntax is the following: server to server>?a=<shoplogin>&b=<encrypted string> The call to the page will be made passing two parameters: a the code which identifies merchant (Shop Login) b the encrypted data string which contains the result of the transaction The page residing on the merchant s server must have the html tags <HTML></HTML> in the source. If there are communication errors, GestPay will make several forwarding attempts for two days after the transaction. The merchant will also receive a transaction result notification at the address configured in his/her profile. In addition, the processed transaction can be viewed by accessing the GestPay Back Office environment in the Active Report section Response to Buyer GestPay immediately communicates the result of the transaction by displaying a virtual receipt showing essential transaction data. GestPay directs the buyer s browser to the merchant s server to conclude the purchasing process. The merchant must prepare two urls (and configure them in the merchant s profile) which will be called in the event of a negative or positive response and will allow the merchant to manage communication with the buyer while maintaining the editorial style that characterises the virtual shop. The call syntax is the following: merchant>?a=<shoplogin>&b=<encrypted string> If there is an anomaly in the server-to-server communication described above, GestPay displays a message to the buyer warning that there may be problems directing him/her to the merchant s server to conclude the purchasing process. In this situation, the buyer receives a notification from GestPay about the transaction result and is invited, if there are anomalies, to contact the merchant by other means (e.g. ) to conclude the purchasing process. The buyer will also receive a transaction result notification at the address provided on the payment page, if indicated. 3.4 Phase IV: decryption of transaction result GestPay communicates the transaction result through an encrypted string (parameter b of the call to the url preconfigured by the merchant). The string is initially forwarded to Page 10 of 46

11 the merchant during server-to-server communication and makes it possible once it has been decrypted to update the status of the transaction recorded in the merchant s information system. The same string is also sent from the buyer s browser to the merchant s server and makes it possible once it has been decrypted to complete the payment process. Web pages preconfigured by the merchant for receiving the transaction result (in the case of both server-to-server communication and through the buyer s browser) must call the GestPay server to request the decryption service and obtain the information that represents the result of the processed transaction in unencrypted form. The request to decrypt the string received can be made through: GestPayCrypt Object Server-to-server communication is handled by the GestPayCrypt object released by EasyNolo and which must be installed on the merchant s server in advance. WebService WSCryptDecrypt The use of the webservice does not require any installation on the server, but simply a call to the webservice using the https protocol. The response is in the XML format. Page 11 of 46

12 4 Authentication Server-to-server calls are managed by a component released by EasyNolo. Server authentication of the merchant requesting encryption or decryption services is made by verifying: Shop Login validity: ShopLogin parameter must correspond to a code recorded in GestPay customers details. IP address server: the calling server IP address must correspond to one of the IP addresses configured in the merchant s profile. Shop Login status: the merchant s status must be active (the merchant s status is managed by the GestPay administrator and not directly by the merchant) If the authentication checks are not passed, a specific error will be returned, making it possible to identify the anomaly found in the authentication process. Page 12 of 46

13 5 Structure of Transaction Data A transaction is characterised by a series of information that must be communicated to GestPay to complete the payment process and by information returned to the system as the transaction result. By suitably configuring his/her profile within the Back Office environment, the merchant can define what information to send to or receive from GestPay, and by what means. 5.1 Transaction Data to Send to GestPay Some of the information to communicate to GestPay is required in order to complete the payment Some information process, while that is other essential information to the payment can be process omitted is without configured compromising as compulsory the processing by GestPay. of This the attribute transaction.through cannot be modified. the GestPay Back Office environment, merchants The can define following what table information gives the is required information and what that must information be communicated is optional. to GestPay in order to make a transaction: Name Format Type R/O Description ShopLogin VarChar (30) P R ShopLogin Currency Num (3) P R Code identifying currency in which transaction amount is denominated (see Currency Codes table) Amount Num (9) P R Transaction amount. Do not insert thousands separator. Decimals (max. 2 numbers) are optional and separator is the point (see examples) ShopTransactionID VarChar (50) P R Identifier attributed to merchant s transaction CardNumber VarChar (20) I/P R Credit card number ExpMonth Char (2) I/P R Credit card expiry month (01, 02 12) ExpYear Char (2) I/P R Credit card expiry year (01, 02 99) BuyerName VarChar (50) I/P O Buyer s name and surname Buyer VarChar (50) I/P O Buyer s address Language Num (2) P O Code identifying language used in communication with buyer String containing specific CustomInfo (1) VarChar (1000) P O information as configured in the merchant s profile 1 Each field can be up to a maximum of 300 characters in length The Name column contains the attribute identifier with which a specific item of information is communicated to the GestPayCrypt object, which handles server-toserver communication for the encryption services. The Format column indicates whether the information value is numeric or alphanumeric. If it is alphanumeric, the maximum allowable number of characters is given in brackets. Page 13 of 46

14 The Type column specifies whether the information must be communicated to the component (passed as Parameter) or if it can be entered by the buyer (passed as Input) in the payment page. The R/O column specifies whether the information is Required (if omitted the transaction cannot be completed) or Optional. However, the minimum quantity of information configured, which allows phase I to be processed, is made up of: Currency Amount Shop TransactionID This information, in fact, is defined as required and must be communicated to GestPay using the GestPayCrypt component. During phase I, GestPay makes validation checks on the information that constitutes the payment transaction, verifying consistency with the merchant s profile setup. If anomalies are detected, the transaction is abandoned, returning a specific error. This approach makes it possible to identify possible anomalies connected with the transaction immediately, preventing the buyer from being directed to the payment page with an encrypted data string that corresponds to an invalid transaction. The CustomInfo attribute contains specific information that the merchant wishes to communicate to or receive from GestPay. What information is included in the CustomInfo attribute is defined in the Back Office environment in the Fields & Parameters section. The information included will follow this form: datum1=value1*p1*datum2=value2*p1* *P1*datumn=valuen The separator between logically different information is the reserved sequence of characters *P1*. Other characters that must not be used within the parameters encoded by GestPay and in customised information are: & (space) ( ) * < >, ; : *P1* / [ ]? = -- /* % // Page 14 of 46

15 Transaction data received by GestPay GestPay communicates the payment transaction result to the merchant through an encrypted data string that contains a series of information returned. Using the GestPayCrypt object, merchants will obtain the information reporting the transaction result in unencrypted form and will be able to update their own information system, allowing buyers to complete the purchasing process. The following table contains the information returned by GestPay as transaction result. Name Format Type R/O Description ShopLogin VarChar (30) P R ShopLogin Currency Num (3) P R Code identifying currency in which transaction amount is denominated (see Currency Codes table) Amount Num (9) P R Transaction amount. Do not insert thousands separator. Decimals (max. 2 numbers) are optional and separator is the point (see examples) ShopTransactionID VarChar (50) P R Identifier attributed to merchant s transaction BuyerName VarChar (50) I/P O Buyer s name and surname Buyer VarChar (50) I/P O Buyer s address TransactionResult Char (2) P R Transaction result AuthorizationCode VarChar (6) P R Transaction authorisation code BankTransactionID Num (9) P R Identifier attributed to the transaction by GestPay Nationality of institute issuing card Country VarChar (30) P O VbV VarChar (50) P O Flag for Verified by Visa transactions (see table of VbV Codes) ErrorCode Num (9) P R Error code ErrorDescription VarChar (255) P R Error description AlertCode Num (9) P O Alert code 3DLevel VarChar(255) P O Level of authentication for VBV Visa / Mastercard Securecode transactions. The string may have the value FULL or HALF AlertDescription VarChar (255) P O Alert description in chosen language CustomInfo (1) VarChar (1000) P O String that has the specific information as configured in the merchant s profile 1 Each field can be up to a maximum of 300 characters in length. The minimum information required to report the transaction result (defined as required) is made up of: Currency Amount ShopTransactionID TransactionResult AuthorizationCode ErrorCode Page 15 of 46

16 ErrorDescription BankTransactionID Other information is defined as optional and will be returned according to the merchant s profile settings made in the GestPay Back Office environment. A transaction result can be interpreted by verifying the TransactionResult field value. The possible values are: TransactionResult OK KO XX Description Positive transaction result Negative transaction result Suspended transaction result (only in the case of money transfers) Page 16 of 46

17 6 Merchant s Profile Each merchant can configure his/her profile by accessing the GestPay Back Office environment at: for test codes Some settings regard the procedure and the information that must be sent to or will be returned by GestPay. 6.1 Authentication configuration GestPay identifies the merchant requesting the encryption service through the GestPayCrypt component by comparing the calling server IP address to the IP addresses configured in the profile associated with the Shop Login used for the call. If the calling server is not recognised, the transaction process ends and a specific error is returned. In the Configuration IP Addresses section of the Back Office environment, the merchant can enter up to a maximum of 10 IP addresses (if calls to GestPay originate from a server farm). Configuration IP Addresses Page 17 of 46

18 6.2 Configuration of response url and GestPay communicates the transaction result with a server-to-server call to the page specifically prepared by the merchant and by directing the buyer s browser to the pages configured by the merchant (different pages for positive or negative results). In the Configuration Responses section in the Back Office environment, it is possible to specify the URLs used by the system to communicate the transaction result. In this section it is also possible to specify the addresses that will be used for notifications via . Configuration Responses Page 18 of 46

19 6.3 Configuration of Fields & Parameters Merchants can define the transaction structure (specifying what information beside the required information will have to be sent to GestPay) by configuring in the Back Office environment what information is to be sent in phase I and what information must be returned when the transaction result is communicated. This system allows the merchant to customise the transaction structure with proprietary information that will be stored in the GestPay archives and will allow each transaction to be identified using customised search keys. Moreover, customised information can be returned with the transaction result communication, thus allowing the merchant s information system to manage this information appropriately. Merchant s profile configuration - Fields & Parameters Page 19 of 46

20 7 Description of GestPayCrypt Object Server-to-server communication between GestPay and merchant is automatically handled by the GestPayCrypt component released by EasyNolo. This component is a Java library that will be called by the web pages preconfigured by the merchant to handle encryption of the transaction data and decryption of the result communicated by GestPay. The GestPayCrypt library is available as open source on the EasyNolo website. Table 1 contains the attributes and the methods made available by the Java library. In the virtual shop pages configured to handle payments the merchant implements a call to the GestPayCrypt component which handles requests to use the GestPay encryption service. Class attributes will be filled in with data that identify the transaction. To request the encryption service it is necessary to call the Encrypt method. If the encryption operation has concluded correctly (value of ErrorCode attribute = 0), the encrypted data string returned by GestPay will be available by reading the EncryptedString attribute value. Otherwise, the values of the ErrorCode and ErrorDescription attributes will allow the reasons that have prevented the encryption operation to be identified. To request the decryption service, it is necessary to call the Decrypt method, after filling in the Shop Login and EncryptedString attributes with values communicated by GestPay in Phase III. Information containing the result of the transaction will be available by reading the Java library attributes that correspond to the information regarding the transaction result. Page 20 of 46

21 The attributes and methods of the GestPayCrypt Java library are described below: Class: GestPayCrypt Attributes AlertCode AlertDescription Amount AuthorizationCode BankTransactionID Buyer BuyerName CardNumber Country Currency CustomInfo CVV EncryptedString Encryption ErrorCode ErrorDescription ExpMonth ExpYear Language MIN PasswordEncrypt ShopLogin ShopTransactionID TransactionResult VBV VBVrisp 3DLevel SET Methods SetAmount (val) SetBuyer (val) SetBuyerName (val) SetCardNumber (val) SetCurrency (val) SetCustomInfo (val) SetCVV SetExpMonth (val) SetExpYear (val) SetEncryptedString (val) SetEncryption SetLanguage (val) SetMIN SetPasswordEncrypt SetShopLogin (val) SetShopTransactionID (val) SetWithoutEncryption Alert code Alert description Transaction amount Transaction authorisation code Identifier assigned to transaction by GestPay Buyer s address Buyer s name and surname Credit card number Nationality of institute issuing card Code identifying currency in which transaction amount is denominated String containing specific merchant information String containing value of Cvv2 / Cvc2 / 4dbc code of credit card Encrypted string Flag to activate local encryption Error code Error description Credit card expiry month Credit card expiry year Language code for communication with buyer Not used Password for local encryption Shop login identifying merchant Identifier assigned to transaction by merchant Transaction result Flag for Verified by Visa transactions Not used Level of authentication for Visa VBV / Mastercard Securecode transactions Used to set Amount attribute Used to set Buyer attribute Used to set BuyerName attribute Used to set CardNumber attribute Used to set Currency attribute Used to set CustomInfo attribute Used to set CVV attribute Used to set ExpMonth attribute Used to set ExpYear attribute Used to set EncryptedString attribute Used to set Encryption attribute to TRUE Used to set Language attribute Not used Used to set PasswordEncrypt attribute Used to set ShopLogin attribute Used to set ShopTransactionID attribute Used to set Encryption attribute to FALSE Page 21 of 46

22 GET methods Decrypt Encrypt GetAlertCode GetAlertDescription GetAmount GetAuthorizationCode GetBankTransactionID GetBuyer GetBuyerName GetCountry GetCurrency GetCustomInfo GetEncryptedString GetErrorCode GetErrorDescription GetShopLogin GetShopTransactionID GetTransactionResult GetVBV GetVBVrisp Get3DLevel Used to request encryption service attribute Used to request decryption service attribute Used to read AlertCode attribute attribute Used to read AlertDescription attribute Used to read Amount attribute Used to read AuthorizationCode attribute Used to read BankTransactionID attribute Used to read Buyer attribute Used to read BuyerName attribute Not used Used to read Currency attribute Used to read CustomInfo attribute Used to read EncryptedString attribute Used to read ErrorCode attribute Used to read ErrorDescription attribute Used to read ShopLogin attribute Used to read ShopTransactionID attribute Used to read TransactionResult attribute Used to read VbV attribute Not used Used to read 3DLevel attribute Page 22 of 46

23 8 Webservice Instructions for the use of the encryption module with the WEBSERVICE interface This document contains the necessary instructions for using the WSCryptDecrypt webservice. This component is a library that must be called from the web pages configured by the merchant to handle transaction data encryption and decryption of the result communicated by GestPay. The WSCryptDecrypt web service is available on the production and test servers and does not require any installation on the merchant s server. The merchant must implement in the page(s) of the virtual store configured to handle payments a call to the webservice which handles requests to use the GestPay encryption service. To request the encryption service it is necessary to call the Encrypt method. An example of a positive XML response returned by the web service is given below: <?xml version="1.0" encoding="utf-8"?> <GestPayCryptDecrypt> <TransactionType>ENCRYPT</TransactionType> <TransactionResult>OK</TransactionResult> <CryptDecryptString>CF66F38B4EC881.</CryptDecryptstring> <ErrorCode>0</ErrorCode> <ErrorDescription /> </GestPayCryptDecrypt> If the encryption operation is concluded correctly (TransactionResult value = OK), the encrypted data string returned by GestPay will be available by reading the value of the CryptDecryptString attribute. If this is not the case, the values of the ErrorCode and ErrorDescription attributes will make it possible to identify the reasons that prevented the encryption operation. To request the decryption service it is necessary to call the Decrypt method, passing the Shoplogin and EncryptedString attributes with the values communicated by GestPay in Phase III. The information containing the transaction result will be available by reading the information in the XML response file corresponding to the result of the transaction. The webservice must be called from the application configured by the merchant to handle the sending of transaction data and reading the result communicated by GestPay in XML format. The address of the service is the following URL: for test codes Page 23 of 46

24 Generation of Proxy Class to use webservice functions from various languages The proxy class in the chosen language can be created automatically through the wsdl.exe program (in this case provided by Microsoft) simply by specifying the contract file relating to the webservice, in this case: The addresses of descriptions of the service are found at the following URLs: For production codes: For test codes: For example: wsdl /language:vb /out: wss2sproxyclass.vb The.vb file will be generated, with handling of the proxy class relating to the webservice which will simply be imported into the project and used. With visual Studio.net it is possible to add the webservice references in order to have the classes of the referenced webservice automatically available in the project (see Add Web Reference ). For other languages, verify normal operations for interfacing with webservices. Page 24 of 46

25 List of calls available with WSCryptDecrypt webservice. A complete list of methods for the WSCryptDecrypt object is provided below. WEBService methods Method name Encrypt Decrypt Description Encryption Decryption The various method calls are handled as function calls to the web service without passing an XML string. The values of the various calls must be passed as parameters. Input parameters, Encrypt method Method name Description ShopLogin Used to set value of ShopLogin attribute UICCode Assigns currency code Amount Assigns transaction amount ShopTransactionID (val) Assigns code attributed by merchant to transaction CardNumber (val) Assigns card number ExpMonth (val) Assigns card expiry month ExpYear (val) Assigns card expiry year BuyerName (val) Assigns buyer s name Buyer Assigns buyer s Language (val) Assigns language for s to buyer CVV (val) Assigns security code printed on card CustomInfo (val) Assigns string containing any customised parameters Input parameters, Decrypt method Method name ShopLogin CryptedString Description Used to set value of ShopLogin attribute String to decrypt received from GestPay Page 25 of 46

26 Il file XML e descritto e può essere validato tramite il relativo file GestPayCryptDecrypt.xsd che qui andiamo a descrivere nel dettaglio XML values returned Method name TransactionType TransactionResult (E,D) CryptDecryptString (E) ShopTransactionID (D) BankTransactionID (D) AuthorizationCode (D) Currency (D) Amount (D) Country (D) CustomInfo (D) BuyerType (D) ErrorCode (E,D) ErrorDescription (E,D) AlertCode (D) AlertDescription (D) Description The type of request executed can have the following values: ENCRYPT (E) DECRYPT (D) Returns result of transaction with values OK and KO Returns encrypted string Returns code attributed by merchant to transaction Returns code attributed by bank to transaction Returns authorisation code Returns currency code Returns transactio amount Returns nationality of institute issuing card Returns any aditional parameters Returns buyer s name and address, separated as follows: Buyer Returns buyer s address BuyerName Returns buyer s name Returns a code referring to result of transaction Returns description associated with value of ErrorCode Returns code for violation of risk management criteria Returns description associated with value of AlertCode Page 26 of 46

27 Doc: GestPay - Security with Encryption Technical Specications 9 Software Requirements GestPay software requirements concern the buyer s browser and the server hosting the virtual store. 9.1 Buyer browser requirements The domain is associated with a 128-bit Verisign The digital buyer s certificate. browser Browsers must be must configured be compatible to accept cookies with this and level Javascript. of encryption. The minimum recommended required versions are Internet Explorer 4.0 and Netscape Merchant server requirements Check with the server administrator that the computer can reach the following addresses: If http (port 80) communication is used: For test codes: If https (port 443) communication is used: For test codes: Installation of GestPayCrypt.class (Java) The GestPayCrypt Java library (GestPayCrypt. class) must be copied into the web server directory containing the Java libraries. For example, in a system with architecture based on Windows NT and Internet Information Server it must be installed in the following directory:...\java\trustlib On the web server that hosts web pages that call the GestPayCrypt library, Java Virtual Machine (from version on) must be installed. Page 27 of 46

28 Doc: GestPay - Security with Encryption Technical Specications Installation of GestPayCrypt.dll (COM) The COM object can be installed only in Windows environments (NT 4.0 or above; MTS; IE 4.x or above installed with Microsoft VM Java), saved at any location on the disk and subsequently registered using one of the following operations: Windows NT from the command prompt using the command: REGSVR32 path (e.g. c:\winnt\system32\gestpaycrypt.dll) Note. For Windows Server 2003 and Windows Xp versions this registration method is not recommended. Through Com+ (for Windows 2000 or above) or MTS (for NT 4.0) Path: Left panel consoleroot /Microsoft transaction server/computer/mycomputer (or other computer name)/packages Installed Right-click > Create new package (taking care not to use Interactive User, but assign an account with sistem administrator privileges for the package) Open the package /Components Right-click > New Component > Install new component >Add Select the Dll OK Note. For more information consult the Microsoft website at the following address: Page 28 of 46

29 Doc: GestPay - Security with Encryption Technical Specications Windows 2003 Follow the manual available at the following address: Page 29 of 46

30 Doc: GestPay - Security with Encryption Technical Specications 10 Example Transactions This chapter describes a number of significant examples of interfacing with Gestpay. The ShopLogin used in the examples is The merchant s profile is the following: Merchant s Profile IP Address Server-to-server Communication Url Url for positive responses Url for negative responses for sending OK result result_ok@myshop.com for sending KO result result_ko@myshop.com for sending information info@myshop.com 9.1 Transaction # 1 The merchant decides to communicate to GestPay only the essential information to allow the buyer to make the payment. The payment page must be displayed to the buyer who enters the sensitive data requie to complete the payment in protected (SSL 128-bit) mode. The transaction to process has the following characteristics: Merchant s Transaction Shop Transaction ID 34az85ord19 Transaction Amount Currency Transaction euro Let us suppose that the transaction is concluded positively (payment will be made), returning the following result: Result Authorisation code 54e813 Bank transaction ID 216 In the following pages, each individual phase that makes up the payment process will be described, highlighting the information exchanged between GestPay and the merchant s server. Page 30 of 46

31 Phase I The merchant s server communicates the information that characterises the transaction to GestPay, setting the value of the GestPayCrypt attributes: GestPayCrypt ShopLogin Currency 242 Amount ShopTransactionID 34az85ord19 Language 2 GestPay authenticates the calling server and validates the information characterising the transaction. If the checks are passed, it returns an encrypted string to GestPay: Encrypted Data String ShopLogin EncryptString 2C53F1B5... Phase II The buyer s server is directed to the GestPay server to complete the payment process. The call to the payment page is made passing two parameters that correspond to the shop login and to the encrypted data string received in the previous phase by GestPay: Payment page Url GestPay authenticates the Shop login (parameter a) and performs security checks on the encrypted data string (parameter b). If the checks are passed, the payment page is displayed to the buyer, who can enter the data necessary to complete the payment. Otherwise, an error will be communicated. Phase III After processing the transaction, GestPay communicates the transaction result (encrypted data string) to the merchant. Server-to-server communication After server-to-server communication has concluded positively, GestPay directs the buyer s browser to the merchant s server (in this case to the Url for positive responses). If this is not the case, the buyer is informed that it is not possible to direct him/her to the merchant s server to conclude the purchasing process. Page 31 of 46

32 Redirection of buyer s client The transaction result is also communicated to the merchant via . Send Result_OK@myshop.com Phase IV GestPay communicates the transaction result to the merchant, sending an encrypted data string. Using the GestPayCrypt object, the merchant must request the string decryption service to interpret the transaction result correctly and update the information in his/her own information system, thus allowing the buyer to complete the purchasing process. The merchant s server communicates the encrypted data string containing the transaction result to GestPay, through GestPayCrypt. Encrypted Data String ShopLogin EncryptedString 4D341A8B... GestPay authenticates the calling server and the integrity of the encrypted data string. If the controls are passed, it returns the unencrypted information to GestPayCrypt allowing the merchant to interpret the transaction result correctly: GestPay Result ShopLogin Currency 242 Amount ShopTransactionID 34az85ord19 TransactionResult OK AuthorizationCode 54e813 BankTransactionID 216 ErrorCode 0 ErrorDescription Transaction Executed Page 32 of 46

33 10.2 Transaction #2 The merchant decides to communicate to GestPay not only the information that is indispensable to allow the buyer to make the payment, but also the buyer s name, surname and address (this information is suggested by default on the payment page so that the buyer does not need to enter it a second time). Other customised information is sent by the merchant (the client code attributed to the buyer and technical information). The payment page must be displayed to the buyer who enters any sensitive data necessary to complete the payment in protected mode (128 bit SSL). In addition, one of the customised items of information (client code) must be displayed on the payment page. The transaction to process has the following characteristics: Transaction Shop Transaction ID 34az85ord19 Transaction Amount Currency Transaction Euro Language Spanish Buyer s Name and Surname Mario Bianchi Buyer s Address mario.bianchi@isp.it Customised info 1 BV_CODCLIENTE=12 Customised info 2 BV_SESSIONID=398 We shall assume that the transaction is concluded positively (payment is made), reporting the following result: Result Authorisation code 9823y5 Bank transaction ID 860 The following pages describe each individual phase that makes up the payment process, highlighting the information exchanged between GestPay and the merchant s server. Phase I The merchant s server communicates the information that characterises the transaction to GestPay, setting the value of the GestPayCrypt attributes: GestPayCrypt ShopLogin Currency 242 Amount 15.6 ShopTransactionID 34az85ord19 Language 3 BuyerName Mario Bianchi Buyer mario.bianchi@isp.it CustomInfo BV_CODCLIENTE=12*P1*SESSIONID=398 Page 33 of 46

34 GestPay authenticates the calling server and validates the information that characterises the transaction. If the controls are passed, it returns an encrypted string to GestPay: Encrypted Data String ShopLogin EncryptString 30715CA8.. Phase II The buyer s server is directed to the GestPay server to complete the payment process. The call to the payment page is made passing two parameters that correspond to Shop login and to the encrypted data string received in the previous phase by GestPay: Payment page Url GestPay verifies the Shop login (parameter a) and performs security checks on the encrypted data string (parameter b). If the checks are passed, the buyer, who can now enter the data necessary to complete the payment, views the payment page. If the checks are not passed, an error will be communicated. Phase III After processing the transaction, GestPay communicates the transaction result (encrypted data string) to the merchant. Server-to-server communication After server-to-server communication has concluded positively, GestPay directs the buyer s browser to the merchant s server (in this case to the Url for positive responses). If this is not the case, the buyer is informed that it is not possible to direct him/her to the merchant s server to complete the purchasing process. Redirection of Buyer s Client F45E129A... The transaction result is also communicated to the merchant and the buyer via . Send result_ok@myshop.com mario.bianchi@isp.it Page 34 of 46

35 Phase IV GestPay communicates the transaction result to the merchant, sending an encrypted data string. Using the GestPayCrypt object, the merchant must request string encryption to interpret the transaction result correctly and update the information in his/her own system, thus allowing the buyer to complete the purchasing process. The merchant s server communicates the encrypted data string containing the transaction result to GestPay, through GestPayCrypt. Encrypted Data String ShopLogin EncryptedString 6C12459A... GestPay authenticates the calling server and checks the encrypted data string. If the checks are passed, it returns an unencrypted data string containing the transaction result: GestPay Result ShopLogin Currency 242 Amount 15.6 ShopTransactionID 34az85ord19 TransactionResult OK AuthorisationCode 9823y5 BankTransactionID 860 CustomInfo BV_CODCLIENTE=12*P1*SESSIONID=398 ErrorCode 0 ErrorDescription Transaction Executed Page 35 of 46

36 11 Examples of Implementation This chapter describes an example of interfacing with GestPay created using the ASP language. Working scripts created using some of the most widely distributed development languages (ASP,JSO,PHP ) can be downloaded from ASP Example PAGE FOR CONNECTING TO PAYMENT PAGE (PAYMENT REQUEST) <% START OF ENCRYPTION SCRIPT DO NOT MODIFY THIS PART Set objcrypt = GetObject("java:GestPayCrypt") if Err.number <> 0 then Response.Write Err.number & Err.description end if MODIFY THIS PART (SETTING VALUES OF TRANSACTION ATTRIBUTES) Replace text contained between square brackets [] with data required to carry out transaction. The lines containing data marked as NOT REQUIRED must be deleted if not used REQUIRED FIELDS myshoplogin= [SHOP LOGIN] e.g mycurrency=[currency CODE] e.g. 242 for euro or 18 for lira myamount=[amount WITHOUT THOUSANDS SEPARATOR WITH POINT AS DECIMAL SEPARATOR] e.g myshoptransactionid= [TRANSACTION IDENTIFIER] e.g. 34az85ord19 FIELDS NOT REQUIRED (DELETE ANY LINES WHICH ARE NOT RELEVANT) mybuyername= [BUYER S NAME AND SURNAME] e.g. Mario Bianchi mybuyer = [BUYER S ] e.g. Mario.bianchi@isp.it mylanguage=[code FOR LANGUAGE TO USE IN COMMUNICATION] e.g. 3 for Spanish mycustominfo= [CUSTOMISED PARAMETERS] e.g. BV_CODCLIENTE=12*P1*BV_SESSIONID=398 Page 36 of 46

37 DO NOT MODIFY THIS PART objcrypt.setshoplogin(myshoplogin) objcrypt.setcurrency(mycurrency) objcrypt.setamount(myamount) objcrypt.setshoptransactionid(myshoptransactionid) objcrypt.setbuyername(mybuyername) objcrypt.setbuyer (mybuyer ) objcrypt.setlanguage(mylanguage) objcrypt.setcustominfo(mycustominfo) call objcrypt.encrypt if objcrypt.geterrorcode = 0 then b = objcrypt.getencryptedstring a = objcrypt.getshoplogin end if END OF ENCRYPTION SCRIPT. IF ALL OK 2 VARIABLES, A AND B, ARE OBTAINED, TO BE USED TO PASS PARAMETERS TO BANCA SELLA EXAMPLE WITH HTML FORM %> <form action= > <input name= a type= hidden value= <%=a%> > <input name= b type= hidden value= <%=b%> > <input type= submit value= OK > </form> Page 37 of 46

38 PAGE FOR HANDLING PAYMENT RESPONSE <% START OF DECRYPTION SCRIPT DO NOT MODIFY INPUT PARAMTERS ARE READ AND PARAMETER B IS DECRYPTED parameter_a = trim(request( a )) parameter_b = trim(request( b )) Set objdecrypt = GetObject("java:GestPayCrypt") if Err.number <> 0 then Response.Write Err.number & Err.description end if objdecrypt.setshoplogin(parameter_a) objdecrypt.setencryptedstring(parameter_b) call objdecrypt.decrypt THERE FOLLOWS A SERIES OF VARIABLES WHOSE VALUE IS SET TO THE DATA RECEIVED BY GESTPAY TO BE USED TO INTEGRATE WITH MERCHANT S OWN SYSTEM myshoplogin=trim(objdecrypt.getshoplogin) mycurrency=objdecrypt.getcurrency myamount=objdecrypt.getamount myshoptransactionid=trim(objdecrypt.getshoptransactionid) mybuyername=trim(objdecrypt.getbuyername) mybuyer =trim(objdecrypt.getbuyer ) mytransactionresult=trim(objdecrypt.gettransactionresult) myauthorizationcode=trim(objdecrypt.getauthorizationcode) myerrorcode=trim(objdecrypt.geterrorcode) myerrordescription=trim(objdecrypt.geterrordescription) myerrorbanktransactionid=trim(objdecrypt.getbanktransacti onid) myalertcode=trim(objdecrypt.getalertcode) myalertdescription=trim(objdecrypt.getalertdescription) mycustominfo=trim(objdecrypt.getcustominfo) END OF DECRYPTION SCRIPT %> Page 38 of 46

39 12 Table of Errors Code Description 0 Transaction correctly processed 57 Credit card frozen 58 Confirmed amount exceeds authorised amount 63 Demand for settlement of a non-existent transaction 64 Pre-authorisation expired 65 Incorrect currency 66 Pre-authorisation already notified 74 Authorisation denied 97 Authorisation denied 100 Transaction interrupted by bank authorisation system 150 Incorrect merchant configuration in bank authorisation system 208 Incorrect expiry date 212 Bank authorisation system unavailable 251 Insufficient credit 810 Bank authorisation system not available 811 Incorrect merchant configuration in bank authorisation system 901 Authorisation denied 902 Authorisation denied 903 Authorisation denied 904 Authorisation denied 905 Authorisation denied 906 Authorisation denied 907 Authorisation denied 908 Authorisation denied 910 Authorisation denied 911 Authorisation denied 913 Authorisation denied 914 Authorisation denied 915 Authorisation denied 916 Authorisation denied 917 Authorisation denied 918 Authorisation denied 919 Authorisation denied 920 Authorisation denied 950 Credit card not authorised 951 Incorrect merchant configuration in bank authorisation system 998 Incorrect credit card check-digit 999 Operation not performed 1100 Empty parameter string 1101 Invalid format of parameter string 1102 No parameter name precedes = symbol 1103 Parameter string ending with a separator 1104 Invalid parameter name Doc: GestPay - Security with Encryption Technical Specifications Page 39 of 46