Download the PHP package prevailexcel/laravel-marasoftpay without Composer

laravel-marasoftpay

A Laravel Package for working with MarasoftPay Payments seamlessly.

Collect payments from individuals or businesses locally and globally, and settle them in multiple currencies, ensuring a cost-effective and hassle-free payment process. This package also allows you to receive all types of webhooks from Marasoft Pay which it verifies and handles the payloads for you. You can start collecting payment in payments in minutes.

Bank Transfers
USSD
Cards
Virtual Bank Accounts
Mobile Money

Installation

PHP 5.4+ or HHVM 3.3+, and Composer are required.

To get the latest version of Laravel Marasoft Pay, simply require it

Or add the following line to the require block of your composer.json file.

You'll then need to run composer install or composer update to download it and have the autoloader updated.

Once Laravel Marasoft Pay is installed, you need to register the service provider. Open up config/app.php and add the following to the providers key.

If you use Laravel >= 5.5 you can skip this step and go to configuration

Also, register the Facade like so:

Configuration

You can publish the configuration file using this command:

A configuration-file named marasoftpay.php with some sensible defaults will be placed in your config directory:

General payment flow

Though there are multiple ways to pay an order, most payment gateways expect you to follow the following flow in your checkout process:

1. The customer is redirected to the payment provider

After the customer has gone through the checkout process and is ready to pay, the customer must be redirected to the site of the payment provider.

The redirection is accomplished by submitting a form with some hidden fields. The form must send a POST request to the site of the payment provider. The hidden fields minimally specify the amount that must be paid, the order id and a hash.

The hash is calculated using the hidden form fields and a non-public secret. The hash used by the payment provider to verify if the request is valid.

2. The customer pays on the site of the payment provider

The customer arrives on the site of the payment provider and gets to choose a payment method. All steps necessary to pay the order are taken care of by the payment provider.

3. The customer gets redirected back to your site

After having paid the order the customer is redirected back. In the redirection request to the shop-site some values are returned. The values are usually the order id, a payment result and a hash.

The hash is calculated out of some of the fields returned and a secret non-public value. This hash is used to verify if the request is valid and comes from the payment provider. It is paramount that this hash is thoroughly checked.

Usage

Open your .env file and add all the necessary keys like so:

If you are using a hosting service like heroku, ensure to add the above details to your configuration variables. Remember to change MARASOFTPAY_ENV to 'live' and update the keys when you are in production

Next, you have to setup your routes.

There are 3 routes you should have to get started.

1. To initiate payment
2. To setup callback - Route::callback.
3. To setup webhook and handle the event responses - Route::webhook.

OR

Let's set our controller

"User Bear Charge" is set to true by default in the config/marasoftpay.php. If you want to bear charges, you can change it to false. You can also manually override it for a particular method by passing it directly as 'user_bear_charge' => 'no'

Lets pay with bank transfer now.

Here you can get a dynamnic account payWithBankTransfer($amount) for a one time payment , or you can get a reserved account getReservedAccount($data) or recurring payments.

This will return data that includes the account details which you will display or send to your user to make payment.

Handling Webhook

You can listen to the webhook and service the user. Write the heavy operations inside the handleWebhook() method.

This package will verify the webhook using the secret hash, identify the event that produced the webhook and then add an event key which can be either of the three:

CHECKOUT
RESERVED
PAYOUT

In your controller

This package recommends to use a queued job to proccess the webhook data especially if you handle heavy operations like sending mail and more

How does the webhook routing Route::webhook(Controller::class, 'methodName') work?

Behind the scenes, by default this will register a POST route 'marasoftpay/webhook' to the controller and method you provide. Because the app that sends webhooks to you has no way of getting a csrf-token, you must add that route to the except array of the VerifyCsrfToken middleware:

Add the 'marasoftpay/webhook' endpoint URL to the three webhook fields on your MarasoftPay;

Payments Webhook URL : 127.0.0.1:8000/marasoftpay/webhook
Transfers Webhook URL : 127.0.0.1:8000/marasoftpay/webhook
Card Webhook URL : 127.0.0.1:8000/marasoftpay/webhook

A sample form will look like so:

When clicking the submit button the customer gets redirected to the Payment page.

So now the customer did some actions there (hopefully he or she paid the order) and now the package will redirect the customer to the Callback URL Route::callback().

We must validate if the redirect to our site is a valid request (we don't want imposters to wrongfully place non-paid order).

In the controller that handles the request coming from the payment provider, we have

MarasoftPay::getPaymentData() - This function calls the verifyTransaction() methods and ensure it is a valid transaction else it throws an exception.

Some Other fluent methods this package provides are listed here.

Collection

Account

Payout

Tools

Todo

• Add Comprehensive Tests

Contributing

Please feel free to fork this package and contribute by submitting a pull request to enhance the functionalities.

How can I thank you?

Why not star the github repo? I'd love the attention! Why not share the link for this repository on Twitter or HackerNews? Spread the word!

Thanks! Chimeremeze Prevail Ejimadu, Akindipe Ambrose.

License

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