nasrulhazim/billplz

PHP Agnostic library for working with BillPlz API

Monday, April 30, 2018
by nasrulhazim.m
Repository
1 Watchers
0 Stars
27 Installations

PHP
0 Dependents
0 Suggesters
11 Forks
0 Open issues
43 Versions
0 % Grown

The README.md

PHP framework agnostic library for working with BillPlz API v3 and beyond...

, _(*1)

Installation
Usages
Handling Response
- Checking the Response HTTP Status
- Checking the Response Header

Installation

To install through composer, simply put the following in your composer.json file:, _(*2)

{
    "require": {
        "jomweb/billplz": "^1.0",
        "php-http/guzzle6-adapter": "^1.1"
    }
}

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., _(*3)

Usages

Creating Billplz Client

You can start by creating a Billplz client by using the following code (which uses php-http/guzzle6-adapter):, _(*4)

<?php

use Billplz\Client;
use Http\Client\Common\HttpMethodsClient;
use Http\Adapter\Guzzle6\Client as GuzzleHttpClient;
use Http\Message\MessageFactory\GuzzleMessageFactory;

$http = new HttpMethodsClient(
    new GuzzleHttpClient(),
    new GuzzleMessageFactory()
);


$billplz = new Client($http, 'your-api-key');

You could also use php-http/discovery to automatically pick available adapter installed via composer:, _(*5)

<?php

use Billplz\Client;

$billplz = Client::make('your-api-key');

Using Sandbox

You can set to use development/sandbox environment by adding the following code:, _(*6)

$billplz->useSandbox();

Using different API Version

By default jomweb/billplz would use v3 API version for any request, however you can customize this in future when new API version is available., _(*7)

$billplz->useVersion('v4');

Creating Collection Request

Now you can create an instance of Collection:, _(*8)

$collection = $billplz->collection();

You can also manually set the API version by doing $billplz->collection('v3');. You can also use $billplz->resource('Collection'); to get the same result., _(*9)

Create a Collection

You can add a new collection by calling the following code:, _(*10)

$response = $collection->create('My First API Collection');

var_dump($response->toArray());

return [
    "id" => "inbmmepb",
    "title" => "My First API Collection",
    "logo" => [
        "thumb_url" => null,
        "avatar_url" => null
    ],
    "split_payment" => [
        "email" => null,
        "fixed_cut" => null,
        "variable_cut" => null
    ]
];

You can also create new collection with optional parameters:, _(*11)

$response = $collection->create('My First API Collection', [
    'logo' => '@/Users/Billplz/Documents/uploadPhoto.png',
    'split_payment' => [
        'email' => 'verified@account.com',
        'fixed_cut' => \Money\Money::MYR(100),
    ],
]);

var_dump($response->toArray());

return [
    "id" => "inbmmepb",
    "title" => "My First API Collection",
    "logo" => [
        "thumb_url" => "https://sample.net/assets/uploadPhoto.png",
        "avatar_url" => "https://sample.net/assets/uploadPhoto.png"
    ],
    "split_payment" => [
        "email" => "verified@account.com",
        "fixed_cut" => \Money\Money::MYR(100),
        "variable_cut" => null
    ]
]

Create an Open Collection

$response = $collection->createOpen(
    'My First API Collection',
    'Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.',
    Money\Money::MYR(299)
);

var_dump($response->toArray());

return [
    "id" => "0pp87t_6",
    "title" => "MY FIRST API OPEN COLLECTION",
    "description" => "Maecenas eu placerat ante. Fusce ut neque justo, et aliquet enim. In hac habitasse platea dictumst.",
    "reference_1_label" => null,
    "reference_2_label" => null,
    "email_link" => null,
    "amount" => \Money\Money::MYR(299),
    "fixed_amount" => true,
    "tax" => null,
    "fixed_quantity" => true,
    "payment_button" => "pay",
    "photo" => [
        "retina_url" =>  null,
        "avatar_url" =>  null
    ],
        "split_payment" => [
        "email" => null,
        "fixed_cut" => null,
        "variable_cut" => null
    ],
    "url" => "https://www.billplz.com/0pp87t_6"
]

