Hubtel Developers

Suggest Edits

Online Checkout

 

Hubtel Online Checkout API gives your customers a simple checkout page for them to enter their mobile money wallet or bank card details. You do not need to worry about how to secure customer card or mobile money details.

The API presents RESTful endpoints that make it easy to integrate online payment into any application.

Authentication

Requests to the checkout API endpoints are authenticated using Basic Authentication. This requires you to provide a Base 64 encoding of your Api ID as your username and Api Key as your password. You can easily create an API User with Keys on your Hubtel account here.

API Endpoint

The Web Checkout Base URL is displayed during the process of adding API keys to your Hubtel account here.

You can also send an email to [email protected] to request for the API Endpoints which you will then use for your integrations.

Accessing your Account Number

You need to specify your Account Number during API requests. Successful deposits are paid into this account. The Account is tagged as a POS Sales Account on your account here

Suggest Edits

Create Checkout Invoice

This enables you to create a checkout invoice by providing the necessary details for your Customer to make payment on. Payment can be via mobile money, debit/credit card or Hubtel. After making payment, your website is notified through a redirect and your online system is also notified by a web callback.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://domain.website.com/checkout
{
  "items": [
    {
      "name": "Harry Potter",
      "quantity": 1,
      "unitPrice": 50
    },
    {
      "name": "Chinua Achebe",
      "quantity": 1,
      "unitPrice": 50
    }
  ],
  "totalAmount": 100,
  "description": "Book Shop Checkout",
  "callbackUrl": "https://webhook.site/8b4bbd0a-5f98-4b3d-abbe-b9b49767f7d5",
  "returnUrl": "http://hubtel.com/online",
  "merchantBusinessLogoUrl": "http://hubtel.com/online",
  "merchantAccountNumber": "11684",
  "cancellationUrl": "http://hubtel.com/online",
  "clientReference": "inv0012"
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "responseCode": "0000",
    "status": "Success",
    "data": {
        "checkoutUrl": "https://pay.hubtel.com/7569a11e8b784f21baa9443b3fce31ed",
        "checkoutId": "7569a11e8b784f21baa9443b3fce31ed",
        "clientReference": "inv0012",
        "message": "",
        "checkoutDirectUrl": "https://pay.hubtel.com/7569a11e8b784f21baa9443b3fce31ed/direct"
    }
}

Body Params

invoice
object
 
invoice.items
array of objects
required

The invoice items object specifies the list of items to display on the invoice page.

name
quantity
unit_price
itemImageUrl
totalAmount
string
required

Specifies the total amount expected to be paid for the Items being purchased.

description
string
required

describes to customers actions they can perform on the checkout page

callbackUrl
string
required

The callback URL registered to receive the final notification on the status of the payment.

returnUrl
string
required

The merchant website URL where the customer should return after payment.

cancellationUrl
string
required

The merchant website URL where the customer should return after cancellation.

merchantBusinessLogoUrl
string
required

The merchant business logo URL. The dimensions should ideally be a 100px X 100px.

merchantAccountNumber
string
required

This refers to the Account Number of your POS Sales Account

clientReference
string
required

A unique string identifying the request. Useful for reference purposes. It cannot be empty but must have a maximum of 10 characters.

 
Suggest Edits

Checkout Callback

 

You are required to implement a callback endpoint on your server to receive payment notification status on the payment or the order notification status.

We recommend using services like Webhook Tester, Request Catcher or ngrok to test your webhook callbacks. These services allow you to define temporary dummy endpoints which will show you the requests and all the data you are receiving from Hubtel.

Provide the dummy URL as the value for the PrimaryCallbackUrl or SecondaryCallbackUrl parameter.

Sample Web Checkout Webhook

  POST https://webhook.site/a8b36a02-5272-4a56-8e2b-15eab5e6bb71 HTTP/1.1
  Host: webhook.site
  Content-Type: application/json
  Cache-Control: no-cache
{
  "ResponseCode": "0000",
  "Status": "Success",
  "Data": {
    "CheckoutId": "99bb18b5-0745-4de7-ac08-72665431e40b",
    "SalesInvoiceId": "9f7d11d4d5d44d6eb5a159e6c47dcaec-20180518131450758",
    "ClientReference": "9246158385",
    "Status": "Success",
    "Amount": 600,
    "CustomerPhoneNumber": "+233541719387",
    "PaymentDetails": {
      "MobileMoneyNumber": "+233541719387",
      "PaymentType": "MobileMoney"
    },
    "Description": "Invoice paid successfully"
  }
}
Suggest Edits

Transaction Status Check

This allows a merchant to check for the current status of a transaction by providing a transaction identifier. A query to this endpoint returns the status of a mobile money or an online checkout transaction along with extra transaction data.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://domain.website.com
curl --request GET \
  --url https://domain.website.com/
var request = require("request");

