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