Manage the checkout flow for orders requiring approval

Commerce cannot store payment details such as credit card information in between when an order is placed and when the order is approved.

As such, storefronts that use the order approvals feature must implement two checkout layouts, one for the initial checkout flow and a second for when payment is provided after approval has been given. The initial checkout flow layout handles orders in the following way:

If an order does not require approval, the shopper can pay for it immediately using any payment method she chooses to provide.
If the order requires approval, the shopper can either:
- Pay for it immediately with a deferred payment method like invoice or cash that does not require storing payment details. Orders that fall into this category are immediately processed after approval is given and require no further interaction by the shopper.
- Opt to pay for the order after approval is given, using a non-deferred payment method like a credit card or gift card. The shopper is notified via email after order approval is given and must return to the store to provide payment information. This is when the shopper is presented with the post-approval checkout layout.

Because order approval is based on aspects of the order (such as the order total or items the order contains) at the time the shopper submitted the order, the post-approval checkout layout must restrict the shopper from editing the order in any way other than providing payment information. To pay for an approved order, the shopper must view the order’s details, either by clicking a link in the Order Approved notification email or by viewing her order history and clicking the order that is pending payment. When a shopper is viewing order details for an approved order that is pending payment, a Complete Payment button is provided. Clicking this button sends the shopper to the post-approval checkout layout, where she can provide the payment information.

The following sections describe how to create the two checkout layouts that support order approvals.

Note: The sections below provide the minimum version number for each of the widgets you will be placing on the checkout layout. In order for the order approvals feature to work as described in this section, you must use these minimum versions or later. To tell which version of a widget you are using, view the widget’s settings and click the About tab to see the widget’s version number.

Initial checkout flow for order approvals

Follow the instructions below to create the initial checkout flow for storefronts that use order approvals.

To create the initial checkout flow:

On the Design tab, clone the Checkout Layout and give it a descriptive name like Checkout, Order Approval, Immediate Payment.
Enable the Display layout to account shoppers only option and save the clone.
Go to Grid View for the Checkout, Order Approval, Immediate Payment layout.
The rows containing the Notifications Widget, Header – Basic Widget, and Footer Widget widget instances should remain as is. Remove all widgets from the row in between them (Login – Checkout, Customer Address Book, Payment Details, and so on) and drag the column separator to the right to reconfigure the row to have a single column.
Add a Progress Tracker stack to the empty row you just created.
Edit the Progress Tracker so that it has the following tabs:
- Login
- Schedule Order (this tab is not required if your storefront does not include the scheduled orders feature)
- Shipping and Promotions
- Billing and Payments
On the Login tab, add the Login – Checkout widget (version 2 or later).
If you created a Schedule Order tab, add the Scheduled Order – Checkout widget to it (version 2 or later).
On the Shipping and Promotions tab, add new instances of the following widgets and modify them as described:
- Promotion (version 1 or later).
- Managed Account Address Book (version 3 or later). Name the instance Managed Account Address Book, Shipping Only. View the widget’s settings and disable the Include Billing Details option.
- Cart Summary (version 5 or later).
- Order Summary - Checkout (version 9 or later). Follow the instructions in Modify the Order Summary – Checkout widget to edit the widget to hide the Place Order button and enable the Shipping Method menu.
- Check for Approval Required. This is a custom widget that you have to create yourself. See Create the Check for Approval Required widget for details on how to do so.
On the Billing and Payments tab, add new instances of the following widgets and modify them as described:
- Managed Account Address Book (version 3 or later). Name the instance Managed Account Address Book, Billing Only. View the widget’s settings and disable the Include Shipping Details option.
- Payment Gateway Options (version 1 or later). Modify the instance to include elements for any deferred payment methods your storefront supports for orders that require approval, such as Invoice Payment and Cash Payment. Make sure to configure the payment gateway for any payment methods you add here. For more information, see Configure a deferred payment gateway for order approvals.
Note: If an order requires approval and a payment gateway is not configured for order approvals (that is, the enableForApproval flag has not been set to true for the gateway) then the payment method associated with that gateway will be hidden and disabled.
- Pay After Approval (version 1 or later). This widget provides shoppers with a checkbox that allows them to specify that they will pay for the order after approval has been given.
- Payment Details (version 6 or later). This version of the widget is hidden if the order requires approval.
- Gift Card Widget (version 3 or later). This version of the widget is hidden if the order requires approval.
- Cart Summary (version 5 or later).
- Order Summary - Checkout (version 9 or later). Follow the instructions in Modify the Order Summary – Checkout widget to edit the widget to display the Place Order button and disable the Shipping Method menu.
In addition to the new widget instances you just added to the Billing and Payments tab, you must also add an instance of the Cart Summary widget (version 5 or later). For this widget, use the same instance you created and placed on the Shipping and Promotions tab.

