0% found this document useful (0 votes)
120 views63 pages

Hubtel Commision Services API (v01.08.20)

Uploaded by

Alex Tuo
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
120 views63 pages

Hubtel Commision Services API (v01.08.20)

Uploaded by

Alex Tuo
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 63

Hubtel Commission Services

API Documentation

1
API Change Log
Changes between document issues are cumulative. The latest document issue contains all
the changes made in earlier issues.
Issue 1 (2019-12-23)
This issue is the first official release
Issue 2 (2020-01-19)
This update includes Query endpoint for Hubtel Prepaid balance
Issue 3 (2020-08-01)
This update includes newly added services.

2
Contents
API Change Log ....................................................................................................................................... 2

1.0 Overview ..................................................................................................................................... 5

2.0 Base Endpoint ............................................................................................................................. 5

3.0 Getting Started With The Hubtel Commission Services API ..................................................... 5

3.1 Authentication .............................................................................................................................. 5

4.0 Core Features Of The Hubtel Commission Services API ............................................................ 6

4.1 Airtime Topups .............................................................................................................................. 6

4.1.1 MTN Airtime Top-Up .......................................................................................................... 6

4.1.2 Vodafone Airtime Topup ....................................................................................................... 8

4.1.3 AirtelTigo Airtime Top-Up ................................................................................................... 10

4.1.4 Glo Airtime Top-Up.............................................................................................................. 12

4.2 Data & Voice Bundle Services .................................................................................................... 14

4.2.1 MTN Data Bundle Query ..................................................................................................... 14

4.2.2 MTN Data Bundle Top-Up ................................................................................................ 16

4.2.3 Vodafone Data Query....................................................................................................... 19

4.2.4 Vodafone Data Bundle Top-Up ........................................................................................ 21

4.2.5 Glo Data Bundle Query..................................................................................................... 23

4.2.6 Glo Data Bundle Top-up ................................................................................................... 25

4.2.7 AirtelTigo Data Bundle Query .......................................................................................... 27

4.2.8 AirteTigo Data Bundle Top-up ......................................................................................... 30

4.2.8 AirtelTigo Voice Bundle Query ......................................................................................... 32

4.2.9 AirtelTigo Voice Bundle Top-up ....................................................................................... 34

4.2.10 Surfline Data Bundle Query ........................................................................................... 37

4.2.11 Surfline Data Bundle Top-Up ........................................................................................... 39

4.2.12 Busy 4G Data Bundle Query ............................................................................................. 41

4.2.13 Busy 4G Data Bundle Top-Up ........................................................................................... 44

3
4.3 Utility Bill Payments ................................................................................................................... 46

4.3.1 DSTV Account Query ........................................................................................................ 46

4.3.2 DSTV Bill Payment ............................................................................................................ 48

4.3.3 GoTV Account Query ........................................................................................................ 50

4.3.4 GoTV Bill Payment ............................................................................................................ 52

4.3.5 ECG Postpaid Account Query ........................................................................................... 54

4.3.6 ECG Postpaid Bill Payment ............................................................................................... 56

4.4 Others ......................................................................................................................................... 58

4.4.1 Query Hubtel Account Balance ........................................................................................ 58

5.0 API Response Codes ................................................................................................................. 61

Contact Us ........................................................................................................................ 62

4
1.0 Overview

The Hubtel Commission Services API has a set of developer tools and products that help
businesses, financial organizations and individuals to facilitate bill payments, airtime top-ups
and various digital services for customers.

2.0 Base Endpoint

All requests to the Commission Services API will be sent to the base URLs below with the
corresponding parameter formats.

Parameter Value

Base URL https://cs.hubtel.com/commissionservices

Request Parameter Format JSON

3.0 Getting Started With The Hubtel Commission Services API


First you need to create a Hubtel Account to be able to use the Commission Services API.
If you already have a Hubtel account, then skip to step 2.

Step 1: Create a Hubtel Account


Step 2: Have the Account Verified and approved.
Step 3: Create API Credentials for integration.
Step 4: Send an email to [email protected] for your new API credentials to be given access.
Just share the API ID. Kindly keep the API secret hidden and do not share with anyone.

