Installing and Configuring the SDK

To install the SDK, you must first download the SDK file and then run an installation program included in the package. The installation procedure varies depending on if you are a new customer or if you are upgrading the SDK from a previous version.

Minimum System Requirements

nOne of these operating systems:

lLinux kernel 2.2, libc 6 with Intel

lSolaris 2.6 operating system on SPARC

lWindows NT 4.0 with Intel

n20 MB of disk space

nA utility to uncompress the distribution file

The SDK supports ISO-8859-1 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 C/C++, this configuration parameter is the ics.host_id entry in the configuration file. The value must not be 127.0.0.1, which is the loopback address of your localhost.

Downloading the SDK

To download the SDK:

Step 1Create a target directory.

Step 2Download the latest SDK package file from the downloads area of the CyberSource Support Center.

Step 3Unzip/untar the package to your target directory.

Unzipping and untarring the original SDK package installs several directories and files in your target directory. The installation program then creates a new directory and copies most of the files from your target directory into this new directory. However, the following files are not copied and exist only in your target directory: README.txt, CHANGES.txt, and LICENSE.txt. Copy the files to the new directory where the SDK is installed so that you can later delete your target directory.

Installing the SDK for the First Time

If you are a new customer and do not have a previous version of the C/C++ SDK installed, simply run the installation program.

Linux and Solaris

Type sh install.sh

The default installation path is /opt/CyberSource/SDK.

To install the SDK to a different directory, enter the path when prompted during the installation.

To install the SDK to an alternate directory, you must set the ICSPATH environment variable to indicate the alternate location of the SDK. For example, set ICSPATH to /opt/ics.

Windows

Type this with your CyberSource merchant ID:

install.bat myMerchantID

The default installation path is c:\opt\CyberSource\SDK\.

To install the SDK to a different directory, type

install.bat myMerchantID path

If you install the SDK to an alternate directory, you must set the ICSPATH environment variable to indicate the alternate location of the SDK. For example, set ICSPATH to \opt\ics.

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).

The client looks for the certificate and private key files in
/opt/CyberSource/SDK/keys by default. To store your keys in a different directory, set an ICSPATH environment variable. The client automatically adds /keys and looks for the keys in the $ICSPATH/keys location. For example, when you set ICSPATH to myDirectory, the client looks for the keys in myDirectory/keys folder.

Upgrading the SDK

To upgrade an existing SDK installation:

Step 1Rename the directory containing your previous SDK installation.

For example, rename opt/CyberSource/SDK to opt/CyberSource/oldSDK.

Step 2Run the installation program:

nLinux and Solaris: type sh install.sh

The default installation path is /opt/CyberSource/SDK. To install the SDK to a different directory, you can enter the path when prompted during the installation.

To install the SDK to an alternate directory, you must set the ICSPATH environment variable to indicate the alternate location of the SDK. For example, set ICSPATH to /opt/ics.

nWindows: type (including your merchant ID) install.bat myMerchantID

The default installation path is c:\opt\CyberSource\SDK\. To install the SDK to a different directory, type install.bat myMerchantID path.

To install the SDK to an alternate directory, you must set the ICSPATH environment variable to indicate the alternate location of the SDK. For example, set ICSPATH to \opt\ics.

Step 3Copy your original key files from the old keys directory to the new keys directory (overwriting any files in the new keys directory).

For example, copy all the files from /CyberSource/oldSDK/keys/ to
opt/CyberSource/SDK/keys/.

Step 4When you are confident that the new SDK is working, delete the oldSDK directory.

Parts of the SDK

The C/C++ SDK includes the directories and files listed in this table.

Directory or file	Description
bin	Contains the ECert program that creates your certificate and private keys. Transaction security keys can also be generated in the Business Center. For more information, see Creating and Using Security Keys (PDF \| HTML).
include	Contains the header file ics.h.
keys	Contains your certificate and private keys.
lib	Contains the C libraries.
sample	Contains test programs (in the icstest directory) and sample requests (in the requests directory). icstest: Runs a sample transaction. Use to test the SDK installation. mt_test: Reads request data from a text file and sends the request. Troubleshoots problems with sending requests. Use with the sample requests or your own requests, for example: mt_test ../requests/ics_auth.txt
CHANGES.txt	Describes the changes in this and previous versions of the SDK.
LICENSE.txt	Contains CyberSource software license information.
README.txt	Contains information about SDK installation, shared libraries, C++ support, supported platforms, and test transactions.
install.sh	Sets up the SDK file structure, installs the libraries, and runs the ECert application.

Creating the Configuration File

You can create a configuration file that stores fields that you need for every request. Use the configuration file as an alternative to specifying the values for these fields in the request.

You can give the file any name and store it in any directory. Specify the file name and path by using the ics_set_config_file() function. The function tells the request to look for a configuration file to retrieve these particular field values. See ics_set_config_file() Function for more information.

These are the fields that you can include in the configuration file:

ndebug — enables debug output. See ics_init() Function for more information about debugging.

nics.host_id — local IP address to use for generating a request ID

nics.http_proxy — URL for CyberSource HTTP proxy

nics.http_proxy_password — your password for CyberSource HTTP proxy

nics.http_proxy_username — your username for CyberSource HTTP proxy

nics.merchant_id — your merchant ID

nics.server_host — default CyberSource server name

nics.server_port — default CyberSource server port

To create a configuration file, create a text file that includes the configuration parameters in a name-value pair format, for example:

debug=0

ics.merchant_id=MyMerchantID

ics.server_host=ics2a.ic3.com

ics.server_port=80

Testing the SDK Installation

To test the SDK installation:

Step 1Open a command prompt.

Step 2Go to the sample/icstest directory in the SDK.

Step 3Run the test program:

For Linux and Solaris, type ./icstest merchant_id

For Windows, type icstest merchant_id

If you successfully installed and configured the SDK, the following message appears: successful ICS order, rcode = 1.

If you do not receive this message, verify that your ICSPATH variable is set correctly, and that your key files are in the correct location.

Using the mt_test Program

You may also create and send your own requests by using the mt_test program. The SDK contains several sample requests that you can use with the program (see the sample/requests directory).

If you provided a merchant ID when you installed the SDK, the request text files were automatically updated with your merchant ID. If you did not provide a merchant ID during installation, edit the line in the ics_auth.txt file that sets your merchant ID.

When in test mode, send your requests to the test server ics2test.ic3.com and use port 80. See the sample requests for examples.

To use the mt_test program with the ics_auth.txt sample request:

Step 1Open a command prompt.

Step 2In the directory where you installed the SDK, go to the sample/icstest directory.

Step 3Type ./mt_test ..requests/ics_auth.txt

The test results appear in the window.

Going Live

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.