Installing and Testing the Client

Minimum System Requirements

nMicrosoft Windows 2000 or later

n.NET Framework 4.0 or later

nMicrosoft Visual Studio 2010

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 (PDF | HTML).

You must protect your security key to ensure that your CyberSource account is not compromised.

Installing the Client

The .NET SDK is available to install from GitHub:

https://github.com/CyberSource/cybersource-sdk-dotnet

Using the NuGet Package Manager

CyberSource recommends using the NuGet Package Manager to install the .NET SDK.

Run the following command in the NuGet Package Manager console:

PM> Install-Package CyberSource

Installing Individual Files

The .NET SDK files are available to download independently from GitHub:

https://github.com/CyberSource/cybersource-sdk-dotnet/releases

To install the files individually:

Step 1Download the latest zip file. The current version is cybersource-sdk-dotnet-1.0.0.zip.

Step 2Extract the contents of the zip file to an appropriate location.

Step 3Add CyberSource.Base.dll and CyberSource.Clients.dll to your project references.

Upgrading from a Previous Version

The .NET 4.0 or later Simple Order API client is a pure .NET client without dependencies outside of the .NET 4.0 or later Framework. It is simplified in comparison to previous Simple Order API .NET clients because it does not require the Microsoft Web Services Enhancements (WSE) and it does not use the CyberSource security libraries.

Previous versions of the Cybersource.Clients.dll required that you register CybsWSSecurity.dll as a COM object. The CybsWSSecurity.dll had dependencies on many other dynamic-link libraries (DLLs). Because the .NET 4.0 or later Simple Order API client does not use the CyberSource security libraries, you can remove or unregister the following DLLs:

nCybsWSSecurity.dll (unregister)

nCybsWSSecurityIOP.dll

nCyberSource.WSSecurity.dll

ndomsupport_1_4_0.dll

nMsvcp60.dll

nplatformsupport_1_4_0.dll

nspapache.dll

nxalandom_1_4_0.dll

nxalansourcetree_1_4_0.dll

nxerces-c_2_1_0.dll

nxercesparserliaison_1_4_0.dll

nxmlsupport_1_4_0.dll

nxpath_1_4_0.dll

Migrating from .NET Framework 1.x

To migrate from a .NET Framework 1.x client:

Step 1Replace the old DLLs with the ones from this package.

Step 2In your project, remove references to the previous CyberSource DLLs.

Step 3Add a reference to CyberSource.Clients.dll.

Step 4In your request code, make the following changes:

aReplace the referenced CyberSource namespaces with this one:

CyberSource.Clients

bIf you use the SOAP client, add the following namespace:

CyberSource.Clients.SoapWebReference

Example In C#, with the SOAP client, you now have:

using CyberSource.Clients.

using CyberSource.Clients.SoapWebReference; /* for SOAP client only */

Step 5Follow the instructions for migrating from .NET Framework 2.X.

Migrating from .NET Framework 2.x

To migrate from a .NET Framework 2.x client:

Step 1Follow the installation instructions in Installing the Client.

Step 2Open your project in Visual Studio 2010. If necessary, use the conversion wizard to update your project from Visual Studio 2005 to Visual Studio 2010.

Step 3In your project properties, set the target framework to .NET Framework 4.

Step 4Make sure that your reference to CyberSource.Clients points to the new .NET 4.0 or later version of the DLL. You must use the DLLs that you installed in Step 1.

Step 5Remove references to System.Web.Services and remove the following namespace from your code:

using System.Web.Services.Protocols

Step 6If your code contains catch statements that use SignException, change them to use CryptographicException instead. Making this change requires that you add a reference to System.Security and add the following namespace to your code:

using System.Security.Cryptography

nFor SOAP and name-value pair (NVP) clients only:

Remove any catch statements that use SoapHeaderException or SoapBodyException.

nFor SOAP clients only:

Consider replacing these exceptions with appropriate Windows Communication Foundation (WCF) services exceptions such as MessageSecurityException, EndpointNotFoundException, or ChannelTerminatedException depending on your requirements. Then you must add a reference to System.ServiceModel and add the following namespaces to your code:

using System.ServiceModel;

using System.ServiceModel.Security;

You have successfully upgraded your client to the new version.

Testing the Client

See the “Running the Samples” section on GitHub:

https://github.com/CyberSource/cybersource-sdk-dotnet#running-the-samples

Once you have tested the client, you are ready to create your own code to request the CyberSource services. Depending on which API you are using, see:

nUsing Name-Value Pairs.

nUsing XML.

nUsing SOAP.

Using the Test Applications

Each type of client variation—name-value pair, XML, and SOAP—includes a pre-compiled test application. You can use these test applications to ensure that the client was installed correctly. The applications request both credit card authorization and capture.

The test applications and their source code are installed in the samples directory. The bin subdirectory contains the pre-compiled binaries. The src subdirectory contains the source code and Visual Studio project files.

Configuring the Test Applications

Before you run a test application, you must edit its application settings file. The following table describes all the configuration fields that you can use in this file.

Configuration settings supported by the latest 1.x.x version are still supported. However, CyberSource recommends that you use the following new settings for this and future versions.

