Completing The Purchase

The in-path booking widget will allow you to generate a final sales quote from the information you provide which you can then use in your backend after final purchase to record the sale with Sitata.

If you do not have a complete set of required information, the widget will also attempt to collect it. For example, if you do not have complete customer details and are missing age, the widget will provide some inputs for the customer to complete. A temporary price will be displayed until more details are provided by the customer.

After enough details are collected, the widget will allow you to generate the final Sales Quote.

For example:


// A function that is triggered when the customer 
// has selected a product.
function captureProducts(event) {
    // update cart with product information.
    let products = event.detail
    let totalCost = 0
    for(var i = 0; i < products.length; i++) {
        let product = products[i]
        console.log(product.name, product)
        let quote = product._quote
        // Sitata measures cost in the lowest common currency
        // denomination. e.g. cents for dollars, pence for british pounds, yen for yen, etc.
        // You can consider multiplying the value by the 
        // cost_modifier field. e.g. for dollars use:
        // totalCost += (quote.cost + quote.insurance_taxes + quote.taxes) * quote.cost_modifier
        totalCost += quote.cost + quote.insurance_taxes + quote.taxes
    }
    console.log("total cost", totalCost)
    // update cart with cost or names of products, etc
}

function captureError(event) {
    console.log("CAUGHT ERROR", e.detail)
}

// When you're ready to capture the final quote for payment processing.
// Depending upon your front end, you will likely call this before
// proceeding to the next step in your booking flow.
function captureInsuranceQuote() {
    window.sitataWidget.onContinue()
        .then((result) => {
            console.log("RESULT", result)
            switch(result.status) {
              case 'noSalesQuote':
                // user is electing to not select a product
                // continue with checkout process
                console.info('continue checkout - no protection')
                break;
              case 'successfulQuote':
                console.info('send quote to backend', result.salesQuote)
                console.info('request params to be adjusted are:', result.salesQuote.request_params)
                break;
            }
          })
          .catch((reason) => {
            console.log("REASON", reason)
            switch(reason.status) {
              case "invalidSelections":
                console.info('no selections')
                // user left widget in a state that
                // requires selections
                // perhaps scroll to widget
                break

            }
          })
}

function startWidget() {
    // note that the sitata widget is being stored on the window object so
    // we can call functions on it at a later point in time.
    let window.sitataWidget = new window.Sitata.inpathInsure(el, options)
    // start the widget
    window.sitataWidget.run()
}
    
window.document.addEventListener('sitata:inpathInsureReady', startWidget)
window.document.addEventListener('sitata:inpathError', captureError)
window.document.addEventListener('sitata:selectedProducts', captureProducts)

In the above example, three events are being listened to. One is for initializing the widget. One is for listening for errors. The last is for listening to changes in a user's product selection so that you can update your cart information for display purposes.

info

Use the selectedProducts event to update your cart's product list and totals when a user adds or removes a product. Each product should have an associated quote under the _quote attribute.

Obtaining a Sales Quote

At an appropriate time in your booking flow (e.g. on next button click), you should call the widget's onContinue function. This function will perform any necessary validation checks before attempting to generate a final Sales Quote, if necessary. Sometimes the user will have elected not to purchase insurance in which case it will not be necessary to generate a Sales Quote.

The onContinue function will return a promise that resolves or rejects with an object with the following properties:

    {
        status: 'successfulQuote',
        salesQuote: <SALES QUOTE OBJECT HERE>,
        error: null
    }

The status property can have the following values:

Status	Description
successfulQuote	A final sales quote has been generated.
noSalesQuote	No sales quote was generated as it was not necessary.
invalidSelections	The widget is in an error state because the user has not picked valid selections.

The final Sales Quote will resemble the following:

