Proxy API

So, we have been working on a neat piece of art, an API for M-Pesa, named Proxy API.

And am proud to announce it is ready!

For quite some time, Developers have been trying (and mostly succeeding) in integrating with the First and Second generation M-Pesa APIs (G1 and G2 respectively). It was quite the effort, requiring VPNs and knowledge of SOAP/XML for you to work with the APIs. Well, they are actually great APIs, the most stable,and the most powerful. as long as one was able use them.

Next came Daraja, their new REST/JSON API. Developers were happy that they finally had an easier option to work with, and most decided to try out the new, better option. It was great at first…

Then the issues began.

Most of us have seen complaints of missing callbacks, long Go Live processes, Forms to fill in and upload (in this age of the Internet, imagine that), weird terminology used on the Documentation and API calls, no way to confirm what URLs are registered on their end e.t.c. That list can go on and on. So we decided to do something about it. We decided to create an M-Pesa API that could pretty much fix most of all issues. And that’s where the idea of Proxy API came from.

Proxy API was so named because it was designed to be literally a proxy: simply receiving requests, reformatting into the required XML format for M-Pesa, and forward the request to M-Pesa. But with that option came the capacity to do a lot more.

First, the API was designed to communicate directly with the M-Pesa G2 API, the most stable API and direct entry point into M-Pesa. Secondly, we decided to use REST/JSON to implement the Proxy API interface. This would make it easier to integrate into the API. We also decided, using the knowledge gained from working with G2, to simplify the API interface facing the developers. Another feature we added was tracing; we could trace requests from developer to M-Pesa and back, then a developer and even business could see what happened when they made a request. Developers could even see the status returned by their services once a callback has been returned or their endpoints called by the API. This would give the developer more control on their integration process and increase the speed with which they integrated into the system.

Then, with tracing requests, came the capability to keep records temporarily for clients to confirm which records or callbacks reached them or not. Clients could place requests to have undelivered callbacks saved and fetched later on demand. Well, this was as long as G2 actually called us too :-).

Thus, the new Proxy API provides the following features:

  • Real time logs and callbacks view
  • Instant C2B callback URLs (Validation and Confirmation URLs) modification
  • Intuitive REST/JSON API interface
  • Live support on Telegram, no emails if you want quick answers
  • No Go Live forms to fill or process, simply confirm ownership of your shortcode via an API call
  • Callback URL testing direct from the Portal

We also have more features in the pipeline for all clients, all building on the simple capability of proxying requests. Please check out the new API at
https://api.proxyapi.co.ke. The documentation for the API is at
https://docs.proxyapi.co.ke/v1/ and we even have an openapi/swagger specification at
https://docs.proxyapi.co.ke/v1/swagger/ .

Hope you enjoy it!

Co-op Bank Kenya API

So The Co-operative Bank of Kenya Ltd. seems to have unveiled a developer portal and exposed quite a number of APIs to work with their back-ends. These include:

  • Account Transactions
  • Exchange Rate
  • Internal Funds Transfer
  • Pesalink
  • Transaction Status Query
  • Account Balance
  • Account Transactions

Check it out at https://developer.co-opbank.co.ke:9443/store/

Interesting times coming up… 🙂

Upcoming M-Pesa API

So, I have been working on a new API. It will simply be dubbed “Proxy API

Will probably be released in the next 2+ months.

Will be prepaid, based on tokens/credits per API call (so it can support itself)

It will be my version of Daraja, but with some new features I believe developers really need. They include (for v1 of the API):

  • Almost real-time logs views for selected API calls
  • Instant callback URL change, including for C2B, via UI
  • As complete Documentation as I can possibly write, in tutorial form similar to my past tutorials (but I think this is obvious)
  • Admin statistics page**
  • Simpler and more intuitive REST/JSON API interfaces

It will be directly connected to Broker API, thus as the name suggests, will be basically a proxy to the SOAP/XML API similar to Daraja, but providing a customized REST/JSON interface to it.

Unfortunately, the first version will not have Lipa na Mpesa/STK Push API available, since there is no other more stable alternative public connection to the STK Push system apart from Daraja to work with. If I or anyone else finds an alternative, I am open to suggestions.