3.1 Authentication
You need to authenticate every API request you make to the Commission Services API using
Basic Auth. Authenticate by encoding your username and password to Base64 HTTP Basic

5
Authorization. Use your API Key as your username and API Secret as your password. A
sample API Key and API Secret looks like these respectively: kpsxolou and ixahwlao.

A Base64 encoding of your API keys should have your Authorization header appear like this:
Basic a2hlcW2sb3U6bWdhtHd9YW8=.

NB: For every request, you will need to include your Hubtel Prepaid Deposit Account ID in
the URL. You can find this when you log in to your Hubtel account here: https://app-
site.hubtel.com/money/accounts

4.0 Core Features Of The Hubtel Commission Services API


The core services are broken down into three main kinds: Airtime Top-ups, Data Bundles and
Utility Payments. The details of how to integrate with each of the services can be found below.

4.1 Airtime Top-ups

4.1.1 MTN Airtime Top-Up

This endpoint is used to top up an MTN account with Airtime.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/fdd76c884e61
API Endpoint
4b1c8f669a3207b09a98

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the airtime


Destination String Mandatory
value.

6
The airtime value to be sent during this
Amount Double Mandatory
transaction. Eg: 0.5

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/fdd76c884e614b1c8f669a3207b09a98 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233246912184",
"Amount": 0.5,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestEVD01011"
}

7
Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestEVD01011",
"Amount": 0. 85,
"TransactionId": "a50e003d8d8741d49a3a0dc677a7576b",
"Meta": {
"Commission": 0.05
}
}
}

4.1.2 Vodafone Airtime Topup

This endpoint is used to top up a Vodafone account with airtime.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/f4be83ad74c7
API Endpoint
42e185224fdae1304800

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the airtime


Destination String Mandatory
value.

The airtime value to be sent during this


Amount Double Mandatory
transaction. Eg: 0.5

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

8
The reference number that is provided by the
ClientReference String Mandatory
API user.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/f4be83ad74c742e185224fdae1304800 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": " 233206439599",
"Amount": 1.0,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestEVD01023"
}

9
Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestEVD01023",
"Amount": 0. 85,
"TransactionId": " 0305e0d79b2048e5b57647d4acaff939",
"Meta": {
"Commission": 0.0280
}
}
}

4.1.3 AirtelTigo Airtime Top-Up

This endpoint is used to top up an AirtelTigo account with Airtime.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/dae2142eb5a1
API Endpoint
4c298eace60240c09e4b

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the airtime


Destination String Mandatory
value.

The airtime value to be sent during this


Amount Double Mandatory
transaction. Eg: 0.5

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.

10
Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/dae2142eb5a14c298eace60240c09e4b HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": " 233574126849",
"Amount": 0.5,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestEVD01027"
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {

11
"ClientReference": " TestEVD01027",
"Amount": 0. 85,
"TransactionId": " a1579b60845444babfe13945660a679d",
"Meta": {
"Commission": 0.35
}
}
}

4.1.4 Glo Airtime Top-Up

This endpoint is used to top up a Glo account with Airtime.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/47d88e88f50f
API Endpoint
47468a34a14ac73e8ab5

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the airtime


Destination String Mandatory
value.

The airtime value to be sent during this


Amount Double Mandatory
transaction. Eg: 0.5

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.

12
Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/47d88e88f50f47468a34a14ac73e8ab5 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233237179385",
"Amount": 1.50,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestEVD01034"
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {

13
"ClientReference": "TestEVD01034",
"Amount": 1.50,
"TransactionId": "b2104b66c1ba42d799cea8522983e2b9",
"Meta": {
"Commission": 0.0280
}
}
}

4.2 Data & Voice Bundle Services

4.2.1 MTN Data Bundle Query

This queries the MTN Data bundle service for the available bundles which can be purchased
for a specific number.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/b230733cd56b
API Endpoint
4a0fad820e39f66bc27c?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number which will be receiving
destination String Mandatory the data bundle value. This parameter is to be
placed in the URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.

