Hubtel Verification API
Verifies Mobile Money wallets and Ghana- issued ID Cards
1
Contents
1.0 Overview of the API .................................................................................................................. 3
3.0 Getting Started .......................................................................................................................... 4
3.1 Authentication.................................................................................................................................. 4
4.0 Endpoints for Integration .......................................................................................................... 5
Contact Us .........................................................................................................................5
2
1.0 Overview of the APIs
This API is for checking whether a customer is registered on Mobile Money and also to query
the username on the Mobile Money account
The following are the available channels
Mobile Money Provider Channel Name
MTN Ghana mtn-gh
Vodafone Ghana vodafone-gh
AirtelTigo Ghana tigo-gh
This API is also checking the validity of a customer’s Basic details eg. age, gender etc whether
customer is eligible for a business partnership etc.
ID Card type Options
ID Type ghanacard
ID Type voterid
3
3.0 Getting Started With The APIs
3.1 Authentication
For this API, there are two required methods of authentication:
3.1 API Keys
3.2 Business IP whitelisting
API Keys
You need to authenticate every API request you make to the Hubtel Sales API using Basic
Auth. Authenticate by encoding your username and password to Base64 HTTP Basic
Authorization. Use your API ID as your username and API Key as your password.
Authorization: Basic {base64_encode(APIiD:APIKey)}
A Base64 encoding of your API keys should have your Authorization header appear like this:
Basic a2hlcW2sb3U6bWdhtHd9YW8=. Try sample basic auth here
https://www.base64encode.org
To create your API keys, kindly visit https://developers.hubtel.com/docs/authentication and
follow the instructions or video under “Creating keys for the Sales API”
PS: After creating API keys, kindly communicate with the Hubtel representative assisting
with your integration to add ‘Receive Money’ scopes to your API keys.
Business IP whitelisting
You will also have to share your business IP address with us for whitelisting. Only requests
from this IP will be accepted. Send this via email to [email protected] or share with the
Hubtel representative assisting with your integration.
4
4.0 Endpoint for Integration
The endpoint for this Hubtel Verification APIs:
1. Mobile Money Registration & Username Query
2. ID Card Validity Verification Query
1. Mobile Money Registration & Username Query
This endpoint can be used to query whether a number is registered on Mobile Money and
the username on the Mobile Money account
Request: To send a request, make an HTTP GET to the below URL with the required
parameters:
API Endpoint https://rnv.hubtel.com/merchantaccount/merchants/{AccountNumber}/mob
ilemoney/verify?channel={channel}&customerMsisdn={CustomerNumber}
Request Type GET
Content Type JSON
NB: Replace the “AccountNumber” in the above endpoint with your Hubtel POS sales
number before proceeding. Find yours here https://bo.hubtel.com/money using the digits
under POS Sales.
Request Parameters:
Parameter Type Requirement Description
The business’ Hubtel POS Sales number. Find
AccountNumber String Mandatory
yours here
The customer’s mobile money number.
CustomerMsisdn String Mandatory Accepted formats 0xxxxxxxxx or 233xxxxxxxxx
Eg: 0200000000 or 233200000000
The mobile money channel provider. Available
channels are:
mtn-gh,
Channel String Mandatory
vodafone-gh
tigo-gh
5
Response Parameters:
Parameter Type Description
The unique response error code on the status of the
ResponseCode String
transaction.
Message String The status of the request
Data Object Contains the isRegistered, status and name
Name String Registered username on the Mobile Money account
Status String The status of the account
Sample Request
GET
https://rnv.hubtel.com/merchantaccount/merchants/11684/mobilemoney/verify?cust
omerMsisdn=233207000000&channel=vodafone-gh
HTTP/1.1
Host:
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=
Cache-Control: no-cache
Sample Response
{
"Message": "Success",
"ResponseCode": "0000",
"Data": {
"IsRegistered": true,
"Name": "Nii Nortei Nortey"
"Status": "active"
}
6
2. ID Card Verification Query
This endpoint can be used to query the validity of issued ID Cards and it’s information.
Request: To send a request, make an HTTP GET to the below URL with the required
parameters:
https://rnv.hubtel.com/merchantaccount/merchants/[HUBTEL_ACCOUNT_NUM
API Endpoint BER]/idcard/verify?idtype=[ ID_TYPE]&idnumber=[ID_NUMBER]
Request Type GET
Content Type JSON
NB: Replace the “AccountNumber” in the above endpoint with your Hubtel POS sales
number before proceeding. Find yours here https://bo.hubtel.com/money using the digits
under POS Sales.
Request Parameters:
Parameter Type Requirement Description
The business’ Hubtel POS Sales number. Find
AccountNumber String Mandatory
yours here
The customer’s ID Card number.
Accepted idnumber format for ghanacard: as
printed on card ([country]-[9 digit alphanumeric]-
ID_NUMBER String Mandatory [1 digit alphanumeric] e.g. GHA-7xxxxxxx9-7)
Accepted idnumber format for voterid: as printed
on card (e.g. 61610xxxx2)
Options for [ID_TYPE]
1. ghanacard
ID_TYPE String Mandatory
2. voterid
Response Parameters:
Parameter Type Description
7
The unique response error code on the status of the
ResponseCode String
transaction.
Message String The status of the request
Data Object Contains the name, dateofbirth and gender
Name String Fullname on the ID card
DateofBirth String The birthdate of the Card holder.
Sample Request
GET
https://rnv.hubtel.com/merchantaccount/merchants/11691/idcard/verify?idtype=gh
anacard&idnumber=GHA-7xxxxxxx9-7
HTTP/1.1
Host:
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=
Cache-Control: no-cache
Sample Response
{
"Message": "Success",
"ResponseCode": "0000",
"Data": {
"Name": "AUGUSTINE GYAWU ADJEI",
"DateOfBirth": "1986 June 25",
"Gender": "Male"
}
8
Contact Us
Hubtel
63 Olympics Street
Accra - Ghana
Postal Code: GA098
Digital Address: GA-098-9573
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
