Skip to content

Multitenancy Support #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NimzyMaina wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Multitenancy Support #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cfee997
- Add Multitenancy Support
NimzyMaina Sep 14, 2018
47556a4
- Revamp readme.md after Multitenancy support
NimzyMaina Sep 14, 2018
2323f88
- Edit read me
NimzyMaina Sep 14, 2018
d1e7f5b
- Add backwards compatibility
NimzyMaina Sep 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 116 additions & 62 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,121 +1,175 @@
**Introduction**
# Introduction

This package seeks to help php developers implement the various Mpesa APIs without much hustle. It is based on the REST API whose documentation is available on http://developer.safaricom.co.ke.

**Installation using composer**<br>
`composer require safaricom/mpesa`<br>

This package seeks to help php developers implement the various Mpesa APIs without much hustle. It is based on the REST API whose documentation is available on [Safaricom Developer](http://developer.safaricom.co.ke).

## Installation using composer

```
composer require safaricom/mpesa
```

## Configuration

At your project root, create a .env file and in it set the consumer key and consumer secret as follows
```.dotenv
MPESA_CONSUMER_KEY=[consumer key]
MPESA_CONSUMER_SECRET=[consumer secret]
MPESA_ENV=[live or sandbox]
```

**Configuration**<br>
At your project root, create a .env file and in it set the consumer key and consumer secret as follows
`MPESA_CONSUMER_KEY= [consumer key]` <br>
`MPESA_CONSUMER_SECRET=[consumer secret]`<br>
`MPESA_ENV=[live or sandbox]`<br>
For Laravel users, open the Config/App.php file and add `\Safaricom\Mpesa\MpesaServiceProvider::class` under providers and ` 'Mpesa'=> \Safaricom\Mpesa\MpesaServiceProvider::class` under aliases.
For Laravel users, open the Config/App.php file and add `\Safaricom\Mpesa\MpesaServiceProvider::class` under providers and ` 'Mpesa'=> \Safaricom\Mpesa\MpesaServiceProvider::class` under aliases.

_Remember to edit the consumer_key and consumer_secret values appropriately when switching between sandbox and live_


**Usage**

**Confirmation and validation urls**

**B2C Payment Request**

This creates transaction between an M-Pesa short code to a phone number registered on M-Pesa.

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
In order to transact from multiple paybill numbers or till numbers , you can change the configs at runtime using the config helper.

`$b2cTransaction=$mpesa->b2c($InitiatorName, $SecurityCredential, $CommandID, $Amount, $PartyA, $PartyB, $Remarks, $QueueTimeOutURL, $ResultURL, $Occasion);`
So we need to add the following to the services config file (config/services.php)

```php
return = [

// More configs here

**Account Balance Request**

This is used to enquire the balance on an M-Pesa BuyGoods (Till Number)
'mpesa' => [
'MPESA_CONSUMER_KEY' => env('MPESA_CONSUMER_KEY'),
'MPESA_CONSUMER_SECRET' => env('MPESA_CONSUMER_SECRET'),
'MPESA_ENV' => env('MPESA_ENV')
]
];
```

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
## Usage

`$balanceInquiry=$mpesa->accountBalance($CommandID, $Initiator, $SecurityCredential, $PartyA, $IdentifierType, $Remarks, $QueueTimeOutURL, $ResultURL);`
### Confirmation and validation urls

### B2C Payment Request

This creates transaction between an M-Pesa short code to a phone number registered on M-Pesa.

**Transaction Status Request**
This is used to check the status of transaction.
```php
$mpesa= new \Safaricom\Mpesa\Mpesa();

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
$b2cTransaction=$mpesa->b2c($InitiatorName, $SecurityCredential, $CommandID, $Amount, $PartyA, $PartyB, $Remarks, $QueueTimeOutURL, $ResultURL, $Occasion);
```

`$trasactionStatus=$mpesa->transactionStatus($Initiator, $SecurityCredential, $CommandID, $TransactionID, $PartyA, $IdentifierType, $ResultURL, $QueueTimeOutURL, $Remarks, $Occasion);`
### Account Balance Request

This is used to enquire the balance on an M-Pesa BuyGoods (Till Number)

```php
$mpesa= new \Safaricom\Mpesa\Mpesa();

**B2B Payment Request**
$balanceInquiry = $mpesa->accountBalance($CommandID, $Initiator, $SecurityCredential, $PartyA, $IdentifierType, $Remarks, $QueueTimeOutURL, $ResultURL);
```

This is used to transfer funds between two companies.
### Transaction Status Request

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
This is used to check the status of transaction.

`$b2bTransaction=$mpesa->b2b($ShortCode, $CommandID, $Amount, $Msisdn, $BillRefNumber );`
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();`

$trasactionStatus = $mpesa->transactionStatus($Initiator, $SecurityCredential, $CommandID, $TransactionID, $PartyA, $IdentifierType, $ResultURL, $QueueTimeOutURL, $Remarks, $Occasion);
```

### B2B Payment Request

**C2B Payment Request**
This is used to transfer funds between two companies.

This is used to Simulate transfer of funds between a customer and business.
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();

$b2bTransaction = $mpesa->b2b($ShortCode, $CommandID, $Amount, $Msisdn, $BillRefNumber );
```

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
### C2B Payment Request

`$b2bTransaction=$mpesa->c2b($ShortCode, $CommandID, $Amount, $Msisdn, $BillRefNumber );`
This is used to Simulate transfer of funds between a customer and business.

_Also important to note is that you should have registered validation and confirmation urls where the callback responses will be sent._
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();

$b2bTransaction = $mpesa->c2b($ShortCode, $CommandID, $Amount, $Msisdn, $BillRefNumber );
```

_Also important to note is that you should have registered validation and confirmation urls where the callback responses will be sent._

**STK Push Simulation**
### STK Push Simulation

This is used to initiate online payment on behalf of a customer.

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();

`$stkPushSimulation=$mpesa->STKPushSimulation($BusinessShortCode, $LipaNaMpesaPasskey, $TransactionType, $Amount, $PartyA, $PartyB, $PhoneNumber, $CallBackURL, $AccountReference, $TransactionDesc, $Remarks);`
$stkPushSimulation = $mpesa->STKPushSimulation($BusinessShortCode, $LipaNaMpesaPasskey, $TransactionType, $Amount, $PartyA, $PartyB, $PhoneNumber, $CallBackURL, $AccountReference, $TransactionDesc, $Remarks);
```

### STK Push Status Query

This is used to check the status of a Lipa Na M-Pesa Online Payment.

**STK Push Status Query**
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();`

This is used to check the status of a Lipa Na M-Pesa Online Payment.

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
$STKPushRequestStatus = $mpesa->STKPushQuery($checkoutRequestID,$businessShortCode,$password,$timestamp);
```

`$STKPushRequestStatus=$mpesa->STKPushQuery($checkoutRequestID,$businessShortCode,$password,$timestamp);`
### Callback Routes

M-Pesa APIs are asynchronous. When a valid M-Pesa API request is received by the API Gateway, it is sent to M-Pesa where it is added to a queue. M-Pesa then processes the requests in the queue and sends a response to the API Gateway which then forwards the response to the URL registered in the CallBackURL or ResultURL request parameter. Whenever M-Pesa receives more requests than the queue can handle, M-Pesa responds by rejecting any more requests and the API Gateway sends a queue timeout response to the URL registered in the QueueTimeOutURL request parameter.

### Obtaining post data from callbacks

This is used to get post data from callback in json format. The data can be decoded and stored in a database.

**Callback Routes**
M-Pesa APIs are asynchronous. When a valid M-Pesa API request is received by the API Gateway, it is sent to M-Pesa where it is added to a queue. M-Pesa then processes the requests in the queue and sends a response to the API Gateway which then forwards the response to the URL registered in the CallBackURL or ResultURL request parameter. Whenever M-Pesa receives more requests than the queue can handle, M-Pesa responds by rejecting any more requests and the API Gateway sends a queue timeout response to the URL registered in the QueueTimeOutURL request parameter.
```php
$mpesa= new \Safaricom\Mpesa\Mpesa();

**Obtaining post data from callbacks**
This is used to get post data from callback in json format. The data can be decoded and stored in a database.

`$mpesa= new \Safaricom\Mpesa\Mpesa();`

`$callbackData=$mpesa->getDataFromCallback();`
$callbackData = $mpesa->getDataFromCallback();
```

**Finishing a transaction**
### Finishing a transaction

After obtaining the Post data from the callbacks, use this at the end of your callback routes to complete the transaction

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();

`$callbackData=$mpesa->finishTransaction();`

$callbackData = $mpesa->finishTransaction();
```

If validation fails, pass `false` to `finishTransaction()`

`$mpesa= new \Safaricom\Mpesa\Mpesa();`
```php
$mpesa = new \Safaricom\Mpesa\Mpesa();

`$callbackData=$mpesa->finishTransaction(false);`
$callbackData = $mpesa->finishTransaction(false);
```

## Multitenancy support

When handling transactions you do as follows

```php
/** Get client preferably from a database somewhere.
* You can use a dynamic url or even an api key to identify which client the transaction belongs to.
* This can be done using a middleware implementation triggered before the transaction is processed.
* (Ignore this part if you don't want Multitenancy support as it will default to the values in the .env file)
*/
$clientA = [
'MPESA_CONSUMER_KEY' => 'MPESA_CONSUMER_KEY_HERE',
'MPESA_CONSUMER_SECRET' => 'MPESA_CONSUMER_SECRET_HERE',
'MPESA_ENV' => 'MPESA_ENV_HERE'
];

// change the configs depending on the client
config(['services.mpesa' => $clientA ]);

// Instanciate the mpesa class ONLY after changing the configs
$mpesa = new \Safaricom\Mpesa\Mpesa();

// Do your business logic here
$b2bTransaction=$mpesa->b2b($ShortCode, $CommandID, $Amount, $Msisdn, $BillRefNumber );

```
Loading