Dashboard

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

EndpointsDescription
Reseller LoginUsed for authenticating and logging in resellers into the system.
About MeTo fetch detailed information about the logged-in reseller, including profile data.
Reseller My BillerProvides information about the billers available for purchase.
Assigned BillerTo retrieve the list of billers assigned to the reseller's account.
Enable/Disable BillerAllows resellers to enable or disable specific billers for transactions.
Validate Phone NetworkUsed to validate the network provider of a phone number before top-up operations.
Purchase VTUFor resellers to purchase airtime or data top-ups on behalf of their customers.
Get Bouquet CodesTo obtain bouquet codes corresponding to different data plans offered by billers.
Purchase ElectricityManage and facilitate electricity meter recharges.
Validate Meter NumberRetrieve the details of an electricity meter number before proceeding with a top-up.
Purchase CableTVProcess CableTV subscriptions for Smartcard numbers, supports DSTV, GOTV, Startimes, and Showmax
Get ProductCodeObtain accurate and up-to-date product codes and their pricing options,
Get Adds-onTo obtain accurate and up-to-date add-on codes and their pricing options,
Purchase JAMBFacilitates the top-up of a candidate's account for JAMB services
Get Jamb Pricing OptionRetrieves a list of all product codes and their corresponding amounts for JAMB services.
Get Jamb Candidate DataValidate the details of a candidate before making a JAMB payment
Purchase EPINRetrieves ePIN top-up codes for WAEC and Spectranet biller products.
Fund Betting WalletTop-up their betting wallet accounts
Verify Betting Account NameVerify the details of the betting account before topping up the wallet.
Validate IPN
Make IGR Payment

Status Codes

Status CodeTypeDescription
90000CustomOperation Successful
10001CustomUnexpected Error
10002CustomInvalid Request
10003CustomUnauthorised
10004CustomNot Found Exception
10005CustomDuplicate 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

TypeNameComment
StringusernameThe reseller's email address.
StringpasswordThe reseller's password.
StringdeviceTokenDevice 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

NameTypeDescription
statusCodeIntegerStatus code indicating the success of the operation.
messageStringA message indicating the outcome of the operation.
dataObjectContains detailed information about the reseller.
firstNameStringThe first name of the reseller.
lastNameStringThe last name of the reseller.
phoneNumberStringThe phone number of the reseller.
emailStringThe email address of the reseller.
walletIDStringThe wallet ID associated with the reseller.
channelIdStringThe channel ID associated with the reseller.
resellerIdStringThe unique ID of the reseller.
resellerStatusStringThe status of the reseller account (e.g., ACTIVE).
hasPinBooleanIndicates whether the reseller has set a PIN.
walletObjectContains 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

NameTypeDescription
ResellerIdStringThe unique ID assigned to the reseller.

Response parameters

NameTypeDescription
statusCodeIntegerStatus code indicating the success of the operation.
messageStringA message indicating the outcome of the operation.
dataArrayArray of objects containing details about assigned billers.
billerNameStringThe name of the assigned biller.
billerSystemIdStringThe unique ID of the assigned biller system.
isEnabledStringIndicates whether the biller is active or not.
billerCategoryNameStringThe category name of the biller (e.g., Virtual TopUp).
commissionFloatThe 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

NameTypeDescription
ResellerIdStringThe unique ID of the reseller.
WalletIdStringThe unique ID of the wallet associated with the biller.
BillerSystemIdStringThe unique ID of the biller system to enable or disable.
isEnabledBooleanIndicates 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

NameTypeDescription
CustomerIdStringThe phone number to validate the network for.

Response parameters

NameTypeDescription
statusCodeIntegerStatus code indicating the success of the operation.
messageStringA message indicating the outcome of the operation.
descriptionStringAdditional description providing details about the operation status.
dataObjectContains detailed information about the validation result.
statusStringThe status of the validation (e.g., Success).
messageStringAdditional message providing details about the validation status.
defaultNetworkStringThe 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

NameTypeDescription
resellerIdStringThe unique ID of the reseller, obtained from the "login" or "About me" endpoint.
billerSystemIdStringThe unique ID of the biller system to purchase from, obtained from the "Get Assigned Biller" endpoint.
amountDecimalThe amount of the top-up to purchase, in the currency specified by the biller system.
phoneNumberStringThe phone number to top up.
bouquetCodeStringThe bouquet code for data top-ups. Required for data purchases, obtained from the "Get Bouquet Code" endpoint.
productTypeStringThe type of product to purchase, either "AIRTIME" or "DATA".
clientReferenceStringThe 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

