After processing the payment information, some web checkout systems will issue a POST request to the Commerce Cloud store to redirect the shopper back to the checkout page to complete the order. The POST request triggers a PAGE_CHANGED event. Your widget code can subscribe to this topic. For example:

$.Topic(pubsub.topicNames.PAGE_CHANGED).subscribe(
   widget.handlePageChanged.bind(widget));

Your custom widget can handle the PAGE_CHANGED event by parsing the parameters in the incoming URL to extract custom properties that identify the order, and then adding these properties to the payment observables array in the OrderViewModel. For example:

widget.handlePageChanged = function(pageData) {

var widget = this;
  if (pageData.pageId === "checkout") {
    var urlParameters = pageData.parameters;
      if (urlParameters) {

        // extract the URL parameters
        var params = urlParameters.split('&');
        var result = {};
        for (var i = 0; i < params.length; i++) {
          var entries = params[i].split('=');
          result[entries[0]] = entries[1];
        }

    // add the extracted parameters to the payment as custom properties
    var payment = {type: "generic", customProperties: result};
    widget.order().addPayment(payment);
    widget.order().getOrder();
    }
  }
};

Notice the use of the getOrder() function. This function invokes the Store API getInitialOrder endpoint to retrieve the incomplete order. When the server receives the request, it invokes the Generic Payment webhook, which sends a retrieve transaction request to the web checkout system. For example:

{
    "transactionType" : "0900",
    "transactionTimestamp" : "2016-06-07T23:31:14+0000",
    "customProperties" : {
      "param1" : "test1",
      "param2" : "test2"
    },
    "gatewaySettings" : [ ],
    "channel" : "storefront"
 }

The webhook response must include the order ID so Commerce Cloud can retrieve the order. The response can also include an additionalProperties object, as well as an externalProperties object that specifies a list of the properties in the additionalProperties object that should be returned to the storefront. For example:

{
     "orderId": "o60412",
     "siteId": "siteUS",
     "transactionTimestamp": "2016-06-07T23:31:14+0000",
     "hostTimestamp": "2016-06-07T23:31:14+0000",
     "transactionType": "0900",
     "additionalProperties": {
          "RetrieveAddProp2": "RetrieveProp2_value",
          "RetrieveAddProp1": "RetrieveProp1_value"
     },
     "externalProperties": ["RetrieveAddProp2"],
     "response": {
          "success": true,
          "code": "Response Code Value",
          "description": "Response description value",
          "reason": "Response reason value"
     }
}

A successful response triggers an ORDER_RETRIEVED_INITIAL event. Your widget can subscribe to this topic:

$.Topic(pubsub.topicNames.ORDER_RETRIEVED_INITIAL).subscribe(
   widget.handleOrderRetrieved.bind(widget));

Your widget should then handle the ORDER_RETRIEVED_INITIAL event by adding the updated payment information to the OrderViewModel:

widget.handleOrderRetrieved = function(orderEvent) {

var widget = this;
widget.order().id(orderEvent.order.id);
widget.order().isVerified(true);

var payment = {type: "generic",
  paymentGroupId: orderEvent.order.payments[0].paymentGroupId};
var payments = [payment];
widget.order().updatePayments(payments);
};