var options = { method: 'GET', url: 'https://domain.website.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://domain.website.com/");

xhr.send(data);
import requests

url = "https://domain.website.com/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

Checkoutid
string

The checkout invoice ID generated from an online checkout.

networkTransactionId
string

The mobile money provider's transaction id.

hubtelTransactionId
string

The transaction id provided by Hubtel.

 

Sample Request

GET https://domain.website.com HTTP/1.1
Host: api.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250cG4=
Cache-Control: no-cache

Sample Response 

{
    "ResponseCode": "0000",
    "Data": [
        {
            "StartDate": "2017-08-23T15:35:17.967",
            "TransactionStatus": "Settled",
            "TransactionId": "8606d5b0c50342c6a35f40fdb95bde78",
            "NetworkTransactionId": "1846027922",
            "InvoiceToken": "57229a472e7f4eae",
            "TransactionType": "RECEIVE-MONEY",
            "PaymentMethod": "MOBILE-MONEY",
            "ClientReference": "DTX589298",
            "CountryCode": "GH",
            "CurrencyCode": "GHS",
            "TransactionAmount": 0.5,
            "Fee": 0.05,
            "AmountAfterFees": 0.45,
            "CardSchemeName": null,
            "CardNumber": null,
            "MobileNumber": "233574126849",
            "MobileChannelName": "tigo-gh",
            "TransactionCycle": [
                {
                    "Date": "2017-08-24T00:00:05.427",
                    "Status": "Settled"
                },
                {
                    "Date": "2017-08-23T15:36:47.277",
                    "Status": "Success"
                },
                {
                    "Date": "2017-08-23T15:35:17.967",
                    "Status": "Pending"
                }
            ],
            "RelatedTransactionId": null,
            "RelatedTransactionType": null,
            "Disputed": false,
            "DisputedAmount": 0,
            "DisputedAmountFee": 0,
            "TotalAmountRefunded": 0
        }
    ]
}
Suggest Edits

USSD Checkout

 

Hubtel USSD Checkout gives your customers a simple way for them to pay for services using their mobile money wallet. You do not need to worry about making any API calls

Authentication

You do not need to worry about API keys or Authorization Headers as Hubtel takes care of this for you.

How to be set up

You will need to send an email to [email protected] for your USSD code to be setup for USSD Checkout. You will be required to provide the following information in the email:

  1. Business Name and Hubtel Business Account ID (eg: PC Enterprise, HM1910009233)
  2. Your Hubtel USSD Code. (eg: 711123# etc)

How it Works

The Hubtel USSD Gateway uses data available in a USSD Session to make payment requests to the Hubtel Payement Gateway.

Three new parameters have been introduced to the Hubtel USSD API during the Release Stage.

  • Amount
  • Callback
  • Description

Whenever you wish to take a Payment after a Release, supply the parameters with the details as per your requirements.

A request will be made take funds from the Customer in the USSD Session. Once the customer makes payment, A Web Callback will be sent to your Callback URL.

Suggest Edits

USSD Checkout Callback

 

You are required to implement a callback endpoint on your server to receive payment notification after a USSD Checkout.

We recommend using services like Webhook Tester, Request Catcher or ngrok to test your webhook callbacks. These services allow you to define temporary dummy endpoints which will show you the requests and all the data you are receiving from Hubtel.

Provide the dummy URL as the value for the CallbackUrl parameter during the USSD Release.

Please note the USSD SessionId is passed as the ClientReference during the callback to your application.

Sample USSD Checkout Webhook

  POST https://webhook.site/a8b36a02-5272-4a56-8e2b-15eab5e6bb71 HTTP/1.1
  Host: webhook.site
  Content-Type: application/json
  Cache-Control: no-cache
{
  "ResponseCode": "0000",
  "Message": "success",
  "Data": {
    "Amount": 0.5,
    "Charges": 0.01,
    "AmountAfterCharges": 0.49,
    "Description": "The MTN Mobile Money payment has been approved and processed successfully.",
    "ClientReference": "8723229819121",
    "TransactionId": "c5d31224e2704fe7a2d18bfbdb9acb6a",
    "ExternalTransactionId": "6535578322",
    "AmountCharged": 0.5,
    "OrderId": "c5d31224e2704fe7a2d18bfbdb9acb6a"
  }
}
Suggest Edits

General Services

The General Services API has two main endpoints. The service interaction endpoint allows users to interact dynamically with your service application based on your own pre-designed flows.

The status notification endpoint allows your service application to inform the General Services API of the status of the service rendering (success/failure) after payment for the transaction has been made.

Request For the API Endpoint

You will need to send an email to [email protected] to request for the API Endpoints which you will then use for your integrations. You will be required to provide the following information in the email:

  1. Business Name and Hubtel Business Account ID (eg: PC Enterprise, HM1910009233)
  2. Service which you will be integrating with. (eg: SMS, SMPP, USSD, Sales etc)
  3. Use case/purpose of the integration. (eg: Integrating SMS API into a campus timetable app, etc)
  4. IP and port from which requests to the API will be sent. This is needed for whitelisting.
 
Suggest Edits

General Services Push Request

The Hubtel General Services API pushes service requests to the application URL you specify for that service in your Hubtel Account.

Your application will need to respond to the Push Service Request which has been outlined in the reference below.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://domain.website.com/your-service-application
{
  "type": "initiation",
  "message": "",
  "serviceCode": "1a1bf6d0f399473bbf2e042a89af0ae0",
  "operator": "HPOS-Android",
  "clientState": "",
  "mobile": "webstoreUser1",
  "sessionId": "2707b622998e47e6a4be2ac38ac835fa"
}

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "2707b622998e47e6a4be2ac38ac835fa",
    "type": "Response",
    "message": "Enter recipient's number (e.g. 0240101101):\r\n",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Enter recipient's number (e.g. 0240101101)",
    "dataType": "Input",
    "data": null,
  }
}

Body Params

type
string

This stipulates the type of G.S request. Possible values are: “initiation” – Indicates the beginning of a session (first message in the session) “response” – indicates the subsequent response in an already existing session. “release” – indicates that the user is ending the G.S session.

message
string

Represents the actual text entered by the User. For USSD Channels, this will represent the USSD string entered by the subscriber during initiation. For HPOS and Webstore, it may be blank for initiation type. But will have a value for Response type.

serviceCode
string

For USSD, this represents the USSD shortcode dialed. For HPOS and Webstore, this represents the Id of the service.

operator
string

For USSD, this indicates the network operator the subscriber belongs to. Possible values are: tigo, airtel, mtn, vodafone, glo. For HPOS and Webstore, this indicates the Hubtel channel being used by the User. Eg: Webstore, HPOS-Android, HPOS-ios, etc.

clientState
string

For USSD, it represents data that the service application asked the API to send from the previous USSD request. This data is only sent in the current request and is then discarded. For Other Channels, is left blank.

mobile
string

