Our VAS Reseller service provides a comprehensive solution for resellers to purchase bill products and manage transactions seamlessly. Key features and functionality, along with integration workflows, are designed to streamline your business operations and enhance customer service.
Users gain access to a dedicated sandbox environment for testing and development, ensuring smooth integration and functionality validation. The admin portal enables efficient management of transactions, viewing of detailed reports, and interaction with billers. KYB verification is mandatory for compliance with regulatory standards and successful reseller registration grants access to the platform's full suite of features and functionalities.
Integration with our service involves incorporating multiple endpoints within your API logic to handle various functionalities seamlessly.
Available Endpoints
Endpoints | Description |
---|---|
Reseller Login | Used for authenticating and logging in resellers into the system. |
About Me | To fetch detailed information about the logged-in reseller, including profile data. |
Reseller My Biller | Provides information about the billers available for purchase. |
Assigned Biller | To retrieve the list of billers assigned to the reseller's account. |
Enable/Disable Biller | Allows resellers to enable or disable specific billers for transactions. |
Validate Phone Network | Used to validate the network provider of a phone number before top-up operations. |
Purchase VTU | For resellers to purchase airtime or data top-ups on behalf of their customers. |
Get Bouquet Codes | To obtain bouquet codes corresponding to different data plans offered by billers. |
Purchase Electricity | Manage and facilitate electricity meter recharges. |
Validate Meter Number | Retrieve the details of an electricity meter number before proceeding with a top-up. |
Purchase CableTV | Process CableTV subscriptions for Smartcard numbers, supports DSTV, GOTV, Startimes, and Showmax |
Get ProductCode | Obtain accurate and up-to-date product codes and their pricing options, |
Get Adds-on | To obtain accurate and up-to-date add-on codes and their pricing options, |
Purchase JAMB | Facilitates the top-up of a candidate's account for JAMB services |
Get Jamb Pricing Option | Retrieves a list of all product codes and their corresponding amounts for JAMB services. |
Get Jamb Candidate Data | Validate the details of a candidate before making a JAMB payment |
Purchase EPIN | Retrieves ePIN top-up codes for WAEC and Spectranet biller products. |
Fund Betting Wallet | Top-up their betting wallet accounts |
Verify Betting Account Name | Verify the details of the betting account before topping up the wallet. |
Validate IPN | |
Make IGR Payment |
Status Codes
Status Code | Type | Description |
---|---|---|
90000 | Custom | Operation Successful |
10001 | Custom | Unexpected Error |
10002 | Custom | Invalid Request |
10003 | Custom | Unauthorised |
10004 | Custom | Not Found Exception |
10005 | Custom | Duplicate Request |
These status codes represent whether or not your call got to our system, and not the final status of the Vas purchase initiated. Please do not take a decision solely on this status codes, but the rather from the "transactionStatus": "string"; found within the response. For example, we can recieve your call successfully with a "90000" response, but the purchase initiated fails to complete.
Reseller Login
The Reseller Login endpoint is a POST method that allows resellers to authenticate and obtain a valid token for accessing other endpoints within the VAS Reseller product. This endpoint requires the reseller's email and password for a successful call.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/ResellerAuth/login
Request parameters
Type | Name | Comment |
---|---|---|
String | username | The reseller's email address. |
String | password | The reseller's password. |
String | deviceToken | Device token for authentication. |
Sample Request
{
"username": "[email protected]",
"password": "Hydrogen123!",
"deviceToken": "string"
}
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"email": "[email protected]",
"resellerId": "579fb9be-cfd4-459a-a5a9-08dc481b122c"
}
}
After a successful login, the obtained token should be passed as a bearer token in the header of subsequent API calls to authenticate and access other endpoints within the VAS Reseller platform. This endpoint is important for resellers to gain access to the platform's features and functionalities, ensuring secure authentication and authorization for all API interactions.
About Reseller
The About Reseller endpoint is a GET method that allows a logged-in reseller to retrieve their details, including the reseller ID, wallet ID, contact information, and wallet balance. This endpoint provides updated information about the reseller's profile within the VAS Reseller product.
This endpoint does not require any request parameters. Authorization is required through the use of a valid bearer token in the header of the API call.
Request
METHOD: GET
URL: https://api.hydrogenpay.com/sb/resellerservice/api/ResellerAuth/about-reseller
Response parameters
Name | Type | Description |
---|---|---|
statusCode | Integer | Status code indicating the success of the operation. |
message | String | A message indicating the outcome of the operation. |
data | Object | Contains detailed information about the reseller. |
firstName | String | The first name of the reseller. |
lastName | String | The last name of the reseller. |
phoneNumber | String | The phone number of the reseller. |
String | The email address of the reseller. | |
walletID | String | The wallet ID associated with the reseller. |
channelId | String | The channel ID associated with the reseller. |
resellerId | String | The unique ID of the reseller. |
resellerStatus | String | The status of the reseller account (e.g., ACTIVE). |
hasPin | Boolean | Indicates whether the reseller has set a PIN. |
wallet | Object | Contains detailed information about the reseller's wallet. |
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"data": {
"firstName": "Okwudili",
"lastName": "Onu",
"phoneNumber": "2347062631299",
"email": "[email protected]",
"walletID": "1c582a5b-5683-4e7f-ccad-08dc480e792d",
"channelId": "BIL12345",
"resellerId": "579fb9be-cfd4-459a-a5a9-08dc481b122c",
"resellerStatus": "ACTIVE",
"hasPin": false,
"wallet": {
"id": "1c582a5b-5683-4e7f-ccad-08dc480e792",
"createdDate": "2024-03-19T13:47:09.0994441",
"updatedDate": "2024-03-20T05:02:39.8644848",
"customerID": "00000000-bbbb-0000-0000-0b0b0b0b0b0b",
"resellerID": "579fb9be-cfd4-459a-a5a9-08dc481b122c",
"channelID": "BIL12345",
"lienAmount": 0.0,
"lienStatus": 0,
"currency": "NGN",
"customerCashBalance": 11400.0,
"customerOverdraftBalance": 0.0,
"pin": 0,
"walletStatus": 1,
"threshold": 0.0
}
}
}
The About Me endpoint provides important information about the logged-in reseller, allowing them to access and manage their account effectively within the VAS Reseller platform.
Reseller My Biller
The GET method is used to retrieve the list of biller IDs assigned to a reseller by Hydrogen. This endpoint provides information about the billers available for purchase, including the biller system IDs and the agreed-upon commission rates for each biller.
Request
METHOD: GET
URL: https://api.hydrogenpay.com/sb/resellerservice/api/Biller/reseller-my-billers
Request parameters
Name | Type | Description |
---|---|---|
ResellerId | String | The unique ID assigned to the reseller. |
Response parameters
Name | Type | Description |
---|---|---|
statusCode | Integer | Status code indicating the success of the operation. |
message | String | A message indicating the outcome of the operation. |
data | Array | Array of objects containing details about assigned billers. |
billerName | String | The name of the assigned biller. |
billerSystemId | String | The unique ID of the assigned biller system. |
isEnabled | String | Indicates whether the biller is active or not. |
billerCategoryName | String | The category name of the biller (e.g., Virtual TopUp). |
commission | Float | The commission rate agreed upon with the biller (%). |
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"data": [
{
"billerName": "9Mobile DATA",
"billerSystemId": "a56a1282-a499-475e-371b-08dc480d5598",
"isEnabled": "Active",
"billerCategoryName": "Virtual TopUp (Airtime & Data)",
"commission": 10.00000
},
{
"billerName": "Airtel DATA",
"billerSystemId": "53c81c51-e08b-4e04-371c-08dc480d5598",
"isEnabled": "Active",
"billerCategoryName": "Virtual TopUp (Airtime & Data)",
"commission": 10.00000
}
]
}
The endpoint will return a list of billers with their respective system IDs and commission rates, allowing resellers to identify and interact with available billers for purchases.
Enable/Disable Biller
The Enable/Disable Biller endpoint is a PUT method that allows resellers to enable or disable an assigned biller. Resellers can use this endpoint by providing the ResellerId and BillerSystemId to either enable or disable the specified biller. Note that disabling a biller will prevent the reseller from purchasing that specific bill.
Request
METHOD: PUT
URL: https://api.hydrogenpay.com/sb/resellerservice/api/ResellerBackoffice/enable-disable-reseller
Response parameters
Name | Type | Description |
---|---|---|
ResellerId | String | The unique ID of the reseller. |
WalletId | String | The unique ID of the wallet associated with the biller. |
BillerSystemId | String | The unique ID of the biller system to enable or disable. |
isEnabled | Boolean | Indicates whether to enable (true) or disable (false) the biller. |
Sample Response
{
"resellerId": "1c582a5b-5683-4e7f-ccad-08dc480e792",
"BillersystemId": "53c81c51-e08b-4e04-371c-08dc480d558",
}
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Operation Successful"
}
The Enable/Disable Biller endpoint allows resellers to manage their assigned billers effectively by enabling or disabling them as needed. This functionality ensures control and flexibility in biller management within the platform.
Validate Phone Network
The Validate Phone Network endpoint is a GET method that allows resellers to validate the network provider of a given phone number. Resellers can use this endpoint by providing the CustomerId (phone number) as a query parameter to validate the network provider associated with that phone number.
Request
METHOD: GET
Request parameters
Name | Type | Description |
---|---|---|
CustomerId | String | The phone number to validate the network for. |
Response parameters
Name | Type | Description |
---|---|---|
statusCode | Integer | Status code indicating the success of the operation. |
message | String | A message indicating the outcome of the operation. |
description | String | Additional description providing details about the operation status. |
data | Object | Contains detailed information about the validation result. |
status | String | The status of the validation (e.g., Success). |
message | String | Additional message providing details about the validation status. |
defaultNetwork | String | The default network provider of the phone number. |
Sample Response
{
"statusCode": 90000,
"message": "Validation was successful",
"description": "request has been processed",
"data": {
"status": "Success",
"message": "Validation was successful",
"defaultNetwork": "airtel"
}
}
The Validate Phone Network endpoint allows resellers to verify the network provider of a given phone number, ensuring compatibility with the desired biller system for top-up transactions. This functionality enhances the accuracy and reliability of phone number validations within the platform.
Purchase VTU
The Purchase VTU endpoint is a POST method that allows resellers to purchase airtime or data top-ups for customers. This endpoint requires the resellerId, billerSystemId, amount, phoneNumber, and productType as inputs to complete the purchase. Additionally, it supports a re-query logic to ensure transaction accuracy.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/VtuPayment/purchase
Request parameters
Name | Type | Description | |
---|---|---|---|
resellerId | String | The unique ID of the reseller, obtained from the "login" or "About me" endpoint. | |
billerSystemId | String | The unique ID of the biller system to purchase from, obtained from the "Get Assigned Biller" endpoint. | |
amount | Decimal | The amount of the top-up to purchase, in the currency specified by the biller system. | |
phoneNumber | String | The phone number to top up. | |
bouquetCode | String | The bouquet code for data top-ups. Required for data purchases, obtained from the "Get Bouquet Code" endpoint. | |
productType | String | The type of product to purchase, either "AIRTIME" or "DATA". | |
clientReference | String | The client reference for the data purchase. |
Airtime Purchase
When purchasing airtime, ensure to remove or comment out the "bouquetCode" before making the call. Our system deducts the purchase amount after removing the commission set for that biller, from your wallet balance. For example, if you purchase N100 airtime for MTN and the commission set is 10%, we will deduct N90 from your wallet. During settlement, we collect only the N90.
Sample Request (Airtime)
{
"resellerId": "579fb9be-cfd4-459a-a5a9-08dc481b122c",
"billerSystemId": "53c81c51-e08b-4e04-371c-08dc480d5598",
"amount": 1000,
"phoneNumber": "08024532388",
"productType": "AIRTIME",
"clientReference": "74637465647859"
}
Sample Response (Airtime)
{
"statusCode": 90000,
"message": "Airtime topup was successful",
"description": "request has been processed",
"data": {
"status": "Success",
"message": "Airtime topup was successful"
},
"transactionStatus": "SUCCESSFUL",
"transactionRef": "fuZSk0xvPn8oBn0ITXTM"
}
Data Purchase
When purchasing data, call the "Get Bouquet Code" endpoint to retrieve the correct bouquet code for the data plan you want. The amount passed must correspond to the actual selling price of the data plan.
Sample Request (Data)
{
"resellerId": "579fb9be-cfd4-459a-a5a9-08dc481b122c",
"billerSystemId": "53c81c51-e08b-4e04-371c-08dc480d5598",
"amount": 1000,
"phoneNumber": "08024532388",
"bouquetCode": "AIRTEL1.5GB7Days1000",
"productType": "DATA",
"clientReference": "74637465647859"
}
Sample Response (Data)
{
"statusCode": 90000,
"message": "Data topup was successful",
"description": "request has been processed",
"data": {
"status": "Success",
"message": "Data topup was successful"
},
"transactionStatus": "SUCCESSFUL",
"transactionRef": "fuZSk0xvPn8oBn0ITXTM"
}
This endpoint facilitates the seamless purchase of airtime and data top-ups for customers, enhancing the service offerings of resellers within the platform.
Sample Response (Pending)
{
"statusCode": 90000,
"message": "success",
"description": "Pendings",
"data": {
"status": "400",
"message": "Pendings"
},
"transactionStatus": "PENDING",
"transactionRef": "9mobileTest3rr277535566481"
}
Please note that if the "transactionstatus" within the response is "pending" , you are expected to requery our system with this API below till you fetch a definite final status.
Requery Purchase-by-ref:
Parameter: transactionReferenceId (also known as Client Reference)
Get Bouquet Code
The Get Bouquet Code endpoint is a GET method that returns a paginated list of all bouquet codes available for data plans. This endpoint is used specifically for purchasing data. Use the Get Bouquet Code endpoint to retrieve the bouquet code of the data plan you want to purchase. Ensure that the amount passed in the request corresponds to the actual selling price of the data plan.
Request
METHOD: GET
URL: https://api.hydrogenpay.com/sb/resellerservice/api/Bouquet?
Request parameters
Name | Type | Description |
---|---|---|
search | String | Filter by any value within the response |
Response parameters
Name | Type | Description |
---|---|---|
statusCode | Integer | Status code indicating the result of the request |
message | String | Indicates the status of the request (Success/Error) |
description | String | Additional description of the request status |
data | Array | List of bouquet codes and their details |
Data Object
Name | Type | Description |
---|---|---|
bouquetCode | String | Unique code representing the bouquet |
name | String | Name or description of the bouquet |
price | String | Selling price of the bouquet |
type | String | Type of plan (Daily, Weekly, Monthly, etc.) |
billerId | String | ID of the biller associated with the bouquet |
providerId | String | ID of the service provider |
id | String | Unique identifier for the bouquet |
createdDate | String | Date and time when the bouquet was created |
updatedDate | String | Date and time when the bouquet was last updated |
rowVersion | String | Version control for the bouquet |
Sample Response
{
"statusCode": 90000,
"message": "Success",
"description": "Operation Successful",
"data": [
{
"bouquetCode": "9MOBILE100MB1Day100",
"name": "N100 = 100MB for 1Day",
"price": "100",
"type": "Daily",
"billerId": "9Mobile-DATA",
"providerId": "00087b9b-2fe0-48bd-9cd9-b9705a8d200a",
"id": "584a1562-468e-4a1b-6387-08dc4a6e30a7",
"createdDate": "2024-03-22T12:47:10.1992724",
"updatedDate": "2024-03-22T12:47:10.1992759",
"rowVersion": "AAAAAAAAZvM="
},
}
The response provides details such as the bouquet code, name, price, type, biller ID, provider ID, and creation/update dates. This endpoint streamlines the process of selecting the correct data plan for purchase, making it easier for developers to integrate data top-up functionalities into their applications.
Purchase Electricity
This endpoint allows resellers to fund an electricity meter number. The endpoint ensures that the electricity meter is recharged under the correct billerSystemId. Resellers need to provide the meter number and other necessary details to complete the purchase. Additionally, there is a separate endpoint available to retrieve meter number information.
To use this endpoint, include the required parameters in the request body and ensure that your request header contains a valid authentication token. The endpoint will process the electricity meter recharge and provide detailed transaction information in the response.
Request
METHOD: POST
https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/electricity/purchase
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the biller. |
amount | Number | The amount to be recharged. |
accountNumber | String | The electricity meter number. |
phoneNumber | String | The phone number of the customer. |
clientReference | String | A unique reference for the transaction. |
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Detailed description of the transaction result. |
data | Object | Contains detailed transaction information. |
transactionStatus | String | Overall status of the transaction. |
transactionRef | String | Unique reference for the transaction. |
transactionMessage | String | Message describing the transaction result. |
provider_message | String | Message from the provider regarding the transaction. |
tokenCode | String | The token code generated for the electricity recharge. |
tokenAmount | Number | Amount of the token (if applicable). |
amountOfPower | Number | Amount of power credited to the meter. |
creditToken | String | Credit token (if applicable). |
rawOutput | Object | Raw output details from the provider. |
rawOutput Fields
Field | Type | Description |
---|---|---|
kct1 | String | Provider-specific field. |
kct2 | String | Provider-specific field. |
token | String | The token generated for the electricity recharge. |
status | String | Status of the transaction from the provider. |
errorCode | String | Error code (if any). |
tariffCode | String | Tariff code associated with the meter. |
tariffClass | String | Tariff class associated with the meter. |
amountOfPower | Number | Amount of power credited to the meter. |
rate | String | Rate applied for the transaction. |
vat | Number | Value-added tax amount for the transaction. |
kwh | Number | Kilowatt-hour units credited. |
unit | Number | Units credited to the meter. |
meterNumber | String | The meter number that was recharged. |
undertaking | String | Undertaking information. |
businessUnit | String | Business unit information. |
customerName | String | Name of the customer associated with the meter. |
errorMessage | String | Error message (if any). |
accountNumber | String | Account number associated with the meter. |
customerAddress | String | Address of the customer (if available). |
customerBalance | Number | Customer balance (if applicable). |
exchangeReference | String | Exchange reference for the transaction. |
externalReference | String | External reference for the transaction. |
transactionStatus | String | Final status of the transaction. |
Sample Request
{
"billerSystemId": "e22168f0-7e0f-4b68-5399-08dc651c6771",
"amount": 500,
"accountNumber": "207309128307",
"phoneNumber": "07033102077",
"clientReference": "749937465647859"
}
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Electricity bill payment was successful",
"data": {
"statusCode": "0",
"transactionStatus": "success",
"transactionReference": "55e39dff-fa11-4f5d-879d-fedd43c3a563",
"transactionMessage": "Topup successful on 207309128307",
"provider_message": "Topup successful on 207309128307",
"tokenCode": "3954 5245 1973 7973 3521",
"tokenAmount": null,
"amountOfPower": 9250,
"creditToken": null,
"rawOutput": {
"kct1": null,
"kct2": null,
"token": "3954 5245 1973 7973 3521",
"status": "ACCEPTED",
"errorCode": null,
"tariffCode": "A1",
"tariffClass": "A1",
"amountOfPower": 9250,
"rate": "70.23",
"vat": 750,
"kwh": 131.17,
"unit": 131.17,
"meterNumber": "30530337820",
"undertaking": "Hadejia Road",
"businessUnit": "KANO EAST REGION",
"customerName": "ISAH MUSA",
"errorMessage": null,
"accountNumber": "37/61/01/0045-01",
"customerAddress": null,
"customerBalance": 0,
"exchangeReference": "110-212562311",
"externalReference": "3954 5245 1973 7973 3521",
"transactionStatus": "success"
}
},
"transactionStatus": "Successful",
"transactionRef": "55e39dff-fa11-4f5d-879d-fedd43c3a563"
}
This endpoint is essential for resellers to manage and facilitate electricity meter recharges efficiently, ensuring accurate and timely transactions for their customers.
Validate Meter Number
This endpoint is used to retrieve the details of an electricity meter number before proceeding with a top-up. This validation ensures that the meter number is correct and provides essential information about the account associated with the meter number.
Request
METHOD: POST
https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/electricity/validate-meter
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the biller. |
accountNumber | String | The electricity meter number. |
Response Parameter
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Detailed description of the verification result. |
data | Object | Contains detailed account information. |
name | String | Name of the account holder. |
address | String | Address associated with the meter number. |
outstandingBalance | Number | Outstanding balance on the account. |
district | String | District of the account holder. |
minimumAmount | Number | Minimum amount for a transaction. |
rawOutput | Object | Raw output details from the provider. |
hasDiscount | Boolean | Indicates if there is any discount. |
errorMessage | String | Error message (if any). |
RawOutput Fields
Field | Type | Description |
---|---|---|
String | Email of the account holder (if available). | |
tariffCode | String | Tariff code associated with the meter. |
phoneNumber | String | Phone number of the account holder. |
meterNumber | String | The meter number that was validated. |
undertaking | String | Undertaking information. |
businessUnit | String | Business unit information. |
customerName | String | Name of the customer associated with the meter. |
accountNumber | String | Account number associated with the meter. |
customerArrears | Number | Customer arrears (if any). |
minimumPurchase | Number | Minimum purchase amount (if applicable). |
Sample Request
{
"billerSystemId": "4f97b1de-36fe-4795-5395-08dc651c6771",
"accountNumber": "207309128307"
}
Example Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Account verification was successful",
"data": {
"name": "Onugu Ngwu Ba",
"address": "Ihe Alor Road Nsukka",
"outstandingBalance": 0,
"district": "Nsukka",
"minimumAmount": 0,
"rawOutput": {
"email": null,
"tariffCode": null,
"phoneNumber": "8039557214",
"meterNumber": "45028652431",
"undertaking": null,
"businessUnit": null,
"customerName": null,
"accountNumber": "1133427",
"customerArrears": 0,
"minimumPurchase": null
},
"hasDiscount": false,
"errorMessage": null
}
}
This endpoint helps resellers to ensure the accuracy of meter numbers and retrieve important information before processing electricity meter top-ups.
Purchase CableTV
This endpoint is used to process CableTV subscriptions for Smartcard numbers. This endpoint supports DSTV, GOTV, Startimes, and Showmax. Ensure that the total amount passed is the value associated with the product code for the desired subscription package. Use the endpoint to get the product code and add-on code for specific packages.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/cabletv/purchase
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the biller. |
smartCardNumber | String | The smart card number for DSTV, GOTV, or Startimes. |
totalAmount | Number | The total amount for the subscription. |
productCode | String | The product code for the cable TV package. |
addonCode | Array | The add-on codes for additional packages. |
productMonthsPaidFor | Number | The number of months paid for the product. |
phoneNumber | String | The phone number for Showmax subscriptions. |
dataCode | String | The data code for Showmax subscriptions. |
clientReference | String | A unique client reference for tracking the transaction. |
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Detailed description of the result. |
data | Object | Contains detailed transaction information. |
referenceId | String | Reference ID for the transaction. |
transactionStatus | String | Status of the transaction. |
transactionRef | String | Unique transaction reference ID. |
Sample for DSTV, GOTV, & Startimes
{
"billerSystemId": "a9d39f64-1e95-4d3a-5393-08dc651c6771",
"smartCardNumber": "1020833447",
"totalAmount": 9000,
"productCode": "66434858fb39137467b774b5",
"addonCode": [
"6643488afb39137467b77767"
],
"productMonthsPaidFor": 1,
"clientReference": "749937465647850"
}
Sample Request for Showmax
{
"billerSystemId": "a9d39f64-1e95-4d3a-5393-08dc651c6771",
"totalAmount": 9000,
"phoneNumber": "08038744691",
"dataCode": "6643488afb39137467b77767",
"clientReference": "749937465647850"
}
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "CableTv purchase was successful",
"data": {
"referenceId": "11a02b2b-c8f4-4032-bfee-a3296d843760",
"transactionStatus": "success"
},
"transactionStatus": "Cable TV Subscription successful",
"transactionRef": "11a02b2b-c8f4-4032-bfee-a3296d843760"
}
This endpoint ensures a smooth subscription process for cable TV services, providing quick and reliable transaction handling.
Get Product Code
The endpoint retrieves a paginated list of all product codes along with their corresponding pricing options and amounts. This information is necessary when purchasing cable TV subscriptions to ensure the correct product code and amount are used.
Request
METHOD: GET
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
data | Array | Contains a list of product codes and their pricing options. |
availablePricingOptions | Array | Contains pricing options for the product. |
code | String | The product code. |
name | String | The name of the product. |
id | String | The unique identifier for the pricing option. |
monthsPaidFor | Number | Number of months the payment covers. |
price | Number | Price for the given period. |
invoicePeriod | Number | The period of the invoice (e.g., monthly). |
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"data": [
{
"availablePricingOptions": [
{
"id": "667a6209bf6a89ea418259f0",
"monthsPaidFor": 1,
"price": 9000,
"invoicePeriod": 1
},
{
"id": "667a6209bf6a89ea418259f1",
"monthsPaidFor": 2,
"price": 18000,
"invoicePeriod": 1
},
{
"id": "667a6209bf6a89ea418259f2",
"monthsPaidFor": 3,
"price": 27000,
"invoicePeriod": 1
}
],
"code": "COMPE36",
"name": "DStv Compact"
}
]
}
This endpoint is important for obtaining accurate and up-to-date product codes and their pricing options before making a cable TV subscription purchase.
Get Adds-on
The endpoint retrieves a paginated list of all add-on codes and their corresponding pricing options and amounts for cable TV services. This information is used to select additional packages that can be included in a cable TV subscription.
Request
METHOD: GET
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
data | Array | Contains a list of add-on codes and their pricing options. |
Data Object Structure
The data
array contains objects with the following fields:
Field | Type | Description |
---|---|---|
availablePricingOptions | Array | Contains pricing options for the add-on. |
code | String | The add-on code. |
name | String | The name of the add-on. |
description | String | Description of the add-on. |
id | String | The unique identifier for the pricing option. |
monthsPaidFor | Number | Number of months the payment covers. |
price | Number | Price for the given period. |
invoicePeriod | Number | The period of the invoice (e.g., monthly). |
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"data": [
{
"availablePricingOptions": [
{
"id": "667a6710bf6a89ea41828fb1",
"monthsPaidFor": 1,
"price": 7100,
"invoicePeriod": 1
},
{
"id": "667a6710bf6a89ea41828fba",
"monthsPaidFor": 10,
"price": 71000,
"invoicePeriod": 1
},
{
"id": "667a6710bf6a89ea41828fbb",
"monthsPaidFor": 12,
"price": 78100,
"invoicePeriod": 12
}
],
"code": "ASIADDE36",
"name": "Asian Add-on",
"description": " "
}
]
}
This endpoint is important for obtaining accurate and up-to-date add-on codes and their pricing options before making a cable TV subscription purchase.
Purchase JAMB
This endpoint facilitates the top-up of a candidate's account for JAMB (Joint Admissions and Matriculations Board) services. It ensures that the amount passed corresponds to the amount specified in the JAMB pricing options. Additionally, there are endpoints to retrieve JAMB pricing options and candidate information.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/jamb/purchase
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the JAMB biller system. |
amount | Number | The amount to be paid, which should match the JAMB pricing options. |
accountNumber | String | The candidate's account number. |
phoneNumber | String | The candidate's phone number. |
productCode | String | The product code for the JAMB service (e.g., UTME). |
clientReference | String | A unique client reference for the transaction. |
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Description of the result of the operation. |
data | Object | Contains details of the transaction. |
transactionStatus | String | Status of the transaction. |
transactionRef | String | Reference ID of the transaction. |
referenceId | String | The unique reference ID for the transaction. |
transactionStatus | String | Status of the transaction. |
Sample Request
{
"billerSystemId": "4bcb9403-5d32-42b6-aa02-08dc6ba22f98",
"amount": 0,
"accountNumber": "9610729153",
"phoneNumber": "08038844791",
"productCode": "UTME",
"clientReference": "149037465647857"
}
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "purchase was successful",
"data": {
"referenceId": "11a02b2b-c8f4-4032-bfee-a3296d843760",
"transactionStatus": "success"
},
"transactionStatus": "Subscription successful",
"transactionRef": "11a02b2b-c8f4-4032-bfee-a3296d843760"
}
The productCode should be appropriate for the specific JAMB service being purchased. This endpoint is for facilitating the payment and top-up process for JAMB candidates, ensuring the correct details and amounts are used.
Get JAMB Pricing Option
This endpoint retrieves a list of all product codes and their corresponding amounts for JAMB services. This information is necessary for ensuring the correct amount is passed when making a JAMB payment.
Request
METHOD: GET
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
data | Array | Contains a list of product codes and their pricing options. |
id | String | The unique identifier for the product option. |
amount | Number | The amount for the product option. |
product_code | String | The product code for the JAMB service. |
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"data": [
{
"id": "1",
"amount": 6700,
"product_code": "UTME_MOCK"
},
{
"id": "2",
"amount": 5700,
"product_code": "UTME"
}
]
}
This endpoint is for obtaining accurate and up-to-date product codes and their corresponding amounts before making a JAMB payment.
Get JAMB Candidate Data
This endpoint is used to validate the details of a candidate before making a JAMB payment. It ensures that the candidate information is accurate and corresponds to the provided candidate ID.
Request
METHOD: GET
URL: https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/jamb/candidate-data
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Description of the result of the operation. |
data | Object | Contains details of the candidate. |
name | String | The full name of the candidate. |
accountNumber | String | The candidate's account number. |
rawOutput | Object | Contains raw data for the candidate details. |
Raw Output Fields
Field | Type | Description |
---|---|---|
error | String | Error message, if any. |
gsmNo | String | The candidate's GSM number. |
lastName | String | The candidate's last name. |
firstName | String | The candidate's first name. |
middleName | String | The candidate's middle name. |
Sample Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Account verification was successful",
"data": {
"name": "\"Emmanuel Amunike Michael\"",
"accountNumber": "9610729153",
"rawOutput": {
"error": null,
"gsmNo": "08000000000",
"lastName": "Amunike",
"firstName": "Emmanuel",
"middleName": "Michael"
}
}
}
This endpoint is for verifying candidate information before proceeding with a JAMB payment to ensure the correctness of the details.
Purchase ePIN
The endpoint retrieves ePIN top-up codes for WAEC and Spectranet biller products. The ePIN is obtained via an API call and can be used for various educational or internet subscription services.
METHOD: POST
WAEC Request
URL: https://api.hydrogenpay.com/sb/resellerservice/BillPayment/e-pin/waec/purchase
Spectranet Request
URL: https://api.hydrogenpay.com/sb/resellerservice/BillPayment/e-pin/spectranet/purchase
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the ePIN biller system. |
pinValue | Number | The value of each PIN. |
amount | Number | The total amount for the PIN(s). |
numberOfPins | Integer | The number of PINs to be purchased. |
clientReference | String | A unique reference number for the transaction. |
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Description of the result of the operation. |
data | Object | Contains details of the ePIN and transaction status. |
transactionStatus | String | Overall transaction status. |
transactionRef | String | Reference ID for the transaction. |
ePIN | String | The purchased ePIN code. |
transactionStatus | String | Status of the individual transaction. |
Sample Request
{
"billerSystemId": "5ec26807-e5da-48ff-7707-08dc7836c751",
"pinValue": 2900,
"amount": 2900,
"numberOfPins": 1,
"clientReference": "7374873987292781"
}
Sample Response (WAEC)
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Waec purchase was successful",
"data": {
"ePIN": "11a02b2b-c8f4-4032-bfee-a3296d843760",
"transactionStatus": "success"
},
"transactionStatus": "success",
"transactionRef": "11a02b2b-c8f4-4032-bfee-a3296d843760"
}
Sample Respobse (Spectranet)
"statusCode": 90000,
"message": "Operation Successful",
"description": "E-pin payment successful",
"data": {
"statusCode": "0",
"transactionStatus": "success",
"transactionReference": "d8cd907d-9664-46ae-b019-b78fe28a2f89",
"transactionMessage": "Transaction was successful",
"providerMessage": "Transaction was successful",
"pins": [
{
"pin": "6573628",
"expiresOn": "2028-05-08T00:00:00",
"serialNumber": "202405081001916"
}
]
This endpoint is useful for retrieving ePINs for educational or internet subscription services.
Fund Betting Wallet
The endpoint allows users to top-up their betting wallet accounts. There are 13 available betting billers. Before using this endpoint, it is recommended to validate the account details of the betting account using the corresponding validation endpoint.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/betting/fund-wallet
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the betting biller system. |
accountNumber | String | The account number of the betting wallet to be funded. |
action | String | The action to be performed, which should be set to WALLET_FUNDING . |
amount | Number | The amount to be funded into the betting wallet. |
clientReference | String | A unique reference number for the transaction. |
Response Parameters
Field | Type | Description |
---|---|---|
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Description of the result of the operation. |
data | Object | Contains details of the transaction status. |
transactionStatus | String | Overall transaction status. |
transactionRef | String | Reference ID for the transaction. |
Sample Request
{
"billerSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accountNumber": "9611728152",
"action": "WALLET_FUNDING",
"amount": 2500,
"clientReference": "1402037465647857"
}
Smple Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Wallet funding was successful",
"data": {
"transactionStatus": "success"
},
"transactionStatus": "success",
"transactionRef": "11a02b2b-c8f4-4032-bfee-a3296d843760"
}
This endpoint is for funding betting wallet accounts with the specified amount.
Verify Betting Account Name
The endpoint is used to verify the details of the betting account before topping up the wallet. This ensures that the account number provided corresponds to a valid betting account.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/betting/verify-account-name
Request Parameters
Parameter | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the betting biller system. |
accountNumber | String | The account number of the betting wallet to be verified. |
Response Parameters
Field | Type | Description |
---|---|---|
billerSystemId | String | The unique identifier for the betting biller system. |
accountNumber | String | The account number of the betting wallet. |
accountName | String | The name associated with the betting account. |
statusCode | Integer | Status code of the operation. |
message | String | Message describing the result of the operation. |
description | String | Description of the result of the operation. |
Example Request
{
"billerSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accountNumber": "9611728152"
}
Example Response
{
"statusCode": 90000,
"message": "Operation Successful",
"description": "Account verification was successful",
"billerSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accountNumber": "9611728152",
"accountName": "John Doe"
}
This endpoint is important for verifying the betting account details before proceeding with the wallet funding.
Validate IPN
The endpoint is used to validate the Instant Payment Number (IPN) of a state IGR generated for a payment. The request should include the IPN and the ID of the terminal from where the request is made, which must have been profiled by OIRS.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/IGRPayments/osun/validate-ipn
Request Parameters
Parameter | Type | Description |
---|---|---|
ipn | String | The unique identifier for the betting biller system. |
terminalId | String | The account number of the betting wallet to be verified. |
Response Parameters
Field | Type | Description |
---|---|---|
name | The unique identifier for the betting biller system. | |
ipn | ||
amount | ||
phoneNumber | ||
status |
Example Request
{
"ipn": "string",
"terminalId": "string"
}
Example Response
{
"statusCode": 90000
"data": {
"statusCode": 90000,
"message": "IPN validation was successful",
"data": {
"name": "John Doe",
"ipn": "161436499556",
"amount": 50,
"phoneNumber": "09876123454",
"status": "pending"
}
Make IGR Payment
The endpoint is used to send payment notification to any state IGR integrated into Biller Platform.
Request
METHOD: POST
URL: https://api.hydrogenpay.com/sb/resellerservice/api/IGRPayments/osun/validate-ipn
Request Parameters
Parameter | Type | Description |
---|---|---|
ipn | String | The unique identifier for the betting biller system. |
terminalId | . | |
billerSystemId | ||
amount | ||
paidAt | ||
clientReference |
Response Parameters
Field | Type | Description |
---|---|---|
id | The unique identifier for the betting biller system. | |
ipn | ||
status | ||
amount | ||
description | ||
narration | ||
company | ||
paid_at | ||
metadata | ||
created_at | ||
updated_at | ||
customer | ||
id | ||
pid | ||
name | ||
phone | ||
address |
Example Request
{
"ipn": "string",
"terminalId": "string",
"billerSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 0,
"paidAt": "2024-07-25T12:36:37.687Z",
"clientReference": "string"
}
Example Response
{
"statusCode": 90000
"data": {
"data": {
"id": 4,
"ipn": "274500900554",
"status": "paid",
"amount": 100,
"description": "ICT Related Services",
"narration": null,
"company": null,
"paid_at": "2024-02-03T15:12:56.000000Z",
"metadata": null,
"created_at": "2023-02-23T07:33:20.000000Z",
"updated_at": "2024-05-02T12:31:58.000000Z",
"customer": {
"id": 37,
"pid": "76322122",
"name": "Ayebatari Fatima Odunayo",
"email": "[email protected]",
"phone": "+2348194650928",
"address": null
}