|
|
|
|
|
|
Installing and Testing the .NET Client
This chapter explains how to install and test the SDK for .NET. The chapter includes these sections:
Installing the CyberSource Sample Store
Customizing Your Visual Studio .NET Toolbox
Testing the .NET Client Installation
Creating a Certificate and Private Key
Your system must meet the following minimum requirements:
• Microsoft .NET Framework Redistributable, installed on your system
For the minimum requirements for .NET, see the .NET home page, at http://msdn.microsoft.com/netframework/.
• Microsoft ASP.NET®.
This application is required for the Sample Store.
• 20 MB of disk space
Microsoft Visual Studio® .NET is optional.
The client supports ISO-8859-1 encoding by default. However, you can configure the client to use UTF-8 instead. See 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. If it is not possible to configure your machines with unique IP addresses, CyberSource provides a client configuration parameter to easily identify your host. For the CyberSource SCMP API SDK for .NET, this configuration parameter is HostID, which is an ICSClient property.
The CyberSource .NET Client Setup Wizard will create program folder shortcuts.
1 Download the latest .NET Client package from the downloads area of the CyberSource Support Center.
2 Run the downloaded file.
The Welcome to the CyberSource .NET Client Setup Wizard window appears.
3 Click Next to continue.
The License Agreement window appears.
4 Select I Agree, then click Next to continue.
The CyberSource .NET Client Information window appears.
5 Click Next.
The Select Installation Folder window appears.
a In the bottom right corner of this window, select Everyone if you want all users on that computer to see the Start menu program shortcuts to the CyberSource Client. If not, then select Just Me.
b If you want to change the installation folder, click Browse, and select a folder. If you want to use the default selection, proceed to the next step.
3 Click Next.
The Confirm Installation window appears.
4 Click Next.
The Generate Keys window appears.
5 Enter your merchant ID and keys directory, then click OK.
Clicking OK generates your keys and updates ICSTest.xml and, after you install the Sample Store, web.config. These files must be updated before you run ICSTest or use the Sample Store.
The Information window appears, showing your output generated by ECert (Electronic Certificate Generation Application).
Note If keys are already present in the keys directory, then new keys will not be generated.
If ECert fails, be sure that your merchant ID is valid, then run ECert on the Command Prompt. If your company requires the use of a proxy server, use the proxy options for ECert. For more information on running ECert, see Creating a Certificate and Private Key.
6 Click OK.
The Installation Complete window appears.
7 Click Close.
Downloading the package installs the directory and files listed in Table 1.
You should now install the CyberSource Sample Store.
Installing the CyberSource Sample Store
The CyberSource Sample Store Setup Wizard will install the CyberSource Sample Store on your computer.
Important The CyberSource Sample Store is intended for testing and basic demonstration purposes only. Do not use the CyberSource Sample Store to build your Web store.
Running the CyberSource Sample Store Setup Wizard
1 From your Windows desktop, select Start > Programs > CyberSource .Net Client > Install Sample Store.
The Welcome to the CyberSource Sample Store Setup Wizard window appears.
2 Click Next.
The Select Installation Address window appears.
The default virtual directory is CyberSourceStore. The default port is 80.
3 Click Next.
The Confirm Installation window appears.
4 Click Next.
The Installation Complete window appears.
Note If you chose not to generate keys when running the CyberSource .NET Client Setup Wizard, or if ECert failed, the Generate Keys windows will appear. For more information on the Generate Keys windows, see Installing the Client.
5 Click Close.
You should now customize your Visual Studio .NET Toolbox.
Customizing Your Visual Studio .NET Toolbox
This section explains how to add the ICSClient component to your Visual Studio .NET Toolbox. To be able to drag and drop the CyberSource .NET Client into your Web pages, you will need to add the ICSClient component to your Visual Studio .NET Toolbox.
Note Remove the older ICSClient if there is one.
1 From your Windows desktop, select Start > Programs > Microsoft Visual Studio .NET > Microsoft Visual Studio .NET.
Microsoft Visual Studio .NET opens.
2 Click on the Toolbox tab.
If the Toolbox tab is not visible, then select Toolbox from the View menu.
3 Right-click in the Toolbox window and select Add/Remove Items.
The Customize Toolbox window appears.
4 Click the .NET Framework Components tab.
The .NET Framework Components tab appears.
5 Under the Name column, find and select ICSClient.
6 Click OK.
The ICSClient icon is now visible on the Components tab of the Tool menu.
You should now test your installation.
Testing the .NET Client Installation
To test your .NET Client installation, do the following:
• Run the ICSTest application
• Run test transactions using the Sample Store
If you did not update the ICSTest.xml file when you generated keys during the .NET Client installation, then you must edit the ICSTest.xml file before you run ICSTest application.
Note You can skip this procedure if you updated the ICSTest.xml file during your .NET Client installation.
1 Using a text editor, open the ICSTest.xml file. The file is located in <directory>\ ICSTest, where <directory> is the directory where the CyberSource Client for .NET is installed.
2 Find <MerchantID>your_merchant_id</MerchantID>, and change the value to your Merchant ID.
3 Find <KeysDir>directory_containing_your_keys</KeysDir>, and change the value to the location of your public and private keys.
4 Save and close the ICSText.xml file.
1 From your Windows desktop, select Start > Programs > CyberSource .NET Client > Run ICSTest.
A Command Prompt window opens.
2 Run the ICSTest.exe application.
If your installation was successful, you will see the request and reply in the Command Prompt window.
If your transaction was not successful, make sure your certificate and private key files were properly generated by the ECert application.
If you continue to receive an error message, review yourICSTest.xml file. For more information see Editing the ICSTest.xml File.
Note The ICSTest directory contains the project and source files, which can be loaded in Visual Studio .NET. You will need to add a reference to the CyberSource .NET Client in order to build the project. For more information on adding a reference, see Using the .NET Client with Other .NET Applications.
If you did not update the web.config file when you generated keys during the .NET Client installation, then you must edit the web.config file before you use the Sample Store.
Note You can skip this procedure if you updated the web.config file during your .NET Client installation.
1 Using a text editor, open the web.config file. The file is located in the inetpub\wwwroot\<VirtualDir> directory, where <VirtualDir> is the one you selected during the Sample Store installation. The default is CyberSourceStore.
2 Find the <appsettings> element. It will appear similar to the following:
<appsettings>
...
</appsettings>
3 Find <add key="icsClient.KeysDir" value= "directory_containing_your_keys" />, and change the value to the location of your public and private keys.
4 Find <add key="icsClient.MerchantId" value= "your_merchant_id" />, and change the value to your merchant ID.
5 Save and close the web.config file.
1 Using a Web browser, go to http://localhost/<virtualdirectory>/, where <virtualdirectory> is the one you selected during the Sample Store installation.
The Shopping Cart page appears.
The Shopping Cart shows a pre-filled order.
2 Click Checkout.
The Enter Shopper Information page appears. The field entries may be modified.
3 Click Submit.
The Order Summary page appears. Tax and the order total are computed.
4 Click Proceed with Checkout.
The Enter Credit Card Information page appears. Be sure the Credit Card Number is a test value. The Card Verification Number can be a three- or four-digit value.
5 Click Submit.
If the .NET Client is working properly, the Order Complete page appears.
If you receive an error message, review your web.config. For more information see Editing the web.config File.
6 If you click Shop again, you will be returned to the Shopping Cart.
The following are the files in the Sample Store directory located in the Solution Explorer—My Store.
• Default — the Shopping Cart page
• DisplayError — shows the error page and prints out the exception
• DisplaySuccess — shows that your order is completed successfully, and displays the order number
• DisplaySummary — displays the total amount after tax; calls the ics_tax service and displays the Shopping Cart with tax, shipping and handling, and total amount
• GetCreditCardInfo — where the credit card information is displayed; calls the ics_score and ics_auth service after the Submit button is clicked.
• GetShoppingInfo — where the billing address and the ship-to address information are entered by the customer
• Global.asax — contains the ICSClient data member, which is used in DisplaySummer.aspx and GetCreditCardInfo.aspx
Note The Sample Store also includes the project and source files, which can be loaded in Visual Studio .NET. You will need to add a reference to the CyberSource .NET Client in order to build the project. For more information on adding a reference, see Using the .NET Client with Other .NET Applications.
Once you have thoroughly tested your system, you can go live with CyberSource, which you must do before you begin to accept customers. 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 (ics2.ic3.com) and not the test server (ics2test.ic3.com).
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, use small amounts, such as one dollar, to do the tests. If you have more than one CyberSource merchant ID, test each one separately. Process an authorization, capture, and credit for each configuration, and use your bank statements to verify that money is deposited into and withdrawn from your merchant bank account.
Creating a Certificate and Private Key
CyberSource uses public key cryptography to securely exchange messages over the Internet. Before you can send transactions to CyberSource, you must generate a public certificate and a private key.
When you install the CyberSource client for .NET using the setup wizard, you can choose to generate a CyberSource certificate and private key. This section explains how to generate an additional certificate and private key, or generate a certificate and private key for the first time if you did not do so during installation. You might choose to use multiple merchant IDs if, for example, you are using multiple currencies.
Important It is your responsibility to closely guard your private key to ensure that your confidential information is not compromised.
The certificate and keys files comprise the following:
• merchant_id.crt — certificate file
• merchant_id.pvt — private key file
• merchant_id.pwd — password file
• CyberSource_SJC_US.crt — CyberSource certificate file
Generating Your Certificate and Private Key
1 Bring up the Command Prompt.
2 Go to the installation directory, and run the ECert application. Type:
ecert <merchant_id>
where <merchant_id> is your merchant ID, which is your merchant identifier used to retrieve your public key from CyberSource.
The syntax and options for ECert (Electronic Certificate Generation Application) are:
ecert <merchant_id>
[ -help ] [ -version ] [ -noprompt ] [ -update ]
[ -display ] [ -debug ] [ -path <key_directory> ]
[ -proxy <url> [ <username> ] [ <password> ] ]
[ -server <ics_server_host> <ics_server_port> ]
Following are descriptions for the options:
• help returns the ECert syntax.
• version reports the version of ECert you have installed.
• noprompt causes ECert to run without additional confirmation.
• update updates your certificate and private key. This option also updates your copy of the CyberSource certificate. You can only use this option if your certificate already exists in the CyberSource server and your site has gone live.
• display displays your certificate and private key information, such as expiration date.
• debug provides debugging information if you experience problems with the ECert application.
• path <key_directory> causes ECert to write the certificate and private key files to directory other than the default directory. The default is [current drive]:\opt\CyberSource\SDK\keys. For example, if you are running Windows NT in Z:\ drive and you run ECert from any directory in Z:\ drive, your keys by default would be put in Z:\opt\CyberSource\SDK\keys.
• proxy <url> [ <username> ] [ <password> ] causes ECert to use a proxy connection before connecting to an ICS server. The username and password are optional, but must be used together if included.
• server <ics_server_host> <ics_server_port> causes ECert to use the host <ics server host> and port <ics_server_port> to connect to CyberSource. The default host server is setup.ic3.com. The CyberSource test server is ics2test.ic3.com, and the CyberSource production server is ics2.ic3.com. The default port is 80. Do not use CyberSource’s test server or production server unless you are specifically instructed to do so by CyberSource Customer Support.
3 Copy the CyberSource certificate, your certificate, your private key, and your password files to the keys directory of any server where the CyberSource .NET Client is installed. Your certificate (.crt) and private key (.pvt) files are paired and must be used together.
After you run ECert to generate your certificate and private key, you can securely send transaction requests to the CyberSource test server. When you go live, you can securely send transaction requests to the CyberSource production server.
You must update your certificate and private key yearly to reduce the risk of having them compromised.
If you need to uninstall the CyberSource client for .NET and the CyberSource Sample Store, do the following:
1 From your Windows desktop, select Start > Settings > Control Panel > Add/Remove Programs.
The Add/Remove Programs window appears.
2 In the left navigation bar, click Change or Remove Programs.
3 Select CyberSource Sample Store.
4 Click Remove.
The CyberSource Sample Store is removed.
5 Select CyberSource .NET Client, noting the version number.
6 Click Remove.
The CyberSource .NET Client is removed.
7 Click Close.
|
|
|
|
|
|