Checkout flow for payment after approval

Follow the instructions below to create a layout for the checkout flow that is used when orders are paid for after approval has been given.

To create the delayed payment checkout flow:

On the Design tab, clone the Checkout Layout and give it a descriptive name like Checkout, Order Approval, Delayed Payment.
Enable the Display layout to account shoppers only option.
Set the layout to be displayed when the Order Status is PENDING_PAYMENT. If your storefront uses the scheduled orders feature, also set the layout to be displayed with the Order Status is PENDING_PAYMENT_TEMPLATE.
Save the clone.
Go to Grid View for the Checkout, Order Approval, Delayed Payment layout.
The rows containing the Notifications Widget, Header – Basic Widget, and Footer Widget widget instances should remain as is. Remove all widgets from the row in between them (Login – Checkout, Customer Address Book, Payment Details, and so on).
Add a new instance of the Managed Account Address Book widget (version 3 or later) to the empty row you just created. Name the instance Managed Account Address Book, Delayed Payment. View the widget’s settings and ensure that both Include Billing Details and Include Shipping Details are enabled. Note that this version of the widget will disable editing of the shipping address if the order state is PENDING_PAYMENT.
Add the next four widgets to the row. Use the same instances you created for the Billing and Payments tab of the immediate payment flow.
- Payment Gateway Options (version 1 or later).
- Payment Details (version 6 or later)
- Gift Card Widget (version 3 or later)
- Cart Summary (version 5 or later).
Add a new instance of the Order Summary - Checkout widget (version 9 or later) to the row.

Modify the Order Summary – Checkout widget

The HTML for the Order Summary – Checkout widget instances on both the Shipping and Promotions tab and the Billing and Payments tab must be modified to support the two order approval-related checkout layouts.

For the Shipping and Promotions tab

Edit the instance of the Order Summary – Checkout widget that resides on the Shipping and Promotions tab to remove the following code from the widget’s HTML template:

<!-- ko ifnot : (order().approvalRequired()) -->
<div class="paymentoptions hidden-xs">
  <h3 data-bind="widgetLocaleText:'paymentOptionsText'"></h3>
  <div class="row-payments">
    <!-- ko foreach: payment().cards -->
    <span data-bind="css : ($index() % 4) == 0 ? 'row-first' : '' ,
       attr:{id: 'CC-checkoutOrderSummary-payment'+$parents[1].id()+value}">
    <img data-bind="attr:{src: img}" alt=""/>
    </span>
    <!-- /ko -->
  </div>
