README

Installation
Getting Started
Usages

Installation

To install through composer, simply put the following in your composer.json file:

{
    "require": {
        "katsana/insurance-sdk-php": "^0.2",
        "php-http/guzzle6-adapter": "^2.0"
    }
}

Quick Installation

Above installation can also be simplify by using the following command:

composer require "php-http/guzzle6-adapter" "katsana/insurance-sdk-php=^0.2"

HTTP Adapter

Instead of utilizing php-http/guzzle6-adapter you might want to use any other adapter that implements php-http/client-implementation. Check Clients & Adapters for PHP-HTTP.

Getting Started

Creating Client

You can start by creating a client by using the following code (which uses php-http/guzzle6-adapter and php-http/discovery to automatically pick available adapter installed via composer):

<?php

use Katsana\Insurance\Client;

$sdk = Client::make('client-id', 'client-secret');

Authenticate Using Client Credential Grant

Once you initiate the client, you need to get an Access Token before using the services. All you need to do is:

$passport = $sdk->authenticate();

$accessToken = $passport->toArray()['access_token'];

$sdk->setAccessToken($accessToken); // The `authenticate` method does this automatically.

Additionally, if you already have an Access Token, you can initiate a client with existing Access Token. You can initiate the client using the following code:

<?php

use Katsana\Insurance\Client;

$sdk = Client::fromAccessToken('access-token');

Handling Response

Every API request using the API would return an instance of Katsana\Insurance\Response which can fallback to \Psr\Http\Message\ResponseInterface, this allow developer to further inspect the response.

As an example:

$response = $sdk->uses('Insurer')->all();

var_dump($response->toArray());

Getting the Response

You can get the raw response using the following:

$response->getBody();

However we also create a method to parse the return JSON string to array.

$response->toArray();

Checking the Response HTTP Status

You can get the response status code via:

$response->getStatusCode();

$response->isSuccessful();

$response->isUnauthorized();

Checking the Response Header

You can also check the response header via the following code:

$response->getHeaders(); // get all headers as array.
$response->hasHeader('Content-Type'); // check if `Content-Type` header exist.
$response->getHeader('Content-Type'); // get `Content-Type` header.

Using the API

There are two way to request an API:

Using API Resolver

This method allow you as the developer to automatically select the current selected API version without having to modify the code when KATSANA release new API version.

$insurer = $sdk->uses('Insurer'); 

$response = $insurer->all();

This would resolve an instance of Katsana\Insurance\One\Insurer class (as v1 would resolve to One namespace).

Explicit API Resolver

This method allow you to have more control on which version to be used.

$insurer = $sdk->via(new Katsana\Insurance\One\Insurer());

$response = $insurer->all();

Usages

Get List of Insurers

Use this API to get a complete list of available Insurers.

Code Example

$insurer = $sdk->uses('Insurer');

$response = $insurer->all();

var_dump($response->toArray());

Response Parameters

Parameters	Type	Description
`country_code`	string	The country code, e.g: `MY`
`name`	string	Insurer name
`partner`	boolean	Whether we can make renewal
`product_code`	string\|null	Product code

Response Sample

{
  "data": [
    {
      "country_code": "MY",
      "name": "RHB Insurance",
      "partner": false,
      "product_code": null
    },
    {
      "country_code": "MY",
      "name": "Allianz Malaysia Berhad",
      "partner": true,
      "product_code": null
    },
    {
      "country_code": "MY",
      "name": "Takaful Ikhlas",
      "partner": false,
      "product_code": null
    }
  ]
}

Create Draft Quotation

Use this API to create a motor insurance renewal quotation draft.

Code Example

$quotation = $sdk->uses('Quotation');

$response = $quotation->draft(
  $plateNumber,
  $insurerCode,
  $ownerInformation,
  $vehicleInformation,
  $sumCovered,
  $addons
);

var_dump($response->toArray());

Request Parameters

Parameter	Type	Rule	Description
`$plateNumber`	string	required	The vehicle license plate.
`$insurerCode`	string	required	Insurer's Product Code.
`$ownerInformation['fullname']`	string	required	Driver's fullname.
`$ownerInformation['birthdate']`	string	required	Driver's birth date in `Y-m-d` format.
`$ownerInformation['email']`	string	required	Driver's e-mail address.
`$ownerInformation['nric']`	string	required	Driver's National Registration Identity Card (NRIC) ID.
`$ownerInformation['phone_no']`	string	required	Driver's phone number.
`$ownerInformation['postcode']`	string	required	Driver's current address postcode.
`$insuranceInformation['ended_at']`	string	required	Current vehicle insurance expiry date in `Y-m-d` format.
`$vehicleInformation['maker']`	string	optional	Vehicle's maker. E.g `Proton`, `Perodua`, `Honda` etc.
`$vehicleInformation['model']`	string	optional	Vehicle's maker. E.g `Iriz`, `Persona`, `MyVi`, `Civic`, `Vios` etc.
`$vehicleInformation['year_manufactured']`	integer	optional	Vehicle's year of manufactured.
`$vehicleInformation['chasis_number']`	string	optional	Vehicle's chassis number.
`$vehicleInformation['engine_number']`	string	optional	Vehicle's engine number.
`$sumCovered`	float	optional	Total sum covered for the vehicle in `MYR`.
`$addons['windscreen']`	float	optional	Total covered for windscreen coverage.
`$addons['flood']`	boolean	optional	Enable basic flood coverage.
`$addons['extended_flood']`	boolean	optional	Enable extended flood coverage.
`$addons['under_repair_compensation']`	boolean	optional	...
`$addons['passenger_negligence_liability']`	boolean	optional	...

