Adding payment information to shopping carts involves the following subprocesses:
Creating a list of payment groups for potential use in the current order. The user can select from among these payment groups when checking out the order. See Creating Potential Payment Groups.
Specifying the payment groups to use with current order. See Adding Payment Groups to an Order.
Creating Potential Payment Groups
You can create a list of payment groups for potential use in an Order
in one of two ways:
from information gathered from the user via forms
from information stored in the user’s profile
To create payment groups from information obtained from the user via forms, use CreateCreditCardFormHandler
and CreateInvoiceRequestFormHandler
. (Note: The CreateInvoiceRequestFormHandler
is provided with ATG Business Commerce only.) These form handlers create, respectively, CreditCard
and InvoiceRequest
payment groups. Additionally, if the addToContainer
property of the form handlers is true (which it is by default), they add the new payment group to the PaymentGroupMapContainer
and make it the default payment group in the container. The PaymentGroupMapContainer
stores the payment groups available for use in the current order. Once the payment group is added to the PaymentGroupMapContainer
, the user can use it when checking out the current order. See Adding Payment Groups to an Order.
The following JSP code example from credit_card.jsp
in the commerce sample catalog illustrates the use of CreateCreditCardFormHandler
.
<dsp:importbean bean="/atg/commerce/order/purchase/CreateCreditCardFormHandler"/> <dsp:importbean bean="/atg/userprofiling/Profile"/> <hr><p>Enter new CreditCard information <dsp:form action="credit_card.jsp" method="post"> <br>CreditCard NickName:<dsp:input bean="CreateCreditCardFormHandler.creditCardName" size="30" type="text" value=""/> <br>CreditCardNumber:<dsp:input bean="CreateCreditCardFormHandler.creditCard.CreditCardNumber" maxsize="20" size="20" type="text" value="4111111111111111"/> <br>CreditCardType: <dsp:select bean="CreateCreditCardFormHandler.creditCard.creditCardType" required="<%=true%>"> <dsp:option value="Visa"/>Visa <dsp:option value="MasterCard"/>Master Card <dsp:option value="American Express"/>American Express </dsp:select> <br>ExpirationMonth: <dsp:select bean="CreateCreditCardFormHandler.creditCard.ExpirationMonth"> <dsp:option value="1"/>January <dsp:option value="2"/>February <dsp:option value="3"/>March <dsp:option value="4"/>April <dsp:option value="5"/>May <dsp:option value="6"/>June <dsp:option value="7"/>July <dsp:option value="8"/>August <dsp:option value="9"/>September <dsp:option value="10"/>October <dsp:option value="11"/>November <dsp:option value="12"/>December </dsp:select> <br>expirationYear:Year: <dsp:select bean="CreateCreditCardFormHandler.creditCard.expirationYear"> <dsp:option value="2002"/>2002 <dsp:option value="2003"/>2003 <dsp:option value="2004"/>2004 <dsp:option value="2005"/>2005 <dsp:option value="2006"/>2006 <dsp:option value="2007"/>2007 <dsp:option value="2008"/>2008 <dsp:option value="2009"/>2009 <dsp:option value="2010"/>2010 </dsp:select> <br>FirstName:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.firstName" beanvalue="Profile.firstName" size="30" type="text"/> <br>MiddleName:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.middleName" beanvalue="Profile.middleName" size="30" type="text"/> <br>LastName:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.lastName" beanvalue="Profile.lastName" size="30" type="text"/> <br>EmailAddress:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.email" beanvalue="Profile.email" size="30" type="text"/> <br>PhoneNumber:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.phoneNumber" beanvalue="Profile.daytimeTelephoneNumber" size="30" type="text"/> <br>Address:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.address1" beanvalue="Profile.defaultBillingAddress.address1" size="30" type="text"/> <br>Address (line 2):<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.address2" beanvalue="Profile.defaultBillingAddress.address2" size="30" type="text"/> <br>City:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.city" beanvalue="Profile.defaultBillingAddress.city" size="30" type="text"/> <br>State:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.state" beanvalue="Profile.defaultBillingAddress.state" size="30" type="text"/> <br>PostalCode:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.postalCode" beanvalue="Profile.defaultBillingAddress.postalCode" size="30" type="text"/> <br>Country:<dsp:input bean="CreateCreditCardFormHandler.creditCard.billingAddress.country" beanvalue="Profile.defaultBillingAddress.country" size="30" type="text"/> <dsp:input bean="CreateCreditCardFormHandler.copyToProfile" type="hidden" value="false"/> <dsp:input bean="CreateCreditCardFormHandler.newCreditCardSuccessURL" type="hidden" value="billing.jsp?init=false"/> <dsp:input bean="CreateCreditCardFormHandler.newCreditCardErrorURL" type="hidden" value="credit_card.jsp"/> <dsp:input bean="CreateCreditCardFormHandler.newCreditCard" type="submit" value="Enter Credit Card"/> </dsp:form>
In the commerce sample catalog, credit_card.jsp
is embedded into billing.jsp
, which itself manages the payment information for the user’s current order.
You use CreateInvoiceRequestFormHandler
in the same way that you use CreateCreditCardFormHandler
, although note that by default the CreateInvoiceRequestFormHandler
requires that a poNumber
is specified for an invoice payment group. For more information on both CreateCreditCardFormHandler
and CreateInvoiceRequestFormHandler
, see the Checking Out Orders section of the Configuring Purchase Process Services chapter in the ATG Commerce Programming Guide.
In contrast to creating payment groups from information gathered from the user via forms, you can also create payment groups from information that is stored in the user’s profile using the PaymentGroupDroplet
servlet bean. PaymentGroupDroplet
uses the information obtained from the current user’s profile to initialize payment groups and add them to the PaymentGroupMapContainer
. The input parameters passed into PaymentGroupDroplet
determine what types of PaymentGroups
are created (such as, credit card, store credit, and/or gift certificate), and whether the PaymentGroupMapContainer
is cleared before they are created. Once the payment groups are added to the PaymentGroupMapContainer
, the user can select from among them when checking out the current Order
. See Adding Payment Groups to an Order.
Additionally, PaymentGroupDroplet
uses the information in the user’s current Order
to initialize CommerceIdentifierPaymentInfo
objects for each CommerceItem
in the Order
and add them to the CommerceIdentifierPaymentInfoContainer
. A CommerceIdentifierPaymentInfo
object is a helper object that represents the relationship between a CommerceItem
in the Order
and its payment information; it contains properties that allow the cost of a given item or even a single item, as well as the order’s shipping costs and tax, to be spread across multiple payment groups. The CommerceIdentifierPaymentInfoContainer
stores the CommerceIdentifierPaymentInfo
objects created for use in the current Order
.
The input parameters passed into PaymentGroupDroplet
determine whether the CommerceIdentifierPaymentInfo
objects are created and whether the CommerceIdentifierPaymentInfoContainer
is cleared before they are created. By default, PaymentGroupDroplet
associates each CommerceIdentifierPaymentInfo
object with the default payment group in the PaymentGroupMapContainer
.
When you use PaymentGroupDroplet
, you should consider the following:
Whether the user is paying for the total cost of the
Order
with one or more payment groups or the component costs of theOrder
(commerce item costs, shipping costs, and tax) with one or more payment groups.The types of payment groups the user can use to pay for the
Order
. By default, ATG Commerce supports the following types ofPaymentGroups
:giftCertificate
,storeCredit
, andcreditCard
. ATG Business Commerce also supportsinvoiceRequest PaymentGroups
.
These factors determine what kind of PaymentGroup
objects you use PaymentGroupDroplet
to initialize for potential use in the user’s order.
PaymentGroupDroplet
takes the following input parameters:
Parameter | Description |
---|---|
| Boolean. When set to true, |
| Boolean. When set to true, |
| Boolean. When set to true, |
| Boolean. When set to true, A |
| Boolean. When set to true, An |
| Boolean. When set to true, the |
| Boolean. When set to true, A |
| Boolean. When set to true, A |
| The user’s |
| A comma-separated list of |
PaymentGroupDroplet
sets the following output parameters:
Parameter | Description |
---|---|
| The |
| The |
| The |
PaymentGroupDroplet
renders one open parameter named output
.
The following code example illustrates the use of PaymentGroupDroplet
. The example creates CreditCard
, StoreCredit
, and GiftCertificate
PaymentGroup
objects based on their availability for the current user. Additionally, it creates CommerceItemPaymentInfo
objects, ShippingGroupPaymentInfo
objects, and a TaxPaymentInfo
object. The example enables the user to pay for the CommerceIdentifiers
in the Order
at the line item level with any of the available PaymentGroup
objects.
<dsp:droplet name="PaymentGroupDroplet"> <dsp:param value="true" name="clear"/> <dsp:param value="giftCertificates, storeCredit, creditCard" name="paymentGroupTypes"/> <dsp:param value="true" name="initPaymentGroups"/> <dsp:param value="true" name="initItemPayment"/> <dsp:param value="true" name="initTaxPayment"/> <dsp:param value="true" name="initShippingPayment"/> <dsp:oparam name="output">Manipulation of objects here... </output> </dsp:droplet>
You can refer to billing.jsp
and invoice_request.jsp
in the commerce sample catalog for additional JSP code examples that illustrate the use of PaymentGroupDroplet
.
Adding Payment Groups to an Order
Use PaymentGroupFormHandler
to add payment groups to an Order
once the payment information for the Order
has been gathered from the following two processes (described in detail in the previous section):
The payment groups for potential use in the
Order
have been created viaCreateCreditCardFormHandler
,CreateInvoiceRequestFormHandler
, and/orPaymentGroupDroplet
. The payment groups have been added to thePaymentGroupMapContainer
.The
CommerceIdentifierPaymentInfo
objects for theCommerceIdentifiers
in theOrder
have been created viaPaymentGroupDroplet
. TheCommerceIdentifierPaymentInfo
objects have been added to theCommerceIdentifierPaymentInfoContainer
.
As an example, consider the following code segment from complex_billing.jsp
in the commerce sample catalog. This page permits the user to divide the total cost of the Order
across multiple CreditCard
payment groups.
Note: In the code segment below, you can assume that each referenced component has been imported into the page via a dsp:importbean
tag. See the actual JSP for these import statements.
<dsp:droplet name="PaymentGroupDroplet"> <dsp:param name="initOrderPayment" param="init"/> <dsp:param name="clearPaymentInfos" param="init"/> <dsp:oparam name="output"> <dsp:setvalue bean="PaymentGroupFormHandler.listId" paramvalue="order.id"/> <!-- begin output --> <table border=0 cellpadding=0 cellspacing=0 width=800> <tr> </tr> <tr> <td width=55></td> <td valign="top" width=745> <table border=0 cellpadding=4 width=80%> <tr><td></td></tr> <tr> <td colspan=2><span class="big">Billing</span></td> </tr> <tr><td></td></tr> <tr> <td colspan=2><b>Split payment by order amount</b><br> Order total: <dsp:valueof converter="currency" param="order.priceInfo.total"/><br> <span class=help>Enter the amount you wish to move to another payment method and select the new method. The remaining amount will stay on the default payment method. <P>You must save changes before continuing.</span></td> </tr> <tr valign=top> <td> <table border=0 cellpadding=4 cellspacing=1> <tr valign=top> <td colspan=9 align=right> </td> </tr> <tr valign=bottom bgcolor="#666666"> <td colspan=2><span class=smallbw>Amount</span></td> <td colspan=2><span class=smallbw>Amt to move </span></td> <td colspan=2><span class=smallbw>Payment method</span></td> <td colspan=3><span class=smallbw>Save changes</span></td> </tr> <dsp:droplet name="ForEach"> <dsp:param bean="PaymentGroupFormHandler.currentList" name="array"/> <dsp:oparam name="output"> <!-- begin order line item --> <dsp:form action="complex_billing.jsp" method="post"> <tr valign=top> <td><dsp:valueof converter="currency" param="element.amount"/></td> <td> </td> <td> $<dsp:input bean="PaymentGroupFormHandler.currentList[param:index].splitAmount" size="6" value="0.00" type="text"/></td> <td> </td> <td> <dsp:select bean="PaymentGroupFormHandler.currentList[param:index].splitPaymentMe thod"> <dsp:droplet name="ForEach"> <dsp:param name="array" param="paymentGroups"/> <dsp:oparam name="output"> <dsp:droplet name="Switch"> <dsp:param name="value" param="key"/> <dsp:getvalueof id="nameval3" param="...element.paymentMethod" idtype="java.lang.String"> <dsp:oparam name="<%=nameval3%>"> <dsp:getvalueof id="option264" param="key" idtype="java.lang.String"> <dsp:option selected="<%=true%>" value="<%=option264%>"/> </dsp:getvalueof><dsp:valueof param="key"/> </dsp:oparam> </dsp:getvalueof> <dsp:oparam name="default"> <dsp:getvalueof id="option272" param="key" idtype="java.lang.String"> <dsp:option selected="<%=false%>" value="<%=option272%>"/> </dsp:getvalueof><dsp:valueof param="key"/> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet> </dsp:select> </td> <td> </td> <td> </td> <td> </td> <td> <dsp:input bean="PaymentGroupFormHandler.ListId" paramvalue="order.id" priority="<%=(int)9%>" type="hidden"/> <dsp:input bean="PaymentGroupFormHandler.splitPaymentInfosSuccessURL" type="hidden" value="complex_billing.jsp?init=false"/> <dsp:input bean="PaymentGroupFormHandler.splitPaymentInfos" type="submit" value=" Save "/> </td> </tr> </dsp:form> <!-- end order line item --> </dsp:oparam> </dsp:droplet> <td colspan=9> <%-- table with one row with one cell --%> <table border=0 cellpadding=0 cellspacing=0 width=100%> <tr bgcolor="#666666"> <td></td> </tr> </table> </td> </tr> </table> </td> </tr> <tr> <td><br> <dsp:form action="complex_billing.jsp" method="post"> <dsp:input bean="PaymentGroupFormHandler.applyPaymentGroupsSuccessURL" type="hidden" value="order_confirmation.jsp"/> <dsp:input bean="PaymentGroupFormHandler.applyPaymentGroups" type="submit" value="Continue"/> </dsp:form> </td> </tr> </table> </td> </tr> </table> </div> <!-- end output --> </dsp:oparam> </dsp:droplet> <!-- end PaymentGroupDroplet -->
Note the following sections of complex_billing.jsp
:
When the page is rendered,
PaymentGroupDroplet
is used to initialize anOrderPaymentInfo
object for the user’s current order and add it to theCommerceIdentifierPaymentInfoContainer
. Recall from the previous section that by defaultPaymentGroupDroplet
associates eachCommerceIdentifierPaymentInfo
object with the default payment group in thePaymentGroupMapContainer
. (Note that the availableCreditCard
payment groups have been initialized and added to thePaymentGroupMapContainer
on a previous page,billing.jsp
.)The
PaymentGroupFormHandler.listId
property is set to the ID of theOrder
object set in theorder
output parameter ofPaymentGroupDroplet
. The order’s ID is the key to itsList
ofCommerceIdentifierPaymentInfo
objects, which are now exposed via thePaymentGroupFormHandler.currentList
property. (A hidden input tag farther down the page also sets this property on a subsequent request.)The remainder of the code renders an interface that enables the user to assign specific amounts of the order’s total cost to different payment groups. This is achieved through the use of nested
ForEach
servlet beans:The outer
ForEach
servlet bean receives as an input parameter the array ofCommerceIdentifierPaymentInfo
objects for the currentOrder
. It renders itsoutput
oparam
once for eachCommerceIdentifierPaymentInfo
object in the array. Essentially, the output rendered is a form that displays the following: the amount associated with the currentCommerceIdentifierPaymentInfo
object, a drop-down list with which to change the payment group for a specified amount in theCommerceIdentifierPaymentInfo
object, a textbox with which to specify the amount in theCommerceIdentifierPaymentInfo
to associate with the selected payment group, and a Save submit button with which to make these new associations.The payment group drop-down list is populated with the payment groups in the
PaymentGroupMapContainer
. These are exposed by thePaymentGroupDroplet
through apaymentGroups
convenience parameter, and a second nestedForEach
servlet bean is used to iterate over the payment groups and populate the drop-down list.Note that the payment group drop-down list is associated with the
splitPaymentMethod
property of the currentCommerceIdentifierPaymentInfo
object. Similarly, the amount textbox is associated with thesplitAmount
property of the currentCommerceIdentifierPaymentInfo
object.Finally, note that the Save submit button invokes the
handleSplitPaymentInfos
method ofPaymentGroupFormHandler
. ThehandleSplitPaymentInfos
method uses the values in theamount
andsplitAmount
properties of theCommercIdentifierPaymentInfo
object to determine if the object should be split into two objects. If that is necessary, it then uses these properties and the payment group specified in thesplitPaymentMethod
property to construct a secondCommerceIdentifierPaymentInfo
object. The method then sets the properties of both the old and new objects accordingly and adds the new object to theCommerceIdentifierPaymentInfoContainer
. Once the form is processed, the page is rendered again and reflects the changes the user has made.
The Continue submit button at the bottom of the page enables the user to apply the current payment associations to the order and proceed to order confirmation. The submit button invokes the
handleApplyPaymentGroups
method ofPaymentGroupFormHandler
, which adds the payment groups that the user has selected to theOrder
. It does this by iterating over theCommerceIdentifierPaymentInfo
objects in theCommerceIdentifierPaymentInfoContainer
. For eachCommerceIdentifierPaymentInfo
object in the container, the associated payment group is retrieved from thePaymentGroupMapContainer
and added to theOrder
, and the appropriate amount of the associatedCommerceIdentifier
is added to thatPaymentGroup
.
Note: For detailed information on all the handle methods of PaymentGroupFormHandler
, see the Preparing a Complex Order for Checkout section of the Configuring Purchase Process Services chapter in the ATG Commerce Programming Guide. For more information on adding costs to payment groups, see the Assigning Costs to Payment Groups section of the Working With Purchase Process Objects chapter in the ATG Commerce Programming Guide.
If you’ve installed ATG Business Commerce, you can refer to checkout/payment_methods.jsp
, checkout/SplitPaymentOrderDetails.jsp
, and checkout/SplitPaymentDetails.jsp
in the Motorprise reference application for additional JSP code examples that illustrate the use of PaymentGroupFormHandler
. In particular, note that /checkout/SplitPaymentDetails.jsp
illustrates how to enable the user to split the component costs or “line items” in the order (that is, the item costs, shipping costs, and tax) across multiple payment groups. You can access these Motorprise pages at <ATG2007.3dir>\MotorpriseJSP\j2ee-apps\motorprise\web-app\en\checkout\
. You can also open these pages in the ACC’s Document Editor via the Pages and Components>J2EE Pages task area. For more details, see the Payment Information section of the Processing Orders chapter in the ATG Business Commerce Reference Application Guide.