Download the PHP package mazimez/laravel-gigapay without Composer

Laravel-Gigapay

A simple API wrapper for Gigapay's APIs. It gives you helper methods that will make your work with gigapay's API easy, fast and efficient

Laravel-Gigapay manage resources like Employees, Invoices, Payouts, Pricing and Webhooks.

It uses the APIs provided by Gigapay, here is it's API documentation

You can also look into the postman collection to call the API by yourself to better understand it.

To understand the Event flow of Gigapay, you can see it's Event Documentation

Table of contents

• Installation
• Configuration
• Employee
  • List
  • Creation
  • Retrieve single
  • Update
  • Replace
  • Delete
  • Resend Invite
  • Helpers
• Payout
  • List
  • Creation
  • Multiple Creation
  • Creation with inline Employee
  • Retrieve single
  • Delete
  • Resend
  • Helpers
• Invoice
  • List
  • Retrieve single
  • Update
  • Delete
• Pricing
  • List
  • Retrieve single
  • Calculate Pricing
  • Calculate Bulk
• Webhook
  • Set-up
  • List
  • Creation
  • Retrieve single
  • Update
  • Replace
  • Delete
• ListResource
  • Pagination
  • Search
  • Expand Resources
  • Add Filter
  • Get JSON data
• Exception Handling
  • Gigapay Exception

Installation

Install the package via composer:

composer require mazimez/laravel-gigapay

Publish the config file:

php artisan vendor:publish --provider="Mazimez\Gigapay\GigapayServiceProvider"

Configuration

The published config file config/gigapay.php looks like:

once the config file is ready, you need to add some variables into your .env file. there are 4 variables

• GIGAPAY_TOKEN = You will get this token from your gigapay account
• GIGAPAY_INTEGRATION_ID = You can get this id from your gigapay account or from Gigapay's API
• GIGAPAY_SERVER_URL = gigapay has 2 servers, demo and production. both's server's URL can be found on Gigapay's documentation
• GIGAPAY_LANG = the language in which Gigapay will give it's responses or errors

keep in mind that Gigapay has separate token and integration id for each server, so whenever you switch server, remember to update SERVER URL with tokens and integration id too.

Employee

An Employee is an individual performing tasks within your organization, employed or sub-contracted by Gigapay. To add an Employee to your organization you can create an Employee object. The Employee will be notified and Gigapay will verify their identity and working permits. you can learn more about that from Gigapay doc

employee-creation

• To create an Employee, you need it's name and either email or cellphone_number other data are not mandatory.
• you can create Employee with create method by passing all the data as arguments and you can also use createByArray method which takes and array with the same data, in that you only need to add the data that's required.
• the metadata is a Json object so remember to use json_encode() method.
• you can get more info about employee's object from Gigapay doc

the getJson() method will return the Employee's object in JSON format

employee-update

• Employee resource can be updated any time, the data that can be updated are id, name, email, country, cellphone_number, metadata.
• each data can be updated by calling separate method and also by updating the values on employee object and then calling save() method to update the whole employee object.
• remember to use json_encode() before saving the metadata
• also, to update the ID of employee, please use the septate method updateId() instead of save(), since save() will try to update the employee with current id(new id that doesn't exists in Gigapay's Database)
• the rules about uniqueness and format still applies here. you can get for info from Gigapay doc

employee-list

The Employee::list() method will return the Gigapay doc

employee-retrieve

You can retrieve any employee by it's id. you can get more info from Gigapay doc

employee-replace

