Appendix: Installing the PeopleSoft Credit Card Interlink

PeopleSoft Financials, Distribution, and Manufacturing applications deliver a Java interface to a third-party credit card authorization and payment application.

This chapter discusses how to:

• Configure the Java interlink plug-in.

• Configure the Application Designer plug-in.

• Set transaction inputs and outputs.

• Use credit card test transaction information.

Note. PeopleSoft applications use PeopleSoft Business Interlink architecture to interface with credit card processing vendors. To configure interfaces with unsupported vendors, create an interlink plug-in.

See Also

Processing Credit Cards

Setting Up the Credit Card Interface

Enterprise PeopleTools 8.46 PeopleBook: PeopleSoft Business Interlinks

Configuring the Java Interlink Plug-In

PeopleSoft delivers a Java interface to a third-party credit card authorization and payment application.

This section provides an overview of the Java Interlink plug-in and discusses how to:

• Set up the CyberSource API and Java plug-in on NT systems.

• Set up the CyberSource API and Java plug-in on Unix systems.

Understanding the Java Interlink Plug-In

Using Business Interlink technology, the Java interface supports four transactions:

• Authorization Only.

• Bill Only.

• Authorization and Bill.

• Credit.

Use the plug-in to interface with the CyberSource Credit Card Processing Services product. The Business Interlink Java plug-in (delivered with the PeopleTools installation) uses the CyberSource Java API, version 3.7.12. Before you configure the system, obtain the CyberSource Java API from http://www.cybersource.com. You must obtain the Java version of the API even if you are already using the C++ plug-in and API.

See http://www.cybersource.com

Download the zipped API files, and use these instructions for environment configuration.

Setting Up the CyberSource API and the Java Plug-in on NT Systems

This section provides instructions for setting up the CyberSource API and the Java plug-in on an NT platform.

Setting Up PeopleTools Java Business Interlink on NT

To set up the PeopleTools Java Business Interlink environment:

1. Ensure that there are two entries in the PATH environment variable that point to the JRE bin.

   Do not confuse the JRE bin with the JDK bin. The two entries in the PATH environment variable should point as follows:

   <<JRE Home>>\jre\bin;<<JRE Home>>\jre\bin\classic;

   If you are using JRE version 1.4 or later, the \classic directory is replaced by \server. In this case, the two entries in the PATH environment variable should point as follows:

   <<JRE Home>>\jre\bin;<<JRE Home>>\jre\bin\server;

2. Create an entry in the CLASSPATH environment variable.

   Point the entry in the CLASSPATH environment variable to the psinterlinks.jar file. The psinterlinks.jar file is located in <<PS Tools>>\class.

   You must include the name of the .jar file in the CLASSPATH entry; for example: c:\pstools\class\psinterlinks.jar

Set Up the CyberSource API

To set up the CyberSource API:

1. Install the CyberSource API using the CyberSource documentation instructions.

2. Follow the CyberSource installation directions for making CLASSPATH entries.

3. Update the CyberSource properties file for the CyberSource environment.

   Update the file (<<CyberSource Home>>\ics_3.7.12\properties\ICSClient.props) to point to the key and certificate files located in the keys directory. Use a forward slash, not a back slash, to separate the directories:

   # file with the location of your private key required
   
   myPrivateKey=D:/opt/ics/keys/ICS2Test.pvt
   
   # file with the location of your cert required 
   
   myCert=D:/opt/ics/keys/ICS2Test.crt
   
   # file with the location of the Cybersource cert
   
   serverCert=D:/opt/ics/keys/CyberSource_SJC_US.crt

4. Run the Java program, ICSAuthTest, to ensure that the API is set up properly.

   ICSAuthTest is located in the directory where you installed CyberSource.

   1. Open the Windows Command Prompt.

   2. Change drives and directories to point to the CyberSource test directory.

   3. Edit ICSAuthTest.java to change the expiration to a future date.

   4. Compile the edited program with the command:

      javac ICSAuthTest.java

   5. Run ICSAuthTest with the command:

      java ICSAuthTest

   6. Verify that ICSAuthTest completes successfully.

Set Up the Plug-in

To set up the plug-in:

