Skip to content

A day or two with Hubtel’s HTTP API – My Thoughts

Posted in Personal, and Tech Review

As disgruntled as I was with Hubtel’s Mobile Money API last week, I’ve had no option than to go back to take a second look, this time, avoiding their non-existent non-up-to-date libraries, especially for Javascript. I wanted to take their HTTP API head on.

I did, and as a developer, I’m still not impressed with how the API is built to handle responses. It makes the life of a developer a handful, unnecessarily.

PS: I expect Johnny Walker to come walking all over this piece with his/her/it nonsense! Whoever you are, or whatever the team is behind such stupidity, for once in your life, get serious! Just once. Not much to ask.

You don’t have to take any of my ‘nonsense’ I share in this article into consideration, heck! I have ‘no real degree’, and I don’t know how to run a 96-man company.

However, don’t come ‘walking all over’ my blog to post messages helping us all determine who you are.

I believe developers “USING” a product are the ones who shape a product, and not only the ones who build. You don’t have to like what I say. We live in a free world. Move on!

Close to the end of this article, I share a proof of concept of how to work around some of the challenges I think Hubtel’s API presents.

I don’t like how and what I’ve done in getting things to work to some extent. However, who is ANYONE from Hubtel to tell me I’m doing something wrong! Can they, considering they’ve not built even a SINGLE, think of a showcase, application to explain HOW developers could make use of their API.

PS: Simply because PayPal or Stripe or any other payment platform in the world don’t exactly and or necessarily DO MOBILE MONEY payments does not mean there is nothing to learn from them.

I chip in this because before I can finish pronouncing Stri–, I’m told, ‘They don’t do Mobile Money’. And so what? Aren’t they Using APIs? Aren’t they using Websites? Aren’t they running on servers too? Was their platform not built by humans like us?

For one thing, I expected the 96+ workers of Hubtel spread across Africa to build a much interesting and presentable documentation pages. Their current documentation pages is a disaster.

Oh wait… Rave Pay, Stripe, PayPal and the others don’t do Mobile Money payments, so no need to learn from how they’ve made their API docs useful for developers to navigate.

Someone does not have to do EXACTLY what you do before you can learn from them.

The fact that Hubtel thinks they’re the ONLY ones doing Mobile Payments around the world, therefore they get to set the rules how they like is unfortunate.

We get it, you get to set the path, but please, as you do, add “Common Sense” Kakra!

Until that happens, I’ll take the ugly mess (yes looks way ugly) I have, and walk. To some extent, would work for now, with the hopes that one at least 1 person out of their 96+ workers spread across Africa would make a dent – a positive one.

With that out of the way, let’s get to the real code.

My Issues

I tried to produce a visual explaining how the current Hubtel API works with Mobile Money payments. I might not fully understand the workings, so I stand to be corrected. However, so far, this is what I know (click to enlarge):

Hubtel Mobile Money API process

Here are my concerns and worries

  • Why is the behavior for Airtel different from the rest?
  • Why is there a callback URL? Where from that idea or implementation? How can developers take advantage of it?
  • In a server-side app, how do I tell the user the transaction failed or succeeded if their use of the site it stateless (i.e they’re not logged in)?
  • In a single-page-app, how do I go about, when the API I made the first request to respond with a temporal ‘distin’ but the actual ‘distin’ will come later?

Before I go ahead to share more details, here’s how I expected the API to behave.

  • Simple, straightforward request and response straightforward
  • No need for callbacks
  • It either happened or not!
Hubtel API – What is can be

So, what are the benefits of the above approach?

  • A developer can make a single request, get a response and move on with his or her life. With the above approach, a call like this can just be made and done from the frontend:

And this request will be made to an API endpoint rigged like this:

The request-response stages are therefore simplified. When a developer, therefore, makes a request to the API, they know they’re getting a complete response, a response they can go ahead to deny or allow the user on their site the proceeding with an action.

