README

The savannabits/daraja package is a Laravel package that makes it easier to talk to the Safaricom MPESA integration RESTFul API dubbed Safaricom Daraja.

Motivation

So why Daraja and not other packages out there? I have looked at a number of packages that can accomplish the same, but the solution I was looking for was a package that can allow me do token generation and Callback registration on the fly from my code. That means I can store my credentials (Consumer Key and consumer secret) even in a database and retrieve them dynamically, using them to register my callbacks. With this solution, you can even have a multiple shortcode gateway (Many apps each using a different paybill can use this gateway to talk to safaricom and register dynamic confirmation urls according to their needs).

Installation

You can install the package via composer:

composer require savannabits/daraja

Usage

Usage is very simple. If you are using C2B apis, the first step is to register the urls. Most of the work has been done for you under the hood.

Callback URLs Registration

 use Savannabits\Daraja\Daraja;
 
 $shortcode = "600737";//Your Paybill or till number here
 $confirmationURL = 'your dynamic validation url here';
 $validationURL = 'your dynamic validation url here'; // Optional. Leave null if you don't want validation
 $environment = "sandbox"; // or "live"
 $responseType = "Cancelled"; //Default Response type in case the validation URL is unreachable or is undefined. Either Cancelled or Completed as per the safaricom documentation
 $response = Daraja::getInstance()
      ->setCredentials("CONSUMER KEY","CONSUMER SECRET",$environment)
      ->registerCallbacks($shortcode, $confirmationURL, $validationURL,$responseType);

That's it. You can even put this code inside a Console Command class so that you run something like php artisna mpesa:register-callbacks from your terminal.

C2B simulation

If you are on Dev and would like to simulate a C2B transaction (without using any actual money) you can use the sandbox credentials and assuming you have registered the callbacks above, run the following:

    use Savannabits\Daraja\Daraja;
    /**
     * Here is the c2b Function documentation to help you understand the params:
     * Use this function to initiate a C2B transaction
     * @param $ShortCode | 6 digit M-Pesa Till Number or PayBill Number
     * @param $CommandID | Unique command for each transaction type. either "CustomerPayBillOnline" or "CustomerBuyGoodsOnline"
     * @param $Amount | The amount been transacted.
     * @param $Msisdn | MSISDN (phone number) sending the transaction, start with country code without the plus(+) sign.
     * @param $BillRefNumber | 	Bill Reference Number (Optional).
     * @return mixed|string
     */
    $shortcode = "YOUR SHORTCODE";
    $commandID = "CustomerPayBillOnline";
    $amount = 100;
    $msisdn = "07xxxxxxxx"; // See safaricom daraja documentation and check your credentials for the specific number given for testing.
    $billRefNumber = "THE PAYBILL ACCOUNT NO."; // e.g "MAMA MBOGA 212"
    $response = Daraja::getInstance()
                    ->setCredentials("YOUR CONSUMER KEY","YOUR CONSUMER SECRET","sandbox")
                    ->c2b($shortcode, $commandID, $amount, $msisdn, $billRefNumber);

STK Simulation (Lipa na MPESA Online)

Here is the method documentation

/**
 * Use this function to initiate an STKPush Simulation
 * @param $BusinessShortCode | The organization shortcode used to receive the transaction.
 * @param $LipaNaMpesaPasskey | The password for encrypting the request. This is generated by base64 encoding BusinessShortcode, Passkey and Timestamp.
 * @param $TransactionType | The transaction type to be used for this request. Only CustomerPayBillOnline is supported.
 * @param $Amount | The amount to be transacted.
 * @param $PartyA | The MSISDN sending the funds.
 * @param $PartyB | The organization shortcode receiving the funds
 * @param $PhoneNumber | The MSISDN sending the funds.
 * @param $CallBackURL | The url to where responses from M-Pesa will be sent to.
 * @param $AccountReference | Used with M-Pesa PayBills.
 * @param $TransactionDesc | A description of the transaction.
 * @param $Remark | Remarks
 * @return mixed|string
 */
\Savannabits\Daraja\Daraja::getInstance()
            ->setCredentials("CONSUMER KEY","CONSUMER SECRET","sandbox")
            ->STKPushSimulation($BusinessShortCode, $LipaNaMpesaPasskey, $TransactionType, $Amount, $PartyA, $PartyB, $PhoneNumber, $CallBackURL, $AccountReference, $TransactionDesc, $Remark);

    // Example
   $json = \Savannabits\Daraja\Daraja::getInstance()
            ->setCredentials("CONSUMER KEY","CONSUMER SECRET","sandbox")
            ->STKPushSimulation($app->short_code,$app->lnm_passkey,$app->transaction_type, $amount, $phone_number, $short_code, $phone_number, $confirm_callback,$account_ref, $transaction_desc, $comments);

Validation and Confirmation Callback example, Finishing a Transaction

use Savannabits\Daraja\Daraja;
class MyController extends \App\Http\Controllers\Controller {
    public function c2bValidationCallback(Request $request) {
        // Perform your validations here and set the status
        $status = true; // Or false based on whether you want to accept or reject the transaction.
        Daraja::getInstance()->finishTransaction($status);
    }
    public function c2bConfirmationCallback(Request $request) {
        //Get Response data
        $response = Daraja::getInstance()->getDataFromCallback();
        // $response = $request->all(); //Alternatively...
        // Do what you want with the data
        // ...
        // Finish Transaction
        Daraja::getInstance()->finishTransaction(true);
    }
    public function stkConfirmationCallback(Request $request) {
       $mpesa = new Daraja();
        // Get data from safaricom response.
       $data = $mpesa->getDataFromCallback();
       \Log::info($data);
        // Handle the data
        //...
        //Finish Transaction by sending acknowledgment to safaricom
        $mpesa->finishTransaction(true);
        
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email maosa.sam@gmail.com instead of using the issue tracker.

savannabits / daraja

Maintainers

Details