1. Move the pscreditcard.jar to the desired directory.

   The pscreditcard.jar file is installed in <<PS Tools>>\class. You can move this .jar file to another directory for more stringent security access. The .jar file operates with execute permission only.

2. Update the CLASSPATH to point to the pscreditcard.jar file.

   Include the file name in the CLASSPATH entry.

3. Open Application Designer, and select File, New, Business Interlink.

4. Select pscreditcard.dll.

5. Verify that the text that appears in the Version text box of the New Business Interlink dialog window begins with plugin.

   If the text reads Failed to initialize JVM, the PATH environment variable is not pointing to the JRE directories. Ensure that the PATH points to both the JRE bin and classic directories; for example: <<JRE Home>>\jre\bin;<<JRE Home>>\jre\bin\classic

Configure the Application Server

To configure the application server:

1. Copy the ICSClient.props file from the CyberSource properties directory to the application server domain directory.

2. Open the psappsrv.env text file that is located in the application server (not the web server) domain folder.

3. Add the path to the JRE using the Add to Path variable.

4. Add the credit card interface JAR files, ics.jar, pscreditcard.jar, and psinterlink.jar (in that order), to the ClassPath using the Add to ClassPath variable. A typical entry would look like:

   Add to CLASSPATH=c:\cybersource\ics.jar;c:\PT8.46\class\pscreditcard.jar;c:\PT8.46\class\pscreditcard.jar

   Note. Ensure that there is a semicolon between the path entries.

5. Shut down and restart the application server.

Configure the Process Scheduler Server

To configure the process scheduler server:

1. Locate the process scheduler domain folder within the application server folder (<<PS Tools>>\appserv\prcs\<<domain>>\).

2. Copy the ICSClient.props file from the CyberSource properties directory into this folder.

3. Open the psprcs.cfg file using a text editor.

4. Add the path to the JRE using the Add to Path variable.

5. Add the credit card interface JAR files, ics.jar, pscreditcard.jar, and psinterlink.jar (in that order), to the ClassPath using the Add to ClassPath variable. A typical entry would look like:

   Add to CLASSPATH=c:\cybersource\ics.jar;c:\PT8.46\class\pscreditcard.jar;c:\PT8.46\class\pscreditcard.jar

   Note. Ensure that there is a semicolon between the path entries.

Setting Up the CyberSource API and the Java Plug-in on Unix

This section provides instructions for setting up the CyberSource API and the Java plug-in on a Unix platform.

Set Up the PeopleTools Java Business Interlink on Unix

To set up the PeopleTools Java Business Interlink environment:

1. Ensure that pspkgs.sh was run as part of the installation process.

2. Verify that the file psinterlinks.jar file exists in <<PS Tools>>/appserv/classes.

   If psinterlinks.jar does not exist, pspkgs.sh may have run incorrectly.

3. Verify that the Java Virtual Machine is installed under the Tools home directory.

   If the Java Virtual Machine is not installed, pspkgs.sh may have run incorrectly.

4. Locate psconfig.sh in <<PS Tools>>, and open it in a text editor.

5. Ensure that there is an entry in the PATH environment variable in psconfig.sh pointing to the JRE bin.

   Do not confuse the JRE bin with the JDK bin. The entry in the PATH environment variable should point as follows: PATH=$PS_JRE/bin:$PATH;export PATH

   If you are using JRE version 1.4 or later, the entry in the PATH environment variable should point as follows:

   $PATH=$PS_JRE/bin:$PS_JRE/bin/server:$PATH;export $PATH

6. Create an entry in the PS_CLASSPATH environment variable in psconfig.sh.

   Point the entry to the psinterlinks.jar file located in <<PS Tools>>\appserv\classes. You must include the name of the .jar file in the PS_CLASSPATH entry; for example: /pstools/class/psinterlinks.jar

Set Up the CyberSource API

To set up the CyberSource API:

Complete the steps in this section for the application servers and the process scheduler servers.

1. Install the CyberSource API using the CyberSource documentation.

2. Update CLASSPATH and PS_CLASSPATH in psconfig.sh to point to the API .jar file.

   The API .jar file is ics.jar

3. Update CLASSPATH in psconfig.sh to point to the test directory under the API’s ics_3.7.12 directory.

