Once a user clicks the "Pay" button on your site server e-store, what next? VeriFone offers a solution for the challenge of verifying customers and collecting your money online.

Okay, so you've decided to take the plunge into e-commerce. You've put your inventory online and set up a decent ordering system. Orders are about to start pouring in. But how will you collect payment from your new customers?     This article will take a look at what happens in a Web-based store using Microsoft® Site Server 3.0 Commerce Edition after the customer hits the Pay button. We'll show you how to automate credit card processing using a third-party product, VeriFone's vPOS software, but also explain the concepts you must understand in order to integrate any vendor's credit card processing software into your store. Armed with a solid understanding of the technical implementation of the Site Server Commerce Edition shopping cart and order processing mechanism, you can successfully customize your e-commerce site and add new features. But you won't have to reinvent the wheel or try to code around what might seem like a complicated and insufficiently documented commerce architecture.     E-commerce sites based on Site Server Commerce Edition are implemented using server-side COM objects and Active Server Pages (ASP) scripts. This gives you complete control over your site's functionality—as long as you understand how all the pieces go together. Site Server Commerce Edition comes with a couple of sample stores, but we chose not to use them because they didn't seem as good as the template store produced by using the Site Server Commerce Foundation Wizard. The sample scripts and file names in this article are based on those generated for you by the wizard. Order Processing       Order processing on the Internet can be separated into five distinct steps: Your server has to determine what the customer wants to buy. It must calculate the total cost of the order including shipping and tax, if any. It must process the payment offered by the customer and verify that the payment is valid. It must migrate the order out of temporary storage and into long-term storage of completed sales. It must inform the customer that payment has been accepted and the transaction is complete. We'll begin by figuring out what the customer wants to buy.     Web commerce software must be able to associate shoppers with their orders. This is most commonly known as state tracking—the ability to identify requests made at various times as being from the same user, who has made requests of the server and perhaps made selections from the merchandise catalog. State tracking is the foundation of any shopping cart mechanism, allowing the customer to choose what to buy prior to heading to the cash register to pay for it. In Site Server Commerce Edition, shoppers are identified by a unique ShopperID number. This number is saved in the database along with the current contents of the user's shopping cart. The ShopperID number can be saved locally on a shopper's hard drive, permanently associating the computer with a single ShopperID via a cookie. Alternatively, the ShopperID can be passed along in the URL when navigating between pages to accommodate shoppers whose browsers do not accept cookies.     Microsoft built the ShopperID into Site Server Commerce Edition for a couple of important reasons. One reason is that Site Server relies on cookies to track session state, which doesn't work if visitors forbid the storage of cookies on their local computers. The other problem is that Site Server's session state management does not allow for load balancing between multiple servers so that any one of the servers can accurately identify the shopper and the shopper's current session and therefore retrieve the contents of their shopping cart. The Site Server Commerce Edition ShopperID is based on a modified GUID, making it possible for any of the servers in a load-balancing scenario to generate the ShopperID with the certainty that none of the other servers will ever generate the same ShopperID for another shopper. Because the ShopperID is stored in the database instead of being stored as a Site Server session scope variable, you don't have to worry about passing session identification between servers in some other way.     The ShopperID lets us query the database for the contents of the shopper's shopping cart. The shopping cart is stored in a table called _basket, and is represented as a special Site Server Commerce Edition object called OrderForm. The OrderForm object is made up of two other Site Server Commerce Edition objects: Dictionary and SimpleList. As you'll see later, the use of Dictionary and SimpleList objects to store items within the OrderForm makes it very easy to add new items that are specific to your store to the OrderForm and save them in the database.     The following script line calls a function that retrieves shopping cart data from the database, populates the OrderForm object, checks the validity of the shopping basket data, and saves any changes that might be needed to bring the shopping cart in line with reality:

Set mscsOrderForm = UtilRunPlan()

The UtilRunPlan function resides in the file i_util.asp. It contains a line that calls another function, UtilGetOrderForm, which returns the actual OrderForm object:

Set mscsOrderForm = UtilGetOrderForm(mscsOrderFormStorage, created)

