Overview

This document describes the RESTful web services exposed on the RechargeHub Platform which enables Merchants buy/sell different products. Our RESTful web service mainly uses data in JSON format for both input and output operations. Http request header should be set to application/json or the corresponding data type. The base url for the API is https://api.rechargehub.ng/v1/. After Merchant Account has been Successfully Created, links to Administer your Merchant Account will be added to your Datahub Account Dashboard. For technical assistance with the Datahub API contact us by sending a mail to dev_support@rechargehub.ng

How to Begin

The first step to becoming a Merchant is to Create a Rechargehub Account. After this has been successfully done, you can apply for a merchant account to be created for you. To do this, send a mail to dev_support@rechargehub.ng or call +234. You will need to Provide :

  • Your Registered Datahub Phone No
  • A valid Email Address to receive your Merchant Account Information
  • The IP Address of your Server which your LIVE calls to our Server will originate from

After an Account has been created for you, links to administer your Merchant Account will be added to your RechargeHub Account Dashboard. To View your Public & Private Keys for both Test and Production, Click on Merchant Actions > Account Settings

PLEASE NOTE THAT A NON-REFUNDABLE FEE OF N25,000 WILL BE CHARGED FROM YOUR WALLET TO ACTIVATE YOUR MERCHANT ACCOUNT FOR LIVE CALLS



Integration Flow

This section contains a description of recommended integration flow which helps minimize the risk of disputing transactions.

  • Merchant should always try to validate and sanitise data received from the customers before sending every request.
  • if the statusCode of a vend Request is 1, the merchant can consider that vending was successful otherwise the merchant can consider that an error occurred in which case, the status message can be read to view the error description.
  • In case the request which the merchant considers to be valid returns with an error response multiple times, the client needs to contact Datahub support in order to resolve the issue.
  • Before sending Data and Airtime Vend Request, Merchant are advised to always send a ccheckNetworkStatus request first to check the current delivery status of the desired network. This will help guide the merchant on weather or not to proceed with the vend Request

Fetch Merchant Data

This service enables RechargeHub integrators fetch current information about integrator’s account, such as the allowed IP addresses, current wallet balance, test public & private key, account information ( name, email, phoneNo ) etc.

Request Parameters

URL https://api.rechargehub.ng/v1/fetchMerchantData
HTTP Method POST
Request Headers application/json

Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statuscode for the transaction
data Collection An array of merchant details


Data Body

Parameter Name Type Description
id String Merchant Id provided during integration
allowedIP String Allowed IP configured for merchant for API calls
account Collection An array of merchant Datahub account details ( firstName, lastName, email, phoneNo etc )
testPublicKey String Public key configured for merchant for test API calls
testPrivateKey String Private Key configured for merchant for test API calls


Sample Response Body

									
{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"merchantData": {
			"id": "923116V56845225L52589849",
			"account": {
				"id": "1",
				"firstName": "Kelvin",
				"lastName": "Osunji.",
				"phoneNo": "080600000000",
				"email": "abctest@ymail.com",
				"gender": "1",
				"accountType": "Distributor",
				"walletBalance": "40954",
				"referralLink": "https:\/\/datahub.com.ng?ref=dGxKZnI5OThlT0F1WFFnSFNOYTN3Zz09",
				"avatar": "",
				"signUpDate": "2018-01-24",
				"stateId": "9",
				"state": "KwaraState",
				"accountStatus": "1",
				"acctType": "4",
				"newsletterSubscriptionStatus": false,
				"referrerId": "0",
				"pin": "0K5oy5"
			},
			"allowedIP”:”192.45.7.98”,
			”activationDate": "2018-11-01",
			"testPublicKey": "DTH-PBK-$C5tr.7Iwy$10$VKybR3huehaV8RwoItJkAvFuSeLLOIO2XJkgFlarKEudbq",
			"testPrivateKey": "DTH-PVK-$2y$10$TCYMQuKAuw8Ns0o9CIxUwmOjmtHH8b9wDZ6v2PaOjeV4fGeQMkWuZ"
		}
	}
}
								

Check Network Status

This service enables RechargeHub integrators check network availability status before sending a vend request for Data or Airtime. It is optional but is highly advised as it will put the merchant on the know as to the current state of the network before sending a vend Request.

