|
Search documentation: |
Help Advanced | |
Published 05/14/2002 |
![]() ![]() ![]() ![]() |
Chapter 1
CDK for ASP 3.4.0
This chapter explains how to use CyberSource® Internet Commerce Suite version 2 (ICS2) Active Server Pages (ASP) Client CyberSource Developer Kit (CDK), as presented in the following sections:
- Overview
- System Requirements
- Installing the CDK for ASP
- Manual DLL Registration
- Testing Your Installation
- Implementing the CDK for ASP
- Sample Active Server Pages
Overview
The Cybersource CDK for ASP is a CyberSource Ready Platform that enables you to implement ICS applications from ASP. The ICS Component wraps the ICS application programming interface (API) so that it may be used inside scripting hosts such as ASP.
This guide describes how to use VBScript in your ASP to send and process Simple Commerce Message Protocol (SCMP) requests. You will learn how to:
- Install and register the ICS component
- Use the ICS component in ASP to run Credit Card Services applications. For details on Credit Card Services applications, see the chapter "Requesting CyberSource ICS Applications" in the ICS2 Developer Guide, available on the CyberSource Small Business Support Center.
- Other services in the ICS component are not supported for CyberSource Small Business.
Note The instructions provided in this chapter assume that you are already familiar with VBScript and ASP.
System Requirements
Before you begin, verify that you have a customer account with CyberSource and that your system has the following minimum requirements:
- Windows NT Server 4.0 or Windows 2000
- Web Server, Microsoft Internet Information Server 4.0 or later
- 1.2 MB of disk space
Installing the CDK for ASP
- Open the file cdkasp-nt-3.4.0.exe and follow the instructions in the InstallShield® Wizard.
- When prompted, select a directory to create the files in.
- The default directory is C:\Program Files\CyberSource Corporation\CyberSource Developer Kit for ASP.
- When prompted, select a program folder to contain the program icons.
- The default is program folder is
CyberSource Developer Kit for ASP
.Note When an ICS message is sent, it is programmed to search for your merchant keys as follows:
* In$(ICSPATH)
/keys
, where$(ICSPATH)
is a Windows environment variable.
* If the ICSPATH variable is not set, the ICS message will next search for the keys subdirectory of the folder in which you installed the component.
* If the keys directory is not found there, then the default directory will be followed:(C:\Program Files\CyberSource Corporation\CyberSource Developer Kit for ASP\keys)
.
These keys must be the same name as the merchant_id.crt. The private key is merchant_id.pvt. The $(ICSPATH) /keys directory must include the server certificate, whose current name is CyberSource_SJC_US. crt.Manual DLL Registration
The installation program automatically registers the component. If the component or the component's registry settings become corrupted, you can register the component again by doing one of the following:
- Run the Register Component by selecting, from your Window's Desktop, Start > Programs >
program folder specified during setup
> Register the CDK for ASP.- Register it manually by typing at the command prompt:
regsvr32 installpath\ics2com.dll
When registration is complete, a dialog box displays the message:
DllRegisterServer in installpath\ics2com.dll succeeded.Testing Your Installation
After the installation is complete, you can test the ICS component.
Run the test application by selecting Start > Programs >
program folder specified during setup
> Test the CDK for ASP.If the installation is complete, a DOS window appears and a transaction is initiated with the test server ics2test.ic3.com. Both the request and response fields are displayed.
If the installation is not complete, the following message appears:
Error: ActiveX component can't create object.If the installation is incomplete, contact CyberSouce Small Business Customer Support.
Implementing the CDK for ASP
Creating the ICS Object
The progid of the component is
CyberSource.ICS
. To create an object, do one of the following:
- Call the
CreateObject
function exposed by the ASP intrinsic object Server:
Set oICS = Server.CreateObject("CyberSource.ICS.3")
- To invoke the methods and properties of the object, use the variable you set the object to, which in this case is
oICS
.- Use the <
OBJECT>
tag:
<OBJECT RUNAT=SERVER PROGID="CyberSource.ICS.3" ID=oICS>
</OBJECT>
- To invoke the methods and properties of the object, use the value specified for ID in the
<OBJECT>
tag.ICS Object Properties
The ICS object exposes the following properties listed in Table 1.
Table 1 ICS Object PropertiesoICS.ServerHost = "ics2test.ic3.com" oICS.Merchant = "Adobe" oICS.Log = True oICS.LogPath = "C:\TEMP\" or just "C:\TEMP" oICS.LogSize = 10' 10 MB Dim Version Version = oICS.Version Dim arr, elem arr = oICS.RequestArray' or oICS.ResponseArray for each elem in arr response.write elem & "<BR>" nextNote Each assignment of a value to a property overwrites the value that was set during a previous assignment.
Adding Fields to the ICS Object
Fields that are not exposed through properties are set using the SetValue method. This method adds an SCMP field to the request. An SCMP field consists of two pieces of information: the field's name and the field's value. These two pieces of information form what is called a name=value pair.
Table 2 Methods for Adding Fields to the ICS ObjectExample Using SetValue to Add an SCMP Field to a Request
oICS.SetValue "bill_city", Request.Form("City") oICS.SetValue "bill_state", Request.Form("State") oICS.SetValue "bill_zip", Request.Form("Zip") oICS.SetValue "bill_country", Request.Form("Country")An alternative to using the properties ServerHost and Merchant is to use SetValue to set the value of the fields ics_svrhost and merchant_id, respectively. For more information on these fields, see the chapter "Requesting CyberSource ICS Applications" in the ICS2 Developer Guide, available on the CyberSource Small Business Support Center. Calling SetValue on either field updates the corresponding property.
Example Setting The Value Of The ics_svrhost Field
oICS.ServerHost = "ics2.ic3.com" oICS.SetValue "ics_svrhost", "ics2test.ic3.com" Response.Write oICS.ServerHost' now ics2test.ic3.comProxy support
CyberSource uses the HTTP protocol as its transport mechanism. By default the HTTP protocol is on port number
80
. If your site uses a proxy server, you do not need to set thehttp_proxy
environment variable, as proxy support is already enabled in the SCMP instructions.Example Setting The Value Of
http_proxy
oICS.SetValue "http_proxy","http://yourserver.com"
Obtaining the Value of a Request Field
You can call
GetRequestValue
to determine the value of a field that has been added to the request message. If the field has not been added, it returns an empty string.
Table 3 Methods for Obtaining the Value of a Request Field
Method Description Parameters Value Returned GetRequestValue Returns the value of a request field. The name of the field. The value of the field or an empty string if the field has not been added.oICS.SetValue "bill_city", "Mountain View" Response.Write oICS.GetRequestValue("bill_city")Adding Offers
An offer carries the description of a product or item and is used by all ICS applications. Offers and their fields are added to the SCMP request via the
AddToOffer
method. For a complete list of offer fields, see the chapter "Requesting CyberSource ICS Applications" in the ICS2 Developer Guide, available on the CyberSource Small Business Support Center.Table 4 Method for Adding Offers to a Request FieldExample Adding Offers To A Request
This code assumes that each shopping basket item is implemented as an object stored as a session property called BasketItemN, where N is an integer uniquely identifying the item.
Dim i, nNumItems, oItem nNumItems = Session("BasketCount") for i = 0 to nNumItems - 1 set oItem = Session("BasketItem" & i) oICS.AddToOffer i, "product_name", oItem.product_name oICS.AddToOffer i, "merchant_product_sku", oItem.merchant_product_sku oICS.AddToOffer i, "product_code", oItem.product_code oICS.AddToOffer i, "amount", oItem.amount oICS.AddToOffer i, "quantity", oItem.quantity oICS.AddToOffer I, "packer_code", oItem.packer_code nextCall the method GetRequestValue to get the value of an offer. You must pass
offerN
to the method whereN
is the integer corresponding to the offer. GetRequestValue returns all name=value pairs that have been added so far (via AddToOffer) separated by carets (^) with colons (:) between each name and its value.An alternative to using AddToOffer is to call SetValue directly as in the following:
oICS.SetValue "offer0", "product_name:widgets^quantity:2^..."AddToOffer and SetValue overwrite each other. If you call SetValue on offerN, it will replace all the fields of item N that have been added via AddToOffer, and vice versa.
While AddToOffer offers the benefit of preventing duplicates and doing the concatenation work for you, you may find SetValue useful if you need to clear everything you have added using AddToOffer. In this case, call SetValue on the offer item, setting its value to ""or anything else. It will then be overwritten in your next call to AddToOffer.
Example Adding Offers To A Request
oICS.AddToOffer 0, "product_name", "widgets" oICS.AddToOffer 0, "quantity", "2" Response.Write oICS.GetRequestValue("offer0")Will output "productname:widgets^quantity:2"
oICS.SetValue "offer0", "" Response.Write oICS.GetRequestValue("offer0")oICS.AddToOffer 0, "product_name", "newproduct" Response.Write oICS.GetRequestValue("offer0")Will output "product_name:newproduct "
Sending a Request and Handling the Response
The information set via SetValue, AddToOffer, and direct assignments to the object's properties are sent to the CyberSource server using the Send method. The GetResponseValue method is then called to get the values of the fields returned by the server.
Table 5 Methods for Sending Requests and Handling the ResponsesExample Sending Requests And Handling The Response
oICS.Send if (CInt(oICS.GetResponseValue("ics_rcode")) < 0) then Response.Write "Error:<BR>" Response.Write oICS.GetResponseValue("ics_rmsg") Response.End end if if (CInt(oICS.GetResponseValue("tax_rcode")) < 0) then Response.Write "Error:<BR>" Response.Write oICS.GetResponseValue("tax_rmsg") Response.End end ifNote For specific information on when and how to call ICS applications, see the chapter "Requesting CyberSource ICS Applications" in the ICS2 Developer Guide, available on the CyberSource Small Business Support Center.
Clearing Fields
The Clear method provides a way of removing all fields, both request and response fields. This allows you to start with a clean object without having to destroy and recreate the object. This is especially useful for objects created in session scope.
The object retains the log information. For example, the values of the propertiesLog, LogPath, and LogSize. If you like investigating a problem by generating a log file, then you need to set Log to
True
. There is no need to find all occurrences of Clear and set Log to True after each such call.
Table 6 Methods for Clearing a Field
Method Description Parameters Clear Removes all request and response fields from the object. NoneoICS.Log = True oICS.SetValue "ics_applications", "ics_score,ics_auth,ics_bill,ics_elc" ' additional code to set other fields goes here oICS.Send ' code to handle response goes here oICS.ClearAt this point, the field ics_applications, among others, has been removed but Log is still true. Subsequent transactions would still be logged.
Sample Active Server Pages
Included in the installation is a set of example Active Server Pages. Access these examples by selecting Start > Programs > CyberSource Developer Kit for ASP > CyberSource Solution Sites.
Note These example pages are for the English version of the CDK for ASP. Japanese samples are located in the installation directory.
The sample pages demonstrate the use of the ICS component to perform several ICS applications. The sections that follow describe the contents of each file.
global.asa: Creating the ICS Object
The global.asa file performs the following:
- Creates the ICS object and stores it into a session variable.
- If scalability in a live Web site is critical, do not do this since this would make the object sit idle until the session times out.
- Creates a dummy shopping basket.
- Sets the merchant and server host fields of the object.
global.asa Script
The following script is used to create the shopping basket. You may choose another script.
<!--/* global.asa************************************************/--> <!--/* */--> <!--/* CyberSource Internet Commerce Services (ICS) libraries */--> <!--/* Copyright 1998, 1999, 2000. CyberSource Corporation. */--> <!--/* All rights reserved. */--> <!--/************************************************************/-->
<SCRIPT RUNAT=SERVER LANGUAGE=VBSCRIPT>
REM Change this value to your own merchant_id
Application("merchant_id") = "YOUR_MERCHANT_ID"
Application("server_host") = "ics2test.ic3.com"
REM Change these values to match your own profile_id's
profile_ids(0) = 2060 ' Happy holidays
profile_ids(1) = 2061 ' Congratulations
profile_ids(2) = 2062 ' Happy birthday
profile_ids(3) = 2076 ' Anniversary
profile_ids(4) = 2077 ' Father's Day
profile_ids(5) = 2078 ' General Gift
profile_ids(6) = 2079 ' I love you
profile_ids(7) = 2080 ' mother's day
profile_ids(8) = 2081 ' thinking of you
Application("profile_ids") = profile_ids
Sub Session_OnStartDim oICS
Set oICS = Server.CreateObject( "CyberSource.ICS.3" )
oICS.ServerHost = "ics2test.ic3.com"
oICS.SetValue "merchant_ref_number", "01"
' store the object as a session property
Set Session("ICSObject") = oICS
<!--/* Copyright 1998, 1999. CyberSource Corporation. All rights reserved.*/-->
checkout.asp: Contents of the Shopping Basket
The checkout.asp file performs the following:
checkout.asp Script
<%@ LANGUAGE = VBScript %> <% Response.Buffer = True %> <% '/* checkout.asp ***************************************************/ '/* */ '/* CyberSource Internet Commerce Services (ICS) libraries */ '/* Copyright 1998, 1999, 2000. CyberSource Corporation. */ '/* All rights reserved. */ '/******************************************************************/ %>
<!-- #INCLUDE FILE="store_header.asp" -->
<SCRIPT RUNAT=SERVER LANGUAGE=JSCRIPT>
function BasketItem( offer_id, product_name, merchant_product_sku, product_code, amount, quantity, packer_code )
this.product_name = product_name;
this.merchant_product_sku = merchant_product_sku;
this.product_code = product_code;
this.packer_code = packer_code;
function CreateShoppingBasket()
Session("BasketItem0") = new BasketItem( "0", "test product 1", "smartcert_test",
"electronic_software", "215.00", "1", "rover10" );
Session("BasketItem1") = new BasketItem( "1", "test product 2", "default_test",
"default", "1.00", "5", "default" );
Session("BasketItem2") = new BasketItem( "2", "test product 3", "No_packer_test",
"electronic_software", "1.00", "5", "download_only" );
<META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-8859-1">
if not IsObject(Session("ICSObject")) then
Response.Write "Failed to create the object."
Here are the items in your shopping basket: <BR><BR>
nNumItems = Session( "BasketCount" )
set oItem = Session( "BasketItem" & i )
<TD><%=oItem.product_name%></TD>
<TD><%=oItem.merchant_product_sku%></TD>
<TD><%=oItem.product_code%></TD>
<TD CLASS=numeric><%=FormatCurrency(oItem.amount)%></TD>
<TD CLASS=numeric><%=oItem.quantity%></TD>
<TD><%=oItem.packer_code%></TD>
Please enter customer information below:
<FORM ACTION="checkout2.asp" METHOD=post>
<!-- Default values are provided for easier testing. -->
<INPUT TYPE=text NAME="customer_firstname" VALUE="John"></INPUT>
<INPUT TYPE=text NAME="customer_lastname" VALUE="Doe"></INPUT>
<INPUT TYPE=text NAME="customer_email" VALUE="nobody@cybersource.com"></INPUT>
<INPUT TYPE=text NAME="customer_phone" VALUE="650-965-6000"></ INPUT>
<INPUT TYPE=text NAME="bill_address1" VALUE="1295 Charleston Road"></INPUT>
<INPUT TYPE=text NAME="bill_city" VALUE="Mountain View"></INPUT>
<INPUT TYPE=text NAME="bill_state" VALUE="CA"></INPUT>
<INPUT TYPE=text NAME="bill_zip" VALUE="94043"></INPUT>
<OPTION VALUE="us">United States
<input type="radio" name="payment_method" value="cc" CHECKED>Credit Card</input><br>
<input type="radio" name="payment_method" value="echeck">Electronic Check</input><br>
<input type="radio" name="payment_method" value="gift">Gift Certificate</input><br>
<INPUT TYPE=submit VALUE="Submit"></INPUT>
<!-- #INCLUDE FILE="store_footer.asp" -->
<%'/* Copyright 1998, 1999, 2000. CyberSource Corporation. All rights reserved.*/%>
checkout3.asp: Calling ICS Applications
The checkout3.asp file calls the ics_auth, ics_bill, ics_score, ics_elc and ics_download applications and displays a link to the download URL.
Note CyberSource Small Business supports ics_auth, ics_bill and ics_credit. Other services in this integration — such as ics_score, ics_elc and ics_download — are not supported for CyberSource Small Business but are included in this sample.
checkout3.asp Script
<%@ LANGUAGE = VBScript %> <% '/* checkout3.asp **************************************************/ '/* */ '/* CyberSource Internet Commerce Services (ICS) libraries */ '/* Copyright 1998, 1999, 2000. CyberSource Corporation. */ '/* All rights reserved. */ '/******************************************************************/ %>
<META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-8859-1">
<!-- #INCLUDE FILE="store_header.asp" -->
Set oICS = Session("ICSObject")
oICS.SetValue "currency", "USD"
PaymentMethod = Session("payment_method")
if (PaymentMethod = "cc") then
' Extract the expiration month and year
dtExp = Request.Form("customer_cc_exp")
Response.Write "Invalid card expiration date."
oICS.SetValue "ics_applications", "ics_score,ics_auth,ics_bill,ics_elc,ics_download"
oICS.SetValue "customer_cc_number", Request.Form("customer_cc_number")
oICS.SetValue "customer_cc_expmo", strMonth
oICS.SetValue "customer_cc_expyr", strYear
elseif (PaymentMethod = "echeck") then
oICS.SetValue "ics_applications", "ics_ecp_debit,ics_elc,ics_download,ics_tax"
oICS.SetValue "ecp_account_no", Request.Form("account_number")
oICS.SetValue "ecp_rdfi", Request.Form("bank_routing_number")
oICS.SetValue "ecp_account_type", Request.Form("account_type")
elseif (PaymentMethod = "gift") then
REM For Gift Certs we need to check the balance before calling redeem
Dim nNumItems, cySplitTenderAmount
nNumItems = Session( "BasketCount" )
dblOrderTotal = Session("OrderTotal")
cySplitTenderAmount = Session("split_tender_amount")
strOfferNum = "offer" & (nNumItems - 1)
if cySplitTenderAmount = 0 then
oICS.AddToOffer nNumItems, "offer_id", nNumItems
oICS.AddToOffer nNumItems, "product_name", "Gift Certificate being Redeemed"
oICS.AddToOffer nNumItems, "merchant_product_sku", "123456789"
oICS.AddToOffer nNumItems, "product_code", "stored_value"
oICS.AddToOffer nNumItems, "amount", dblOrderTotal
oICS.AddToOffer nNumItems, "quantity", "1"
oICS.AddToOffer nNumItems, "isv_number", Session("isv_number")
oICS.AddToOffer nNumItems, "isv_currency", "USD"
oICS.SetValue "ics_applications", "ics_redeem_isv,ics_tax,ics_download"
oICS.SetValue "isv_number", Request.Form("gift_number")
elseif cySplitTenderAmount > 0 then
oICS.AddToOffer nNumItems, "offer_id", nNumItems
oICS.AddToOffer nNumItems, "product_name", "Gift Certificate being Redeemed"
oICS.AddToOffer nNumItems, "merchant_product_sku", "123456789"
oICS.AddToOffer nNumItems, "product_code", "stored_value"
oICS.AddToOffer nNumItems, "amount", dblOrderTotal
oICS.AddToOffer nNumItems, "quantity", "1"
oICS.AddToOffer nNumItems, "isv_number", Session("isv_number")
oICS.AddToOffer nNumItems, "isv_currency", "USD"
dtExp = Request.Form("customer_cc_exp")
oICS.SetValue "bill_address1", Request.Form("bill_address1")
oICS.SetValue "bill_city", Request.Form("bill_city")
oICS.SetValue "bill_state", Request.Form("bill_state")
oICS.SetValue "bill_zip", Request.Form("bill_zip")
oICS.SetValue "bill_country", Request.Form("bill_country")
oICS.SetValue "customer_cc_number", Request.Form("customer_cc_number")
oICS.SetValue "customer_cc_expmo", strMonth
oICS.SetValue "customer_cc_expyr", strYear
oICS.SetValue "ics_applications", "ics_redeem_isv,ics_tax,ics_auth,ics_download"
oICS.SetValue "isv_number", Request.Form("gift_number")
Response.write "INTERNAL ERROR: No split tender amount was specified."
Response.Write "An invalid payment method was selected. Please try a different payment method."
rcode = oICS.GetResponseValue( "ics_rcode" )
response.write "Host did not return expected field."
' For simplicity, we are not checking each of the service- specific return codes.
response.write "We encountered the following error while submitting your request:<BR>"
response.write oICS.GetResponseValue( "ics_rmsg" )
response.write "<H4>Data Sent:</H4>"
response.write "<H4>Data Received:</H4>"
Response.write "<H2> Thank you for choosing our store! <br>Your order has been received. </H2>"
strURL = oICS.GetResponseValue( "download_download_url2" )
strURL2 = oICS.GetResponseValue( "elc_rover_url0")
If (PaymentMethod = "gift") then
To check the updated balance of your gift certificate <a href=display_cert.asp?id=<%=Session("isv_number")%> > click here</a>
<li><A HREF=<%=strURL%>>Click here to download your first item.</A>
<!-- This line is only used when the ics_elc service is being requested
<li><A HREF=<%=strURL2%>>Click here to download your second item.</A>
<!-- #INCLUDE FILE="store_footer.asp" -->
<%'/* Copyright 1998, 1999, 2000. CyberSource Corporation. All rights reserved.*/%>
Copyright © 2002 CyberSource Corporation. |
![]() |
![]() |
![]() |
![]() |