JFIFxxC      C  " }!1AQa"q2#BR$3br %&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz w!1AQaq"2B #3Rbr# Laravel PayHere [![Latest Version on Packagist](https://img.shields.io/packagist/v/lahirulhr/laravel-payhere.svg?style=flat-square)](https://packagist.org/packages/lahirulhr/laravel-payhere) [![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/lahirulhr/laravel-payhere/run-tests?label=tests)](https://github.com/lahirulhr/laravel-payhere/actions?query=workflow%3Arun-tests+branch%3Amain) [![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/lahirulhr/laravel-payhere/Check%20&%20fix%20styling?label=code%20style)](https://github.com/lahirulhr/laravel-payhere/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain) [![Total Downloads](https://img.shields.io/packagist/dt/lahirulhr/laravel-payhere.svg?style=flat-square)](https://packagist.org/packages/lahirulhr/laravel-payhere)
[](http://laravel.com)
[](http://payhere.lk)
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](https://support.payhere.lk/api-&-mobile-sdk/payhere-checkout) 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 ```php // 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: ```bash composer require lahirulhr/laravel-payhere ``` You can publish the config file with: ```bash php artisan vendor:publish --provider="Lahirulhr\PayHere\PayHereServiceProvider" --tag="laravel-payhere-config" ``` This is the contents of the published config file: ```php 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](https://support.payhere.lk/api-&-mobile-sdk/payhere-checkout) 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. ```php // 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 notify your application with response data using public url POST request callback. then this package will emit new event with their callback data. you just need to listen on event and do any thing you want with payload data. ```php // 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 listners to do something with callback ], ]; } ``` ###### [Recurring API](https://support.payhere.lk/api-&-mobile-sdk/payhere-recurring) Recurring API is accept data array same as checkout API. the only things you need to change checkOut() method to recurring(). ```php 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 ```php // 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. ``` ```php // use this event to recieve server callback. see above example on Checkout API RecurringCallbackEvent::class ``` ###### [Preapproval API](https://support.payhere.lk/api-&-mobile-sdk/payhere-preapproval) Use same as checkout method ```php 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(); ``` ```php // use this event to recieve server callback. see above example on Checkout API PreapprovalCallbackEvent::class ``` ###### [Charging API](https://support.payhere.lk/api-&-mobile-sdk/payhere-charging) 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. ```php $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](https://support.payhere.lk/api-&-mobile-sdk/payhere-retrieval) Retrieval API lets you retrieve the details of the Successful payments processed through your PayHere ```php $info = PayHere::retrieve() ->orderId("od-43784658374534") // order number that you use to charge from customer ->submit(); ``` ##### [Subscription Manager](https://support.payhere.lk/api-&-mobile-sdk/payhere-subscription) Subscription Manager API lets you view, retry & cancel your subscription customers programmatically you subscribed from Recurring API. ```php // 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](https://support.payhere.lk/api-&-mobile-sdk/payhere-refund) Refund API lets you refund your existing payment programmatically. ```php PayHere::refund() ->makePaymentRefund('320027150501') // payment_id ->note("Out of stock") // note for refund ->submit(); ``` ###### [Authorize API](https://support.payhere.lk/api-&-mobile-sdk/payhere-authorize) Authorize API allows you to get your customer authorization for Hold on Card payments. this method will redirect user to payment page ```php // use same $data as Checkout method return PayHere::authorize() ->data($data) ->successUrl('www.visanduma.com/success') ->failUrl('www.visanduma.com/fail') ->renderView(); ``` ```php // use this event to recieve server callback. see above example on Checkout API AuthorizeCallbackEvent::class ``` ###### [Capture API](https://support.payhere.lk/api-&-mobile-sdk/payhere-capture) Capture API lets you capture your authorized Hold on Card payments programmatically on demand using the authorization tokens you retrieved from Payment Authorize API. ```php $response = PayHere::capture() ->usingToken('e34f3059-7b7d-4b62-a57c-784beaa169f4') // authorization token ->amount(100) // charging amount ->reason("reason for capture") ->submit(); ``` --- ## TODO - [x] ~~Events for server callbacks~~ - [ ] Custom payment redirection page - [ ] Custom Error types - [ ] Response Data Objects - [ ] Optional Data handling - [ ] Inbuilt subscription database - [ ] Server callback log ## Testing ```bash composer test ``` ## Changelog Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. ## Contributing Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details. ## Security Vulnerabilities Please review [our security policy](../../security/policy) on how to report security vulnerabilities. ## Credits - [LaHiRu](https://github.com/lahirulhr) - [All Contributors](../../contributors) ## License The MIT License (MIT). Please see [License File](LICENSE.md) for more information.