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. (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 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, ATG Commerce supports the following types of PaymentGroups: giftCertificate, storeCredit, and creditCard. ATG Business Commerce also supports invoiceRequest 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
`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.
`initItemPayment`	Boolean. When set to true, `PaymentGroupDroplet` creates a `CommerceItemPaymentInfo` object for each `CommerceItem` in the order and adds them to the `CommerceIdentifierPaymentInfoContainer`. 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`. 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`. 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 GiftCertificatePaymentGroup 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 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 outputoparam 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.

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.

ATG Commerce Guide to Setting Up a Store