4. Save the changes to psconfig.sh.

5. Update the CyberSource properties file.

   Update the file (<<CyberSource Home>>\ics_3.7.12\properties\ICSClient.props) to point to the key and certificate files located in the keys directory. Use a forward slash; not a back slash to separate the directories:

   # file with the location of your private key required
   
   myPrivateKey=D:/opt/ics/keys/ICS2Test.pvt
   
   # file with the location of your cert required 
   
   myCert=D:/opt/ics/keys/ICS2Test.crt
   
   # file with the location of the Cybersource cert
   
   serverCert=D:/opt/ics/keys/CyberSource_SJC_US.crt

6. Run psconfig.sh to set the properties.

7. Run the Java program ICSAuthTest to ensure that the API is set up properly.

   ICSAuthTest is located in the directory where you installed CyberSource. You must edit ICSAuthTest.java to set the expiration to a future date and compile before running ICSAuthTest.

Note. You do not need to make a system-level CLASSPATH entry in addition to the CLASSPATH entry in psconfig.sh.

If Java class ICSAuthTest.class runs successfully, you can remove the CLASSPATH references to the test directory and the ics.jar file.

Set Up the Plug-in

To set up the plug-in:

Complete the steps in this section for the applications servers and the process scheduler servers.

1. Confirm that the pscreditcard.jar file is located in <<PS Tools>>/appserv/classes.

   Optionally, you can move this .jar file to another directory to tighten security and limit access. If you move this .jar file to a different location, ensure that you reference the new location in these steps.

2. Update PS_CLASSPATH in psconfig.sh to point to pscreditcard.jar file in the classes directory.

   Include the file name in the entry.

3. Confirm that the libpscreditcard file is in the <<PS Tools>/bin/InterfaceDrivers directory.

   Note. Unix file extensions can differ. Use the same naming convention as the libpsjavaproxy file for the libpscreditcard file.

4. Stop and restart the application server.

   Stop the services; do not stop the machine.

Configure the Application Server

To configure the application server:

1. Copy the ICSClient.props file from the CyberSource properties directory to the application server domain directory.

2. Open the psappsrv.env text file that is located in the application server (not the web server) domain folder.

3. Add the path to the JRE using the Add to Path variable.

4. Add the credit card interface JAR files, ics.jar, pscreditcard.jar, and psinterlink.jar (in that order), to the ClassPath using the Add to ClassPath variable.

   Note. Ensure that there is a semicolon between the path entries.

5. Shut down and restart the application server.

Configure the Process Scheduler Server

To configure the process scheduler server:

1. Locate the process scheduler domain folder within the application server folder (<<PS Tools>>/appserv/prcs/<<domain>>\)

2. Copy the ICSClient.props file from the Cybersource properties directory into this folder.

3. Open the psprcs.cfg file using a text editor.

4. Add the path to the JRE using the Add to Path variable.

5. Add the credit card interface JAR files, ics.jar, pscreditcard.jar, and psinterlink.jar (in that order), to the ClassPath using the Add to ClassPath variable.

   Note. Ensure that there is a semicolon between the path entries.

Set up the Windows Client Plug-in

To set up the Windows client plug-in, verify that the pscreditcard.xml file is in the client\InterfaceDrivers directory.

Configuring the Application Designer Plug-in

The Business Interlink definition in Application Designer is delivered preconfigured.

This section discusses how to:

• Configure access to account information.

• Configure proxy server support.

• Set up tracing.

• Check parameter check logic.

• Set the decryption option.

Note. All credit card transactions are supported through one Business Interlink transaction:

Setting Configuration Parameters: Configuring Access to Account Information

The API needs six essential configuration parameters to complete any transaction:

• Merchant ID

• Private Key File

• Certificate File

• Server ID

• Server Certificate

• Server URL

The Java plug-in offers three configuration options. The options are:

• Keep the six configuration parameters in a properties file.

  Use this option if you are building a new credit card processing application.

• Pass the merchant ID and server URL as input parameters, and specify the path of the key and certificate files.

  Use this option if you have an existing application that has used the C++ plug-in, but which you are now porting to Unix.

