katsana / insurance-sdk-php
KATSANA Insurance Renewal SDK for PHP
Installs: 8 591
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 11
Forks: 0
Open Issues: 0
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
README
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 (asv1
would resolve toOne
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": "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
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.