A simple API wrapper to Gigapay's APIs for Laravel Framework

Overview

Laravel In-app Purchase cover

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 and Payouts. although its compatible with Laravel framework, but it can be used into other frameworks too since it doesn't depends on any Laravel library

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

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

Table of contents

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:

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Gigapay Server URL
    |--------------------------------------------------------------------------
    |
    | Gigapay generally has 2 servers, 1 for demo and 1 for production
    | both server has different url, by default it will use the demo server URL
    | but you can change it from your project's .env file.
    | also currently Gigapay's APIs are at version 2, so it will use version 2
    |
    */

    'server_url' => env('GIGAPAY_SERVER_URL', 'https://api.demo.gigapay.se/v2'),

    /*
    |--------------------------------------------------------------------------
    | Gigapay Token
    |--------------------------------------------------------------------------
    |
    | Gigapay uses this token to identify and authenticate requests,
    | you can get this Token from your Gigapay account
    | Note that Tokens are different for demo server and production server
    | define it in your .env.
    |
    */

    'token' => env('GIGAPAY_TOKEN'),

    /*
    |--------------------------------------------------------------------------
    | Gigapay integration id
    |--------------------------------------------------------------------------
    |
    | Integrations are like Transactions, it's a parent object of all other objects in the Gigapay API
    | whenever you do any action in Gigapay, it will be in integration and it has a integration id
    | Gigapay's API need integration id, you can create integration with Gigapay APIs from https://developer.gigapay.se/#create-an-integration
    |
    */

    'integration_id' => env('GIGAPAY_INTEGRATION_ID'),

    /*
    |--------------------------------------------------------------------------
    | Gigapay lang
    |--------------------------------------------------------------------------
    |
    | Language for the API responses. default will be english(en)
    |
    */

    'lang' => env('GIGAPAY_LANG', 'en'),

];

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.

GIGAPAY_TOKEN=""
GIGAPAY_INTEGRATION_ID=""
GIGAPAY_SERVER_URL="https://api.demo.gigapay.se/v2"
GIGAPAY_LANG="en"

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

use Mazimez\Gigapay\Employee;

$employee = Employee::create(
            'jhone doe',  //employee's name (required)
            '[email protected]',  //employee's email (has to be unique)
            null,  //employee's phone number(proper swidish phone number, has to be unique)
            'SWE', //employee's contry
            json_encode([
                "data" => "data from your system"  //any metadata that you want to add from you system(json encoded)
            ]),
            '123dvsdv23' //employee's ID(has to be unique)
        );
return $employee->getJson();

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
use Mazimez\Gigapay\Employee;

//#1: updating values using separate methods
$employee = Employee::findById('123'); //finding employee by id

$employee = $employee->updateCountry('SWE'); //updating country
$employee = $employee->updateName("test employee"); //updating name
$employee = $employee->updateEmail("[email protected]"); //updating email
$employee = $employee->updateMetaDate(json_encode([
    "data" => "some more data from you system",  //updating metadata
]));
$employee = $employee->updateId('12354'); //updating id
return $employee->getJson();

//#2 updating values using save() methods
$employee = Employee::findById('dvsdvsdv'); //finding employee by id

$employee->country  = "SWE"; //updating country
$employee->name = "test employee"; //updating name
$employee->email = "[email protected]"; //updating email
$employee->metadata = json_encode([
    "data" => "some more data from you system", //updating metadata
]);
$employee->save(); //saving the employee object
return $employee->getJson();

employee-list

The Employee::list() method will return the ListResource for employees that you can use to apply filters and search into all your employees. you can get more info from Gigapay doc

use Mazimez\Gigapay\Employee;

$employees = Employee::list(); //getting list of employee
$employees = $employees->paginate(1, 5);  //add pagination
return $employees->getJson();

employee-retrieve

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

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
return $employee->getJson();

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

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$employee->destroy(); //deletes the employee
return $employees->getJson(); //return the empty Employee instance

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

