{"id":21565861,"url":"https://github.com/prevailexcel/laravel-marasoftpay","last_synced_at":"2025-10-29T04:42:57.678Z","repository":{"id":214896044,"uuid":"736739396","full_name":"PrevailExcel/laravel-marasoftpay","owner":"PrevailExcel","description":"A Laravel SDK for Marasoft Pay","archived":false,"fork":false,"pushed_at":"2024-01-01T10:16:50.000Z","size":164,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-12T22:05:55.719Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://marasoftpay.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PrevailExcel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-28T18:27:46.000Z","updated_at":"2023-12-31T19:05:33.000Z","dependencies_parsed_at":"2023-12-31T20:19:19.708Z","dependency_job_id":"5ffd3911-b30c-470c-a3b3-1d63771fe268","html_url":"https://github.com/PrevailExcel/laravel-marasoftpay","commit_stats":null,"previous_names":["prevailexcel/laravel-marasoftpay"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/PrevailExcel/laravel-marasoftpay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrevailExcel%2Flaravel-marasoftpay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrevailExcel%2Flaravel-marasoftpay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrevailExcel%2Flaravel-marasoftpay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrevailExcel%2Flaravel-marasoftpay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PrevailExcel","download_url":"https://codeload.github.com/PrevailExcel/laravel-marasoftpay/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrevailExcel%2Flaravel-marasoftpay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275572629,"owners_count":25489093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T10:22:11.003Z","updated_at":"2025-09-17T09:51:25.650Z","avatar_url":"https://github.com/PrevailExcel.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# laravel-marasoftpay\n\n[![Latest Stable Version](https://poser.pugx.org/prevailexcel/laravel-marasoftpay/v/stable.svg)](https://packagist.org/packages/prevailexcel/laravel-marasoftpay)\n[![License](https://poser.pugx.org/prevailexcel/laravel-marasoftpay/license.svg)](LICENSE.md)\n\u003e A Laravel Package for working with MarasoftPay Payments seamlessly.\n\nCollect payments from individuals or businesses locally and globally, and settle them in multiple currencies, ensuring a cost-effective and hassle-free payment process.\nThis package also allows you to receive all types of webhooks from [Marasoft Pay](https://marasoftpay.com/) which it verifies and handles the payloads for you. You can start collecting payment in payments in minutes.\n\n    Bank Transfers\n    USSD\n    Cards\n    Virtual Bank Accounts\n    Mobile Money\n\n## Installation\n\n[PHP](https://php.net) 5.4+ or [HHVM](http://hhvm.com) 3.3+, and [Composer](https://getcomposer.org) are required.\n\nTo get the latest version of Laravel Marasoft Pay, simply require it\n\n```bash\ncomposer require prevailexcel/laravel-marasoftpay\n```\n\nOr add the following line to the require block of your `composer.json` file.\n\n```\n\"prevailexcel/laravel-marasoftpay\": \"1.0.*\"\n```\n\nYou'll then need to run `composer install` or `composer update` to download it and have the autoloader updated.\n\nOnce 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. \n\u003e If you use **Laravel \u003e= 5.5** you can skip this step and go to [**`configuration`**](https://github.com/PrevailExcel/laravel-marasoftpay#configuration)\n\n```php\n'providers' =\u003e [\n    ...\n    PrevailExcel\\MarasoftPay\\MarasoftPayServiceProvider::class,\n    ...\n]\n```\n\nAlso, register the Facade like so:\n\n```php\n'aliases' =\u003e [\n    ...\n    'MarasoftPay' =\u003e PrevailExcel\\MarasoftPay\\Facades\\MarasoftPay::class,\n    ...\n]\n```\n\n## Configuration\n\nYou can publish the configuration file using this command:\n\n```bash\nphp artisan vendor:publish --provider=\"PrevailExcel\\MarasoftPay\\MarasoftPayServiceProvider\"\n```\n\nA configuration-file named `marasoftpay.php` with some sensible defaults will be placed in your `config` directory:\n\n```php\n\u003c?php\n\nreturn [\n\n    /**\n     * Public Key From MARASOFTPAY Dashboard\n     *\n     */\n    'publicKey' =\u003e getenv('MARASOFTPAY_PUBLIC_KEY'),\n\n    /**\n     * Encryption Key From MARASOFTPAY Dashboard\n     *\n     */\n    'encryptionKey' =\u003e getenv('MARASOFTPAY_ENCRYPTION_KEY'),\n\n    /**\n     * You enviroment can either be live or stage.\n     * Make sure to add the appropriate API key after changing the enviroment in .env\n     *\n     */\n    'env' =\u003e env('MARASOFTPAY_ENV', 'test'), // OR \"LIVE\"\n\n    /**\n     * Your secret hash is a unique key which is part of the data sent with your webhooks\n     * It serves as a form of verification to prove that the webhook is coming from Marasoft Pay.\n     *\n     */\n    'hash' =\u003e env('MARASOFTPAY_HASH', 'MarasoftPay'), // OR \"LIVE\"    \n    \n    /**\n     * Should user bear charge?\n     *\n     */\n    'user_bear_charge' =\u003e \"yes\", // or \"no\"\n\n    /**\n     * MARASOFTPAY Base URL\n     *\n     */\n    'baseUrl' =\u003e env('MARASOFTPAY_LIVE_URL', \"https://api.marasoftpay.live\"),\n];\n```\n\n## General payment flow\n\nThough there are multiple ways to pay an order, most payment gateways expect you to follow the following flow in your checkout process:\n\n### 1. The customer is redirected to the payment provider\nAfter 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.\n\nThe 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.\n\nThe 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.\n\n\n### 2. The customer pays on the site of the payment provider\nThe 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.\n\n### 3. The customer gets redirected back to your site\nAfter 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.\n\nThe 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.\n\n## Usage\n\nOpen your .env file and add all the necessary keys like so:\n\n```bash\nMARASOFTPAY_PUBLIC_KEY=MSFT_****_****************************************\nMARASOFTPAY_ENCRYPTION_KEY=MSFT_Enc******************************************\nMARASOFTPAY_ENV=test\nMARASOFTPAY_HASH=yoursecret\n```\n*If you are using a hosting service like heroku, ensure to add the above details to your configuration variables.*\n*Remember to change MARASOFTPAY_ENV to 'live' and update the keys when you are in production*\n\n#### Next, you have to setup your routes. \nThere are 3 routes you should have to get started.\n1. To initiate payment\n2. To setup callback - Route::callback.\n3. To setup webhook and handle the event responses - Route::webhook.\n\n```php\n// Laravel 5.1.17 and above\nRoute::post('/pay', 'PaymentController@createPayment')-\u003ename('pay');\nRoute::callback(PaymentController::class, 'handleGatewayCallback');\nRoute::webhook(WebhookController::class, 'handleWebhook');\n```\nOR\n\n```php\n// Laravel 8 \u0026 9\nRoute::post('/pay', [PaymentController::class, 'createPayment'])-\u003ename('pay');\nRoute::callback(PaymentController::class, 'handleGatewayCallback');\nRoute::webhook(WebhookController::class, 'handleWebhook');\n```\n\n\n#### Let's set our controller\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse Illuminate\\Http\\Request;\n\nuse App\\Http\\Requests;\nuse App\\Http\\Controllers\\Controller;\nuse Illuminate\\Support\\Facades\\Redirect;\nuse PrevailExcel\\MarasoftPay\\Facades\\MarasoftPay;\n\nclass PaymentController extends Controller\n{\n\n    /**\n     * Redirect the User to Marasoft Pay Payment Page\n     * @return Url\n     */\n    public function redirectToGateway()\n    {\n        try{\n            return MarasoftPay::getLink()-\u003eredirectNow();\n        }catch(\\Exception $e) {\n            return Redirect::back()-\u003ewithMessage(['msg'=\u003e $e-\u003egetMessage(), 'type'=\u003e'error']);\n        }        \n    }\n\n    /**\n     * Obtain Marasoft Pay payment information\n     * @return void\n     */\n    public function handleGatewayCallback()\n    {\n        $paymentDetails = marasoftpay()-\u003egetPaymentData();\n\n        dd($paymentDetails);\n        // Now you have the payment details,\n        // you can store the reference ID in your db.\n        // you can then redirect or do whatever you want\n    }\n}\n```\n\n```php\n/**\n *  In the case where you need to pass the data from your\n *  controller or via your client or app instead of a form\n *  \n */\n $data = [       \n        'name' =\u003e \"Prevail Ambrose\",\n        'email_address' =\u003e \"example@gmail.com\",\n        'phone_number' =\u003e \"08100000000\",\n        'amount' =\u003e \"9000\",\n        'description' =\u003e \"Gold Color\"\n    ];\n\n    // if monolithic, do\n    return MarasoftPay::getLink($data)-\u003eredirectNow();\n\n    // if API, do\n    return MarasoftPay::getLink($data, true);\n\n```\n\u003e \"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' =\u003e 'no'`\n### Lets pay with bank transfer now.\nHere 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.\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse Illuminate\\Http\\Request;\nuse PrevailExcel\\MarasoftPay\\Facades\\MarasoftPay;\n\nclass PaymentController extends Controller\n{  \n    /**\n     * You collect data from your blade form\n     * and this returns the Account details for payment\n     */\n    public function createPayment()\n    {\n        try {\n            // You can use the global helper marasoftpay()-\u003emethod() or the Facade MarasoftPay::method().\n            \n            // Dynamic Account Payment\n            return MarasoftPay::payWithBankTransfer(\"100000\");\n\n            // Reserved Account Payment\n            $data = [        \n                'first_name' =\u003e \"Prevail\",\n                'last_name' =\u003e \"Ambrose\",\n                'phone_number' =\u003e \"08052344545\",\n                'tag' =\u003e \"whatever\",\n                'bvn' =\u003e \"2522222222\"\n            ];\n            return MarasoftPay::getReservedAccount($data);\n            \n        } catch (\\Exception $e) {\n            return redirect()-\u003eback()-\u003ewithMessage(['msg' =\u003e $e-\u003egetMessage(), 'type' =\u003e 'error']);\n        }\n    }\n}\n```\nThis will return data that includes the account details which you will display or send to your user to make payment.\n\n### Handling Webhook\nYou can listen to the webhook and service the user. Write the heavy operations inside the `handleWebhook()` method.\n\nThis 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:\n\n    CHECKOUT\n    RESERVED\n    PAYOUT\n\n#### In your controller\n\n```php\n    public function handleWebhook()\n    {\n        // verify webhook and get data\n        marasoftpay()-\u003egetWebhookData()-\u003eproccessData(function ($data) {\n            // Do something with $data\n            logger($data);\n            $decodedData = json_decode($data, true);\n            if (decodedData['event'] == 'CHECKOUT') {\n            // Do Something\n            } else if (decodedData['event'] == 'RESERVED') {\n            // Do Another Thing\n            } else {\n                // Do Any other thing\n            }\n            \n            // If you have heavy operations, dispatch your queued jobs for them here\n            // OrderJob::dispatch($data);\n        });\n        \n        // Acknowledge you received the response\n        return http_response_code(200);\n    }\n```\n\n\u003e This package recommends to use a queued job to proccess the webhook data especially if you handle heavy operations like sending mail and more \n\n##### How does the webhook routing `Route::webhook(Controller::class, 'methodName')` work?\n\nBehind 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:\n```php\nprotected $except = [\n    'marasoftpay/webhook',\n];\n```\n\nAdd the  `'marasoftpay/webhook'` endpoint URL to the three webhook fields on your MarasoftPay;\n\n    Payments Webhook URL : 127.0.0.1:8000/marasoftpay/webhook\n    Transfers Webhook URL : 127.0.0.1:8000/marasoftpay/webhook\n    Card Webhook URL : 127.0.0.1:8000/marasoftpay/webhook\n\n![Add Webhook to dashboard](image.png)\n\n\n#### A sample form will look like so:\n```blade\n\u003cform method=\"POST\" action=\"{{ route('pay') }}\"\u003e\n    @csrf\n    \u003cdiv class=\"form-group\" style=\"margin-bottom: 10px;\"\u003e\n        \u003clabel for=\"name\"\u003eName\u003c/label\u003e\n        \u003cinput class=\"form-control\" type=\"text\" name=\"name\" /\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"form-group\" style=\"margin-bottom: 10px;\"\u003e\n        \u003clabel for=\"phone-number\"\u003ePhone Number\u003c/label\u003e\n        \u003cinput class=\"form-control\" type=\"tel\" name=\"phone\" required /\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"form-group\" style=\"margin-bottom: 10px;\"\u003e\n        \u003clabel for=\"email\"\u003eEmail\u003c/label\u003e\n        \u003cinput class=\"form-control\" type=\"email\" name=\"email\" required /\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"form-group\" style=\"margin-bottom: 10px;\"\u003e\n        \u003clabel for=\"amount\"\u003eAmount\u003c/label\u003e\n        \u003cinput class=\"form-control\" type=\"number\" name=\"amount\" required /\u003e\n    \u003c/div\u003e\n    \u003cinput value=\"This is the description\" type=\"hidden\" name=\"description\" /\u003e    \n    \u003cdiv class=\"form-submit\"\u003e\n        \u003cbutton class=\"btn btn-primary btn-block\" type=\"submit\"\u003e Pay \u003c/button\u003e\n    \u003c/div\u003e\n\u003c/form\u003e\n```\nWhen clicking the submit button the customer gets redirected to the Payment page.\n\nSo 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()`.\n\nWe must validate if the redirect to our site is a valid request (we don't want imposters to wrongfully place non-paid order).\n\nIn the controller that handles the request coming from the payment provider, we have\n\n`MarasoftPay::getPaymentData()` - This function calls the `verifyTransaction()` methods and ensure it is a valid transaction else it throws an exception.\n\n\n### Some Other fluent methods this package provides are listed here.\n\n#### Collection\n\n```php\n/**\n * Make payment with MPESA mobile money\n * @returns array\n */\nMarasoftPay::payWithMobileMoney(?array $data);\n// Or\nmarasoftpay()-\u003epayWithMobileMoney(?array $data);\n\n/**\n * Make payment via USSD\n * @returns array\n */\nMarasoftPay::ussd();\n\n/**\n * Check your balance for the different currencies available\n * @returns array\n */\nMarasoftPay::checkBalance();\n```\n\n#### Account\n\n```php\n/**\n * Generate account statements with custom date ranges\n * @returns array\n */\nMarasoftPay::accountStatement(?string $start_date = null, ?string $end_date = null);\n\n/**\n * Generate transfer history statements with custom date ranges\n * @returns array\n */\nMarasoftPay::transferHistory(?string $start_date = null, ?string $end_date = null);\n\n/**\n * Generate payments history statements with custom date ranges\n * @returns array\n */\nMarasoftPay::paymentsHistory(?string $start_date = null, ?string $end_date = null);\n\n/**\n * Generate reserved account history statements with custom date ranges\n * @returns array\n */\nMarasoftPay::reservedAccountHistory(?string $start_date = null, ?string $end_date = null);\n\n```\n\n#### Payout\n\n```php\n/**\n * Move funds from your Marasoft Pay balance to a bank account.\n * @returns array\n */\nMarasoftPay::transfer($data = null);\n```\n\n#### Tools\n\n```php\n/**\n * Get all the bank codes for all existing banks in our operating countries.\n * @returns array\n */\nMarasoftPay::getBanks();\n\n/**\n * Verify the status of a transaction carried out on your Marasoft Pay account\n * @returns array\n */\nMarasoftPay::verifyTransaction(?string $ref = null);\n// Or\nrequest()-\u003eref = \"reference\";\nmarasoftpay()-\u003everifyTransaction();\n\n/**\n * Verify the status of a transfer carried out from your Marasoft Pay account \n * @returns array\n */\nMarasoftPay::verifyTransfer(?string $ref = null);\n\n/**\n * Verify the owner of a bank account using the bank code and the account uumber \n * @returns array\n */\nMarasoftPay::confirmAccount(?string $bank_code = null, ?string $account_number = null);\n\n```\n\n## Todo\n\n* Add Comprehensive Tests\n\n## Contributing\n\nPlease feel free to fork this package and contribute by submitting a pull request to enhance the functionalities.\n\n## How can I thank you?\n\nWhy 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!\n\nThanks!\n[Chimeremeze Prevail Ejimadu](https://x.com/EjimaduPrevail), \n[Akindipe Ambrose](https://x.com/AkindipeAmbrose).\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprevailexcel%2Flaravel-marasoftpay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprevailexcel%2Flaravel-marasoftpay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprevailexcel%2Flaravel-marasoftpay/lists"}