Response Example

{
  "data": {
    "status": "pending",
    "ends_at": "2020-06-09 00:00:00",
    "starts_at": "2019-06-09 00:00:00",
    "expires_at": "2019-06-23 10:33:07",
    "insurer_code": "MI",
    "quotation": {
      "options": {
        "addons": {
          "windscreen": []
        },
        "sum_covered": []
      },
      "proposed": {
        "addons": [],
        "amount": {
          "ncd": 529.71,
          "sst": 23.4,
          "total": 423.46,
          "rebate": 43.34,
          "cashback": 0,
          "after_tax": 413.46,
          "before_tax": 390.06
        },
        "sum_covered": 25000,
        "contribution": {
          "basic": 963.1,
          "gross": 433.4,
          "total": 423.46,
          "after_rebate": 390.06
        }
      },
      "discounts": {
        "addons": {
          "flood": {
            "rules": [
              {
                "if": "addon",
                "is": "windscreen",
                "min_value": 1
              }
            ],
            "discount_percent": 0
          },
          "extended_flood": {
            "rules": [
              {
                "if": "addon",
                "is": "windscreen",
                "min_value": 1
              }
            ],
            "discount_percent":0
          }
        },
        "sum_covered": []
      },
      "stamp_duty": 10,
      "ncd_percent": 55,
      "sst_percent": 6,
      "sum_covered": {
        "max": 30000,
        "min": 20000
      },
      "rebate_percent": 10,
      "cashback_percent": 0
    }
  }
}

Update Quotation

Use this API to update draft quotation for motor insurance renewal.

Code Example

$quotation = $sdk->uses('Quotation');

$response = $quotation->update(
  $plateNumber,
  $insurerCode,
  $sumCovered,
  $addons
)

Request Parameters

Parameter	Type	Rule	Description
`$plateNumber`	string	required	The vehicle license plate.
`$insurerCode`	string	required	Insurer's Product Code.
`$sumCovered`	float	required	Total sum covered for the vehicle in `MYR`.
`$addons['windscreen']`	float	optional	Total covered for windscreen coverage.
`$addons['flood']`	boolean	optional	Enable basic flood coverage.
`$addons['extended_flood']`	boolean	optional	Enable extended flood coverage.
`$addons['under_repair_compensation']`	boolean	optional	...
`$addons['passenger_negligence_liability']`	boolean	optional	...

Response Example

{
  "data": {
    "status": "pending",
    "ends_at": "2020-06-09 00:00:00",
    "starts_at": "2019-06-09 00:00:00",
    "expires_at": "2019-07-08 00:00:00",
    "insurer_code": "MI",
    "quotation": {
      "options": {
        "addons": {
          "windscreen": []
        },
        "sum_covered": []
      },
      "proposed": {
        "addons": [],
        "amount": {
          "ncd": 601.21,
          "sst": 26.56,
          "total": 479.27,
          "rebate": 49.19,
          "cashback": 0,
          "after_tax": 469.27,
          "before_tax": 442.71
        },
        "sum_covered": 30000,
        "contribution": {
          "basic": 1093.1,
          "gross": 491.9,
          "total": 479.27,
          "after_rebate": 442.71
        }
      },
      "discounts": {
        "addons": {
          "flood": {
            "rules": [
              {
                "if": "addon",
                "is": "windscreen",
                "min_value": 1
              }
            ],
            "discount_percent": 0
          },
          "extended_flood": {
            "rules": [
              {
                "if": "addon",
                "is": "windscreen",
                "min_value": 1
              }
            ],
            "discount_percent": 0
          }
        },
        "sum_covered": []
      },
      "stamp_duty": 10,
      "ncd_percent": 55,
      "sst_percent": 6,
      "sum_covered": {
        "max": 30000,
        "min": 20000
      },
      "rebate_percent": 10,
      "cashback_percent": 0
    }
  }
}

Save Vehicle Information

Use this API to store and update Vehicle information.

Code Example

$vehicles = $sdk->uses('Vehicle');

$response = $sdk->save(
  $plateNumber,
  $ownerInformation,
  $insuranceInformation,
  $vehicleInformation
);

var_dump($response->toArray());

Request Parameters

