Gift certificates allow a customer to pay for all or part of a purchase using a prepaid amount. Processing a gift certificate involves the following steps:

The Purchase and Fulfillment Process for Gift Certificates

Set up gift certificates as items in your product catalog, adding separate SKUs for different amounts. For example, you could have two SKUs, one for a $50 dollar certificate and another for a $100 certificate. The value of the gift certificate is stored in the listPrice property of each gift certificate SKU in the product catalog.

Each SKU has a fulfiller property that defines an ElectronicFulfiller. When Customer A adds a gift certificate to his or her shopping cart, the fulfiller property tells the OrderFulfiller to route the purchase to the specified ElectronicFulfiller. The ElectronicFulfiller then creates the gift certificate in the Claimable repository (by means of the ClaimableManager component) and sends an e-mail to the recipient notifying him or her that a gift certificate has been purchased on his or her behalf and including the code to use for claiming it. Refer to the Configuring the Order Fulfillment Framework chapter for more information on the ElectronicFulfiller.

The following properties can be set when the gift certificate is created. The gift certificate is not functional unless the three required properties (identified below) are set.

amount

(Required) The original dollar value of the gift certificate.

amountAuthorized

(Required) The total amount of money on the gift certificate that has been authorized for debit.

amountRemaining

(Required) The current amount of money remaining on the gift certificate for debit.

purchaserId

The profileId of the person who bought the gift certificate.

purchaseDate

The date the gift certificate was purchased.

lastUsed

The latest date on which fulfillment updated the amount.

Note: By default, the stock level of a gift certificate is set to -1 indicating that an infinite number of the item is available. Setting the stock level of a gift certificate to 0 (out of stock) does not affect the gift certificate’s availability because the ElectronicFulfiller does not check a gift certificate’s stock level.

Sending an e-mail to the recipient of the gift certificate requires knowing his or her e-mail address. ATG Commerce does this through an ElectronicShippingGroup, which designates the necessary information for delivering electronic goods, in this case an e-mail address. So, when Customer A adds the gift certificate to his or her cart, you add an ElectronicShippingGroup to the order as well, and define the relationship between the two. Use the handleAddSoftGoodToOrder() method in the /atg/commerce/order/ShoppingCartModifier component to do this. The following example shows the JSP code you would add to the page on which the gift certificate product is displayed. It adds the gift certificate to the customer’s order and prompts him or her to specify the e-mail address of the recipient:

<%@ taglib uri="http://www.atg.com/dsp.tld" prefix="dsp" %>
<dsp:page>

<dsp:form action="<%=request.getServletPath()%>" method="post">
<!-- Store this Product's ID in the Form Handler: -->
 <dsp:input bean="ShoppingCartModifier.ProductId"
paramvalue="Product.repositoryId" type="hidden"/>
<!--set id param so that the Navigator won't get messed up
     in case of an error that makes us return to this page.-->
 <input value='<dsp:valueof param="Product.repositoryId"/>' type="hidden"
name="id">
    Give
    <dsp:input bean="ShoppingCartModifier.quantity" size="4" value="1"
type="text"/>

<!-----------DropDownList format (default) ----------- -->
<!--Create a dropdown list will all Sku in the Product.
           Store the selected SKU's id in the Form Handler: -->
       <dsp:select bean="ShoppingCartModifier.catalogRefIds">
<!--For each of the SKUs in this Product, add the SKU to the
            dropdown list:-->
  <dsp:droplet name="/atg/dynamo/droplet/ForEach">
         <dsp:param param="Product.childSKUs" name="array"/>
         <dsp:param value="Sku" name="elementName"/>
         <dsp:param value="skuIndex" name="indexName"/>
         <dsp:oparam name="output">
<!--This is the ID to store, if this SKU is selected in
             dropdown:-->
          <dsp:getvalueof id="option48" param="Sku.repositoryID"