14
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the MTN Data top-
up endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle.

Sample Request
GET
/commissionservices/11691/b230733cd56b4a0fad820e39f66bc27c?destination=2332469
12184 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Successful",
"Data":
[
{
"Display": "Daily 20MB",
"Value": "DAILY_20MB",
"Amount": 0.5
},
{

15
"Display": "Daily 50MB",
"Value": "DAILY_50MB",
"Amount": 1.0
},
{
"Display": "Weekly 60MB",
"Value": "WEEKLY_60MB",
"Amount": 2.0
},
{
"Display": "Weekly 180MB",
"Value": "WEEKLY_180MB",
"Amount": 3.0
},
{
"Display": "Monthly 1GB",
"Value": "MONTHLY_1GB",
"Amount": 20.0
},
{
"Display": "Monthly 6GB",
"Value": "MONTHLY_6GB",
"Amount": 80.0
}
]
}

4.2.2 MTN Data Bundle Top-Up

This endpoint is used to top up an MTN account with a data bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/b230733cd56b
API Endpoint
4a0fad820e39f66bc27c

Request Type POST

Content Type JSON

16
Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available data bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
parameter is taken from the “value” response
parameter on the MTN Data Bundle Query
Bundle String Mandatory Endpoint. Note that: if the Bundle and the
amount do not correspond to what is taken from
the Data Bundle Query endpoint, the transaction
will fail.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

17
Sample Request
POST /commissionservices/11691/b230733cd56b4a0fad820e39f66bc27c HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233246912184",
"Amount": 1,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01013",
"Extradata": {
"bundle": "DAILY_50MB"
}
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestDATA01013",
"Amount": 1,
"TransactionId": "87acd82ed62c4e55bcac876da84e5de0",
"Meta": {
"Commission": 0.0420
}
}
}

18
4.2.3 Vodafone Data Query

This queries the Vodafone Data Bundle Service for the available bundles which can be
purchased for a specific number.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/fa27127ba039
API Endpoint
455da04a2ac8a1613e00?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number to receive the data
destination String Mandatory bundle value. This parameter is placed in the
URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the Vodafone Data
Top-up endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle being purhased.

19
Sample Request
GET /commissionservices/11691/fa27127ba039455da04a2ac8a1613e00?destination=
0206439599 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Successful",
"Data":
[
{
"Display": " Dual Recharge",
"Value": " 5.7 GB",
"Amount": 50.0
},
{
"Display": "Chat Monthly",
"Value": "2 GB",
"Amount": 20.0
},
{
"Display": "Starter Monthly",
"Value": "560 MB",
"Amount": 10.0
},
{
"Display": " Streamer Weekly",
"Value": "460 MB",
"Amount": 5.0
},
{
"Display": "Browser Daily",

20
"Value": "61 MB",
"Amount": 1.0
},
{
"Display": " Starter Daily",
"Value": "25 MB",
"Amount": 0.5
}
]
}

4.2.4 Vodafone Data Bundle Top-Up

This endpoint is used to top up a Vodafone account with a data bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/fa27127ba039
API Endpoint
455da04a2ac8a1613e00

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available data bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
bundle String Mandatory parameter is taken from the “value” response
parameter on the Vodafone Data Bundle Query

21
Endpoint. Note that: if the Bundle and the
amount do not correspond to what is taken from
the Data Bundle Query endpoint, the transaction
will fail.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/fa27127ba039455da04a2ac8a1613e00 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233206439419",
"Amount": 0.5,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01025",
"Extradata": {
"bundle": "25 MB"
}
}

22
Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestDATA01025",
"Amount": 1,
"TransactionId": " 558625e7f8c94feb82ddf50cb33bc557",
"Meta": {
"Commission": 0.0140
}
}
}

4.2.5 Glo Data Bundle Query

This queries the Glo Data bundle service for the available bundles which can be purchased
for a specific number.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/524895af10af
API Endpoint
40aabed4b313d1ae7991?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number to receive the data
destination String Mandatory bundle value. This parameter is placed in the
URL, not in the request body.

