Oracle ATG Web Commerce - Adding Payment Information to Shopping Carts

Adding Payment Information to Shopping Carts

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. 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 the Order. A CommerceIdentifierPaymentInfo object is a helper object that represents the relationship between an Order and its components (commerce items, shipping, and taxes) and payment information; it contains properties that allow the cost of a given 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. CommerceIdentifierPaymentInfo objects are further subclassed into the following types:

OrderPaymentInfo objects store payment information for the entire order, including all commerce items, shipping, and taxes.
ItemPaymentInfo objects store payment information for individual items.
ShippingPaymentInfo objects store payment information for shipping costs.
TaxPaymentInfo objects store payment information for taxes.

The input parameters you provide to PaymentGroupDroplet determine which of the four CommerceIdentifierPaymentInfo object types are initialized for the Order. In general, you will opt to either initialize an OrderPaymentInfo object for the entire order, or a combination of ItemPaymentInfo, ShippingPaymentInfo, and TaxPaymentInfo objects that account for all of the order’s components.

Once a set of CommerceIdentifierPaymentInfo objects is initialized for an order, you can present your customer with a form that allows the customer to:

Specify a different PaymentGroup for each CommerceIdentifierPaymentInfo object.
Update the SplitPaymentMethod, SplitAmount, and SplitQuantity property values of the CommerceIdentifierPaymentInfo objects and submit the changes by calling the PaymentGroupFormHandler.handleSplitPaymentInfos method. In this way, CommerceIdentifier objects can be associated with additional PaymentGroups other than those provided by the PaymentGroupDroplet initialization. The changes are stored in additional CommerceIdentifierPaymentInfo objects.

The illustration below shows a sample user interface that allows the user to split payment amounts among PaymentGroups.

When the customer is satisfied with the PaymentGroup to CommerceIdentifier associations, he or she clicks a button to proceed with the purchase process. Behind the scenes, this button invokes the PaymentGroupFormHandler.handleApplyPaymentGroups method. This method collects the information in the CommerceIdentifierPaymentInfo helper objects and adds corresponding PaymentGroup relationship objects to the order. A PaymentGroup relationship object creates an association between a CommerceIdentifier and a PaymentGroup and represents the amount of the cost in the CommerceIdentifier that will be paid for using the information in the PaymentGroup. PaymentGroup relationship objects can be of several types:

A PaymentGroupOrderRelationship represents a relationship between an Order and a PaymentGroup. This relationship object also stores tax payment information.
A PaymentGroupCommerceItemRelationship represents a relationship between a CommerceItem and a PaymentGroup.
A PaymentGroupShippingGroupRelationship represents a relationship between a ShippingGroup and a PaymentGroup.

While they are closely related, CommerceIdentifierPaymentInfo and PaymentGroup relationship objects serve slightly different purposes. A CommerceIdentifierPaymentInfo object is external to the order and provides a means for defining commerce identifier-to-payment group relationships. These changes do not affect the actual order until they are applied, allowing the order to remain in a stable state until the PaymentGroupFormHandler.handleApplyPaymentGroups method is invoked. Once the information in the CommerceIdentifierPaymentInfo objects is applied to the order, the relationships are stored in the order as PaymentGroup relationship objects.

Note: For more detailed information on PaymentGroup relationship objects, see the Using Relationship Objects section in the Working with Purchase Process Objects chapter of the ATG Commerce Programming Guide.

