Installing the SFA JAVA Library
Pre-requisites –
1. The Merchant's machine where SFA will be installed should have JDK1.3 installed.
2. The Merchant must possess the key file generated by the Payment Gateway
(available in the zip as 00001003.key). The file name should not be changed, where
00001003 is the merchant ID.
Steps for obtaining the key file –
1. Login into the Merchant Web Interface using the Merchant Super User login.
2. Click on the link “Personalize>> Key Download”
3. Save the “.key” file sent by the Payment Gateway in a local folder.
Note – The key file can be downloaded only once. Please keep the key file in a
secure location. Contact PG System Administrator in case the key file needs to be
regenerated.
The JAVA SFA comes bundled as 2 zip files
-1. SFAClient.zip - This zip file contains the components, which provide the core SFA
functionality and test pages
2. SFA_Dependencies.zip - This zip file contains the components that are required for
the SFA to function
The installation process for SFA_Dependencies.zip is as follows –
1. Copy the ZIP file to a temporary location on the Merchant site
2. The zip has the following files
1) cryptix32.jar – Required by SFA to encrypt the data sent to the ePG
2) jcert.jar – Required to establish the SSL connection with ePG
3) jnet.jar – Required to establish the SSL connection with ePG
4) jsse.jar – Required to establish the SSL connection with ePG
5) Servlet.jar – HTTP Request/Response handling
3. Copy the folder to a desired location (folder path names should not have spaces).
4. Set the Jar files in the system classpath (classpath must contain the absolute path
to the jar files with the names of the jar files included)
The Installation process for SFAClient.zip is as follows
-1. Copy the ZIP file to a temporary location on the Merchant site
2. Unzipping shall create a folder called SFAClient.
3. SFAClient contains the following files/directories
1. sfa.jar – SFA Client library (contains a sfa.properties file and a set of class files)
2. TestPages – Sample pages
4. Editing the sfa.properties file
a. Open the file sfa.jar using WINZIP. Open the sfa.properties file.
Note - If WINZIP or a similar facility is not available on the
machine then the following java command can be used for
extracting the properties file
Jar -xvf sfa.jar
To jar the file again use,
Jar -cvf sfa.jar com sfa.properties
b. For the parameter 'Key.Directory' in the properties file set the name of the
folder, which contains the merchant key. A trailing slash has to be put at the
end of this value. The name of the file need not be set. Save the file after
making other relevant changes.
c.
For the parameter “traceLog”, set the name of the folder to which sfa logs needs
to be written.
It shall point to a folder to which write permissions are avail
able to java.
d. Enable the verbose parameter to “true” only when necessary as the log gen
erated might be considerable depending on the number of transactions.
e. To verify the success of the above operations open the jar file again and
check if the properties file has the values set.
5. Copy the sfa.jar to any desired folder (folder path names should not have spaces).
6. Set the sfa.jar in the system classpath (classpath must contain the absolute path to
the jar files with the names of the jar files included).
The Merchants jsp pages can now start using the SFA library. Test pages are shipped
along with the distribution, which can be used for test/understanding purposes.
Note:
1. The verbose parameter in sfa.properties should be set to true only when need
ed.
Setting the java keystore for SSL communications
1. It is necessary to import the public certificates of Payment Gateway’s Intermediate
CA and Root CA into the keystore of the JDK so that the SSL communication can be
facilitated. Get the appropriate certificates from PG Administrator.
a. Import the Root CA.
keytool -import -trustcacerts -alias pgRootCA -file $CERT_LOCATION$\epgRootca.cer -keystore $JAVA_HOME$\jre\lib\security\cacerts -storepass changeit
Where,
$CERT_LOCATION$ is the location of the cert file
$JAVA_HOME$ refers to the folder in which the JDK is installed
The directory delimiter "\" must be changed as per the Operating System
b. A message is displayed on the console "Trust this certificate? [no]:" Type 'y'.
c. A message "Certificate was added to keystore" should be displayed indicat
d. Similarly import the intermediate ca certificate.
Note:
1. The certificate import step assumes that the Merchant is using the SUN JVM. If
a JVM other than the SUN JVM is used, then the above step must be altered
accordingly to import the certificates so that SSL communication can be estab
lished
Appendix A
What’s in This Appendix?
The MOTO and the SSL Merchant’s use the Store Front Adaptor for integrating with the
Payment Gateway. This appendix details the data that is passed from the Merchant to
the Payment Gateway via the Store Front Adaptor.
The following sections define the various parameters and their definitions.
Note -
1. The information provided in the section “VBV fields for MOTO Merchants” and
“VBV fields for SSL Merchant” are applicable only to the Merchants enrolled for
MPI. For MOTO merchants who support MPI, it is mandatory to send the data re
ceived from the MPI to the Payment Gateway.
2. In case of the SSL Merchant, the Card details will be accepted by the Payment
Gateway. Hence, the Object mapping to the Card details mentioned below need
not be populated.
Merchant Information
Function Name - setMerchantDetails
Sr No Parameter Details Valid values Mandatory
1 astrMerchantID ID assigned by the Payment Gateway to the Merchant Data with maximum size of 8 characters Y 2 astrVendor Same as Merchant ID
Data with maximum size of 8
characters N
3 astrPartner Same as merchant ID
Data with maximum size of 8
characters N
4 astrCustIPAddress
Corresponds to the IP Address of the Customer. In case of a SSL merchant this data will be captured by the Payment Gateway. However, a MOTO merchant has to pass this data to the Payment Gateway. This data is mandatory for a MOTO merchant and non-mandatory for the SSL
merchant Data with maximum size of 20 characters N (for SSL)Y (for MOTO)
5 astrMerchantTxnID
Transaction number generated by the Merchant for reference. Root Transactions should have unique Transaction Reference Number.
Alpha-numeric data with maximum size of 50
characters Y
6 astrOrderReferenceNo
Order number generated by the Merchant for his/her reference.
Alpha-numeric data with maximum size of 30
characters N
7 astrRespURL
URL of the Merchants site on which the Payment Gateway must post the results of the transaction. This parameter is valid only in case of a SSL merchant The MOTO merchant always receives the response via the PGResponse Object
Data with maximum size of 80 characters
Y (for SSL merchants only)
8 astrRespMethod
HTTP method (GET/POST) to be used by the Payment Gateway for posting the results of the transaction to the Merchants site. In case of SSL Merchants the value should be POST as the response is sent via a redirection.
Data with maximum size of 4 characters. (GET/POST) Y
9 astrCurrCode Currency of the transaction
Data with maximum size of 3 characters. ISO Alpha Currency Code
‘INR’ for transactions in
Rupees. Y
10 astrInvoiceNo Invoice number generated by the Merchants application
Alpha-numeric data with maximum size of 20
Sr No Parameter Details Valid values Mandatory
11 astrMessageType Indicates the type of transaction. This field can contain either of the values mentioned in the adjacent field
Data with maximum size of 20 characters.
req.Preauthorization
req.Sale Y
12 astrAmount Amount of the transaction
Numeric with maximum size of 15 digits. Maximum exponent is 5.For example, maximum possible data in the amount field can be 999999999999999.99999 Y 13 astrGMTOffset GMT Time Offset of the Merchants sites locale
Data with maximum size of 9 characters
Format: GMT+hh:mm N 14 astrExt1
Additional fields provided to the Merchant for passing any specific data
Data with maximum size of
50 characters N
15 astrExt2
Additional field provided to the Merchant for passing any specific data. To be filled in as “true” by SSL merchant
Data with maximum size of
50 characters N
16 astrExt3 Reserved Data with maximum size of 50 characters N 17 astrExt4
Additional field provided to the Merchant for passing any specific data
Data with maximum size of
50 characters N
18 astrExt5
Additional field provided to the Merchant for passing any specific data
Data with maximum size of
50 characters N
Function Name - setMerchantRelatedTxnDetails
Sr No Parameter Details Valid values Mandatory
1 astrMerchantID ID assigned by the Payment Gateway to the Merchant
Data with maximum size of 8 characters. Id given to the Merchant for identification by
the PG Y
2 astrVendor Same as Merchant ID Data with maximum size of 8 characters. N
3 astrPartner Same as Merchant ID
Data with maximum size of 8
characters. N
4 astrMerchantTxnID
Transaction number generated by the Merchant for reference.
Alpha-numeric data with maximum size of 50
characters. Y
5 astrRootTxnSysRefNum
Transaction reference number generated by the Payment Gateway for the original transaction and sent to the merchant. Example, for an Authorization transaction the Root Transaction System reference of Pre-Authorization needs to be given. Similarly, for a Refund transaction the Root Transaction System reference of Authorization needs to be given
Numeric data with maximum size of 15 characters Y
6 astrRootPNRef
RRN number sent by the Payment Gateway to the merchant for the original transaction. Example, for an Authorization transaction the RRN of Pre-Authorization needs to be given. Similarly, for a Refund transaction the
Sr No Parameter Details Valid values Mandatory
7 astrRootAuthCode
Auth Code sent by the Payment Gateway to the merchant for the original transaction
Numeric data with maximum size of 6 characters Y
8 astrCurrCode Currency of the transaction
Data with maximum size of 3 characters. ISO Alpha Currency Code.
‘INR’ for transactions in
Rupees Y
9 astrMessageType
Indicates the type of transaction. This field can contain either of the values mentioned in the adjacent field
Data with maximum size of 20 characters.
req.Refund
req.Authorization Y
10 astrAmount Amount of the transaction
Numeric with maximum size of 15 digits. Maximum exponent is 5.For example, maximum possible data in the amount field can be 999999999999999.99999 Y
11 astrGMTOffset GMT Time Offset of the Merchants sites locale
Data with maximum size of 9 characters.
GMT+hh:mm N
12 astrExt1
Additional fields provided to the Merchant for passing any specific data
Data with maximum size of
50 characters N
13 astrExt2 Additional field provided to the Merchant for passing any specific data Data with maximum size of 50 characters N 14 astrExt3
Additional field provided to the Merchant for passing any specific data
Data with maximum size of
50 characters N
15 astrExt4
Additional field provided to the Merchant for passing any specific data
Data with maximum size of
50 characters N
16 astrExt5
Additional field provided to the Merchant for passing any specific data
Data with maximum size of
Card Information
Function Name - setCardDetails
Sr No Field Details Valid values Mandatory
1 astrCardType
Data with maximum size of 5 characters. VISA –Visa
MC- MasterCard Y
2 astrCardNum Numeric data with maximum size of 20 Y
3 astrCVVNum
AlphaNumeric data with maximum size of 5. For VISA,This field should contain the value in the following format
CVVNum $ Presence Indicator
Where CVVNum is a CVV value Presence indicator is one of the following 1 – CVV2 value is present
2 – CVV2 value is on the Card, but is illegible 9 – Cardholder states CVV2 is not present on the Card
e.g 010$1, 011$2 , $9
Y 4 astrExpDtYr yyyy Data with maximum size of 4 characters. Y 5 astrExpDtMon mm Data with maximum size of 2 characters. Y 6 astrNameOnCard
Alphabetic data with maximum size of 80
characters N
7 astrInstrType
Mode of payment - Credit/ Debit
Data with maximum size of 5 characters. CREDI - For credit cards
Ship To Address
Function Name - setAddressDetails
The Payment Gateway will store the Ship To Address details in its database only if all the details mentioned as mandatory are populated. If the merchant is not capturing the Address then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory
Sr No Field Details Valid values Mandatory
1 astrAddrLine1 Alphabetic data with maximum size of 50 characters Y 2 astrAddrLine2 Alphabetic data with maximum size of 50 characters N 3 astrAddrLine3 Alphabetic data with maximum size of 50 characters N 4 astrCity Alphabetic data with maximum size of 30 characters Y 5 astrState Alphabetic data with maximum size of 30 characters Y 6 astrZip Numeric data with maximum size of 10 digits Y 7 astrCountryAlphaCode Alphabetic data with maximum size of 3 characters IND for INDIA Y
8 astrEmail
Alpha-Numeric data with maximum size of 80
characters N
Bill To Address
Function Name - setAddressDetails
The Payment Gateway will store the Ship To Address details in its database only if all the details mentioned as mandatory are populated. If the merchant is not capturing the Address then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory
Sr No Field Details Valid values Mandatory
1 astrCustomerId
If customer is a registered customer with the merchant, then his ID needs to be populated in this field.
Data with maximum size of 10
characters N
2 astrCustomerName Data with maximum size of 80 characters N
3 astrAddrLine1
Alphabetic data with maximum size
of 50 characters Y
4 astrAddrLine2
Alphabetic data with maximum size
of 50 characters N
5 astrAddrLine3
Alphabetic data with maximum size
of 50 characters N
6 astrCity
Alphabetic data with maximum size
of 30 characters Y
7 astrState
Alphabetic data with maximum size
of 30 characters Y
8 astrZip
Numeric data with maximum size of
10 digits Y
9 astrCountryAlphaCode
Alphabetic data with maximum size of 3 characters
IND for India Y
10 astrEmail
Alpha-Numeric data with maximum size of 80 characters N
Customer Details (required for FDMS)
Function Name - setCustomerDetails
Customer information is sent to the Fraud Detection system for risk verification. If the merchant is not capturing the said details, then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory
Sr No Field Details Valid values Mandatory
1 strFirstName Alphabetic data with maximum size of 50 characters Y 2 strLastName
Alphabetic data with maximum size of 50
characters N
3 OfficeAddress Object of Address Type N
4 HomeAddress Object of Address Type N
5 MobileNo Numeric data passed as string. Max length of 15 N 6 Registration Date
yyyy-mm-dd
Alphabetic data with maximum length of 10
characters N
7 BillingShippingAddrMatch Y or N Alphabetic data with maximum size of 1 characters. Y
Address (for Home/Office address details)
Function Name - setAddressDetails
Home and Office address details are sent to the Fraud Detection system for risk verification. If the merchant is not capturing the Address details, then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory
Sr No Field Details Valid values Mandatory
1 astrAddrLine1 Alphabetic data with maximum size of 50 characters Y 2 astrAddrLine2 Alphabetic data with maximum size of 50 characters N 3 astrAddrLine3 Alphabetic data with maximum size of 50 characters N 4 astrCity Alphabetic data with maximum size of 30 characters Y 5 astrState Alphabetic data with maximum size of 30 characters Y
6 astrZip
Numeric data passed as string with maximum size of
10 digits Y
7 astrCountryAlphaCode
Alphabetic data with maximum size of 3 characters
IND for INDIA Y
Session Information
Function Name - setSessionDetails
Session information is sent to the Fraud Detection system for risk verification. The details have to be captured by the merchant if the merchant wishes to run the transaction through the FDMS system. In case the merchant is not capturing the details, then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory
Sr No Field Details Valid values Mandatory
1 strRemoteAddr IP Address of the system from where the end customer is performing the transaction. Y
2 strCookie The value stored in the cookie named “vsc”
Alphabetic data with maximum size of 50
characters N
3 strBrowserCountry
Alphabetic data with maximum size of 50
characters N
4 strBroswerLanguage
Alphabetic data with maximum size of 16
characters Y
5
strBroswerLocalLangu ageVariant
Alphabetic data with maximum size of 30
characters N
6 strUserAgent
Alphabetic data with maximum size of 30
characters Y
Merchandise Information
Function Name - setMerchanDiseDetails
Merchandise information is sent to the Fraud Detection system for risk verification. The details along with Session, customer information are used by the FDMS for risk verification. In case the merchant is not capturing the details, then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory. In case the purchased goods is related to Airline ticket, then this object need not be filled in and can be passed as null to the SFA. Instead the Airline details needs to be filled by the merchant.
Sr No Field Details Valid values Mandatory
1 strItemPurchased
e.g., Computer,
Shirts, Alphabetic data with maximum size of 24 Y 2 Quantity
Numeric data passed as string with maximum
length of 3 Y
3 strBrand
Alphabetic data with maximum size of 24
characters N
4 strModelNumber
Alphabetic data with maximum size of 24
characters N
5 strBuyer’s Name
Alphabetic data with maximum size of 32
characters N 6 MatchingCardBuyerName Flag indicating whether CardName and BuyerName Matches Y or N
Alphabetic data with maximum size of 1
Airline Transaction Information
Function Name - setAirLineTransactionDetails
Airline transaction information is sent to the Fraud Detection system for risk verification. The details along with Session, customer information are used by the FDMS for risk verification. In case the merchant is not capturing the details, then this object can be passed as null to the SFA. However, if the Class is instantiated and passed to the SFA, then it is necessary to populate the fields marked as mandatory. In case the purchased goods is related to merchandise, then this object need not be filled in and can be passed as null to the SFA. Instead the merchandise details needs to be filled by the merchant.
Sr No Field Details Valid values Mandatory
1 strBookingDate yyyy-mm-dd Alphabetic data with maximum size of 10 Y 2 strFlightDate yyyy-mm-dd Alphabetic data with maximum size of 10 Y 3 strFlightTime
Hh:mm (24 hr format)
Alphabetic data with maximum size of 5
characters Y
4 strFlightNo
Alphabetic data with maximum size of 12
characters Y
5 strPassengerName
Alphabetic data with maximum size of 32
characters Y
6 NoOfTickets
Numeric data passed as string with maximum length of 2 characters N
7 MatchingCardBuyerName
Flag indicating whether Card Name and Buyer Name Matches Y or N
Alphabetic data with maximum size of 1
characters N
8 strPNR Alphabetic data with maximum size of 24 Y
9 strSectorFrom Alphabetic data with maximum size of 24 Y 10 strSectorTo Alphabetic data with maximum size of 24 Y
VBV Fields for a MOTO Merchant
Function Name - setMPIResponseDetails
Sr No Field Details Valid values Mandatory
1 astrECI
Numeric value associated with the VBV process
provided by the MPI Data of the size 2 characters.
Conditional Mandatory (in case of VBV status Y). In all other cases, the values must be sent if the MPI has provided the same
2 astrXID
This value is generated during the VBV validation process
Data with maximum size of 28 characters
Conditional Mandatory (in case of VBV status Y). In all other cases, the values must be sent if the MPI has provided the same
3 astrVBVStatus
The result of the VBV validations.
Data with size of 1 character.
Single character status indicated by either of Y - Authentication Successful N - Authentication failed U - Processing Failure E - Not Enrolled A – Attempts Y 4 astrCAVV This value is generated during the VBV validation process if the validation is successful
Data with maximum size of 28 characters
Conditional Mandatory (in case of VBV status Y). In all other cases, the values must be sent if the MPI has provided the same
5 astrShoppingContext
The Payment Gateway currently stores the value of the Shopping Context that is passed to it. This value is not passed to the Acquirer.
Data with maximum size of
256 characters N
6 astrPurchaseAmount
The Payment Gateway currently stores the value of the Purchase Amount that is passed to it. This value is not passed to the Acquirer
Data with maximum size of
20 characters. N
7 astrCurrencyVal
The Payment Gateway currently stores the value of the Currency value that is passed to it. This value is not passed to the
VBV Fields for a SSL Merchant
Function Name - setMPIRequestDetails
Sr No Field Details Valid values
Mandator y
1 astrPurchaseAmount Amount of the transaction
Data with maximum size of 20 characters. Unformatted purchase amount. It should not contain any special characters such as “$” etc.
Example 100.20,100 Y
2 astrDisplayAmount Formatted purchase amount.
Data with maximum size of 20 characters. This field should contain a currency symbol, with an thousands separator (s), decimal point and ISO minor units defined for the currency specified in the Purchase Currency field.
Ex. INR1,234.56 Y
3 astrCurrencyVal
This is the currency code used by the merchant
Data with size of 3 characters. Data with size of 3 characters. ISO Numeric Currency Code.
Example 356 Y
4 astrExponent
Denotes the number of digits after the decimal point in the amount
Data with maximum size of 3 characters. If the amount is 100.20 then the exponent is 2 Y 5 astrOrderDesc
Brief description of items purchased,
determined by the Merchant Data with a maximum size of 125 characters Y 6 astrRecurFreq
This field is calculated based on installments and the Recur End and it denotes the frequency of payment
Data with maximum size of 3 characters.
Example: 12 Y
7 astrRecurEnd
This field indicates the end date of re curring value. It should be less than the card expiry date. It is also an op
tional field Data with maximum size of 8 characters.
Example: 20011212 Y
8 astrInstallment
Number of Installments Data with maximum size of 3 characters.
Example: 12 Y
9 astrDeviceCategory
This attribute indicates mode of transaction. For an internet based transaction the value to be set is "0".
Always use value 0 Y
10 astrWhatIUse
This field is used by the MPI to denote
the browser version. This field can be empty and is used by the MPI to denote the browser version. N
11 astrAcceptHdr
The Accept request-header field can be used to specify certain media types which are acceptable for the response. Accept headers can be used to indi cate that the request is specifically lim ited to a small set of desired types, as in the case of a request for an in-line image. The server property re quest.getHeader("Accept") can be used for setting this value
This indicates the MIME type the client can ac cept.
Ex: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-powerpoint, application/vnd.ms-excel, application/msword, application/x-shockwave-flash, */*
Y
12 astrAgentHdr
The User-Agent-header contains information about the user agent (typically a newsreader) generating the article, for statistical purposes and tracing of standards violations to specific software needing correction. Although not one of the mandatory headers, posting agents SHOULD normally include it. The server property request.getHeader("User-Agent") can be used for setting this value.
This indicates the type and version of browser used by the cardholder
Ex: Mozilla/4.0 (compatible; MSIE 5.5; Windows
