Installing and Testing the Client
nThis client is supported on the Windows 2000/XP/2003, Linux, and Solaris platforms.
nThe minimum Java SDK supported are Oracle or IBM Java SDK 1.6 or later. Depending on the package that you choose, you also need one of these:
lFor Oracle Java SDK versions earlier than 1.4.0, you need the Java Secure Socket Extension (JSSE) 1.0.3_02 or later (see http://java.sun.com/products/jsse).
lFor IBM Java SDK, you need IBMJSEE 1.0.2 or later.
nMaven 3 or later.
nUnlimited Strength Jurisdiction Policy files from Oracle® (US_export_policy.jar and local_policy.jar), available at:
http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html
The first thing you must do is create your security key. The client uses the security key to add a digital signature to every request that you send. This signature helps ensure that no one else can use your CyberSource account to process orders. You specify the location of your key when you configure the client.
|
|
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). |
|
|
You must protect your security key to ensure that your CyberSource account is not compromised. |
The Java SDK is available to install from GitHub:
https://github.com/CyberSource/cybersource-sdk-java
Maven
CyberSource recommends using the Maven Package Manager to install the Java SDK.
To install the JAVA SDK:
Step 1Add the dependency to your application pom.xml.
|
<dependency> <groupId>com.cybersource</groupId> <artifactId>cybersource-sdk-java</artifactId> <version>6.0.1</version> </dependency> |
Step 2Run mvn install.
Gradle
Add the dependency to your build.gradle.
|
dependencies { compile 'com.cybersource:cybersource-sdk-java:6.0.1' } |
The Java SDK jar file is available to download independently from GitHub:
http://search.maven.org/remotecontent?filepath=com/cybersource/cybersource-sdk-java/6.0.1/cybersource-sdk-java-6.0.1.jar
To install the files individually:
Step 1Download the latest jar file. The current version is cybersource-sdk-java-6.0.1.jar.
Step 2Save the jar file to an appropriate location.
Step 3Import the com.cybersource.ws.client package.
The client requires certain properties to run transactions. The samples provided in the <main directory>/samples/nvp and <main directory>/samples/xml folders read a file called cybs.properties into a Properties object which is passed to the runTransaction() method. Table 18 , Configuration Properties, describes the properties that you can set. Note that the default cybs.properties file that comes with the client package does not include all of the properties listed in the table. It includes only the ones required to run the sample.
The client also includes additional property configuration capabilities. For example, you can configure for multiple merchants or configure using system properties. For more information, see Advanced Configuration Information.
|
|
For Java SDK 1.4.x, the client sets the system properties https.proxyHost and https.proxyPort to the values of the client properties proxyHost and proxyPort. If these system properties are defined beforehand, possibly by using the -D option in the command line, the system properties will take precedence. |
|
Property |
Description |
|
This client uses this value if you do not specify a merchant ID in the request itself. This value is case sensitive. |
|
|
Location of the merchant’s security keys. Although UNC paths are allowed, for faster request processing, CyberSource recommends that you store your key locally. You must use forward slashes even in a Windows environment (for example: c:/keys). The client includes a keys directory that you can use. |
|
|
Flag that indicates whether the transactions for this merchant should be sent to the production server. Use one of these values: nfalse: Send to the test server. (default setting) ntrue: Send to the production server |
|
|
Version of the Simple Order API to use, such as 1.18. For the list of available versions, go to https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor. For transactions in India, go to https://ics2ws.in.ic3.com/commerce/1.x/transactionProcessor. Changes in each version are described in the Simple Order API Release Notes. Do not set this property to the current version of the client. See Client Versions, for more information. |
|
|
Name of the security key file name in the format <security_key_name>.p12. |
|
|
Alternative server URL to use. For more information, see Using Alternate Server Properties. Give the complete URL because it will be used exactly as specified here. |
|
|
Alternative namespace URI to use. Give the complete namespace URI because it will be used exactly as specified here. For more information, see Using Alternate Server Properties. |
|
|
Flag directing the client to log transactions and errors. Use one of these values: nfalse: Do not enable logging (default setting) ntrue: Enable logging Important Logging can cause very large log files to accumulate. Therefore, 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, card or check account numbers, and card verification numbers. For more information about PCI and PABP requirements, see www.visa.com/cisp. |
|
|
Directory to which to write the log file. UNC paths are allowed. You must use forward slashes even in a Windows environment, for example: c:/logs. The client does not create this directory; instead you must specify an existing directory. The client includes a logs directory that you can use. |
|
|
Log file name. The client uses cybs.log by default. |
|
|
Maximum size in megabytes for the log file. The default value is "10". When the log file reaches the specified size, it is archived into cybs.log.<yyyymmddThhmmssxxx> and a new log file is started. The xxx indicates milliseconds. |
|
|
Important Ignore this property. Instead set a specific amount of time that is acceptable to your business. Number of seconds to wait for reply before timing out. Default value is 130. This property does not have an effect if useHttpClient is false and you are using cybsclients14.jar. |
|
|
Flag directing the client to use Apache HttpClient for the HTTPS communication. Use one of these values: nfalse: (default setting) Do not use Apache HttpClient. Use built-in HttpURLConnection. The timeout property does not have an effect if useHttpClient is false and you are using cybsclients14.jar. ntrue: Use Apache HttpClient. When useHttpClient is true, your CLASSPATH must include the three commons-*.jar files shipped with the package. |
|
|
Optional host name or IP address of the HTTP proxy server. |
|
|
Port number of the proxy server. The default is 8080. This property is ignored if you do not specify proxyHost. |
|
|
User name used to authenticate against the proxy server if required. |
|
|
Password used to authenticate against the proxy server if required. |
The client tests and samples are configured to run with Maven. Before you test the client, update the client properties with your test merchant credentials (see Configuring Client Properties).
Running the SDK Integration Tests
To run the SDK integration tests:
Step 1Configure your merchant credentials in test_cybs.properties (<main directory>/src/test/resources).
Step 2Run mvn failsafe:integration-test from the main directory.
To run the samples:
Step 1Configure your merchant credentials in cybs.properties (<main directory>/samples/nvp or xml).
Step 2Run mvn exec:java from samples directory (<main directory>/samples/nvp or xml).
When you finish configuring and testing the client, your deployment is ready to go live.
|
|
Make sure that your client is set to send transactions to the production server, not the test server. See the description of sendToProduction. |
CyberSource Essentials Merchants
If you use CyberSource Essentials services, you can use the Business Center site to go live. For a description of the process of going live, see the “Steps for Getting Started” section in Getting Started with CyberSource Essentials.
|
|
You must also configure your client so that it sends transactions to the production server and not the test server. See the description of the sendToProduction property in Table 18 , Configuration Properties. |
After your deployment goes live, use real card numbers and other data to test every card type you support. Because these are real transactions in which you are buying from yourself, use small monetary amounts to do the tests. Process an authorization, then capture the authorization, and later refund the money. Use your bank statements to verify that money is deposited into and withdrawn from your merchant bank account as expected. If you have more than one CyberSource merchant ID, test each one separately.
CyberSource Advanced Merchants
If you use CyberSource Advanced services, see the “Steps for Getting Started” chapter in Getting Started with CyberSource Advanced for information about going live.
When your deployment goes live, your CyberSource account is updated so that you can send transactions to the CyberSource production server. If you have not already done so, you must provide your banking information to CyberSource so that your processor can deposit funds to your merchant bank account.
After CyberSource confirms that your account is live, make sure that you update your system so that it can send requests to the production server (ics2wsa.ic3.com or ics2ws.in.ic3.com in India) using your security keys for the production environment. The test server (ics2wstesta.ic3.com) cannot be used for real transactions. For more information about sending transactions to the production server. see the description of the configuration property sendToProduction.
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 in which you are buying from yourself, use small monetary amounts to do the tests. Use your bank statements to verify that money is deposited into and withdrawn from your merchant bank account as expected. If you have more than one CyberSource merchant ID, test each one separately.