gestpay: wss2s web service technical specifications · gestpay: wss2s web service technical...

GestPay: WSs2s web service technical specifications of 53

GestPay: WSs2s web service technical

specifications


About this Document ........................................................................................2 About this version .............................................................................................4 Instructions for the use of the WSs2s module with web service interface ..5 Definitions for WSs2s web service .................................................................6 List of the available calls of the WSs2s web service......................................7

Method callPagamS2S...................................................................................................7 RED Accreditation Tests .........................................................................................11

Method callReadTrxS2S..............................................................................................12 Method callCheckCartaS2S.........................................................................................13 Method callVerifyCardS2S..........................................................................................14 Method callSettleS2S ..................................................................................................15 Method callRefundS2S ...............................................................................................16 Method callDeleteS2S ................................................................................................17 Method CallRequestTokenS2S ...................................................................................18 Method callUpdateTokenS2S .....................................................................................19 Method callDeleteTokenS2S ......................................................................................20 Method CallIdealListS2S.............................................................................................21 Method CallMyBankListS2S.......................................................................................22

Operations allowed through the WSs2s web service...................................23 Authorisation Request..................................................................................................23 Settlement ....................................................................................................................28 Withdrawal...................................................................................................................29 Reversal........................................................................................................................30 Transaction status query ..............................................................................................31 Card verification ..........................................................................................................33 Card check ...................................................................................................................34 Request Tokens............................................................................................................36 Delete Tokens ..............................................................................................................38 Update Tokens .............................................................................................................39 Ideal List ......................................................................................................................40 MyBank List ...............................................................................................................41

3D-secure Transactions ..................................................................................42 Transactions made with non 3D-Secure cards.............................................................42 Transactions made with 3D-Secure cards....................................................................42

CVV field handling...........................................................................................44 Payment orders in test environment..............................................................45 Table of Country RED Codes..........................................................................46 Software Requirements...................................................................................52 Links .................................................................................................................53 Support.............................................................................................................53


About this Document Project name WSs2s WEB SERVICE XML Document Title WSs2s – Technical Specifications Creation Date 20.08.2010 Language English Company Easy Nolo S.p.A.


About this version

Version Description Date 1_0_0 Initial Version 02/12/08 1_1_0 URL 3D Updated 05/11/12 1_2_0 Tokenization, RED functionalities 25/11/13 1_3_0 MyBank Bank List, Ideal Bank list 21/03/14 1_4_0 IGFS Integration, PayPal Reference Transaction 22/10/14 1_5_0 Tokenization Group, naming revision (case sensitive)

13/02/15

1_6_0 Software Requirements 27/01/16


Instructions for the use of the WSs2s module with web service interface

This document contains the instructions for using WSs2s web service, needed by merchants in order to use GestPay in Server-Server mode. GestPay servers apply TLS encryption protocol and they are periodically updated to the latest security standards. The same care is suggested to the merchants, who are required to periodically verify the compatibility of their systems against GestPay test environment, that is always updated before the production environment. The use of GestPay, and therefore also of the WSs2s module, is reserved for companies which entered in the relevant agreements with EasyNolo and Banca Sella regarding the management of online payment transactions and therefore identified as "Participating Merchants". A GestPay Participating Merchant is recognizable by an identification code called "shopLogin" 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). As GestPay allows each merchant to decide what information to send to the system (apart from a minimum required series of information), merchants must configure the system appropriately, using the "Fields & Parameters" section in the Back Office (BackOffice->PaymentPage->Fields&Parameters). GestPay, furthermore, only accepts calls from an IP address associated with the shopLogin of the merchant making the call. It is therefore necessary, once again working within the Back Office environment (BackOffice->Configuration->Environments->IPAddress), to configure the IP address of the server that is to make the calls to WSs2s.