idtype="java.lang.String">
<dsp:option value="<%=option48%>"/>
</dsp:getvalueof>
<!--Display the SKU's display name in the dropdown
              list:-->
          <dsp:valueof param="Sku.displayName"/>
         </dsp:oparam>
        </dsp:droplet>
<!--ForEach SKU droplet-->
       </dsp:select> to
       <br>
    Recipient's e-mail address
    <dsp:input bean="ShoppingCartModifier.softGoodRecipientEmailAddress"
size="30"/>
    <p>
 <!-- ADD TO CART BUTTON: Adds this SKU to the Order-->
     <dsp:input bean="ShoppingCartModifier.addSoftGoodToOrder"
value=" Add Gift Certificate to Cart " type="submit"/>
 <!-- Goto this URL if NO errors are found during the ADD TO CART
          button processing:-->
     <dsp:input bean="ShoppingCartModifier.addSoftGoodToOrderSuccessURL"
value="../checkout/cart.jsp" type="hidden"/>
     <dsp:input bean="ShoppingCartModifier.addSoftGoodToOrderErrorURL"
value="product_gift_certificate.jsp" type="hidden"/>
   </td>
  </tr>
 </table>
</dsp:form>

</dsp:page>

In this example, note the code that handles the recipient’s e-mail address. The customer enters the recipient’s e-mail address into a form field set to the property ShoppingCartModifier.softGoodRecipientEmailAddress. Thus, the e-mail address is set in the ElectronicShippingGroup through the handleAddSoftGoodToOrder method, and then the ElectronicFulfiller examines it to determine where to send the message.

Note that electronic goods require special processing, so the submit method of the form is set to addSoftGoodOrder and not addItemToOrder.

For more information on the ShoppingCartModifier component, please refer to the Setting Up Gift Lists and Wish Lists section.

Using a Gift Certificate

On your Checkout page (or an equivalent page on your site), include a text field where customers can enter the claim codes for any gift certificates they may have (you send the codes in the gift certificate notification e-mail). Hook the text field up to the giftCertificateNumbers property of the ShoppingCartModifier component. During the handleMoveToConfirmation process, the ShoppingCartModifier parses any values it finds in this field into tokens, using white space as the delimiter. This behavior allows customers to enter multiple gift certificate codes into a single text field.

After the system tokenizes the giftCertificateNumbers property, it hands each token string to the ClaimableManager component. The ClaimableManager attempts to match each string to a corresponding gift certificate in the Claimable repository. If it cannot find a corresponding item, it adds an error to the FormHandler. If the system does find an item that corresponds to the token string, it creates a new GiftCertificate payment group and adds it to the order.

You must initialize the properties of the payment group to the correct values. The properties to initialize include the claim code ID, the user profile ID, and the amount of the gift certificate. Finally, create a relationship between the order and the new payment group indicating that the gift certificate payment group can account for any amount up to the value of the gift certificate.

Please refer to the Configuring Purchase Process Services chapter for more information on payment groups.

Settling a Gift Certificate

Gift certificate settlement is handled similar to the way that settlement for credit cards is handled. (For more information, see the Processing Payment of Orders section.)

When an order is submitted, each PaymentGroup in the order is authorized using the PaymentManager. The PaymentManager has different processors for gift certificates and credit cards. The processor used for gift certificates handles the authorization, debit, and credit of gift certificates. When a gift certificate is authorized, the amountRemaining is reduced by the amount being authorized. This prevents the same gift certificate from being used for more than it is worth.

During fulfillment, the PaymentGroup containing the gift certificate is debited through the PaymentManager (and ultimately the GiftCertificateProcessor). When this happens, the amount that was authorized is checked against the amount that is being debited. If the amount authorized was the same as the amount being debited, the PaymentManager.debit returns successfully. If there are any differences, they are corrected now. To make sure that the gift certificate is valid if an order is removed before the debit occurs (and after authorization), any amount that was authorized will be credited back to the gift certificate before the PaymentGroup is removed.

 
loading table of contents...