All it takes is this:

  • Dev hits the API. Hubtel sends a message to the phone number
    • Hubtel starts a counter, say 15 seconds maximum
  • User receives message
    • If user confirms ‘yes’ within 15 seconds, Hubtel sends a success response to the Dev (0000)
    • If user confirms ‘no’ within 15 seconds, Hubtel sends a failure response to the Dev (2001)
    • If user DOESN’T confirm, Hubtel sends a failure (with the appropriate response code, i.e 2105 or the others)

Therefore, it would be up to the developer to, BEFORE making the request to the API, entreat the user to have their phone by their side to confirm, saying they have 10-15 seconds to confirm.

The advantages of such an approach are numerous:

  • For Hubtel
    • Hubtel cleans their hands off EVERY transaction within 15 or 30 seconds. If anything, DO IT AGAIN!
    • There is NO need for callbacks logic whatever. Just ‘Wait for me. Here. Go!’
    • Reduces API requests to be made.
      • Current approach is
        • dev —-> H.API (hubtel)
        • H.API —-> dev (temporal response) (if not airtel money)
        • H.API —-> dev (callback)
        • dev —-> magically finds out if the callback is in
      • Suggested approach is
        • dev —-> H.API (hubtel)
        • H.API —-> dev (case closed)
  • For the Developer
    • Developer request boils down to only 1 request. The request that initiates the transaction gets the response back
    • Developer implements a much easier User feedback process in a seamless manner.
    • No if/else logic here and there, just pure Observables (@Bubu, you dey?)

In all, no one is asking Hubtel to fire the 96+ workers they have across Africa. As a developer, all I’m saying is, you can implement a better mobile money payment process, both for yourself ease and to the potential developers interested in the platform.

I’m not asking them to do anything that’ll go against what they currently have. All I’m asking are actually ways to make both of us enjoy using the platform. It’ll be simpler for Hubtel, and seamless for lazy developers like myself.

It’s About Time – A Developer Advocate Role

Does the 96+ workers of Hubtel spread across Africa include any Developer Advocate?

Not that I know of. Who is a Developer Advocate then?

Definition: “A developer advocate is someone who’s primary responsibility is to make it easy for developers to use a platform.”

Does Hubtel have anyone who’s “primary responsibility is to make it easy for developers to use” their APIs and or Platform?

Do they?

Companies the size of Hubtel I know of DO have Developer Advocates. Aside from the developers building the tools, they have the advocates, who ACTUALLY build using the tools, and in the process LEARN the challenges and ways to make it better.

As it stands now, there’s NO known (at least to me) application built by the Hubtel team that explains HOW their API could be used in REAL WORLD Applications.

And so they’re there, thinking because PayPal and Stripe don’t do Mobile Money Payments, ‘them do all’. But they say, the ‘Devil is in the Details’.

Developer advocates, through use (like what I’m doing), bring out the devils from the details.

I found some devils, and yet I’m the one who’s delusional who has something against Hubtel because I wasn’t offered a job whatnot.

For the record, I’ve not applied for a role at Hubtel before, but I’m hoping the “Developer Advocate Role” is opened soon, so I can apply, be rejected, and then Johnny Walker’s allegation would be true by then!

Me: Waiting for a “Developer Advocate Role” at Hubtel

I think filling such a role at Hubtel would help channel my frustration into solving a lot of developers facing challenges like me.


Take a look at how I’m approaching this whole “Go, I’ll get back to you later” scenario. The pseudocode is this

  • Make request to API
  • If response says 0000 or 2001, it means it is Airtel, therefore Client proceeds to show success
  • If response is 0001, it means we have to wait for callback
    • The 0001 response to client triggers a setInterval() function to run, polling an endpoint every 15 seconds.
    • When the callback from Hubtel is sent to this endpoint, the POST is saved to DB (mongodb)
    • The polling request would query to find if there’s a trans_id matching what the 0001 had.
    • It shall keep polling at 15 seconds interval until something is found
    • If something is found, show response and proceed appropriately to show either success or error message

As the polling happens, the user in the browser will be shown the “Wait for the transaction to complete” feedback.

Throw any PR or Issues at the repositories above. If there’s a better way to do the above, kindly enlighten me.

And ooh, shall we all wait for Mr. Johnny Walker in the comments…