The input parameters passed into PaymentGroupDroplet determine how the droplet creates and initializes CommerceIdentifierPaymentInfo objects for the order and whether the CommerceIdentifierPaymentInfoContainer is cleared before they are created. Parameters control CommerceIdentifierPaymentInfo object creation: initOrderPayment, initItemPayment, initShippingPayment, initTaxPayment, and initBasedOnOrder. These parameters, along with the other PaymentGroupDroplet input parameters, are described in the table below.

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 the Order (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, Oracle ATG Web Commerce supports the following types of PaymentGroups: giftCertificate, storeCredit, creditCard, invoiceRequest, and PaymentGroups.

These factors determine what kind of PaymentGroup objects you use PaymentGroupDroplet to initialize for potential use in the order.

PaymentGroupDroplet takes the following input parameters:

Parameter	Description
`clear`	Boolean. When set to `True`, `PaymentGroupDroplet` clears both the user’s `CommerceIdentifierPaymentInfoContainer` and `PaymentGroupMapContainer`.
`cleaPaymentGroups`	Boolean. When set to `True`, `PaymentGroupDroplet` clears the user’s `PaymentGroupMapContainer`.
`clearPaymentInfos`	Boolean. When set to `True`, `PaymentGroupDroplet` clears the user’s `CommerceIdentifierPaymentInfoContainer`. This should be done at least once per new order; the default value is false.
`createAllPaymentInfos`	Boolean. When set to `True`, the `PaymentGroupDroplet` creates an `OrderPaymentInfo` for all possible payment types stored in the user’s profile (credit cards, store credit, gift certificate, or invoice request). Initially, the entire order’s cost is assigned to the `OrderPaymentInfo` that is associated with the default `PaymentGroup` and all other `OrderPaymentInfo` objects are set to 0. This option supports a different type of user interface than that which is described in the sections above. Use `createAllPaymentInfos` to initialize the objects needed to support a user interface where the user manually specifies the amount of the order to be paid by each payment type in her profile. See Using createAllPaymentInfos for more information. This option is `False` by default.
`initBasedOnOrder`	Boolean. When set to `True`, `PaymentGroupDroplet` creates a `CommerceIdentifierPaymentInfo` object for each `PaymentGroup` relationship object in the `Order`. This option is provided for the scenario where a customer has already gone part way through the checkout process and the order already contains some `PaymentGroup` relationship objects. The types of `CommerceIdentifierPaymentInfo` objects that are created correspond to the `PaymentGroup` relationship types. For example, if a `PaymentGroupCommerceItemRelationship` exists in the `Order`, `PaymentGroupDroplet` creates a corresponding `CommerceItemPaymentInfo` object and adds it to the `CommerceIdentifierPaymentInfoContainer`. Each `CommerceIdentifierPaymentInfo` object is initialized with the `PaymentGroup` that exists in its corresponding `PaymentGroup` relationship object. Set to `False` by default.
`initItemPayment`	Boolean. When set to `True`, `PaymentGroupDroplet` creates a `CommerceItemPaymentInfo` object for each `CommerceItem` in the order and adds them to the `CommerceIdentifierPaymentInfoContainer`. If a user has a default `PaymentGroup` in his or her profile, the `CommerceItemPaymentInfo` object is initialized with that `PaymentGroup`. Set to `False` by default. Note: A `CommerceItemPaymentInfo` object is a `CommerceIdentifierPaymentInfo` object whose `CommerceIdentifier` is a `CommerceItem`; it is used for `CommerceItem` payment information.
`initOrderPayment`	Boolean. When set to `True`, `PaymentGroupDroplet` creates an `OrderPaymentInfo` object and adds it to the `CommerceIdentifierPaymentInfoContainer`. If a user has a default `PaymentGroup` in his or her profile, the `OrderPaymentInfo` object is initialized with that `PaymentGroup`. Set to `True` by default. Note: An `OrderPaymentInfo` object is a `CommerceIdentifierPaymentInfo` object whose `CommerceIdentifier` is an `Order`; it is used for `Order` payment information.
`initPaymentGroups`	Boolean. When set to `True`, the `PaymentGroup` types supplied in the `paymentGroupTypes` input parameter are initialized.
`initShippingPayment`	Boolean. When set to `True`, `PaymentGroupDroplet` creates a `ShippingGroupPaymentInfo` object for each `ShippingGroup` in the order and adds them to the `CommerceIdentifierPaymentInfoContainer`. If a user has a default `PaymentGroup` in his or her profile, the `ShippingGroupPaymentInfo` object is initialized with that `PaymentGroup`. Set to `False` by default. Note: A `ShippingGroupPaymentInfo` object is a `CommerceIdentifierPaymentInfo` object whose `CommerceIdentifier` is a `ShippingGroup`; it is used for `ShippingGroup` payment information.
`initTaxPayment`	Boolean. When set to `True`, `PaymentGroupDroplet` creates a `TaxPaymentInfo` object and adds it to the `CommerceIdentifierPaymentInfoContainer`. A `TaxPaymentInfo` object is a `CommerceIdentifierPaymentInfo` object whose `CommerceIdentifier` is an `Order`; it is used for tax payment information.
`order`	The user’s `Order`. You can use this parameter to override the default setting for `PaymentGroupDroplet.order`.
`paymentGroupTypes`	A comma-separated list of `PaymentGroup` types (such as “creditCard,” “storeCredit,” “giftCertificate”) that is used to determine which `PaymentGroupInitializer` components are executed.

PaymentGroupDroplet sets the following output parameters:

Parameter	Description
`cipiMap`	The `Map` referenced by the `CommerceIdentifierPaymentInfoContainer`.
`order`	The `Order` object that represents the user’s order.
`paymentGroups`	The `Map` referenced by the `PaymentGroupMapContainer`.

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.

Using createAllPaymentInfos

You can use the createAllPaymentInfos input parameter to initialize the objects needed to support a user interface where the user manually specifies the amount of the order to be paid by each payment type in her profile, for example:

When the createAllPaymentInfos parameter is set to True, the PaymentGroupDroplet creates an OrderPaymentInfo for all possible payment types stored in the user’s profile (credit cards, store credit, gift certificate, or invoice request). Initially, the entire order’s cost is assigned to the OrderPaymentInfo that is associated with the default PaymentGroup and all other OrderPaymentInfo objects are set to 0. For example, consider the following scenario:

The total cost of the order is $100.
The user’s profile has two credit cards stored in it, Credit Card A and Credit Card B as well as a store credit.
Credit Card A is the default payment method for the user.

In this scenario, PaymentGroupDroplet creates three OrderPaymentInfo objects, one for each credit card and another for the store credit. The amount property for the OrderPaymentInfo associated with Credit Card A is set to 100. The amount properties for the OrderPaymentInfo objects associated with Credit Card B and the store credit are set to 0.

In the application, the user is presented with a list of payment options generated by iterating over the list of OrderPaymentInfo objects. The user provides the amount to be paid by each payment option directly in the form, effectively setting the amount property for the OrderPaymentInfo object associated with each PaymentGroup. If the user adds additional PaymentGroups during the checkout process, you should call the PaymentGroupDroplet again to create OrderPaymentInfo objects for the newly added PaymentGroups.

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 via CreateCreditCardFormHandler, CreateInvoiceRequestFormHandler, and/or PaymentGroupDroplet. The payment groups have been added to the PaymentGroupMapContainer.
The CommerceIdentifierPaymentInfo objects for the CommerceIdentifiers in the Order have been created via PaymentGroupDroplet. The CommerceIdentifierPaymentInfo objects have been added to the CommerceIdentifierPaymentInfoContainer.

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
&nbsp;</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>&nbsp;</td>
                        <td>
                        $<dsp:input
bean="PaymentGroupFormHandler.currentList[param:index].splitAmount"
size="6" value="0.00" type="text"/></td>
                        <td>&nbsp;</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>&nbsp;</td>
                        <td>&nbsp;</td>
                        <td>&nbsp;</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 an OrderPaymentInfo object for the user’s current order and add it to the CommerceIdentifierPaymentInfoContainer. Recall from the previous section that by default PaymentGroupDroplet associates each CommerceIdentifierPaymentInfo object with the default payment group in the PaymentGroupMapContainer. (Note that the available CreditCard payment groups have been initialized and added to the PaymentGroupMapContainer on a previous page, billing.jsp.)
The PaymentGroupFormHandler.listId property is set to the ID of the Order object set in the order output parameter of PaymentGroupDroplet. The order’s ID is the key to its List of CommerceIdentifierPaymentInfo objects, which are now exposed via the PaymentGroupFormHandler.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 of CommerceIdentifierPaymentInfo objects for the current Order. It renders its output oparam once for each CommerceIdentifierPaymentInfo object in the array. Essentially, the output rendered is a form that displays the following: the amount associated with the current CommerceIdentifierPaymentInfo object, a drop-down list with which to change the payment group for a specified amount in the CommerceIdentifierPaymentInfo object, a textbox with which to specify the amount in the CommerceIdentifierPaymentInfo 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 the PaymentGroupDroplet through a paymentGroups convenience parameter, and a second nested ForEach 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 current CommerceIdentifierPaymentInfo object. Similarly, the amount textbox is associated with the splitAmount property of the current CommerceIdentifierPaymentInfo object.
  Finally, note that the Save submit button invokes the handleSplitPaymentInfos method of PaymentGroupFormHandler. The handleSplitPaymentInfos method uses the values in the amount and splitAmount properties of the CommercIdentifierPaymentInfo 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 the splitPaymentMethod property to construct a second CommerceIdentifierPaymentInfo object. The method then sets the properties of both the old and new objects accordingly and adds the new object to the CommerceIdentifierPaymentInfoContainer. 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 of PaymentGroupFormHandler, which adds the payment groups that the user has selected to the Order. It does this by iterating over the CommerceIdentifierPaymentInfo objects in the CommerceIdentifierPaymentInfoContainer. For each CommerceIdentifierPaymentInfo object in the container, the associated payment group is retrieved from the PaymentGroupMapContainer and added to the Order, and the appropriate amount of the associated CommerceIdentifier is added to that PaymentGroup.

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.

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 <ATG10dir>\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.

Adding Payment Information to Shopping Carts

Creating Potential Payment Groups

Using createAllPaymentInfos

Adding Payment Groups to an Order

ATG Commerce Guide to Setting Up a Store