Creating Bill Request

Now you can create an instance of Bill:, _(*12)

$bill = $billplz->bill();

You can also manually set the API version by doing $billplz->bill('v3');. You can also use $billplz->resource('Bill'); to get the same result., _(*13)

Create a Bill

You can add a new bill by calling the following code:, _(*14)

$response = $bill->create(
    'inbmmepb',
    'api@billplz.com',
    null,
    'Michael API V3',
    Money\Money::MYR(200),
    'http://example.com/webhook/',
    'Maecenas eu placerat ante.'
);

var_dump($response->toArray());

return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "overdue",
    "amount" => \Money\Money::MYR(200),
    "paid_amount" => \Money\Money::MYR(0),
    "due_at" => \DateTime::createFromFormat('Y-m-d', "2015-3-9"),
    "email" => "api@billplz.com",
    "mobile" => null,
    "name" => "MICHAEL API V3",
    "url" => "https://www.billplz.com/bills/8X0Iyzaw",
    "reference_1_label" => "Reference 1",
    "reference_1" => null,
    "reference_2_label" => "Reference 2",
    "reference_2" => null,
    "redirect_url" => null,
    "callback_url" => "http://example.com/webhook/",
    "description" => "Maecenas eu placerat ante."
];

Payment Completion

You can setup a webhook to receive POST request from Billplz. In order to accept the response all you to do is write the following., _(*15)

$data = $billplz->webhook($_POST);

return [
    'id' => 'W_79pJDk',
    'collection_id' => 'inbmmepb',
    'paid' => true,
    'state' => 'paid',
    'amount' => \Money\Money::MYR(200),
    'paid_amount' => \Money\Money::MYR(0),
    'due_at' => \Carbon\Carbon::parse('2020-12-31'),
    'email' => 'api@billplz.com',
    'mobile' => '+60112223333',
    'name' => 'MICHAEL API',
    'metadata' => [
        'id' => 9999,
        'description' => 'This is to test bill creation',
    ],
    'url' => 'https://billplz.dev/bills/W_79pJDk',
    'paid_at' => \Carbon\Carbon::parse('2015-03-09 16:23:59 +0800'),
];

Get a Bill

$response = $bill->show('8X0Iyzaw');

var_dump($response->toArray());

return [
    "id" => "8X0Iyzaw",
    "collection_id" => "inbmmepb",
    "paid" => false,
    "state" => "due",
    "amount" => \Money\Money::MYR(200),
    "paid_amount" => \Money\Money::MYR(0),
    "due_at" => \Carbon\Carbon::parse("2020-12-31"),
    "email" => "api@billplz.com",
    "mobile" => "+60112223333",
    "name" => "MICHAEL API V3",
    "url" => "https://www.billplz.com/bills/8X0Iyzaw",
    "reference_1_label" => "First Name",
    "reference_1" => "Jordan",
    "reference_2_label" => "Last Name",
    "reference_2" => "Michael",
    "redirect_url" => "http://example.com/redirect/",
    "callback_url" => "http://example.com/webhook/",
    "description" => "Maecenas eu placerat ante."
]

Delete a Bill

$response = $bill->destroy('8X0Iyzaw');

var_dump($response->toArray());

[]

Creating Transaction Request

Now you can create an instance of Transaction:, _(*16)

$transaction = $billplz->transaction();

You can also manually set the API version by doing $billplz->transaction('v3');. You can also use $billplz->resource('Bill.Transaction'); to get the same result., _(*17)

Get Transaction Index

You can get Transaction index by calling following code:, _(*18)

$response = $transaction->show('inbmmepb');

var_dump($response->toArray());