Forgive me if my perfectionist mind does not work fast enough, We all know how much we need an improvement on Daraja.

Coming Soon :-)…

#52WeekChallenge

There is a Challenge going around Local social circles (could be International) called the 52 Week Challenge. This challenge is a savings plan that seeks to motivate or encourage people to save a small amount each week, towards a final target at the end of the year. I have seen multiple variations of the challenge, and they all seem to provide a tidy sum to the ones who are able to hold out.

For those unfamiliar with the challenge, one of it’s versions goes along these lines:

  • Begin by choosing a starting amount which you are comfortable with e.g. Ksh. 50. This is what will be saved on the first week.
  • Choose an increment that will be added to the starting amount to get the amount to save for the second week. By default, the initial/starting amount is chosen.
  • For every successive week, the increment will be added to the total increments since the beginning of the plan, then added again to the previous week’s amount to get the current week’s amount to save. E.g. taking the initial amount as Ksh. 50, and taking increment = initial amount = Ksh. 50, we can get the following outline for the first month
    • Week 1: 0 + 0 + 50 = Ksh. 50 (previous total increments = 0, previous weekly amount = 0, current increment = 50)
    • Week 2: ((50 + 50) + 50) = Ksh. 150 (previous total increments = 50, previous weekly amount = 50, current increment = 50)
    • Week 3: ((100 + 50) + 150 ) = Ksh. 300 (previous total increments = 100, previous weekly amount = 150, current week’s increment = 50)
    • Week 4: ((150 + 50) + 300) = Ksh. 500 (previous total increments = 150, previous weekly amount = 300, current week’s increment = 50)
    • …and so on till the 52nd week where we shall have Ksh. 68900 as our final amount. Tidy sum, right? 😀

For those with the ability, you can change the initial value and the increment at your own volition to vary the amount you get at the end of the year. Of course the higher the better. 😉

Also, I really think its a good way to get some free cash to splash out on yourself/your friends at the end of the year. Who knows, you could use that cash for a trip anywhere you like (of course within your means).

Yes, we know, the economy is tough, so is life. So suck it up and get moving.

But I believe humans have quite a short lifespan, so they should spend some of it, if not most of it, enjoying the short time they have on this planet. Don’t argue with me…

