API Documentation

1. User Login API

POST yoursiteurl.vendutility.com/api/v1/auth/

Description: This API endpoint handles user login by validating the provided email and password. If the credentials are correct, it generates JWT access and refresh tokens for the authenticated user. If the credentials are invalid, it returns an error message.

Request Body:

{
  "email": "[email protected]",
  "password": "user_password"
}

Fields:

email (string): The email address of the user.
password (string): The password of the user.

Response:

Successful Response:

{
  "status": true,
  "BearerToken": "access_token_here",
  "refresh_token": "refresh_token_here"
}

BearerToken (string): The JWT access token for the user.
refresh_token (string): The JWT refresh token for the user.

Failed Response (User does not exist):

{
  "status": false,
  "message": "User does not exist"
}

Failed Response (Invalid credentials):

{
  "status": false,
  "message": "Invalid credentials"
}

Failed Response (Internal Server Error):

{
  "status": false,
  "message": "An error occurred: [error_details]"
}

2. Airtime Purchase API

POST yoursiteurl.vendutility.com/api/v1/airtime/

Description: This API allows an authenticated user to purchase airtime. It checks the user's wallet balance and processes the purchase with an external service provider's API. The wallet is debited with the airtime amount, and the transaction is logged.

Request Body:

{
  "card_phone_number": "08012345678",
  "card_amount": "1000",
  "card_network": 1
}

Fields:

card_phone_number (string): The phone number to which the airtime will be credited.
card_amount (string): The amount of airtime to purchase (must be a valid integer).
card_network (integer): The network for the airtime purchase (e.g., 1 for MTN, 2 for GLO, etc.).

Response:

Successful Response:

{
  "status": true,
  "data": {
    "id": 123,
    "customer": "[email protected]",
    "amount": "1000.00",
    "phone_number": "08012345678",
    "wallet_balance": "1500.00",
    "old_wallet_balance": "2500.00",
    "status": "Transaction Successful",
    "api_transaction_id": "transaction_reference_token",
    "transaction_response": "API response text here",
    "active_api": "Plugin Name"
  }
}

data (object): Contains details of the transaction.

id (integer): Transaction ID.
customer (string): The email of the user.
amount (decimal): The amount of airtime purchased.
phone_number (string): The phone number to which airtime was sent.
wallet_balance (decimal): The remaining wallet balance after the transaction.
old_wallet_balance (decimal): The wallet balance before the transaction.
status (string): Status of the transaction (e.g., "Transaction Successful").
api_transaction_id (string): The transaction reference ID from the external API.
transaction_response (string): The response from the external API.
active_api (string): The name of the active API used for the transaction.

Failed Response (Invalid Input Amount):

{
  "status": false,
  "message": "Invalid Input Amount"
}

Failed Response (Card Amount Must Be a Valid Integer):

{
  "status": false,
  "message": "Card amount must be a valid integer"
}

Failed Response (Insufficient Wallet Balance):

{
  "status": false,
  "message": "Insufficient Fund In Wallet, You Currently have #500"
}

Failed Response (Internal Server Error):

{
  "status": false,
  "message": "An error occurred: [error_details]"
}

3. Buy Data API

POST yoursiteurl.vendutility.com/api/v1/buy_data/

Description: This API allows the user to buy data by specifying the phone number, mobile network, data plan, and plan type. It performs balance validation, checks available plans, and processes the purchase using a third-party gateway.

Request Body:

{
  "phone_number": "user_phone_number",
  "mobile_network": 1,
  "data_plan": "data_plan_code",
  "plantype": "plan_type"
}

Fields:

phone_number (string): The phone number for the data purchase.
mobile_network (integer): The mobile network identifier (1 for MTN, 2 for Glo, etc.).
data_plan (string): The unique code representing the data plan.
plantype (string): The type of data plan (e.g., 3G, 4G, etc.).

Response:

Successful Response:

{
  "status": true,
  "data": {
    "transaction_id": "transaction_reference_token",
    "amount": 1000,
    "phone_number": "user_phone_number",
    "status": "Transaction Successful"
  }
}