Definitions for WSs2s web service Server to Server communication between merchants and GestPay is managed by consuming WSs2s SOAP web service (http://www.w3.org/TR/soap/). Consuming WSs2s methods allow merchants to send requests and retrieve responses in XML format. WSDL - Web Services Description Language (http://www.w3.org/TR/wsdl) Production: https://ecomms2s.sella.it/gestpay/gestpayws/WSs2s.asmx?WSDL Test environment: https://testecomm.sella.it/gestpay/gestpayws/WSs2s.asmx?WSDL Language References .Net http://msdn.microsoft.com/en-us/library/ms733133.aspx Php http://php.net/manual/en/class.soapclient.php http://sourceforge.net/projects/nusoap/ Python https://wiki.python.org/moin/WebServices Java http://docs.oracle.com/javaee/5/tutorial/doc/bnayn.html [A Simple JAX-WS Client] Ruby http://savonrb.com/


List of the available calls of the WSs2s web service. Below is a complete list of the methods of WSs2s web service. The names of the methods are case sensitive:

WSs2s methods Method Name Description

callDeleteS2S Cancels an authorized transaction callPagam S2S Performs an authorisation request callReadTrxS2S Queries the transaction details and status callRefundS2S Withdraws a settled transaction callSettleS2S Settles an authorized transaction callVerifyCardS2S Verifies the validity of a credit card call CheckCartaS2S Checks the card information with or without validat ion callDeleteTokenS2S Deletes a token from GestPay CallRequestTokens2S Requests a token for a credit card number CallUpdateTokenS2S Updates Expiry Month and Expiry Year for a token Cal lIdealListS2S Requests Ideal Bank List CallMyBankListS2S Requests MyBank Bank List

The different calls to the methods are handled by the web service as function calls and therefore without the passage of a XML string. The values of the different calls must be passed as parameters.

Method callPagamS2S Merchants can use this method to perform the transaction, passing all the parameters useful to define all the transaction’s features. CallPagamS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim amount Assigns amount Numeric 9 buyerEmail Assigns buyer’s e-mail address.

Using :NOSEND: before the email address, it' s possible to pass the email information but avoid the email send to the buyer.

Alphanumeric 50

buyerName Assigns buyer’s name Alphanumeric 50 cardNumber Assigns card account number Alphanumeric 20 uicCode Assigns currency code Numeric 3 customInfo Assigns a string containing possible

customised parameters Alphanumeric 1000

cvv Assigns security code of the card Alphanumeric 4 expiryMonth Assigns card expiration month Alphanumeric 2 expiryYear Assigns card expiration year Alphanumeric 2 languageId Assigns language to use for e-mails to

the buyer Numeric 2

PARes Assigns encrypted string returned by Issuer (for 3D-Secure transactions only)

Alphanumeric 4096

shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 transKey Assigns transaction ID value for 3D-

Secure transactions Numeric 18

requestToken “MASKEDPAN” for a Standard Token any other value for Custom Token

Alphanumeric 25

tokenValue String containing the token value, in Alphanumeric 25


Input Parameters case of PayPalBillingAgreement this token value is the Token returned back from PayPal during the Billing Agreements

redFraudPrevention Flag to activate Red Fraud Prevention (redFraudPreventin=1)

Numeric 1

Red_CustomerInfo Customer_Title Red parameter: Customer Title Alphanumeric 5 Customer_Name Red parameter: Customer First Name Alphanumeric 30 Customer_Surname Red parameter: Customer Last Name Alphanumeric 30 Customer_Email Red parameter: Customer Email Address -

value must contain @ Alphanumeric 45

Customer_Address Red parameter: Customer address line 1 Alphanumeric 30 Customer_Address2 Red parameter: Customer address line 2 Alphanumeric 30 Customer_City Red parameter: Customer address city String 20 Customer_StateCode Red parameter: Customer address state

code String 2

Customer_Country Red parameter: Customer Country Code - ISO-Alpha 3 (IE: ITA) - See Table of Country RED Codes at the end of the document

String 3

Customer_PostalCode Red parameter: Customer Post/Zip Code Alphanumeric 9 Customer_Phone Red parameter: Customer Phone - no

spaces Numeric (no spaces)

19

Red_ShippingInfo Shipping_Name Red parameter: Shipping First Name Alphanumeric 30 Shipping_Surname Red parameter: Shipping Last Name Alphanumeric 30 Shipping_Email Red parameter: Shipping Email Address -

value must contain @ Alphanumeric 45

Shipping_Address Red parameter: Shipping address line 1 Alphanumeric 30 Shipping_Address2 Red parameter: Shipping address line 2 Alphanumeric 30 Shipping_City Red parameter: Shipping address city String 20 Shipping_StateCode Red parameter: Shipping address state

code String 2

Shipping_Country Red parameter: Shipping Country Code - ISO-Alpha 3

String 3

Shipping_PostalCode Red parameter: Shipping Post/Zip Code Alphanumeric 9 Shipping_HomePhone Red parameter: Shipping Home Phone - no

spaces Numeric (no spaces)

19

Shipping_MobilePhone Red parameter: Shipping Fax Phone - no spaces

Numeric (no spaces)

12

Shipping_FaxPhone Red parameter: Shipping Mobile Phone Numeric (no spaces)

19

Shipping_TimeToDeparture Red parameter: Shipping Time To Departure (See RED Par. for details)

String 1

Red_BillingInfo Billing_Id Red parameter: Billing ID Alphanumeric 16 Billing_Name Red parameter: Billing First Name Alphanumeric 30 Billing_Surname Red parameter: Billing Last Name Alphanumeric 30 Billing_DateOfBirth Red parameter: Billing DoB - format:

YYYY-MM-DD Alphanumeric 10

Billing_Email Red parameter: Billing Email Address - value must contain @

Alphanumeric 45

Billing_Address Red parameter: Billing address line 1 Alphanumeric 30 Billing_Address2 Red parameter: Billing address line 2 Alphanumeric 30 Billing_City Red parameter: Billing address city Alphanumeric 20 Billing_StateCode Red parameter: Billing address state

code String 2

Billing_Country Red parameter: Billing Country Code - ISO-Alpha 3

String 3

Billing_PostalCode Red parameter: Billing Post/Zip Code Alphanumeric 9 Billing_HomePhone Red parameter: Billing Home Phone - no Numeric (no 19


Input Parameters spaces spaces)

Billing_WorkPhone Red parameter: Billing Work Phone - no spaces

Numeric (no spaces)

19

Billing_MobilePhone Red parameter: Billing Mobile Phone Numeric (no spaces)

19

Red_CustomerData MerchantWebSite Red parameter: Transaction Source

Website Alphanumeric 60

Customer_IPAddress Red parameter: IP of customer - Format: nnn.nnn.nnn.nnn

Alphanumeric 45

PC_FingerPrint Red parameter: PC Finger Print (See PC Finger Print Paragraph below) if the RED Configuration is defined with the chance to fill this value, but for some reasons it's left empty, then pay attention and fill Red_ServiceType=N to avoid error

Alphanumeric 4000

PreviousCustomer Red parameter: Previous Customer Flag - format Y or N

Numeric 1

Red_Merchant_ID Red parameter: Optional only for merchant with a specific set of rules (Code provided by Sella)

Alphanumeric 12

Red_ServiceType Red parameter: Optional only for merchant with a specific set of rules (Code provided by Sella)

Alphanumeric 1

Red_CustomInfo UserCustomData Red parameter: Custom Data Fields (Zero

or more repetitions) Alphanumeric From 1 To 10

->256 From 11 To 25 ->30

Red_Items NumberOfItems Red parameter: Required to specify the

number of repeating item tags max value 99

Numeric 2

Red_Item Item_ProductCode Red parameter: Item Product Code Alphanumeric 12

Item_StockKeepingUnit Red parameter: Item Stock Keeping Unit Alphanumeric 12

Item_Description Red parameter: Item Description Alphanumeric 26

Item_Quantity Red parameter: Item quantity - 1 should be sent as 10000

Numeric 12

Item_UnitCost Red parameter: Item cost amount - € 5.00 should be sent as 50000

Numeric 12

Item_TotalCost Red parameter: Total Item Amount (item qty x item cost amt), no decimal

Numeric 12

Item_ShippingNumber Red parameter: Item shipping/tracking number

Alphanumeric 19

Item_GiftMessage Red parameter: Item gift message Alphanumeric 160

Item_PartEAN_Number Red parameter: Item Park or EAN Number Alphanumeric 30

Item_ShippingComments Red parameter: Item Shipping Comments Alphanumeric 160 ClientIP For PayPal Billing Agreements it is

required only in the "one click" mode transaction For AMEX transaction not in Euro, in this filed the merchant could provide the ClientIP address to activate the Enhanced Authorization AAV

Alphanumeric 45

itemType Item Category Digital/Physical (If physical the ShippingDetails have to be filled)

String 250

shippingDetails shipToName String containing the shipping name Alphanumeric 32


Input Parameters shipToStreet String containing the shipping address Alphanumeric 100 shipToCity String containing the shipping city Alphanumeric 40 shipToState String containing the shipping state

(see State Codes table) Alphanumeric 40

shipToCountryCode String containing the shipping country code (see Country Codes table)

Alphanumeric 2

shipToZip String containing the shipping zip Alphanumeric 20 shipToStreet2 String containing a shipping address

additional field Alphanumeric 100

CallPagamS2S output description:

XML returned Parameter Name Description TransactionType The performed request PAGAM TransactionResult Returns transaction result with OK e KO values ShopTransactionID Ret urns shop transaction ID value BankTransactionID Returns code given by bank to transaction AuthorizationCode Returns authorisation code Currency Returns currency code Country Returns nationality of the card issuer Custom Info Returns the possible custom parameters Buyer Type Returns address name and e-mail of the buyer

divided as follows Buyer Email Returns the e - mail of the buyer Buyer Name Returns the name of the buyer ErrorCode Returns a code related to the transact ion result ErrorDescription Returns the description connected to the ErrorCode value AlertCode Returns the violation code of the risk management c riteria AlertDescription Returns the description connected to the AlertCode value Amount Returns the a mount of the transaction TransKey Returns transaction ID value for 3D - Secure transactions VBV Returns the values for 3D - Secure as follows VbVFlag Returns the flag 3D - Secure (OK or KO) VbVBuyer Returns the flag Full Verified by Visa transaction VbVRisp Returns the encrypted string obtained by 3D-Secure

directory

TDLevel Level of authentication for 3D-Secure transactions. The string may have the value FULL or HALF

ACCEPT Passed fraud screening DENY Recommend Deny CHALLENGE Recommend Challenge NOSCORE

ReD not required to give a recommendation

ERROR Error in request data or internal ReD Shield

ENETFP Unable to connect to ReD Shield ETMOUT Screening request timed out

RedResponseCode RED Fraud Score of the transaction or Error code if there are problems with RED request

EIVINF Invalid Information RedResponseDescription RED Description of the RedResponseCo


RED Accreditation Tests

The purpose of the accreditation is to ensure clients have developed their interface to meet RED's requirements. Clients are expected to demonstrate that they can process good transactions. Each test section has a column available to provide the RED_ID so that RED can validate the test results. Please send these completed section back to BancaSella once you have completed your tests.

Positive Response Testing Test No. Istruction RED_ID

POS001 Send a transaction using Billing_Email=accep [email protected] POS002 Send a transaction using Billing_Email=chall [email protected] POS003 Send a transaction using Billing_Email=deny@ email.com POS004 Send a transaction with every field you will be sending to

ReD


Method callReadTrxS2S This method can be called passing as mandatory shopLogin, then it's possible to pass shopTransactionID or bankTransactionID or both. If it will be passed only ShopLogin and shopTransactionID it’s mandatory that the last one has to be unique. CallReadTrxS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 bankTransactionId BankTransactionID assigned to the

transaction Numeric 18

CallReadTrxS2S output description:

XML returned values Parameter Name Description TransactionType The performed request QUERYTX TransactionResult Returns transaction result with OK e KO values ShopTransactionID Returns shop transaction ID value BankTransactionID Returns code given by bank to transaction AuthorizationCode Returns authorisation code Currency Returns currency code Country Returns nationality of the card issuer

AUT MOV CAN REQ

Events.eventtype EventType type of event with the following values. There is a node Events for each existing events regarding the transaction, one for AUT, one for MOV and so on

STO

Events.eventamount Event Amount Relative value of the event Events.eventdate Event date Company Returns card company: Visa, Mastercard etc . TransactionState Returns status (Authorised, Withdrawn etc.) of t ransaction AlertDescription Returns the description connected to the AlertCode value AlertCode Returns the violation code of the risk management c riteria TransKey Returns transaction ID value for 3D - Secure transactions TDLevel Level of authentication for 3D- Secure transactions. The string

may have the value FULL or HALF Buyer.BayerName Buyer Email Returns the e-mail of the buyer Buyer.BuyerEmail Buyer Name Returns the name of the buyer ErrorCode Returns a code related to the transaction result ErrorDescription Returns the description connected to the ErrorCode value


Method callCheckCartaS2S Merchants can use this method to check the Credit Card. It's possible to check with or without verify the Authorization, setting the flag "withAuth". CallCheckCartaS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 cardNumber Assigns card account number Alphanumeric 20 expMonth Assigns card expiration month Alphanumeric 2 expYear Assigns card expiration year Alphanumeric 2 CVV2 Assigns security code of the card Alphanumeric 4 withAuth Flag to define if verify the

Authorization or not Y on N values Alphanumeric 1

CallCheckCartaS2S output description:

XML returned values Parameter Name Description TransactionType The performed request CHECKCARD TransactionResult Returns transaction result with OK e KO values TransactionErrorCode Returns transaction error code TransactionErrorDescription Returns transaction error description AuthorizationErrorCode Returns authorisation error code if an error occurred AuthorizationResult Returns authorisation results AuthorizationCodeDescription Returns authorisation code description CardCountry Returns nationality of the card CardCountryCode Returns nationality code of the card CheckCVV Returns results of check CVV CheckCVVDescription Returns description of CVV check results IssuerCountry Returns nationality of the card issuer IssuerCountryCode Returns nationality code of the card issuer CompanyDescription Description of the Card company CompanyCode Code of the Company Commercial Flag that indicates if the Card is commercial or not ProductDescription Returns description of the product linked to the card ProductType Returns the type of product CheckDigit Returns OK or KO according to the check digit of the card CheckDigitDescription Return description of the check Digit response CheckDate Returns OK or KO according to the check date of the card CheckDateDescription Returns description of the check date response EnrolledCode Returns enrolment code (Y,N or U) EnrolledDescription Returns enrolment description Prepaid Flag that indicates if the card is prepaid or not (Y, N or empty)


Method callVerifyCardS2S Merchants can use this method to check the Credit Card. CallVerifyCardS2S input description:

Input Parameters

Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 cardNumber Assigns card account number Alphanumeric 20 expMonth Assigns card expiration month Alphanumeric 2 expYear Assigns card expiration year Alphanumeric 2 CVV2 Assigns security code of the card Alphanumeric 4

CallVerifyCardS2S output description:

XML returned values Parameter Name Description TransactionType The performed request VerCard TransactionResult Returns transaction result with OK e KO values ErrorCode Returns transaction error code ErrorDescription Returns transaction error description Country Returns nationality of the card issuer Company Description of the Card company


Method callSettleS2S Merchants can use this method to settle the transaction. It's possible to settle only a part of the amount, so the amount value has to be passed. CallSettleS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 amount Assigns amount Numeric 9 uicCode Assigns currency code Numeric 3 bankTransID BankTransactionID assigned to the transaction Numeric 18

CallSettleS2S output description:

XML returned values Parameter Name Description TransactionType The performed request Settle TransactionResult Returns transaction result with OK e KO values ErrorCode Returns transaction error code ErrorDescription Returns transaction error description BankTransactionID BankTransactionID assigned to the transaction ShopTransactionID Shop transaction ID value assigned to the transaction


Method callRefundS2S Merchants can use this method to perform a partial or complete transaction amount refund. CallRefundS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 amount Assigns amount Numeric 9 uicCode Assigns currency code Numeric 3 bankTransactionId BankTransactionID assigned to the


CallRefundS2S output description:

XML returned values Parameter Name Description TransactionType The performed request Refund TransactionResult Returns transaction result with OK e KO values ErrorCode Returns transaction error code ErrorDescription Returns transaction error description BankTransactionID BankTransactionID assigned to the transaction ShopTransactionID Shop transaction ID value assigned to the transaction


Method callDeleteS2S Merchants can use this method to delete a transaction passing the shopLogin , shopTransactionId and/or bankTransactionId. CallDeleteS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 shopTransactionId Assigns shop transaction ID value Alphanumeric 50 bankTransactionId BankTransactionID assigned to the


CallDeleteS2S output description:

XML returned values Parameter Name Description TransactionType The performed request Delete TransactionResult Returns transaction result with OK e KO values ErrorCode Returns transaction error code ErrorDescription Returns transaction error description BankTransactionID BankTransactionID assigned to the transaction ShopTransactionID Shop transaction ID value assigned to the transaction


Method CallRequestTokenS2S Merchants can use this method to request the token generation for a Credit Card. This token can be generated as Standard Format or Custom Format. Tokens created by merchants belonging to a group will be available to all the merchants of the same group. CallRequestTokenS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 requestToken “MASKEDPAN” for a Standard Token any

other value for Custom Token Alphanumeric 25

cardNumber Assigns card account number Alphanumeric 20 expiryMonth Assigns card expiration month Alphanumeric 2 expiryYear Assigns card expiration year Alphanumeric 2 cvv Assigns security code of the card Alphanumeric 4 withAuth Flag to define if verify the Authorization or not

Y on N values Alphanumeric 1

CallRequestTokenS2S output description:

XML returned values Parameter Name Description TransactionType The performed request REQUESTTOKEN TransactionResult Returns transaction result with OK e KO values TransactionErrorCode Returns transaction error code TransactionErrorDescription Returns transaction error description AuthorizationErrorCode Returns authorisation error code if an error occurred AuthorizationResult Returns authorisation results AuthorizationCodeDescription Returns authorisation code description CardCountry Returns nationality of the card CardCountryCode Returns nationality code of the card CheckCVV Returns results of check CVV CheckCVVDescription Returns description of CVV check results IssuerCountry Returns nationality of the card issuer IssuerCountryCode Returns nationality code of the card issuer CompanyDescription Description of the Card company CompanyCode Code of the Company Commercial Flag that indicates if the Card is commercial or not ProductDescription Returns description of the product linked to the card ProductType Returns the type of product CheckDigit Returns OK or KO according to the check digit of the card CheckDigitDescription Return description of the check Digit response CheckDate Returns OK or KO according to the check date of the card CheckDateDescription Returns description of the check date response EnrolledCode Returns enrolment code (Y,N or U) EnrolledDescription Returns enrolment description Prepaid Flag that indicates if the card is prepaid or not (Y or N) Token Returns the token value TokenExpiryMonth Returns the token expiry month TokenExpiryYear Returns the token expiry year


Method callUpdateTokenS2S Merchants can use this method to update the expiry date of a token. Merchants belonging to a group are allowed to update also tokens created by other merchants of the same group. If a merchant belongs to a group, can update also token created by the other group's merchants. CallUpdateTokenS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 token Token value to update Alphanumeric 25 exipryMonth Assigns card expiration month Alphanumeric 2 expiryYear Assigns card expiration year Alphanumeric 2 withAut Flag to define if verify the Authorization or not Y on N values Alphanumeric 1

CallUpdateTokenS2S output description:

XML returned values Parameter Name Description TransactionType The performed request DisableToken TransactionResult Returns transaction result with OK e KO values ErrorCode Returns transaction error code ErrorDescription Returns transaction error description


Method callDeleteTokenS2S Merchants can use this method to disable a token linked to a Credit Card or to cancel a PayPal Billing Agreement. Merchants belonging to a group are allowed to delete also tokens created by other merchants of the same group CallDeleteTokenS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 tokenValue Token value to delete Alphanumeric 25

CallDeleteTokenS2S output description:

XML returned values Parameter Name Description TransactionType The performed request DisableToken TransactionResult Returns transaction result with OK e KO values ErrorCode Returns transaction error code ErrorDescription Returns transaction error description


Method CallIdealListS2S Merchants can use this method to have the list of the Banks available for their customers for IDeal payment method. CallIdealListS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30

CallIdealListS2S output description:

XML returned values Parameter Name Description TransactionType The performed request IdealList TransactionResult Returns transaction result with OK e KO values ErrorCode Returns a code related to the transaction result ErrorDescription Returns the description connected to the ErrorCode value BankList.Bank.BankCode Returns Ideal Bank List, for each bank returns the Bank Code BankList.Bank.BankName Returns Ideal Bank List, for each bank returns the Bank Name


Method CallMyBankListS2S Merchants can use this method to have the list of the Banks available for their customers for MyBank payment method CallMyBankListS2S input description:

Input Parameters Parameter Name Description Data Type Max Dim shopLogin Assigns shopLogin value Alphanumeric 30 languageId Assigns the response language of the Bank list Numeric 2

CallMyBankListS2S output description:

XML returned values Parameter Name Description TransactionType The performed request MyBank TransactionResult Returns transaction result with OK e KO values ErrorCode Returns a code related to the transaction result ErrorDescription Returns the description connected to the ErrorCode value BankList.Bank.BankCode Returns MyBank Bank List, for each bank returns the Bank Code BankList.Bank.BankName Returns MyBank Bank List, for each bank returns the Bank Name


Operations allowed through the WSs2s web service A description follows of all operations allowed through the WSs2s web service and the way to perform each operation.

Authorisation Request

This is simply the payment operation. It consists in sending all of the information required to make a payment transaction to the bank’s server. It also consists in retrieving the transaction result after it has been processed by the bank. The specific WSs2s method to use for this purpose is CallPagamS2S.

However, before using this method, it is necessary to assign a value to all the required information, for the passage of the parameters: ▪ shopLogin (Merchant Code) ▪ uicCode (Currency Code) ▪ amount (Amount) ▪ shopTransactionId (Transaction ID Code) ▪ cardNumber (Credit Card Account Number) ▪ expiryMonth (Card Expiration Month) ▪ expiryYear (Card Expiration Year) The following features may optionally be assigned, upon appropriate configuration of the “Client configuration | Fields & Parameters” section:

▪ buyerName (Buyer’s name) ▪ buyerEmail (Buyer’s e-mail address) ▪ languageId (Language code)

▪ cvv (String containing the Card Verification Value printed on the credit card, as specified in the chapter "Handling of CVV field")

▪ min (not in use leave empty) ▪ transKey (check the Verified by Visa Transactions paragraph) ▪ PARes (check the Verified by Visa Transactions paragraph) ▪ customInfo (String containing possible customised fields, declared as “Parameters”

in the relevant section of the Back Office environment , BackOffice->PaymentPage- >Fields&Parameters) ▪ IDEA (not in use leave empty) ▪ requestToken (“MASKEDPAN” for a Standard Token any other value for Custom Token) ▪ TokenValue (Token used for the transaction, in case of PayPalBilling Agrrements is the token provided by PayPal. If a merchant belongs to a group can use a own token or also one of token of the group’s components) ▪ ClientIP (For PayPal Billing Agreements it is required only in the "one click" mode transaction For AMEX transaction not in Euro, in this filed the merchant could provide the ClientIP address to activate the Enhanced Authorization AAV ) ▪ itemType (Item Category Digital/Physical) ▪ shippingDetails (shipToName, shipToStreet, shipToCity, shipToState, shipToCountryCode, shipToZip, shipToStreet2)

If the merchat has the RED Fraud Prevention feature, then. upon appropriate configuration of the “Client configuration | Fields & Parameters” section to enable these fields, may optionally assignee the following features:


• redFraudPrevention Flag to activate Red Fraud Prevention (redFraudPreventin=1) • Red_CustomerInfo.Customer_Title Red parameter: Customer Title • Red_CustomerInfo.Customer_Name Red parameter: Customer First Name • Red_CustomerInfo.Customer_Surname Red parameter: Customer Last Name • Red_CustomerInfo.Customer_Email Red parameter: Customer Email Address -

value must contain @ • Red_CustomerInfo.Customer_Address Red parameter: Customer address line 1

• Red_CustomerInfo.Customer_Address2 Red parameter: Customer address line 2 • Red_CustomerInfo.Customer_City Red parameter: Customer address city • Red_CustomerInfo.Customer_StateCode Red parameter: Customer address state

code • Red_CustomerInfo.Customer_Country Red parameter: Customer Country Code -

ISO-Alpha 3 (IE: ITA) • Red_CustomerInfo.Customer_PostalCode Red parameter: Customer Post/Zip Code • Red_CustomerInfo.Customer_Phone Red parameter: Customer Phone - no spaces

• Red_ShippingInfo.Shipping_Name Red parameter: Shipping First Name • Red_ShippingInfo.Shipping_Surname Red parameter: Shipping Last Name • Red_ShippingInfo.Shipping_Email Red parameter: Shipping Email Address - value

must contain @ • Red_ShippingInfo. Shipping_Address Red parameter: Shipping address line 1 • Red_ShippingInfo.Shipping_Address2 Red parameter: Shipping address line 2 • Red_ShippingInfo.Shipping_City Red parameter: Shipping address city • Red_ShippingInfo.Shipping_StateCode Red parameter: Shipping address state

code • Red_ShippingInfo.Shipping_Country Red parameter: Shipping Country Code - ISO-

Alpha 3 • Red_ShippingInfo.Shipping_PostalCode Red parameter: Shipping Post/Zip Code • Red_ShippingInfo.Shipping_HomePhone Red parameter: Shipping Home Phone -

no spaces • Red_ShippingInfo.Shipping_MobilePhone Red parameter: Shipping Fax Phone - no

spaces • Red_ShippingInfo.Shipping_FaxPhone Red parameter: Shipping Mobile Phone • Red_ShippingInfo.Shipping_TimeToDeparture Red parameter: Shipping Time To

Departure (See RED Par. for details) • Red_BillingInfo.Billing_Id Red parameter: Billing ID • Red_BillingInfo.Billing_Name Red parameter: Billing First Name • Red_BillingInfo.Billing_Surname Red parameter: Billing Last Name • Red_BillingInfo.Billing_DateOfBirth Red parameter: Billing DoB - format: YYYY-MM-

DD • Red_BillingInfo.Billing_Email Red parameter: Billing Email Address - value must

contain @ • Red_BillingInfo.Billing_Address Red parameter: Billing address line 1 • Red_BillingInfo.Billing_Address2 Red parameter: Billing address line 2 • Red_BillingInfo.Billing_City Red parameter: Billing address city • Red_BillingInfo.Billing_StateCode Red parameter: Billing address state code • Red_BillingInfo.Billing_Country Red parameter: Billing Country Code - ISO-Alpha 3 • Red_BillingInfo.Billing_PostalCode Red parameter: Billing Post/Zip Code • Red_BillingInfo.Billing_HomePhone Red parameter: Billing Home Phone - no

spaces • Red_BillingInfo.Billing_WorkPhone Red parameter: Billing Work Phone - no spaces

• Red_BillingInfo.Billing_MobilePhone Red parameter: Billing Mobile Phone • Red_CustomerData.MerchantWebSite Red parameter: Transaction Source Website • Red_CustomerData.Customer_IPAddress Red parameter: IP of customer - Format:

nnn.nnn.nnn.nnn • Red_CustomerData.PC_FingerPrint Red parameter: PC Finger Print (See PC


Finger Print Paragraph below) • Red_CustomerData.PreviousCustomer Red parameter: Previous Customer Flag -

format Y or N • Red_CustomerData.Red_Merchant_ID Red parameter: Optional only for merchant

with a specific set of rules (Code provided by Sella) • Red_CustomerData. Red_ServiceType Red parameter: Optional only for merchant

with a specific set of rules (Code provided by Sella) • Red_CustomInfo.UserCustomData Red parameter: Custom Data Fields (Zero or

more repetitions) • Red_Items.NumberOfItems Red parameter: Required to specify the number of

repeating item tags max value 99 • Red_Items.Red_Item.Item_ProductCode Red parameter: Item Product Code • Red_Items.Red_Item.Item_StockKeepingUnit Red parameter: Item Stock Keeping

Unit • Red_Items.Red_Item.Item_Description Red parameter: Item Description • Red_Items.Red_Item.Item_Quantity Red parameter: Item quantity - 1 should be sent

as 10000 • Red_Items.Red_Item.Item_UnitCost Red parameter: Item cost amount - €5.00

should be sent as 50000 • Red_Items.Red_Item.Item_TotalCost Red parameter: Total Item Amount (item qty x

item cost amt), no decimal • Red_Items.Red_Item.Item_ShippingNumber Red parameter: Item shipping/tracking

number • Red_Items.Red_Item.Item_GiftMessage Red parameter: Item gift message • Red_Items.Red_Item.Item_PartEAN_Number Red parameter: Item Park or EAN

Number • Red_Items.Red_Item.Item_ShippingComments Red parameter: Item Shipping

Comments

The CallPagamS2S method sends GestPay all previously assigned data; GestPay checks the correspondence between data received and the configuration set within the Back Office environment, and, if these match, it will operate. If the M.O.T.O. configuration anticipates a separation between the authorisation and the settlement phase, the activity of GestPay will be limited to the authorisation request only. If, conversely, the M.O.T.O. configuration anticipates that the authorisation and the settlement phase will occur simultaneously, then GestPay will make the authorisation request and, if the response is positive, subsequently perform the settlement operation. After the CallPagamS2S method is performed, it is possible to know the outcome of the transaction by using the returned XML file: <GestPayS2S xmlns=""> <TransactionType>PAGAM</TransactionType> <TransactionResult>OK</TransactionResult> <ShopTransactionID>prova2</ShopTransactionID> <BankTransactionID>65</BankTransactionID> <AuthorizationCode>365530</AuthorizationCode> <Currency>242</Currency> <Amount>0.90</Amount> <Country>ITALIA</Country> <Buyer> <BuyerName/> <BuyerEmail/> </Buyer> <CustomInfo/> <TDLevel/>


<ErrorCode>0</ErrorCode> <ErrorDescription>Transazione correttamente effettuata</ErrorDescription> <AlertCode/> <AlertDescription/> <TransactionKey>579428899</TransactionKey> <VbV> <VbVFlag>KO</VbVFlag> <VbVBuyer/> <VbVRisp/> </VbV> <RedResponseCode/> <RedResponseDescription/> </GestPayS2S>


• First, check TransactionResult which will return a string "OK" if the transaction was authorised or a string "KO" if the transaction was not authorised.

• If TransactionResult returns "KO", by using the ErrorCode value it is then possible to know whether the failure is caused by technical problems or by a denied authorisation by the credit card network:

� If ErrorCode returns a <> 0 value, the authorization of the transaction was negative;

the returned value will be different according to the specific reason for the failure. � The ErrorDescription value will return a description (in the language set in the

Back Office environment) of the reason for the failure.

•••• If TransactionResult returns "OK", the transaction was authorised (and, if the M.O.T.O. was simultaneous, settled as well). It will be then possible to obtain further information about the transaction, using the following values:

•••• BankTransactionID to obtain the unique code assigned to the transaction by GestPay •••• AuthorizationCode to obtain the authorisation code assigned to the transaction by the

international credit card network •••• AlertCode (and the corresponding AlertDescription) in the case which Risk

Management criteria were set through BackOffice and the transaction violated one of them; if no Risk Management criteria were violated, AlertCode will be empty.

•••• CustomInfo returns the CustomInfo tag passed during the transaction •••• TDLevel Level of authentication for 3D-Secure transactions. The string may have the

value FULL or HALF •••• VBV Returns the values for VbV as follows

� VBVFalg Returns the flag Verified by Visa (OK or KO) � VBVBayer Returns the flag Full Verified by Visa transaction � VBVRisp Returns the encrypted string obtained by Visa directory

•••• REDResponseCode RED Fraud Score of the transaction or Error code if there are

problems with RED request (ACCEPT, DENY, CHALLENGE, NOSCORE, ERROR, ENETFP, ETMOUT, EIVINF)

•••• REDResponseDescription RED Description of the RedResponseCode All the other returned values can be used.


Settlement

This is the financial confirmation operation which may follow a positive authorisation. It exists only for merchants with a M.O.T.O. configuration when a separation between the authorisation and the settlement phase is anticipated. The WSs2s method to be used for this purpose is CallSettleS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required to securely identify the transaction to be settled. A transaction may be uniquely identified by the pair < Merchant code > + < Unique code assigned by GestPay to the transaction > It is however also possible to use the code assigned to the transaction by the merchant, taking care to ascertain that this code uniquely identifies a transaction; otherwise WSs2s will return an error code referring to a “Non-uniquely identified transaction”. As a transaction may also be settled for an amount which is less that the one authorised, it is necessary to assign to WSs2s also the amount to be settled and the currency code in which this amount is expressed (obviously the currency may be the same as the authorised currency). In order to do all this, it is sufficient to use all of the following specific SET methods:

• shopLogin (merchant code) • bankTransID (GestPay Transaction Identification Code) or shopTransID (Merchant

Transaction Identification Code) •••• uicCode (Currency Code: 242 = EUR) •••• amount (Amount)

Unlike the authorisation request, the settlement operation may not incur a negative result, unless this is due to technical problems. In order to know the result of this operation it is therefore sufficient to consult the technical result by reading in the XML return file the following values:

• ErrorCode (and ErrorDescription) If the settlement request will receive a negative result due to technical problems the transaction state will change to PRE and the settlement will be done automatically by GestPay the first night after the request.


Withdrawal

This is the operation by which it is possible to withdraw an authorised transaction. It may be performed only if M.O.T.O. is set with separate phases. The WSs2s web service call to use for this purpose is CallDeleteS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required to securely identify the transaction to be withdrawn. A transaction may be uniquely identified by the pair < Merchant code > + < Gestpay unique transaction code > It is however possible to use also the code assigned by the merchant to the transaction, taking care to ascertain that the code uniquely identifies the transaction; otherwise WSs2s will return an error code referring to a “Non-uniquely identified transaction”. To do so it is sufficient to use the following parameters:

• shopLogin (merchant code) • bankTransactionID (GestPay transaction code) or shopTransactionID (merchant

transaction code) Unlike the authorisation request operation, the withdrawal operation cannot incur a negative result, unless this is due to technical problems. In order to know the outcome of the operation it is therefore sufficient to consult its technical result, by reading in the XML return file the following values:

• ErrorCode (and ErrorDescription)


Reversal

This operation reverses (totally or partially) a settlement operation. From an account prospective it consists in debiting the merchant and subsequently crediting back the amount originally due to the buyer’s credit card. Obviously, it may be performed only on already-settled transactions. An already-settled transaction may also be reversed more than once, for partial amounts, until a total equal to the settled amount is reached. The correct WSs2s web service method to be used for this purpose is CallRefundS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required to securely identify the transaction to be reversed. A transaction may be uniquely identified by the pair < Merchant code > + < GestPay unique transaction code > It is however possible to use also the code assigned by the merchant to the transaction, taking care first to ascertain that the code uniquely identifies a transaction; otherwise, WSs2s will return an error code referring to a “Non-uniquely identified transaction”. As a transaction may be reversed also for an amount which is less than the amount for which the transaction was settled, it is necessary also to assign to WSs2s the amount to be withdrawn and the currency code in which the amount is expressed (obviously the currency must be the same as the settled amount). In order to do all this it is sufficient to use the specific SET methods:

• shopLogin (merchant code) • bankTransactionID (GestPay transaction code) or • shopTransactionID (merchant transaction ID code) • uicCode (currency code: 18 = ITL, 242 = EUR) • amount (amount)

Unlike the authorisation request operation, the reversal operation cannot incur a negative result, unless this is due to technical reasons. In order to know the outcome of the operation, it is therefore sufficient to consult its technical result, by reading in the XML return file the following values:

• ErrorCode (and ErrorDescription)


Transaction status query

This operation makes it possible to know the status and details of a specific transaction. The specific WSs2s web service method for this purpose is CallReadTrxS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required to securely identify the transaction whose status is required. A transaction may be uniquely identified by using the pair < Merchant Code > + < GestPay univocal transaction ID Code > It is however possible to use also the transaction code assigned by the merchant, taking care to ascertain that it uniquely identifies a transaction; otherwise WSs2s will return the “Not uniquely identified” error. To do so it is sufficient to use the following parameters:

• shopLogin (Merchant code) • bankTransactionID (GestPay transaction ID code) or • shopTransactionID (Merchant transaction ID code)

After the CallReadTrxS2S has been performed, it is possible to know the outcome of the operation by using the specific GET method:

• First the GetErrorCode method must be used (as well as the corresponding GetErrorDescription) in order to know whether the transaction has been correctly identified or not.

• If the transaction was correctly identified, it is then possible to obtain all information relevant to the transaction by reading the values in the returned XML file:

� TransactionResult to know whether the transaction was authorised (“OK” =

authorised; “KO” = not authorised) � BankTransactionID to obtain the GestPay unique transaction identification code � AuthorizationCode to obtain the authorisation code assigned to the

transaction by the international credit card network (if the transaction was authorised)

� ErrorCode (and the corresponding ErrorDescription) to know the reason for an authorisation denial (ErrorCode = 0 if the transaction was authorised)

� AlertCode (and the corresponding AlertDescription) if the Risk Management criteria were set within the Back Office environment and the transaction was in violation of one of these; if no Risk Management criteria were violated, AlertCode will return the value 0.

� Currency to know the transaction currency � BuyerName to know the name given by the buyer in the payment page � BuyerEmail to know the e-mail address given by the buyer in the payment page � AuthorizationAmount to know the amount for which the authorisation request was

made � TransactionState To know the status of the transaction. Possible values and their

meanings are as follows:

▪ AUT The authorisation request was carried out. No other operation occurred

▪ MOV The transaction was positively authorised and was subsequently settled. It may have been reversed, but only partially

▪ CAN The transaction was authorised and subsequently cancelled ▪ STO The transaction was authorised, settled and then fully reversed

� Perform a cycle on the Events values to obtain the different operations

performed on the transaction


� EventType (AUT,MOV,CAN,REQ,STO) SettledAmount to know the amount for which the transaction was settled (0 if settlement did not occur)

� EventAmount to know the amount of the relevant operation � EventDateTime to know date-hour of the relevant operation


Card verification

This operation makes it possible to check the card’s validity. It consists in sending data about the card (such as the account number and the expiration date) to the bank’s server and in receiving the result after processing by the bank’s server. The correct WSs2s web service method to use for this purpose is CallVerifyCardS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required through the valorisation of the following parameters:

• shopLogin (merchant code) • shopTransactionID (transaction identification code) • cardNumber (credit card account number) • expMonth (card expiration month) • expYear (card expiration Year) • CVV2 (String containing the Card Verification Value printed on the credit card, as

specified in the chapter "Handling of CVV field")

The CallVerifyCardS2S method sends to GestPay all previously assigned data, which GestPay uses to make a transaction request without affecting the account and return the result of the operation to WSs2s. After the CallVerifyCardS2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:

• First it is possible to use the TransactionResult method which will return the string “OK” if the transaction was authorised or the string “KO” if the transaction was not authorised.

• If TransactionResult returns the string “KO”, then it is possible to know whether the Failure was due to a negative response from the credit card network, using the ErrorCode method: � If ErrorCode returns a value which is <> 0, the transaction was denied due to

technical problems; the value returned will vary according to the specific reason for the failure. The ErrorDescription method will return a description of the reason for the failure (in the language set within the Back Office environment).

� If ErrorCode returns the value 0, the transaction did not fail due to technical problems. By using the ErrorCode it is possible to know the error code associated with the failure; the description of the error will be shown in the language set within the Back Office environment by using the ErrorDescription method.

• If TransactionResult returns the value “OK”, the transaction was authorised and the card is considered valid.


Card check

This operation makes it possible to check the card’s validity as the previous method but also a set of information regarding the card. It consists in sending data about the card (such as the account number and the expiration date) to the bank’s server and in receiving the result after processing by the bank’s server. The correct WSs2s web service method to use for this purpose is callCheckCartaS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required through the valorisation of the following parameters:

• shopLogin (merchant code) • shopTransactionID (transaction identification code) • cardNumber (credit card account number) • expMonth (card expiration month) • expYear (card expiration Year) • CVV2 (String containing the Card Verification Value printed on the credit card, as

specified in the chapter "Handling of CVV field") • withAuth flag that indicates if make a transaction request or not (the same performed

by CallVerifyCardS2S method)

The CallCheckCartaS2S method sends to GestPay all previously assigned data, if the flag withAuth is set to Y then GestPay uses these data to make a transaction request without affecting the account and return the result of the operation to WSs2s, otherwise only the information about the card are returned back. After the callCheckCartaS2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:

• First it is possible to use the TransactionResult method which will return the string “OK” if the check has been performed or the string “KO” if not. In the fields TransactionErrorCode and TransactionErrorDescription there are the detailed information in case of error.

• AuthorizationResult method which will return the string “OK” if the transaction was authorised or the string “KO” if the transaction was not authorised

• If AuthorizationResult returns the string “KO”, then it is possible to know whether the Failure was due to a negative response from the credit card network, using the AuthorizationErrorCode method: � If AuthorizationErrorCode returns a value which is <> 0, the transaction was

denied due to technical problems; the value returned will vary according to the specific reason for the failure. The AuthorizationErrorDescription method will return a description of the reason for the failure (in the language set within the Back Office environment).

� If AuthorizationErrorCode returns the value 0, the transaction did not fail due to technical problems. By using the AuthorizationErrorCode it is possible to know the error code associated with the failure; the description of the error will be shown in the language set within the Back Office environment by using the AuthorizationErrorDescription method.

• If AuthorizationResult returns the value “OK”, the transaction was authorised and the card is considered valid.

• CardCountry Returns nationality of the card • CardCountryCode Returns nationality code of the card • CheckCVV Returns results of check CVV • CheckCVVDescription Returns description of CVV check results • IssuerCountry Returns nationality of the card issuer • IssuerCountryCode Returns nationality code of the card issuer • CompanyDescription Description of the Card company • CompanyCode Code of the Company • Commercial Flag that indicates if the Card is commercial or not (Y or N) • ProductDescription Returns description of the product linked to the card (i.e. Visa


Gold) • ProductType Returns the type of product (i.e. Credit) • CheckDigit Returns OK or KO according to the check digit of the card • CheckDigitDescription Return description of the check Digit response • CheckDate Returns OK or KO according to the check date of the card • CheckDateDescription Returns description of the check date response • EnrolledCode Returns enrolment code (Y,N or U) • EnrolledDescription Returns enrolment description • Prepaid Flag that indicates if the card is prepaid or not (Y, N or empty)


Request Tokens

With "Tokenization", a merchant will be able to remotely store credit card data in GestPay archives and receive a Token in answer; the merchant will save the received Token in its system instead of the credit card data. For the next purchases, the merchants will send to GestPay the Token instead of the credit card number. GestPay will retrieve the credit card number from its archives starting from the Token and it will complete the transaction. This operation provides the generation of a new Token during a transaction passing the "requestToken" field, so they will obtain a Token in response. The correct WSs2s web service method to use for this purpose is callRequestTokens2S. A group of merchants can share a set of tokens. So if a merchant belongs to a group, it can use all the tokens of the other merchants of the same group. Merchants cannot directly define and manage groups. Groups are managed only by Banca Sella operators, who will take care of the requests coming from merchants. The available options are: - add a merchant to a group, and take in the group all the tokens previously created by the merchant - add a merchant to a group without taking in the group the tokens previously created by the merchant, only those created since that moment will belong to the group - remove a merchant from a group and remove all its tokens from the group - remove a merchant from a group leaving in the group all its tokens; the new token created by the merchant since its exclusion from the group will be accessible only by that merchant Before using this method,merchants must assign to WSs2s all of the required information, through the following parameters:

• shopLogin (merchant code) • requestToken (“MASKEDPAN” for a Standard Token any other value for Custom

Token) • cardNumber (credit card account number) • expMonth (card expiration month) • expYear (card expiration Year) • cvv (String containing the Card Verification Value printed on the credit card, as

specified in the chapter "Handling of CVV field") • withAuth flag that indicates if make a transaction request or not (the same performed

by CallVerifyCardS2S method)

The callRequestTokens2S method sends to GestPay all previously assigned data, if the flag withAuth is set to Y then GestPay uses these data to make a transaction request without affecting the account and return the result of the operation to WSs2s, otherwise only the information about the card are returned back. After the callRequestTokens2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:

• First it is possible to use the TransactionResult method which will return the string “OK” if the check has been performed or the string “KO” if not. In the fields TransactionErrorCode and TransactionErrorDescription there are the detailed information in case of error.

• AuthorizationResult method which will return the string “OK” if the transaction was authorised or the string “KO” if the transaction was not authorised


• If AuthorizationResult returns the string “KO”, then it is possible to know whether the Failure was due to a negative response from the credit card network, using the AuthorizationErrorCode method: � If AuthorizationErrorCode returns a value which is <> 0, the transaction was

denied due to technical problems; the value returned will vary according to the specific reason for the failure. The AuthorizationErrorDescription method will return a description of the reason for the failure (in the language set within the Back Office environment).

� If AuthorizationErrorCode returns the value 0, the transaction did not fail due to technical problems. By using the AuthorizationErrorCode it is possible to know the error code associated with the failure; the description of the error will be shown in the language set within the Back Office environment by using the AuthorizationErrorDescription method.

• If AuthorizationResult returns the value “OK”, the transaction was authorised and the card is considered valid.

• CardCountry Returns nationality of the card • CardCountryCode Returns nationality code of the card • CheckCVV Returns results of check CVV • CheckCVVDescription Returns description of CVV check results • IssuerCountry Returns nationality of the card issuer • IssuerCountryCode Returns nationality code of the card issuer • CompanyDescription Description of the Card company • CompanyCode Code of the Company • Commercial Flag that indicates if the Card is commercial or not (Y or N) • ProductDescription Returns description of the product linked to the card (i.e. Visa

Gold) • ProductType Returns the type of product (i.e. Credit) • CheckDigit Returns OK or KO according to the check digit of the card • CheckDigitDescription Return description of the check Digit response • CheckDate Returns OK or KO according to the check date of the card • CheckDateDescription Returns description of the check date response • EnrolledCode Returns enrolment code (Y,N or U) • EnrolledDescription Returns enrolment description • Prepaid Flag that indicates if the card is prepaid or not (Y, N or empty)


Delete Tokens

The method of WSs2s web service that merchants must use in order to delete a token from GestPay is callDeleteTokenS2S. Merchants belonging to a group are allowed to delete also tokens created by other merchants of the same group. Before using this method,merchants must assign to WSs2s all of the required information, through the following parameters:

• shopLogin (merchant code) • TokenValue (Token associated to a Credit Card)

The callDeleteTokenS2S method sends to GestPay a token to delete After the callDeleteTokenS2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:

• First it is possible to use the TransactionResult method which will return the string “OK” if the check has been performed or the string “KO” if not.

• ErrorCode Returns error code • ErrorDescription Returns error description


Update Tokens

The method of WSs2s web service that merchants must use in order to update a token in GestPay is callDeleteTokenS2S. Merchants belonging to a group are allowed to update also tokens created by other merchants of the same group. Before using this method,merchants must assign to WSs2s all of the required information, through the following parameters:

• shopLogin (merchant code) • TokenValue (Token associated to a Credit Card) • expMonth (card expiration month) • expYear (card expiration Year) • withAuth flag that indicates if make a transaction request or not (the same performed

by CallVerifyCardS2S method) The callUpdateTokenS2S method sends to GestPay a token to update After the callupdateTokenS2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:


• ErrorCode Returns error code • ErrorDescription Returns error description


Ideal List

To retrieve the Ideal Bank List the correct WSs2s web service method to use for this purpose is callIdealListS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required through the valorisation of the following parameters:

• shopLogin (merchant code) The callIdealListS2S method retrieves from GestPay the Ideal Bank List After the callIdealListS2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:


• ErrorCode Returns error code • ErrorDescription Returns error description • BankList Returns a list of banks splits into Bank nodes. Each bank node has two

elements: � BankCode Returns the Bank Code � BankName Returns the Bank Name

<callIdealListS2SResult xmlns=""> <GestPayS2S> <TransactionType>IdealList</TransactionType> <TransactionResult>OK</TransactionResult> <ErrorCode>0</ErrorCode> <ErrorDescription>Transazione correttamente effettuata</ErrorDescription> <BankList> <Bank> <BankCode>ABNANL2A</BankCode> <BankName>ABN Amro</BankName> </Bank> <Bank> <BankCode>FRBKNL2L</BankCode> <BankName>Friesland Bank</BankName> </Bank> <Bank> <BankCode>INGBNL2A</BankCode> <BankName>ING</BankName> </Bank> .... </BankList> </GestPayS2S> </callIdealListS2SResult>


MyBank List

To retrieve the MyBank Bank List the correct WSs2s web service method to use for this purpose is callMyBankListS2S. However, before using this method, it is necessary to assign to WSs2s all of the information required through the valorisation of the following parameters:

• shopLogin (merchant code) • languageID Id of the language of the Bank List

� 1 Italiano � 2 English � 3 Espanol � 4 Francais � 5 German

The callMyBankListS2S method retrieves from GestPay the MyBank Bank List After the callMyBankListS2S method has been performed, it is possible to know the outcome of the operation by using the values in the relevant XML return:


• ErrorCode Returns error code • ErrorDescription Returns error description • BankList Returns a list of banks splits into Bank nodes. Each bank node has two

elements: � BankCode Returns the Bank Code � BankName Returns the Bank Name

<callMyBankS2SResult xmlns=""> <GestPayS2S> <TransactionType>MyBank</TransactionType> <TransactionResult>OK</TransactionResult> <ErrorCode>0</ErrorCode> <ErrorDescription>Transazione correttamente effettuata</ErrorDescription> <BankList> <Bank> <BankCode>CT000125</BankCode> <BankName>ALLIANZ BANK F.A. S.P.A.</BankName> </Bank> <Bank> <BankCode>CT000038</BankCode> <BankName>ALLIANZ BANK FINANCIAL ADVISORS SPA</BankName> </Bank> <Bank> <BankCode>CT000137</BankCode> <BankName>ALTO ADIGE BANCA - SUEDTIROL BANK</BankName> </Bank> <Bank> <BankCode>CT000084</BankCode> <BankName>BANCA ALTO VICENTINO</BankName> </Bank> ..... </BankList> </GestPayS2S> </callMyBankS2SResult>


3D-secure Transactions

Transactions made with credit cards, if the merchant is registered with the 3D-Secure service, ensure that the cardholder cannot renounce the transaction. There are two main cases:

• Transactions made with non 3D-Secure cards involving merchants with 3D-Secure authorisation

• Transactions made with 3D-Secure cards involving merchants with 3D-Secure authorisation

Transactions made with non 3D-Secure cards

From a functional perspective the transaction is processed as a normal authorisation request. 3D-Secure transactions are characterised by a flag (whose value is OK or KO) which is readable by means of the VbV method contained in the XML return

Transactions made with 3D-Secure cards Transactions made with 3D-Secure credit cards require cardholder authentication. The buyer is redirected to the card issuer’s website and must enter the password with which he/she provided the issuer. If the outcome of the authentication process is positive, the transaction may proceed and generate a positive or negative outcome according to the response of the international credit card network. In functional terms the process consists of 3 phases: Phase I: authorisation request A standard authorisation request is made. If the card is recognised as 3D, the outcome of the request is a specific error code (8006) which is readable by means of the ErrorCode method. The error description (Verified By Visa) will be readable by means of the ErrorDescription method. In this phase the following additional information is also shown. This information is required during the payment process and is specific to Verified by Visa transactions. In particular it is necessary to acquire the transaction code, which can be read by means of the TransKey method and an encrypted string to be used during the subsequent phase and which is readable by means of the VbVRisp value, which is as well in the XML return.

Phase II: cardholder authentication In this phase it is necessary to allow the buyer to authenticate him/herself to the credit card issuer. The buyer’s browser must be redirected to a specific page on the Banca Sella website which will act as an interface for authentication and to direct the buyer to the issuer’s site, providing him/her with all of the information required for authentication. The page to be retrieved has the following URL:

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

for test codes

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

The page must be retrieved through the following 3 parameters: a shopLogin b an encrypted string acquired in the previous phase through GetVbVRisp c the URL of the merchant’s web site to which the buyer must be redirected after the

authentication procedure


Any additional parameters will not be returned in the response to the second call. It is therefore advisable to store them in specifically created variables during Phase I.

An example of an html form for redirection could be:

<html> <body>

<form action="https://ecomm.sella.it/pagam/pagam3d.aspx" method="post"> <input type="hidden" name="a" value="9000001"> <input type="hidden" name="b" value="dffbihuihiuhe656erh12t5"> <input type="hidden" name="c" value="http://www.sitoesercente.it/rientro.asp"> <input type="submit" value=" authentication">

</form> </body>

</html>

At the end of the authentication process the buyer will be redirected to the merchant’s site to the URL specified as redirection parameter c. The merchant’s page for welcoming back the buyer after authentication will be retrieved by means of a PARES parameter (an encrypted string containing the result of authentication) which must be acquired by the merchant and forwarded to Banca Sella during the following phase.

Phase III: conclusion of transaction At this stage the merchant is in possession of all of the information required to conclude the transaction. A new authorisation request must be made (by using the CallPagamS2S method). However, before using again such call, it is necessary to assign to WSs2s all of the information required by providing the variables:

• shopLogin (merchant code) • uicCode (currency code) • amount (amount) • shopTransactionID (transaction identification code) • transKey (transaction ID acquired during Phase I) • PARes (encrypted string containing the result of authentication acquired during Phase

II) The result of the transaction displayed by Gestpay will be interpreted as depicted in the Authorisation Request section.


CVV field handling

In this document we shall call CVV the 3- or 4-figure number printed on the credit card. It is called different names according to card issuing company (CVV2 for Visa, 4DBC for American Express, CVC2 for Mastercard). In all cases it is a number used to increase the security of payments, as it reduces the chance of the credit card being used by someone who is not in possession of it. In order to carry out transactions while also sending the CVV field, it is enough to perform the following operations:

1) Ask the bank to activate the CVV service for the companies desired (or for all companies). This operation needs to be carried out once only (it is repeatable for other companies if the request to activate the service was made for only some of them).

