Flex checkout

Basically the flex checkout lets you decide which data (e.g. amount, description, generated images, ...) will be passed to the parent page when a user performs a Checkout.

As already described in Embedding and configurations, the configurator will communicate with the parent page via cross-document messaging during the checkout. Technically speaking this all happens within your browser on the client side, so it is extremly fast.

Combeenation platform

On the Combeenation platform you just have to define the data within the property Parameter in the flex shop. Combeenation won't enforce a specific file format (can be JSON, CSV, XML, ...), but we strongly recommend JSON. If you aren't required to use a specific JSON format, we strongly recommend the following structure:

{
    "products": [ 
        { // (mandatory) at least one product must be defined
            "main": { // (mandatory) 
                "productId": "123456", // (mandatory) SKU
                "quantity": 1,
                "price": 99.99, // gross price of the configured product WITHOUT accessories
                "imageUrl": "Assetbundle1.MyImage.url", // url to the image which will be used in the cart
                "title": "My coffee mug", // new title of the product
                "productText": "My own description", // new description of your product
                "customFields": [ // (optional)
                    {
                        "id": "model", // (mandatory) unique identifier
                        "label": "Model type", // label which the user will also see in the cart (if it is visible)
                        "value": "espresso", // value of the custom field
                        "position": 1, // position in the cart
                        "isVisible": true // if it should be visible in the cart
                    }
                ]
            },
            "accessories": [ // (optional) additional predefined products which will be added to the cart (no custom price/image/title)
                {
                    "productId": "987654",
                    "quantity": 1
                },
                {
                    "productId": "456789",
                    "quantity": 1
                }
            ]
        }
    ]
}

Your website/shop/system/...

On the parent page (on which the configurator is embedded) you just have to implement the JavaScript function window.Combeenation.onCheckout. This function will be called during the checkout and has one parameter which contains:

• configuration id
• configuration auth token
• CheckoutParameters are the values you have defined previously
• CheckoutParametersHash SHA256 hash of CheckoutParameters
• queryParameters which are set to the iframe url

With this data on your hand you can implement your further checkout logic on your own. Example implementation of the checkout function:

<script type="application/javascript">
  window.Combeenation = (window.Combeenation || {});
  window.Combeenation.onCheckout = function(data) {
    /*
    structure of the parameter 'data':
    data.id // id of the configuration (Provided by Combeenation)
    data.authentication // authentication token, which is needed if a customer wants to edit the configuration. (Provided by Combeenation)
    data.checkoutParameters // value of the checkout component property 'Parameter' (Provided by you)
    data.checkoutParametersHash // SHA256 hash of `CheckoutParameters` (Provided by Combeenation)
    data.queryParameters // all query parameters which are added to the iframe URL (Provided by the person who inserts the iframe in the page)
    */

    // e.g. make AJAX calls, redirects, ...
  }
</script>

Data security (integrity)

The checkout response property checkoutParametersHash contains a SHA256 hash over the checkoutParameters. The hash will be salted with a secret which can be defined in the HashSecret property of the flex shop. This secret should be kept private and only be stored on your server.

With the checkoutParameters and the secret you can calculate a hash and test whether it matches the given checkoutParametersHash. If the hash differs the checkoutParameters have been altered.

Example for checking the hash in PHP:

$secret = "myPrivateSecretWhichIsOnlyStoredOnTheServer";
$data = $_POST["checkoutParameters"];
$givenHash = $_POST["checkoutParametersHash"];

// (optional) normalize line endings; there should be no \r in the checkoutParameters
$data = str_replace("\r\n", "\n", $data);

// convert base64 hash
$base64Hash = base64_encode(hash_hmac('sha256', $data, $secret, true));

// check hash
if($base64Hash == $givenHash) {
  echo "Add to cart successful";
} else {
  echo "Hash invalid!";
}