GestPay Technical Specifications iframe Payment Page

Transcription

1 GestPay Technical Specifications iframe Payment Page

2 Summary About this Document...4 About this version Introduction System Architecture Architecture scheme Process phases description Transaction data encryption GestPay iframe inclusion on the merchant checkout page Hidden payment page call Send the credit card data Transaction results D transactions (Verified by Visa, Mastercard SecurCode) Cardholder authentication Transaction end Javascript js_gestpay.js GestPay.CreatePaymentPage...15 Arguments Syntax:...15 Example: Function: GestPay.SendPayment...16 Credit card authorization Arguments Syntax:...16 Example: nd call after 3D authentication...16 Arguments Syntax:...16 Example: Object: Result Properties: Examples: Error Codes Response to merchant Default payment page call Communication of transaction result Response to merchant Response to Buyer Transaction result decryption Server to Server Authentication Transaction Data structure Transaction Data to Send to GestPay Transaction data received by GestPay Merchant s Profile Authentication configuration Configuration of response url and Configuration of Fields & Parameters Webservice Instructions for the use of the encryption module with the WEBSERVICE interface Generation of Proxy Class to use webservice functions from various languages List of calls available with WSCryptDecrypt webservice Software Requirements Buyer browser requirements Merchant server requirements Transaction Examples Transaction # Phase I Phase II... 36

3 Phase III Phase IV Transaction # Phase I Phase II Phase III Phase IV Implementations Examples Net C# PHP Errors Table Table of currency codes Table of Language Codes Table of Verified by Visa Codes Payment Orders in Test Environment Links... 53

4 About this Document Project name Document Title Creation Date Language Company GestPay iframe Payment page GestPay Technical Specifications iframe Payment page 02.APR.2012 English Easy Nolo S.p.A.

5 About this version Version Description Date Author Initial Version 02.APR.2012 EasyNolo 5