NameTypeDescription
searchStringFilter by any value within the response

Response parameters

NameTypeDescription
statusCodeIntegerStatus code indicating the result of the request
messageStringIndicates the status of the request (Success/Error)
descriptionStringAdditional description of the request status
dataArrayList of bouquet codes and their details

Data Object

NameTypeDescription
bouquetCodeStringUnique code representing the bouquet
nameStringName or description of the bouquet
priceStringSelling price of the bouquet
typeStringType of plan (Daily, Weekly, Monthly, etc.)
billerIdStringID of the biller associated with the bouquet
providerIdStringID of the service provider
idStringUnique identifier for the bouquet
createdDateStringDate and time when the bouquet was created
updatedDateStringDate and time when the bouquet was last updated
rowVersionStringVersion 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the biller.
amountNumberThe amount to be recharged.
accountNumberStringThe electricity meter number.
phoneNumberStringThe phone number of the customer.
clientReferenceStringA unique reference for the transaction.

Response Parameters

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDetailed description of the transaction result.
dataObjectContains detailed transaction information.
transactionStatusStringOverall status of the transaction.
transactionRefStringUnique reference for the transaction.
transactionMessageStringMessage describing the transaction result.
provider_messageStringMessage from the provider regarding the transaction.
tokenCodeStringThe token code generated for the electricity recharge.
tokenAmountNumberAmount of the token (if applicable).
amountOfPowerNumberAmount of power credited to the meter.
creditTokenStringCredit token (if applicable).
rawOutputObjectRaw output details from the provider.

rawOutput Fields

FieldTypeDescription
kct1StringProvider-specific field.
kct2StringProvider-specific field.
tokenStringThe token generated for the electricity recharge.
statusStringStatus of the transaction from the provider.
errorCodeStringError code (if any).
tariffCodeStringTariff code associated with the meter.
tariffClassStringTariff class associated with the meter.
amountOfPowerNumberAmount of power credited to the meter.
rateStringRate applied for the transaction.
vatNumberValue-added tax amount for the transaction.
kwhNumberKilowatt-hour units credited.
unitNumberUnits credited to the meter.
meterNumberStringThe meter number that was recharged.
undertakingStringUndertaking information.
businessUnitStringBusiness unit information.
customerNameStringName of the customer associated with the meter.
errorMessageStringError message (if any).
accountNumberStringAccount number associated with the meter.
customerAddressStringAddress of the customer (if available).
customerBalanceNumberCustomer balance (if applicable).
exchangeReferenceStringExchange reference for the transaction.
externalReferenceStringExternal reference for the transaction.
transactionStatusStringFinal 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the biller.
accountNumberStringThe electricity meter number.

Response Parameter

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDetailed description of the verification result.
dataObjectContains detailed account information.
nameStringName of the account holder.
addressStringAddress associated with the meter number.
outstandingBalanceNumberOutstanding balance on the account.
districtStringDistrict of the account holder.
minimumAmountNumberMinimum amount for a transaction.
rawOutputObjectRaw output details from the provider.
hasDiscountBooleanIndicates if there is any discount.
errorMessageStringError message (if any).

RawOutput Fields

FieldTypeDescription
emailStringEmail of the account holder (if available).
tariffCodeStringTariff code associated with the meter.
phoneNumberStringPhone number of the account holder.
meterNumberStringThe meter number that was validated.
undertakingStringUndertaking information.
businessUnitStringBusiness unit information.
customerNameStringName of the customer associated with the meter.
accountNumberStringAccount number associated with the meter.
customerArrearsNumberCustomer arrears (if any).
minimumPurchaseNumberMinimum 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the biller.
smartCardNumberStringThe smart card number for DSTV, GOTV, or Startimes.
totalAmountNumberThe total amount for the subscription.
productCodeStringThe product code for the cable TV package.
addonCodeArrayThe add-on codes for additional packages.
productMonthsPaidForNumberThe number of months paid for the product.
phoneNumberStringThe phone number for Showmax subscriptions.
dataCodeStringThe data code for Showmax subscriptions.
clientReferenceStringA unique client reference for tracking the transaction.