2) Configure the CVV field as a "PARAMETER" in the "Fields & Parameters" section of the Back Office environment (BackOffice->PaymentPage->Fields&Parameters), with regard to the public page.

Once the list of fields that make up the page has been displayed, simply click on the name of the field ("Cvv") to access the detail window of the field itself. Here simply activate the "Parameter" check box and confirm the change.

For pages created before 2005, the CVV field may not be present. In this case it is necessary to contact the technical support centre to obtain the creation of a new page, identical to the previous one, with the addition of the CVV field. At this point it is possible to configure the field as a "PARAMETER".

Please note: the page must always be published to make the changes effective.

3) At this point, for cards belonging to companies for which the service has been activated, transactions containing the CVV can be performed in the same way as transactions without CVV, with the exception of the fact that it is necessary to communicate to the WSs2s web service the value of the number setting the variable CVV value


Payment orders in test environment Remember that to simulate the authorisation 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.


Table of Country RED Codes

The list of Country Code in ISO 3 digit format. This is only an example it's not exhaustive of the actual standard.

ISO Code 3 digit Country ABW ARUBA AFG AFGHANISTAN AGO ANGOLA AIA ANGUILLA ALA Isole Åland ALB ALBANIA AND ANDORRA ANT NETHERLAND ANTILLES ARE UNITED ARAB EMIRATES ARG ARGENTINA ARM ARMENIA ASM AMERICAN SAMOA ATA ANTARTIDE ATF TERRITORI FRANCESI DEL SUD ATG ANTIGUA AND BARBUDA AUS AUSTRALIA AUT AUSTRIA AZE AZERBAIJAN BDI BURUNDI BEL BELGIO BEN BENIN BES Isole BES BFA BURKINO FASO BGD BANGLADESH BGR BULGARIA BHR BAHRAIN BHS BAHAMAS BIH BOSNIA HERZEGOVINA BLM Saint-Barthélemy BLR BELARUS BLZ BELIZE BMU BERMUDA BOL BOLIVIA BRA BRASILE BRB BARBADOS BRN BRUNEI DARUSSALAM BTN BHUTAN BVT ISOLA DI BOUVET BWA BOTSWANA CAF REPUBBLICA CENTROAFRICANA CAN CANADA CCK ISOLE COCOS CHE SVIZZERA CHL CILE CHN CINA CIV COTE D.IVOIRE