23
Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the Vodafone Data
top-up endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle.

Sample Request
GET /commissionservices/11691/524895af10af40aabed4b313d1ae7991?destination=
0237383393 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Successful",
"Data":
[
{
"Display": "300MB Plan",

24
"Value": "BUNDLE_300MB_Plan1",
"Amount": 1.0
},
{
"Display": "600MB Plan",
"Value": "BUNDLE_600MB_Plan1",
"Amount": 2.0
},
{
"Display": "1.5GB Plan",
"Value": "BUNDLE_1.5GB_Plan1",
"Amount": 5.0
},
{
"Display": "15GB Plan",
"Value": "BUNDLE_15GB_Plan1",
"Amount": 50.0
},
{
"Display": "UNLIMITED Data",
"Value": "BUNDLE_UNLIMITED_Plan1",
"Amount": 300.0
}
]
}

4.2.6 Glo Data Bundle Top-up

This endpoint is used to top up a Glo account with a data bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/524895af10af
API Endpoint
40aabed4b313d1ae7991

Request Type POST

Content Type JSON

25
Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available data bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
parameter is taken from the “value” response
parameter on the Glo Data Query Endpoint.
bundle String Mandatory
Note that: if the Bundle and the amount do not
correspond to what is taken from the Data
Bundle Query endpoint, the transaction will fail.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

26
Sample Request
POST /commissionservices/11691/524895af10af40aabed4b313d1ae7991 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233237383393",
"Amount": 1,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01029",
"Extradata": {
"bundle": " BUNDLE_300MB_Plan1",
}
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestDATA01029",
"Amount": 1,
"TransactionId": " 6bf810b8f7d5424a973165b36cc1817e",
"Meta": {
"Commission": 0.0560
}
}
}

4.2.7 AirtelTigo Data Bundle Query

This queries the AirtelTigo Data bundle service for the available bundles which can be
purchased for a specific number.

27
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/06abd92da45
API Endpoint
9428496967612463575ca?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number to receive the data
destination String Mandatory bundle value. This parameter is placed in the
URL, not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the AirtelTigo Data
top-up endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle.

28
Sample Request
GET /commissionservices/11691/06abd92da459428496967612463575ca?destination=
0237383393 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Select bundle",
"Data":
[
{
"Display": "80MB Bundle (GHS 1)",
"Value": "DATA1",
"Amount": 1.0
},
{
"Display": "200MB Bundle (GHS 2",
"Value": "DATA2",
"Amount": 2.0
},
{
"Display": "650MB Bundle (GHS 5)",
"Value": "DATA5",
"Amount": 5.0
},
{
"Display": "2GB Bundle (GHS 10)",
"Value": "DATA10",
"Amount": 10.0
},
{
"Display": "5GB Bundle (GHS 20)",

29
"Value": "DATA20",
"Amount": 20.0
},
{
"Display": "11GB Bundle (GHS 50)",
"Value": "DATA50",
"Amount": 50.0
}
]
}

4.2.8 AirteTigo Data Bundle Top-up

This endpoint is used to top up an AirtelTigo account with a data bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/
API Endpoint
06abd92da459428496967612463575ca

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available data bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
parameter is taken from the “value” response
bundle String Mandatory parameter on the AirtelTigo Data Query
Endpoint. Note that: if the Bundle and the
amount do not correspond to what is taken from

30
the Data Bundle Query endpoint, the transaction
will fail.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/ 06abd92da459428496967612463575ca HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233271643397",
"Amount": 50,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01090",
"Extradata": {
"bundle": "DATA50",
}
}

31
Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestDATA01090",
"Amount": 1,
"TransactionId": " 6bf810b8f7d5424a973165b36cc1817e",
"Meta": {
"Commission": 0.0560
}
}
}

4.2.8 AirtelTigo Voice Bundle Query

This queries the AirtelTigo Voice bundle service for the available bundles which can be
purchased for a specific number.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/97a460db3e04
API Endpoint
463cbabc1ee5d239bb92?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number to receive the data
destination String Mandatory bundle value. This parameter is placed in the
URL, not in the request body.

