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 LoginEndpoint used for authenticating and logging in resellers into the system.
About MeEndpoint to fetch detailed information about the logged-in reseller, including profile data.
Assigned BillerEndpoint to retrieve the list of billers assigned to the reseller's account.
Enable/Disable BillerEndpoint allowing resellers to enable or disable specific billers for transactions.
Validate Phone NetworkEndpoint used to validate the network provider of a phone number before top-up operations.
Purchase VTUEndpoint for resellers to purchase airtime or data top-ups on behalf of their customers.
Get Bouquet CodesEndpoint to obtain bouquet codes corresponding to different data plans offered by billers.
Transaction HistoryEndpoint providing access to the transaction history of the reseller's account.

Status Codes

Status CodeTypeDescription
90000CustomOperation Successful
10001CustomUnexpected Error
10002CustomInvalid Request
10003CustomUnauthorised
10004CustomNot Found Exception
10005CustomDuplicate Request

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 Me

The About Me 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.

Assigned Biller

The Assigned Biller endpoint is a GET method that allows resellers to retrieve the biller IDs assigned to them by Hydrogen. This endpoint also provides information about the commission rates agreed upon with each biller.

Resellers can use this endpoint to obtain the BillerSystemId for any biller they wish to purchase from within the platform. This endpoint requires authorization through a valid bearer token passed in the header of the API call.

Request

METHOD: GET

🚧

URL: https://api.hydrogenpay.com/sb/resellerservice/api/Biller/get-assigned-billers

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 Assigned Biller endpoint provides resellers with essential information about the billers assigned to them, including the BillerSystemId and commission rates. This information is important for resellers to facilitate biller transactions and manage commission agreements effectively within the platform.

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

Sample Response

{
  "resellerId": "1c582a5b-5683-4e7f-ccad-08dc480e792",
  "walletId": "53c81c51-e08b-4e04-371c-08dc480d558",
}

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

{
  "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/get-phone-network-provider?customerId=07062631588

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".

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"
}

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": "AIRTIME"
}

Sample Response

{
  "statusCode": 90000,
  "message": "Success"
}

Before calling this endpoint, ensure that you have obtained the necessary IDs and codes from the respective endpoints mentioned in the documentation. 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

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.

Transaction History

This GET method endpoint retrieves the transaction history of the reseller based on the provided token. It allows developers to access detailed information about past transactions made by the reseller, including transaction dates, reference IDs, product names, biller names, amounts, statuses, and more.

Request

METHOD: GET

🚧

URL: https://api.hydrogenpay.com/sb/resellerservice/api/ResellerTransaction/reseller-trans-history

Request parameters

NameTypeDescription
resellerIdStringIdentifier for the reseller.
pageIntegerPage number for paginated results.
pageSizeIntegerNumber of transactions per page.

Response parameters

NameTypeDescription
statusCodeIntegerStatus code indicating the result of the operation.
messageStringDescription of the operation status.
dataObjectContainer for transaction data.

Data Objects

NameTypeDescription
transactionDateStringDate and time of the transaction.
transactionReferenceIdStringUnique identifier for the transaction.
productNameStringName of the product/service involved in the transaction.
productCategoryStringCategory of the product/service.
billerNameStringName of the biller.
receiverNameStringName of the receiver/customer.
amountStringTotal amount of the transaction.
amountDeductedStringAmount deducted from the reseller's wallet.
statusStringStatus of the transaction (e.g., SUCCESSFUL, FAILED).
walletIdStringIdentifier of the reseller's wallet.
paymentChannelStringChannel through which the payment was made (e.g., WEB, MOBILE).
resellerNameStringName of the reseller initiating the transaction.
commentStringAdditional comments or notes about the transaction.
commissionStringCommission deducted from the transaction amount.
providerIdStringIdentifier of the service provider.

Sample Request

{
  "resellerId": "56a1282-a499-475e-371b-08dc480d5598",
  "page": 2,
  "pageSize": 20
}

Sample Response

{
  "statusCode": 90000,
  "message": "Operation Successful",
  "data": {
    "data": [
      {
        "transactionDate": "2024-03-22T06:10:29.170436",
        "transactionReferenceId": "80d36938-8c71-4658-ba78-855e6eef29f8",
        "productName": "BILLS PAYMENT",
        "productCategory": "BILLS PAYMENT",
        "billerName": "Airtel DATA",
        "receiverName": "Airtel DATA-08024532388",
        "amount": 1000.00000,
        "amountDeducted": 900.00000,
        "status": "SUCCESSFUL",
        "walletId": "1c582a5b-5683-4e7f-ccad-08dc480e792d",
        "paymentChannel": "WEB",
        "resellerName": "Onu Obumsdili",
        "comment": "Data topup was successful",
        "commission": 100.00000,
        "providerId": "c5b83b59-542a-4387-b1b9-7cf8c4482b56"
      },
      {
        "transactionDate": "2024-03-21T11:32:21.2385308",
        "transactionReferenceId": "90205ad7-e225-4ca5-8aa1-a701cdf1d4b0",
        "productName": "BILLS PAYMENT",
        "productCategory": "BILLS PAYMENT",
        "billerName": "Airtel DATA",
        "receiverName": "Airtel DATA-08024532388",
        "amount": 1000.00000,
        "amountDeducted": 900.00000,
        "status": "SUCCESSFUL",
        "walletId": "1c582a5b-5683-4e7f-ccad-08dc480e792d",
        "paymentChannel": "WEB",
        "resellerName": "Onu Obumsdili",
        "comment": "Data topup was successful",
        "commission": 100.00000,
        "providerId": "c5b83b59-542a-4387"
      }
    ]
  }
}

This endpoint provides a comprehensive view of the reseller's transaction history, enabling developers to track and manage transactions efficiently within their applications.