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

Status Codes

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

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

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

Response parameters

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

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

Response parameters

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

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.

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

Response parameters

Data Object

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

Response Parameters

rawOutput Fields

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

Response Parameter

RawOutput Fields

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

Response Parameters

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

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

Data Object Structure

The data array contains objects with the following fields:

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

Response Parameters

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

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

Raw Output Fields

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

Response Parameters

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

Response Parameters

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

Response Parameters

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.