Parameter	Type	Rule	Description
`$plateNumber`	string	required	The vehicle license plate.
`$ownerInformation['fullname']`	string	required	Driver's fullname.
`$ownerInformation['birthdate']`	string	required	Driver's birth date in `Y-m-d` format.
`$ownerInformation['email']`	string	required	Driver's e-mail address.
`$ownerInformation['nric']`	string	required	Driver's National Registration Identity Card (NRIC) ID.
`$ownerInformation['phone_no']`	string	required	Driver's phone number.
`$ownerInformation['postcode']`	string	required	Driver's current address postcode.
`$insuranceInformation['ended_at']`	string	required	Current vehicle insurance expiry date in `Y-m-d` format.
`$vehicleInformation['maker']`	string	required	Vehicle's maker. E.g `Proton`, `Perodua`, `Honda` etc.
`$vehicleInformation['model']`	string	required	Vehicle's maker. E.g `Iriz`, `Persona`, `MyVi`, `Civic`, `Vios` etc.
`$vehicleInformation['year_manufactured']`	integer	required	Vehicle's year of manufactured.
`$vehicleInformation['chasis_number']`	string	optional	Vehicle's chassis number.
`$vehicleInformation['engine_number']`	string	optional	Vehicle's engine number.

Response Example

{
  "data": {
    "plate_number": "ABC123",
    "maker": "Proton",
    "model": "Iriz",
    "variant": null,
    "year_manufactured": 2018,
    "chasis_no": null,
    "engine_no": null,
    "customer": {
      "data": {
        "fullname": "Ali bin Abu",
        "email": "ali@katasanalabs.com",
        "ic": "880102030405",
        "ic_type": "nric",
        "marital": null,
        "birthdate": "1988-01-02",
        "phone_no": "60123456789",
        "line1": null,
        "line2": null,
        "line3": null,
        "postcode": "47150",
        "city": null,
        "state": null,
        "country": null
      }
    }
  }
}

Make Payment

Use this API to make a payment for Insurance Renewal.

Code Example

$renewal = $sdk->uses('Renewal');

$response = $renewal->pay(
  $plateNumber, 
  $insurerCode, 
  $sumCovered, 
  $addons,
  $declaration
]);

var_dump($response->toArray());

Request Parameters

Parameter	Type	Rule	Description
`$plateNumber`	string	required	The vehicle license plate.
`$insurerCode`	string	required	Insurer's Product Code.
`$sumCovered`	float	required	Total sum covered for the vehicle in `MYR`.
`$addons['windscreen']`	float	optional	Total covered for windscreen coverage.
`$addons['flood']`	boolean	optional	Enable basic flood coverage.
`$addons['extended_flood']`	boolean	optional	Enable extended flood coverage.
`$addons['under_repair_compensation']`	boolean	optional	...
`$addons['passenger_negligence_liability']`	boolean	optional	...
`$declaration['pds']`	boolean	required	...
`$declaration['ind']`	boolean	required	...
`$declaration['pdpa']`	boolean	required	Required to be `true` to indicate user has agree to Insurance Renewal PDPA.
`$declaration['lapse']`	boolean	optional	Required to be `true` only if insurance has been expired but within the 90 days lapse duration!

Insurance renewal is not available for insurance that has been expired over 90 days!

Response Example

{
  "data": {
    "options": {
      "addons": {
        "windscreen": []
      },
      "sum_covered": []
    },
    "proposed": {
      "addons": [],
      "amount": {
        "ncd": 601.21,
        "sst": 26.56,
        "total": 479.27,
        "rebate": 49.19,
        "cashback": 0,
        "after_tax": 469.27,
        "before_tax": 442.71
      },
      "sum_covered": 30000,
      "contribution": {
        "basic": 1093.1,
        "gross": 491.9,
        "total": 479.27,
        "after_rebate": 442.71
      }
    },
    "discounts": {
      "addons": {
        "flood": {
          "rules": [
            {
              "if": "addon",
              "is": "windscreen","min_value":1
            }
          ],
          "discount_percent":0
        },
        "extended_flood": {
          "rules": [
            {
              "if": "addon",
              "is": "windscreen",
              "min_value": 1
            }
          ],
          "discount_percent": 0
        }
      },
      "sum_covered": []
    },
    "stamp_duty": 10,
    "ncd_percent": 55,
    "sst_percent": 6,
    "sum_covered": {
      "max": 30000,
      "min": 20000
    },
    "rebate_percent": 10,
    "cashback_percent": 0,
    "pay_url": "https:\/\/insure-staging.katsanalabs.com\/public\/payments\/1",
    "completion_url": "https:\/\/insure-staging.katsanalabs.com\/public\/payments\/complete"
  }
}

Notes:

pay_url is the URL user must be redirected to, to start payment process.
Once user has completed payment, they will be redirected to completion_url. Mobile application can listen to this URL to detect end of payment process.

katsana / insurance-sdk-php

Maintainers

Details

README

Installation

Quick Installation

HTTP Adapter

Getting Started

Creating Client

Authenticate Using Client Credential Grant

Handling Response

Getting the Response

Checking the Response HTTP Status

Checking the Response Header

Using the API

Using API Resolver

Explicit API Resolver

Usages

Get List of Insurers

Code Example

Response Parameters

Response Sample

Create Draft Quotation

Code Example

Request Parameters

Response Example

Update Quotation

Code Example

Request Parameters

Response Example

Save Vehicle Information

Code Example

Request Parameters

Response Example

Make Payment

Code Example

Request Parameters

Response Example

Notes: