Initiate the order

When the shopper invokes checkout with an external checkout system, the Store API createOrder endpoint sends the contents of the shopping cart to the Commerce server, and includes a special parameter ("op":"initiate") to specify that the order being created is incomplete.

The server invokes the Generic Payment webhook, which sends an initiate transaction request with the cart data to the web checkout system. For example:

{
    "transactionId" : "o60412-pg60411-1465342272905",
    "currencyCode" : "USD",
    "paymentId" : "pg60411",
    "locale" : "en",
    "siteURL": "https://www.example.com",
    "customProperties" : { },
    "gatewaySettings" : [ {
      "name" : "paymentMethodTypes",
      "value" : "generic"
    } ],
    "amount" : "000000004999",
    "transactionType" : "0800",
    "items" : [ {
      "id" : "ci6000412",
      "catRefId" : "sku10020",
      "price" : 49.99,
      "rawTotalPrice" : 49.99,
      "description" : "Xbox 360 Controller",
      "quantity" : 1,
      "unitPrice" : null,
      "displayName" : null,
      "options" : [ ],
      "productId" : "prod10017"
    } ],
    "transactionTimestamp" : "2016-06-07T23:31:12+0000",

    ... billing and shipping addresses ...

    "channel" : "storefront",
    "siteId": "siteUS",
    "orderId" : "o60412",
    "paymentMethod" : "generic",
    "profile" : {
      "id" : "140160",
      "phoneNumber" : "617-555-1977",
      "email" : "[e-mail]"
    },
    "profileDetails": {
      "id": "140160",
      "lastName": "Shopper",
      "firstName": "Test",
      "taxExempt": false,
      "profileType": "b2c_user",
      "receiveEmail": "no",
      "registrationDate": "2019-10-15T06:50:51.000Z",
      "lastPasswordUpdate": "2019-10-15T06:50:51.000Z",
    },
    "retryPaymentCount": 0,
    "gatewayId" : "demoGenericGateway"
}

The checkout system typically creates its own representation of the order and sends a response to Commerce indicating that it was created successfully. This triggers an ORDER_CREATED_INITIAL event on the client. You can write widget code to subscribe to this topic. For example:

$.Topic(pubsub.topicNames.ORDER_CREATED_INITIAL).subscribe(
   widget.initialOrderCreated.bind(widget));

In this example, the widget defines a function called initialOrderCreated() that subscribes to the ORDER_CREATED_INITIAL topic. The response object, named order, is passed in the event. Your custom widget can retrieve the response and inspect the properties of the order.

Note that when the shopper is directed back to the checkout page from the web checkout system (as described in Retrieve the order), the shopping cart should be retrieved from the Commerce server, not reloaded from local storage. To prevent reloading from local storage, your widget code should set the ccConstants.SKIP_LOADING_LOCAL_CART variable to true before initiating the web checkout. For example:

widget.initialOrderCreated = function(orderEvent) {
    var widget = this;
    storageApi.getInstance().setItem(ccConstants.SKIP_LOADING_LOCAL_CART,true);
    navigation.goTo(widget.links().checkout.route+'?
      param1=test1&param2=test2&orderId='+orderEvent.order.id);
};

Setting the variable to true prevents the cart from being reloaded from local storage, and causes a DEFERRED_CART_LOAD event to be published from the initCatalog() function of the CartViewModel. When the order is retrieved, the handlePageChanged() widget function receives this event. See Retrieve the order for more information.

Use custom properties

A key aspect of the integration involves the use of custom properties in the Generic Payment webhook data. The webhook response to the initiate request may include custom properties that the storefront can use to hand off control to the external system.

For example, the response may include a REDIRECT property that specifies the URL for redirecting the shopper’s browser to the external checkout system:

{
     "orderId": "o60412",
     "paymentId": "pg60411",
     "merchantTransactionId": "c9f058f8-ef54-44cc-9c90-dc58269d3667",
     "hostTransactionId": "o60412-pg60411-1465342272905",
     "transactionTimestamp": "2016-06-07T23:31:12+0000",
     "hostTimestamp": "2016-06-07T23:31:14+0000",
     "transactionType": "0800",
     "siteId": "siteUS",
     "additionalProperties": {
          "AddProp1": "AddProp1_value",
          "AddProp2": "AddProp2_value",
          "AddProp3": "AddProp3_value",
          "REDIRECT": "checkout_system_URL"
     },
     "externalProperties": ["AddProp2", "REDIRECT"],
     "amount": "000000004999",
     "currencyCode": "USD",
     "response": {
          "success": true,
          "code": "Response Code Value",
          "description": "Response description value",
          "reason": "Response reason value"
     }
}

See Send custom properties to a payment gateway for more information about using custom properties with the Generic Payment webhook.