{
    "charge": null,
    "cost": 9470,
    "cost_modifier": 0.01,
    "cost_symbol": "£",
    "created_at": "2024-07-18T17:46:20.220158Z",
    "currency_code": "GBP",
    "days_to_departure": 12,
    "finish": "2023-11-30T04:59:59.000000Z",
    "id": "c07f5ad9-d4d1-421c-9668-7607fe5fd356",
    "insurance_taxes": 0,
    "num_people": 2,
    "num_subscriptions": 1,
    "payment_intent_client_secret": null,
    "payment_intent_id": null,
    "previous_product_sale_group_id": null,
    "product_quote_ids": [
        "6007beea-8d0a-4b65-92c7-d81250af3553",
        "4149128a-5c8a-4146-b2dd-7470cb5cb047"
    ],
    "product_quotes": [<PRODUCT_QUOTE>, <PRODUCT_QUOTE>],
    "refund_charge": null,
    "refunded": false,
    "request_params": {
        "affiliate_id": null,
        "client_type": "web",
        "country_code": "GB",
        "currency_code": "GBP",
        "lang": "en",
        "metadata": {
            "browser_agent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Mobile Safari/537.36",
            "browser_name": "Netscape",
            "browser_platform": "MacIntel",
            "browser_version": "5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Mobile Safari/537.36"
        },
        "region_code": "US-CA",
        "subscriptions": [
            {
                "beneficiaries": [
                    {
                        "_id": "1721324771029-0.6796939041481032",
                        "birthday": "1970-04-09",
                        "email": "[email protected]",
                        "home_country": "GB",
                        "name": "Susan Jekins",
                        "relation": 0
                    }
                ],
                "product_ids": [
                    "7637e020-f74b-4dca-9479-437339cd2f2a",
                    "5e4ae692-eacf-4422-a5ca-117bb5b434a7"
                ],
                "user": {
                    "address": {
                        "address1": "123 willaby lane",
                        "address2": null,
                        "address3": null,
                        "address_str": "123 willaby lane, London, United Kingdom",
                        "city": "London",
                        "country": "United Kingdom",
                        "postal_code": "N2G 1H6"
                    },
                    "birthday": "1968-04-09",
                    "email": "[email protected]",
                    "home_country": "GB",
                    "name": "Jimmy Bean"
                }
            }
        ],
        "trip": {
            "currency_code": "GBP",
            "destinations": [
                {
                    "country_code": "CH",
                    "entry_date": 1700542800,
                    "exit_date": 1700801999,
                    "friendly_name": "Switzerland",
                    "type": 0
                },
                {
                    "country_code": "ES",
                    "entry_date": 1700715600,
                    "exit_date": 1701320399,
                    "friendly_name": "Spain",
                    "type": 0
                }
            ],
            "finish": 1701320399,
            "finish_date": "2023-11-29T23:59:59+00:00",
            "start": 1700542800,
            "start_date": "2023-11-21",
            "total_cost": 100000
        },
        "trip_deposit_date": null
    },
    "running_cost": null,
    "running_insurance_taxes": null,
    "running_taxes": null,
    "start": "2023-11-21T05:00:00.000000Z",
    "subscriptions": [],
    "taxes": 0,
    "updated_at": "2024-07-18T17:46:20.220158Z"
}

(please note that the product quotes which make up the sales quote were removed for brevity)

In particular, you should use the Sales Quote's request_params field which will give you an almost fully formed request body to use with Sitata's backend.

Note in the previous examples that the user's name and email were not available at the time of generating a final Sales Quote and some temporary values were inserted as seen in the request_params field of the Sales Quote. The same is true for the beneficiaries.

You will need to ensure that this user information is present before sending it to Sitata so that we have the correct user details. In some cases you might need to add it (for example, if you are quoting before your passenger/traveller information is fully known).

Your next steps should be:

Send the Sales Quote to your backend.
Adjust the Sales Quote request_params field to have the correct User and Beneficiary details.
Optionally persist the SalesQuote (with modified request_params).
Use the id of the SalesQuote and the request_params as the request body to register the sale with Sitata upon successful payment in your booking/checkout workflow.

Completing the purchase from your backend

In order to complete the purchase, you must send the Sales Quote id and the adjusted request_params as the request body to Sitata from your backend. To do so, you should perform a POST request to the following endpoint:

https://www.sitata.com/api/v2/products/quote/:id/capture

Upon successful request, the purchase will be recorded and policy wording and other important information will be relayed to your customer.

warning

The above request should be sent from your backend upon successful payment from your customer. You should also consider making the capture quote request using a queuing system that can retry (with exponential backoff) in the event of a failure or system downtime.

Please note, in order to act as merchant of record for any insurance products, your organization will need to adhere to the local regulatory requirements for distribution of insurance products and have the distributor role assigned to your company by Sitata.

Next we will review the widget's configuration options.

info

Obtaining a Sales Quote​

Completing the purchase from your backend​

warning

Obtaining a Sales Quote

Completing the purchase from your backend