GestPay Technical Specifications iframe Payment Page

(1)

GestPay

Technical Specifications

(2)

Summary

About this Document...4

About this version...5

1. Introduction... 6

2. System Architecture... 7

2.1 Architecture scheme ... 7

3. Process phases description...9

3.1 Transaction data encryption... 9

3.2 GestPay iFrame inclusion on the merchant checkout page ...10

3.3 Hidden payment page call...12

3.3.1 Send the credit card data... 12

3.3.2 Transaction results... 13

3.3.2.1 3D transactions (Verified by Visa, Mastercard SecurCode)...13

3.3.2.1.1 Cardholder authentication... 14

3.3.2.1.2 Transaction end... 14

3.3.3 Javascript js_GestPay.js ... 15

3.3.3.1 GestPay.CreatePaymentPage...15

Arguments... 15

Syntax:... 15

Example:... 15

3.3.3.2 Function: GestPay.SendPayment...16

Credit card authorization... 16

Arguments... 16

Syntax:... 16

Example:... 16

2nd call after 3D authentication... 16

Arguments... 16

Syntax:... 16

Example:... 17

3.3.3.3 Object: Result ... 18

Properties:... 18

Examples:... 18

3.3.3.3.1 Error Codes...19

3.3.4 Response to merchant... 20

3.4 Default payment page call ...21

3.4.1 Communication of transaction result...21

3.3.1 Response to merchant...21

3.3.2 Response to Buyer... 21

3.5 Transaction result decryption... 22

4. Server to Server Authentication... 23

5. Transaction Data structure...24

5.1 Transaction Data to Send to GestPay... 24

5.2 Transaction data received by GestPay...26

6. Merchant’s Profile... 28

6.1 Authentication configuration... 28

6.2 Configuration of response url and e-mail... 29

6.3 Configuration of Fields & Parameters... 30

7. Webservice...31

7.1 Instructions for the use of the encryption module with the WEBSERVICE interface 31

7.2 Generation of Proxy Class to use webservice functions from various languages....32

7.3 List of calls available with WSCryptDecrypt webservice... 33

8. Software Requirements... 34

8.1 Buyer browser requirements... 34

8.2 Merchant server requirements...34

9. Transaction Examples...35

9.1 Transaction # 1... 35

(3)

Phase III... 36

Phase IV... 37

9.2 Transaction #2... 38

Phase I... 38

Phase II... 39

Phase III... 39

Phase IV... 39

10. Implementations Examples...41

10.1 .Net C#...41

10.2 PHP...41

11 Errors Table... 42

12 Table of currency codes... 50

13 Table of Language Codes... 51

14 Table of Verified by Visa Codes... 52

15 Payment Orders in Test Environment... 53

(4)

About this Document

Project name GestPay iFrame Payment page

Document Title GestPay – Technical Specifications – iFrame Payment page

Creation Date 02.APR.2012

Language English

(5)

About this version

Version Description Date Author

(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 (https://www.pcisecuritystandards.org/).

(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.

(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.

(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.

(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

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="https://ecomm.sella.it/Pagam/HiddeniFrame.aspx? 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

} }

(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 10+

(12)

3.3 Hidden payment page call

3.3.1 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 3.3.2.2 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" /> </fieldset> </form> <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

(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).

3.3.2.1 3D 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.

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

} }

(14)

3.3.2.1.1 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: https://ecomm.sella.it/pagam/pagam3d.aspxs for test codes

https://testecomm.sella.it/pagam/pagam3d.aspx

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.

3.3.2.1.2 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.

GestPay.SendPayment({'TransKey':'//PLACE HERE THE TRANSKEY VALUE','PARes':'//PLACE HERE THE PARES VALUE'},LocalObj.CallBack);

//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; }

}

(15)

3.3.3 Javascript js_GestPay.js

3.3.3.1 GestPay.CreatePaymentPage

Arguments

1. Merchant code (string) 2. EncryptedString (string) 3. CallBackObject (object) Syntax: GestPay.CreatePaymentPage (MerchantCode,EncryptedString,CallBackObj); Example: GestPay.SendPayment ('9000001', '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

} });

(16)

3.3.3.2 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 : '44444444444444444', EXPMM : '11', EXPYY : '14' },function(Result){ if(Result.ErroCode == 0){

//Transaction correctly processed

//Decrypt the Result.EncryptedString property to read the //transaction result

}else{

} });

2nd_{call after 3D authentication}

Arguments 6. CCData (Array) 1. PARes (string) 2. TransKey (string) 7. CallBackObj (object) Syntax:

(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{

} });

(18)

3.3.3.3 Object: Result

Properties:

Result.ErrorCode return the error code Result.ErrorDescription return the error description

Result.EncryptedResponse return the encrypted response string

Result.TransKey return the TransKey in case of 3D enrolled credit card Result.VBVRisp 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

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

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{

//Transaction correctly processed proceed to decrypt the //Result.EncryptedResponse property

} }

(19)

3.3.3.3.1 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 CVV2

1154 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.

8008 Feature disabled iFrame feature is not active

9991 Browser not supported

9992 Error creating iFrame

9999 System Error Technical error during the transaction

process

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

http://<url 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 e-mail 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.

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

https://ecomm.sella.it/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>

for test codes:

https://testecomm.sella.it/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>

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.

3.4.1 Communication of transaction result

GestPay communicates the transaction result both to the merchant and the buyer. 3.3.1 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:

http://<url server to server>?a=<ShopLogin>&b=<encrypted string>

a the code which identifies merchant (Shop Login)

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

