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	Validate the Instant Payment Number (IPN) for a state Internal Generated Revenue (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 allows resellers to authenticate and obtain a valid token for accessing other endpoints within the VAS Reseller platform. Authentication requires the reseller's email and an encrypted password. The password must be encrypted using the secret key and ClientIV provided during onboarding.

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 encrypted password using the secret key & ClientIV.

Sample Request

{
  "username": "email@accessbank.com",
  "password": "cPXja5M0rO0e4zVyBTBvaQ=="
}

Sample Response

{
  "statusCode": 90000,
  "message": "Operation Successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwOGRjNDdlOC01ZTMzLWM5NTItMWFhMy00YjQzM2U4ZTAwMDAiLCJpc3MiOiJoeXJvZ2VuLmNvbSIsImlhdCI6MTcxMTA4Mjc1MiwiZXhwIjoxNzExMDg2MzUyLCJ1bmlxdWVfbmFtZSI6Im9udWZyYW5rbGlub2t3dWRpbGkrNUBnbWFpbC5jb20iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6IjA4ZGM0N2U4LTVlMzMtYzk1Mi0xYWEzLTRiNDMzZThlMDAwMCIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2dpdmVubmFtZSI6IjViZGZkNzFhLTM4OGQtYjFmYi1hMWM5LTg2Y2ViZGY1NGE0MSJ9.aLalmgfidFGFZspT_DRehrktmRIss9cJXotStPfx",
    "email": "email@accessbank.com",
    "resellerId": "579fb9be-cfd4-459a-a5a9-08dc481b122c"
  }
}

Once the login request is successful, the obtained token must be included in the Authorization header as a Bearer Token for all subsequent API requests.

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.
email	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@accessbank.com",
    "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

☑️
URL: <https://api.hydrogenpay.com/sb/resellerservice/api/VtuPayment/get-phone-network-provider?customerId=07062631588>

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:

☑️
URL: <https://api.hydrogenpay.com/sb/resellerservice/api/VtuPayment/requery-purchase-by-ref?transactionReferenceId=>

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://qa-api.hydrogenpay.com/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.
ServiceType	String	Unique Reference of the Disco

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": "fd4c3ac8-629a-4e23-0bdc-08dc96f033de",
    "accountNumber": "4313185093",
    "amount": 1000,
    "phoneNumber": "07033102077",
    "serviceType":"AbaPower",
    "clientReference": "TestingAbaElectric001"
}

Sample Response

{
  "statusCode": 90000,
    "message": "Electricity bill payment was successful",
    "data": {
        "transactionRef": "TestingAbaElectric001",
        "transactionStatus": "SUCCESSFUL",
        "data": {
            "statusCode": "200",
            "transactionStatus": "successful",
            "transactionReference": "TestingAbaElectric001",
            "transactionMessage": "successful",
            "tokenCode": "0000 0000 0000 0000",
            "tokenAmount": 1000,
            "amountOfPower": "0.0Kwh",
            "creditToken": "0000 0000 0000 0000",
            "rawOutput": {
                "message": "successful",
                "account": "4313185093",
                "category": "postpaid",
                "transactionRef": "TestingAbaElectric001",
                "vendorName": "testadmin",
                "vendorBal": "99175473",
                "unit": "0.0Kwh",
                "arrears": 44508.4,
                "token": "0000 0000 0000 0000",
                "meterNumber": "",
                "arrearsPaid": 0,
                "buckets": []
            }
        }
    }   
 
}

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://qa-api.hydrogenpay.com/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.
productCode	String	The Biller name from Reseller-my-biller

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
email	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).
vendors_allowed	String	Vendors that are permitted by Disco to vend Token for meter number

Sample Request

{
  "accountNumber": "4313185093",
  "billerSystemId": "fd4c3ac8-629a-4e23-0bdc-08dc96f033de",
 "productCode": "aba_electric_prepaid"
 
}

Example Response