32
Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the AirtelTigo Voice
Bundle endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle.

Sample Request
GET /commissionservices/11691/97a460db3e04463cbabc1ee5d239bb92?destination=
0273383393 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Select bundle",
"Data":
[
{
"Display": "Xtra Unlimited (GHS 0.60 - 1 Day)”

33
"Value": "XUCB060",
"Amount": 0.6
},
{
"Display": "Xtra Unlimited (GHS 1 - 2 Days)”
"Value": "XUCB1",
"Amount": 1.0
},
{
"Display": "Xtra Unlimited (GHS 4 - 15 Days)”
"Value": "XUCB4",
"Amount": 4.0
},
{
"Display": "Xtra Unlimited (GHS 6 - 30 Days)”
"Value": "XUCB6",
"Amount": 0.6
},
{
"Display": "Xtra Unlimited (GHS 10 - 60 Day)”
"Value": " XUCB10",
"Amount": 10.0
}
]
}

4.2.9 AirtelTigo Voice Bundle Top-up

This endpoint is used to top up an AirtelTigo account with a Voice bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/
API Endpoint
97a460db3e04463cbabc1ee5d239bb92

Request Type POST

Content Type JSON

34
Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available voice bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
parameter is taken from the “value” response
parameter on the AirtelTigo Voice Bundle Query
bundle String Mandatory Endpoint. Note that: if the Bundle and the
amount do not correspond to what is taken from
the Data Bundle Query endpoint, the transaction
will fail.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

35
Sample Request
POST /commissionservices/11691/ 06abd92da459428496967612463575ca HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233271643397",
"Amount": 50,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01099",
"Extradata": {
"bundle": "XUCB060",
}
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestDATA01099",
"Amount": 1,
"TransactionId": " 6bf810b8f7d5424a973165b36cc1819e",
"Meta": {
"Commission": 0.0560
}
}
}

36
4.2.10 Surfline Data Bundle Query

This queries the Surfline Data bundle service for the available bundles which can be
purchased for a specific number.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/abdbfacfa60e
API Endpoint
43d0adff023a110e648b?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number to receive the data
destination String Mandatory bundle value. This parameter is placed in the
URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the Surfline Data
Bundle Top-up endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle.

37
Sample Request
GET
/commissionservices/11691/abdbfacfa60e43d0adff023a110e648b?destination=2332550
20186 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Successful",
"Data":
[
{
"Display": "1.5GB 24Hrs - GHS10 (GHS 10)",
"Value": "1.5gbp",
"Amount": 10.0
},
{
"Display": "3GB 3days - GHS20 (GHS 20)",
"Value": "3gbp ",
"Amount": 20.0
},
{
"Display": 4.5GB 7days - GHS35 (GHS 35) ",
"Value": "4.5gbp ",
"Amount": 35.0
},
{
"Display": "15GB 30days - GHS100 (GHS 100)",
"Value": "15gbp ",
"Amount": 100.0
},

38
{
"Display": "Unlimited Night - GHS110 (GHS 110)",
"Value": "ulntp",
"Amount": 110.0
}
]
}

4.2.11 Surfline Data Bundle Top-Up

This endpoint is used to top up a Surfline account with a data bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/abdbfacfa60e
API Endpoint
43d0adff023a110e648b

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available data bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
parameter is taken from the “value” response
parameter on the Surfline Data Query Endpoint.
bundle String Mandatory
Note that: if the Bundle and the amount do not
correspond to what is taken from the Data
Bundle Query endpoint, the transaction will fail.

39
Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/abdbfacfa60e43d0adff023a110e648b HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "233255020186",
"Amount": 10,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01045",
"Extradata": {
"bundle": "1.5gbp"
}
}

40
Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": " TestDATA01045",
"Amount": 1,
"TransactionId": " 6bf810b8f7d5424a973165b36cc1817e",
"Meta": {
"Commission": 0.0560
}
}
}

