Installing and Configuring the SDK
This section explains how to install, configure, and test the SDK for Java. If you are a new customer installing the SDK for the first time, skip the section about upgrading and go directly to Downloading the SDK File.
nJava 2 SDK version 1.2 or later
n128 MB RAM allocated to your Java Virtual Machine (JVM)
n10 MB of disk space
nA utility to uncompress the distribution file
The SDK supports UTF-8 encoding.
|
|
Failure to configure your client API host to a unique, public IP address causes inconsistent transaction results. |
The client API request ID algorithm uses a combination of IP address and system time, along with other values. In some architectures this combination might not yield unique identifiers. If it is not possible to configure your machines with unique IP addresses, CyberSource provides a client configuration parameter that you can use to identify your host. For the CyberSource SCMP API SDK for Java, this configuration parameter is the ics.hostID entry in the ICSClient.props file.
If you are an existing customer upgrading a previous version of the SDK, you follow many of the same procedures as a new customer installing the SDK for the first time.
The main difference is that you need not generate your certificate and private key files. Instead, copy your existing certificate and key files from your old SDK to the ics_n.n.n/keys/ directory in the new SDK.
Do not, however, copy your old ICSClient.props properties file from the old SDK. Instead, use the ICSClient.props.template file provided in the ics_n.n.n/properties/ directory of the new SDK. This ensures that you use the latest version of the file. Change the file to include the new location of your key files, and make any other changes you want, based on your old file. For more information, see Indicating the Path to Your Security Keys and Setting Properties in ICSClient.props.
If you use the ICSClient(Properties) constructor in your code, make sure that it uses the correct path to your new ICSClient.props file. For more information, see ICSClient(Properties).
You can delete the old SDK directory after the new SDK is successfully installed and tested.
To download the SDK file:
Step 1Create a target directory for the SDK files.
Step 2Download the latest SDK package file from the downloads area of the CyberSource Support Center.
Step 3Unzip or untar the package to your target directory.
The target directory contains the directories and files listed below.
|
Directory or File |
Description |
|
doc/ |
Contains Javadoc for the SDK. |
|
keys/ |
Contains your certificate and private keys and the ECert application which can be used to generate your keys. Transaction security keys can also be generated in the Business Center. For more information, see Creating and Using Security Keys (PDF | HTML) |
|
properties/ |
Contains the properties file that stores basic client properties required for transactions. |
|
test/ |
Contains test programs for different types of transactions. Includes an EJB/ directory that contains test programs for Enterprise JavaBeans™ (EJB) transactions. |
|
CHANGES.txt |
Describes the changes in this and previous versions of the SDK. |
|
LICENSE.txt |
Contains the CyberSource software license agreement. |
|
README_JDK12.txt |
Contains SDK installation and testing instructions, as well as frequently asked questions. |
|
README_EJB.txt |
Contains instructions for implementing and testing EJB server support. Describes the test programs in the test/EJB/ directory. |
|
README_TEST.txt |
Contains descriptions of the different test programs in the test/ directory. |
|
ics.jar |
Contains the Java class files for the SDK. |
You must set the CLASSPATH environment variable to include the ics.jar file.
setenv CLASSPATH ${CLASSPATH}:<Install_dir>/ics_n.n.n/ics.jar
export CLASSPATH=${CLASSPATH}:<Install_dir>/ics_n.n.n/ics.jar
To set the classpath for Windows operating systems:
Step 1Right-click the My Computer icon.
Step 2Click Properties > Environment.
Step 3Edit the value for CLASSPATH to include ics.jar.
Example C:\CyberSource\ics_n.n.n\ics.jar;.
Indicating the Path to Your Security Keys
|
|
You must generate two transaction security keys—one for the CyberSource production environment and one for the test environment. For information about generating and using security keys, see Creating and Using Security Keys (PDF | HTML). |
Use one of the three following options to indicate the path to your key files:
nSet the ics.keysPath property in the ICSClient.props file, for example:
ics.keysPath=/opt/ics_n.n.n/keys/
If you are using multiple merchant IDs, this method is the most efficient. Store the key files for all of your merchant IDs in one directory, indicated by the ics.keysPath property. CyberSource can then locate the key files automatically based on the merchant ID you specify in the request. This way you do not have to specify the individual paths for the files in the request or the properties file.
You can override the path specified with ics.keysPath by using either of the other two options.
nSpecify the full path for each file using the myCert, myPrivateKey, and serverCert properties in the ICSClient.props file, for example:
myCert=/opt/ics/keys/MyMerchant.crt
myPrivateKey=/opt/ics/keys/MyMerchant.pvt
serverCert=/opt/ics/keys/CyberSource_SJC_US.crt
nSpecify the full path for each file in the request itself. This overrides both of the other options. Use this method if you use multiple merchant IDs and do not store the key files for all of your merchant IDs in the same directory. For more information about setting fields in requests, see Adding Request-Level Fields.
Setting Properties in ICSClient.props
Before you can send transactions to CyberSource, you must configure a properties file called ICSClient.props, located in the properties/ directory in the SDK.
See Table 13 for a list of the properties that you can set. Using the properties file to specify these values is optional. If you do not specify a value in the properties file, you must set the value for the corresponding field in the request. For example, you can either set the retryEnabled property in the properties file, or you can set the retry_enabled field in the request itself. See Adding Request-Level Fields for more information about setting fields in the request.
In the ICSClient.props file, use this syntax to set property values: fieldName=value
Example myPrivateKey=/home/opt/ics_n.n.n/keys/example.pvt
If you do not want to use one of the properties in the file, delete it or comment it out.
|
Properties |
Explanation |
|
Determines whether ICSClient writes debugging information. Use one of these values: n0: Debugging off (default) n1: Debugging information recorded n2: Trace information recorded (less information than with debugLevel=1). Important CyberSource recommends that you use logging only when troubleshooting problems. To comply with all Payment Card Industry (PCI) and Payment Application (PA) Data Security Standards regarding the storage of credit card and card verification number data, the logs that are generated contain only masked credit card and card verification number data (CVV, CVC2, CVV2, CID, CVN). Follow these guidelines: nUse debugging temporarily for diagnostic purposes only. nIf possible, use debugging only with test credit card numbers. nNever store clear text card verification numbers. nDelete the log files as soon as you no longer need them. nNever send email to CyberSource containing personal and account information, such as customers' names, addresses, credit card or checking account numbers, and card verification numbers. For more information about PCI and PABP requirements, see www.visa.com/cisp. |
|
|
debugFile |
Name of the file that stores debugging information when debugLevel is enabled. The default name is debug.log. |
|
IP address to use for generating a request ID. If none is specified, the computer’s local IP address is used. Corresponds to the host_id request field. |
|
|
ics.keysPath |
Default location of the certificate and private key files if they are not specified as myCert, myPrivateKey, serverCert, or in the request. Corresponds to the keys_path request field. |
|
merchantID |
CyberSource merchant ID. Corresponds to the merchant_id request field. |
|
myCert |
Full path to your certificate file. Read only if myCertData property is not specified and certificate data is absent from the request message, for example: /opt/java_sdk_ics_n.n.n/ics_n.n.n/keys/MyMerchant.crt Corresponds to the merchant_cert_file request field. |
|
myCertData |
Default merchant certificate data if absent from the request message. The data must be Base-64 encoded. Corresponds to the merchant_cert request field. |
|
myPrivateKey |
Full path to your private key file. Read only if myPrivateKey property is not specified and private key data is absent from the request message, for example: /opt/java_sdk_ics_n.n.n/ics_n.n.n/keys/MyMerchant.pvt Corresponds to the merchant_private_key_file request field. |
|
myPrivateKeyData |
Default merchant certificate data if absent from the request message. The data must be Base-64 encoded. Corresponds to the merchant_private_key request field. |
|
serverCert |
Full path to the CyberSource server’s certificate file, for example: /opt/java_sdk_ics_n.n.n/ics_n.n.n/keys/CyberSource_SJC_US.crt Corresponds to the server_cert_file request field. |
|
serverCertData |
Default server certificate data to use if absent from the request message. The data must be Base-64 encoded. Corresponds to the server_cert request field. |
|
serverName |
CyberSource server ID. The default value is CyberSource_SJC_US. |
|
serverURL |
Default URL for requests to CyberSource: nTest: http://ics2testa.ic3.com:80/ nProduction: http://ics2a.ic3.com:80/ Default value: http://ics2testa.ic3.com:80/ Corresponds to the server_host and server_port request fields. |
|
retryEnabled |
Set to true or false. The default value is false. For more information, see Timeouts and Automatic Retries. Corresponds to the retry_enabled request field (which is set to yes or no). |
|
retryStart |
Number of seconds to wait before sending the retry request. The default value is 30. For more information, see Timeouts and Automatic Retries. Corresponds to the retry_start request field. |
|
timeout |
Client timeout value in seconds. The default value is 110. For more information, see Timeouts and Automatic Retries. Corresponds to the timeout request field. |
To test the SDK installation:
Step 1Open a command prompt.
Step 2In the directory where you extracted the SDK, go to the test/ directory.
Step 3To run the test application, type
java ICSClientTest
You receive the message Transaction succeeded if you successfully installed and configured the SDK. If you do not receive this message, verify that your certificate and private key files where generated correctly and that the location is specified correctly. For more information, see Indicating the Path to Your Security Keys.
The SDK includes additional programs in the test/ directory that you can use to test different CyberSource services. The README_TEST.txt file in the SDK describes the different programs.
|
|
When you are still in test mode, send your requests to the test server ics2test.ic3.com and use port 80. See the sample CyberSource requests for examples. |
You should also intentionally fail test transactions. To do this, modify field values in the test programs in the test/ directory of the SDK. You receive a message that says Transaction Failed and the reason for the error. The following examples show how to intentionally fail a test transaction.
To intentionally fail a test transaction due to a missing field:
Step 1In a text editor, open the ICSClientTest.java file in the test/ directory of the SDK.
Step 2Change the statement that sets the billing city field so that the value is empty:
request.setBillCity("");
Step 3Save and recompile the file.
Step 4Run the test file:
aOpen a command prompt.
bIn the directory where you extracted the SDK, go to the test/ directory.
cType java ICSClientTest
You receive a message that says Transaction Failed and DMISSINGFIELD, indicating a missing field in the request.
To intentionally fail a test transaction due to invalid data:
Step 1In a text editor, open the ICSAuthTest.java file in the test/ directory of the SDK.
Step 2Change the statement that sets the customer credit card expiration year field so that the value is invalid, for example
request.setCustomerCreditCardExpirationYear("asdfjkl");
Step 3Save and recompile the file.
Step 4Run the test file:
aOpen a command prompt.
bIn the directory where you extracted the SDK, go to the test/ directory.
cType java ICSAuthTest
You receive a message that says Transaction Failed and DINVALIDDATA, indicating invalid data in one of the request fields.
When you complete all of your system testing and are ready to accept real transactions from your customers, your deployment is ready to go live. When your deployment goes live, you can send transactions to CyberSource’s production server. Provide your banking information to CyberSource so that your processor can deposit funds to your merchant bank account.
To send transactions to the CyberSource production server:
Step 1Log in to the test Business Center.
Step 2In the left navigation panel of the test Business Center, click Support Center.
Step 3On the Support Center home page, in the Search Knowledgebase search well, type go live, and then click Search.
Step 4In the search results, depending on what version of CyberSource you use, click How do I go live? (Enterprise) or How do I go live? (Small Business).
These knowledgebase articles provide instructions that describe how to activate your account to process live transactions.
Once CyberSource has confirmed that your deployment is live, make sure to update your system so that you send requests to the production server (ics2a.ic3.com) instead of the test server (ics2testa.ic3.com).
After your deployment goes live, use real card numbers and other data to test every card type, currency, and CyberSource application that your integration supports. Because these are real transactions, use small monetary amounts to do the tests. Process an authorization, capture, and credit for each configuration. Use your bank statements to verify that money is deposited into and withdrawn from your merchant bank account. If you have more than one CyberSource merchant ID, test each one separately.