So I decided to have some fun and create my own challenge calculator. I have modified mine to allow someone to change the incremental value added on each week e.g. if your initial amount was Ksh. 50, you can choose to decrease the increment for the second week by Ksh. 5 off the previous week’s increment, giving you Ksh. 45. We shall define the Ksh. 5 as the decrement. Add this to the first week’s amount of Ksh. 50 and you get Ksh. 145 to save for the second week. I have also allowed one to vary the time period they want to save for (in weeks). Using our previous example, for the first month, the savings plan, with a decrement of Ksh. 5 every week, will look something like this :

  • Week 1: (0 + 50) + 0 = Ksh. 50 (previous total increments = 0, previous amount = 0, current increment = 50
  • Week 2: ((50 + 45) + 50) = Ksh. 145 (previous total increments = 50, previous amount = 50, current increment = (50 – 5) = 45)
  • Week 3: ((95 + 40) + 145) = Ksh. 280 (previous total increments = (45 + 50), previous amount = 145, current week’s increment = (45 – 5) = 40)
  • Week 4: ((135 + 35) + 280) = Ksh. 450 (previous total increments = (50 + 45 + 40) = 135, previous amount = 280, current week’s increment = (40 – 5) = 35)

You can also choose to use the default decrement of 0 to use the default implementation of the plan.

NB: In some cases, while performing the calculations, there will be a time when the weekly increment will get to and go below 0 due to the subtractions on it when a decrement > 0 has been set. At that moment, we shall use the absolute value of the increment for your calculations to get the weekly deposit e.g. instead of -5, we shall use 5. You will not notice this without performing your own calculations, but this actually yields some interesting results. Play around with the calculator and see for yourself 😀


Results:

So, who’s up for a game of Savings? 😎

Changing Safaricom API C2B Validation and Confirmation URLs

For those who have integrated into Safaricom’s M-Pesa C2B APIs via both Daraja or Broker, you may need to change the URLs probably due to change/relocation of servers or location of your services. The steps involved are just a few as laid out below. You must be the owner of the actual Paybill receiving payments to be able to request the change of URLs.

  • Write a letter to APIfeedback@safaricom.co.ke using the business/company’s official letterhead requesting for a change in URLs
  • Include the Paybill number whose URLs are being replaced and new/replacement URLs, specifying which is the validation URL and which is the confirmation URL. If you are on Broker, also include the SPID used to register the URLs in the first place.
  • Send an email with the above letter scanned into PDF to APIfeedback@safaricom.co.ke.
  • They should respond to you after the request has been processed informing you to register your new URLs asap.

M-Pesa Portal Certificates

Safaricom’s M-Pesa portal, located at https://org.ke.m-pesa.com, requires you to have a pre-installed certificate that identifies you as a “valid” entity. If you have tried accessing this site and getting something similar to the below error or another access error/failure, it means the portal has refused your connection request due to absence of the SSL Certificate identifying you.

Fig. 1: M-Pesa portal error

To acquire this certificate, these are the steps to follow:

  • Send a blank email to M-PESACertpassword@safaricom.co.ke
  • You will receive an email in response after a short while (3-10 minutes) from the same email with a username and password like the one shown below (Fig. 2):
  • Go to the site https://vmtke.ca.vodafone.com/certsrv using Internet Explorer browser. Using any other browser will shout out a warning similar to “You are not using Internet Explorer. This application will not work correctly” or worse, fail with an error along the lines of “This page has not finished loading yet” as the site still uses VB on the back-end, which is not supported by any other browser (imagine that 👿 ). The browser will ask you for a username and password. Use the details received in the email above. The password is changed every week as specified in the email. If by any chance you cancelled the first username/password request,and subsequent requests automatically cancel, clear cookies and restart your IE browser, then try again.
Fig. 2: M-Pesa automated reply
  • Fill in the details as requested by the site, then press on Submit.
  • If you face any issues on submission e.g. the page shows the loading error below (Fig. 3), it means the browser is not yet compatible or has blocked some elements of the site. Try the steps shown after this to try and fix the problem
    • Go to Tools -> Compatibility View Settings
    • Add the site vodafone.com to the Compatibility View list
    • Go to Tools -> Internet Options -> Advanced
    • Under the Settings section, look for the options Use SSL 3.0, Use TLS 1.0,  Use TLS 1.1 and Use TLS 1.2 and check them all.
    • Go to Tools -> Internet Options -> Security
    • Click on Trusted Sites zone, then click on Sites under it
    • Add the site https://vmtke.ca.vodafone.com to the zone list, then click on OK
    • On the same tab, under Trusted Sites, click on Default Level to reset the security level defaults and show the levels slider, then set the Security level to Low on the slider
    • Restart/reopen your IE browser
  • Try submitting again. If the page submits successfully, the site might show you the message shown below (Fig. 4). If so, click on Yes. The resulting page then displays some info including a Request ID which can be used to track the request later on (Fig. 5).
  • Then you shall wait for between 2 – 10 days for them to process the application.
  • Once in a while, go back to the same site and click on the View the status of a pending certificate request link to view pending requests. If your request is processed, you shall get a download/install link for your certificate which you can use to download the certificate to install elsewhere, or simply install into IE if you prefer to use that browser for logging into your portal.
Fig. 3: IE Site Loading error

To install the certificate:

  • IE allows you to install the certificate automatically, but for other users, they need to download the certificate to their machines and perform the installation manually. Google for how to install custom certificates for your respective browser. The team has also provided documents on how to import and install the certificate (attached below)
  • Try loading the site https://org.ke.m-pesa.com/ again. It will ask you whether to use the newly installed certificate to identify you. Accept the prompt and you are good to go!
Fig 4. Site Confirmation Prompt
Fig. 5: Request ID received

This certificate can be installed and used on multiple machines within the same organization, thus eliminating the need to apply for a certificate for each machine BUT requires the private key associated with the certificate to be also exported. This is tricky, and requires some technical know-how. The site https://org.ke.m-pesa.com can also be run on any site able to execute JSP code and accepts custom certificates.

Hope this helps 🙂