katsana/insurance-sdk-php

KATSANA Insurance Renewal SDK for PHP

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

Requires

• php: >=7.1
• laravie/codex: ^4.0 || ^5.0
• laravie/codex-security: ^1.0.1

Requires (Dev)

• fzaninotto/faker: ^1.9
• mockery/mockery: ^1.2
• nesbot/carbon: ^1.26.3 || ^2.0
• php-http/curl-client: ^1.7 || ^2.0
• phpunit/phpunit: ^7.5 || ^8.0

BSD-3-Clause

• KATSANA Developer

README

• Installation
• Getting Started
  • Creating Client
  • Handling Response
  • Using the API
• Usages
  • Get List of Insurers
  • Create Draft Quotation
  • Update Quotation
  • Save Vehicle Information
  • Make Payment

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

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

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

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

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": "[e-mail]",
        "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

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.