Download the PHP package smodav/mpesa without Composer

M-PESA API Package

This is a PHP package for the Safaricom's M-Pesa API. The API allows a merchant to initiate C2B online checkout (paybill via web) transactions. The merchant submits authentication details, transaction details, callback url and callback method.

After request submission, the merchant receives instant feedback with validity status of their requests. The C2B API handles customer validation and authentication via USSD push. The customer then confirms the transaction. If the validation of the customer fails or the customer declines the transaction, the API makes a callback to merchant. Otherwise the transaction is processed and its status is made through a callback.

If you enjoy using this package, please take a moment and buy me some coffee.

Installation

Pull in the package through Composer.

Native Addon

When using vanilla PHP, modify your composer.json file to include:

This script will copy the default configuration file to a config folder in the root directory of your project. Now proceed to require the package.

General Install

Run composer require smodav/mpesa to get the latest stable version of the package.

Migration from previous versions

v5 of the package changes the implementation and introduces some breaking changes. Please have a look at the CHANGELOG.

v4 of this package uses a new configuration setup. You will need to update your config file in order to upgrade v3 to v4. v2 is still incompatible since it uses the older API version.

Laravel

When using Laravel 5.5+, the package will automatically register. For laravel 5.4 and below, include the service provider and its alias within your config/app.php.

Publish the package specific config using:

Other Frameworks

To implement this package, a configuration repository is needed, thus any other framework will need to create its own implementation of the ConfigurationStore and CacheStore interfaces.

Configuration

The package allows you to have multiple accounts. Each account will have its specific credentials and endpoints that are independent of the rest. You will be required to set the default account to be used for all transactions, which you can override on each request you make. The package comes with two default accounts that you can modify.

You can add as many accounts as required and switch the connection using the method usingAccount on STK, Register and Simulate as shown below.

Also, note the difference between the business shortcode and your paybill number in the configuration as getting them wrong will cost you a lot of time debugging.

Usage

For Vanilla PHP you will need to initialize the core engine before any requests as shown below. The package comes with a vanilla php implementation of the cache and configuration store, NativeCache and NativeConfig.

The NativeConfig receives the custom location for the configuration file to be used as the first constructor argument. If no value is passed when creating the instance, it will use the default configuration and look for a configuration file on the root of the project under configs directory.

The NativeCache receives a custom directory path as the first constructor argument. The path denotes where the cache should store its files. If no path is provided, the default cache location in the config will be used.

URL Registration

submit(shortCode = null, confirmationURL = null, validationURL = null, onTimeout = 'Completed|Cancelled', account = null)

Register callback URLs

Vanilla

When having multiple accounts, switch using the usingAccount method. We currently have staging, paybill_1 and paybill_2 with staging as the default:

Laravel

Using the paybill_1 account:

Simulate Transaction

push(amount = null, number = null, reference = null, account = null, command = null)

Initiate a C2B simulation transaction request.

Note that when initiating a C2B simulation, setting the command type is optional and by default CustomerPaybillOnline will be used.

Vanilla

Using the paybill_1 account:

Using the CustomerBuyGoodsOnline command:

Laravel

Using the paybill_1 account:

Using the CustomerBuyGoodsOnline command:

STK PUSH

push(amount = null, number = null, reference = null, description = null, account = null, command = null)

Initiate a C2B STK Push request.

Note that when initiating an STK Push, setting the command type is optional and by default CustomerPaybillOnline will be used.

Vanilla

Using the paybill_2 account:

Using CustomerBuyGoodsOnline command:

Laravel

Using the paybill_2 account:

Using the CustomerGoodsOnline command:

STK PUSH Transaction Validation

validate(merchantReferenceId, account = null)

Validate a C2B STK Push transaction.

Vanilla

Using the paybill_2 account:

Laravel

Using the paybill_1 account:

When going live, you should change the default value of the config file to the production account.

License

The M-Pesa Package is open-sourced software licensed under the MIT license.