use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$employee->resend(); //resend invite to the employee

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.
use Mazimez\Gigapay\Employee;

$employee = Employee::findById('1'); //getting employee by it's id
$payouts = $employee->getAllPayouts(); //gettin payouts for that perticular employee
return $payouts->getJson(); //returning the payouts in json

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.
  • while providing metadata, remember to use json_encode() method.
  • you can get more info about Payout's pricing from Gigapay doc
use Mazimez\Gigapay\Payout;

$payout = Payout::create(
            '9aa16b42-d0f3-420f-ba57-580c3c86c419', //employee id
            'Instagram samarbete 2021-11-13.', //description for payout
            120, //amount of payout
            null, //cost of payout
            null, //invoice amount of payout
            'SEK', //currency of payout
            json_encode([
                "data" => "data from your system" //metadata of payout
            ]),
            null, //The time at which the gig will start. Displayed as ISO 8601 string.
            null, //The time at which the gig will end. Displayed as ISO 8601 string.
            3 //Unique identifier for the object.
);
return $payout->getJson();

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

payout-list

The Payout::list() method will return the ListResource for payouts that you can use to apply filters and search into all your payout. you can get more info from Gigapay doc

use Mazimez\Gigapay\Payout;

$payouts = Payout::list(); //getting list of employee
$payouts = $payouts->paginate(1, 5);  //add pagination
return $payouts->getJson();

payout-retrieve

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

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('1'); //getting payout by it's id
return $payout->getJson();

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

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('1'); //getting payout by it's id
$payout->destroy(); //deletes the payout
return $payout->getJson(); //return the empty payout instance

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

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('89f9cfbe-f1ec-4d17-a895-21cdb584eb4d'); //getting payout by it's id
$payout->resend(); //resend mail to the employee

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

use Mazimez\Gigapay\Payout;

$payout = Payout::findById('89f9cfbe-f1ec-4d17-a895-21cdb584eb4d'); //getting payout by it's id
$payout->expandInvoice()->expandEmployee();//expanding invoice and employee field
return $payout->getJson(); //returning the payouts in json(with expanded values)

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 ListResource for invoices that you can use to apply filters and search into all your invoice. you can get more info from Gigapay doc

use Mazimez\Gigapay\Invoice;

$invoices = Invoice::list(); //getting list of invoices
$invoices = $invoices->paginate(1, 5);  //add pagination
return $invoices->getJson();

invoice-retrieve

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

use Mazimez\Gigapay\Invoice;

$invoice = Invoice::findById('f3ee8cb8-fc95-4ea2-9b2e-18875b0d759a');//getting invoice by it's ID
return $invoice->getJson();

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)
use Mazimez\Gigapay\Invoice;

//#1: updating values using separate methods
$invoice = Invoice::findById('4bb6bd41-643e-43fe-af09-206c755088c9');
$invoice = $invoice->updateId("123");  //updating id
$invoice =$invoice->updateMetaDate(json_encode([
    "data" => "data from your system" //updating metadata
]));

//#2 updating values using save() methods
$invoice->metadata = json_encode([
    "data" => "data from your system" //updating metadata
]);
$invoice->save();

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

use Mazimez\Gigapay\Invoice;

$invoice = Invoice::findById('f3ee8cb8-fc95-4ea2-9b2e-18875b0d759a');//getting invoice by it's ID
$invoice->destroy(); //deletes the invoice
return $invoice->getJson(); //return the empty invoice instance

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 ListResource for pricing that you can use to apply filters. you can get more info from Gigapay doc

use Mazimez\Gigapay\Pricing;

$pricing = Pricing::list(); //getting list of pricing
$pricing = $pricing->paginate(1, 5);  //add pagination
return $pricing->getJson();

Pricing-Retrieve

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

use Mazimez\Gigapay\Pricing;

$pricing = Pricing::findById('89f9cfbe-f1ec-4d17-a895-21cdb584eb4d')//getting pricing info by payout's ID
return $pricing->getJson();

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.
use Mazimez\Gigapay\Pricing;

