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 (for RedHat users, this currently corresponds to versions 7.1 and 7.2)
  • PHP4 (minimum version 4.2.1) or PHP5 (5.0.0–5.0.3 and 5.1.0-5.1.2)
  • GNU GCC

Minimum System Requirements For Windows

  • Windows XP, 2000, or newer
  • Minimum PHP version 4.2.1
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
Creating and Using Security Keys
.
The Simple Order API client for PHP 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 move it elsewhere, use the sslCertFile configuration parameter to specify the file location. For more information, see the description of the parameter sslCertFile.
You must protect your security key to ensure that your
Cybersource
 account is not compromised.

Installing the Client

This section describes the installation steps for Linux and Windows environments.

Install the Client on Linux

  1. Go to the client downloads page on the Support Center.
  2. Download the latest client package. You can save the file in any directory.
  3. Unzip and untar the package. This creates a directory called
    simapi-php-n.n.n
    , where
    n.n.n
     is the client version.

    ADDITIONAL INFORMATION

    The
    simapi-php-n.n.n/lib
     directory contains symbolic links. If you install the client by copying the
    lib
     directory from some other location where you untarred the package, check to see if the symbolic links are still there. If they are not, you must recreate them.
  4. Copy the
    php
    N
    _cybersource.so
     file into the PHP extension directory, where the N is 4 if your PHP version is 4.x.x; 5 if your PHP version is 5.0.0-5.0.2; 503 if your PHP version is 5.0.3.; or 512 if your version is 5.1.0-5.1.2.
  5. The extension directory is the one
    "extension_dir"
     is set to in the
    php.ini
     file. If you do not already have
    "extension_dir"
     set to an explicit directory:
    Create an extension directory (outside of the client installation directory).
    Set
    "extension_dir"
     to that directory.
    Copy the
    php
    N
    _cybersource.so
     file to that directory location.
  6. If you are using an Oracle database, go to Special Installation Instructions for Oracle Users and follow the instructions.

    ADDITIONAL INFORMATION

    Otherwise, in the
    php.ini
     file, locate the “Dynamic Extensions” section and add one of the following lines anywhere before the next section in the file:
    extension=php4_cybersource.so
     (if using PHP 4.x.x) or
    extension=php5_cybersource.so
     (if using PHP 5.0.0-5.0.2)
    extension=php503_cybersource.so
     (if using PHP 5.0.3) or
    extension=php512_cybersource.so
     (if using PHP 5.1.0-5.1.2)
  7. Save the
    php.ini
     file.
  8. Modify the environment variable LD_LIBRARY_PATH to include the
    lib
     directory of the Cybersource client. For example:

    ADDITIONAL INFORMATION

    export LD_LIBRARY_PATH=/baseDir/simapi-php-n.n.n/lib:$LD_LIBRARY_PATH
    where
    /baseDir
     is the directory where you untarred the Cybersource client package.
    If the web server is running as the user "nobody", you must use
    ldconfig
     instead of setting the LD_LIBRARY_PATH. In this case, update the
    /etc/ld.so.conf
     file to include the library path (
    /baseDir/simapi-php-n.n.n/lib
    ), and run
    ldconfig
     to update the configuration.
  9. Configure the client. See Configuring Client Settings below.
  10. Test the client. See Testing the Client.

Install the Client on Windows

  1. Go to the client downloads page on the Support Center.
  2. Download the latest client package. You can save the file in any directory.
  3. Unzip the package. This creates a directory called
    simapi-php-n.n.n
    , where
    n.n.n
     is the client version.
  4. Copy the
    php
    N
    _cybersource.dll
     file into the PHP extension directory, where the N is 4 if your PHP version is 4.x.x, or 5 if your PHP version is 5.x.x.

    ADDITIONAL INFORMATION

    The extension directory is the one
    "extension_dir"
     is set to in the
    php.ini
     file. If you do not already have
    "extension_dir"
     set to an explicit directory:
    Create an extension directory (outside of the client installation directory).
    Set
    "extension_dir"
     to that directory.
    Copy the
    php
    N
    _cybersource.dll
     file to that directory location.
  5. In the
    php.ini
     file, locate the “Windows Extensions” section and add one of the following lines anywhere before the next section in the file:

    ADDITIONAL INFORMATION

    extension=php4_cybersource.dll
    (if using PHP 4.x.x) or
    extension=php5_cybersource.dll
    (if using PHP 5.0.0–5.0.2)
    extension=php503_cybersource.dll
    (if using PHP 5.0.3) or
    extension=php512_cybersource.dll
    (if using PHP 5.1.0-5.1.2)
  6. Save the
    php.ini
     file.
  7. Add the
    lib
     directory of the
    Cybersource
     client package to the system PATH. This makes the DLLs included in the client package available to the
    Cybersource
     PHP extension. The client is installed on your system.
  8. Configure the client. See Configuring Client Settings below.
  9. Test the client. See Testing the Client.

Configuring Client Settings

To run the sample scripts included in the client package, you must set the configuration parameters in the
cybs.ini
 file, which is located in the <installation directory>
/samples
 directory for Linux, and in the