ISO Code 3 digit Country CMR CAMEROON,UNITED REP. COD ZAIRE COG CONGO COK COOK ISLANDS COL COLOMBIA COM COMORE CPV CAPE VERDE IS. CRI COSTA RICA CUB CUBA CUW CURACAO CXR ISOLA DI NATALE CYM CAYMAN ISLANDS CYP CYPRUS CZE REPUBBLICA CECA DEU GERMANIA DJI GIBUTI DMA DOMINICA DNK DENMARK DOM REPUBBLICA DOMINICANA DZA ALGERIA ECU ECUADOR EGY EGITTO ERI ERITREA ESH SAHARA OCCIDENTALE ESP SPAGNA EST ESTONIA ETH ETHIOPIA FIN FINLANDIA FJI FIJI FLK ISOLE FALKLAND FRA FRANCIA FRO ISOLE FAROE FSM STATI FEDERATI DELLA MICRONESIA GAB GABON GBR GRAN BRETAGNA GEO GEORGIA GGY Guernsey GHA GHANA GIB GIBRALTAR GIN GUINEA GLP GUADALUPA GMB GAMBIA GNB GUINEA-BISSAU GNQ GUINEA EQUATORIALE GRC GREECE GRD GRENADA GRL GROENLANDIA GTM GUATEMALA GUF GUYANA FRANCESE GUM GUAM