For USSD, this represents the phone number of the user dialing the code. For HPOS and Webstore, it represents a unique data ID for the client/user.

sessionId
string

This represents a unique identifier for the current G.S Session.

 
Suggest Edits

General Service Response

This represents the General Services response that must be sent to Hubtel from your Service Application.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://domain.website.com
curl --request POST \
  --url https://domain.website.com/
var request = require("request");

var options = { method: 'POST', url: 'https://domain.website.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://domain.website.com/");

xhr.send(data);
import requests

url = "https://domain.website.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "type": "response",
  "message": "0276912184",
  "serviceCode": "713*222",
  "operator": "mtn",
  "clientState": "",
  "mobile": "0246183214",
  "sessionId": "1379oe04198a4af9jab522e928aded31"
}

Body Params

status
string
required

Represents the success/failed status of the API call

message
string
required

Represents additional message on the status of the API call.

data
object
required

Contains the relevant information passed on in the response.

 
data.sessionId
string
required

This represents a unique identifier for the current G.S Session.

data.type
string
required

This stipulates the type of G.S response from the application. Possible values are: “response” – indicates the subsequent response in an already existing session. “release” – indicates that the application is ending the G.S session. “AddToCart” – indicates that the application is ending the G.S session for the data to be sent to checkout for payment.

data.message
string
required

Represents the actual text to be shown to a USSD User. A “\n” represents a new line in the text. Options are connoted by text. Eg: “\n1. Confirm” Additional data for a better user experience using Webstore & HPOS consumer apps is found in the label, datatype and data parameters)

data.mask
string

Indicates that the current message is masked.

data.maskNextRoute
string

Indicates that the next message is of vital importance (eg: pin number) so should be masked during transmission.

data.item
array of objects

Contains data that is sent during the AddToCart type response for checkout. For other response types, it must be empty.

data.serviceCode
string

Can be used to pass back the service code by the third party service app. Is left null.

data.label
string

Represents the title message which will be displayed to a user using the Webstore or HPOS applications. It is meant to provide a richer user experience for such channels. USSD does not use this parameter, but uses only the message parameter.

data.dataType
string

Represents the data type which can be used by the Webstore or HPOS applications for a richer user experience. These data types can be: “display”: this is used when a message is to be displayed. “input”: this is used when an input is required of the user. “confirm”: this is used when a Yes or No selection is to be made to either confirm a previous selection or not. It uses the display and value parameters for selection. “select”: this is used when a selection is to be made from multiple options. It also uses the display and value parameters for selection. “menu”: this is used to display a menu out of which a selection can be made. It also uses the display and value parameters for selection.

data.data
array of objects

Additional data that is added when the datatype parameter is set to either confirm, select or menu. It contains the data to be used for the selection.

 
Suggest Edits

Sample General Services Interaction 1

The following describes a sample interaction between a service application for MTN Data and the General Services API by a Customer using the Hubtel Webstore.

 

The General Services API sends the following request to the MTN Data Service application when the User selects that item on the business' webstore.

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
Accept: application/json
{
  "type": "initiation",
  "message": "",
  "serviceCode": "testmtndata",
  "operator": "web-store",
  "clientState": "",
  "mobile": "webstoreUser1",
  "sessionId": "88826304198a4a378ab522e928aded31"
}

The MTN Data Service Application sends the following response to the General Services API:

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "88826304198a4a378ab522e928aded31",
    "type": "Response",
    "message": "Enter recipient's number (e.g. 0240101101):\r\n",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Enter recipient's number (e.g. 0240101101)",
    "dataType": "Input",
    "data": null,
  }
}

The User responds to menu invitation by entering phone number . The General Services API sends the following request to the MTN Data Service application:

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
{
  "type": "response",
  "message": "0246912184",
  "serviceCode": "testmtndata",
  "operator": "web-store",
  "clientState": "",
  "mobile": "webstoreUser1",
  "sessionId": "88826304198a4a378ab522e928aded31"
}

The MTN Data Service Application sends the following response to the General Services API for the User to select a bundle:

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "88826304198a4a378ab522e928aded31",
    "type": "Response",
    "message": "Select Bundle\r\n Enter Selected Bundle:\r\n 1. Daily 20MB \r\n 2. Daily 50MB\r\n 2. Weekly 60MB\r\n 2. Weekly 300MB\r\n 2. More",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Select Bundle",
    "dataType": "select",
    "data": [
     {
        "display": "Daily 20MB",
        "value": "DAILY_20MB"
     },
     {
        "display": "Daily 50MB",
        "value": "DAILY_50MB"
     },
     {
        "display": "Weekly 60MB",
        "value": " WEEKLY_60MB"
     },
     {
        "display": "Weekly 300MB",
        "value": "WEEKLY_300MB"
     },
     {
        "display": "Monthly 1GB",
        "value": "MONTHLY_1GB"
     }
     ],
  }
}

The User responds by selecting a bundle. The General Services API sends the following request to the MTN Data Service application:

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
{
  "type": "response",
  "message": "DAILY_20MB",
  "serviceCode": "testmtndata",
  "operator": "web-store",
  "clientState": "",
  "mobile": "webstoreUser1",
  "sessionId": "88826304198a4a378ab522e928aded31"
}

The MTN Data Service Application sends the following response to the General Services API for the User to confirm the purchase:

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "88826304198a4a378ab522e928aded31",
    "type": "Response",
    "message": "Purchase Confirmation\nItem: MTN Daily 20MB Data for 233246912184\nPrice: 0.5\nQuantity: 1\r\n1. Confirm\r\n0. Cancel\r\n",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Purchase Confirmation\nItem: MTN Daily 20MB Data for 233246912184\nPrice: 0.5\nQuantity: 1",
    "dataType": "confirm",
    "data": [
      {
        "display": "Confirm",
        "value": "1"
      },
      {
        "display": "Cancel",
        "value": "0"
      }
    ]
  }
}