• Use the Java plug-in just as you use the C++ version.

  The plug-in gets the certificate and key files from c:\opt\ics\keys. Use this option if you use the C++ plug-in and if you want to continue to operate on a Windows platform.

Note. These configuration options contain screen shots of Business Interlinks (open in Application Designer) and demonstrate default input parameter values. After setting up a transaction, set the input parameter values as default values to test them in the Business Interlink Tester. Typically, PeopleCode sets these input parameter values at runtime. In Application Designer, click File, Open, Business Interlink to open a Business Interlink transaction. Define the configuration parameters for the credit card Business Interlink definition on the Settings and Input pages.

Option 1: Keep All Configuration Parameters in a Properties File

Use this option if you are building a new credit card processing application.

To keep all of the configuration parameters in a properties file:

1. Update the CyberSource properties file.

   Update the file (<<CyberSource Home>>/ics_3.7.12/properties/ICSClient.props) to point to the key and certificate files located in the keys directory. Use a forward slash to separate directories:

   # file with the location of your private key required
   myPrivateKey=C:/opt/ics/keys/ICS2Test.pvt
   
   # file with the location of your cert required 
   myCert=C:/opt/ics/keys/ICS2Test.crt
   
   # file with the location of the Cybersource cert
   serverCert=C:/opt/ics/keys/CyberSource_SJC_US.crt

2. Set the value of the properties_file configuration parameter to the path of the ICSClient.props file.

   In Application Designer, click the Settings tab to set the value. Ensure that you use a forward slash to separate directories.

3. Leave the privateKeyFile, myCertFile, serverCertFile, and certServerID fields blank.

Option 2: Pass the Merchant ID and Server URL as Input Parameters, and Specify the Path of the Key and Certificate Files

Use this option if you have an existing application that has used the C++ plug-in but which you are now porting to Unix.

To pass the merchant ID and server URL as input parameters and to specify the path of the key and certificate files:

1. Delete the value of the properties_file config parameter on the Settings page.

   Enter the paths for the key and certificate files in their appropriate config parameters. Ensure that you use a forward slash to separate directories. The default value for the certServerID is CyberSource_SJC_US.

2. Ensure that you include the merchant and server_host input parameters in the transaction.

   Do not include the text http:// in the server URL string.

Option 3: Use the Java Plug-in as You Use the C++ Version

Use this option if you use the C++ plug-in and want to continue to operate on a Windows platform.

To use the Java plug-in as you use the C++ version:

1. Delete the values of the properties_file, certificate, key, and server ID field parameters on the Settings page of the Business Interlink definition.

2. Use the merchant and server_host field input parameters in the transaction. Do not include the text http:// in the server URL string.

Setting Configuration Parameters: Configuring Proxy Server Support

The Java plug-in supports the HTTP proxy without a user name and password, and it supports the SOCKS proxy protocols. This functionality was implemented as outlined in the ICS2 Developers Guide issued by CyberSource.

Implementing Proxy Server Support

To implement proxy server support:

1. Select the proxy type from the useProxyServer configuration parameter.

2. Enter the values of the host and port in the proxyHost and proxyPort configuration parameters.

Setting Up Tracing

The plug-in and the CyberSource API support the use of a trace file. To keep a log of the transactions, use the plug-in’s trace file, and reserve the API’s trace file for debugging. The plug-in trace file:

• Uses the input names as they appear in Application Designer, not the CyberSource API property names.

• Prints only the last four digits of the credit card number.

• Prints the output values and any error messages.

Activating Tracing

There are two methods for activating tracing in the Java plug-in:

• Leave the trace_file blank and use the trace input parameter to toggle tracing.

  The trace file writes to c:\temp\crcard.txt.

• Enter a path and file name in the trace_file configuration parameter, and use the trace input parameter to enable the tracing (trace=Y) or disable the tracing (trace=N).

  Use this method for new credit card definitions, if porting existing credit card definitions to Unix, or to have the trace file written to a directory other than c:\temp. Ensure that you use forward slashes when specifying directory paths.

Activating Trace Run Only

To view the input values that are sent to the CyberSource API and to confirm that the plug-in can instantiate the CyberSource interface (without sending the transaction to CyberSource), pass a value of T with the trace input parameter. If a trace file is specified in the trace_file configuration parameter, the system uses that trace file. Otherwise, the system uses the c:\temp\crcard.txt trace file.