4.2.12 Busy 4G Data Bundle Query

This queries the Busy 4G Data bundle service for the available bundles which can be
purchased for a specific number.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/6d31c55fb48d
API Endpoint
4987bfb12ce2d55a2ddb?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The destination number to receive the data
destination String Mandatory bundle value. This parameter is placed in the
URL. Not in the request body.

41
Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. For Busy
Label String 4G, this displays the name of the Busy 4G account
holder.

Display String The display tag for the bundle.

The value of the data bundle. The desired value will


Value String then be used in the request body of the Vodafone Data
top-up endpoint.
The transaction amount. The actual cost of the data
Amount Double
bundle.

Sample Request
GET
/commissionservices/11691/6d31c55fb48d4987bfb12ce2d55a2ddb?destination=200234
HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Sena Deku",
"Data":
[

42
{
"Display": " 2GB Loyalty Business Bundle | Loyalty Business Bundle
Group",
"Value": " 878",
"Amount": 25.0
},
{
"Display": " 25GB Loyalty Business Bundle | Loyalty Business Bundle
Group",
"Value": "881",
"Amount": 130.0
},
{
"Display": ”200GB Loyalty Business Bundle | Loyalty Business Bundle
Group",
"Value": "885",
"Amount": 425.0
},
{
"Display": " 1Day Unlimited Bundle | Loyalty Business Bundle Group",
"Value": " 903",
"Amount": 13.0
},
{
"Display": " Super Unlimited Bundle | Loyalty Business Bundle Group",
"Value": " 854",
"Amount": 85.0
}
]
}

43
4.2.13 Busy 4G Data Bundle Top-Up

This endpoint is used to top up a Busy 4G account with a data bundle.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/6d31c55fb48d
API Endpoint
4987bfb12ce2d55a2ddb

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The destination account to receive the data


Destination String Mandatory
bundle value.
The cost of the data bundle being purchased.
Amount Double Mandatory This amount is known by querying for the
available data bundles to purchase.
Used to receive the callback for the transaction
CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.
The desired bundle being purchased. This
parameter is taken from the “value” response
parameter on the Busy 4G Data Bundle Query
bundle String Mandatory Endpoint. Note that: if the Bundle and the
amount do not correspond to what is taken from
the Data Bundle Query endpoint, the transaction
will fail.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.

44
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/6d31c55fb48d4987bfb12ce2d55a2ddb HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "200234",
"Amount": 25,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestDATA01051",
"Extradata": {
"bundle": "878"
}
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestDATA01051",
"Amount": 1,
"TransactionId": "74f0626a3568472a82b5087023ed3233",
"Meta": {

45
"Commission": 1.4000
}
}
}

4.3 Utility Bill Payments

4.3.1 DSTV Account Query

This queries the DSTV service to get the details of a DSTV account.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/297a96656b58
API Endpoint
46ad8b00d5d41b256ea7?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The DSTV account number whose details needs
destination String Mandatory to be checked. This parameter is placed in the
URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.
The display tag for the account detail. Eg: name,
Display String
account, etc.

46
This shows the actual account detail of the “Display”
Value String parameter. Eg: the Account name (John Many) is shown
under a display tag of “name”.
The amount being paid for in this transaction. As this is
Amount Double a Query endpoint and not a POST endpoint, this
parameter will usually be empty.

Sample Request
GET
/commissionservices/11691/297a96656b5846ad8b00d5d41b256ea7?destination=7029864
396 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "",
"Data":
[
{
"Display": "name",
"Value": "John Barnes",
"Amount": 0.0
},
{
"Display": "amountDue",
"Value": "0.00",
"Amount": 0.0
},
{
"Display": “account",
"Value": "7029864396",

47
"Amount": 0.0
}
]
}

4.3.2 DSTV Bill Payment

This endpoint is used to top up a DSTV account with any specified amount.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/297a96656b58
API Endpoint
46ad8b00d5d41b256ea7

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

Destination String Mandatory The DSTV account number to be topped up.

Amount Double Mandatory The amount to top-up the DSTV account with.

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.