$pricing = Pricing::calculatePricing(
        '0d42728d-b565-402d-80aa-a20bec94a9a2', //id of employee that you want to pay
        'SEK', //currency of payout
        null, //cost (only 1 out cost, amount and invoiced_amount is allowed)
        '120', //amount (only 1 out cost, amount and invoiced_amount is allowed)
        null, //invoiced_amount (only 1 out cost, amount and invoiced_amount is allowed)
        'test', //description
        false, //full_salary_specification
        json_encode([
            "data" => "data from your system" //metadata of payout
        ]), 
        null, //start_at
        null, //end_at
        null, //id
    );
return $pricing->getJson();
    

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.

use Mazimez\Gigapay\Employee;

$employees = Employee::list();
$employees->paginate($page, $page_size);  //paginate methode with parameters
return $employees->getJson();

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.

use Mazimez\Gigapay\Employee;

$employees = Employee::list();
$employees->search('test');  //chaining search methode 
return $employees->getJson();

expand

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

use Mazimez\Gigapay\Payout;

$payouts = Payout::list();
$payouts->expand('employee'); //exapanding employee resource
return $payouts->getJson();

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

use Mazimez\Gigapay\Payout;

$payouts = Payout::list();
//exapanding employee and invoice resource
$payouts->expand('employee')->expand('invoice'); 
return $payouts->getJson();

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

use Mazimez\Gigapay\Employee;

$employees = Employee::list();

//adding filter to get the employees who are created before 10 days
$employees->addFilter('created_at_before', Carbon::now()->subDays(10)->toISOString());

//adding filter to get the onty verfied employees.
$invoice->addFilter('verified_at_null', 'false');

return $invoice->getJson();

getJson

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

use Mazimez\Gigapay\Employee;

$employees = Employee::list();
return $invoice->getJson(); //returning json response

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.
use Mazimez\Gigapay\Exceptions\GigapayException;
use Mazimez\Gigapay\Invoice;

try {
    return Invoice::findById("non-exiting-id")->getJson(); //code that will surely gives error.
} catch (GigapayException $th) { //catching the error with GigapayException
    return [
        'message' => $th->getErrorMessage(), //the error message
        'json' => $th->getJson() //the json
    ];
} catch (Exception $th) {
    return $th->getMessage(); //catching exception other then GigapayException
}
  • result
{
    "message": "Problem with detail->Not found.",
    "json": {
        "detail": "Not found."
    }
}
You might also like...
Execute Laravel Artisan commands via REST APIs and HTTP requests safely.

Artisan Api There might be some times you wanted to execute an Artisan command, but you did not have access to shell or SSH. Here we brought REST API

Laravel wrapper package for the Aimon.it API

Laravel Aimon Package A laravel wrapper package for the Aimon.it API. For more information see Aimon Requirements Laravel 6 or later Installation Inst

Laravel API wrapper to interact fluently with your Janus Media Server

Laravel API wrapper to interact fluently with your Janus Media Server. Core server interactions, as well as the video room plugin included.

Open Food Facts API wrapper for Laravel

Laravel Open Food Facts API This package provides a convenient wrapper to the Open Food Facts API for Laravel applications (5.7+). Installation You ca

a Google API v3 wrapper for Laravel 4.x

A Google API v3 wrapper for Laravel 4 This package enables a Laravel flavoured way to manage Google services through its API interface (v3) Installati

Laravel wrapper for Sentry Official API

