API Reference - Prog Services

The Hubtel Programmable Services API pushes service requests to the service URLs 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: "711*2" 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	String	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 (via USSD)

{
    "Type": "initiation",
    "Mobile": "233200585542",
    "SessionId": "3c796dac28174f739de4262d08409c51",
    "ServiceCode": "713",
    "Message": "*713#",
    "Operator": "vodafone",
    "Sequence": 1,
    "ClientState": "",
    "Platform": "USSD"
}

SAMPLE RESPONSE FROM YOUR APP

{
    "SessionId": "3c796dac28174f739de4262d08409c51",
    "Type": "response",
    "Message": "Hubtel\n1. Airtime & Data\n2. Withdraw Money\n3. Send Money\n4. Pay A Business\n5. Web Login\n6. My Balance\n",
    "Label": "Hubtel",
    "ClientState": "100",
    "DataType": "input",
    "FieldType": "text"
}

SAMPLE REQUEST FROM HUBTEL (via Hubtel App)

{
  "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
}