48
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/297a96656b5846ad8b00d5d41b256ea7 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "7029864396",
"Amount": 50,
"CallbackUrl": " https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestTV0101"
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestTV0101",
"Amount": 50,
"TransactionId": "9c6d65a2a7834759b44919a1621b80fd",
"Meta": {
"Commission": 0.3500
}
}
}

49
4.3.3 GoTV Account Query

This queries the GoTV service to get the details of a GoTV account.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/e6ceac7f3880
API Endpoint
435cb30b048e9617eb41?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The GoTV account number whose details needs
destination String Mandatory to be checked. This parameter is placed in the
URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.
The display tag for the account detail. Eg: name,
Display String
account, etc.
This shows the actual account detail of the “Display”
Value String parameter. Eg: the Account name (John Manu) is shown
under a display tag of “name”.
The amount being paid for in this transaction. As this is
Amount Double a Query endpoint and not a POST endpoint, this
parameter will usually be empty.

50
Sample Request
GET
/commissionservices/11691/e6ceac7f3880435cb30b048e9617eb41?destination=7032371
505 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "",
"Data":
[
{
"Display": "name",
"Value": "Senya Duku ",
"Amount": 0.0
},
{
"Display": "amountDue",
"Value": "-201.00",
"Amount": 0.0
},
{
"Display": “account",
"Value": "7032371505",
"Amount": 0.0
}
]
}

51
4.3.4 GoTV Bill Payment

This endpoint is used to top up a GoTV account with a specified amount.


https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/e6ceac7f3880
API Endpoint
435cb30b048e9617eb41

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

Destination String Mandatory The GoTV account number to be topped up.

Amount Double Mandatory The amount to top-up the GoTV account with.

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

52
TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/e6ceac7f3880435cb30b048e9617eb41 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "7032371505",
"Amount": 50,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestTV0106"
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestTV0106",
"Amount": 50.0,
"TransactionId": " 0bf810b8f7d5424a973165b36cc1817e",
"Meta": {
"Commission": 0.3500
}
}
}

53
4.3.5 ECG Postpaid Account Query

This queries the ECG Postpaid service to get the details of an ECG Postpaid account.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/bc6e32762683
API Endpoint
4c12baa45e2f3bfe433f?destination={RecipientNumber}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description


The ECG postpaid account number whose details
destination String Mandatory needs to be checked. This parameter is placed in
the URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.
The display tag for the account detail. Eg: name,
Display String
account, etc.
This shows the actual account detail of the “Display”
Value String parameter. Eg: the Account name (John Manu) is shown
under a display tag of “name”.
The amount being paid for in this transaction. As this is
Amount Double a Query endpoint and not a POST endpoint, this
parameter will usually be empty.

54
Sample Request
GET
/commissionservices/11691/bc6e327626834c12baa45e2f3bfe433f?destination=7233756
21 HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "",
"Data":
[
{
"Display": "name",
"Value": "MR MENSAH JOHN",
"Amount": 0.0
},
{
"Display": "amountDue",
"Value": "GHS 1,040.66",
"Amount": 0.0
},
{
"Display": “account",
"Value": "723375621",
"Amount": 0.0
}
]
}

55
4.3.6 ECG Postpaid Bill Payment

This endpoint is used to top up an ECG postpaid account with a specified amount.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/bc6e32762683
API Endpoint
4c12baa45e2f3bfe433f

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The ECG Postpaid account number to be topped


Destination String Mandatory
up.

The amount to top-up the ECG Postpaid account


Amount Double Mandatory
with.

Used to receive the callback for the transaction


CallbackURL String Mandatory
from Hubtel. See below for a sample callback.

The reference number that is provided by the


ClientReference String Mandatory
API user.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The reference number that was initially provided by the
ClientReference String
API user in the request payload.

Amount Double The transaction amount, minus the charges/fees

56
TransactionId String The unique ID to identify a transaction.

Commission String The commission gained for the transaction.

Sample Request
POST /commissionservices/11691/bc6e327626834c12baa45e2f3bfe433f HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

