Giter VIP home page Giter VIP logo

mpesa-online's Introduction

mpesa-online

gitter Maintainability

A lightweight library for node.js that simplifies integrating your website/web app to mpesa using the Lipa na mpesa online payment API . The API documentation is quite adequate and contains sufficient code samples for several languages, you can check it out here. If you don't have a developers' account , please register and create an app. This step is very important in order to access test short codes and credentials required by the API.

This library provides a quick and painless means to integrate to MPESA. It will be useful to developers that want to get up and running as fast as possible and also presents an opportunity to effortlessly test the payment experience for those who are unfamiliar with the process.

Installation

$ npm i mpesa-online

Initiate mpesa transaction (processRequest)

The mpesaRequest() method expects 2 arguments - a params object and the request type (in this case processRequest). This request type will initiate an mpesa transaction and a USSD payment prompt (STK push) will be sent to your mobile device.

const MpesaOnline = require('mpesa-online')
const mpesa = new MpesaOnline()

mpesa.mpesaRequest(params, 'processRequest')
  .then(response => console.log(response))
  .catch(error => console.log(error))

A sample of the params object:

const params = {
  'BusinessShortCode': '', // The organization shortcode used to receive the transaction.
  'TransactionType': 'CustomerPayBillOnline', // The transaction type to be used for this request.
  'Amount': '1', // Amount to be charged / paid
  'PartyA': '', // The mobile number sending the funds.
  'PartyB': '', // The organization shortcode receiving the funds
  'PhoneNumber': '', // The mobile number sending the funds.
  'CallBackURL': '', // The url to where responses from M-Pesa will be sent to.
  'AccountReference': '', // Used with M-Pesa PayBills
  'TransactionDesc': 'Testing mpesa online',
  'consumerKey': '',
  'consumerSecret': '',
  'passKey': '', // Used to create a password for use when making a Lipa Na M-Pesa Online Payment API calls
  'authenticationURL': 'https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials', // MPESA authentication end point
  'processRequestURL': 'https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest' // MPESA request processing end point
}

You can retrieve the BusinessShortCode (Lipa Na Mpesa Online Shortcode), PartyB and passKey (Lipa Na Mpesa Online Passkey) values here. A link to the test credentials is provided in the instructions.

To obtain the consumerKey and consumerSecret:

  1. Login to the developers' portal
  2. Click on your app.
  3. The 'Keys' tab contains both keys.

When you run your code, you should receive a USSD payment prompt(STK push) on your mobile device:

STK push

Check payment status(queryRequest)

The queryRequest request type checks the status of the payment.

const params = {
  'BusinessShortCode': '',
  'CheckoutRequestID': '',
  'consumerKey': '',
  'consumerSecret': '',
  'passKey': '',
  'authenticationURL': '',
  'queryRequestURL': 'https://sandbox.safaricom.co.ke/mpesa/stkpushquery/v1/query'
}
mpesa.mpesaRequest(params, 'queryRequest')
  .then(response => console.log(response))
  .catch(error => console.log(error))

Connecting the dots...

A snippet demonstrating how to make an mpesa payment request and query for the payment status.

// Add the mpesa-online module
const MpesaOnline = require('mpesa-online')
const mpesa = new MpesaOnline()

// The params required to make a processRequest
const processRequestParams = {
  'BusinessShortCode': '',
  'TransactionType': 'CustomerPayBillOnline',
  'Amount': '1',
  'PartyA': '',
  'PartyB': '',
  'PhoneNumber': '',
  'CallBackURL': '',
  'AccountReference': '4002',
  'TransactionDesc': 'Testing mpesa online',
  'consumerKey': '',
  'consumerSecret': '',
  'passKey': '',
  'authenticationURL': 'https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',
  'processRequestURL': 'https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest'
}

// Use processRequest to receive the USSD payment prompt(STK push) on your mobile device
mpesa.mpesaRequest(processRequestParams, 'processRequest')
  .then(response => {
    // If the response code is '0'(a success), query to check the status of the payment
    if (response.ResponseCode === '0') {
      poll(() => {
        const queryRequestParams = {
          'BusinessShortCode': '',
          'CheckoutRequestID': response.CheckoutRequestID,
          'consumerKey': '',
          'consumerSecret': '',
          'passKey': '',
          'authenticationURL': 'https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',
          'queryRequestURL': 'https://sandbox.safaricom.co.ke/mpesa/stkpushquery/v1/query'
        }
        return mpesa.mpesaRequest(queryRequestParams, 'queryRequest')
          .then(response => response) // Anything resolved will be handled here
          .catch(error => error) // Anything rejected will be handled here
      }, 10000, 1000) // Let's query for the payment status every second for 10 seconds, to cater for any little delay in processing
        .then(response => console.log(response))
        .catch(error => {
          // An error occured, handle it
          console.log(error)
        })
    } else {
      // An error occured, handle it
      console.log(response)
    }
  })
  .catch(error => {
    // An error occured, handle it
    console.log(error)
  })

const poll = (fn, timeout, interval) => {
  const endTime = Number(new Date()) + (timeout)
  const query = (resolve, reject) => {
    fn()
      .then(result => {
        if (result.ResponseCode === '0') {
          // Payment successful
          resolve(result)
        } else if (Number(new Date()) < endTime && (result.errorCode === '500.001.1001' &&
          result.errorMessage === 'The transaction is being processed')) {
          // Payment pending, continue querying
          console.log('continue polling', result)
          setTimeout(query, interval, resolve, reject)
        } else if (Number(new Date()) > endTime) {
          // Configured timeout period has lapsed, handle it
          reject(result)
        } else {
          // An error occured, handle it
          reject(result)
        }
      })
      .catch(error => {
        // An error occured, handle it
        reject(error)
      })
  }
  return new Promise(query)
}

License

MIT

mpesa-online's People

Contributors

njunge11 avatar

Watchers

James Cloos avatar Khadija Mahanga avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.