The UtilGetOrderForm function, which also resides in i_util.asp, calls the GetData function on a DBStorage object. DBStorage handles the marshaling of Dictionary and SimpleList objects to and from the database. A binary, or Image, database table column type is used to store a marshaled representation of the Dictionary or SimpleList object.      Figure 1 shows the database tables created for you by the Commerce Site Foundation wizard. The wizard precedes each table name shown in Figure 1 with the name of your store. For example, if you name your store members, then the customer's shopping cart data is stored in members_basket. If you look at the structure of the two database tables in which receipts and shopping carts are stored, _basket and _receipt, you will see that each contains an image column with the prefix marshalled_, indicating its use by the DBStorage object to essentially serialize a binary image of the OrderForm.     A shopper can return hours, days, or even months after filling the shopping cart with merchandise to provide payment for an order. Therefore, it is necessary to verify upon retrieving an OrderForm from the database that the products in the shopping cart are still listed in the product catalog and that the prices have not changed. In Microsoft Site Server Commerce Edition, this task is performed by a tool called the Order Processing Pipeline.     The pipeline is a framework for connecting COM components so that the processing performed by one component can be built upon by the next component. Because each component exposes the same COM interface and makes the same assumptions about the data type of the OrderForm object passed between them (a Variant of type Commerce. Dictionary), it is possible for the pipeline to do some fairly complex processing. The order of execution of each component in each stage of the pipeline can be viewed and modified using a Site Server Commerce Edition tool called the Pipeline Editor.       Figure 2: The Plan Pipeline       Many pipelines can exist within a single site, and new pipeline components can be created without too much effort using Visual C++®. The Site Server Commerce Foundation Wizard provides two pipelines that are called by ASP scripts: plan and purchase. The plan pipeline is invoked to validate the information contained within the OrderForm object. The purchase pipeline is invoked to finalize the sale, validate payment, and record the sales receipt.       The plan pipeline is invoked whenever the customer's shopping cart and other information about the pending order needs to be validated. The plan pipeline consists of 14 stages beginning with a lookup of product information and ending with an inventory check. Figure 2 shows the entire plan pipeline viewed within the Pipeline Editor.     The OrderForm object is manipulated by the plan pipeline according to the logic implemented by the pipeline components. In the case of the plan pipeline, this includes adding subtotal, total, shipping cost, and tax to the OrderForm object. The following script lines invoke the plan pipeline, which is stored in the file plan.pcf:

REM Get the basic pipe context Set mscsPipeContext = UtilGetPipeContext() REM Create and run the pipe errorLevel = UtilRunPipe("plan.pcf", mscsOrderForm, mscsPipeContext)

If any changes are made to the OrderForm object by the plan pipeline, those changes are immediately saved back to the database by additional script lines in the ASP. If changes are made to the OrderForm, such as removing a product that no longer exists or adjusting prices, the customer is alerted to that fact before paying for the order.     If everything about the order is acceptable to the customer then he or she is next asked to fill out an HTML form (or use the Microsoft Wallet, which is beyond the scope of this article) to supply shipping and billing information. Looking at the default structure of the pages generated by the Site Server Commerce Foundation Wizard, the first form presented to the customer is the shipping form contained within shipping.asp. The form's action is set to:

ACTION="<%= mscsPage.SURL("xt_orderform_prepare.asp") %>"

Inside xt_orderform_prepare.asp, the properties shown in Figure 3 are added to the OrderForm object. Values for these properties are posted to this ASP script by the HTML form in shipping.asp.     The customer is then redirected to payment.asp, where he or she asked to give billing information, including a credit card number. The plan pipeline is run once again just to be sure everything in the shopping cart is still valid. OrderForm properties with the bill_to_ prefix, which were initialized by POSTing the shipping.asp form, are displayed and the customer has the option to change values to create a billing address that is different than the shipping address. Five properties are added to the OrderForm by posting the payment.asp HTML form input fields:

cc_name cc_type _cc_number _cc_expmonth _cc_expyear

When the payment.asp form is submitted to the server, it posts to an ASP script (xt_orderform_purchase.asp), which triggers the second Order Processing Pipeline: purchase.pcf.     We'll discuss the credit card processing stage of the purchase pipeline in a moment, but first there's one more thing that is important to understand. Adding properties to the OrderForm so that they propagate through the Order Processing Pipeline and finally end up in the database is one of the fundamental things you'll need to do when customizing order processing for your storefront. One of the last stages of the purchase pipeline saves the entire OrderForm object, with the exception of properties beginning with _cc_ (although you can override this default), to the database.     Surprisingly, the Site Server Commerce Edition Site Foundation Wizard does not include an email address in the HTML form it creates for your customer to enter contact information. To add the customer's email address to the OrderForm object you must first add an HTML form input field for collecting it. We added the following to our payment.asp page, along with a line to initialize this value in xt_orderform_prepare.asp as discussed previously:

