README

Laravel - PayHere was made to manage PayHere payment gateway on your laravel application with ease. currently this package supports all available methods on official PayHere documentation.

Read official Documentation for more information

Available API methods

✔️ Checkout API
✔️ Recurring API
✔️ Preapproval API
✔️ Charging API
✔️ Retrieval API
✔️ Subscription Manager API
✔️ Refund API
✔️ Authorize API
✔️ Capture API

Basic Usage

// adding payment details
$data = [
            'first_name' => 'Lahiru',
            'last_name' => 'Tharaka',
            'email' => 'lahirulhr@gmail.com',
            'phone' => '+94761234567',
            'address' => 'Main Rd',
            'city' => 'Anuradhapura',
            'country' => 'Sri lanka',
            'order_id' => '45552525005',
            'items' => 'Smart band MI 4 - BLACK',
            'currency' => 'LKR',
            'amount' => 4960.00,
        ];

// creating checkout page & redirect user
        
return PayHere::checkOut()
            ->data($data)
            ->successUrl('www.visanduma.com/payment-success')
            ->failUrl('www.visanduma.com/payment-fail')
            ->renderView();

Installation

You can install the package via composer:

composer require lahirulhr/laravel-payhere

You can publish the config file with:

php artisan vendor:publish --provider="Lahirulhr\PayHere\PayHereServiceProvider" --tag="laravel-payhere-config"

This is the contents of the published config file:

return [


    /*
     PayHere action url. usually,
     for production   https://www.payhere.lk
     for testing  https://sandbox.payhere.lk
      remember to update api when production
     * */

    'api_endpoint' => env('PAYHERE_API'),


    /*
      PayHere merchant ID can be found in their dashboard
      https://www.payhere.lk/account/settings/domain-credentials
     * */

    'merchant_id' => env('PAYHERE_MERCHANT_ID'),

    /*
     Merchant Secret is specific to each App/Domain. it can be generated for your domain/app as follows
     https://www.payhere.lk/account/settings/domain-credentials
        *Click 'Add Domain/App' > Fill details > Click 'Request to Allow'
        *Wait for the approval for your domain
        *Copy the Merchant Secret for your domain/app to .env file
     * */
    'merchant_secret' => env('PAYHERE_MERCHANT_SECRET'),


    /*
     Follow PayHere official instructions to obtain 'app_id' and 'app_secret'.
     NOTE: you dont need to generate "Authorization code". it will be automatically generate by this package
        *Sign in to your PayHere account & go to Settings > Business Apps section
        *Click 'Create App' button & enter an app name & comma seperated domains to whilelist
        *Tick the permission 'Payment Retrieval API'
        *Click 'Add Business App' button to create the app
        *Once the app is created click 'View Credential' button in front of the created app
        *Copy the 'App ID' & 'App Secret' values
     * */
    'app_id' => env('PAYHERE_APP_ID'),
    'app_secret' => env('PAYHERE_APP_SECRET'),

Usage

Checkout API

Checkout API lets you integrate PayHere with your website, web application or any other application in code level. It offers a simple HTML Form to initiate a payment request and redirect your customer to PayHere Payment Gateway to securely process the payment.

// in your controller

use Lahirulhr\PayHere\PayHere;

// prepair posting data

$data = [
            'first_name' => 'Lahiru',
            'last_name' => 'Tharaka',
            'email' => 'lahirulhr@gmail.com',
            'phone' => '+94761234567',
            'address' => 'Main Rd',
            'city' => 'Anuradhapura',
            'country' => 'Sri lanka',
            'order_id' => '45552525005',
            'items' => 'Smart band MI 4 - BLACK',
            'currency' => 'LKR',
            'amount' => 4960.00,
        ];

// creating checkout page & ridirect the user  

return PayHere::checkOut()
            ->data($data)
            ->setOptionalData() // Set optional data. see PayHere documantaion for available values
            ->successUrl('www.visanduma.com/success')
            ->failUrl('www.visanduma.com/fail')
            ->renderView();

Handling the server callback

PayHere will be notified your application with response data using public url POST request callback. then this package will emit a new event with their callback data. you just need to listen on an event and do anything you want with payload data.

Available Events

AuthorizeCallbackEvent
CheckoutCallbackEvent
PreapprovalCallbackEvent
RecurringCallbackEvent

Example:

            
// define listners in your EventServiceProvider.php

class EventServiceProvider extends ServiceProvider
{

    use Lahirulhr\PayHere\Events\CheckoutCallbackEvent;
    
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        CheckoutCallbackEvent::class => [
            // register listeners to do something with callback
            SomeListener::class 
        ],
    ];
    
}