The User responds by confirming the purchase. The General Services API sends the following request to the MTN Data Service application:

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
{
  "type": "response",
  "message": "1",
  "serviceCode": "testmtndata",
  "operator": "web-store",
  "clientState": "",
  "mobile": "webstoreUser1",
  "sessionId": "88826304198a4a378ab522e928aded31"
}

Finally, the MTN Data Service Application sends the following response to the General Services API for the payment process to begin.

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "88826304198a4a378ab522e928aded31",
    "type": "AddToCart",
    "message": "Add to Cart",
    "mask": null,
    "maskNextRoute": null,
    "item": {
      "itemName": "MTN Daily 20MB Bundle for 233246912184",
      "qty": 1,
      "price": 0.5
    },
    "serviceCode": null,
    "label": null,
    "dataType": "display",
    "data": []
  }
}
Suggest Edits

Sample General Services Interaction 2

The following describes another sample interaction between a service application for Airteltigo Airtime and the General Services API by a Customer using the Hubtel USSD store (mobile)

 

The General Services API sends the following request to the Airteltigo Airtime Service application when the User selects that item on the business' Hubtel USSD store.

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
Accept: application/json
{
  "type": "initiation",
  "message": "*713*222#",
  "serviceCode": "713*222",
  "operator": "mtn",
  "clientState": "",
  "mobile": "0246183214",
  "sessionId": "1379oe04198a4af9jab522e928aded31"
}

The Airteltigo Airtime Service Application sends the following response to the General Services API:

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "1379oe04198a4af9jab522e928aded31",
    "type": "Response",
    "message": "Enter recipient's number (e.g. 0270101101):\r\n",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Enter recipient's number (e.g. 0240101101) ",
    "dataType": "Input",
    "data": null,
  }
}

The User responds to menu invitation by entering phone number . The General Services API sends the following request to the Airteltigo Airtime Service application:

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
{
  "type": "response",
  "message": "0276912184",
  "serviceCode": "713*222",
  "operator": "mtn",
  "clientState": "",
  "mobile": "0246183214",
  "sessionId": "1379oe04198a4af9jab522e928aded31"
}

The Airteltigo Airtime Service Application sends the following response to the General Services API for the User to enter an amount value:

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "1379oe04198a4af9jab522e928aded31",
    "type": "Response",
    "message": "Enter amount:\r\n",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Enter amount",
    "dataType": "Input",
    "data": null,
  }
}

The User responds by inputting an amount. The General Services API sends the following request to the Airteltigo Airtime Service application:

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
{
  "type": "response",
  "message": "10",
  "serviceCode": "713*222",
  "operator": "mtn",
  "clientState": "",
  "mobile": "0246183214",
  "sessionId": "1379oe04198a4af9jab522e928aded31"
}

The Airteltigo Airtime Service Application sends the following response to the General Services API for the User to confirm the purchase:

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "1379oe04198a4af9jab522e928aded31",
    "type": "Response",
    "message": "Purchase Confirmation\nItem: AirtelTigo Airtime for 233276912184\nPrice: 10\nQuantity: 1\r\n1. Confirm\r\n0. Cancel\r\n",
    "mask": null,
    "maskNextRoute": null,
    "item": null,
    "serviceCode": null,
    "label": "Purchase Confirmation\nItem: AirtelTigo Airtime for 233276912184\nPrice: 10\nQuantity: 1",
    "dataType": "confirm",
    "data": [
      {
        "display": "Confirm",
        "value": "1"
      },
      {
        "display": "Cancel",
        "value": "0"
      }
    ]
  }
}

The User responds by confirming the purchase. The General Services API sends the following request to the Airteltigo Airtime Service application:

POST /api/service-flow HTTP/1.1
Host: https://www.hubtel.com
Content-Type: application/json
{
  "type": "response",
  "message": "1",
  "serviceCode": "713*222",
  "operator": "mtn",
  "clientState": "",
  "mobile": "0246183214",
  "sessionId": "1379oe04198a4af9jab522e928aded31"
}

Finally, the Airteltigo Airtime Service Application sends the following response to the General Services API for the payment process to begin.

{
  "status": "success",
  "message": "Success",
  "data": {
    "sessionId": "1379oe04198a4af9jab522e928aded31",
    "type": "AddToCart",
    "message": "Add to Cart",
    "mask": null,
    "maskNextRoute": null,
    "item": {
      "itemName": "AirtelTigo Airtime Topup for 233276912184",
      "qty": 10,
      "price": 1
    },
    "serviceCode": null,
    "label": null,
    "dataType": "display",
    "data": []
  }
}
Suggest Edits

Response Codes

The Hubtel Sales API uses standard HTTP error reporting. Successful requests return HTTP status codes in the 2xx. Failed requests return status codes in 4xx and 5xx. Response codes are included in the JSON response body, which contain information about the response.

 
Response Code
Description
Action Required

0000

The transaction has been processed successfully.

0001

Sales API is not available.

Ensure that your're providing the correct Basic Auth key for the Authorization header. See authentication above for more details.

0002

The Order has been processed successfully. Payment will have to be completed manually as a cash sale after delivery.

4105

Authenticated hubtel organisation not owner of specified account number.

There's a mismatch of the Merchant Account number (Account ID) and the the Basic Authorisation key. Ensure your API keys are from the same Hubtel account.

2050

The MTN Mobile Money user has insufficient funds in wallet to make this payment.

Customer has to top up mobile money wallet with funds more than the amount being charged.

2051

The mobile number provided is not registered on MTN Mobile Money.

Ensure that the mobile number is registered on the MTN channel.

2100

The request failed as the customer's phone is switched off.

2101

The transaction failed as the PIN entered by the Airtel Money customer is invalid.

2102

The Airtel Money user has insufficient funds in wallet to make this payment.

2103

The mobile number specified is not registered on Airtel Money.

