katsana/insurance-sdk-php

KATSANA Insurance Renewal SDK for PHP

v0.2.0 2019-11-16 01:50 UTC

This package is auto-updated.

Last update: 2020-01-07 04:35:48 UTC


README

Build Status Latest Stable Version Total Downloads Latest Unstable Version License Coverage Status

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.