LOGIN NAME:

PASSWORD:

:: Web Services :: XWebCheckOut :: Implementation Guides ::

Build Your Own XML/SOAP Web Service Based Shopping Cart
Handle Credit Card Details

The procedures in this implementation guide require that you have some knowledge of XML and ASP.NET web development with the Microsoft Visual Basic.NET development tool.

The steps in this "how-to" implementation guide are:

• Add a "Web Reference" to the XWebCheckOut Web Service
• Add a "Web Form" to the web application
• Write code in the "Codebehind" of the web form to retrieve the Credit Card details by consuming the XWebCheckOut Web Service
• Implement an ASP.NET Form that displays and allows for edits to be made to the Credit Card details

To download the source code for this "how-to" implementation guide, as well as for additional hints and tips, please read our Final Notes.

Add a "Web Reference" to the XWebCheckOut Web Service

• In your web project, add a Web Reference to the XWebCheckOut web service. Here are 2 ways you can accomplish this:

  • Browse the Solution Explorer, right click on References and select Add Web Reference... from the drop down menu.
  • From the File Menu, select Project - Add Web Reference....

• The Add Web Reference pop-up window will open. In the URL textbox, enter the following URI:

  https://ws.xwebservices.com/XWebCheckOut/XWebCheckOut.asmx?wsdl

• Hit the Enter key or click the Go button located to the right of the URL textbox.
• Change the Web reference name to XWebCheckOut for easier reference.
• Click the Add Reference button to complete this step.

Add a "Web Form" to the Web Application

• In your web project, add a Web Form. This is the Web Form that will host the ASP.NET Form which will display and allow for edits to be made to the credit card details. Here are 2 ways you can accomplish this:

  • Browse the Solution Explorer, right click the name of your project, and select Add - Add Web Form....
  • From the File Menu, select Project - Add Web Form....
• Change the Name textbox in the Add New Item pop-up provided to credit_card.aspx.

Write code in the "Codebehind" of the web form to retrieve the Credit Card details by consuming the XWebCheckOut Web Service

Before we begin talking about code, we must keep in mind that during checkout, a visitor may go back and forth between the checkout process steps. Therefore, we account for the Credit Card details already having been provided every time the page loads.

In the first "how-to" implementation guide of our Build Your Own XML/SOAP Web Service Based Shopping Cart series, every order is assigned an Order ID and the Order ID is then stored in a cookie. Using the Order ID stored in the cookie, in the Page_Load subroutine of the web form, we retrieve the Credit Card details by consuming the LoadOrder SOAP method of the XWebCheckOut Web Service:

• Since the web service requires SOAP Headers for authentication purposes, we must first create a new instance of the class representing the SOAP Header and then populate the SOAP Header values:

  ' handle authentication
  Dim objAuth As New XWebCheckOut.AuthHeader
  objAuth.LoginName = "<my_login_name>"
  objAuth.Password = "<my_password>"

  NOTE***: Instead of hard-coding the LoginName and Password values, you may want to dynamically read them from the web.config file (LOGIN_NAME and PASSWORD must be added to the <AppSettings> section of the web.config file):

  objAuth.LoginName = System.Configuration.ConfigurationSettings.AppSettings("LOGIN_NAME")
  objAuth.Password = System.Configuration.ConfigurationSettings.AppSettings("PASSWORD")

• Next, we need to create a new instance of the proxy class and assign the SOAP Header object to the member variable of the proxy class representing the SOAP Header:

  ' create the XWebCheckOut web service proxy
  Dim objOrder As New XWebCheckOut.XWebCheckOut
  objOrder.AuthHeaderValue = objAuth

• We are now ready to call the method on the proxy class that communicates with the Web Service SOAP Method and returns the Order record we requested. Since the method returns the Order record in the form of an XML string, we load an XML DOM with it:

  ' load the xml string into a DOM
  Dim orderDOM As New System.Xml.XmlDocument
  orderDOM.LoadXml(objOrder.LoadOrder(Request.Cookies("OID").Value))

Implement an ASP.NET Form that displays and allows for edits to be made to the Credit Card details

In the Code Editor, we really don't need to declare a Form since there won't be anything that we will be doing with the actual form itself. Instead we need to declare the dropdownlists and textboxes that will display the Credit Card details and the button that when clicked, will store the Credit Card details changes. Then, using the XML DOM, we populate the textbox values. Here's how:

• Declare the dropdownlists and textboxes in the Code Editor, using the Order XSD validation schema as a guide:

  Protected ddlType, ddlExpirationMonth, ddlExpirationYear As System.Web.UI.WebControls.DropDownList
  Protected txtNumber, txtVerificationNumber As System.Web.UI.WebControls.TextBox
  Protected WithEvents btnProceed As System.Web.UI.WebControls.Button

• In the Page_Load subroutine of the web form, since the Order's data is already in an XML DOM, we first check to see if the Credit Card details already exist, then we set the correct index of the dropdownlists and populate the textboxes:

  ' handle the Credit Card element
  Dim ccNode As System.Xml.XmlNode
  ccNode = orderDOM.DocumentElement.SelectSingleNode("Credit_Card")
  
  ' check if Credit Card details already exist
  If Not ccNode Is Nothing Then
     ddlType.SelectedValue =
        ccNode.SelectSingleNode("Type").InnerText
     txtNumber.Text =
        ccNode.SelectSingleNode("Number").InnerText
     ddlExpirationMonth.SelectedValue =
        ccNode.SelectSingleNode("Expiration_Month").InnerText
     ddlExpirationYear.SelectedValue =
        ccNode.SelectSingleNode("Expiration_Year").InnerText
     txtVerificationNumber.Text =
        ccNode.SelectSingleNode("Verification_Number").InnerText
  End If

