|
|
|
|
|
|
Payment Services
The Order Processing package also contains a Payment Service, which specifies how payment for an order is authorized and settled. Currently the Payment Service allows credit card payments to be made using the CyberCash, Inc. service. However, the JSP templates, input processors, and Pipeline components allow different services to be integrated. This topic describes the Payment Services in detail.
This topic includes the following sections:
JavaServer Pages (JSPs)
A primary goal of the Commerce Server's Order Processing package is to allow you to quickly establish a fully-functioning e-commerce site. To this end, the Payment Service provides you with a JavaServer Page (JSP) template that you can use as is, or customize to better meet your needs. This section describes this page in detail.
payment.jsp Template
If a customer has already specified payment information in their user profile, the payment.jsp template (shown in Figure 6-1) 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 BEA WebLogic Commerce Server Registration and User Processing Package documentation.
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-1 shows an annotated version of the payment.jsp template. The dashed lines and numbers in the diagram are not part of the template; they are referenced in the explanation that follows the screen shot.
Figure 6-1 Annotated payment.jsp Template
The numbers in the following list refer to the numbered regions in the figure:
<%@ include file="/commerce/includes/innerheader.jsp" %>
<%@ include file="/commerce/includes/innerfooter.jsp" %>
innerfooter.jsp consists of the horizontal footer at the bottom of the page, plus the right-side vertical column that describes (for the benefit of you and your development team) the name of the current template and links to its About information. In the innerfooter.jsp file, the right-side vertical column is an include file:
<%@ include file="/commerce/includes/rightside.jsp" %>
Location in the WebLogic Commerce Server Directory Structure
You can find the payment.jsp template file at the following location, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server:
%WL_COMMERCE_HOME%\server\webapps\wlcs\commerce\order\payment.jsp (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/commerce/order/payment.jsp (UNIX)
Tag Library Imports
The payment.jsp template uses existing WebLogic Server and the WebLogic Personalization Server's User Management JSP tags. Therefore, the template includes the following JSP tag libraries:
<%@ taglib uri="weblogic.tld" prefix="wl" %>
<%@ taglib uri="um.tld" prefix="um" %>
Note: For more information on the WebLogic Server JSP tags or the WebLogic Personalization Server JSP tags, see "JSP Tag Reference" in the BEA WebLogic Personalization Server documentation.
These files reside in the following directory for the WebLogic Commerce Server Web application:
%WL_COMMERCE_HOME%\server\webapps\wlcs\WEB-INF (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/WEB-INF (UNIX)
Java Package Imports
The payment.jsp template uses Java classes in the following packages and therefore includes these import statements:
<%@ page import="java.servlet.*" %>
<%@ page import="java.servlet.http.*" %>
<%@ page import="com.beasys.commerce.webflow.*" %>
<%@ page import="com.beasys.commerce.webflow.tags.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.customer.*" %>
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 the Order Processing Package.
Included JSP Templates
The following JSP templates are included in the payment.jsp template:
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.
|
Event |
Webflow Response(s) |
|---|---|
|
button(addNewCreditCard) |
No business logic required. Loads paymentnewcc.jsp. |
|
button(continue) |
AuthorizePaymentIP |
|
button(updatePaymentInfo) |
No business logic required. Loads paymenteditcc.jsp. |
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 Personalization Server 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 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)credtCardsMapObject).keySet().iterator()%>"
id="creditCard" type="String" count="100000">
<tr>
<td><%=creditCard%></td>
</tr>
</wl:repeat>
</table>
Note: For more information on the WebLogic Server JSP tags or the WebLogic Personalization Server JSP tags, see "JSP Tag Reference" in the BEA WebLogic Personalization Server documentation.
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-2) 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-2 shows an annotated version of the paymentnewcc.jsp template. The dashed lines and numbers in the diagram are not part of the template; they are referenced in the explanation that follows the screen shot.
Figure 6-2 Annotated paymentnewcc.jsp Template
The numbers in the following list refer to the numbered regions in the figure:
<%@ include file="/commerce/includes/innerheader.jsp" %>
<%@ include file="/commerce/includes/newcctemplate.jsp" %>
<%@ include file="/commerce/includes/innerfooter.jsp" %>
innerfooter.jsp consists of the horizontal footer at the bottom of the page, plus the right-side vertical column that describes (for the benefit of you and your development team) the name of the current template and links to its About information. In the innerfooter.jsp file, the right-side vertical column is an include file:
<%@ include file="/commerce/includes/rightside.jsp" %>
Location in the WebLogic Commerce Server Directory Structure
You can find the paymentnewcc.jsp template file at the following location, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server:
%WL_COMMERCE_HOME%\server\webapps\wlcs\commerce\order\
paymentnewcc.jsp (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/commerce/order/
paymentnewcc.jsp (UNIX)
Tag Library Imports
The paymentnewcc.jsp template uses Pipeline and Webflow JSP tags. Therefore, the template includes the following JSP tag libraries:
<%@ taglib uri="webflow.tld" prefix="webflow" %>
<%@ taglib uri="pipeline.tld" prefix="pipeline" %>
Note: For more information on the Webflow and Pipeline JSP tags, see BEA WebLogic Commerce Server Webflow and Pipeline Management.
These files reside in the following directory for the WebLogic Commerce Server Web application:
%WL_COMMERCE_HOME%\server\webapps\wlcs\WEB-INF (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/WEB-INF (UNIX)
Java Package Imports
The paymentnewcc.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.*" %>
<%@ page import="com.beasys.commerce.webflow.tags.*" %>
<%@ page import="com.beasys.commerce.foundation.pipeline.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.customer.*" %>
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.
Note: For more information about the default Webflow, see Overview of the Order Processing Package.
Included JSP Templates
The following JSP templates are included in the paymentnewcc.jsp template:
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.
|
Event |
Webflow Response(s) |
|---|---|
|
button(save) |
UpdatePaymentInfoIP |
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.
|
Parameter Name |
Type |
Description |
|---|---|---|
|
"event" |
Hidden |
Indicates which event has been triggered. It is used by the Webflow to determine what happens next. |
|
"origin" |
Hidden |
The name of the current page (paymentnewcc.jsp), used by the Webflow. |
|
HttpRequestConstants. |
Listbox |
The type of the customer's credit card. |
|
HttpRequestConstants. |
Textbox |
The name on the credit card. |
|
HttpRequestConstants. |
Textbox |
The number of the customer's credit card. |
|
HttpRequestConstants. |
Listbox |
The month of the customer's credit card expiration date. |
|
HttpRequestConstants. |
Listbox |
The year of the customer's credit card expiration date. |
|
HttpRequestConstants. |
Textbox |
The first line in the customer's billing address. |
|
HttpRequestConstants. |
Textbox |
The second line in the customer's billing address. |
|
HttpRequestConstants. |
Textbox |
The city in the customer's billing address. |
|
HttpRequestConstants. |
Listbox |
The state in the customer's billing address. |
|
HttpRequestConstants. |
Textbox |
The zip/postal code in the customer's billing address. |
|
HttpRequestConstants. |
Listbox |
The country in the customer's billing address. |
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-3) 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-3 shows an annotated version of the paymenteditcc.jsp template. The dashed lines and numbers in the diagram are not part of the template; they are referenced in the explanation that follows the screen shot.
Figure 6-3 Annotated paymenteditcc.jsp Template
The numbers in the following list refer to the numbered regions in the figure:
<%@ include file="/commerce/includes/innerheader.jsp" %>
<%@ include file="/commerce/includes/editcctemplate.jsp" %>
<%@ include file="/commerce/includes/innerfooter.jsp" %>
innerfooter.jsp consists of the horizontal footer at the bottom of the page, plus the right-side vertical column that describes (for the benefit of you and your development team) the name of the current template and links to its About information. In the innerfooter.jsp file, the right-side vertical column is an include file:
<%@ include file="/commerce/includes/rightside.jsp" %>
Location in the WebLogic Commerce Server Directory Structure
You can find the paymenteditcc.jsp template file at the following location, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server:
%WL_COMMERCE_HOME%\server\webapps\wlcs\commerce\order\
paymenteditcc.jsp (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/commerce/order/
paymenteditcc.jsp (UNIX)
Tag Library Imports
The paymenteditcc.jsp template uses the existing WebLogic Personalization Server's User Management JSP tags, and the Pipeline and Webflow JSP tags. Therefore, the template includes the following JSP tag libraries:
<%@ taglib uri="webflow.tld" prefix="webflow" %>
<%@ taglib uri="pipeline.tld" prefix="pipeline" %>
<%@ taglib uri="um.tld" prefix="um" %>
Note: For more information on the Webflow and Pipeline JSP tags, see BEA WebLogic Commerce Server Webflow and Pipeline Management. For more information on the WebLogic Personalization Server JSP tags, see "JSP Tag Reference" in the BEA WebLogic Personalization Server documentation.
These files reside in the following directory for the WebLogic Commerce Server Web application:
%WL_COMMERCE_HOME%\server\webapps\wlcs\WEB-INF (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/WEB-INF (UNIX)
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.*" %>
<%@ page import="com.beasys.commerce.webflow.tags.*" %>
<%@ page import="com.beasys.commerce.foundation.pipeline.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.customer.*" %>
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.
Note: For more information about the default Webflow, see Overview of the Order Processing Package.
Included JSP Templates
The following JSP templates are included in the paymenteditcc.jsp template:
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.
|
Event |
Webflow Response(s) |
|---|---|
|
button(save) |
UpdatePaymentInfoIP |
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 the WebLogic Personalization Server'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 Personalization Server's User Management JSP tags, see "JSP Tag Reference" in the BEA WebLogic Personalization Server documentation.
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 propertyName="creditCardsMap"
id="creditCardsMapObject" />
<%
Map creditCardsMap = (Map) creditCardsMapObject;
String creditCardKey =
request.getParameter(HttpRequestConstants.CREDITCARD_KEY);
CreditCard defaultCreditCard = null;
defaultCreditCard = (CreditCard) creditCardsMap.get(creditCardKey);
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.
|
Method/Attribute |
Description |
|---|---|
|
getType() |
The credit card type (VISA, MasterCard, AMEX, and so on). |
|
getName() |
The credit card holder's name. |
|
getDisplayNumber() |
The credit card number for display (12 Xs and last 4 digits). |
|
getNumber() |
The credit card number. |
|
getExpirationDate() |
The credit card's expiration date. |
|
Method/Attribute |
Description |
|---|---|
|
getStreet1() |
The first line in the customer's billing street address. |
|
getStreet2() |
The second line in the customer's billing street address. |
|
getCity() |
The city in the customer's billing address. |
|
getCounty() |
The county in the customer's billing address. |
|
getState() |
The state in the customer's billing address. |
|
getPostalCode() |
The zip/postal code in the customer's billing address. |
|
getCountry() |
The country in the customer's billing address. |
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.
|
Parameter Name |
Type |
Description |
|---|---|---|
|
"event" |
Hidden |
Indicates which event has been triggered. It is used by the Webflow to determine what happens next. |
|
"origin" |
Hidden |
The name of the current page (paymenteditcc.jsp), used by the Webflow. |
|
HttpRequestConstants. |
Listbox |
The type of the customer's credit card. |
|
HttpRequestConstants. |
Textbox |
The name on the credit card. |
|
HttpRequestConstants. |
Textbox |
The number of the customer's credit card. |
|
HttpRequestConstants. |
Listbox |
The month of the customer's credit card expiration date. |
|
HttpRequestConstants. |
Listbox |
The year of the customer's credit card expiration date. |
|
HttpRequestConstants. |
Textbox |
The first line in the customer's billing address. |
|
HttpRequestConstants. |
Textbox |
The second line in the customer's billing address. |
|
HttpRequestConstants. |
Textbox |
The city in the customer's billing address. |
|
HttpRequestConstants. |
Listbox |
The state in the customer's billing address. |
|
HttpRequestConstants. |
Textbox |
The zip/postal code in the customer's billing address. |
|
HttpRequestConstants. |
Listbox |
The country in the customer's billing address. |
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.
Input Processors
This section provides a brief description of each input processor associated with the Payment Services JSP template(s).
PaymentAuthorizationIP
|
Class Name |
com.beasys.commerce.ebusiness.payment.webflow. |
|
Description |
Retrieves the shopping cart from the Pipeline session, the CreditCardMapKey from the request, and determines the total price of the order associated with the shopping cart. Adds the amount and credit card associated with the key to the Pipeline session. |
|
Required HTTPServletRequest Parameters |
HttpRequestConstants.CREDITCARD_KEY |
|
Required Pipeline |
PipelineSessionConstants.SHOPPING_CART |
|
Updated Pipeline |
PipelineSessionConstants.PAYMENT_CREDIT_CARD PipelineSessionConstants.PAYMENT_AUTHORIZATION_AMOUNT |
|
Removed Pipeline |
None |
|
Validation |
Verifies that the credit card key is valid and that it references an existing credit card. |
|
Exceptions |
ProcessingException, thrown for invalid types of CREDITCARD_KEY, PAYMENT_CREDIT_CARD, or SHOPPING_CART. Also thrown if these attributes are not available. |
|
Class Name |
com.beasys.commerce.ebusiness.customer.webflow. UpdatePaymentInfoIP |
|
Description |
Processes the customer's input from paymentnewcc.jsp and paymenteditcc.jsp. Retrieves the customer name from the Pipeline session, creates a new CustomerValue object, and sets it in the Pipeline session. |
|
Required HTTPServletRequest Parameters |
HttpRequestConstants.CUSTOMER_CREDITCARD_TYPE HttpRequestConstants.CUSTOMER_CREDITCARD_HOLDER HttpRequestConstants.CUSTOMER_CREDITCARD_NUMBER HttpRequestConstants.CUSTOMER_CREDITCARD_MONTH HttpRequestConstants.CUSTOMER_CREDITCARD_YEAR HttpRequestConstants.CUSTOMER_CREDITCARD_ADDRESS1 HttpRequestConstants.CUSTOMER_CREDITCARD_ADDRESS2 HttpRequestConstants.CUSTOMER_CREDITCARD_CITY HttpRequestConstants.CUSTOMER_CREDITCARD_STATE HttpRequestConstants.CUSTOMER_CREDITCARD_ZIPCODE HttpRequestConstants.CUSTOMER_CREDITCARD_COUNTRY |
|
Required Pipeline |
PipelineSessionConstants.USER_NAME |
|
Updated Pipeline |
PipelineSessionConstants.CUSTOMER |
|
Removed Pipeline |
None |
|
Validation |
Verifies that the required fields contain values. |
|
Exceptions |
InvalidInputException, thrown if invalid credit card information is obtained from the HttpServletRequest. |
Pipeline Components
This section provides a brief description of each Pipeline component associated with the Payment Services JSP templates(s).
Note: Some Pipeline components extend other, base Pipeline components. For more information on the base classes, see the Javadoc.
PaymentAuthorizationHostPC
|
Class Name |
com.beasys.commerce.ebusiness.payment.pipeline. |
|
Description |
Authorizes a given credit card for a specified amount. Used for host-based payment models, shown in the weblogiccommerce.properties file as: HOST_AUTH_CAPTURE HOST_AUTH_CAPTURE_AVS HOST_POST_AUTH_CAPTURE HOST_POST_AUTH_CAPTURE_AVS |
|
Required Pipeline |
PipelineSessionConstants.PAYMENT_CREDIT_CARD PipelineSessionConstants.PAYMENT_AUTHORIZATION_AMOUNT PipelineSessionConstants.ORDER_HANDLE (Request scope) |
|
Updated Pipeline |
None |
|
Removed Pipeline |
None |
|
Type |
Java object |
|
JNDI Name |
None |
|
Exceptions |
AuthorizationFailureException, thrown when the credit card being used for authorization is invalid (that is, the number or other associated information is incorrect).
|
PaymentAuthorizationTerminalPC
|
Class Name |
com.beasys.commerce.ebusiness.payment.pipeline. |
|
Description |
Authorizes a given credit card for a specified amount. Used for terminal-based payment models, shown in the weblogiccommerce.properties file as: AUTO_MARK_AUTO_SETTLE AUTO_MARK_AUTO_SETTLE_AVS AUTO_MARK_MANUAL_SETTLE AUTO_MARK_MANUAL_SETTLE_AVS MANUAL_MARK_AUTO_SETTLE MANUAL_MARK_AUTO_SETTLE_AVS MANUAL_MARK_MANUAL_SETTLE MANUAL_MARK_MANUAL_SETTLE_AVS |
|
Required Pipeline |
PipelineSessionConstants.PAYMENT_CREDIT_CARD PipelineSessionConstants.PAYMENT_AUTHORIZATION_AMOUNT PipelineSessionConstants.ORDER_HANDLE (Request scope) |
|
Updated Pipeline |
None |
|
Removed Pipeline |
None |
|
Type |
Java object |
|
JNDI Name |
None |
|
Exceptions |
AuthorizationFailureException, thrown when the credit card being used for authorization is invalid (that is, the number or other associated information is incorrect).
|
Integration with CyberCash
Part of the functionality provided by the Payment Services is their ability to interact with CyberCash, a service which allows you to accept credit cards from customers over the Internet. However, to run CyberCash with the Order Processing package's Payment Services, you will need to perform a number of configuration activities so that CyberCash, your financial institution (credit card provider), and the Payment Services can work together as shown in Figure 6-4.
Figure 6-4 CyberCash Interactions Diagram
Note: For more information about CyberCash, Inc. and their payment solutions, see http://www.cybercash.com.
Configuration Activities for Using CyberCash
The following is a list of the configuration activities you must perform in order to use CyberCash with the Order Processing package's Payment Services:
Note: For more information about the possible payment models, see Payment Models.
Note: Be sure to carefully read the instructions in the weblogiccommerce.properties file under the Payment Services heading prior to making any changes.
Listing 6-6 Setting the CyberCashConfigFile Property
###############################################
# Properties required for the payment component
###############################################
#
# This property defers payment authorization to the administration tools.
# If set to true, all payment service authorization calls are disabled
# and payment transactions are persisted in a RETRY state. Payments must
# then be reauthorized through the payment administration tool.
#
commerce.payment.defer.authorization=true
#
# CyberCash configuration files contain CyberCash-specific data, such as a
# merchant-id and merchant hash secret. The specific properties in the
# configuration files depend upon the payment model assigned to a merchant by
# his/her financial institution. The two files declared below are example files # and are provided for demonstration purposes ONLY. MERCHANGS MUST ACQUIRE A
# CYBERCASH CONFIGURATION FILE FROM CYBERCASH. These will be furnished by
# CyberCash as part of the merchant agreement. Once a merchang has a CyberCash
# configuration file, the property below must be replaced with the location of
# the configuration file.
#
# Example: CyberCashConfigFile=c:/merchang/config/file/location/merchant_conf
# This file may be used for testing terminal based payment models.
CyberCashConfigFile=@BEA_WEBLOGIC_COMMERCE_SERVER_HOME@/eval/common/CyberCash/
conf/merchant_conf-terminal
# This file may be used for testing host based payment models.
CyberCashConfigFile=@BEA_WEBLOGIC_COMMERCE_SERVER_HOME@/eval/common/CyberCash/
conf/merchant_conf-host
Note: Single front slashes (or double back slashes) are required in this location specification.
Note: For instructions on how to use the payment management administration tool, see Using the Order and Payment Management Pages.
Listing 6-7 Setting the PaymentModel Property
#
# Properties below represent the different payment models provided # by CyberCash.
#
# Terminal based models
PaymentModel=AUTO_MARK_AUTO_SETTLE
# PaymentModel=AUTO_MARK_AUTO_SETTLE_AVS
# PaymentModel=AUTO_MARK_MANUAL_SETTLE
# PaymentModel=AUTO_MARK_MANUAL_SETTLE_AVS
# PaymentModel=MANUAL_MARK_AUTO_SETTLE
# PaymentModel=MANUAL_MARK_AUTO_SETTLE_AVS
# PaymentModel=MANUAL_MARK_MANUAL_SETTLE
# PaymentModel=MANUAL_MARK_MANUAL_SETTLE_AVS
# Host based models
#PaymentModel=HOST_AUTHCAPTURE
#PaymentModel=HOST_AUTHCAPTURE_AVS
#PaymentModel=HOST_AUTH_POSTAUTH
#PaymentModel=HOST_AUTH_POSTAUTH_AVS
Note: Detailed documentation for CyberCash, Inc. products can be found online at http://www.cybercash.com/cashregister/docs/.
Payment Models
There are two types of payment models: terminal-based and host-based. The difference between these payment models is where the transaction batch is stored. For a host-based model, the transaction batch is stored on the host network rather than on the local system at the merchant's site. Settlement typically occurs sometime at the end of the day, and the merchant is not required to do anything to initiate the settlement process.
For a terminal-based model, the transaction batch is stored as data files on the local system at the merchant's site. Merchants must initiate the settlement process at the end of each day in order for the funds to be transfered to the merchant's bank account.
Table 6-8 describes each of the terminal-based payment models that may be assigned by your financial institution. Table 6-9 describes each of the host-based payment models that may be assigned.
|
Payment Model |
Description |
|---|---|
|
AUTO_MARK_AUTO_SETTLE |
This payment model is used for soft goods. Settlement occurs as soon as authorization is complete, because it is assumed that soft goods are shipped at the time of purchase. |
|
AUTO_MARK_MANUAL_SETTLE |
This payment model is used in cases where goods have been shipped at authorization but the merchant requests that funds should be transferred at a later date. |
|
MANUAL_MARK_AUTO_SETTLE |
This payment model allows merchants to indicate that the goods have been shipped, at which point settlement is done automatically. |
|
MANUAL_MARK_MANUAL_SETTLE |
This is the most flexible payment model in that it allows merchants to specify when goods are shipped and when funds should be transferred. The mark process allows the merchant to specify that the goods have been shipped. The settlement process allows the merchant to indicate that funds may be transferred. |
Note: Each of the terminal-based payment models may be suffixed by _AVS. This suffix indicates that merchants are also required to send an address. The BEA WebLogic Commerce Server product always sends this address for verification purposes.
|
Payment Model |
Description |
|---|---|
|
HOST_AUTH_CAPTURE |
This payment model is used for services, sale of digital goods, or physical goods shipped within 24 hours of when the order is placed. In this case, the merchant only needs to get an authorization for the purchase amount. The capture of the authorization into the batch and the settlement of the transaction are done for the merchant by the processor at the time of authorization. |
|
HOST_POST_AUTH_CAPTURE |
When the merchant fulfills orders more than one day after receiving them, the merchant must authorize and capture transactions separately. In this payment model, authorization is performed at the time the consumer wants to make the purchase. Capture is performed when the merchant ships the order. The processor handles settlement of the batched transactions at certain times of the day. |
Note: Each of the host-based payment models may be suffixed by _AVS. This suffix indicates that merchants are also required to send an address. The BEA WebLogic Commerce Server product always sends this address for verification purposes.
How Do I Switch Between the Two Payment Models?
If you decide to use the terminal-based payment model, your Web application must use the PaymentAuthorizationTerminalPC Pipeline component. If you decide to use the host-based payment model, your Web application must use the PaymentAuthorizationHostPC Pipeline component instead.
To change the Pipeline component to reflect the payment model, follow these steps:
Note: For more information about the properties associated with the PaymentAuthorizationTerminalPC and PaymentAuthorizationHostPC Pipeline components, see Pipeline Components.
What if I Don't Want to Use CyberCash for Credit Card Processing?
The BEA WebLogic Commerce Server product provides you with a CyberCash-based implementation of a Payment Service. However, you may want to use a service provider other than CyberCash. Use of a different provider requires that you implement a payment authorization Pipeline component that is specific to the provider of your choice.
Note: It is expected that a Java/EJB programmer (or someone with similar technical knowledge and abilities) will develop new Pipeline components.
To implement a new Pipeline component for a Payment Service provider other than CyberCash, perform the following steps:
Listing 6-8 Creating a New Pipeline Component
// java imports
import java.rmi.RemoteException;
import java.sql.Date;
import java.sql.Connection;
// javax imports
import javax.ejb.*;
// com.beasys imports
import com.beasys.commerce.ebusiness.payment.*;
import com.beasys.commerce.ebusiness.order.*;
import com.beasys.commerce.ebusiness.security.*;
import com.beasys.commerce.axiom.contact.*;
import com.beasys.commerce.axiom.units.*;
import com.beasys.commerce.axiom.util.helper.*;
import com.beasys.commerce.webflow.*;
import com.beasys.commerce.foundation.*;
import com.beasys.commerce.foundation.exception.*;
import com.beasys.commerce.foundation.pipeline.*;
import com.beasys.commerce.util.*;
/**
* This <code>PipelineComponent</code> authorizes a credit card
* for a purchase of a given amount using a payment service other
* than CyberCash. This class is a concrete extension of the
* <code>CommercePipelineComponent</code> abstract base class.
*
* PipelineSession input attributes:
* PipelineSessionConstants.PAYMENT_CREDIT_CARD
* PipelineSessionConstants.PAYMENT_AUTHORIZATION_AMOUNT
* PipelineSessionConstants.ORDER_HANDLE
*/
public class MyPaymentAuthorizationPC extends
CommercePipelineComponent
{
Listing 6-9 Implementing the process() Method
/**
* Authorize a credit card for a purchase amount.
*
* @param pipelineSession The current PipelineSession
* @throws PipelineFatalException on fatal error
* @throws PipelineNonFatalException on non-fatal error
* @throws RemoteException on remote error
*/
public PipelineSession process(PipelineSession pipelineSession)
throws PipelineFatalException, PipelineNonFatalException, RemoteException {
//
// Get the order, credit card, and authorization amount from
// the PipelineSession.
//
CreditCard card = (CreditCard)pipelineSession.
getAttribute(PipelineSessionConstants.PAYMENT_CREDIT_CARD);
Price amount = (Price)pipelineSession.getAttribute
(PipelineSessionConstants.PAYMENT_AUTHORIZATION_AMOUNT);
Handle orderHandle = (Handle)pipelineSession.getAttribute
(PipelineSessionConstants.ORDER_HANDLE, PipelineConstants.REQUEST_SCOPE);
Order order = (Order)(orderHandle.getEJBObject());
//Create a Transaction ID
//This can be done with any persistent number generator.
//Every transaction ID must be unique.
//Look at //http://edocs.beasys.com/wlcs/docs32/javadoc/wlps/com/beasys/
//commerce/util/Sequencer.html for information on the Sequencer interface.
com.beasys.commerce.util.Sequencer mySequencer = com.beasys.commerce.util.SequencerFactory.createSequencer
("PaymentTransactionIDSequence");
mySequencer.setCacheSize(10); //optional
Connection myConnection = getConnection();
long myTransactionID = 0;
try {
myTransactionID = mySequencer.getNext(myConnection);
} catch(java.sql.SQLException sqlException) {
//Add the appropriate exception handling logic.
}
//
// Decrypt the credit card using the Decryptor service.
//
String creditCardNumber = null;
try {
DecryptorHome home = (DecryptorHome)JNDIHelper.getHome(
"com.beasys.commerce.ebusiness.security.Decryptor");
Decryptor decryptor = home.create();
creditCardNumber = decryptor.decrypt(card.getNumber());
} catch (Exception e) {
// Add the appropriate exception handling logic.
// This will depend on your payment service requirements.
}
//
// Invoke the credit card service authorization method using
// the order, credit card, and authorization amount.
//
// Throw an appropriate exception for authorization error
// condition(s).
//
Logger.getInstance().info("In MyPaymentAuthorizationPC:calling payment service.");
< Insert credit card service authorization code here >
//
// Immediately nullify the decrypted number.
//
creditCardNumber = null;
//
// If the authorization was successful, create a
// PaymentTransaction entity EJB for the transaction.
// Use the transaction ID returned by the credit card
// service as the primary key.
PaymentTransaction paymentTransaction = null;
try {
PaymentTransactionHome home = (PaymentTransactionHome)JNDIHelper.
getHome("com.beasys.commerce.ebusiness.payment.PaymentTransaction");
PaymentTransactionPk pk = new
PaymentTransactionPk(Long.toString(myTransactionID));
paymentTransaction = home.create(pk);
} catch (Exception e){
// Add the appropriate exception handling logic.
// This will depend on your payment service requirements.
}
//
// Set the PaymentTransaction date, credit card, and amount.
//
paymentTransaction.setTransactionDate(new Date(System.
currentTimeMillis()));
paymentTransaction.setCreditCard(card);
paymentTransaction.setTransactionAmount(amount);
//
// Add a TransactionEntry to the PaymentTransaction and
// mark the PaymentTransaction with the appropriate status.
// In this example, we assume that the payment transaction
As shown in Listing 6-9, the credit card, authorization amount, and order is first extracted from the supplied PipelineSession. Next, the Decryptor security service is used to decrypt the encrypted credit card number. After obtaining all the information necessary to authorize a payment, you must next call your Payment Service provider authorization routine using any of the collected data necessary. Finally, after completing the authorization, a payment transaction is recorded using the PaymentTransaction entity EJB. The PaymentTransaction entity EJB records the date, amount, credit card, and status (in this case, authorized) associated with the payment. It also keeps an audit trail of payment transaction modifications via a collection of TransactionEntry objects. Each TransactionEntry object stores a date, identifier, and amount.
- Compile the new Pipeline component. Make sure to include any Payment Service provider classes that the new Pipeline component uses in your classpath.
- Configure the pipeline.properties file to use your new Pipeline component. To do this, locate the following line in the pipeline.properties file:
AuthorizePaymentPC.className=com.beasys.commerce.ebusiness.
payment.pipeline.PaymentAuthorizationTerminalPCThen, modify the AuthorizePaymentPC Pipeline component definition to use your new Pipeline component as follows:
AuthorizePaymentPC.className=MyPaymentAuthorizationPC
- Restart the WebLogic Commerce Server. Make sure to include the new Pipeline component as well as any Payment Service provider classes used by the Pipeline component in your classpath.
You should now be able to authorize payments using the new Payment Service PipelineComponent.
Note: If you replace the existing Payment Authorization Pipeline component, you must administer payments using tools supplied by your Payment Service provider and NOT the administrative Payment Management pages. The administrative Payment Management pages should only be used for CyberCash-based payment administration. For more information about the administrative Payment Management pages, see Using the Order and Payment Management Pages.
Credit Card Security Service
All credit card information your customers provide is considered sensitive and is encrypted for security purposes. This information is decrypted only when absolutely necessary during specific payment processing activities (authorization). On the order confirmation JSP template (confirmorder.jsp), for example, only the last 4 digits of a customer's credit card are displayed.
Encryption/Decryption Implementation
The BEA WebLogic Commerce Server product's encryption mechanism is based upon RSA's public key infrastructure. A public key is used to encrypt a customer's credit card information, while a private key is used to decrypt it when required.
The public key is stored in the database for use by the EncryptCreditCardPC Pipeline component, while the private key is itself encrypted using a password you supply, and stored in the database.
When invoked from the Webflow, the EncryptCreditCardPC Pipeline component reads the customer-provided credit card information from the Pipeline session, encrypts it using the public key, and then places it back into the Pipeline session. This encrypted data is subsequently written to the database. Decryption is accomplished using a back-end component and the private key. Again, decryption is initiated only in stages of the ordering process where this data is absolutely necessary.
For more technical information about the Credit Card Security Service, please contact your BEA representative.
Customizable Security Settings
Although the BEA WebLogic Commerce Server product specifies default settings for the Credit Card Security Service, you can customize them. The security settings reside in the weblogiccommerce.properties file (located in the WL_COMMERCE_HOME directory, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server). These security settings are shown in Listing 6-10.
Listing 6-10 Security Settings in weblogiccommerce.properties
###################################################
# Properties required for the Security Service
###################################################
# Security services are turned on by setting this property to true.
# Commenting out the property or setting it to false will disable
# security.
is.encryption.enabled=true
# The name of the security table and column names for the public
# and private keys can be specified using the properties below.
security.table.name=WLCS_SECURITY
security.backup.table=WLCS_SECURITY_BACKUP
public.key.column.name=PUBLIC_KEY
private.key.column.name=PRIVATE_KEY
# The key bit size desired
# Key bit length and length of data that can be encrypted are related # as follows:
# KEY BIT LENGTH(bits) DATA LENGTH (bytes)
# 512 53
# 1024 117
# 2048 (MAX LENGTH) 245
key.bit.size=1024
# WARNING! Remember that setting this property will start up the
# server without prompting for a password. The password will be read # from this property which makes the encryption vulnerable to an
# inside attack.
private.key.password=WLCS
First, the is.encryption.enabled property enables encryption mechanisms. Please note that a value of false (or no value at all) will disable encryption mechanisms. BEA has assigned this property a default value of true.
Next is a series of properties that allow you to specify the names of the security tables (primary and backup) and the columns in which the public and private keys will be stored. BEA has assigned default values to these properties, but you can modify them based on your database.
Following the properties related to the database, the key.bit.size property allows you to specify the encryption key length. BEA has assigned this property a default value of 1024, but you can adjust this value. Table 6-10 illustrates the possible key bit values.
|
Length (Bits) |
Data Length (Bytes) |
|---|---|
|
512 |
53 |
|
1024 |
117 |
|
2048 |
245 |
Lastly, the private.key.password property allows you to specify, in the weblogiccommerce.properties file, the password used to encrypt the private key. Please note that BEA does not recommend use of this property. Rather, the private key should be supplied by an administrator during server startup. For more information about supplying the private key, see Methods for Supplying the Private Key Encryption Password.
Note: If not used, the private.key.password property should be commented out with a # symbol. BEA has assigned this property a default value of WLCS, but this is for demonstration purposes only.
Methods for Supplying the Private Key Encryption Password
As previously mentioned, the private key used to encrypt customer credit cards is itself encrypted with a password before being stored in the database. There are three methods by which you can supply this password:
Specifying the Password in weblogiccommerce.properties (Default)
The first method for specifying the private key encryption password is to specify the password as a value for a property in the weblogiccommerce.properties file.
Note: BEA does not recommend this method because by providing the password in a simple text file, you leave yourself vulnerable to security attacks. Anyone who gains access to this file can read the password you use to encrypt the private key, and thus gain access to it.
To use this method, follow these steps:
Listing 6-11 Encryption Section of weblogic.properties file
################################################
# ENCRYPTION SERVICES
# -------------------------------------
#
# Specify a method for supplying the password for decrypting
# private keys. This may be one of two mechanisms:
#
# (1) Servlet-based password entry
# (2) Property specification by way of a startup class
#
# NOTE: Make sure that the property is.encryption.enabled
# in weblogiccommerce.properties is commented out or set to false
# if neither the servlet nor the startup class is being used.
#
#
# Startup class password entry
#
# Reads a private key encryption password from the
# weblogiccommerce.properties file if the private.key.password
# property has a non-empty value. If keys are already present in the
# database and the password used to generate them differs from the
# one specified by this property, the user must enter the password
# on the console.
#
# OR
#
# Prompts the user to enter a password on the console at server
# startup. If there are no public and private keys in the database
# the user is prompted to specify that new keys be created. If new
# key generation is not desired, encryption should be turned off
# by way of the is.encryption.enabled property in the
# weblogiccommerce.properties file. If the user knows that keys are
# already generated, he/she should stop the server and check the
# security database tables and properties in the
# weblogiccommerce.properties file.
weblogic.system.startupClass.KeyBootstrap=com.beasys.commerce.
ebusiness.security.KeyBootstrap
Specifying the Password at Server Startup Using the Console
The second method for specifying the private key encryption password is for an administrator to specify the password at server startup using the server console.
To use this method, follow these steps:
Specifying the Password After Server Startup Using a Secure Web Form
The third method for specifying the private key encryption password allows an administrator to enter the password on a secure Web form, so the password is stored in memory on your system instead of in a text file.
To use this method, follow these steps:
Figure 6-5 security_getPassword.html
On submission, this page will invoke the EncryptionServlet and KeyGeneratorServlet registered in the web.xml file (located in the WL_COMMERCE_HOME/server/webapps/admin/Web-inf directory, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server).
Important Notes About Supplying Your Password
You must supply the password for all nodes in a cluster. Should one node in the cluster fail, other machines that know the private key encryption password can be used for failover.
The first time you enter the password, you will be asked to confirm whether or not you want to generate new keys. If this is indeed the first time you are entering the password, you do want to generate new keys. However, be sure to select a password that is memorable. All credit cards accepted by your site will be encrypted using this password, and cannot be decrypted if you forget your password.
If you are asked to confirm whether or not you want to generate new keys and you are using the same password, then the keys cannot be found in the database. If no data was encrypted using the old keys, you can regenerate the keys. However, if data has already been encrypted using the old keys, this data will be lost because it cannot be read using the new keys. If you have data encrypted with the old keys, you should stop the server, check the database, and verify the properties in the weblogiccommerce.properties file to ensure that the system is set up properly.
During server startup, any orders placed before the password is entered will be persisted with a payment transaction in the RETRY state. After supplying the password, administrators should use the payment management administration tool to reauthorize the transaction. For more information about using the payment management administration tool, see Using the Order and Payment Management Pages.
What if I Want to Change My Password?
Because all the credit cards that have been encrypted use the private key encryption password, it is not recommended that you change this password. However, there may be the rare occasion (for example, if the password has been compromised) when you need to change the password. Changing the password means changing the public and private key pair. Therefore, you must follow this process when changing the password:
Note: Changing the password is especially difficult if you have a lot of encrypted data. Again, this process is not recommended and should not be done unless absolutely required.
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|