Chapter 1

Introduction

This chapter provides an introduction to the CyberSource Simple Order API Client for PHP. The chapter includes these sections:

Who Should Read This Guide

Other Necessary Documentation

This section lists documents that you need to integrate with CyberSource.

General Documentation

This documentation is available in the client package download:

• README file

• CHANGES file

• Sample code files (see Sample Code Available)

Business Center Users

For merchants and resellers using the Business Center, the Business Center Simple Order API User’s Guide describes the API for using the CyberSource ICS services for payment processing. This and other related documentation is available in the Business Center.

Enterprise Business Center Users

If you use the Enterprise Business Center, you need these guides:

• Credit Card Services Implementation Guide: Describes the API for using the CyberSource ICS Credit Card Services. Make sure when you read this guide that you read the Simple Order API chapter, not the SCMP API chapter.

• Reporting Developer’s Guide: Describes how to download the CyberSource reports that you will be using to manage your orders.

• Implementation guides for any other ICS services that you are planning to use. These are available in the documentation area of the Support Center.

Important The Simple Order API was originally referred to as the Web Services API in the CyberSource documentation. You may still see old references to the Web Services API in some locations.

Using PHP in a Hosted Environment

If you are operating in a hosted environment (with an Internet Service Provider hosting your Web store), read this section.

To use the CyberSource Simple Order API client for PHP, you must register a PHP extension in php.ini and modify the LD_LIBRARY_PATH (for Linux) or the system PATH (for Windows) to include the lib directory of the CyberSource client. The CyberSource binaries ensure that your transactions are secure while being sent to CyberSource. If you use a hosted environment, you must check with your hosting provider (ISP) to make sure that they support the addition of a PHP extension and editing of the path environment variables.

If you cannot find any documentation related to your hosting provider's support of extensions and new library locations, contact your hosting provider with this statement:

CyberSource requires modifying php.ini to add their extension and editing of LD_LIBRARY_PATH (for Linux) or the system PATH (for Windows) to add the directory containing the dynamic libraries required by the extension for use by my e-commerce software. CyberSource ensures the safety and functionality of these libraries. Please let me know your policy for supporting this implementation.

Because other merchants who use your hosting provider may also use CyberSource, your hosting provider may have already installed the CyberSource PHP client. In that case, we suggest that you verify with your hosting provider the version of the client they have installed and registered. If the client you want to use is newer, ask them to replace the libraries with the new ones.

If you have any questions regarding the above information or installation of the client, please contact Customer Support. If you are a Business Center user, and you cannot obtain the appropriate access from your ISP to install the client, consider using CyberSource’s Hosted Order Page or Simple Order Post instead of the PHP client. These connection methods are described in the Hosted Order Page User’s Guide and the Silent Order Post User’s Guide, both of which are available in the Business Center.

Choosing Your API and Client Version

You need to choose an API and a client.

API Variation

With this client package, you can use either of these variations of the Simple Order API:

• Name-value pairs, which are simpler to use

• XML, which requires you to create and parse XML documents

The test that you run immediately after installing the client uses name-value pairs.

Client Versions

CyberSource regularly updates the Simple Order API to introduce new API fields and functionality. To determine the latest version of the server-side API for the ICS services, go to https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/.

The Simple Order API Client for PHP also has a version, but it is not the same as the API version. The client version represents the version of the client-side code that you use to access the ICS services.

When configuring the client, you indicate the version of the API that you want to use. When setting this parameter, do not use the current version of the client; use the current version of the API.

Sample Code Available

The client contains sample scripts and sample PHP pages.

Basic PHP Page Example

Creating a Web page that uses PHP to access ICS services is easy. The example below shows the primary code required to send a Simple Order API request for credit card authorization. The example uses name-value pairs. For a more complete example, see the sample program and sample PHP pages included in the package (see Sample Code Available). Chapter 4, Using Name-Value Pairs shows you how to create the code.

// Load the configuration settings

$config = cybs_load_config( 'cybs.ini' );

// set up the request by creating an array and adding fields to it

$request = array();

// We want to do credit card authorization in this example

$request['ccAuthService_run'] = "true";

// Add required fields

$request['merchantID'] = 'infodev';

$request['merchantReferenceCode'] = 'MRC-14344';

$request['billTo_firstName'] = 'Jane';

$request['billTo_lastName'] = 'Smith';

$request['billTo_street1'] = '1295 Charleston Road';

$request['billTo_city'] = 'Mountain View';

$request['billTo_state'] = 'CA';

$request['billTo_postalCode'] = '94043';

$request['billTo_country'] = 'US';

$request['billTo_email'] = 'jsmith@example.com';

$request['card_accountNumber'] = '4111111111111111';

$request['card_expirationMonth'] = '12';

$request['card_expirationYear'] = '2010';

$request['purchaseTotals_currency'] = 'USD';

// This example has two items

$request['item_0_unitPrice'] = '12.34';

$request['item_1_unitPrice'] = '56.78';

// Add optional fields here according to your business needs

// Send request

$reply = array();

$status = cybs_run_transaction( $config, $request, $reply );

// Handle the reply. See Handling the Return Status.

Sample Scripts

The client contains two sample scripts, one for using name-value pairs and one for using XML. See Testing the Client or see the README file for more information about using the authCaptureSample.php script to test the client.

• Name-value pairs: See authCaptureSample.php in <installation directory>/samples/nvp.

• XML: We suggest that you examine the name-value pair sample code listed above before implementing your code to process XML requests.

For the XML sample code, see authSample.php in <installation directory>/samples/xml. Also see the auth.xml XML document that the script uses.

Sample PHP Pages

The client download package also includes sample PHP pages in the <installation directory>/samples/store directory.

**Table 1** Files in sampleStore Directory
File	Description
util.php	Used by the other PHP pages in the directory.
checkout.php	Displays the contents of the shopping basket and prompts for address and payment information.
checkout2.php	Authorizes the order and displays the result.
store_footer.php	Footer used in the checkout pages.
store_header.php	Header used in the checkout pages.

To use the sample PHP pages:

1 If you have files in your Web server’s root directory that have the same name as the files listed in Table 1, back up those files.

You will be copying the sample store files into the root directory in the next step. For Apache, the root directory is the one specified by DocumentRoot in httpd.conf.

2 Copy all of the files in the <installation directory>/samples/store directory into your Web server’s root directory.

3 Modify the cybs.ini file as appropriate (see Configuring Client Settings).

Important Make sure you use absolute paths for the directories in the cybs.ini file that you use with the sample store, for example: keysDirectory=c:\keys.

If you encounter problems getting the sample PHP pages to work, you may need to locate your cybs.ini file outside of the root directory.

4 Open the checkout.php file in a text editor and locate the cybs_load_config() function.

5 Make sure that the parameter for the cybs.ini file passed to the function includes the absolute path. For example, make sure the line reads:

$config = cybs_load_config( 'c:\cybs.ini' );

not this line:

$config = cybs_load_config( 'cybs.ini' );

6 Restart your Web server.

If you are using IIS, you may need to restart you computer for IIS to pick up the new server path.

7 Open a Web browser and type the following URL:

http://<your web server name or IP address>/<virtual directory if applicable>/checkout.php