Response Parameters

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDetailed description of the result.
dataObjectContains detailed transaction information.
referenceIdStringReference ID for the transaction.
transactionStatusStringStatus of the transaction.
transactionRefStringUnique 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

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
dataArrayContains a list of product codes and their pricing options.
availablePricingOptionsArrayContains pricing options for the product.
codeStringThe product code.
nameStringThe name of the product.
idStringThe unique identifier for the pricing option.
monthsPaidForNumberNumber of months the payment covers.
priceNumberPrice for the given period.
invoicePeriodNumberThe 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

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
dataArrayContains a list of add-on codes and their pricing options.

Data Object Structure

The data array contains objects with the following fields:

FieldTypeDescription
availablePricingOptionsArrayContains pricing options for the add-on.
codeStringThe add-on code.
nameStringThe name of the add-on.
descriptionStringDescription of the add-on.
idStringThe unique identifier for the pricing option.
monthsPaidForNumberNumber of months the payment covers.
priceNumberPrice for the given period.
invoicePeriodNumberThe 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the JAMB biller system.
amountNumberThe amount to be paid, which should match the JAMB pricing options.
accountNumberStringThe candidate's account number.
phoneNumberStringThe candidate's phone number.
productCodeStringThe product code for the JAMB service (e.g., UTME).
clientReferenceStringA unique client reference for the transaction.

Response Parameters

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDescription of the result of the operation.
dataObjectContains details of the transaction.
transactionStatusStringStatus of the transaction.
transactionRefStringReference ID of the transaction.
referenceIdStringThe unique reference ID for the transaction.
transactionStatusStringStatus 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

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
dataArrayContains a list of product codes and their pricing options.
idStringThe unique identifier for the product option.
amountNumberThe amount for the product option.
product_codeStringThe 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

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDescription of the result of the operation.
dataObjectContains details of the candidate.
nameStringThe full name of the candidate.
accountNumberStringThe candidate's account number.
rawOutputObjectContains raw data for the candidate details.

Raw Output Fields

FieldTypeDescription
errorStringError message, if any.
gsmNoStringThe candidate's GSM number.
lastNameStringThe candidate's last name.
firstNameStringThe candidate's first name.
middleNameStringThe 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the ePIN biller system.
pinValueNumberThe value of each PIN.
amountNumberThe total amount for the PIN(s).
numberOfPinsIntegerThe number of PINs to be purchased.
clientReferenceStringA unique reference number for the transaction.

Response Parameters

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDescription of the result of the operation.
dataObjectContains details of the ePIN and transaction status.
transactionStatusStringOverall transaction status.
transactionRefStringReference ID for the transaction.
ePINStringThe purchased ePIN code.
transactionStatusStringStatus 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the betting biller system.
accountNumberStringThe account number of the betting wallet to be funded.
actionStringThe action to be performed, which should be set to WALLET_FUNDING.
amountNumberThe amount to be funded into the betting wallet.
clientReferenceStringA unique reference number for the transaction.

Response Parameters

FieldTypeDescription
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDescription of the result of the operation.
dataObjectContains details of the transaction status.
transactionStatusStringOverall transaction status.
transactionRefStringReference 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

ParameterTypeDescription
billerSystemIdStringThe unique identifier for the betting biller system.
accountNumberStringThe account number of the betting wallet to be verified.

Response Parameters

FieldTypeDescription
billerSystemIdStringThe unique identifier for the betting biller system.
accountNumberStringThe account number of the betting wallet.
accountNameStringThe name associated with the betting account.
statusCodeIntegerStatus code of the operation.
messageStringMessage describing the result of the operation.
descriptionStringDescription 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

ParameterTypeDescription
ipnStringThe unique identifier for the betting biller system.
terminalIdStringThe account number of the betting wallet to be verified.

Response Parameters

FieldTypeDescription
nameThe 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

ParameterTypeDescription
ipnStringThe unique identifier for the betting biller system.
terminalId.
billerSystemId
amount
paidAt
clientReference

Response Parameters

FieldTypeDescription
idThe unique identifier for the betting biller system.
ipn
status
amount
description
narration
company
paid_at
metadata
created_at
updated_at
customer
id
pid
name
email
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
}