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