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" : "bshopper@example.com"
},
"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¶m2=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.