Request Parameters

URL https://api.rechargehub.ng/v1/checkNetworkStatus
HTTP Method POST
Request Headers application/json

Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
networkId Int ID assigned to the Network that the Merchant wish to Check Status ( 1 for MTN, 2 for 9Mobile, 3 for Glo, 4 for Etisalat )
vendType Int ID assigned to the Vend Type ( 1 for Data Vending, 2 for Airtime Vending )
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"networkId" => 1,
	"vendType" => 1
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An array of containing the Network Delivery Status of the desired Network


Data Body

Parameter Name Type Description
networkStatus Int Current Network Delivery Status ( 0 for Unavailble, 1 for Available, 2 for Delay )


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"networkStatus": "1"
	}
}								

Check Wallet Balance

This service enables RechargeHub merchants check their account wallet balance. Making a call to this endpoint before sending any vend request is highly advised to ensure that the merchant have enough fund in his/her wallet to permit the vend transaction

Request Parameters

URL https://api.rechargehub.ng/v1/checkBalance
HTTP Method POST
Request Headers application/json


Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An array that contains merchant wallet balance


Data Body

Parameter Name Type Description
walletBalance Numeric Merchant’s current wallet balance


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"walletBalance": "118627"
	}
}								

Vend Data

This service enables Rechargehub merchants to vend Data to a customer’s phone number through the merchant’s account. This endpoint does not validate recipient phone number(s) as merchants are expected to validate recipient phone number(s) before sending a vend Request. To vend Data to multiple recipients at the same time, seperate the numbers with commas

Request Parameters

URL https://api.rechargehub.ng/v1/vendData
HTTP Method POST
Request Headers application/json


Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
networkId Numeric Network Id of desired network ( 1 for Mtn, 2 for 9mobile, 3 for Glo, 4 for Airtel )
plan String Plan to vend to customer ( e.g 5GB ). ( See Available Data Plans section for list of available plans )
recipient String Recipient phone No(s). Multiple PhoneNos are separated with commas
customReference String Optional Custom Reference ID for this Transaction ( This will be used to fetch the delivery status of the Transaction subsequently )
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"networkId": 1,
	"plan": "1GB",
	"recipient": "080300000000,080600000000",
	"customReference" : "RC-984H84",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An array that contains deliveryStatus for each recipient


Data Body

Parameter Name Type Description
transactionStatus Collection An array containing recipients and thier corresponding delivery status


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"transactionStatus": [{
			"recipient": "080300000000",
			"deliveryStatus": 1
		}, {
			"recipient": " 080600000000",
			"deliveryStatus": 1
		}]
	}
}								

Vend Airtime

This service enables Rechargehub merchants to vend Airtime to a customer’s phone number through the merchant’s account. This endpoint does not validate recipient phone number(s) as merchants are expected to validate recipient phone number(s) before sending a vend Request. To vend Airtime to multiple recipients at the same time, seperate the numbers with commas

Request Parameters

URL https://api.rechargehub.ng/v1/vendAirtime
HTTP Method POST
Request Headers application/json


Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
networkId Numeric Network Id of desired network ( 1 for Mtn, 2 for 9mobile, 3 for Glo, 4 for Airtel )
amount Numeric Amount with which to top-up amount customers phone ( Maximum 100,000 )
recipient String Recipient phone No(s). Multiple PhoneNos are separated with commas
customReference String Optional Custom Reference ID for this Transaction ( This will be used to fetch the delivery status of the Transaction subsequently )
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"networkId": 3,
	"amount": 1000,
	"recipient": "080500000000,080550000000",
	"customReference" : "TC093394",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An array that contains deliveryStatus for each recipient


Data Body

Parameter Name Type Description
transactionStatus Collection An array containing recipients and thier corresponding delivery status


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"transactionStatus": [{
			"recipient": "080300000000",
			"deliveryStatus": 1
		}, {
			"recipient": " 080600000000",
			"deliveryStatus": 1
		}]
	}
}								

Subscribe Cable

This service enables Rechargehub merchants to Subscribe to a customer’s Cable TV ( GoTV, DSTV & Startimes ) through the merchant’s account. Before sending a subcribe cable call, a call to validate the customer's smart card/IUC No should be sent first. A successfull response will return an array containing the customer's registered name and a customer No. These values will be used in the subsequent call to subscribe cable.