ISO Code 3 digit Country GUY GUYANA HKG HONG KONG HMD ISOLA HEARD E ISOLE MCDONALD HND HONDURAS HRV CROAZIA HTI HAITI HUN HUNGARY IDN INDONESIA IMN ISOLA DI MAN IND INDIA IOT Territorio Britannico Oceano Indiano IRL IRELAND IRN IRAN IRQ IRAQ ISL ICELAND ISR ISRAEL ITA ITALIA JAM JAMAICA JEY Jersey JOR JORDAN JPN JAPAN KAZ KAZAKHSTAN KEN KENYA KGZ KYRGYZSTAN KHM KAMPUCHEA DEMOCRATIC KIR KIRIBATI KNA ST. KITTS-NEVIS KOR KOREA, REPUBLIC OF KWT KUWAIT LAO LAO PEOPLES DEMOCRATIC REPUBLIC LBN LIBANO LBR LIBERIA LBY LIBIA LCA SAINT LUCIA LIE LIECHTENSTEIN LKA SRI LANKA LSO LESOTHO LTU LITUANIA LUX LUSSEMBURGO LVA LATVIA MAC MACAU MAF Saint-Martin MAR MAROCCO MCO MONACO MDA MOLDOVA, REP. OF MDG MADAGASCAR MDV MALDIVES MEX MEXICO MHL ISOLE MARSHALL MKD MACEDONIA


