Kopokopo Node.js SDK

This is a module to assist developers in consuming Kopokopo's API

Installation

To install run the following command on your project's directory:

npm install --save k2-connect-node

Initialisation

The package should be configured with your client id and client secret which you can get from your account on the kopokopo's app

//Having stored your credentials as environment variables
const options = {
  clientId: process.env.K2_CLIENT_ID,
  clientSecret: process.env.K2_CLIENT_SECRET,
  baseUrl: process.env.K2_BASE_URL,
  apiKey: process.env.K2_API_KEY
}

//Including the kopokopo module
var K2 = require("k2-connect-node")(options)

Note: The baseUrl can be custom for testing purposes but we recommend using the sandbox base url during development.

After initialization, you can get instances of offered services as follows:

Tokens : var TokenService = K2.TokenService
Webhooks : var Webhooks = K2.Webhooks
STK PUSH : var StkService = K2.StkService
Pay : var PayService = K2.PayService
Transfer : var TransferService = K2.TransferService
Polling : var PollingService = K2.PollingService
Transaction Sms Notification : var SmsNotificationService = K2.SmsNotificationService

Usage

The package needs to be configured with your kopokopo's clientId and Secret Key, which you can get from the kopokopo application.

Tokens

To send any requests to Kopokopo's API you'll need an access token

const TokenService = K2.TokenService

TokenService
    .getToken()
    .then(response => {
        //Developer can decide to store the token_details and track expiry
        console.log("Access token is: " + response.access_token)
    })
    .catch( error => {
        console.log(error)
    })

Webhooks

Consuming

const Webhooks = K2.Webhooks

//Router or whatever server you are using
router.post('/customercreated', function(req, res, next){  
    // Send message and capture the response or error
    Webhooks
        .webhookHandler(req, res)
        .then( response => {
            console.log(response)
        })
        .catch( error => {
            console.log(error)
        })
})

Subscription

const subscribeOptions = { 
    eventType: 'buygoods_transaction_received', 
    url: 'https://my-valid-url.com/endpoint', 
    accessToken: 'my_access_token',
    scope: 'till',
    scopeReference: '123456'
}

Webhooks 
    .subscribe(subscribeOptions) 
    .then( response => {
       console.log("The location url is: " + response) 
	}) 
    .catch( error => {
		console.log(error) 
	})

To get the status of the webhook subscription

const statusOptions = { 
    location: 'https://sandbox.kopokopo.com/webhook_subscriptions/c7f300c0-f1ef-4151-9bbe-005005aa3747',
    accessToken: 'my_access_token'
}

Webhooks 
    .getStatus(statusOptions) 
    .then( response => {
		console.log("The status is: " + response) 
	}) 
    .catch( error => {
		console.log(error) 
	})

STK PUSH

const StkService = K2.StkService

var stkOptions = {
    tillNumber: K000000,
    firstName: 'Jane',
    lastName: 'Doe',
    phoneNumber: '+254712345678',
    email: '[email protected]',
    currency: 'KES',
    amount: 20,
    callbackUrl: 'https://my-valid-url.com/endpoint',
	  paymentChannel => 'M-PESA STK Push',
    accessToken: 'my_access_token',

    //A maximum of 5 key value pairs
    metadata: {
		customerId: '123456789',
		reference: '123456',
		notes: 'Payment for invoice 123456'
    }
  }

  // Send message and capture the response or error

  StkService
    .initiateIncomingPayment(stkOptions)
    .then( response => {     
		console.log(response)
    })
    .catch( error => {
      	console.log(error)
    })

For other usage examples check out the example app.

Services

The methods are asynchronous.

The only supported ISO currency code at the moment is: KES

`TokenService`

TokenService.getToken() to get an access token.
- The response will contain: token_type, expires_in, created_at and access_token

NB: The access token is required to send subsequent requests

TokenService.revokeToken({accessToken: 'my_access_token'}) to revoke an access token.
- The response will be an empty body

NB: A revoked access token cannot be used on subsequent requests

TokenService.introspectToken({accessToken: 'my_access_token'}) to get introspect a token.
- The response will contain: token_type, client_id, scope, active, exp(Expiry time) and iat(created at time)
TokenService.infoToken({accessToken: 'my_access_token'}) to get information on an access token.
- The response will contain: scope, expires_in, application.uid, created_at