<tr> <td ALIGN="RIGHT"> <b>E-Mail:</b> </td> <td COLSPAN="3"> <input TYPE="text" NAME="bill_to_email" SIZE="54,1" VALUE= "<%= mscsPage.HTMLEncode(mscsOrderForm.bill_to_email) %>"> </td> </tr>

By default, the Action for the payment.asp HTML form is a POST to xt_orderform_purchase.asp. When the user submits the form, xt_orderform_purchase.asp must update the OrderForm object and then trigger the purchase pipeline.

ACTION="<%= mscsPage.SURL("xt_orderform_purchase.asp") %>"

If you want to add properties to OrderForm, you can do so with standard dot notation. If the specified property does not yet exist inside the OrderForm, it is added automatically because OrderForm is derived from the Commerce.Dictionary class. The new property is a name/value pair where the name of the property becomes its retrieval key and a value is associated with that name. Inside xt_orderform_purchase.asp, the HTML form field value that was posted from the payment.asp page is retrieved and added to the OrderForm object.

bill_to_email = mscsPage.RequestString("bill_to_email", null, 1, 100) if IsNull(bill_to_email) then errorList.Add("E-Mail address must be a string between 1 and 100 characters") else orderForm.bill_to_email = bill_to_email end if

The marshaled OrderForm object is saved in binary format by the purchase pipeline and cannot be accessed except by creating an OrderForm object with server.CreateObject and retrieving the object's image from the database. However, the purchase pipeline component that saves the OrderForm to the database will also save the value of any property on the OrderForm if there is a database table column that matches the name of the property.     If you add a table column and give it a name that matches an OrderForm property, then you will have access to that property's value in the table without instantiating an OrderForm object and retrieving the marshaled OrderForm image. However, when you change the value in the database table column for a single property, the corresponding property does not get changed in the marshaled binary representation of the OrderForm. Because other ASP scripts that retrieve the OrderForm from marshaled storage (including the receipt.asp page as an example) are generated by the Site Server Commerce Foundation Wizard, changes made only to the added table column will not be reflected properly on those other Web pages.     If you intend to make changes to the values in an order form once it is saved to the database, you should do so via the OrderForm object. However, saving the OrderForm object by using the functions in i_util.asp does not give you the ability to also save values to table columns with names that match OrderForm property names. Therefore, you must do one of two things to keep your marshaled OrderForm object consistent with the added table column values. First, you can update the table column values explicitly using ADO. Second, you can create a new pipeline that contains only the OrderForm save component and trigger this new pipeline whenever you need to save an OrderForm object that has been saved before.     A good example of a situation in which you will want to make changes to a previously saved OrderForm object is when the person responsible for order fulfillment (the shipping department, for example) actually ships the order. The status of the order should be updated to indicate that it has been shipped. When the customer views the receipt to see the status of the order, he or she should be able to find out that the order has been shipped. The fulfillment person could also add a tracking number that you would want the customer to be able to see. Using the persistent OrderForm object that has been serialized (marshaled) into the database table is a better way to handle these added stages of order fulfillment and communication with the customer than using extra table columns that are accessed through ADO. Better, that is, unless you want the flexibility of implementing your order fulfillment and tracking system on a server that does not have Site Server Commerce Edition installed, but that can access the database server.     Once an OrderForm has been processed by the plan pipeline, the purchase pipeline processes orders in three stages: the purchase check stage, the payment stage, and the accept stage. As we mentioned earlier, the purchase pipeline is called to save the order in the database and complete the sale. The purchase pipeline is launched in the xt_orderform_purchase.asp file using the UtilRunPipe function.

errorLevel = UtilRunPipe("purchase.pcf", mscsOrderForm, mscsPipeContext)

In the purchase check stage, the bill_to fields are checked to make sure that they contain values. Additionally, standard checksum algorithms are run to make sure that a valid credit card number has been entered by the user.     In the payment stage of the purchase pipeline, the order._payment_auth_code value is changed to reflect the credit card authorization status. When a credit card is approved or denied, this value is set. The vPOS additions to the purchase pipeline will be described later.     In the accept stage, the OrderForm can be handed off to other pipelines or applications for further processing, such as inventory management, purchase order creation, and order tracking systems. The ExecuteProcess component is used to run an application on the server, passing any arguments needed by the application. The PipeToPipeTransfer component transfers an OrderForm object to another pipeline for further processing. It's also in this stage that you can choose to write the order into permanent receipt storage using the SaveReceipt component.     Receipt storage is optional, but if you include it in the purchase pipeline, you have to create the receipt storage and add it into the pipe context because the SaveReceipt component makes use of it. This code is also found in xt_orderform_purchase.asp.

