|
|
|
|
|
|
Payment Services
WebLogic Portal includes a flexible payment service that lets you connect to a third-party payment product for authorizing and settling orders. The payment service itself currently allows credit card payments to be made. This topic describes the Payment Services in detail.
This topic includes the following sections:
How the Payment Service Works
For an introduction to Web services, see Introduction to Web Services in Taxation Services.
Figure 6-1 shows the basic architecture of WebLogic Portal's payment service. The key component of this architecture is the Credit Card Web Service, which is the connection point between WebLogic Portal and any third-party payment product.
Figure 6-1 Payment Service Architecture
Following is a description of each piece of the architecture. Because no industry standards exist yet for handling payment tasks (such as authorization, retry, and settle), third-party payment products have their own APIs handling these tasks. There are two keys to connecting an enterprise application with a third-party payment Web service:
For information on connecting an enterprise application to a Web service, see Integrating with a Payment Service.
JavaServer Pages (JSPs)
A primary goal of Order services is to allow you to quickly establish a fully-functioning e-commerce site. To this end, the Payment Service provides you with a Java Server Page (JSP) template that you can use as is, or customize to better meet your needs. This section describes this page in detail.
Note: For a description of the complete set of JSPs used in the WebLogic Portal Web application and a listing of their locations in the directory structure, see the E-Commerce Summary of JSP Templates
documentation.payment.jsp Template
If a customer has already specified payment information in their user profile, the payment.jsp template (shown in Figure 6-2) provides the customer with a list of credit cards (by type and last 4 digits) for selection. Customers wanting to use an existing credit card can simply click its associated Use button to proceed to the next part of the checkout process.
Note: For more information about user profiles, see "Customer Profile Services" in the Guide to Registering Customers and Managing Customer Services.
Customers can also choose to update the information associated with this credit card by clicking the Update This Card button. If your customer wants to use a credit card they have never used on your e-commerce site before, the customer can click the Add Card button to add it to the list (using the paymentnewcc.jsp template). If a customer wants to go back to the previous page, the customer can click the Back button.
Sample Browser View
Figure 6-2 shows an annotated version of the payment.jsp template. The Payment region uses a combination of the WebLogic Server and WebLogic Portal JSP tags to obtain and display the customer's saved credit card(s).
Note: For information on other elements in the payment.jsp template, see Common JSP Template Elements.
Figure 6-2 Annotated payment.jsp Template
Location in the WebLogic Portal Directory Structure You can find the payment.jsp template file at the following location, where PORTAL_HOME is the directory in which you installed WebLogic Portal: %PORTAL_HOME%\applications\wlcsApp\wlcs\commerce\order\ Tag Library Imports The payment.jsp template uses existing WebLogic Server and WebLogic Portal's User Management JSP tags. Therefore, the template includes the following JSP tag libraries: Note: For more information on the WebLogic Server JSP tags or the WebLogic Portal JSP tags, see "JSP Tag Reference" in the Guide to Building Personalized Applications. These files reside in the lib directory within PORTAL_HOME. Java Package Imports The payment.jsp template uses Java classes in the following packages and therefore includes these import statements: Location in Default Webflow Customers arrive at payment.jsp from the page where they select their shipping address (selectaddress.jsp). If they choose to add a new credit card, they will be directed to the paymentnewcc.jsp template. If the customer chooses to edit one of the cards that appears in the list, the customer will be directed to the paymenteditcc.jsp template. After selecting a credit card for payment, customers move on to the final page in the checkout process, where they can review their order prior to committing it (checkout.jsp). Note: For more information about the default Webflow, see Overview of Managing Purchases and Processing Orders. Included JSP Templates The following JSP templates are included in the payment.jsp template:
payment.jsp (Windows)
$PORTAL_HOME/applications/wlcsApp/wlcs/commerce/order/
payment.jsp (UNIX)<%@ taglib uri="webflow.tld" prefix="webflow" %>
<%@ taglib uri="um.tld" prefix="um" %>
<%@ taglib uri="weblogic.tld" prefix="wl" %><%@ page import="javax.servlet.*" %>
<%@ page import="javax.servlet.http.*" %>
<%@ page import="com.beasys.commerce.webflow.tags.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.customer.*" %>
<%@ page import="com.beasys.commerce.webflow.HttpRequestConstants" %>
Events
The payment.jsp template presents a customer with several buttons, each of which is considered an event. These events trigger a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or Pipeline is invoked first. Table 6-1 provides information about these events and the business logic they invoke.
Dynamic Data Display
The purpose of the payment.jsp template is to display a list of the customer's previously saved credit cards. This is accomplished on the payment.jsp template using a combination of WebLogic Server and WebLogic Portal JSP tags and accessor methods/attributes.
First, the getProfile JSP tag is used to set the customer profile (context) for which the credit cards should be retrieved, as shown in Listing 6-1.
Listing 6-1 Setting the Customer Context
<um:getProfile
profileKey="<%=request.getRemoteUser()%>"
profileType="WLCS_Customer" />
Next, the getProperty JSP tag is used to retrieve a cached copy of the possible credit cards for the customer from the database, as shown in Listing 6-2.
Listing 6-2 Retrieving the CreditCardsMap for the Customer
<um:getProperty propertySet="CustomerProperties" propertyName="creditCardsMap" id="creditCardsMapObject" />
You can now iterate through the credit cards contained within the creditCardsMap (using the WebLogic Server JSP tag) and display each credit card in the collection (using a Java scriptlet) as shown in Listing 6-3.
Listing 6-3 Iterating Through and Displaying the Credit Cards
<table>
<wl:repeat
set="<%=((Map)creditCardsMapObject).keySet().iterator()%>"
id="creditCard" type="String" count="100000">
<tr>
<!-- Output the credit card name -->
<td width="50%"><div class="tabletext"><%=creditCard%></div></td>
<!-- The update button -->
<td width="30%" align="right">
<%
String extraParams = HttpRequestConstants.CREDITCARD_KEY + "=" + creditCard;
%>
<a
href="<webflow:createWebflowURL event="button.updatePaymentInfo" httpsInd="calculate" namespace="sampleapp_order" extraParams="<%= extraParams %>" />"><img src="<webflow:createResourceURL resource="/commerce/images/btn_updatecard.gif" />" border="0">
</a>
</td>
<!-- The use button -->
<td width="20%" align="right">
<a
href="<webflow:createWebflowURL event="button.continue" httpsInd="calculate" namespace="sampleapp_order" extraParams="<%= extraParams %>" />"><img src="<webflow:createResourceURL resource="/commerce/images/btn_use.gif" />" border="0">
</a>
</td>
</tr>
<tr>
<td colspan="3"><hr size="1"></td>
</tr>
</wl:repeat>
</table>
Note: For more information on the WebLogic Server JSP tags or the WebLogic Portal JSP tags, see "JSP Tag Reference" in the Guide to Building Personalized Applications.
Form Field Specification
The payment.jsp template does not make use of any form fields.
paymentnewcc.jsp Template
The paymentnewcc.jsp template (shown in Figure 6-3) allows customers to enter information about a new credit card, which will be added to their profile. This information includes the credit card type (VISA, MasterCard, and so on), the name on the card, the card number, the card expiration date (month and 4-digit year), and the billing address (including a street address, city, state, zip/postal code, and country). The customer must click the Save button for the new credit card to be added to the customer's list of credit cards.
Sample Browser View
Figure 6-3 shows an annotated version of the paymentnewcc.jsp template. The New Credit Card region provides customers with a series of form fields that allow customers to add a credit card. This region utilizes the form fields defined in the included newcctemplate.jsp template file, which itself includes the states.jsp and countries.jsp template files. The import call in paymentnewcc.jsp is:
<%@ include file="/commerce/includes/newcctemplate.jsp" %>
Figure 6-3 Annotated paymentnewcc.jsp Template
Location in the WebLogic Portal Directory Structure You can find the paymentnewcc.jsp template file at the following location, where PORTAL_HOME is the directory in which you installed Commerce services: %PORTAL_HOME%\applications\wlcsApp\wlcs\commerce\order\ Tag Library Imports The paymentnewcc.jsp template uses Pipeline and Webflow JSP tags. Therefore, the template includes the following JSP tag libraries: Note: For more information on the Webflow and Pipeline JSP tags, see the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline. These files reside in the lib directory within PORTAL_HOME. Java Package Imports The paymentnewcc.jsp template uses Java classes in the following packages and therefore includes these import statements: Location in Default Webflow Customers arrive at the paymentnewcc.jsp template from the page where they are given the option of selecting a credit card from their profile (payment.jsp). When customers are finished with this page, customers are returned to the payment.jsp template so customers can make their selection. This template is in the sampleapp_order namespace. Note: For more information about the default Webflow, see Overview of Managing Purchases and Processing Orders. Included JSP Templates The following JSP templates are included in the paymentnewcc.jsp template:
paymentnewcc.jsp (Windows)
$PORTAL_HOME/applications/wlcsApp/wlcs/commerce/order/
paymentnewcc.jsp (UNIX)<%@ taglib uri="webflow.tld" prefix="webflow" %>
<%@ page import="javax.servlet.*" %>
<%@ page import="javax.servlet.http.*" %>
<%@ page import="com.beasys.commerce.webflow.tags.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.customer.*" %>
<%@ page import="com.beasys.commerce.webflow.HttpRequestConstants" %>
Events
The paymentnewcc.jsp template presents a customer with a single button, which is considered an event. This event triggers a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or Pipeline is invoked first. Table 6-2 provides information about these events and the business logic they invoke.
Dynamic Data Display
No dynamic data is displayed on the paymentnewcc.jsp template.
Form Field Specification
The purpose of the paymentnewcc.jsp template is to provide form fields that allow the customer to enter new credit card information. It also passes hidden information to the Webflow. The form fields used in the paymentnewcc.jsp template, and a description for each of these form fields, are listed in Table 6-3.
You could add additional fields if your payment service required them.
Note: Parameters that are literals in the JSP code are shown in quotes, while non-literals will require scriptlet syntax (such as
<%= HttpRequestConstants.CUSTOMER_CREDIT_CARD_COUNTRY %>) for use in the JSP.
paymenteditcc.jsp Template
The paymenteditcc.jsp template (shown in Figure 6-4) allows your customers to modify information about one of the credit cards shown in the credit card list. Editable information includes the name on the credit card, the expiration date (month and 4-digit year), and the billing address (including street address, city, state, zip/postal code, and country). The customer must click the Save button to save the modifications to their credit card.
Sample Browser View
Figure 6-4 shows an annotated version of the paymenteditcc.jsp template. The Edit Credit Card region provides customers with a series of form fields that allow customers to edit a credit card. This region utilizes the form fields defined in the included editcctemplate.jsp template file, which itself includes the states.jsp and countries.jsp template files. The import call in paymenteditcc.jsp is:
<%@ include file="/commerce/includes/editcctemplate.inc" %>
Note: For information on other elements in the paymenteditcc.jsp template, see Common JSP Template Elements.
Figure 6-4 Annotated paymenteditcc.jsp Template
Location in the WebLogic Portal Directory Structure You can find the paymenteditcc.jsp template file at the following location, where PORTAL_HOME is the directory in which you installed WebLogic Portal: %PORTAL_HOME%\applications/wlcsApp\wlcs\commerce\order\ Tag Library Imports The paymenteditcc.jsp template uses the existing WebLogic Portal's User Management JSP tags, and the Pipeline and Webflow JSP tags. Therefore, the template includes the following JSP tag libraries: Note: For more information on the Webflow and Pipeline JSP tags, see the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline
paymenteditcc.jsp (Windows)
$PORTAL_HOME/applications/wlcsApp/wlcs/commerce/order/
paymenteditcc.jsp (UNIX)<%@ taglib uri="webflow.tld" prefix="webflow" %>
<%@ taglib uri="um.tld" prefix="um" %>
These files reside in the lib directory within PORTAL_HOME.
Java Package Imports
The paymenteditcc.jsp template uses Java classes in the following packages and therefore includes these import statements:
<%@ page import="javax.servlet.*" %>
<%@ page import="javax.servlet.http.*" %>
<%@ page import="com.beasys.commerce.webflow.tags.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.customer.*" %>
<%@ page import="com.beasys.commerce.webflow.HttpRequestConstants" %>
Location in Default Webflow
Customers arrive at paymenteditcc.jsp template from the page where they are given the option of selecting a credit card from their profile (payment.jsp). When customers are finished with this page, they are returned to the payment.jsp template so they can make their selection.
This template is in the sampleapp_order namespace.
Note: For more information about the default Webflow, see Overview of Managing Purchases and Processing Orders.
Included JSP Templates
The following JSP templates are included in the paymenteditcc.jsp template:
Events
The paymenteditcc.jsp template presents a customer with a single button, which is considered an event. This event triggers a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or Pipeline is invoked first. Table 6-4 provides information about these events and the business logic they invoke.
Dynamic Data Display
One purpose of the paymenteditcc.jsp template is to prepare the credit card information a customer had previously entered, so the editcctemplate.jsp template can display this information in the payment information form fields. This is accomplished on the paymenteditcc.jsp template using a combination WebLogic Portal's User Management JSP tags and accessor methods/attributes.
First, the getProfile JSP tag is used to set the customer profile (context) for which the customer information should be retrieved, as shown in Listing 6-4.
Listing 6-4 Setting the Customer Context
<um:getProfile
profileKey="<%=request.getRemoteUser()%>"
profileType="WLCS_Customer" />
Note: For more information on the WebLogic Portal User Management JSP tags, see "JSP Tag Reference" in the Guide to Building Personalized Applications.
Next, the getProperty JSP tag is used to obtain the customer's list of credit cards (and related billing information), which is then initialized with data from the customer object, as shown in Listing 6-5.
Listing 6-5 Obtaining the Customer's Credit Cards and Billing Information
<um:getProperty propertySet="CustomerProperties" propertyName="creditCardsMap" id="creditCards" />
<%
String creditCardKey = request.getParameter(HttpRequestConstants.CREDITCARD_KEY);
CreditCard defaultCreditCard = null;
if(creditCardKey != null)
{defaultCreditCard = (CreditCard)((Map)creditCards).get(creditCardKey);
}
else
{defaultCreditCard = CreditCardHome.create();
}
Address billingAddress = (Address) defaultCreditCard.getBillingAddress();
%>
The data stored within the defaultCreditCard and billingAddress objects can now be accessed by calling accessor methods/attributes within Java scriptlets. Table 6-5 provides more detailed information about the methods/attributes for the default credit card, while Table 6-6 provides more information about the accessor methods/attributes on billingAddress.
Form Field Specification
Another purpose of the paymenteditcc.jsp template is to provide the form fields for the customer's modifications and to pass hidden information to the Webflow. The form fields used in the paymenteditcc.jsp, and a description for each of these form fields, are listed in Table 6-7.
You could add additional fields if your payment service required them.
Note: Parameters that are literals in the JSP code are shown in quotes, while non-literals will require scriptlet syntax (such as
<%= HttpRequestConstants.CUSTOMER_CREDIT_CARD_COUNTRY %>) for use in the JSP.
payment_admin.jsp, paymenthistory.jsp, and payment_info.jsp Templates
Following are descriptions of the payment_admin.jsp, the payment_info.jsp, and the paymenthistory.jsp.
payment_admin.jsp
The payment_admin.jsp is the main page used for payment administration. All payment administration functions go through this page. It interfaces with the CreditCardService EJB for many operations.
payment_info.jsp
The payment_info.jsp provides developer-level information about the Payment JSP files. This file is, out of the box, only available as a popup from the main admin page when you click the More Explanation link under the Payment Administration section.
paymenthistory.jsp
The paymenthistory.jsp lets customers view their payment history by clicking the Payments link under View History in the left side of the window.
Input Processors
This section provides a brief description of each input processor associated with the Payment Services JSP template(s).
PaymentAuthorizationIP
UpdatePaymentInfoIP
Pipeline Components
This section provides a brief description of each Pipeline component associated with the Payment Services JSP templates.
Note: Some Pipeline components extend other, base Pipeline components. For more information on the base classes, see the Javadoc.
PaymentAuthorizationHostPC
PaymentAuthorizationTerminalPC
Integrating with a Payment Service
The Credit Card Web Service that is installed with WebLogic Portal provides a default framework for handling authorization, capture, and settlement of credit card transactions received from the default CreditCardService EJB in the enterprise application. The business methods within the CreditCardService EJB implement a standard workflow that is associated with the completion of credit card transactions, and the current state of the transaction is maintained and each action is journaled. (The Credit Card Web Service, by comparison, is a stateless session EJB wrapped in code that makes it a Web service.)
Integrating your enterprise applications with the payment Web service involves modifying either the CreditCardService EJB and/or the Credit Card Web Service, depending on who will host the Web service: your organization or the third-party payment vendor.
In either case, it helps to understand the connection relationship between the pieces in the WebLogic Portal payment services and the pieces in the Credit Card Web Service. Figure 6-5 illustrates the connection between the two.
Figure 6-5 The Relationship Between the Credit Card Web Service and the CreditCardService EJB
Caution: The default payment Web service that is shipped with WebLogic Portal always sends payment information through without any errors, as if it were connected to and approved by a third-party payment service. This default processing of payment is not designed for production use. You must integrate with your third-party vendor's payment service to process payment correctly. If the Third-Party Vendor Hosts the Web Service If the third-party vendor hosts the Credit Card Web Service, the vendor will integrate the Web service with their product's API. Here is what your organization must do to connect to the vendor-hosted Web service:
PORTAL_HOME\applications\wlcsApp\src\examples\wlcs\
sampleapp\payment\PS*.java
Compile the source files.
PORTAL_HOME\applications\wlcsApp\src\examples\wlcs\
sampleapp\payment\CreditCardService*.java
Compile the source files.
Note: At startup, WebLogic Server reads the application-config.xml file, so it knows where to find the Web service.
If Your Organization Hosts the Web Service
If your organization hosts the Credit Card Web Service, we strongly recommend that you deploy the Web service on a separate instance of WebLogic Server (that is, use a separate Java Virtual Machine [JVM]) than what your enterprise applications are running on. This way, your enterprise applications are insulated from failures or incidents in the Web service.
Here is what you must do if your organization hosts the Credit Card Web Service:
Caution: These are general, simplified guidelines for integrating with a vendor's API. In actual practice, such integration requires close collaboration with your vendor. We strongly recommend you contact your vendor for assistance.
PORTAL_HOME\applications\paymentWSApp\src\examples\wlcs\
sampleapp\payment\CreditCardWebService*.java
Compile the source files.
For information on using wsgen, see Programming WebLogic Server Web Services at http://download.oracle.com/docs/cd/E13222_01/wls/docs61/webServices/index.html.
PORTAL_HOME\applications\wlcsApp\src\examples\wlcs\
sampleapp\payment\CreditCardService*.java
Compile the source files.
Note: At startup, WebLogic Server reads the application-config.xml file, so it knows where to find the Web service.
Default Payment Services Shipped With WebLogic Portal
The CreditCardWebService EJB is a stateless session bean that provides services related to the authorization, capture, and settlement of credit card transactions. The CreditCardWebService EJB serves as an interface behind which integrations with various payment solutions can be implemented. The current state of each transaction is maintained, and each action is journaled, by the CreditCardService EJB in the wlcsApp application.
Caution: The CreditCardWebService EJB that is shipped with WebLogic Portal is designed to give you an example of the different payment services you can use. The default Web service always sends payment information through without any errors, as if it were connected to and approved by a third-party payment service. This default processing of payment is not designed for production use. You must integrate with your third-party vendor's payment service to process payment correctly.
General characteristics of transactions are described in the following list:
You can configure the Payment service to work with your business model. The methods/entry points are described in detail in the sections that follow.
Authorize
Use this method in the CreditCardService EJB only for terminal-based payment models. This entry point validates the credit card number and reserves credit on the supplied card for the amount specified. When validated, it creates a new entry in the WLCS_TRANSACTION table that records the incident and sets the state based on the payment model. The amount of the transaction is deducted from the open to buy in the customer's credit balance. However, the funds are not transferred to the merchant until settling.
Note: Merchants who are using a terminal-based processor must perform a capture and settlement procedure before the funds from the sale are transferred to their account. This is accomplished by a subsequent call to Capture and/or Settle, depending on the Auto Mark/Auto Settle processor configuration.
AuthorizeAndCapture
Use this method only for host-based payment models. This entry point validates the credit card number and reserves credit on the supplied card for the amount specified. When validated, it creates a new entry in the WLCS_TRANSACTION table that records the incident and sets the state based on the payment model. The amount of the transaction is deducted from the open to buy in the customer's credit balance. However, the funds are not transferred to the merchant until settling.
Note: Merchants who are using a host-based post-authorization capture processor must perform a capture and settlement procedure before the funds from the sale are transferred to their account.
BatchQuery
Use this method to update and reconcile the status of a transaction committed in a given batch. This entry point determines if a particular transaction has failed, and is essential for payment processors where the status of an item cannot be determined correctly from the output fields of a batch-commit message. BatchQuery always returns success on the query and creates a TransactionEntry to reflect this success.
Note: This method is implemented as a pass through to the underlying service provider. Subsequently, all return information is service specific. For details on return codes and results, see your service providers documentation.
QueryTransactions
Use this method to query the Payment server for transactions that match the designated parameters. You need only to supply non-null values for those parameters that you want to query against. However, you must supply at least one non-null parameter. Always returns OK.
Note: This method is implemented as a pass through to the underlying service provider. Subsequently, all return information is service specific. For details on return codes and results, see your service provider documentation.
Reauthorize
Use this method only for terminal-based payment models. This method attempts to authorize a payment transaction that is in the retry state. After authorization attempt, the payment transaction is updated with the current date and a transaction entry is added to the payment transaction. The modified payment transaction and any service-specific results are then returned.
ReauthorizeAndCapture
Use this method only for host-based payment models. This method attempts to authorize a payment transaction that is in the retry state. After authorization attempt, the payment transaction is updated with the current date and a transaction entry is added to the payment transaction. The modified payment transaction and any service-specific results are then returned.
Settle
Use this method only for terminal-based payment models with a manual-settle processor configuration. This method finalizes a transaction by transferring a portion of the funds previously captured from the customer's account to the merchant's account. The amount can be less than or equal to the captured amount. Always returns settle success.
VoidTransaction
This method aborts previously submitted transactions. Returns OK. The following transactions can be voided:
Credit Card Encryption
For information on credit card encryption, see "Credit Card Security Service" in the Security Guide.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|