Brief description about platform's core functionality.
Last updated
Initial setup
The detailed instructions below assumes that you already have an insurer account within the KASKO platform and you have understanding how to create and configure a product explained in detail within Product Builder Manual.
Before we can start using some of the platform core functionalities, we will need to setup a product. For showcase purposes we will be creating a mock company cyber insurance product that will have the following settings configured:
pricing logic
field definition
payment plan
The same product will be used in the sections below in order to hands-on explain how to use the platform.
Product creation
We will be creating a simple cyber insurance product with English language and TEST policy prefix. This product will not have sub products - all of the product settings will be configured on product level.
Pricing logic
For pricing logic, we will be using single payment pricing logic with the pricing file below:
And with the following validation rules under Validation Rules section:
The product will have a single payment plan setup with an insurer payment method and invoice as the payment provider.
Integration
We will also need to create an integration. We can name it whatever we like, however since our mock product will be used through API only, we will toggle API Only Integrationon.
Policy creation flow
The core functionality of platform is the policy creation flow. In order to create a policy in KASKO, three steps must be completed:
Quote generated;
Offer created;
Payment made;
This guide will be using the product created from Initial setup and will go through all of three steps above with request and response examples, explaining each of the steps in detail.
Quote generation
A "quote" refers to an estimate or proposal provided by the insurance product to a potential customer, outlining the cost and terms of an insurance policy.
The quote is calculated from the pricing logic file uploaded, given the user input.
In order to generate a quote, Create a quote API endpoint must be called.
In order to successfully construct the necessary payload, we will need to know:
product's payment plan id,
integration id and the,
public key.
Given the pricing logic and our hypothetical company we wish to insure, we construct the request below.
Pricing logic specific data must be passed within the data object and this data will be later passed to the pricing logic to perform the calculations.
As our product is not published, we set live_product & live_integration properties to "false" and for demonstration purposes we substituted product-specific variable values with curly braces (i.e. {{ integration_id }}).
If everything is setup correctly, expected response should look something like this:
If one or more of the values fails either the defined validation rules within the product settings or the validation present within the pricing file itself, it will be noted to the end-user. An example of a failed validation response would look something like this:
Within the example we did not provide a value for company backup and the following response with a 400 status code was returned, as company_backup is defined as required in validation string.
Unpaid policy creation
Within the platform, an unpaid policy is considered an offer, so when an offer is created, technically platform is creating a policy that is waiting to be paid for.
Within the payload, the API expects data object. This is where we pass policy specific data. This data must align with the field definition configured (i.e. all the fields are present in the definition and they pass the validation rules). Given the mock product's field definition and the company we wish to insure, we construct the following payload:
Similar to the quote request, if any of the fields fail validation, a 400 HTTP status code response is returned with validation error response. For example, If subsidiary value is provided that exceeds the maximum of 20, following message is returned to the end-user:
On success, a payment token is generated (i.e. payment_token) and an unique 33 character offer ID (i.e. tpol_...) is returned.
Paying for policy
When constructing the payload for the request, provider and method properties must be set. These values depend on the product's configuration, however, since our mock product payment is setup to use invoice, we will use invoice for both of these properties.
The payment request should look something like this:
To view more detailed information about the policy, other means of authorization must be used. The example above used a public key which restricts access to certain policy fields, thus only limited information can be fetched about the policy.
In this section we managed to undergo the policy creation flow and have successfully issued a policy for our mock product, exploring one of the core functionalities of the KASKO platform.
To create an offer, refer to section. API expects a quote_token property. This is where you pass the acquired token from previous request.
In order to pay for a policy API must be used. API expects two values - payment_token and policy_id that are to be taken from Unpaid policy creation request. policy_id will be the policy for which the payment will be taken.
To view our newly issued insurance policy, refer to the API section.