6 1. Introduction This document contains the instructions for GestPay iframe payment page, which allows merchants to process online credit card transactions with an hidden payment page within an iframe in the shop checkout page. A GestPay Partecipating Merchant is recognisable by an identification code called "Shop_Login" and is entitled to use the Back Office environment through one or more operators registered on the Sella.it website (at least one operator, with Administrator status is a requirement for activation of the service). The adoption of the GestPay iframe payment page will leave to the merchant the full control of the form design, the credit card data will be sent by the merchant checkout form to a hidden payment page (which will be on the GestPay servers) via javascript. This solution will free the merchant by the need to comply with PCI Security Standards ( 6

7 2. System Architecture Within the system architecture, 3 components can be identified: Customer's client Merchant server GestPay server Communication between the various components use the http or https (1024-bit) protocols. The payment process is split into communication steps in which the components interact, exchanging the information needed to complete the transaction. 2.1 Architecture scheme 1. The customer 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 shop checkout will create the iframe and load the hidden 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 loaded. 5. The customer's browser send to the hidden payment page within the iframe the credit card data and the transaction is processed. 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. 7

8 7b. GestPay communicates the encrypted parameter string to the buyer s browser within a javascript object. 8b. The shop checkout page read the encrypted parameter string in javascript result object. 9. The merchant s server contacts the GestPay server via Internet to decrypt the encrypted data string that returns the transaction result. 10. 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. 8

9 3. Process phases description 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 Transaction data encryption The information required for the payment is previously communicated to GestPay to be encrypted. In this phase, the merchant s server requests the encryption service from GestPay, obtaining the encrypted string that represents the transaction to process. Encryption can be handled thought the use of the webservice. It 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 authentication checks and transaction data validation are passed, GestPay returns the encrypted data string. Otherwise, a specific error code will be returned. The encrypted string will be use as a token to authenticate the customer in the hidden iframe page loaded from GestPay servers. 9

10 3.2 GestPay iframe inclusion on the merchant checkout page After obtaining the encrypted data string (as described in the preceding section), the buyer s browser will be redirected to the merchant checkout page which will include a remote javascript file from the GestPay's servers <script src=" type="text/javascript"></script> The script will automatically perform a browser compatibility check to ensure that the HTML 5 postmessage function, which will be used to exchange data, is supported. The result of the check will be the boolean value of the variable BrowserEnabled. If (BrowserEnabled){ //The Browser is supported! //Proceed to create the Payment page }else{ //The browser is not supported //Place here error handle code } To load the hidden iframe page the checkout page must call the Javascript function GestPay.CreatePaymentPage passing the Merchant code, the Encrypted string and a callback object needed to read the security checks results. <script> GestPay.CreatePaymentPage(MerchantCode,EncryptedString,LocalObj.PaymentPageLoad); </script> The function will create an hidden iframe into the body element and will load the payment page passing the merchant code and the generated encrypted string from the previous phase. <iframe src=" a=merchantcode&b=encryptedstring" heigth="0" width="0" style="position:absolute;top:0;left:0;width:0;height:0;visibility:hidden" ></iframe> When the payment page is called, it will perform the security checks needed and will fire the result in the Result object. <script> LocalObj. PaymentPageLoad = function(result){ if(result.errorcode!= 10){ //An Error has occurred //Result.ErrorCode will return the Error occurred //Result.ErrorDescription will return the Error Description //... place here error handle code... }else{ //the iframe is correctly created and the payment page is loaded the user can //proceed to insert the credi card data } } </script> 10

11 If the browser compatibility check fails the iframe will not be created and the payment page will not be loaded! Note. The HTML 5 cross-document messaging is supported by: Firefox 3+, Safari 4+, Chrome 8+, IE 8+, Opera

12 3.3 Hidden payment page call Send the credit card data. To send the credit card data to the hidden iframe the checkout page will assign a function to the OnSubimt event of the credit card form, this function will retrieve the credit card data and will call the GestPay.SendPayment method providing an array with the credit card number (CC), the expiration month (EXPMM) and the expiration year (EXPYY), the CVV (CVV2) if enabled, and a CallBack object (see chapter Javascript Result object). The credit card field must contain values between 13 and 19 digits. The expiry month value and the expiry year value must contain 2 digits. The Cvv2 field must contain values between 3 and 4 digits. e.g. <form name="myccform" action="" method="post" OnSubmit="return CheckCC();"> <fieldset> <legend>insert Credit Card Data</legend> <label for "CC">Credit Card Number</label> <input type="text" name="cc" value="" autocomplete="off" id="cc" /> <label for "ExpMM">Expiry Month</label> <input type="text" name="expmm" id="expmm" value=""/> <label for "ExpYY">Expiry Year</label> <input type="text" name="expyy" id="expyy" value=""/> <label for "CVV2">CVV2 / 4DBC</label> <input type="text" name="cvv2" id="cvv2" value=""/> </fieldset> <fieldset> <input type="submit" name="submit" value="send Payment" id="submit" /> </form> </fieldset> <script> function CheckCC(){ document.getelementbyid('submit').disabled=true; GestPay.SendPayment ({ CC : document.getelementbyid('cc').value, EXPMM : document.getelementbyid('expmm').value, EXPYY : document.getelementbyid('expyy').value, CVV2 : document.getelementbyid('cvv2').value },LocalObj.CallBack); return false; } </script> To free the Shop from the need to comply with PCI Security standard the OnSubmit event of the Credit card form must avoid to postback the Credit Card data to the checkout page! 12

13 3.3.2 Transaction results Gestpay will send the transaction result as javascript object and as notification which will be forwarded with a server- to- server call to the page properly set on merchant s server (the notification page can be set in the [URL Server to Server] Response feature of the Configuration > Environment section of the Merchant Back Office environment) D transactions (Verified by Visa, Mastercard SecurCode) Transactions made by 3D credit cards require the cardholder authentication. The buyer will be redirected to the card issuer web site and will have to fill a password which was released to him by the issuer itself. In case the authentication process ends up positively the transaction may end-up and generate a positive or negative result according to the reply from the credit card companies. If the card is recognized as 3D the outcome of the request is a specific error code (8006) which is readable by means of the ErrorCode property of the Result object. The error description (Verified By Visa) will be readable by means of the ErrorDescription property of the Result object. In this phase additional info are showed, that are necessary during the payment process and are specific to 3D transactions. In particular it is necessary to acquire the transaction id readable by means of the TransKey property of the Result object and a ciphered string to be used during the subsequent phase readable by means of the VbVRisp property of the Result object. e.g. <script> LocalObj.CallBack = function(result){ if (Result.ErrorCode!= 0){ if (Result.ErrorCode == 8006){ //3D Transaction - Card holder authorization required //Get the TransKey //NOTE you have to store this value in your server for further use var TransKey = Result.TransKey; //Get the VBVRisp var VBVRisp = Result.VBVRisp; //place here the code to redirect the card holder to the authentication website }else{ //Call failed an error has occurred //... place here error handle code... } }else{ //Call went good proceed to decrypt the Result.EncryptedResponse property } </script> } 13

14 Cardholder authentication If the credit card given result enrolled it is a prerequisite to allow the buyer authenticating himself in front of his credit card Issuer. The buyer s browser has to be redirected to a dedicated GestPay's page which will act as an interface for the authentication and will address the buyer to the Issuer s site giving him all necessary info for the authentication. The page to recall has the following URL: for test codes The page is to be called through the following 3 parameters: a shop_login b a ciphered string acquired in the previous phase through the Result.VbVRisp property of the Result object c URL on the merchant web site to which the buyer must be redirected after the authentication procedure At the end of the authentication process the buyer will be redirected on the merchant site to the URL specified as redirection parameter c. The merchant page for the buyer s welcome back after authentication will be recalled by means of a PARES parameter (a ciphered string containing the authentication result) which must be acquired by the merchant and forwarded to GestPay during the following phase Transaction end Once the card holder land to the merchant website after the authentication we have all necessary info to end the transaction. A new authorization request must occur using the GestPay.SendPayment method. Before using such method, however it is necessary to include the GestPay given javascript and call the Javascript function GestPay.CreatePaymentPage passing the Merchant code and the Encrypted string created before the first authorization request. Once the hidden iframe is created the page can proceed to send the new authorization request through the GestPay.SendPayment method, passing an array containing the TransKey value(transkey), the Pares value (PARes) and the CallBack object to handle the asynchronous response and retrieve the encrypted string with the transaction results. e.g. <script> GestPay.SendPayment({'TransKey':'//PLACE HERE THE TRANSKEY VALUE','PARes':'//PLACE HERE THE PARES VALUE'},LocalObj.CallBack); LocalObj.CallBack = function(result){ if (Result.ErrorCode!= 0){ //Call failed an error has occurred //... place here error handle code... }else{ //Call went good //place here the code to retreive the encrypted string var responsestring = Result.EncryptedResponse; } } </script> 14

15 3.3.3 Javascript js_gestpay.js GestPay.CreatePaymentPage Arguments 1. Merchant code (string) 2. EncryptedString (string) 3. CallBackObject (object) Syntax: GestPay.CreatePaymentPage (MerchantCode,EncryptedString,CallBackObj); Example: GestPay.SendPayment (' ', 'DcffrrnDNdjfnemfnermgnermNfdm,gnem/*ng', function(result){ if(result.errocode == 10){ //iframe created and payment page correctly loaded }else{ //An error has occurred, check ErrorCode and ErrorDescription //properties of the Result object }); } 15

16 Function: GestPay.SendPayment Credit card authorization Arguments 4. CCData (Array) 1. CC Credit card number (number) length: min(13) - max(19) 2. EXPMM Expiration Month (number) length: 2 3. EXPYY Expiration Year (number) length: 2 4. CVV2 Cvv / 4DBC (number) [optional] length: min(3) - max(4) 5. CallBackObj (object) Syntax: GestPay.SendPayment ({ CC : '', EXPMM :'', EXPYY :''[,CVV2:'']},CallBackObj); Example: GestPay.SendPayment ({ CC : ' ', EXPMM : '11', EXPYY : '14' },function(result){ if(result.errocode == 0){ //Transaction correctly processed //Decrypt the Result.EncryptedString property to read the //transaction result }else{ //An error has occurred, check ErrorCode and ErrorDescription //properties of the Result object }); } 2 nd call after 3D authentication Arguments 6. CCData (Array) 1. PARes (string) 2. TransKey (string) 7. CallBackObj (object) Syntax: GestPay.SendPayment ({ PARes: '', TransKey :''},CallBackObj); 16

17 Example: GestPay.SendPayment ({ PARes : 'xmnjdsre23214hjksbbdsjkrhewgsd/*dwhjdkhawndahdguy', TransKey : 'eftstsstefgd23432' },function(result){ if(result.errocode == 0){ //Transaction correctly processed //Decrypt the Result.EncryptedString property to read the //transaction result }else{ //An error has occurred, check ErrorCode and ErrorDescription //properties of the Result object }); } 17

18 Object: Result Properties: Result.ErrorCode Result.ErrorDescription Result.EncryptedResponse Result.TransKey Result.VBVRisp return the error code return the error description return the encrypted response string return the TransKey in case of 3D enrolled credit card return the ciphered string needed to the cardholder authentication in case of 3D enrolled credit card The GestPay.SendPayment() function will send an asynchronous call to the hidden iframe windows, the CallBack object will retrieve the Result object once the transaction result is thrown from the hidden payment page. Examples: e.g. Merchant not 3D enabled or not enrolled credit card <script> LocalObj.CallBack = function(result){ if (Result.ErrorCode!= 0){ //Call failed an error has occurred //... place here error handle code... }else{ //Transaction correctly processed proceed to decrypt the //Result.EncryptedResponse property } </script> } e.g. Merchant 3D enabled and 3D enrolled credit card <script> LocalObj.CallBack = function(result){ if (Result.ErrorCode!= 0){ if (Result.ErrorCode == 8006){ //3D Transaction - Card holder authorization required //Get the TransKey //NOTE you have to store this value in your server for //further use var TransKey = Result.TransKey; //Get the VBVRisp var VBVRisp = Result.VBVRisp; //place here the code to redirect the card holder to the //authentication website }else{ }else{ } //Call failed an error has occurred //... place here error handle code... //Transaction correctly processed proceed to decrypt the //Result.EncryptedResponse property } </script> } 18

19 Error Codes ErrorCode ErrorDescription Description 0 Transaction correctly processed The transaction is correctly processed, an encrypted string with the transaction result is provided either in the Result.EncryptedString property and in URL server-to-server in any was provided. 10 Payment page correctly loaded 1119 Credit card number with wrong length 1120 Credit card with wrong check-digit 1124 Invalid expiry month 1125 Invalid expiry year 1126 Expired expiry date 1130 Call rejected: missing parameter A Shop login missing 1131 Call rejected: Shop not recognised 1132 Call rejected: shop without active status 1134 Call rejected: empty parameter B Empty Encrypted String 1149 Missing or wrong CVV TransKey missing 8006 Verified by Visa The credit card provided is 3D enrolled (Verified by Visa / Mastercard Securecode).The cardholder must authenticate to proceed the transaction process Feature disabled iframe feature is not active 9991 Browser not supported 9992 Error creating iframe 9999 System Error Technical error during the transaction process To end-up the transaction when error 8006 occur the card holder must be authenticated by the credit card issuer. See section D transactions (Verified by Visa, Mastercard SecurCode) 19

20 3.3.4 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. 20

21 3.4 Default payment page call GestPay will let the shop to redirect the card holder to the default payment page as alternative to the iframe solution in case the browser did not support the iframe solution. The page will resides on the GestPay servers and let the card holder to insert the credit card data without the merchant can see or store them. After obtaining the encrypted data string (as described in 3.2 paragraph), 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 recognized merchant) and transaction data security (parameter b must 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 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. 21

22 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.5 Transaction result decryption GestPay notifies transaction result through an encrypted string (parameter b of the call to the url preset by merchant or EncryptedResponse property of the javascript object Result). The string allows, once it s decoded, updating the state of the transaction registered in the merchant s informative system. Web pages preset by the merchant for receiving the transaction result (in the case of both server-to-server communication and through the Result Javascript Object) must call the GestPay server to request the decryption service and obtain the result of the processed transaction in unencrypted form. The request to decrypt the string received can be made through the use of the webservice. It 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. 22

23 4. Server to Server Authentication 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. 23

24 5. Transaction Data structure A transaction is characterized 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 its 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 process, while other information can be omitted without compromising the processing of the transaction.through the GestPay Back Office environment, merchants can define what information is required and what information is optional. Some information that is essential to the payment process is configured as compulsory by GestPay. This attribute cannot be modified. The following table gives the information that must be communicated 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 CustomInfo (1) VarChar (1000) P O String containing specific 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 WSCryptDecrypt webservice, which handles server-to-server 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. 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 24

25 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 WSCryptDecrypt webservice. 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 possible to identify possible anomalies connected with the transaction immediately, preventing the shop checkout page to load the hidden 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 customized information are: & (space) ( ) * < >, ; : *P1* / [ ]? = -- /* % // 25

26 5.2 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 WSCryptDecrypt webservice, 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 Country VarChar (30) P O by GestPay Nationality of institute issuing card Flag for Verified by Visa transactions VbV VarChar (50) P O (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 Level of authentication for VBV Visa / Mastercard Securecode transactions. VarChar(255) P O 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. 26

27 The minimum information required to report the transaction result (defined as required) is made up of: Currency Amount ShopTransactionID TransactionResult AuthorizationCode ErrorCode 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 Description Positive transaction result Negative transaction result 27

28 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 WSCryptDecrypt webservice 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 recognized, 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 28

29 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 Note. URL for positive response and URL for negative response will not be called using the iframe payment page. 29

30 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 customize the transaction structure with proprietary information that will be stored in the GestPay archives and will allow each transaction to be identified using customized search keys. Moreover, customized 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 30

31 7. Webservice 7.1 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 31

32 7.2 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. 32

33 7.3 List of calls available with WSCryptDecrypt webservice. A complete list of methods for the WSCryptDecrypt object is provided below. WEBService methods Method name Description Encrypt Encryption Decrypt 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 The XML file is described and can be valuated through the relevant GestPayCryptDecrypt.xsd file which is now described in detail 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 33

34 8. Software Requirements GestPay software requirements concern the buyer s browser and the server hosting the virtual store. 8.1 Buyer browser requirements The domain is associated with a 1024-bit Verisign digital certificate. Browsers must be compatible with this level of encryption. The iframe page exchange data with the merchant checkout page using the HTML 5 javascript cross-document messaging. Cross-document messaging is supported by: FF3+, IE8+, Chrome, Safari4+, Opera Merchant server requirements Check with the server administrator that the server 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: 34

35 9. Transaction Examples 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 [email protected] for sending KO result [email protected] for sending information [email protected] 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 1024-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. 35

36 Phase I The merchant s server communicates the information that characterizes the transaction to GestPay, setting the value of the GestPayCrypt attributes: WSCryptDecrypt 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 checkout page will load the js_gestpay.js file and will check the boolean variable BrowserEnabled. If the BrowserEnabled is true the page will call the GestPay.CreatePage function passing three parameters that correspond to the shop login, the encrypted data string received in the previous phase by GestPay and the function that will check the Result object. GestPay authenticates the Shop login (parameter a) and performs security checks on the encrypted data string (parameter b). If the checks are passed, the Result.ErrorCode property will return 10, the iframe is created and the hidden payment page is loaded. Otherwise, the function will return a proper ErrorCode. Phase III In the OnSubmit event of the credit card form the checkout page will retrieve the value inserted by the cardholder and send them to the hidden iframe through the GestPay.SendPayment function. After processing the transaction, GestPay communicates the transaction result (encrypted data string) to the merchant with a server to server comunication. Server-to-server communication myshop.com/s2s.asp?a= &b=4d341a8b... After server-to-server communication has sent, GestPay will return the result through the Result object. The object will provide the encrypted string in the Result.Encrypted string property. The transaction result is also communicated to the merchant via . Send [email protected] 36

37 Phase IV GestPay communicates the transaction result to the merchant, sending an encrypted data string. Using the WSCryptDecrypt webservice, 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 the WSCryptDecrypt webservice. 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 37

38 9.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 customized 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 customized 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 [email protected] 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 [email protected] CustomInfo BV_CODCLIENTE=12*P1*SESSIONID=398 38

39 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 checkout page will load the js_gestpay.js file and will check the boolean variable BrowserEnabled. If the BrowserEnabled is true the page will call the GestPay.CreatePage function passing three parameters that correspond to the shop login, the encrypted data string received in the previous phase by GestPay and the function that will check the Result object. GestPay authenticates the Shop login (parameter a) and performs security checks on the encrypted data string (parameter b). If the checks are passed, the Result.ErrorCode property will return 10, the iframe is created and the hidden payment page is loaded. Otherwise, the function will return a proper ErrorCode. Phase III In the OnSubmit event of the credit card form the checkout page will retrieve the value inserted by the cardholder and send them to the hidden iframe through the GestPay.SendPayment function. After processing the transaction, GestPay communicates the transaction result (encrypted data string) to the merchant with a server to server comunication. Server-to-server communication myshop.com/s2s.asp?a= &b=4d341a8b... After server-to-server communication has sent, GestPay will return the result through the Result object. The object will provide the encrypted string in the Result.Encrypted string property. The transaction result is also communicated to the merchant via . Send [email protected] Phase IV GestPay communicates the transaction result to the merchant, sending an encrypted data string. Using the WSCryptDecrypt webservice, 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 the WSCryptDecrypt webservice. 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: 39

40 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 40

41 10. Implementations Examples 10.1.Net C# PHP 41

42 11 Errors Table Codice Descrizione 0 Transaction correctly processed 10 Payment page correctly loaded 57 Blocked credit card 58 Confirmed amount exceeds authorized amount 63 Demand for settlement of one nonexistent transaction 64 Expired preauthorization 65 Wrong currency 66 Preauthorization already notified 74 Authorization denied 97 Authorization denied 100 Transaction interrupted by bank authorizative system 150 Wrong merchant configuration in bank authorizative system 208 Wrong expiry date 212 Bank authorizative system not available 251 Insufficient credit 401 Call credit card company 402 Call credit card company 403 Technical error 404 Collect card 405 Authorization refused by credit card companies 406 Technical error 409 Technical error 412 Technical error 413 Technical error 414 Card not recognized 415 Technical error in connection with Credit Card Company network 416 Wrong PIN 417 Authorization denied 418 Network not available 419 Wrong transaction date 420 Wrong card date 42

43 430 Technical error 431 Technical error in connection with Credit Card Company network 433 Card expired 434 Authorization refused by credit card companies 435 Authorization refused by credit card companies 436 Card not qualified 437 Operation not allowed 438 Operation not allowed 439 Card not recognized 441 Blocked credit card 443 Blocked credit card 451 Amount not available 454 Card expired 455 Operation not performed 456 Card not recognized 457 Authorization refused by credit card companies 458 Wrong merchant configuration in bank authorizative system 461 Amount not available 462 Blocked credit card 468 Bank authorizative system not available 475 Operation not allowed 490 Technical error 491 Technical error in connection with Credit Card Company network 492 Technical error in connection with Credit Card Company network 494 Technical error 810 Bank authorizative system not available 811 Wrong merchant configuration in bank authorizative system 901 Authorization denied 902 Authorization denied 903 Authorization denied 904 Authorization denied 905 Authorization denied 906 Authorization denied 907 Authorization denied 43

44 908 Authorization denied 910 Authorization denied 911 Authorization denied 913 Authorization denied 914 Authorization denied 915 Authorization denied 916 Authorization denied 917 Authorization denied 918 Authorization denied 919 Authorization denied 920 Authorization denied 950 Not qualified credit card 951 Wrong merchant configuration in bank authorizative system 998 Credit card with wrong 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 1105 Invalid parameter value 1106 Repeated parameter name 1107 Unexpected parameter name. Please double check Fields and Parameters configuration in Back Office Compulsory parameter not set 1109 Missing parameter 1110 Missing PAY1_UICCODE parameter 1111 Invalid currency code 1112 Missing PAY1_AMOUNT parameter 1113 Not numeric amount 1114 Amount with a wrong number of decimal digits 1115 Missing PAY1_SHOPTRANSACTIONID parameter 1116 Too long PAY1_SHOPTRANSACTIONID parameter 1117 Invalid language identifier 1118 Not numeric characters in credit card number 44

45 1119 Credit card number with wrong length 1120 Credit card with wrong check-digit 1121 Credit card belongs to a Company not enabled 1122 Expiry year without expiry month 1123 Expiry month without expiry year 1124 Invalid expiry month 1125 Invalid expiry year 1126 Expired expiry date 1127 Invalid cardholder address 1128 Too long parameter string 1129 Too long parameter value 1130 Not accepted call: missing parameter A 1131 Not accepted call: Shop not recognized 1132 Not accepted call: shop is not in active state 1133 Not accepted call: missing parameter B 1134 Not accepted call: empty parameter B 1135 Not accepted call: other parameters beside A and B are present 1136 Not accepted call: transaction did not begin with a call to server-server cryptography system 1137 Not accepted call: transaction already processed before 1138 Not accepted call: card number or expiry date are missing 1139 Not accepted call: missing published payment page 1140 Transaction cancelled by buyer 1141 Not accepted call: input parameter string not acceptable 1142 Not accepted call: invalid IP Address 1143 Transaction abandoned by buyer 1144 Compulsory field not set 1145 Invalid OTP 1146 Too small amount 1147 Too big amount 1148 Invalid cardholder name 1149 Missing or wrong CVV IPIN must be set 1151 Parameters error 45

46 1153 GestPay failed to verify if the card is enrolled to VBV service 1154 Not accepterd call: missing parameter TransKey 1999 Technical error in connection with Credit Card Company network 2000 Transaction exceeds maximum operations number in time period 2001 Transaction exceeds maximum number of operations performed by the same buyer in time period 2002 Transaction exceeds maximum amount in time period 2003 Transaction exceeds maximum amount payable by same buyer in time period 2004 Transaction contains a field value that had been declared not acceptable 2005 Buyer abandoned the transaction because it was double 2006 Wrong line length 2007 Wrong value in SHOPTRANSACTIONID field 2008 Wrong value in CURRENCY field 2009 Wrong value in AMOUNT field 2010 Wrong value in AUTHORIZATION DATE field 2011 Transaction not found 2012 Transaction ambiguous 2013 Text file contains more rows related to the same transaction 2014 You requested a refund operation with an amount exceeding transaction balance 2015 Wrong value in BANKTRANSACTIONID field 2016 Fields BANKTRANSACTIONID and SHOPTRANSACTIONID are empty 2017 Transacion can not be deleted 2018 Transacion can not be refunded 2019 Transacion can not be settled 2020 Transacion can not be renounced 4100 Operation not allowed 4101 Credit card number with wrong length 4102 Amount not available 4103 Technical error 4104 Technical error 4105 Technical error 46

47 4106 Technical error 4108 Technical error in connection with Credit Card Company network 4109 Technical error 4200 Technical error 4201 Technical error 4202 Technical error 4203 Call credit card company 4204 Operation not allowed 4205 Operation not allowed 4206 Credit card with wrong check-digit. Please double-check the credit card number typed in Technical error 4208 Operation not allowed 4209 Technical error 4300 Technical error 4301 Too big amount 4302 Technical error 4303 Operation not allowed 4304 Technical error 4305 Authorization refused by credit card companies 4306 Operation not allowed 4307 Technical error 4308 Operation not allowed 4309 Too big amount 4400 Wrong transaction date 4401 Wrong expiry date 4402 Technical error in connection with Credit Card Company network 4403 Technical error 4404 Technical error 4405 Operation not allowed 4406 Operation not allowed 4407 Amount not available 4408 Operation not allowed 4409 Operation not allowed 4500 Technical error 4501 Technical error 47

48 4502 Technical error 4503 Operation not allowed 4504 Operation not allowed 4505 Operation not allowed 4506 Technical error 4507 Technical error 4508 Operation not allowed 4604 Technical error 4701 Operation not allowed 4702 Wrong expiry date 4703 Card not qualified 4704 Amount not available 4705 Technical error in connection with Credit Card Company network 4706 Technical error in connection with Credit Card Company network 7400 Authorization denied 7401 Authorization refused by credit card companies 7402 Card not qualified 7403 Card not recognized 7404 Card expired 7405 Call credit card company 7406 Wrong card date 7407 Wrong transaction date 7408 System error 7409 Merchant not recognized 7410 Invalid format 7411 Amount not available 7412 Not settled 7413 Operation not allowed 7414 Network not available 7415 Collect card 7416 PIN attempts exhausted 7417 Blocked terminal 7418 Forcedly Closed terminal 7419 Not permitted transaction 7420 Not authorized transaction 7421 Servizio sospeso il 01/01/

49 7500 Authorization denied 7600 Authorization denied 8000 File correctly processed 8001 Header/bottom record not found 8002 Merchant code not set 8003 Incorrect row number 8004 Incorrect file format 8005 Merchant not enabled 8006 Verify By Visa 8007 Feature disabled for VISA credit card 8008 Feature disabled 8010 Wrong credit card number for this transaction 8011 Transaction correctly received 8012 Authorization not found 8013 Settlement not found 8014 Settlement amount > Authorization amount 8015 Refund amount > balance 8016 Transaction without settlement 8018 File correctly processed 8021 Feature disable for MASTERCARD credit card 8022 Feature disable for JCB credit card 8023 Feature disabled for MAESTRO cards 9991 Browser not supported 9992 Error creating iframe 9997 Phase with error 9998 Phase correctly ended 9999 System Error 49

50 12 Table of currency codes Currency codes are handled by GestPay using the currency attribute. Code UIC Description 18 Italian lira 242 Euro 1 Dollar 2 Pound 71 Japanese Yen 103 Hong Kong Dollar 234 Real 3 Swiss franc 50

51 13 Table of Language Codes The language code is handled by GestPay using the Language attribute. Code Description 1 Italian 2 English 3 Spanish 4 French 5 German 51

52 14 Table of Verified by Visa Codes The VbV code is handled by GestPay using the VbV attribute. Code OK KO Description VbV-certified transaction Transaction not VbV-certified 52

53 15 Payment Orders in Test Environment Remember that to simulate the authorization of a payment order in the test environment it is necessary to use a currently valid credit card. Amounts relating to authorised payment orders will be set against the credit limit of the card used and will never be debited. We therefore recommend that payment orders are made for small amounts so as not to run down the remaining credit on the card used for the tests. 16 Links Test codes Technical support F.A.Q. Forum E-Commerce on Sella.it Back Office environment for actual merchants Back Office environment for test merchants 53