Table 17Fields in the Settings File
Field Name	Description	Required/Optional
cybs.connectionLimit	Maximum number of allowed concurrent connections between the client and CyberSource’s server. For more information on this field and alternate ways to set the connection limits, see Setting the Connection Limit.	Optional
cybs.keysDirectory	Directory that contains the pkcs12 security key file. For example: c:\keys\	Required
cybs.merchantID	Your CyberSource merchant ID. You can override this value by providing the merchantID field in the request itself. The merchant ID is case sensitive.	Optional
cybs. sendToProduction	Flag that indicates whether the transactions for this merchant should be sent to the production server. Use one of these values: nfalse: Do not send to the production server; send to the test server (default setting). ntrue: 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.	Required
cybs.keyFilename	Name of the security key file name for the merchant in the format <security_key_filename>.p12.	Optional
cybs.serverURL	Alternate server URL to use. For more information, see Configuring Your Settings for Multiple Merchants. Give the complete URL because it will be used exactly as you specify.	Optional
cybs.enableLog	Flag directing the client to log transactions and errors. Use one of these values: nfalse: Do not enable logging (default setting). ntrue: Enable logging. Important Logging can cause very large log files to accumulate. Therefore, CyberSource recommends 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: nUse debugging temporarily for diagnostic purposes only. nIf possible, use debugging only with test credit card numbers. nNever store clear text card verification numbers. nDelete the log files as soon as you no longer need them. nNever 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.	Optional
cybs.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: c:\simapi-net-2.0.0\logs.	Required if cybs. enableLog is true
cybs.logFilename	Name of the log file. The client uses cybs.log by default.	Optional
cybs.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.<yyyymmddThhmmssxxx> and a new log file is started. The xxx indicates milliseconds.	Optional
cybs.timeout	Length of time-out in seconds. The default is 130.	Optional
cybs.proxyURL	URL of a proxy server. For example: https://proxy.example.com:4909	Optional
cybs.proxyUser	User name for the proxy server.	Optional
cybs.proxyPassword	Password for the proxy server.	Optional

To test applications:

Step 1Decide which test application you want to run, such as SoapSample.exe.

Step 2Using a text editor, open the settings file for the test application.

The settings file has the same name as the test application, with the extension config appended to the name. For example, SoapSample.exe.config.

Step 3Find the cybs.merchantID field and change its value to your CyberSource merchant ID.

For example, if your merchant ID is widgetsinc, change the field to
<add key="cybs.merchantID" value="widgetsinc"/>.

The merchant ID is case sensitive.

Step 4Find the cybs.keysDirectory field and change its value to the directory that contains your security key.

For example, if your key is in c:\keys\, change the field to
<add key="cybs.keysDirectory" value="c:\keys\"/>.

Step 5Edit other fields as necessary.

See Table 17 , Fields in the Settings File, for a complete list.

Step 6Save and close the settings file.

Configuring Your Settings for Multiple Merchants

If you have multiple merchant IDs, or if you are a reseller handling multiple merchants, you can configure the settings to allow different configurations for different merchant IDs.

To specify the settings for a specific merchant, prefix all settings, except for cybs.merchantID and the cybs.proxy*, with <merchantID>. The cybs.proxy* wildcard refers to the proxyURL, proxyUser, proxyPassword settings.

Example You have a new merchant with merchant ID of NewMerchant. To send only test transactions for this merchant, you can set all requests for NewMerchant to go to the test server:

With the second line of the example, the client will send all other requests to the production server.

Running the Test Applications

To run test applications:

Step 1Open a Windows command-line shell.

Step 2Change to the directory where the test application is located.

Step 3Type the name of the test application, then press Enter.

The test application requests an CyberSource service, interprets the reply, and prints information about the result. If you receive a .NET exception, use the error message to debug the problem.

Deploying the Client to Another Computer

To deploy the client to another computer without running the installer provided by CyberSource, you must include all the files from the lib directory in your custom installer and then run it. Then the client is ready to be used on the computer.

Going Live

When you complete all of your system testing and are ready to accept real transactions from consumers, 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 site 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.

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 configuration setting cybs. sendToProduction.

CyberSource Advanced Merchants

If you use CyberSource Advanced services, see the “Steps for Getting Started” chapter in 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 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 cybs. sendToProduction.

Updating the Client to Use a Later API Version

CyberSource periodically updates the Simple Order API. You can update your existing client to work with the new API version. For a list of the available API 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

Alternately, if a new client is available that works with the later API version, you can download that new client.

The new client may have new functionality unrelated to the changes in the API. Read the release notes in the CHANGES file to determine if the new client contains new functionality that you want to use.

Name-Value Pair Client

To update a name-value pair client:

Step 1Load src\CyberSource.Clients.sln in Visual Studio 2010.

Step 2In the Solution Explorer, locate the Service References folder.

Step 3Right-click NVPWebReference and choose Configure Service Reference.

Step 4Update the Address field with the New WSDL URL. Typically, only the version number at the end of the URL needs to be updated.

Step 5Build the Release configuration.

Step 6Save a copy of the original CyberSource.Clients.dll and then replace it with the newly built CyberSource.Clients.dll.

SOAP Client

To update a SOAP client:

Step 1Load src\CyberSource.Clients.sln in Visual Studio 2010.

Step 2In the Solution Explorer, locate the Service References folder.

Step 3Right-click SoapWebReference and choose Configure Service Reference.

Step 4Update the Address field with the New WSDL URL. Typically, only the version number at the end of the URL needs to be updated.

Step 5Build the Release configuration.

Step 6Save a copy of the original CyberSource.Clients.dll and then replace it with the newly built CyberSource.Clients.dll.

XML Client

Updating the client is unnecessary. Start using the new namespace URI in your input XML documents. The client automatically uses the specified version.