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 Cloud 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", "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", "orderId" : "o60412", "paymentMethod" : "generic", "profile" : { "id" : "140160", "phoneNumber" : "617-555-1977", "email" : "bshopper@example.com" }, "gatewayId" : null }
The checkout system typically creates its own representation of the order and sends a response to Commerce Cloud indicating that it was created successfully. This triggers an ORDER_CREATED_INITIAL
event. 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.
A key aspect of the integration involves the use of custom order properties. 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 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", "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 custom order properties.