2152

The mobile number specified is not registered on Tigo cash.

2153

The amount specified is more than the maximum allowed by Tigo Cash.

2154

The amount specified is more than the maximum daily limit allowed by Tigo Cash.

2200

The recipient specified is not registered on Vodafone Cash.

2201

The customer specified is not registered on Vodafone Cash.

Suggest Edits

USSD Push Request

The Hubtel USSD API pushes USSD requests to the application URL you specify in your Hubtel account.

 
posthttp://yourhostname.com/ussd-app
{
   "Type":"Initiation",
   "Mobile":"233244123456",
   "SessionId":"bb3aece1deb543009c9f35b943c74b7f",
   "ServiceCode":"714",
   "Message":"*714#",
   "Operator":"Vodafone",
   "Sequence":1,
   "ClientState":null
}

//Download Google Gson: A Java serialization/deserialization library that can convert Java Objects into JSON and back. 
package com.smsgh;

import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.google.gson.Gson;

public class HelloUssdServlet extends HttpServlet {

    /*
     * Not needed by USSD API.
     */
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        resp.setContentType("text/plain");
		resp.getWriter().println("Hello USSD!");
    }

    /**
     * USSD API request is received as a POST request.
     */
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        // Use Gson JSON library to read and parse JSON request.
        Gson gson = new Gson();
        UssdRequest ussdRequest = gson.fromJson(req.getReader(), UssdRequest.class);
        
        // Log request in server's logs.
        getServletContext().log("Received USSD request: " + ussdRequest);
        
        // Since this is just a demo, release USSD session with a "Hello" message
        // to the mobile phone user.
        UssdResponse ussdResponse = new UssdResponse("Release",
            "Hello USSD! To: " + ussdRequest.Mobile);
        
        // USSD API accepts and requires JSON, so set content type accordingly.
        resp.setContentType("application/json");
        
        // Generate and send JSON response.
        String ussdResponseJson = gson.toJson(ussdResponse);
        resp.getWriter().print(ussdResponseJson);
    }      
}

class UssdRequest
{
    public String Type;
    
    public String Message;
    
    public String Operator;
    
    public String SessionId;
    
    public String Mobile;
    
    public int Sequence;
    
    public String ClientState;
    
    public String ServiceCode;
    
    @Override 
    public String toString() {
        return String.format("UssdRequest" +
            "[Mobile=%s, SessionId=%s, " +
            "Type=%s, Message=%s, Operator=%s, " +
            "Sequence=%s, ClientState=%s, ServiceCode=%s]",
            Mobile, SessionId, Type, Message, Operator, Sequence,					
                ClientState, ServiceCode);
    }
}

class UssdResponse
{    
    public String Type;
    
    public String Message;
    
    public String ClientState;
    
    public UssdResponse() {}
    
    public UssdResponse(String type, String message)
    {
        this.Type = type;
        this.Message = message;
    }
}            

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Web;
using System.Web.Helpers;
using System.Web.Mvc;

namespace HelloUssd.Controllers
{
    public class HelloUssdController : Controller
    {
        // GET: HelloUssd. Not needed by USSD API.
        public ActionResult Index()
        {
            return new ContentResult
            {
                ContentType = "text/plain",
                Content = "Hello USSD!"
            };
        }

        // POST: HelloUssd. USSD API request is received as a POST request.
        [HttpPost]
        [ActionName("Index")]
        public ActionResult IndexPost()
        {
            // Fetch request body as a string.
            BinaryReader inputStreamReader = new BinaryReader(Request.InputStream);
            byte[] requestBytes = inputStreamReader.ReadBytes(Request.ContentLength);
            string requestString = Request.ContentEncoding.GetString(requestBytes);
                            
            // Parse JSON request.
            UssdRequest ussdRequest = System.Web.Helpers.Json.Decode(requestString);

            // Since this is just a demo, release USSD session with a "Hello" message
            // to the mobile phone user.
            var resp = new { Type = "Release", Message = "Hello USSD! To: " + ussdRequest.Mobile };

            // USSD API accepts and requires JSON, so generate and send JSON response.
            return Json(resp);
        }
    }

    class UssdRequest
    {
        public String Type;

        public String Message;

        public String Operator;

        public String SessionId;

        public String Mobile;

        public int Sequence;

        public String ClientState;

        public String ServiceCode;
    }
}


header('Content-type: application/json; charset=utf-8'); 
$ussdRequest = json_decode(@file_get_contents('php://input')); 

    // Check if no errors occured. 
    if ($ussdRequest != NULL) { 

    // Create a response object. 
    $ussdResponse = new stdClass; 

    // Set the message to display. 
    $ussdResponse->Message = "Hello world $ussdRequest->Mobile"; 

    // Set the type of this response. 
    $ussdResponse->Type = "Release"; 

  // Encode the response object as JSON and send. 
  echo json_encode($ussdResponse); 
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "Message": "Welcome James Thompson. \n 1.Check Balance 2.Change PIN 3.Request Support.",
    "Type": "Response",
    "ClientState": null
}

Body Params

Mobile
string
required

Represents the phone number of the mobile subscriber. This is in the international format eg: 233244100410

SessionId
string
required

UUID string representing a unique identifier for the current USSD Session.

ServiceCode
string
required

Represents the USSD Service code assigned by the network.

Type
string
required

Indicates the type of USSD Request. Possible values are: Initiation:: indicates the first message in a USSD Session. Response:: indicates the subsequent response in an already existing USSD session. Release:: indicates that the subscriber is ending the USSD session. Timeout:: indicates that the USSD session has timed out.

Message
string
required

Represents the actual text entered by the mobile subscriber. For initiation, this will represent the USSD string entered by the subscriber. For Response, this will be the message sent.

Operator
string
required

Indicates the network operator the subscriber belongs to: Tigo, Airtel, MTN ,Vodafone, Safaricom

Sequence
int32
required