ISO Code 3 digit Country MLI MALI MLT MALTA MMR MYANMAR MNE REPUBLIC OF MONTENEGRO MNG MONGOLIA MNP ISOLE MARIANNE SETTENTRIONALI MOZ MOZAMBIQUE MRT MAURITANIA MSR MONTSERRAT MTQ MARTINICA MUS MAURITIUS MWI MALAWI MYS MALAYSIA MYT MAYOTTE NAM NAMIBIA NCL NUOVA CALEDONIA NER NIGER NFK ISOLA NORFOLK NGA NIGERIA NIC NICARAGUA NIU NIUE NLD NETHERLANDS NOR NORWAY NPL NEPAL NRU NAURU NZL NEW ZEALAND OMN OMAN PAK PAKISTAN PAN PANAMA PCN PITCAIRN PER PERU PHL PHILIPPINES PLW PALAU PNG PAPUA NEW GUINEA POL POLONIA PRI PUERTO RICO PRK COREA DEL NORD PRT PORTOGALLO PRY PARAGUAY PSE PALESTINA PYF POLINESIA FRANCESE QAT QATAR REU REUNION ROU ROMANIA RUS RUSSIA RWA RUANDA SAU SAUDI ARABIA SCG SERBIA E MONTENEGRO SDN SUDAN SEN SENEGAL