Setting Parameter Check Logic

If the paramchk parameter is set to Y, the plug-in runs in trace run only mode and performs additional checks in the input parameters to ensure that the parameters do not exceed maximum allowed field lengths. The system sends the transaction information to the CyberSource API.

Setting the Decryption Option

Credit card numbers are sent encrypted to the plug-in. Do not toggle this option unless you also make a change in the PeopleCode to pass the credit card number as plain text.

Setting Transaction Inputs and Outputs

This section presents information necessary for creating a new Business Interlink definition. If you are configuring the environment for the delivered Business Interlink definition, skip this section.

This section discusses how to:

• Use Authorize, Authorize Only, and Bill transactions.

• Identify Input fields not used or supported.

Understanding Transaction Inputs and Outputs

The service and merchant_ref input parameters are required in all credit card transactions. The method that you use to configure the plug-in determines which fields are required. The minimum number of fields to include are listed in this table.

Service Input Field

The system uses the service parameter to determine which of the four credit card transactions it should conduct through the Business Interlink transactions. The service parameter values perform these functions:

merchant_ref Input Field

The merchant_ref field is a merchant-generated order reference or tracking number, containing information such as a purchase order number. Use the merchant_ref_number field as the own tracking number for the order. Record and track this number to keep track of requests sent to CyberSource relating to the same order.

For a single order, you might need to make these requests:

1. Send a request for ics_tax to get a total amount for an order quote.

2. Thirty seconds later, after a customer clicks the Buy Now button on the web form, you send a request to ics_auth to authorize the card and to check for fraud.

3. The next day, you ship the item and send a request to ics_bill to bill the credit card.

4. A week later, the customer returns one of the products in the order, and you request a credit using ics_credit.

For this single order, you forward four separate requests to CyberSource to perform different services for the same order. If you send a common merchant_ref_number for each of these requests, you can efficiently track the order.

Using Authorize, Authorize Only, and Bill Transactions

The authorize-only transaction (service=1) authorizes the amount passed in and returns a request ID for use later in a bill-only transaction. The authorize and bill transaction (service=2) performs both actions and returns a bill_amount for verification of the amount billed.

Address Verification Service

CyberSource returns the decline code DAVSNO if the billing address does not match the billing address for the credit card. If you set the value of the field avs_ignore to yes and include it in the Business Interlink definition, the system allows the authorization transaction to proceed despite the billing address discrepancy. If the value of the field avs_ignore is anything other than yes, the AVS check proceeds as usual.

The address verification service returns a value that is stored in ret_avs. The values are:

Fraud screen service

Both the Authorize and the Authorize and Bill transactions support the fraud screen transaction. Refer to the CyberSource documentation for an explanation of the fraud screen transaction and how the score tuning parameters are used.

Bill-Only Transaction

The bill-only transaction (service=3) requires the use of a request ID obtained from an authorize-only transaction.

Credit Transaction

Use one of these methods to perform the credit transaction. Options are:

1. Use request ID.

   This option enables you to use the value of a request ID returned from a previous request for bill transactions. This value is matched with a previous bill for the same order. If this field is present and there is no matching bill, the transaction fails. If the bill request ID is not present, the credit transaction requires the customer billing information.

   Required Inputs	Service, Merchant_ref, Amount, Currency, Rqstid
   Output	Return_status, Return_status_msg, Ret_msg1, Ret_msg2, Ret_authcd, Ret_authdttm, Rqstid_out, Credit_amount, Trans_ref_no

2. Use Billing Information.

   Required Inputs	Service, Merchant_ref, Fname, Lname, Addr1, City, Country, State, Zip, Email, Phone, Expmo, Expyr, Ccnum, Amount, Currency
   Output	Return_status, Return_status_msg, Ret_msg1,Ret_msg2, Ret_authcd, Ret_authdttm, Rqstid_out, Credit_amount

Identifying Input Fields Not Used or Supported

These input fields are not used or supported as of 11/06/00:

Using Credit Card Test Transaction Information

You can use this credit card sample data in test transactions: