API Reference - Prog Services

The Hubtel Programmable 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. Please see the expected response below

PUSH REQUEST


This is the request which Hubtel will send to your Service Interaction URL when a User dials your USSD code or selects your service on the Hubtel app or web mall.

Parameter

Type

Description

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 programmable service session. "AddToCart" - This is used to process the User to a checkout to pay.

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 Hubtel App, Online Mall, and Point Of Sales (POS) App, it may be blank for initiation type. But will have a value for Response type.

serviceCode

String

This represents either the USSD shortcode dialed. eg: "7112#" or the Id of the service. eg: "n383he9jioe923232347423".

Operator

String

For sessions initiated using USSD, this indicates the network operator of the user. Possible values are: "tigo", "airtel", "mtn", "vodafone". For Hubtel App, Online Mall, and Point Of Sales (POS) App, this indicates the specific Hubtel channel being used. Possible values are: "Hubtel-Android", "Hubtel IOS", "Android POS", "IOS HPOS", "Hubtel-Mall"

ClientState

String

It represents data that the service application asked the API to send from the previous request. This data is only sent in the current request and is then discarded.

Mobile

String

For USSD & Hubtel App users, this represents the phone number of the user dialing the code or selecting the service. For the Online Mall users, it represents a unique data ID for the client/user.

SessionId

String

This represents a unique identifier for the current programmable service session.

Sequence

Int

Indicates the position of the current message in the session.

Platform

String

This represents the actual platform channel being used for the Programmable service session. Possible Values are: "USSD", "HUBTEL APP", "HUBTEL POS", "WEB"


RESPONSE

This is the response your application is expected to provide to the push request from Hubtel.

Parameter

Type

Requirement

Description

SessionId

String

Mandatory

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

Type

Mandatory

This stipulates the type of 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 session. “AddToCart” – indicates that the application is ending the session for the data to be sent to checkout for payment.

Message

String

Mandatory

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 on Web & Hubtel Mobile Apps is found in the label, datatype and data parameters)

Mask

String

Optional

Indicates that the current message is masked.

Item

Object

Optional

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

ServiceCode

String

Optional

Can be used to pass back the service code by the Service Application.

Label

String

Mandatory

Represents the title message which will be displayed to a user using the Web or Mobile channels. It is meant to provide a richer user experience for such channels.

DataType

String

Mandatory

Represents the data type which can be used by the Web or Mobile Channels 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.

Data

Object

Optional

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

FieldType

String

Mandatory

"text" - This gives a simple text box and allows the user to type with an alphanumeric keyboad when using mobile. "phone" - This allows the user to type in a phone number with all needed validations using a phonic keyboard. "email" - This allows the User to type in an email address with an email keyboard. "number" - This allows the User to type in a whole number with a numeric keyboard. "decimal" - This gives a Numeric keyboard and allows for the user to type in a decimal number. , "textarea" - This shows a big text field for the user.

Sequence

Int

Optional

Indicates the position of the current message in the session.

ClientState

String

Optional

It represents data that the service application asked the API to send from the previous request. This data is only sent in the current request and is then discarded.


SAMPLE REQUEST FROM HUBTEL


{
  "Type": "initiation",
  "Message": "",
  "ServiceCode": "1a1bf6d0f399473bbf2e042a89af0ae0",
  "Operator": "HPOS-Android",
  "ClientState": "",
  "Mobile": "webstoreChrome1-bc",
  "SessionId": "2707b622998e47e6a4be2ac38ac835fa",
  "Platform": "Android"
}

SAMPLE RESPONSE FROM YOUR APP


{
    "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",
    "FieldType": "phone",
    "Data": null
}

Updated 18 days ago

API Reference - Prog Services


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.