In the HTML Editor, we define the ASP.NET form, the ASP.NET dropdownlists, the ASP.NET textboxes and an ASP.NET button. Here is the code:

<Form Runat="server">
   <asp:DropDownList ID="ddlType" Runat="server">
      <asp:ListItem Value="1">Visa</asp:ListItem>
      <asp:ListItem Value="2">MasterCard</asp:ListItem>
   </asp:DropDownList>
   <asp:TextBox ID="txtNumber" MaxLength="50" Runat="server" />
   <asp:DropDownList ID="ddlExpirationMonth" Runat="server">
      <asp:ListItem Value="1">01</asp:ListItem>
      <asp:ListItem Value="2">02</asp:ListItem>
      <asp:ListItem Value="3">03</asp:ListItem>
      <asp:ListItem Value="4">04</asp:ListItem>
      <asp:ListItem Value="5">05</asp:ListItem>
      <asp:ListItem Value="6">06</asp:ListItem>
      <asp:ListItem Value="7">07</asp:ListItem>
      <asp:ListItem Value="8">08</asp:ListItem>
      <asp:ListItem Value="9">09</asp:ListItem>
      <asp:ListItem Value="10">10</asp:ListItem>
      <asp:ListItem Value="11">11</asp:ListItem>
      <asp:ListItem Value="12">12</asp:ListItem>
   </asp:DropDownList>
   <asp:DropDownList ID="ddlExpirationYear" Runat="server">
      <asp:ListItem Value="2005">2005</asp:ListItem>
      <asp:ListItem Value="2006">2006</asp:ListItem>
      <asp:ListItem Value="2007">2007</asp:ListItem>
      <asp:ListItem Value="2008">2008</asp:ListItem>
      <asp:ListItem Value="2009">2009</asp:ListItem>
   </asp:DropDownList>
   <asp:TextBox ID="txtVerificationNumber" MaxLength="10" Runat="server" />
   <asp:Button ID="btnProceed" Text="Proceed To Order Confirmation"       Runat="server" />
</Form>

Finally, in the Code Behind, we handle the button's Click event and store the Credit Card details:

' create an order DOM
Dim orderDOM As New System.Xml.XmlDocument
orderDOM.AppendChild(orderDOM.CreateElement("Order"))

'add the order id
Dim oidAttribute As System.Xml.XmlAttribute =
   orderDOM.CreateAttribute("Order_ID")
oidAttribute.InnerText = Request.Cookies("OID").Value
orderDOM.DocumentElement.Attributes.Append(oidAttribute)

' add the Credit Card node
Dim ccNode As System.Xml.XmlElement =
   orderDOM.CreateElement("Credit_Card")

' add the children
Dim typeNode As System.Xml.XmlElement =
   orderDOM.CreateElement("Type")
typeNode.InnerText = ddlType.SelectedValue
ccNode.AppendChild(typeNode)

Dim numberNode As System.Xml.XmlElement =
   orderDOM.CreateElement("Number")
numberNode.InnerText = txtNumber.Text
ccNode.AppendChild(numberNode)

Dim emNode As System.Xml.XmlElement =
   orderDOM.CreateElement("Expiration_Month")
emNode.InnerText = ddlExpirationMonth.SelectedValue
ccNode.AppendChild(emNode)

Dim eyNode As System.Xml.XmlElement =
   orderDOM.CreateElement("Expiration_Year")
eyNode.InnerText = ddlExpirationYear.SelectedValue
ccNode.AppendChild(eyNode)

Dim vnNode As System.Xml.XmlElement =
   orderDOM.CreateElement("Verification_Number")
vnNode.InnerText = txtVerificationNumber.Text
ccNode.AppendChild(vnNode)

' append the Credit Card Node
orderDOM.DocumentElement.AppendChild(ccNode)

' store the Credit Card details
' handle authentication
Dim objAuth As New XWebCheckOut.AuthHeader
objAuth.LoginName =
   System.Configuration.ConfigurationSettings.AppSettings("LOGIN_NAME")
objAuth.Password =
   System.Configuration.ConfigurationSettings.AppSettings("PASSWORD")

' create the XWebCheckOut web service proxy
Dim objOrder As New XWebCheckOut.XWebCheckOut
objOrder.AuthHeaderValue = objAuth

' call the ProcessOrder SOAP method
Dim strResult As String =
   objOrder.ProcessOrder(orderDOM.DocumentElement.OuterXml)
If strResult <> "" Then Throw New Exception(strResult)

Final Notes

The source code for this "how-to" implementation guide can be downloaded by clicking the link below (zip file, contains the source code for all "how-to" implementation guides for the XWebCheckOut Web Service)

XWebCheckOutClient.zip

In this "how-to" implementation guide we hardcoded the Credit Card Types. However, the XWebCheckOut Web Service does provide the LoadCreditCardTypes SOAP Method if you prefer to populate the dropdownlist dynamically.

The XWebCheckOut Web Service also provides the means to store special payment arrangements (i.e. not paying by Credit Card). Simply add a <Comments> node to the Order DOM and then store each special payment arrangement as its own <Comment> node.

It's always good practice to implement a Try...Catch... error handling technique to handle some or all possible errors that may occur while the code is executing. We strongly recommend that you implement such a technique.