Replacing any Employee will actually change the ID of that employee as well as all the data of that employee with the data you have provided. keep in mind that other connect with this employee (like it's payouts) will still stay connected to it. so here you are not creating a new employee, you can just replace an existing employee with new data. refer to Gigapay doc for more info.

employee-delete

You can delete any employee by calling the destroy method on Employee instance but we can not delete an Employee after a Payout has been registered to it. get for info from Gigapay doc

employee-resend

Employee will get 1 email to join, on the mail-id that we provided while creating the Employee, we can also resend that mail in case something gets wrong. After resending, you need to wait at least 24 hours before resending again. get for info from Gigapay doc

employee-helper

There are some helper methods that you can use on employee instance. for example:

• getAllPayouts() that will return the ListResource for Payouts on that Employee.

Payout

To make a payout to an Employee you need to create a Payout object. The Employee is notified of the Payout once the corresponding Invoice is paid. The Employee will need to sign and accept the Payout before it is disbursed to their account. you can learn more about that from Gigapay doc

payout-creation

• To create an Payout, you either need it's amount or invoiced_amount or cost, anyone one of these data is required.
• also you need to add Employee id and description for that payout. also employee needs to be verified before you start paying him/her salaries(amount).
• just like Employee resource, Payout also have 2 methods for creation. create method takes data in Arguments while createByArray takes data as an Array.
• while providing metadata, remember to use json_encode() method.
• you can get more info about Payout's pricing from Gigapay doc

the getJson() method will return the Payout's object in JSON format

payout-inline-creation

• Gigapay also provides API to create payouts and employee all together.
• while creating new Payout and Employee togher, it's important to note that you should use invoiced_amount since other type of filed like cost and amount needs employee to be verified and since it's new Employee, it wont be verified at that point.
• if you are using this API with some existing Employee then you can use cost and amount too, it wont create new Employee but just merge it with the given data.
• the arguments for this method is almost same as normal create method, only change is that now instead of employee-id, you need to pass an array with info like Employee email and name etc.
• you can get more info from Gigapay doc
• thanks @rolandlluka for suggesting this method and adding a pull-request for it. I hope you will be suggesting more improvements too😅

payout-multiple-creation

• Gigapay also provides API to create multiple payouts at once
• All of this payouts will be added to the same Invoice object.
• it takes an array(json) in the payout object structure.
• you need to at least provide employee-id, description and either one from amount , cost , invoice_amount. other things are not required.
• you can create payout to different employees all together.
• you can get more info from Gigapay doc

payout-list

The Payout::list() method will return the Gigapay doc

payout-retrieve

You can retrieve any payout by it's id. you can get more info from Gigapay doc

payout-delete

You can delete any payout by calling the destroy method on Payout instance but we can not delete a payout belonging to a paid Invoice or an Invoice on credit. get more info from Gigapay doc

payout-resend

Once the Payout is been paid, Employee should get the mail about his/her payout. you can also resend the mail using the resend() method on payout instance. keep in mind that mail can only be sent once the Payout has been paid. get more info from Gigapay doc

payout-helper

There are some helper methods that you can use on payout instance. for example:

• expandInvoice() this method will expand the invoice field on payout and gives the whole invoice's JSON data.
• expandEmployee() this method will expand the employee field on payout and gives the whole employee's JSON data.

you can also chain this method on same Payout instance

invoice

An Invoice groups Payouts together. It is a managed object, you can not create them directly. When a Payout is created it is added to the Invoice that is currently open. If there is no open Invoice, a new will be created. you can learn more about that from Gigapay doc

invoice-list

The Invoice::list() method will return the Gigapay doc

invoice-retrieve

You can retrieve any invoice by it's id. you can get more info from Gigapay doc

invoice-update

• The only fields that can be updated in invoice resource are id and metadata.
• just like Employee, they have the separate method for that and also a save() method that will update the whole instance with Gigapay
• To update the ID of invoice, please use the septate method updateId() instead of save(), since save() will try to update the invoice with current id(new id that doesn't exists in Gigapay's Database)

invoice-delete

You can delete any invoice by calling the destroy method on invoice instance but we can not delete a paid Invoice or an Invoice on credit. get for info from Gigapay doc

Pricing

• The Pricing Resource allows you to calculate the price of payout you would like to make, and to retrieve the price information about previously made payouts. The Resource is designed to mirror the Payouts Resource as closely as possible, e.g. the same request can be used to retrieve the price information of a Payout you'd like to make and to actually make it.
• Either amount, invoiced_amount or cost is used as a basis for calculating the Pricing breakdown.
• One is provided and the other are calculated based on that. Their definitions are:
  1. amount: net amount paid out plus obligations paid by the recipient.
  2. invoiced_amount: amount plus obligations paid by the employer.
  3. cost: invoiced_amount plus Gigapay's fee. This is the final amount you end up paying.

     Pricing-List

     The Pricing::list() method will return the Gigapay doc

Pricing-Retrieve

You can retrieve any payout's Pricing info by payout's id. you can get more info from Gigapay doc

Pricing-Calculate

• Pricing resource mainly helps you calculating the payouts before actually making it. you can use Pricing::calculatePricing method to calculate any payout without actually making it.
• while calculating pricing, you need to give employee_id as well as the amount that you want to pay, you can give either the amount or cost or invoiced_amount according to your need.

pricing-calculate-bulk

• Gigapay also provides API to calculate the payout in bulk(multiple payouts at once)
• it takes an array(json) in the payout object structure.
• you need to at least provide employee-id, and either one from amount , cost , invoice_amount. other things are not required (description is also not required).
• the you can calculate pricing for different employees all together.
• you can get more info from Gigapay doc

Webhook

• Webhooks allows you to receive real-time status updates any time an event happens on your gigapay account. basically it sends you the data of the resource on which the Action is performed.
• there are total of 9 events, you can get more information from Gigapay doc
• laravel-gigapay provides a simple way to handle all this Webhooks by Laravel event. laravel-gigapay can fire an Event whenever any Webhook sends the data. and then you can listen to this events by Listeners

  webhook-setup

• In order to receive the webhooks and Use the Listeners, you need to first set-up some things in you Laravel project.
  1. App URL : first you need to set the APP_URL in you .env file if it's not already set since this URL will be used to register the webhooks.

2. Event Discovery : in order for your Listeners to directly discover the Events from larave-gigapay. you need to enable the Auto discovery.
   • you can do that by going to your project's EventServiceProvider and change the method shouldDiscoverEvents to return true.

• If you don't want auto discovery to be enabled(or your Laravel version does not support auto discovery) then you can also manually add those Listeners into the $listen array.

3. Command gigapay:webhook: laravel-gigapay provides the command that will register all the webhooks with the APP_URL and it also has a route that will receive this webhooks and fire the events. so once you run this command with artisan you webhooks will get registered

php artisan gigapay:webhook

• once this steps are done, your webhooks for Gigapay are set-up. now you only need to add the listeners that can listen to this webhook's event.

• here is one example of the Listener that will listen to the event of Employee.created

• In the above example, the EmployeeCreatedListener is listening to the event of EmployeeCreated in it's handle method.
• In the handle method, you will get the instance of EmployeeCreated event on which you can call the method getResource that will give you the resource thats related to this event.
• The getResource method can return different resource based on the events. it can be Employee,Payout or Invoice.
• once you got the resource you can use that to update your system.
• since there are total 9 webhooks, there is total 9 different events. you can get that events list from config file of gigapay.php as events_list.
• you have to create 9 different listeners just like above to handle different webhook's events.

webhook-list

The Webhook::list() method will return the Gigapay doc

webhook-creation

• If you want to configure the Gigapay webhooks in other way then Laravel event. then you can also use the create and createByArray method just like you can do on other resources.
• while creating webhooks, only url and events fields are required.

webhook-retrieve

You can retrieve any webhook by it's id. you can get more info from Gigapay doc

webhook-update

• Webhook resource can be updated any time, the data that can be updated are id, url, event, metadata ,secret_key.
• each data can be updated by calling separate method and also by updating the values on employee object and then calling save() method to update the whole employee object.
• remember to use json_encode() before saving the metadata
• also remember that events as to be a string while saving, not in array.
• also, to update the ID of employee, please use the septate method updateId() instead of save(), since save() will try to update the webhook with current id(new id that doesn't exists in Gigapay's Database)
• the rules about uniqueness and format still applies here. you can get for info from Gigapay doc

webhook-replace

similar to employee, webhook can also be replaced. this will update the ID of webhook too. you can get more info from Gigapay doc.

webhook-delete

You can delete any webhook by calling the destroy method on Webhook instance. get for info from Gigapay doc

ListResource

This is the class that provides you with some helper methods to get the list of Any resource from Gigapay. The methods that you can use is:

paginate

This will add the parameter for pagination into Gigapay's APIs. it take 2 parameter, page and page_size. you can directly chain this method on any ListResource instance, you can also refer the Gigapay doc for this.

search

This will add the parameter for searching into Gigapay's APIs. it take 1 parameter, search. you can directly chain this method on any ListResource instance.

expand

This will add the parameter to expand any resource, for example a Payout has an associated Employee identifier. Those objects can be expanded

you can also expand multiple resource just by chaining the expand method. you can also refer the Gigapay doc for this.

addFilter

This will add the parameter for filtering regarding timestamp or relational filters. you just need to add the suffix like _before or _after. you can also refer the Gigapay doc for this. keep in mind that here all the timestamps are in ISO 8601 string. you can also chain this method and add multiple filters

getJson

This will return the JSON response we get from Gigapay API with all our filters applied.

Exception-Handling

Gigapay Exception

• Laravel-Gigapay also provided some helper methods to deal with errors and exception given by Gigapay APIs.
• whenever Gigapay's API return any error, it will be thrown as GigapayException, that you can catch and them display the error properly
• Gigapay normally return the errors in json format with field name and error with that field.
• the json data about that error can be show using getJson() method on GigapayException instance.

• GigapayException also provide a method getErrorMessage that will convert the json into single message that you can show to end user.

• result