{
    "statusCode": 90000,
    "message": "Operation Successful",
    "description": "Account verification was successful",
    "data": {
        "name": "A.A.C CHURCH",
        "address": "ACCHURCH          OHANKU TOWN IKWUORIE",
        "outstandingBalance": 45508.4,
        "district": "ARIARIA DISTRICT",
        "minimumAmount": null,
        "rawOutput": {
            "email": null,
            "tariffCode": "R2SB-NMD",
            "phoneNumber": "7038120046",
            "meterNumber": null,
            "undertaking": null,
            "businessUnit": "ARIARIA DISTRICT",
            "customerName": "A.A.C CHURCH",
            "accountNumber": "4313185093",
            "customerArrears": 45508.4,
            "minimumPurchase": null
        },
        "hasDiscount": false,
        "paycode": "postpaid",
        "txnRef": null,
        "errorMessage": null
    }
}

This endpoint helps resellers to ensure the accuracy of meter numbers and retrieve important information before processing electricity meter top-ups.

Requery Electricity

This endpoint is used to requery an electricity transaction to verify the latest status of the transaction from the system. its important to call this API after a purchase to confirm the final status of a transaction before moving on. If transaction is still pending then its advised to keep trying this API till a conclusive status is returned. Incase of a downtime when Electricity purchase was called, this API can used to fetch the Meter token, arrears and other details of the purchase.

Request

METHOD: GET

☑️
<https://qa-api.hydrogenpay.com/resellerservice/api/BillPayment/requery-electricity?clientReference=[ClientReference]

Request Parameters

Parameter	Type	Description
Clientreference	String	The unique reference for the transaction

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.
Statuscode	number	status code of the operation from provider
transactionStatus	String	Status label of the transaction
transactionReference	String	Unique Reference name of the transaction from the provider
transactionMessage	String	Message from Provider describing status of Transaction
tokenCode	String	Unique Token for the electricity purchase
tokenAmount	Number	Amount for the Token Vended
amountOfPower	String	Amount of Units vended in KWH
creditToken	String	Unique Token for the electricity purchase
rawOutput	Object	Raw output details from our system

RawOutput Fields

Field	Type	Description
message	String	Transaction status from Provider
account	String	Meter number
category	String	category of Reseller in the system
transactionRef	String	Unique identifier of the transaction in the system
vendorName	String	Reseller name
vendorBal	Number	more information about Reseller
unit	String	Value of Units purchased
arrears	String	Arrears recorded by Disco for Meter number
token	String	Token details of the transaction
arrearsPaid	Number	Arrears record by the Disco for that meter number

Example Response

{
    "statusCode": 90000,
    "message": "Transaction status retrieved successfully.",
    "data": {
        "status": "true",
        "message": "successful",
        "code": "200",
        "data": {
            "statusCode": "200",
            "transactionStatus": "successful",
            "transactionReference": "TestingAbaElectric0051",
            "transactionMessage": "successful",
            "tokenCode": "0000 0000 0000 0000",
            "tokenAmount": 1000,
            "amountOfPower": "0.0Kwh",
            "creditToken": "0000 0000 0000 0000",
            "rawOutput": {
                "message": "successful",
                "account": "4313185093",
                "category": "postpaid",
                "transactionRef": "TestingAbaElectric0051",
                "vendorName": "testadmin",
                "vendorBal": "99155460",
                "unit": "0.0Kwh",
                "arrears": 23507.4,
                "token": "0000 0000 0000 0000",
                "meterNumber": "",
                "arrearsPaid": 0,
                "buckets": []
            }
        }
    }
}

This endpoint helps resellers to verify the conclusive status of an electricity purchase call using the client reference

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

☑️
URL: <https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/cabletv/%7BBillersystemId%7D/product-codes?page=1>

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

☑️
URL: <https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/cabletv/%7BBillersystemId%7D/addon-codes?page=1>

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

☑️
URL: <https://api.hydrogenpay.com/sb/resellerservice/api/BillPayment/jamb/pricing-options?BillerSystemId={BillerSystemId}>

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.