Java SFA merchant integration guide

Transcription

1 Java SFA merchant integration guide

2

3 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 key). The file name should not be changed, where 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. ote 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

4 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 WIZIP. Open the sfa.properties file. ote - If WIZIP 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 available to java.

5 d. Enable the verbose parameter to true only when necessary as the log generated 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. ote: 1. The verbose parameter in sfa.properties should be set to true only when needed. 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_LOCATIO$\epgRootca.cer -keystore $JAVA_HOME$\jre\lib\security\cacerts -storepass changeit Where, $CERT_LOCATIO$ 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 indicating the certificate was successfully imported into the keystore

6 d. Similarly import the intermediate ca certificate. ote: 1. The certificate import step assumes that the Merchant is using the SU JVM. If a JVM other than the SU JVM is used, then the above step must be altered accordingly to import the certificates so that SSL communication can be established

7 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. ote - 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 received 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.

8 Merchant Information Function ame - setmerchantdetails Sr o Parameter Details Valid values Mandatory Data with maximum size of 8 1 astrmerchantid ID assigned by the Payment Gateway to the Merchant Data with maximum size of 8 2 astrvendor Same as Merchant ID Data with maximum size of 8 3 astrpartner Same as merchant ID 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 Data with maximum size of (for SSL) 4 astrcustipaddress merchant 20 (for MOTO) 5 astrmerchanttxnid Transaction number generated by the Merchant for Alpha-numeric data with reference. Root Transactions should have unique maximum size of 50 Transaction Reference umber. 6 astrorderreferenceo Alpha-numeric data with Order number generated by the Merchant for his/her maximum size of 30 reference. 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 Data with maximum size of (for SSL always receives the response via the PGResponse Object 80 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 Data with maximum size of 4 should be POST as the response is sent via a redirection.. (GET/POST) 9 astrcurrcode Currency of the transaction Data with maximum size of 3. ISO Alpha Currency Code IR for transactions in Rupees. 10 astrinvoiceo Invoice number generated by the Merchants application Alpha-numeric data with maximum size of 20

9 Sr o Parameter Details Valid values Mandatory Data with maximum size of 20. Indicates the type of transaction. This field can contain req.preauthorization 11 astrmessagetype either of the values mentioned in the adjacent field req.sale umeric with maximum size of 15 digits. Maximum exponent is 5.For example, maximum possible data in the amount field can be 12 astramount Amount of the transaction Data with maximum size of 9 13 astrgmtoffset GMT Time Offset of the Merchants sites locale Format: GMT+hh:mm 14 astrext1 15 astrext2 16 astrext3 Reserved 17 astrext4 Additional fields provided to the Merchant for passing any Data with maximum size of specific data 50 Additional field provided to the Merchant for passing any Data with maximum size of specific data. To be filled in as true by SSL merchant 50 Data with maximum size of 50 Additional field provided to the Merchant for passing any Data with maximum size of specific data astrext5 Additional field provided to the Merchant for passing any Data with maximum size of specific data 50 Function ame - setmerchantrelatedtxndetails Sr o Parameter Details Valid values Mandatory Data with maximum size of 8. Id given to the Merchant for identification by 1 astrmerchantid ID assigned by the Payment Gateway to the Merchant the PG Data with maximum size of 8 2 astrvendor Same as Merchant ID. 3 astrpartner Same as Merchant ID Data with maximum size of 8. 4 astrmerchanttxnid 5 astrroottxnsysrefum 6 astrrootpref Alpha-numeric data with Transaction number generated by the Merchant for maximum size of 50 reference.. 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 umeric data with maximum to be given size of 15 RR number sent by the Payment Gateway to the merchant for the original transaction. Example, for an Authorization transaction the RR of Pre-Authorization needs to be given. Similarly, for a Refund transaction the umeric data with maximum RR of Authorization needs to be given. size of 20

10 Sr o Parameter Details Valid values Mandatory 7 astrrootauthcode Auth Code sent by the Payment Gateway to the merchant umeric data with maximum for the original transaction size of 6 8 astrcurrcode Currency of the transaction Data with maximum size of 3. ISO Alpha Currency Code. IR for transactions in Rupees Data with maximum size of 20. Indicates the type of transaction. This field can contain req.refund 9 astrmessagetype either of the values mentioned in the adjacent field req.authorization umeric with maximum size of 15 digits. Maximum exponent is 5.For example, maximum possible data in the amount field can be 10 astramount Amount of the transaction astrgmtoffset GMT Time Offset of the Merchants sites locale Data with maximum size of 9. GMT+hh:mm 12 astrext1 13 astrext2 14 astrext3 15 astrext4 16 astrext5 Additional fields provided to the Merchant for passing any Data with maximum size of specific data 50 Additional field provided to the Merchant for passing any Data with maximum size of specific data 50 Additional field provided to the Merchant for passing any Data with maximum size of specific data 50 Additional field provided to the Merchant for passing any Data with maximum size of specific data 50 Additional field provided to the Merchant for passing any Data with maximum size of specific data 50

11 Card Information Function ame - setcarddetails Sr o Field Details Valid values Mandatory 1 astrcardtype Data with maximum size of 5. VISA Visa MC- MasterCard 2 astrcardum umeric data with maximum size of 20 Alphaumeric data with maximum size of 5. 3 astrcvvum For VISA,This field should contain the value in the following format CVVum $ Presence Indicator Where CVVum 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 4 astrexpdtr yyyy Data with maximum size of 4. 5 astrexpdtmon mm Data with maximum size of 2. 6 astrameoncard 7 astrinstrtype Alphabetic data with maximum size of 80 Data with maximum size of 5. Mode of payment - CREDI - For credit cards Credit/ Debit DEBIT- For Debit Cards

12 Ship To Address Function ame - 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 o Field Details Valid values Mandatory 1 astraddrline1 Alphabetic data with maximum size of 50 2 astraddrline2 Alphabetic data with maximum size of 50 3 astraddrline3 Alphabetic data with maximum size of 50 4 astrcity Alphabetic data with maximum size of 30 5 astrstate Alphabetic data with maximum size of 30 6 astrzip umeric data with maximum size of 10 digits 7 astrcountryalphacode 8 astr Alphabetic data with maximum size of 3 ID for IDIA Alpha-umeric data with maximum size of 80 Bill To Address Function ame - 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 o Field Details Valid values Mandatory If customer is a registered customer with the merchant, then his ID needs to be Data with maximum size of 10 1 astrcustomerid populated in this field. 2 astrcustomerame Data with maximum size of 80 3 astraddrline1 4 astraddrline2 5 astraddrline3 6 astrcity 7 astrstate 8 astrzip 9 astrcountryalphacode 10 astr Alphabetic data with maximum size of 50 Alphabetic data with maximum size of 50 Alphabetic data with maximum size of 50 Alphabetic data with maximum size of 30 Alphabetic data with maximum size of 30 umeric data with maximum size of 10 digits Alphabetic data with maximum size of 3 ID for India Alpha-umeric data with maximum size of 80

13 Customer Details (required for FDMS) Function ame - 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 o Field Details Valid values Mandatory 1 strfirstame 2 strlastame Alphabetic data with maximum size of 50 Alphabetic data with maximum size of 50 3 OfficeAddress Object of Address Type 4 HomeAddress Object of Address Type umeric data passed as string. Max length of 5 Mobileo 15 yyyy-mmdd Alphabetic data with maximum length of 10 6 Registration Date 7 BillingShippingAddrMatch or Alphabetic data with maximum size of 1. Address (for Home/Office address details) Function ame - 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 o Field Details Valid values Mandatory 1 astraddrline1 Alphabetic data with maximum size of 50 2 astraddrline2 Alphabetic data with maximum size of 50 3 astraddrline3 Alphabetic data with maximum size of 50 4 astrcity Alphabetic data with maximum size of 30 5 astrstate Alphabetic data with maximum size of 30 umeric data passed as string with maximum size of 6 astrzip 10 digits 7 astrcountryalphacode Alphabetic data with maximum size of 3 ID for IDIA 8 astr Alphabetic data with maximum size of 80

14 Session Information Function ame - 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 o Field Details Valid values Mandatory IP Address of the system from where the end 1 strremoteaddr customer is performing the transaction. The value stored in the cookie named Alphabetic data with maximum size of 50 2 strcookie vsc Alphabetic data with maximum size of 50 3 strbrowsercountry Alphabetic data with maximum size of 16 4 strbroswerlanguage strbroswerlocallangu Alphabetic data with maximum size of 30 5 agevariant Alphabetic data with maximum size of 30 6 struseragent Merchandise Information Function ame - 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 o Field Details Valid values Mandatory 1 stritempurchased e.g., Computer, Shirts, Alphabetic data with maximum size of 24 umeric data passed as string with maximum 2 Quantity length of 3 Alphabetic data with maximum size of 24 3 strbrand Alphabetic data with maximum size of 24 4 strmodelumber Alphabetic data with maximum size of 32 5 strbuyer s ame Flag indicating whether Cardame and Buyerame Matches Alphabetic data with maximum size of 1 6 MatchingCardBuyerame or

15 Airline Transaction Information Function ame - 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 o Field Details Valid values Mandatory 1 strbookingdate yyyy-mm-dd Alphabetic data with maximum size of 10 2 strflightdate yyyy-mm-dd Alphabetic data with maximum size of 10 Hh:mm (24 hr Alphabetic data with maximum size of 5 3 strflighttime format) Alphabetic data with maximum size of 12 4 strflighto Alphabetic data with maximum size of 32 5 strpassengerame umeric data passed as string with 6 ooftickets maximum length of 2 Flag indicating whether Card ame and Buyer ame Matches Alphabetic data with maximum size of 1 7 MatchingCardBuyerame or 8 strpr Alphabetic data with maximum size of 24 9 strsectorfrom Alphabetic data with maximum size of strsectorto Alphabetic data with maximum size of 24

16 VBV Fields for a MOTO Merchant Function ame - setmpiresponsedetails Sr o Field Details Valid values Mandatory 1 astreci umeric value associated with the VBV process provided by the MPI Data of the size 2. Conditional Mandatory (in case of VBV status ). 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 Data with maximum size of process 28 Data with size of 1 character. Conditional Mandatory (in case of VBV status ). In all other cases, the values must be sent if the MPI has provided the same 3 astrvbvstatus Single character status indicated by either of - Authentication Successful - Authentication failed U - Processing Failure The result of the VBV E - ot Enrolled validations. A Attempts 4 astrcavv 5 astrshoppingcontext 6 astrpurchaseamount 7 astrcurrencyval This value is generated during the VBV validation process if the Conditional Mandatory validation (in case of VBV status ). In all other cases, the values is Data with maximum size of 28 must be sent if the MPI has successful provided the same The Payment Gateway currently stores the value of the Shopping Context that is passed to it. This value is not passed to the Data with maximum size of Acquirer. 256 The Payment Gateway currently stores the value of the Purchase Amount that is passed to it. This value is not passed to the Data with maximum size of Acquirer 20. The Payment Gateway currently stores the value of the Currency value that is passed to it. This value is not passed to the Data with a maximum size of Acquirer 3.

17 VBV Fields for a SSL Merchant Function ame - setmpirequestdetails Sr o Field Details Valid values 1 astrpurchaseamount Amount of the transaction Data with maximum size of 20. Unformatted purchase amount. It should not contain any special such as $ etc. Example ,100 Data with maximum size of 20. 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. 2 astrdisplayamount Formatted purchase amount. Ex. IR1, Data with size of 3. Data with size of This is the currency code used by the 3. ISO umeric Currency Code. 3 astrcurrencyval merchant Example astrexponent 5 astrorderdesc 6 astrrecurfreq 7 astrrecurend 8 astrinstallment 9 astrdevicecategory 10 astrwhatiuse 11 astraccepthdr Denotes the number of digits after the Data with maximum size of 3. decimal point in the amount If the amount is then the exponent is 2 Brief description of items purchased, determined by the Merchant Data with a maximum size of 125 This field is calculated based on installments and the Recur End and it Data with maximum size of 3. denotes the frequency of payment Example: 12 This field indicates the end date of recurring value. It should be less than the card expiry date. It is also an optional field Data with maximum size of 8. umber of Installments This attribute indicates mode of transaction. For an internet based transaction the value to be set is "0". Example: Data with maximum size of 3. Example: 12 Always use value 0 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. The Accept request-header field can be used to specify certain media types which are acceptable for the response. This indicates the MIME type the client can accept. Accept headers can be used to indicate that the request is specifically limited to a small set of desired types, as Ex: image/gif, image/x-xbitmap, image/jpeg, in the case of a request for an in-line image/pjpeg, application/vnd.ms-powerpoint, image. The server property request.getheader("accept") can be application/x-shockwave-flash, */* application/vnd.ms-excel, application/msword, used for setting this value Mandator 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 T 5.0)