Validate Customer SmartCard/IUC No

Request Parameters

URL https://api.rechargehub.ng/v1/validateSmartCardNo
HTTP Method POST
Request Headers application/json


Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
smartCardNo String Smart Card or IUC No of the Customer
subType String Type of Cable that the customer want to subscribe ( Possible Values: DSTV, GOtv, Startime )
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"smartCardNo" : "2020704902",
	"subType" : "GoTV",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An array that contains Decoder's Owner Name and Activation No


Data Body

Parameter Name Type Description
customerName String The Decoder's Registered Owner name
customerNo Numeric Activation Number assigned to the Decoder


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"customerName" : "Precious Ebuka",
		"customerNo" : "109291830081"
	}
}								

Subcribe Cable Call

Request Parameters

URL https://api.rechargehub.ng/v1/subscribeCable
HTTP Method POST
Request Headers application/json


Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
smartCardNo String Smart Card or IUC No of the Customer
subType String Type of Cable that the customer want to subscribe ( Possible Values: DSTV, GOtv, Startime )
subPlanId Numeric Selected Supscription Plan ID on rechargehub. See Cable Plans for more Information
duration Numeric Duration ( In Months ) of Cable Subscription
customerName String Decoder's Registered Customer Name sent from ValidateSmartCardNo Request
customerNo Numeric Decoder's Activation No. sent from ValidateSmartCardNo Request
customReference String Optional Custom Reference ID for this Transaction ( This will be used to fetch the delivery status of the Transaction subsequently )
checksum String Checksum computed for the request. See Checksum Computation section for more information


Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"subType" => "GoTV",
	"subPlanId" => 1,
	"smartCardNo" => '2020706836',
	"duration" => 1,
	"customerName" : "Precious Ebuka",
	"customerNo" : "109291830081"
	"customReference" : "YT-948832",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An empty array


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {}
}								

Electricity Billing

This endpoint is currently under development

Fetch Transaction Details

This end enables Rechargehub merchants use a customReference to fetch transaction details. This endpoint returns an array of Transactions tied to the customReference Note that the customReference MUST have been sent when the preceding vend request was sent.

Request Parameters

URL https://api.rechargehub.ng/v1/fetchTransactionDetails
HTTP Method POST
Request Headers application/json

Request Body

Parameter Name Type Description
merchantId String Merchant Id provided during Integration
customReference String Custom Reference to use for quering the transaction status
checksum String Checksum computed for the request. See Checksum Computation section for more information

Sample Request Body

									
{
	"merchantId": "4V39044769C867345361018",
	"customReference" : "TC093394",
	"checksum": "RFRILVBCSy0kMnkkMTAkQmdJTXlLR0dGMk43TTQ0TUpKTEds"
}
									
								


Response Parameters

Parameter Name Type Description
statusCode String Response code for the transaction. 1 signifies success
msg String Response message describing the statusCode for the transaction
data Collection An array that containing transaction details


Data Body

Parameter Name Type Description
transactions Collection An array containing transaction objects


Sample Response Body


{
	"statusCode": "1",
	"msg": "Operation successful",
	"data": {
		"transactions": [{
			"id": "VX-245873",
			"date": "2019-04-17",
			"time": "1555508807",
			"userId": "1",
			"typeDesc": "Data Purchase",
			"amount": "460",
			"amountCharged": "460",
			"recipient": "08062295588660000",
			"status": "1",
			"approvedTime": ""
		}, {
			"id": "UQ-364503",
			"date": "2019-04-30",
			"time": "1556638068",
			"userId": "1",
			"typeDesc": "Data Purchase",
			"amount": "440",
			"amountCharged": "440",
			"recipient": "08062295588660000",
			"status": "1",
			"approvedTime": "1556638068"
		}, {
			"id": "RG-792425",
			"date": "2019-05-01",
			"time": "1556710219",
			"userId": "1",
			"typeDesc": "Data Purchase",
			"amount": "460",
			"amountCharged": "460",
			"recipient": "08062295588660000",
			"status": "1",
			"approvedTime": "1556710219"
		}]
	}
}								

Checksum Computation