nvp
,
xml
, and
store
 subfolders inside the
samples
 directory for Windows. You can also use this file when running transactions in a production environment (see the function descriptions in PHP API for the Client). The following table describes the parameters that you can set. The default
cybs.ini
 file that comes with the client package does not include all of the parameters listed in the table. The file includes only the parameters required to run the sample scripts.
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 Your Settings for Multiple Merchant IDs for more information.
Configuration Settings
Setting
Description
merchantID
Merchant ID. The client uses this value if you do not specify a merchant ID in the request itself.
keysDirectory
Location of the merchant’s security key. The client includes a
keys
 directory that you can use. Include the path, for example:
../keys
, or
c:\simapi-php-1.0.0\keys
.
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.
    Make sure that if your merchant ID is configured to use the test mode, you send requests to the test server.
targetAPIVersion
Version of the Simple Order API to use.
For a current list of the 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.
keyFilename
Name of the security key file name for the merchant in the format
<
security_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 because it will be used exactly as you specify here.
enableLog
Flag directing the client to log transactions and errors. Use one of these 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. Include the path, for example:
../logs
, or
c:\simapi-php-1.0.0\logs
.
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 key is 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 time-out 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 was successful.

Test the Client

  1. Go to the <installation directory>
    /samples/nvp
     directory.
  2. Run the test
    authCaptureSample.php
     script by typing: php authCaptureSample.php

    ADDITIONAL INFORMATION

    where php is the command-line interface (CLI) version. Depending on the PHP version, php may be in the main PHP directory, the
    sapi/cli
     directory, the
    cli
     directory, or it may be named
    php-cli.exe
     or
    php.exe
    .
    For example, for PHP 4.3.0 with Linux, you might have:
    <PHP directory>/sapi/cli/php authCaptureSample.php
    Or for PHP 4.3.8 with Windows, you might have:
    <PHP directory>\cli\php authCaptureSample.php
    or
    <PHP directory>\php.exe authCaptureSample.php
    The results of the test are displayed in the window.
    • 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 Client Test Failures

  1. Verify that your
    cybs.ini
     settings are correct.
  2. Run the test again.
  3. If the test still fails, look at the error message and determine the return status value (a numeric value from -1 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. Go to the <installation directory>
    /sample/xml
     directory.
  2. For Windows, modify the
    cybs.ini
     in the folder with your settings (for Linux, make sure the
    samples/cybs.ini
     file is set how you want it).
  3. Run the test
    authSample.php
     script by typing: php authSample.php

    ADDITIONAL INFORMATION

    The results of the test are displayed in the window.
    • If the test is successful, you see a decision of ACCEPT for both the credit card authorization and the follow-on capture.
    • If the test is not successful, you see a different decision value or an error message. See Troubleshoot Client Test Failures to troubleshoot the error.

RESULT

The client is installed and tested. You are ready to create your own code for requesting
Cybersource
 services. For information about creating requests, see Using Name-Value Pairs if you plan to use name-value pairs, or Using XML if you plan to use XML.

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
.
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
 Essentials Merchants

If you use
Cybersource
 Essentials services, you can use the
Business Center
 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.
Configure your client so that it can send transactions to the production server and not the test server. For more information, see the description of the configuration setting sendToProduction.

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
 has confirmed 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 key 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.

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. For transactions in India, go to https://ics2ws.in.ic3.com/commerce/1.x/transactionProcessor. Or, if you are in test mode, go to https://ics2wstesta.ic3.com/commerce/1.x/transactionProcessor.
To update the client to use a later API version, update the value for the
targetAPIVersion
 configuration parameter in the
cybs.ini
 file. For example, to use the 1.18 version of the API, set the property to
1.18
.

Special Installation Instructions for Oracle Users

If you are using Linux and an Oracle database, you must:
  • Load the Oracle extensions dynamically
  • In the
    php.ini
     file, load the
    Cybersource
     extension before the Oracle extensions

Load Oracle Extensions Dynamically After the
Cybersource
 Extension

  1. At a command prompt, go to your PHP directory.
  2. Type
    make clean
    .
  3. Execute configure so that you are loading the Oracle extensions dynamically. To do this, include “shared,” before the path to each Oracle extension. For example, you might execute configure as follows:

    ADDITIONAL INFORMATION

    ./configure --prefix=<target PHP directory>

--with-apxs=/usr/local/apache_1.3.32/bin/apxs

--with-oracle=shared,/home/u01/app/oracle/product/8.1.7

--with-oci8=shared,/home/u01/app/oracle/product/8.1.7

--without-mysql
  4. Type:

    ADDITIONAL INFORMATION

    make
make install
  5. In the “Dynamic Extensions” section of the
    php.ini
     file, add the
    Cybersource
     extension before the Oracle extensions:

    ADDITIONAL INFORMATION

    extension=php
    N
    _cybersource.so
     (where N represents the version of PHP: 4, 5, 503, or 512)
    extension = oracle.so
    extension = oci8.so
  6. Save the
    php.ini
     file.
  7. Continue with the original installation instructions (see Step 7 in Installing the Client).
RELATED TO THIS PAGE