Laravel Sentry API Provides a simple laravel wrapper to some of the endpoints listed on (Official Sentry API)[https://docs.sentry.io/api/]. **Note: Th

Laravel wrapper for the Gmail API

Laravel Gmail Gmail Gmail API for Laravel 8 You need to create an application in the Google Console. Guidance here. if you need Laravel 5 compatibilit

Shared code for the MaxMind Web Service PHP client APIs

Common Code for MaxMind Web Service Clients This is not intended for direct use by third parties. Rather, it is for shared code between MaxMind's vari

A CommonMark wrapper for Laravel
A CommonMark wrapper for Laravel

Laravel Markdown Laravel Markdown was created by, and is maintained by Graham Campbell, and is a CommonMark wrapper for Laravel. It ships with integra

Releases(v1.1.1)
  • v1.1.1(Jun 25, 2022)

  • v1.1.0(Jun 19, 2022)

    Webhooks

    • this update includes the support for Webhooks for Gigapay. Now you can listen to Gigapay webhooks by Laravel event Listeners.
    • this update provides helper methods and class to manage the Webhook resource.

    Full Changelog: https://github.com/mazimez/laravel-gigapay/commits/v1.1.0

    Source code(tar.gz)
    Source code(zip)
  • v1.0.1(Jun 14, 2022)

    Added Bulk payout support: added the methods in Pricing and Payout resource to support the Bulk payouts.

    Added helper methods to create resources by array: added the helper method createByArray in Employee and Payout resource to create resource by giving array instead of arguments

    Full Changelog: https://github.com/mazimez/laravel-gigapay/commits/v1.0.1

    Source code(tar.gz)
    Source code(zip)
  • v1.0.0(May 29, 2022)

    This version support different frameworks (not only Laravel). The future updates may be specific to the Laravel framework

    Full Changelog: https://github.com/mazimez/laravel-gigapay/commits/v1.0.0

    Source code(tar.gz)
    Source code(zip)
Owner
Asif Patel
just a normal guy
Asif Patel
Get started using SELCOM APIs with Laravel framework

About Laravel Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experie

Bruno 2 Jan 13, 2022
A Laravel Wrapper for the CoinDCX API. Now easily connect and consume the CoinDCX Public API in your Laravel apps without any hassle.

This package provides a Laravel Wrapper for the CoinDCX API and allows you to easily communicate with it. Important Note This package is in early deve

Moinuddin S. Khaja 2 Feb 16, 2022
Laravel-api - crud and login/signup apis

About Laravel Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experie

Maaz Ali Khan 2 Jan 2, 2022
Simple and ready to use API response wrapper for Laravel.

Laravel API Response Simple Laravel API response wrapper. Installation Install the package through composer: $ composer require obiefy/api-response Re

Obay Hamed 155 Sep 20, 2022
Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite

Mollie for Laravel Laravel-Mollie incorporates the Mollie API and Mollie Connect into your Laravel or Lumen project. Accepting iDEAL, Apple Pay, Banco

Mollie 287 Sep 23, 2022
Easily Integrate PingPing APIs in your Laravel Project

PingPing This composer package allows us to easily integrate PingPing APIs in your Laravel project. What is PingPing ? PingPing is the simplest uptime

Bhushan Gaikwad 15 Mar 22, 2022
A Laravel 8 Project Implement with GraphQL With Sanctum APIs Authentications Which utilized in Any Frontend or Any Mobile Application Programs.

A Laravel 8 Project Implement with GraphQL With Sanctum APIs Authentications Which utilized in Any Frontend or Any Mobile Application Programs.

Vikas Ukani 3 Jan 6, 2022
A package to access messari apis for laravel

Messari API - Laravel Laravel wrapper for messari.io API Full API documentation could be found on messari.io Installation PHP 7.2+ and Composer are re

Seyyed Ahmad Mousavi 2 Apr 13, 2022
Builds nice, normalized and easy to consume REST JSON responses for Laravel powered APIs.

REST API Response Builder for Laravel Master branch: Development branch: Table of contents Introduction Why should I use it? Usage examples Features E

Marcin Orlowski 598 Sep 20, 2022
Backend application using Laravel 9.x REST APIs for games topup from digiflazz.com and payment gateway using xendit.co

TOPUP - Laravel 9.x REST API Documentation is still on progress. For now, you can fork this postman collection Installation Clone this project git clo

Muhammad Athhar Kautsar 39 Sep 12, 2022