The Rechargehub API uses an authentication scheme which utilises the Base64 encoding to produce a hash algorithm. This is used to authenticate request sent to API endpoints via a checksum. Each Merchant has been provided with a private and public key for both test and live API calls. To generate a checksum, you first build a string by concatenating selected elements of the request, then you generate the checksum of the concatenated string in the previous step by hashing it using the base64 encode function.

When the Rechargehub API receives a request, it fetches the merchants private and public keys and compute the checksum in the same process as described above. It the two checksums match, the request is assumed to be valid and appropriate service will be rendered. If there is a mismatch, the request is dropped and the system responds with an error message.

The following illustrate the construction of a request checksum.

Fetch Merchant Data / Check Balance Request / Check Network Status
										
concatString = publicKey + ‘|’ + merchantId + ‘|’ + privateKey
checkSum = Base64(Bcyrpt(concatString))
										
									

Fetch Tranasction Details
										
concatString = publicKey + ‘|’ customReference + ‘|’ + merchantId + ‘|’ + privateKey
checkSum = Base64(Bcyrpt(concatString))
										
									

Vend Data / Vend Airtime Request
										
concatString = publicKey + ‘|’ + merchantId + ‘|’ + recipient + ‘|’ + privateKey
checkSum = Base64(Bcyrpt(concatString))
										
									

Validate SmartCard/IUCNumber Reports
										
concatString = publicKey + ‘|’+ smartCardNo + ‘|’ + merchantId + ‘|’ + privateKey
checkSum = Base64(Bcyrpt(concatString))
										
									

Subscribe Cable
										
concatString = publicKey + ‘|’+ customerNo + ‘|’ + merchantId + ‘|’ + smartCardNo + ‘|’ privateKey
checkSum = Base64(Bcyrpt(concatString))
										
									

Checksum Computation Examples

Below are examples of how to compute checksum using PHP and Python. This snippets only serves as a guide

PHP

										
/**
* checksum for Data/Airtime Vend Request
*/
function computeChecksum(){
	$concatString = $publicKey . ‘|’ . $merchantId . ‘|’ .
	$recipientPhoneNo . ‘|’ . $privateKey;
	$checksum = base64_encode($concatString);
	return $checksum;
}

/**
* checksum for fetchMerchantData/checkBalance Request
*/
function computeChecksum(){
	$concatString = $publicKey . ‘|’ . $merchantId . ‘|’ . $privateKey;
	$checksum = base64_encode($concatString);
	return $checksum;
}
										
									

Python

										
# checksum for Data/Airtime Vend Request
def computeChecksum():
	concatString = publicKey . ‘|’ . merchantId . ‘|’ .
	recipientPhoneNo . ‘|’ . privateKey;
	checksum = base64.urlsafe_b64encode(concatString)
	return checksum

# checksum for fetchMerchantData/checkBalance Request
def computeChecksum():
	concatString = publicKey . ‘|’ . merchantId . ‘|’ . privateKey;
	checksum = base64.urlsafe_b64encode(concatString)
	return checksum
										
									

Available DataPlans List

Click Here to View all Available Data Plans the Recharge Hub offer and thier Prices

Available Cable Plans List

Below is a List of Cable Plans avaiable on Rechargehub and thier IDs


ID Plan Amount
1 GoTV Lite 400
2 GoTV Value 1,250
3 GoTV Plus 1900
4 GoTV Max 3,200
5 Dstv Access 2,000
6 Dstv Family 2,000
7 Dstv Compact 6,800
8 Dstv Compact Plus 10,650
9 Dstv Premium 15,800
10 Startimes

Error Codes & Description

Below is a list of all Rechargehub Error codes and thier description


StatusCode Description
1 Operation successful
000 Data not Passed
001 Invalid Merchant Id
002 Request Denied ( i.e Request is not sent from the allowed IP )
003 Account Suspended
004 Invalid Request
005 Invalid Network ID
006 Invalid DataPlan ( i.e DataPlan format incorrect or DataPlan does not exist for selected network )
007 Invalid Recipients(s) found ( i.e some recipient no(s) not valid phone Number or not Valid for selected Network )
008 Insufficient Wallet Balance
009 Invalid Checksum string
010 Maximum vend Amount exceeded
011 Network currently Unavailable
012 Transaction not found
013 Required Payload Value not sent
014 This account has not been activated for Live Transactions