</div>
<!-- /ko -->
<!-- ko ifnot : (order().showSchedule) -->
<div id="CC-checkoutOrderSummary-placeOrder" class="checkout row">
<button class="cc-button-primary col-xs-12" data-bind="click: handleCreateOrder,
enable: order().enableOrderButton">
<span data-bind="widgetLocaleText:'placeOrderText'"></span></button></div>
<!-- /ko -->
<!-- ko if : (order().showSchedule) -->
<div id="CC-checkoutOrderSummary-placeOrder" class="checkout row">
<button class="cc-button-primary col-xs-12" data-bind="click: handleCreateOrder,
enable: order().enableOrderButton">
<span data-bind="widgetLocaleText:'scheduleOrderText'"></span></button></div>
<!-- /ko -->
<p><span data-bind="widgetLocaleText:'paymentMessage'"></span></p>
<!-- ko if : $data.payment().gateways.paypalGateway.enabled -->
<!-- ko ifnot : (order().approvalRequired()) -->
<!-- ko ifnot : (order().isPaypalVerified()) -->
<div id="CC-checkoutOrderSummary-paypal" class="checkout row">
  <!-- ko if: (order().showSchedule() &&
       !order().paymentDetails().isPaypalEnabledForScheduledOrder()) -->
  <span id="CC-checkoutOrderSummary-paymentAvailablability"
    data-bind="widgetLocaleText: 'paymentMethodNotAvilable'"></span><br>
  <img class="img-responsive center-block" alt="checkoutWithPayPal"
    data-bind="attr: {src: paypalImageSrc}">
  <!-- /ko -->
  <!-- ko ifnot: (order().showSchedule() &&
       !order().paymentDetails().isPaypalEnabledForScheduledOrder()) -->
  <a data-bind="attr : { id: 'CC-checkoutOrderSummary-checkoutWithPaypal'},
    disabled: {condition: cart().items().length == 0,
    click: order().handleCheckoutWithPaypal.bind(order()) }" href="#">
  <img class="img-responsive center-block" alt="checkoutWithPayPal"
    data-bind="attr: {src: paypalImageSrc}">
  </a>
  <!-- /ko -->
</div>
<!-- /ko -->
<!-- /ko -->
<!-- /ko -->

For the Billing and Payments tab

Edit the instance of the Order Summary – Checkout widget that resides on the Billing and Payments tab to replace this portion of the widget’s HTML template:

<button id="cc-shippingOptions-dropDown" class="btn dropdown-toggle col-xs-12"
data-toggle="dropdown" tabindex="0" data-bind="click:
displayShippingMethodsDropdown,disable: !order().isOrderEditable(),
attr: {'aria-label': ''}" style="border-color:#ddd;background-color:white;">

With the following code:

<button id="cc-shippingOptions-dropDown" class="btn dropdown-toggle col-xs-12"
        data-toggle="dropdown" tabindex="0" data-bind="click:
        displayShippingMethodsDropdown,disable: true, attr: {'aria-label': ''}"
        style="border-color:#ddd;background-color:white;">

Create the Check for Approval Required widget

The checkout flow for order approvals requires a custom widget that determines whether or not an order requires approval. This widget manages what the shopper sees for billing and payment options, depending on whether or not an order requires approval. For example, if the order requires approval, the shopper will not be able to pay for the order using a credit card. This widget does not have any UI associated with it, only the logic for determining if the order requires approval.

For general information on creating and uploading a custom widget, refer to Create a Widget. The code snippets below show you the custom code that must exist in the widget.

The following example shows the JavaScript for the Check for Approval Required widget:

/**
 * @fileoverview Check for Approval Require Widget.
 *
 * @author
 */
define(
  //-------------------------------------------------------------------
  // DEPENDENCIES
  //-------------------------------------------------------------------
  ['knockout', 'pubsub', 'notifier', 'CCi18n', 'ccConstants', 'navigation',
   'ccRestClient'],
  //-------------------------------------------------------------------
  // MODULE DEFINITION
  //-------------------------------------------------------------------
  function(ko, pubsub, notifier, CCi18n, CCConstants, navigation, ccRestClient) {
    "use strict";
  return {

    onLoad: function(widget){
      var pageId=widget.pageContext().pageType.id;
    },
     validate : function() {
         var orderId=this.user().orderId();
         var data = {
             "orderId":orderId
         };
         this.order().checkOrderForApproval(data);
       return true;
   }
  }
});

The following example shows the content of the HTML template for the Check for Approval Required widget. Note that, because there is no UI associated with this widget, it contains only a placeholder <div> element:

<div style="display:none"></div>