{
"Destination": "7032371505",
"Amount": 10,
"CallbackUrl": "https://webhook.site/fcad8efa-624b-44c8-a129-b1c01921191d",
"ClientReference": "TestECG01011"
}

Sample Response
{
"ResponseCode": "0001",
"Message": "Transaction pending. Expect callback request for final state",
"Data": {
"ClientReference": "TestECG01011",
"Amount": 50.0,
"TransactionId": " 92bf810b8f7d5424a973165b36cc1817e",
"Meta": {
"Commission": 0.3500
}
}
}

57
4.4 Others

4.4.1 Query Hubtel Account Balance

This endpoint is used to get the details of your Hubtel account balance.
https://cs.hubtel.com/commissionservices/{HubtelPrepaidAccountID}/670c06954da0
API Endpoint
4974b0cfdd307fe62383?destination={HubtelPrepaidAccountID}

Request Type GET

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The Hubtel Prepaid Account ID. This parameter is


destination String Mandatory
placed in the URL. Not in the request body.

Response Parameters:

Parameter Type Description

The unique response error code on the status of the


ResponseCode String
transaction.
The description of the response received from the API
Message Double
call that is related to the ResponseCode.
The response label from the service provider. Usually
Label String
the same as the message.
The display tag for the account detail. Eg: name,
Display String
balance, etc.
This shows the actual account detail of the “Display”
Value String parameter. Eg: the business name (May Enterprise) is
shown under a display tag of “name”.
The amount value associated with the Display
Amount Double
parameter.

58
Sample Request
GET
/commissionservices/11691/670c06954da04974b0cfdd307fe62383?destination=11691
HTTP/1.1
Host: cs.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=

Sample Response
{
"ResponseCode": "0000",
"Message": "Successful",
"Label": "Successful",
"Data":
[
{
"Display": "name",
"Value": " Reseller Shop",
"Amount": 0.0
},
{
"Display": "clientId",
"Value": "20246",
"Amount": 0.0
},
{
"Display": “accountNumber",
"Value": "000002505",
"Amount": 0.0
},
{
"Display": “currency",
"Value": "GHc",
"Amount": 0.0
},
{

59
"Display": “balance",
"Value": "150.00",
"Amount": 150.00000
}
]
}

60
5.0 API Response Codes
The Hubtel Commission Services API uses standard HTTP error reporting. Successful requests
return HTTP status codes in the 2xx. Failed requests return status codes in 4xx and 5xx.

Error responses are included in the JSON response body, which contains information about
the error. You can also find Error Responses in the Final Callbacks. Kindly note that all
Callback Response Codes which are not 0000 should be considered as FAILED.

Response Code Description Action Required

The transaction has been processed


0000 Nil
successfully.
Transaction pending. Expect callback
0001 Nil
request for final state
The transaction state is not known. Please
0005 There was an HTTP failure/exception. contact [email protected] to confirm the
status of this transaction
Usually, check the description of the response
callback. It gives the actual error. Eg: The
2001 General Failure Error
receiving user is not registered in the system.
Or the Bundle is invalid

2000 General Failure Error

A required request parameter might have been


4010 Validation Errors
left empty, invalid or omitted.
Ensure that you're providing the correct Basic
4101 Authorization for request is denied. Auth key for the Authorization header. See
authentication above for more details.
You are not allowed to perform this
4103 Permission denied transaction. Kindly ensure your API keys are
accurate.

61
You don't have enough funds in your prepaid
balance to vend this service to your customers.
4080 Insufficient prepaid balance. You can top-up your prepaid balance by
transferring funds from your available balance
or bank deposit.

Contact Us
Hubtel

63 Hotel Road
Accra - Ghana

Postal Code: GA098


Digital Address: GA-098-9573

62
P.O. Box CT 2156 Cantonments Accra, Ghana.

Telephone: (+233) 30 225 6859, 30 222 2081, 20 253 2273


Toll Free: 0800 222 081

General: [email protected]
Sales: [email protected]
Help: [email protected]

www.hubtel.com

63

You might also like