Indicates the position of the current message in the USSD session.

ClientState
string

Represents data that API client asked API service to send from the previous USSD request. This data is only sent in the current request and is then discarded.

 

USSD Response Parameters

This object represents the USSD response that must be sent to the user.

ATTRIBUTE
TYPE
DESCRIPTION
REQUIRED

Type

String

Indicates the type of USSD Request. Possible values are:
Response: indicates a response in an already existing USSD session.
Release: indicates that the application is ending the USSD session.

Yes

Message

String

Represents the actual message on the mobile subscriber’s phone.

Yes

ClientState

String (maximum of 100 characters)

Represents data that API client wants API service to send in the next USSD request. This data is sent in the next USSD request only and is subsequently discarded.

No

Description

String (maximum of 100 characters)

This parameter only applies for Hubtel USSD Checkout during a Release. This is the description of the Payment Request to be generated

No

Amount

Decimal

This parameter only applies for Hubtel USSD Checkout during a Release. This is the amount of the Payment Request to be generated

No

CallbackUrl

String

This parameter only applies for Hubtel USSD Checkout during a Release. This is the URL where Payment notices will be sent.

No

More Examples

The following describes an example where a mobile subscriber requests for an account balance via a USSD service. The subscriber sends a request: *711#.

The Hubtel USSD API sends the following request to the Client Resource (application):

POST 
Content-Type: application/json
Accept: application/json

{
    "Mobile": "233262183777",
    "SessionId": "8883ba8b1e7348b8b566b4b3396575d5",
    "ServiceCode": "711",
    "Type": "Initiation",
    "Message": "*711#",
    "Operator": "vodafone",
    "Sequence": 1
    "ClientState": null,
}

The application responds by sending out a menu requesting for pin

{
    "Type": "Response",
    "Message" : "Enter your pin",
    "ClientState": "2017-03-30",
    "MaskNextRoute": true  
}

The User responds to menu invitation by entering pin. The Hubtel USSD API sends the following request to the Client Resource:

POST 
Content-Type: application/json
Accept: application/json

{
    "Mobile": "233262183777",
    "SessionId": "8883ba8b1e7348b8b566b4b3396575d5",
    "ServiceCode": "711",
    "Type": "Response",
    "Message":  "1234",
    "Operator":"vodafone",
    "Sequence": 2,
    "ClientState":"2018-08-14"
}

The application responds by sending out a menu with multiple options

{
    "Message": "Dear Customer \n1. Account Balance \n2. Mini Statement",
    "Type": "Response", 
    "MaskNextRoute": true, 
}

The User responds to menu invitation by entering "1". The Hubtel USSD API sends the following request to the Client Resource:

POST 
Content-Type: application/json
Accept: application/json

{
    "Mobile": "233262183777",
    "SessionId": "8883ba8b1e7348b8b566b4b3396575d5",
    "ServiceCode": "711",
    "Type": "Response",
    "Message":  "1",
    "Operator":"vodafone",
    "Sequence": 3,
    "ClientState":null
}

The application responds by sending out a menu with multiple options

{
    "Message": "Your account balance is GHS 53,743",
    "Type": "Release", 
    "Mask": true, 
}
Suggest Edits

USSD Error Codes

The USSD Gateway throws an error if a USSD request is not processed appropriately, a system generated error message is sent to the mobile user. Below are the possible messages and their causes.

 
Error Code
Description

URNF

Your setup is not complete. Email [email protected] for assistance.

UUT

Our attempt to reach your application URL has timed out. Optimize your application and ensure that it is responding to requests within 7 seconds.

ST

The application took too long to respond. Either the app is too slow, or the subscriber took too long to respond to the USSD prompt. Please note that subscribers must respond within 60 seconds.

UUE

Your application is not responding with a valid JSON response. Check to see if your JSON response is valid.

NOCR

Your service is currently unavailable because you are out of credit on your Unity account. Top up your account here.

NOAPP

Your application is not yet mapped to any USSD Service Code. You can map your app URL here.

CSP

Hubtel is unable to forward your request to our upstream provider for onward processing. Contact [email protected] for assistance.

There are also Errors which will emanate from the Network Operator. A few of the errors which can be encountered are:

NETWORK ERROR CODE
DESCRIPTION

SERVICE UNAVAILABLE

The Network Provider is unable to display the USSD Menu because the service is not available.

UNABLE TO DISPLAY USSD

The Network Provider is unable to display the USSD Menu.

ERROR AT WASP E150

The Network Provider gives a negative response to the USSD Application.

REQUEST FAILS

The Network Provider does not recognise the USSD code.

ERROR WAP

The Network Provider is unable to process Code now.

Suggest Edits

Sending Messages

 

Request For the API Endpoint

You will need to send an email to [email protected] to request for the API Endpoints which you will then use for your integrations. You will be required to provide the following information in the email:

  1. Business Name and Hubtel Business Account ID (eg: PC Enterprise, HM1910009233)
  2. Service which you will be integrating with. (eg: SMS, SMPP, USSD, Sales etc)
  3. Use case/purpose of the integration. (eg: Integrating SMS API into a campus timetable app, etc)
  4. IP and port from which requests to the API will be sent. This is needed for whitelisting.
Suggest Edits

Quick Send

Waste no time installing SDK. Try out the Quick API.

 
gethttps://domain.website.com
curl --request GET \
  --url 'https://domain.website.com/?From=From&To=To&Content=Content&ClientID=ClientID&ClientSecret=ClientSecret'
var request = require("request");