return [
    "bill_id" => "inbmmepb"
    "transactions" => [
        [
            "id": "60793D4707CD",
            "status": "completed",
            "completed_at": "2017-02-23T12:49:23.612+08:00",
            "payment_channel": "FPX"
        ],
        [
            "id" => "28F3D3194138",
            "status" => "failed",
            "completed_at" => ,
            "payment_channel" => "FPX"
        ]
    ],
    "page" => 1
]

You also can provide optional parameters (page, status):, _(*19)

$response = $transaction->show('8X0Iyzaw', [
    'page' => 1,
    'status' => 'completed'
]);

var_dump($response->toArray());

return [
    "bill_id" => "8X0Iyzaw"
    "transactions" => [
        [
            "id" => "60793D4707CD",
            "status" => "completed",
            "completed_at" => "2017-02-23T12:49:23.612+08:00",
            "payment_channel" => "FPX"
        ]
    ],
    "page" => 1
]

Creating Bank Request

Now you can create an instance of Bank:, _(*20)

$bank = $billplz->bank();

You can also manually set the API version by doing $billplz->bank('v3');. You can also use $billplz->resource('Bank'); to get the same result., _(*21)

Check Bank Account Registration Status

At any given time, you can request to check on a registration status by bank account number., _(*22)

$response = $bank->checkAccount('1234567890');

var_dump($response->toArray());

return [
    "name" => "verified"
]

Get FPX Banks List

If you want to use Bank Direct Feature in Billplz, you need list of FPX Banks to send in create bill request., _(*23)

You can get supported bank for FPX by calling following code:, _(*24)

$list = $bank->supportedForFpx();

var_dump($list->toArray());

return [
    "banks" => [
        [
            "name" => "PBB0233",
            "active" => true,
        ],
        [
            "name" => "MBB0227",
            "active" => true,
        ],
        [
            "name" => "MBB0228",
            "active" => true,
        ],
    ],
];

Note: You will hit 401, Invalid access error if you have not enabled Bank Direct by Billplz. Contact Billplz for information., _(*25)

Handling Response

Every request made to Billplz would return \Laravie\Codex\Response which can fallback to \Psr\Http\Message\ResponseInterface which would allow developer to further inspect the response., _(*26)

Getting the Response

You can get the raw response using the following:, _(*27)

$response->getBody();

However we also create a method to parse the return JSON string to array., _(*28)

$response->toArray();

Checking the Response HTTP Status

You can get the response status code via:, _(*29)

if ($response->getStatusCode() !== 200) {
    throw new SomethingHasGoneReallyBadException();
}

Checking the Response Header

You can also check the response header via the following code:, _(*30)

$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.

The Versions

30/04 2018

1.3.x-dev

1.3.9999999.9999999-dev

PHP Agnostic library for working with BillPlz API

library billplz

PHP Agnostic library for working with BillPlz API

nasrulhazim/billplz

The README.md

PHP framework agnostic library for working with BillPlz API v3 and beyond...

Installation

HTTP Adapter

Usages

Creating Billplz Client

Using Sandbox

Using different API Version

Creating Collection Request

Create a Collection

Create an Open Collection

Creating Bill Request

Create a Bill

Payment Completion

Get a Bill

Delete a Bill

Creating Transaction Request

Get Transaction Index

Creating Bank Request

Check Bank Account Registration Status

Get FPX Banks List

Handling Response

Getting the Response

Checking the Response HTTP Status

Checking the Response Header

The Versions

1.3.x-dev

The Requires

The Development Requires

by Mior Muhammad Zaki

dev-develop

The Requires

The Development Requires

by Mior Muhammad Zaki

dev-master

The Requires

The Development Requires

by Nasrul Hazim

by Mior Muhammad Zaki

1.1.x-dev

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.1.1

The Requires

The Development Requires

by Mior Muhammad Zaki

1.0.x-dev

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.0.7

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.1.0

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.0.6

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.0.5

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.0.4

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.0.3

The Requires

The Development Requires

by Mior Muhammad Zaki

v1.0.2

The Requires