class SomeListener{

    //....
    
     public function handle($event)
    {
     // you can access payhere callback data using $event->payload 
        Log::info($event->payload);
    }

}

Recurring API

Recurring API is accept data array same as checkout API. the only things you need to change checkOut() method to recurring().

return PayHere::recurring()
            ->data($data)
            ->setOptionalData() // Set optional data. see PayHere documantaion for available values
            ->successUrl('www.visanduma.com/success')
            ->failUrl('www.visanduma.com/fail')
            ->chargeMonthly(2)
            ->forYears()
            ->renderView();

The following options are available for making adjustment to recurring period

// Charging interval (Recurrence)
PayHere::recurring()->chargeWeekly(2) // charge per specific period of weeks .the default value is one week
PayHere::recurring()->chargeMonthly(3) // charge per specific period of months .the default value is one month
PayHere::recurring()->chargeAnnually() // charge per specific period of years .the default value is one year

// Duration to charge 
PayHere::recurring()->forWeeks(6) // set duratoin by weeks .the default value is one week
PayHere::recurring()->forMonths(3) // set duratoin by months .the default value is one month
PayHere::recurring()->forYears() // set duratoin by years .the default value is one year
PayHere::recurring()->forForever() // set charging period to infinity.

// use this event to recieve server callback. see above example on Checkout API 
RecurringCallbackEvent::class

Preapproval API

Use same as checkout method

return PayHere::preapproval()
            ->data($data)
            ->setOptionalData() // Set optional data. see PayHere documantaion for available values
            ->successUrl('www.visanduma.com/payment-success')
            ->failUrl('www.visanduma.com/payment-fail')
            ->renderView();

// use this event to recieve server callback. see above example on Checkout API 
PreapprovalCallbackEvent::class

Charging API

Charging API lets you charge your preapproved customers programatically on demand using the encrypted tokens. it will return response data array on success or return PayHereException if any error.

$data = [
        "type" => "PAYMENT",
        "order_id" => "Order12345",
        "items" => "Taxi Hire 123",
        "currency" => "LKR",
        "amount" => 345.67,
    ];

$response =  PayHere::charge()
        ->byToken("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx") // customer token
        ->withData($data)
        ->submit();

Retrieval API

Retrieval API lets you retrieve the details of the Successful payments processed through your PayHere

$info = PayHere::retrieve()
        ->orderId("od-43784658374534") // order number that you use to charge from customer
        ->submit();

Subscription Manager

Subscription Manager API lets you view, retry & cancel your subscription customers programmatically you subscribed from Recurring API.

// get all subscriptions
$subscriptions = PayHere::subscription()->getAll();

// get payment details of specific subscription
$paymentInfo = PayHere::subscription()
        ->getPaymentsOfSubscription("420075032251"); // subscription ID
        
// retry on failed supscription payments
PayHere::subscription()
        ->retry("420075032251"); // subscription ID
        
// cancel a subscription
PayHere::subscription()
        ->cancel("420075032251"); // subscription ID

Refund API

Refund API lets you refund your existing payment programmatically.

PayHere::refund()
        ->makePaymentRefund('320027150501') // payment_id
        ->note("Out of stock") // note for refund
        ->submit();

Authorize API

Authorize API allows you to get your customer authorization for Hold on Card payments. this method will redirect user to payment page

// use same $data as Checkout method

return PayHere::authorize()
        ->data($data)
        ->successUrl('www.visanduma.com/success')
        ->failUrl('www.visanduma.com/fail')
        ->renderView();

// use this event to recieve server callback. see above example on Checkout API 
AuthorizeCallbackEvent::class

Capture API

Capture API lets you capture your authorized Hold on Card payments programmatically on demand using the authorization tokens you retrieved from Payment Authorize API.

$response =  PayHere::capture()
        ->usingToken('e34f3059-7b7d-4b62-a57c-784beaa169f4') // authorization token
        ->amount(100) // charging amount
        ->reason("reason for capture")
        ->submit();

TODO

~~Events for server callbacks~~
Custom payment redirection page
Custom Error types
Response Data Objects
Optional Data handling
Inbuilt subscription database
Server callback log

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

lahirulhr / laravel-payhere

Maintainers

Details