k2-connect-node v1.2.1
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: 'example@example.com',
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
andaccess_token
- The response will contain:
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) andiat
(created at time)
- The response will contain:
TokenService.infoToken({accessToken: 'my_access_token'})
to get information on an access token.- The response will contain:
scope
,expires_in
,application.uid
,created_at
- The response will contain:
StkService
StkService.initiateIncomingPayment({ stkOptions })
:stkOptions
: A hash of objects containing the following keys:tillNumber
: Your online payments till number from Kopo Kopo's DashboardREQUIRED
firstName
: Customer's first namelastName
: Customer's last namephoneNumber
: Phone number to pull money from.REQUIRED
email
: Subscriber's email addresscurrency
: 3-digit ISO format currency code.REQUIRED
amount
: Amount to charge.REQUIRED
callbackUrl
: Url that the result will be posted toREQUIRED
paymentChannel
: Payment channel. Default is:"M-PESA STK Push"
.REQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
metadata
: It is a hash containing a maximum of 5 key value pairs
StkService.getStatus({ statusOpts })
:statusOpts
: A hash of objects containing the following keys:location
: The location url you got from the requestREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
This works the same for all requests that you get a location response.
For more information, please read https://api-docs.kopokopo.com/#receive-payments-from-m-pesa-users-via-stk-push
PayService
PayService.addPayRecipient({ payRecipientOptions })
:payRecipientOptions
: A hash of objects containing the following keys:type
: Recipient typeREQUIRED
- Mobile Wallet Recipient(
mobile_wallet
)firstName
: Pay recipient's first nameREQUIRED
lastName
: Pay recipient's last nameREQUIRED
phoneNumber
: Pay recipient's phone numberREQUIRED
email
: Pay recipient's email addressnetwork
: Pay recipient's networkREQUIRED
- Bank Account Recipient(
bank_account
)accountName
: Pay recipient's account nameREQUIRED
accountNumber
: Pay recipient's account numberREQUIRED
bankBranchRef
: Bank branch reference from the kopokopo dashboardREQUIRED
settlementMethod
: Settlement MethodREQUIRED
- External Till Recipient(
till
)tillNumber
: Pay recipient's till numberREQUIRED
tillName
: Pay recipient's till nameREQUIRED
- Paybill Recipient(
paybill
)paybillName
: Paybill nameREQUIRED
paybillNumber
: Paybill numberREQUIRED
paybillAccountNumber
: Paybill account numberREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
PayService.sendPay({ payOptions })
:payOptions
: A hash of objects containing the following keys:destinationType
: The destination typeREQUIRED
destinationReference
: The destination referenceREQUIRED
currency
: 3-digit ISO format currency code.REQUIRED
amount
: Amount to charge.REQUIRED
description
: Payment description.REQUIRED
category
: Payment category.tags
: Tags relevant to the payment. The tags should be comma separated.callbackUrl
: Url that the result will be posted toREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
metadata
: It is a hash containing a maximum of 5 key value pairs
PayService.getStatus({ statusOpts })
:statusOpts
: A hash of objects containing the following keys:location
: The location url you got from the requestREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
This works the same for all requests that you get a location response.
For more information, please read https://api-docs.kopokopo.com/#send-money-pay
TransferService
TransferService.createMerchantBankAccount({ accountOpts })
:accountOpts
: A hash of objects containing the following keys:accountName
: Settlement Account NameREQUIRED
settlementMethod
: Settlement MethodREQUIRED
bankBranchRef
: Settlement Bank Branch ReferenceREQUIRED
accountNumber
: Settlement account numberREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
TransferService.createMerchantWallet({ accountOpts })
:accountOpts
: A hash of objects containing the following keys:phoneNumber
: Phone number to settle toREQUIRED
network
: NetworkREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
TransferService.settleFunds({ settleOpts })
:settleOpts
: A hash of objects containing the following keys:destinationType
: The destination typeREQUIRED FOR A TARGETED TRANSFER
destinationReference
: The destination referenceREQUIRED FOR A TARGETED TRANSFER
currency
: 3-digit ISO format currency code.REQUIRED FOR A TARGETED TRANSFER
amount
: Amount to charge.REQUIRED FOR A TARGETED TRANSFER
callbackUrl
: Url that the result will be posted toREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
TransferService.getStatus({ statusOpts })
:statusOpts
: A hash of objects containing the following keys:location
: The location url you got from the requestREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
This works the same for all requests that you get a location response.
For more information, please read https://api-docs.kopokopo.com/#transfer-to-your-account-s
PollingService
PollingService.pollTransactions({ pollingOpts })
:pollingOpts
: A hash of objects containing the following keys:fromTime
: The starting time of the polling requesttoTime
: The end time of the polling requestscope
: The scope of the polling requestscopeReference
: The scope referenceREQUIRED for the 'Till' scope
callbackUrl
: Url that the result will be posted toREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
PollingService.getStatus({ statusOpts })
:statusOpts
: A hash of objects containing the following keys:location
: The location url you got from the requestREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
This works the same for all requests that you get a location response.
For more information, please read https://api-docs.kopokopo.com/#polling
SmsNotificationService
SmsNotificationService.sendTransactionSmsNotification({ transactionNotificationOpts })
:transactionNotificationOpts
: A hash of objects containing the following keys:webhookEventReference
: The webhook event reference for a buygoods_transaction_received webhook.message
: The message to be sentcallbackUrl
: Url that the result will be posted toREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
SmsNotificationService.getStatus({ statusOpts })
:statusOpts
: A hash of objects containing the following keys:location
: The location url you got from the requestREQUIRED
accessToken
: Gotten from theTokenService
responseREQUIRED
This works the same for all requests that you get a location response.
For more information, please read https://api-docs.kopokopo.com/#transaction-sms-notifications
Responses and Results
- All the post requests are asynchronous apart from
TokenService
. This means that the result will be posted to your custom callback url when the request is complete. The immediate response of the post requests contain thelocation
url of the request you have sent which you can use to query the status.
Note: The asynchronous results are processed like webhooks.
Author
Contributions
We welcome those with open arms just make a pull request and we will review.
Development
Run all tests:
$ npm install
$ npm test
Generate Docs:
$ ./node_modules/.bin/jsdoc lib -d docs
Issues
If you find a bug, please file an issue on our issue tracker on GitHub.
License
k2-connect-node is MIT licensed. See LICENSE for details.