ISO Code 3 digit Country SGP SINGAPORE SGS SUD GEORGIA E ISOLE SANDWICH SHN SANT'ELENA SJM SVALBARD E JAN MAYEN SLB SOLOMON ISLANDS SLE SIERRA LEONE SLV EL SALVADOR SMR SAN MARINO SOM SOMALIA SPM SAINT PIERRE E MIQUELON SRB SERBIA AND MONTENEGRO SSD Sudan del Sud STP SAO TOME E PRINCIPE SUR SURINAME SVK SLOVAK REPUBLIC SVN SLOVENIA SWE SVEZIA SWZ SWAZILAND SXM SINT MAARTEN (DUTCH) SYC SEYCHELLES SYR SYRIAN ARAB REPUBLIC TCA TURKS AND CAICOS ISLANDS TCD CIAD TGO TOGO THA THAILAND TJK TAJIKISTAN TKL TOKELAU TKM TURKMENISTAN TLS TIMOR EST TON TONGA TTO TRINIDAD AND TOBAGO TUN TUNISIA TUR TURCHIA TUV TUVALU TWN TAIWAN PROVINCE OF CHINA TZA TANZANIA, UNITED REPUBLIC OF UGA UGANDA UKR UKRAINE UMI ISOLE MINORI DEGLI STATI UNITI