http://<url 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. e-mail) to conclude the purchasing process.

The buyer will also receive a transaction result notification e-mail 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.

(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.

(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

BuyerEmail VarChar (50) I/P O Buyer’s e-mail 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.

(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*

/ [ ] ? =

(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

BuyerEmail VarChar (50) I/P O Buyer’s e-mail 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

Country VarChar (30) P O

Nationality of institute issuing card

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

(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 Description

OK Positive transaction result KO Negative transaction result

(28)

6. Merchant’s Profile

Each merchant can configure his/her profile by accessing the GestPay Back Office environment at:

https://ecomm.sella.it/gestpay/backoffice/logingestpay.asp for test codes:

https://testecomm.sella.it/gestpay/backoffice/logingestpay.asp

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).

(29)

6.2 Configuration of response url and e-mail

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 e-mail.

Configuration – Responses Note.

“URL for positive response “ and “URL for negative response” will not be called using the iFrame payment page.

(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.

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

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:

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

https://ecomms2s.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL

For test codes:

https://testecomm.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL

For example:

wsdl /language:VB /out: wss2sProxyClass.vb

https://testecomm.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL

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”).

(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

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

BuyerEmail Assigns buyer’s email

Language (val) Assigns language for emails to buyer

CVV (val) Assigns security code printed on card

CustomInfo (val) Assigns string containing any customised parameters

Input parameters, Decrypt method

ShopLogin Used to set value of ShopLogin attribute

CryptedString 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

TransactionType The type of request executed can have the following values:

ENCRYPT (E) DECRYPT (D)

(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 https://ecomm.sella.it/ 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+, Opera10+

8.2 Merchant server requirements

Check with the server administrator that the server can reach the following addresses:

If http (port 80) communication is used:

http://ecomms2s.sella.it/testhttp/test.asp

For test codes:

http://testecomm.sella.it/testhttp/test.asp

If https (port 443) communication is used:

https://ecomms2s.sella.it/testhttps/test.asp

For test codes:

(35)

9. Transaction Examples

This chapter describes a number of significant examples of interfacing with Gestpay. The ShopLogin used in the examples is 9000001.

The merchant’s profile is the following:

Merchant’s Profile

IP Address 171.85.234.97

Server-to-server Communication Url http://www.myshop.com/s2s.asp

Url for positive responses http://www.myshop.com/respOK.asp

Url for negative responses http://www.myshop.com/respKO.asp

E-mail for sending OK result [email protected]

E-mail for sending KO result [email protected]

E-mail 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 1828.45

Currency Transaction euro

Let us suppose that the transaction is concluded positively (payment will be made), returning the following result:

Result

Authorisation code 54e813

(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 9000001 Currency 242 Amount 1828.45 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 9000001

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

http://www. myshop.com/s2s.asp?a=9000001&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 e-mail.

Send E-mail

(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.

ShopLogin 9000001

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 9000001 Currency 242 Amount 1828.45 ShopTransactionID 34az85ord19 TransactionResult OK AuthorizationCode 54e813 BankTransactionID 216 ErrorCode 0

(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 e-mail 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 1245.6

Currency Transaction Euro

Language Spanish

Buyer’s Name and Surname Mario Bianchi

Buyer’s E-mail 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 9000001 Currency 242 Amount 15.6 ShopTransactionID 34az85ord19 Language 3

BuyerName Mario Bianchi

BuyerEmail [email protected]

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

ShopLogin 9000001

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

http://www. myshop.com/s2s.asp?a=9000001&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 e-mail.

Send E-mail

[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

(40)

GestPay Result ShopLogin 9000001 Currency 242 Amount 15.6 ShopTransactionID 34az85ord19 TransactionResult OK AuthorisationCode 9823y5 BankTransactionID 860 CustomInfo BV_CODCLIENTE=12*P1*SESSIONID=398 ErrorCode 0

(41)

10. Implementations Examples

10.1 .Net C#

http://service.easynolo.it/download/iFrameExample_Net.zip

10.2 PHP

(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

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

418 Network not available

419 Wrong transaction date

(43)

430 Technical error

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

451 Amount not available

454 Card expired

455 Operation not performed

457 Authorization refused by credit card companies

458 Wrong merchant configuration in bank authorizative system

468 Bank authorizative system not available

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

(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.

1108 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

(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 email 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

(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

4103 Technical error

(47)

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.}

4301 Too big amount

4305 Authorization refused by credit card companies 4306 Operation not allowed

4309 Too big amount

(48)

4502 Technical error 4503 Operation not allowed 4504 Operation not allowed 4505 Operation not allowed

4703 Card not qualified

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

7404 Card expired

7405 Call credit card company

7406 Wrong card date

7408 System error

7409 Merchant not recognized

7410 Invalid format

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

(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

(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

(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

(52)

14 Table of Verified by Visa Codes

The VbV code is handled by GestPay using the VbV attribute.

Code Description

OK VbV-certified transaction

(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 http://service.easynolo.it/download.asp Technical support https://www.easynolo.it/easynolo/ecommerce/assistenza/richiedi_assistenza.jsp?p=com_42 F.A.Q. https://www.easynolo.it/easynolo/ecommerce/assistenza/faq_ecommerce.jsp?p=com_55 Forum http://service.easynolo.it/forum.asp E-Commerce on Sella.it https://www.sella.it/ita/aziende/ecommerce/index.jsp

Back Office environment for actual merchants

https://ecomm.sella.it/gestpay/backoffice/LoginGestPay.asp

Back Office environment for test merchants