|
|
|
|
|
|
Installing and Testing the Client
This chapter explains how to install, configure, and test the Simple Order API Client for PHP and includes these sections:
Updating the Client to Use a Newer API Version
Special Installation Instructions for Oracle Users
Your system must meet the following requirements.
• 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
• Windows® XP, 2000, or newer
• Minimum PHP version 4.2.1
The SDK supports UTF-8 encoding.
Important Failure to configure your client API host to a unique, public IP address will cause inconsistent transaction results.
CyberSource strongly recommends configuring your client API host to a unique, public IP address. Failure to do so 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 it is possible that this combination will not yield unique identifiers.
The first thing you need to 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 will specify the location of your key when you configure the client.
Important If you do not protect your security key, the security of your CyberSource account may be compromised.
The client package includes a certificate file called ca-bundle.crt. The client expects to find the ca-bundle.crt file in the same directory as your security key. If you decide to move it elsewhere, use the sslCertFile configuration parameter to specify the file’s location (see the description of sslCertFile in Table 1).
To generate your key, you log in to either the Business Center or the Enterprise Business Center, depending on which one you normally use. If you are not sure which one to use, see Who Should Read This Guide.
If you are a reseller using the Business Center, you can use the CyberSource Security Libraries for the Simple Order API to create keys on behalf of your merchants.
If you are a merchant using the Business Center, you create your security key by using a Java applet that you access through the Business Center. See Appendix A, Merchants Using the Business Center for instructions.
Enterprise Business Center Users
If you are an enterprise merchant using the Enterprise Business Center, you create your key by using a Java applet that you access through the Enterprise Business Center. See Merchants Using the Enterprise Business Center for instructions.
This section describes the steps for the Linux and Windows environment.
To install the client:
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.
Important 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 need to recreate them.
4 Copy the phpN_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.
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:
a Create an extension directory (outside of the client installation directory).
b Set "extension_dir" to that directory.
c Copy the phpN_cybersource.so file to that directory location.
4 If you are using an Oracle database, go to Special Installation Instructions for Oracle Users and follow the instructions.
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)
5 Save the php.ini file.
6 Modify the environment variable LD_LIBRARY_PATH to include the lib directory of the CyberSource client. For example:
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.
Note 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.
7 Configure the client. See Configuring Client Settings below.
8 Test the client. See Testing the Client.
You have now installed and tested the client. You are ready to create your own code for requesting ICS services. Finish reading this chapter, and then move on to either Chapter 4, Using Name-Value Pairs if you plan to use name-value pairs, or Chapter 5, Using XML if you plan to use XML.
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 phpN_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.
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:
a Create an extension directory (outside of the client installation directory).
b Set "extension_dir" to that directory.
c Copy the phpN_cybersource.dll file to that directory location.
4 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:
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)
5 Save the php.ini file.
6 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 now installed on your system.
7 Configure the client. See Configuring Client Settings below.
8 Test the client. See Testing the Client.
You have now installed and tested the client. You are ready to create your own code for requesting ICS services. Finish reading this chapter, and then move on to either Chapter 4, Using Name-Value Pairs if you plan to use name-value pairs, or Chapter 5, Using XML if you plan to use XML.
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 Chapter 3, 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 for more information.
|
Setting |
Description |
|---|---|
|
Merchant ID. The client uses this value if you do not specify a merchant ID in the request itself. |
|
|
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. Note We recommend that you store your key locally for faster request processing. |
|
|
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. Note Make sure that if your merchant ID is configured to use the test mode, you send requests to the test server. |
|
|
Version of the Simple Order API to use. Note For an up-to-date list of the available versions, go to https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/. For information about what has changed in each version, see the Simple Order API Release Notes. |
|
|
Name of the security key file name for the merchant if you have changed it from the default value of <merchantID>.p12. |
|
|
Alternate server URL to use. See Using Alternate Server Configuration Settings for more information. Give the complete URL, as it will be used exactly as you specify here. |
|
|
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. |
|
|
Flag directing the client to log transactions and errors. Use one of these values: • false: Do not enable logging (default setting). • true: Enable logging. Important CyberSource recommends that you use logging only when troubleshooting problems. If you turn on logging during production, the logs that are generated will not contain unmasked credit card or card verification number (CVV, CVC2, CVV2, CID, CVN) data. The logs will therefore be compliant with all Payment Card Industry (PCI) and Payment Application Best Practices (PABP) regulations regarding the storage of credit card and card verification number data. Follow these guidelines: • It is recommended that you use logging temporarily and for diagnostic purposes only. • If possible, use logging only with test credit card numbers. • Delete the log files as soon as you no longer need them. • Never email to CyberSource personal and account information, such as customers' names, addresses, card or check account numbers, and card verification numbers. For more information about PCI requirements, see www.visa.com/cisp. For more information about PABP requirements, see http://usa.visa.com/download/business/accepting_visa/ops_risk_management/cisp_Payment_Application_Best_Practices.pdf#search=%22visa.com%20pabp%22. |
|
|
Directory of 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. |
|
|
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. |
|
|
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. |
|
|
Length of time-out in seconds. The default is 110. |
|
|
Proxy server to use. Allowable formats include: • <http://>server<:port> • <http://>IP address<:port> The http:// and port are optional. Note The default port is 1080. If your proxy server is listening on another port, you must specify a port number. |
|
|
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> |
|
|
Password used to authenticate against the proxy server, if required. |
Once you have installed and configured the client, you should immediately test it to ensure the installation was successful.
To test the client:
1 Go to the <installation directory>/samples/nvp directory.
2 Run the test authCaptureSample.php script by typing:
php authCaptureSample.php
where php is the command-line interface (CLI) version. Depending on your 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 may have:
<PHP directory>/sapi/cli/php authCaptureSample.php
Or for PHP 4.3.8 with Windows, you may 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, 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.
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 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.
If you want to also 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
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.
When you have completed all of your system testing and are ready to accept real transactions from your customers, you are ready to go live.
If you are a Business Center user, you can use the Business Center site to go live (see the Business Center User’s Guide for more information).
Important 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 1.
After you go 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 amounts, such as one dollar, 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.
Enterprise Business Center Users
If you are an Enterprise Business Center user, use the procedure below to go live.
When you go live, your CyberSource account is updated so that you can send transactions to CyberSource’s production server. If you have not already done so, you will need to provide your banking information to CyberSource so that your processor can deposit funds to your merchant bank account.
To go live:
1 Go to the CyberSource Knowledgebase at http://www.cybersource.com/esupport.
2 Submit a question (click the Submit a Question link).
3 Log in with your CyberSource merchant ID and password (the same ones you use to log in to the Enterprise Business Center).
4 On the Submit a Question page, fill in the contact information.
5 For the General Topic, select Getting Set Up on CyberSource.
6 For the Specific Topic, select Go Live.
7 For the Subject, enter "Go Live".
8 In the question field, indicate that you would like to go live.
9 If you have not already submitted your banking information to CyberSource, include the information in the question field and select the check box for This question contains sensitive banking information.
10 Click Submit question.
You will receive an email with your support ticket number, and a CyberSource representative will contact you to complete the process.
11 Once CyberSource has confirmed that you are live, make sure to update your system so that you send requests to the production server and not the test server. See the description of the SendToProduction property in Table 1.
After you go 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 amounts, such as one dollar, 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.
Updating the Client to Use a Newer API Version
CyberSource will periodically update 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://ics2ws.ic3.com/commerce/1.x/transactionProcessor/ for a list of the available API versions. Or, if you are in test mode, go to https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/.
To update the client to use a newer 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
To meet these requirements, follow these instructions:
1 At a command prompt, go to your PHP directory.
2 Type the following:
make clean
3 Execute configure so that you are loading the Oracle extension(s) dynamically. To do this, include "shared," before the path to each Oracle extension. For example, you might execute configure as follows:
./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 the following:
make
make install
5 In the "Dynamic Extensions" section of the php.ini file, add the CyberSource extension before the Oracle extensions:
extension=phpN_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 6 on this page).
|
|
|
|
|
|