D'AMERICA UNK UN INT ADMIN MISSION IN KOSOVO URY URUGUAY USA STATI UNITI UZB UZBEKISTAN VAT VATICAN CITY STATE (HOLY SEE) VCT SAINT VINCENT AND GRENADINES VEN VENEZUELA VGB VIRGIN ISLANDS BRITISH VIR VIRGIN ISLANDS U.S. VNM VIET NAM


ISO Code 3 digit Country VUT VANUATU WLF WALLIS E FUTUNA WSM SAMOA YEM YEMEN ZAF SUD AFRICA ZMB ZAMBIA ZWE ZIMBABWE


Software Requirements

GestPay applies TSL1.1 protocol or latest. However, the system has to be updated to the last security patch, so it's mandatory to verify the compatibility in the test environment. GestPay's domains are associated with a 256-bit SHA-2 and extended versions SSL digital certificates issued by Verising.


Links

More info at https://www.gestpay.it/ Get a test code https://www.gestpay.it/gestpay/index.jsp#area-sviluppatori Back Office environment for actual merchants https://ecomm.sella.it/backoffice Back Office environment for test merchants https://testecomm.sella.it/backoffice Support call +39 015.24.34.640 from Monday to Friday from 8.00 AM to 06:00 PM send an email to [email protected] technical forum https://forum.sella.it/spazioaperto/forums/show/11602.page

gestpay: wss2s web service technical specifications · gestpay: wss2s web service technical...

Documents