var options = { method: 'GET',
  url: 'https://domain.website.com/',
  qs:
   { From: 'From',
     To: 'To',
     Content: 'Content',
     ClientID: 'ClientID',
     ClientSecret: 'ClientSecret' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/?From=From&To=To&Content=Content&ClientID=ClientID&ClientSecret=ClientSecret")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://domain.website.com/?From=From&To=To&Content=Content&ClientID=ClientID&ClientSecret=ClientSecret");

xhr.send(data);
import requests

url = "https://domain.website.com/"

querystring = {"From":"From","To":"To","Content":"Content","ClientID":"ClientID","ClientSecret":"ClientSecret"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "Status": 0,
    "MessageId": "0d225943d1844829b6a154aeb1d1671d",
    "Rate": 1,
    "NetworkId": "62001",
    "ClientReference": "1234"
}

Query Params

From
string
required

The sender address. In case it is a telephone number it must comply with the telephone rules.

To
string
required

The recipient telephone number. It must comply with the telephone rules.

Content
string
required

The message content

ClientID
string
required

Your Unity API Client ID

ClientSecret
string
required

Your Unity API Client secret

RegisteredDelivery
boolean

A true or false setting to indicate a delivery report request

 
Suggest Edits

Send Message

Send Message API helps you reach your customers with information. Improve your customer service with Hubtel Send Message API.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://domain.website.com
curl --request POST \
  --url https://domain.website.com/
var request = require("request");

var options = { method: 'POST', url: 'https://domain.website.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://domain.website.com/");

xhr.send(data);
import requests

url = "https://domain.website.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Content-Length: 102
Content-Type: application/json; charset=utf-8
Location: https://domain.website.com
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 13 Aug 2013 14:41:26 GMT

{
    "Status": 0,
    "MessageId": "43cceb19d2a242f58fb338692e12c0bb",
    "Rate": 0,
    "NetworkId": "0"
}

Body Params

Type
int32

Indicates the type of message to be sent. Possible values are: Unset(default) 0 - Text message 1 - Binary message 2 - Unicode based message

From
string
required

The sender address.Sender IDs must be 11 characters or less without spaces or 16 numbers.

To
string
required

The recipient telephone number. This number must be in the international telephone number format with a "+" as prefix. National numbers may be used if there is a guarantee that the Country Code set is valid for the recipient number. For example when the user’s country is “United States”, it is possible to send messages to the phone number "773-409-4910". The number must be a valid phone number

Content
string
required

The body of the message. This is required for all message types except WAP Push messages. Binary messages should use HEX string notation

Udh
string

The User Data Header of the SMS Message being sent. Udh must be HEX string notation.

Direction
string

Indicates if the message originated from this API ("out") or originated from a mobile subscriber ("in"). This attribute is only displayed in response to a query. Possible Values are "in" and "out".

Time
date-time

The is automatically converted to GMT, in case you want it in UTC, kindly change it in your Unity Account.

UpdateTime
date-time

Indicates when the message was last updated. Usually when the last delivery report was received on the message.

NetworkId
string

The unique ID for the mobile network a combination of MCC and MNC for this message.

ClientReference
string

A reference set by the client for uniquely identifying this message. The client reference will be sent as part of delivery report notifications.

RegisteredDelivery
boolean

A true or false setting to indicate a delivery report request.

Units(readonly)
int32

The number of parts or units of this message.

Rate(readonly)
int32

The total cost of this message. The default rate plan is messaging credit. Users on a service postpaid plan may have the rates defined in local currency.

Status(readonly)
string

The current delivery status of this SMS message.

FlashMessage
boolean

A true or false value indicating if this message must be sent as a flash message.

 
Suggest Edits

Get Message

You may want to know the details or the status of a particular message that you have sent in the past. Get Message API makes it possible in a simple way.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://domain.website.com
curl --request GET \
  --url https://domain.website.com/
var request = require("request");

var options = { method: 'GET', url: 'https://domain.website.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://domain.website.com/");

xhr.send(data);
import requests

url = "https://domain.website.com/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}

HTTP/1.1 200 Ok
Content-Length: 282
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 29 Aug 2017 08:16:48 GMT

{
    "MessageId": "6f19395db2fb497ea4ebd1e218dd3e4c",
    "From": "Seinti",
    "To": "+233208183783",
    "Time": "2013-06-02 10:56:34",
    "UpdateTime": "2013-08-12 17:11:42",
    "NetworkId": "62001",
    "Units": 1,
    "Rate": 1,
    "Status": "Undeliverable",
    "Content": "hello, Kwadwo!"
}

Path Params

messageId
string
required

The Id of the message you want to retrieve

 
Suggest Edits

Query Message

We are sure you will want to retrieve all the messages you have sent so Query Message API has been provided to make it possible.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://domain.website.com
curl --request GET \
  --url https://domain.website.com/
var request = require("request");

var options = { method: 'GET', url: 'https://domain.website.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://domain.website.com/");

xhr.send(data);
import requests

url = "https://domain.website.com/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
GET /v1/messages?index=100&limit=2 HTTP/1.1
Host: api.hubtel.com
Accept: application/json
Authorization: Basic aWlocGtoZHU6bnZtdnp2bWY=
 
Suggest Edits

Schedule Message

You will want to send a message at a particular time, but you may not be available at that time to send. Our SMS API allows you to schedule the message to be sent at the desired time.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://domain.website.com
curl --request POST \
  --url https://domain.website.com/
var request = require("request");

var options = { method: 'POST', url: 'https://domain.website.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://domain.website.com/");

xhr.send(data);
import requests

url = "https://domain.website.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Content-Length: 102
Content-Type: application/json; charset=utf-8
Location: https://domain.website.com
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 13 Aug 2017 14:41:26 GMT

{
    "Status": 0,
    "MessageId": "43cceb19d2a242f58fb338692e12c0bb",
    "Rate": 0,
    "NetworkId": "0"
}

Body Params

Type
string

Indicates the type of message to be sent. Possible values are: Unset(default) 0 - Text message 1 - Binary message 2 - Unicode based message

From
string
required

The sender address.Sender IDs must be 11 characters or less without spaces or 16 numbers

To
string
required

The recipient telephone number. This number must be in the international telephone number format with a "+" as prefix. National numbers may be used if there is a guarantee that the Country Code set is valid for the recipient number. For example when the user’s country is “United States”, it is possible to send messages to the phone number "773-409-4910". The number must be a valid phone number.

Content
string
required

The body of the message. This is required for all message types except WAP Push messages. Binary messages should use HEX string notation.

Time
date
required

The time at which you want the message to be sent

 
Suggest Edits

Reschedule Scheduled Message API

A message you scheduled can be rescheduled. This is done when the scheduled message failed or when you want to make changes to the time for the message to be sent earlier or later than the current time.

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://domain.website.com/messageId
curl --request PUT \
  --url https://domain.website.com/messageId
var request = require("request");

var options = { method: 'PUT',
  url: 'https://domain.website.com/messageId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/messageId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://domain.website.com/messageId");

xhr.send(data);
import requests

url = "https://domain.website.com/messageId"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
PUT /v1/messages/43cceb19d2a242f58fb338692e12c0bb HTTP/1.1
Host: https://domain.website.com
Accept: application/json
Authorization: Basic aWlocGtoZHU6bnZtdnp2bWY=
Content-Type: application/json
{
    "Time": "2017-08-09 05:00:00"
}

Path Params

messageId
date
required

Indicates when to send the message. It also indicates when a message was sent if this is an inbound message.

Body Params

Time
date
required

The time at which you would like to reschedule the message

 
Suggest Edits

Cancel Scheduled Message API

With this API, you can cancel a scheduled message that you no more want to send.

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://domain.website.com/messageId
curl --request DELETE \
  --url https://domain.website.com/messageId
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://domain.website.com/messageId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://domain.website.com/messageId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://domain.website.com/messageId");

xhr.send(data);
import requests

url = "https://domain.website.com/messageId"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "Status": 0
}

Path Params

messageId
string
required

The Id of the scheduled message you want to delete

 
Suggest Edits

Receive Message API

 
Suggest Edits

Receive Message

In case you want to receive message from your subscribers, what you need is the Short Code API.

 
posthttps://myapp.myserver.com/message/?fromtofulltextkeywordtextaccountcampaigndatenetwork
curl --request POST \
  --url 'https://myapp.myserver.com/message/?from=from&to=to&fulltext=fulltext&keyword=keyword&text=text&account=account&campaign=campaign&network=network&fromtofulltextkeywordtextaccountcampaigndatenetwork='
var request = require("request");

var options = { method: 'POST',
  url: 'https://myapp.myserver.com/message/',
  qs:
   { from: 'from',
     to: 'to',
     fulltext: 'fulltext',
     keyword: 'keyword',
     text: 'text',
     account: 'account',
     campaign: 'campaign',
     network: 'network',
     fromtofulltextkeywordtextaccountcampaigndatenetwork: '' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://myapp.myserver.com/message/?from=from&to=to&fulltext=fulltext&keyword=keyword&text=text&account=account&campaign=campaign&network=network&fromtofulltextkeywordtextaccountcampaigndatenetwork=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://myapp.myserver.com/message/?from=from&to=to&fulltext=fulltext&keyword=keyword&text=text&account=account&campaign=campaign&network=network&fromtofulltextkeywordtextaccountcampaigndatenetwork=");

xhr.send(data);
import requests

url = "https://myapp.myserver.com/message/"

querystring = {"from":"from","to":"to","fulltext":"fulltext","keyword":"keyword","text":"text","account":"account","campaign":"campaign","network":"network","fromtofulltextkeywordtextaccountcampaigndatenetwork":""}

response = requests.request("POST", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

from
string
required

The sender of the message

to
string
required

Recipient of the message

fulltext
string
required

The full text message including the keyword.

keyword
string
required

first word in the message

text
string
required

message without the keyword

account
string
required

your unity account Id

campaign
string
required

The unity campaign ID on which messages were received

date
date-time

message timestamp in the format YYYY-MM-DD HH:MM. For example the date will be formatted as (2009-05-24 18:00).

network
string
required

network MCC and MNC combination where known or only MCC otherwise. Refer to this article Mobile Country Code for more information

 

Event Data

Attribute
Type
Description

From

string

The sender of the message

To

string

Recipient of the message

MessageId

string

UUID (with no dashes). The ID of the message that was returned during sending operatio

ClientReference

string

The client reference that was used to send the message

Status

string

The status of the message. The following status are available:
Rejected
Submitted
Delivered
Buffered
Accepted
Undeliverable
Deleted
Expired
Received
Unknown
Error
Buffered Locally
Scheduled
Sent
Expired Locally
Out of Credit
SMSC Invalid
Blacklisted
Unrouteable
Exceeded Limited
Invalid Source Address
Invalid Destination Address
Invalid Message Length
Invalid Time
Invalid Message ID
Invalid Account ID/Number

Suggest Edits

Response Code

You will receive responses after sending a message and it is important for you to understand what each means. Below is a list of success and error codes you may get and their description.

 
Code
Subcode
Description

200

The request was successfully handled by the API

201

0

The request was successful and the message has been sent for onward delivery

100

General invalid request. Returned when no data is sent or a malformed request is received.

1

Invalid Destination address received. The recipient's phone number is not a valid phone number

2

Invalid Source address was sent. You need to be aware of the sender address restrictions.

3

The message body was too long.

400

4

The message is not routable on Hubtel gateway

5

The delivery time specified was not a valid time.

6

The message content was rejected or is invalid.

7

One or more parameters are not allowed in the message. Details will be provided as part of the response.

8

One or more parameters are not valid for the message. Details will be provided as part of the response.

401

The request authorization failed.

402

Your account does not have enough messaging credit to send the message.

403

Forbidden. It means that the recipient has not given his/her approval to receive messages.

404

The specified message was not found.

500

The request failed on the server.

502

Bad Gateway. The server could not find any appropriate gateway for the request.