On This Page
FILTER BY TAG

Installing and Testing the Client

Minimum System Requirements For Linux

  • Linux kernel 2.2, LibC6 on an Intel processor
  • GNU GCC compiler (with C++ enabled)

Minimum System Requirements For Windows

  • Windows XP, 2000, or newer
  • Microsoft Visual Studio 6.0
The SDK supports UTF-8 encoding.
Failure to configure your client API host to a unique, public IP address will cause 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.

Transaction Security Keys

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 ).
The Simple Order API client for C/C++ package includes the
ca-bundle.crt
, a bundle of certificate files. The client expects to find the
ca-bundle.crt
 file in the same directory as your security keys. If you decide to move it elsewhere, use the sslCertFile configuration parameter to specify the file’s location (see the description of sslCertFile).
You must protect your security key to ensure that your
Cybersource
 account is not compromised.

Install the Client

  1. Go to the client downloads page on the Support Center.
  2. Download the latest client package, and save it in any directory.
  3. Unpack the file. This creates an installation directory called
    simapi-c-n.n.n
    , where
    n.n.n
     is the client version. The client is now installed on your system.
  4. Configure the client. See Configuring Client Settings below.
  5. Test the client. See Testing the Client.

RESULT

You have installed and tested the client. You are ready to create your own code for requesting
Cybersource
 services. Finish reading this section, and then move on to either Using Name-Value Pairs, if you plan to use name-value pairs, or Using XML, if you plan to use XML.

Configuring Client Settings

To run the sample code included in the client package, you must set the configuration parameters in the
cybs.ini
 file, which is located in the installation directory. You can also use this file when running transactions in a production environment (see the function descriptions in C/C++ API for the Client). The table below describes the parameters that you can set. Note that the default
cybs.ini
 file that comes with the client package does not include all of the parameters listed in the table below. It includes only the ones required to run the sample code.
If you have multiple merchant IDs, or if you are a reseller handling multiple merchants, you can use different configuration settings depending on the merchant ID. See Configuring for Multiple Merchant IDs, for more information.
Configuration Settings
Setting
Description
merchantID
Merchant ID. This client uses this value if you do not specify a merchant ID in the request itself.
keysDirectory
Location of the merchant’s security keys for the production and the test environments. The client includes a
keys
 directory that you can use.
We recommend that you store your key locally for faster request processing.
sendToProduction
Flag that indicates whether the transactions for this merchant should be sent to the production server. Use one of these values:
  • false
    : Do not send to the production server; send to the test server (default setting).
  • true
    : Send to the production server.
targetAPIVersion
Version of the Simple Order API to use, for example:
1.18
. Do not set this property to the current version of the client; set it to an available API version. See Client Versions for more information.
Go to https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor to see a current list of the available versions. For transactions in India, go to https://ics2ws.in.ic3.com/commerce/1.x/transactionProcessor.
keyFilename
Name of the security key filename for the merchant in the format

<
key_fileName
>
.
p12
.
serverURL
Alternate server URL to use. See Using Alternate Server Configuration Settings for more information. Give the complete URL because it will be used exactly as you specify here.
namespaceURI
Alternate namespace URI to use. See Using Alternate Server Configuration Settings for more information. Give the complete namespace URI, as it will be used exactly as you specify here.
enableLog
Flag directing the client to log transactions and errors. Possible values:
  • false
    : Do not enable logging (default setting).
  • true
    : Enable logging.
    Logging can cause very large log files to accumulate. Therefore, we recommend 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:
    • Use debugging temporarily for diagnostic purposes only.
    • If possible, use debugging only with test credit card numbers.
    • Never store clear text card verification numbers.
    • Delete the log files as soon as you no longer need them.
    • Never 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.
logDirectory
Directory to which to write the log file. Note that the client will not create this directory for you; you must specify an existing directory. The client includes a
logs
 directory that you can use.
logFilename
Log file name. The client uses
cybs.log
 by default.
logMaximumSize
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
.<yyyymmdd
T
hhmmssxxx> and a new log file is started. The xxx indicates milliseconds.
sslCertFile
The location of the bundled file of CA Root Certificates (
ca-bundle.crt
) which is included in the client download package. The client automatically looks for the file in the directory where your security keys are stored (specified by keysDirectory). If you move the file so it does not reside in keysDirectory, use this configuration setting to specify the full path to the file, including the file name.
timeout
Length of timeout in seconds. The default is 110.
proxyServer
Proxy server to use. Allowable formats include:
  • <http://>server<:port>
  • <http://>IP address<:port>
    The
    http://
     and
    port
     are optional.
    The default port is 1080. If your proxy server is listening on another port, you must specify a port number.
proxyUsername
Username used to authenticate against the proxy server, if required. If the proxy server requires the domain name during authentication, add the domain name and a backslash: <domain>\<username>
proxyPassword
Password used to authenticate against the proxy server, if required.

Testing the Client

After you install and configure the client, test it immediately to ensure that the installation is successful.

Test the Client

  1. At a command prompt, go to the <installation directory>
    /samples/nvp
     directory.
  2. Run the sample program by typing
    authCaptureSample
    . The results of the test are displayed in the window.

RESULT

  • If the test is successful, a decision of ACCEPT appears for both the credit card authorization and the follow-on capture.
  • If the test is not successful, a different decision value or an error message appears.

Troubleshoot if The Test Fails

  1. Check to see that your
    cybs.ini
     settings are correct.
  2. Run the test again.
  3. If the test still fails, look at the error message and find the return status value (a numeric value from 0 to 8).
  4. See the descriptions of the status values in Possible Return Status Values, and follow any instructions given there for the error you received.
  5. Run the test again.
  6. If the test still fails, contact Customer Support.

Run the XML Sample

  1. At a command prompt, go to the <installation directory>
    /samples/xml
     directory.
  2. Run the sample program by typing
    authSample
    . The results of the test are displayed in the window.

RESULT

  • If the test is successful, a decision of ACCEPT appears for both the credit card authorization and the follow-on capture.
  • If the test is not successful, a different decision value or an error message appears.

Going Live

When you have completed all of your system testing and are ready to accept real transactions from your customers, your deployment is ready to
go live
.

Cybersource
 Essentials Merchants

If you use
Cybersource
 Essentials services, you can use the
Business Center
 site to go live.
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
 setting in Configuration Settings.
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 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 deployment 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 setting 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 merchant ID, test each one separately.

Updating the Client to Use a Later API Version

Cybersource
 periodically updates the Simple Order API (previously called the Web Services API). You can update your existing client to work with the new API version. Go to https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor for a list of the available API versions.
To update the client to use a later API version, update the value for the
targetAPIVersion
 configuration parameter. For example, to use the 1.18 version of the API, set the property to
1.18
.
RELATED TO THIS PAGE