Set mscsReceiptStorage = UtilGetReceiptStorage() Set mscsPipeContext.ReceiptStorage = MSCSReceiptStorage

The pipeline processes any objects that are passed to it. When the pipeline has completed processing, you are expected to access the values that have had their state changed by the pipeline by reading the properties of the objects. Once a purchase has been processed by the purchase pipeline, the order can be deleted. The order is deleted in the Set_pay_ success.asp file.

call MSCSOrderFormStorage.DeleteData(null, mscsOrderForm)

Using vPOS        Figure 4 shows our digitalmarketplace.com purchase pipeline as we've modified it to include payment processing using our personal package of choice, VeriFone's vPOS software (http://www.verifone.com), and to automatically send a confirmation email to the customer.

Figure 4: Purchase Pipeline with Payment Processing

Installing the VeriFone vPOS software is very simple. During installation the vPOS payment component is registered as a COM object and is added to the list of available pipeline components for the payment stage. To make use of the vPOS payment component in your Site Server Commerce Edition-based store, you simply open the purchase pipeline in the Pipeline Editor, right-click on the payment stage, and choose Insert Component. The dialog shown in Figure 5 appears, and you select the vPOS component from the list. The vPOS payment component is shown already inserted in the purchase pipeline in Figure 4.

Figure 5: Adding the vPOS Component

The remainder of vPOS installation adds configuration and store management tools and scripts, tables to the database for the storage of credit card processing logs, and encryption certificates to enable communication with the bank's payment processing gateway. The vPOS payment component is the only part of vPOS that integrates directly into your Site Server Commerce Edition store architecture, and because it does so with the simplicity of adding a component to the purchase pipeline, there are few things that can go wrong.     After installing vPOS and adding the payment component to the purchase pipeline, you must perform several configuration steps before the software will function. Obviously, you need a credit card processing merchant account with a bank. Most large banks now offer Internet credit card processing services, though not necessarily service that is compatible with VeriFone's vPOS. The vPOS terminal interface, a CGI script that is used to access the features of the vPOS software on the server, is used for configuring and managing the operation of the VeriFone vPOS payment processing system.     Three sections in the vPOS terminal interface pertain to its configuration: Administrator, where batch processing of credit card transactions can be managed; Setup, where simple vPOS settings can be tailored; and the most important, Certificates, where encryption certificates (which are based on public key cryptography from RSA Data Security Inc.) are issued by your bank, installed, and activated to allow vPOS to communicate securely with the payment processing gateway.     By default, the vPOS payment component does not actually bill the customer's credit card when the order is processed. Instead, it performs what is known in the credit card industry as an authorization. An authorization is more than just a query to see if the card number and expiration date are valid, however; it actually reserves a portion of the customer's available credit for the amount of the order they would like to place with your store. When you're ready to ship the product to the customer (or upon receiving a cancellation of the order from the customer) you follow the authorization with a settlement request. If the customer cancels the order before you ship it, you settle the transaction by voiding the original authorization. Otherwise, you capture the order and the customer's card is officially billed for the amount of the sale.

Figure 6: Reviewing Outstanding Transactions

Another section of the vPOS terminal interface, Operator, is used to review authorized transactions and void or capture them for final settlement. Figure 6 shows the Operator section being used to review the outstanding transactions. Figure 7 shows the response from vPOS to the review transactions request. Each authorized transaction is displayed and you are given a button to click for settling the transaction. You simply click on the Go button to perform a capture on the authorized transaction and settle the sale. It is possible to script this step, too, though that requires a more detailed knowledge of the API exported by the vPOS payment component and is outside the scope of this article.

Figure 7: Response to Review Transactions Request

The key to getting the vPOS payment component to do what you need for your Site Server Commerce Edition store is to set the properties of the OrderForm object that the vPOS software reads when performing its stage of the purchase pipeline. The initial configuration of vPOS, including applying for and receiving the encryption certificates, can be somewhat challenging and time-consuming. If you use software from another vendor, the concepts will be very similar for relaying the credit card and order information to that vendor's payment processing component. However, if your vendor's component does not plug into the pipeline, the steps required to successfully integrate that vendor's payment processing software may be more complicated.     Once you've identified what the customer wants to buy, determined who the customer is, received the customer's credit card information, and sent it to the vPOS payment component, you have to do something with the response you receive from the bank. The credit card transaction will either be approved or denied based on the shopper's available credit balance and the validity of the information sent to the bank, such as the card number and expiration date. In the case where a shopper's card is declined, the i_error.asp page is displayed, and the shopper is notified of the error and allowed to go back and correct it or try a different credit card.     When the credit card transaction is approved, the customer is shown the confirmed.asp page, notifying them that their purchase has been completed successfully. The order confirmation page also tells the shopper when their order will be shipped, or in the case of electronic goods, gives them download access. This page also includes a link to the shopper's receipt. The receipt link sends the shopper to the receipt.asp page where a query is performed based on the shopper ID and the order ID, and a summary of the customer's order is displayed.     One way you may want to customize the store created by the Site Server Commerce Edition wizard is to add an additional address verification check. Verifying that the address supplied by the shopper matches the one on record with the bank helps prevent credit card fraud. Not all banks have implemented an Address Verification Service (AVS) for their online credit card processing service. Additionally, AVS is currently not able to verify addresses from foreign countries.     The code in Figure 8 shows an example of how AVS is used to detect when a customer provides an invalid billing address. It then sends email asking the shopper to return and enter their shopper ID and order ID into a confirmation Web page in order to complete the purchase. Sending email and requesting a response at least verifies that the user has entered a valid email address and is the minimum level of verification we suggest you implement to help prevent fraud.     You may want to telephone any customer whose billing address does not match the bank's records to talk with the person placing the order before deciding whether or not to accept it. Also, any customer who asks that the order be shipped to an address other than the verified billing address that the bank has on record should perhaps be treated with extra caution. Sending these customers email and asking that they return to the site and type in confirmation codes to complete the purchase wouldn't be a bad idea. However, no bank that we are aware of currently requires that you do anything at all to prevent credit card fraud, so these extra steps are entirely optional.     In vPOS, there is a table column that stores the result of a comparison performed between the customer's billing address as supplied by the customer and the customer's billing address in the bank's records. The AVS has five possible return codes:

0 - resultUnavailable 1 - noMatch 2 - addressMatchOnly 3 - postalCodeMatchOnly 4 - fullMatch

Note that these codes are not included in the vPOS product documentation.     Unlike most of the other result codes, where vPOS has provided variables within the OrderForm object, the AVS result is stored directly in a database table. The navresult field in the table storename_vtt contains the address verification result returned from the bank. The nstan field is the key field that uniquely identifies the order. In the global.asa file we created the following query map, which will retrieve the AVS result code from the vPOS database table in which it is stored:

Set MSCSQueryMap.AVS_Result = AddQuery( "SELECT navsresult FROM digitalmkt_vtt WHERE nstan = :1")

In the xt_orderform_ purchase.asp file (where most of the post-order processing is done in Site Server Commerce Edition), we included the script shown in Figure 9 within the OrderFormPurchase function. The vpos_cc_ transaction_id value added to the OrderForm object by vPOS during execution of the purchase pipeline corresponds to the nstan column inside the table and is the unique query key that must be used to retrieve information about the present order.     We created an EmailConfirmation.asp file to process the order and shopper IDs to be entered by the shopper in the event that there is an address mismatch detected by AVS. We use Collaboration Data Objects (CDONTS.NewMail) to send the address confirmation email from within our script. The email simply tells the customer what happened and directs him or her to the URL for our EmailConfirmation.asp page. The contents of this page are shown in Figure 9.     This address verification is only one example of post-order processing you may want to do. Most of the post-order processing is handled within the xt_orderform_purchase.asp, confirmed.asp, and receipt.asp files. vPOS includes variables to track the entire credit card processing transaction, including the time and date of the transaction, the result code, a unique number to track the order, and more. You can expect any credit card processing software you integrate to include these types of variables. Conclusion       Implementing a credit card processing system can be frustrating and time-consuming. Good documentation telling you which objects and tables contain the values you need to access before, during, and after the transaction will speed you along the way. The tools provided within the store by the Site Server Commerce Foundation Wizard will make the job of modifying objects like the OrderForm a much simpler task. Once you have a handle on some of these basics, you can create an extremely powerful Internet store quickly and easily.     The complete source to the real-world sample discussed in this article, Digital Marketplace, can be downloaded from the Windows® source code area of the site http://www.digitalmarketplace.com/department.asp?aisle=windowssourcecode&sessionID=34D5B149B0CD46FCA77AD9B2D516B45A.

http://msdn.microsoft.com/workshop/ server/commerce/promotions101.asp and http://msdn.microsoft.com/workshop/ essentials/forstarters/starts082498.asp

From the August 1999 issue of Microsoft Internet Developer.