Failed Response (Insufficient Balance):

{
  "status": false,
  "message": "Insufficient Wallet Balance"
}

Failed Response (Invalid Data Plan):

{
  "status": false,
  "message": "Invalid Data Plan"
}

Failed Response (Transaction Failed):

{
  "status": false,
  "message": "Transaction Not Successful"
}

4. Buy Cable API

POST yoursiteurl.vendutility.com/api/v1/cable/

Description: This API allows the user to purchase cable subscription for services like DSTV, GOTV, or Startimes. It requires the Smart IUC number, cable network, and cable plan.

Request Body:

{
  "smartIUCNumber": "IUC_number_here",
  "cable_network": 1,
  "cable_plan": "cable_plan_code"
}

Fields:

smartIUCNumber (string): The unique smart IUC number for the cable account.
cable_network (integer): The cable network identifier (e.g., 1 for DSTV, 2 for GOTV).
cable_plan (string): The code for the cable plan to be purchased.

Response:

Successful Response:

{
  "status": true,
  "data": {
    "transaction_id": "transaction_reference_token",
    "amount": 3000,
    "smartIUCNumber": "IUC_number_here",
    "status": "Transaction Successful"
  }
}

Failed Response (Insufficient Balance):

{
  "status": false,
  "message": "Insufficient Wallet Balance"
}

Failed Response (Invalid Cable Plan):

{
  "status": false,
  "message": "Invalid Cable Plan"
}

Failed Response (Transaction Failed):

{
  "status": false,
  "message": "Transaction Not Successful"
}

5. Electricity Purchase API

POST yoursiteurl.vendutility.com/api/v1/electricity/

Description: This API allows the user to purchase electricity. The request must include the meter number, service type, and amount to be purchased.

Request Body:

{
  "meter_number": "1234567890",
  "service_type": "prepaid",
  "amount": 1000
}

Fields:

meter_number (string): The meter number to which electricity will be purchased.
service_type (string): Type of service (e.g., 'prepaid' or 'postpaid').
amount (integer): The amount of electricity to purchase in local currency.

Response:

Successful Response:

{
  "status": true,
  "data": {
    "transaction_id": "transaction_reference_token",
    "amount": 1000,
    "status": "Transaction Successful"
  }
}

Failed Response (Invalid Meter Number):

{
  "status": false,
  "message": "Invalid Meter Number"
}

Failed Response (Insufficient Balance):

{
  "status": false,
  "message": "Insufficient Wallet Balance"
}

Failed Response (Transaction Failed):

{
  "status": false,
  "message": "Transaction Not Successful"
}

6. Validate Smart IUC API

POST yoursiteurl.vendutility.com/api/v1/validate-smart_cable/

Description: This API validates the Smart IUC (Identification Code) for a user to proceed with their electricity purchase or validation.

Request Body:

{
  "smart_iuc": "smart_iuc_code_here"
}

Fields:

smart_iuc (string): The Smart IUC code to validate.

Response:

Successful Response:

{
  "status": true,
  "data": {
    "valid": true,
    "message": "Smart IUC is valid."
  }
}

Failed Response (Invalid Smart IUC):

{
  "status": false,
  "message": "Invalid Smart IUC"
}

Failed Response (Internal Server Error):

{
  "status": false,
  "message": "An error occurred: [error_details]"
}

7. Validate Meter API

POST yoursiteurl.vendutility.com/api/v1/validate_electricity/

Description: This API validates the meter number before allowing the user to proceed with the electricity purchase.

Request Body:

{
  "meter_number": "1234567890"
}

Fields:

meter_number (string): The meter number to validate.

Response:

Successful Response:

{
  "status": true,
  "data": {
    "valid": true,
    "message": "Meter number is valid."
  }
}

Failed Response (Invalid Meter Number):

{
  "status": false,
  "message": "Invalid Meter Number"
}

Failed Response (Internal Server Error):

{
  "status": false,
  "message": "An error occurred: [error_details]"
}