API Documentation

Overview

The Vido API is a reseller-order API. It only processes orders for airtime, data, cable TV, electricity, ePINs and betting funding and lets you check their status. It does not handle account creation, login, wallet transfers or profile management – those are handled on the main website.

Base URL

https://awasub.com/api

Response Format

Success Response:

{
  "success": true,
  "message": "Success",
  "data": {},
  "timestamp": "2024-01-01 12:00:00"
}

Error Response:

{
  "success": false,
  "message": "Error message",
  "errors": null,
  "timestamp": "2024-01-01 12:00:00"
}

Authentication

API tokens are not issued through this API. They can only be generated from your account on the website, under Account → API Access, and only after your KYC verification has been approved (status "verified"). Every request to this API is re-checked against your KYC status.

Include the token in the Authorization header on every request:

Authorization: Bearer awasub_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Only one active token per account is issued at a time; regenerating a token immediately revokes the previous one.

Balance & Catalogue

GET /balance

Wallet Balance

Returns the available wallet balance used to fund orders.

Example Response

{
  "success": true,
  "message": "Success",
  "data": {
    "available_balance": 5000,
    "currency": "NGN"
  },
  "timestamp": "2024-01-01 12:00:00"
}

GET /services

List Services

Lists active reseller services. Optional category query parameter: 1=airtime, 2=data, 3=electricity, 4=cabletv, 6=betting.

Example Request

GET /api/services?category=1

Example Response

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": 1,
      "category_id": 1,
      "name": "MTN Airtime",
      "slug": "mtn-airtime",
      "service_code": "mtn",
      "min_amount": 50,
      "max_amount": 50000,
      "currency": "NGN"
    }
  ],
  "timestamp": "2024-01-01 12:00:00"
}

GET /services/{id}/plans

List Data / TV Plans

Fetches selectable variations (bundles/packages) for a data (category 2) or cable TV (category 4) service, live from the provider.

Example Response

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "variation_id": "1",
      "name": "1GB - 30 Days",
      "amount": 300,
      "display_amount": 300
    }
  ],
  "timestamp": "2024-01-01 12:00:00"
}

GET /discos

List Electricity Discos

Lists active electricity distribution companies used with the Electricity endpoint.

Orders

GET /orders

List Orders

Paginated list of your orders. Query parameters: page, per_page (max 100).

Example Response

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "uuid": "a1b2c3d4-...",
      "reference": "AIR-1A2B3C4D5E",
      "category_id": 1,
      "status": "completed",
      "phone": "2348012345678",
      "amount": 100,
      "fee": 0,
      "total_amount": 100,
      "currency": "NGN",
      "provider_reference": "VTU-...",
      "error_message": null,
      "created_at": "2024-01-01 12:00:00",
      "completed_at": "2024-01-01 12:00:05"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_items": 1,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  },
  "timestamp": "2024-01-01 12:00:00"
}

GET /orders/{uuid}

Order Status

Returns the details and status of a single order belonging to the authenticated account.

Example Response

{
  "success": true,
  "message": "Success",
  "data": {
    "uuid": "a1b2c3d4-...",
    "reference": "AIR-1A2B3C4D5E",
    "category_id": 1,
    "status": "completed",
    "phone": "2348012345678",
    "amount": 100,
    "fee": 0,
    "total_amount": 100,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Buy Airtime

POST /orders/airtime

Debits your wallet and purchases airtime. Amount must be within the service's min/max range.

Parameter	Type	Required	Description
service_id	integer	Yes	Airtime service id (category 1), see `/services?category=1`
phone	string	Yes	Recipient phone number (10/11 digit local or 234-prefixed)
amount	number	Yes	Airtime amount

Example Request

POST /api/orders/airtime
service_id=1&phone=08012345678&amount=500

Example Response

{
  "success": true,
  "message": "Order completed successfully",
  "data": {
    "uuid": "a1b2c3d4-...",
    "reference": "AIR-1A2B3C4D5E",
    "category_id": 1,
    "status": "completed",
    "phone": "2348012345678",
    "amount": 500,
    "fee": 0,
    "total_amount": 500,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Buy Data

POST /orders/data

Fetch a variation_id from /services/{id}/plans first, then submit the order.

Parameter	Type	Required	Description
service_id	integer	Yes	Data service id (category 2)
phone	string	Yes	Recipient phone number
variation_id	string	Yes	Data plan variation id

Example Request

POST /api/orders/data
service_id=8&phone=08012345678&variation_id=1

Example Response

{
  "success": true,
  "message": "Order completed successfully",
  "data": {
    "uuid": "b2c3d4e5-...",
    "reference": "DATA-2B3C4D5E6F",
    "category_id": 2,
    "status": "completed",
    "phone": "2348012345678",
    "amount": 300,
    "fee": 0,
    "total_amount": 300,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Cable TV Subscription

POST /orders/cabletv

Verifies the smartcard number with the provider before charging your wallet.

Parameter	Type	Required	Description
service_id	integer	Yes	Cable TV service id (category 4)
smartcard_number	string	Yes	Smartcard / IUC number
variation_id	string	Yes	TV package variation id from `/services/{id}/plans`

Example Request

POST /api/orders/cabletv
service_id=12&smartcard_number=1234567890&variation_id=3

Example Response

{
  "success": true,
  "message": "Order completed successfully",
  "data": {
    "uuid": "c3d4e5f6-...",
    "reference": "TV-3C4D5E6F7A",
    "category_id": 4,
    "status": "completed",
    "smartcard_number": "1234567890",
    "amount": 4500,
    "fee": 0,
    "total_amount": 4500,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Electricity Bill Payment

POST /orders/electricity

Verifies the meter number with the disco before charging your wallet.

Parameter	Type	Required	Description
disco_id	integer	Yes	Disco id, see `/discos`
meter_type	string	Yes	`prepaid` or `postpaid`
meter_number	string	Yes	Meter number
amount	number	Yes	Payment amount

Example Request

POST /api/orders/electricity
disco_id=1&meter_type=prepaid&meter_number=12345678901&amount=2000

Example Response

{
  "success": true,
  "message": "Order completed successfully",
  "data": {
    "uuid": "d4e5f6a7-...",
    "reference": "ELEC-4D5E6F7A8B",
    "category_id": 3,
    "status": "completed",
    "meter_number": "12345678901",
    "amount": 2000,
    "fee": 0,
    "total_amount": 2000,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Buy ePINs

POST /orders/epins

Purchases fixed-denomination recharge ePINs.

Parameter	Type	Required	Description
service_id	integer	Yes	Network service id (category 1)
value	integer	Yes	One of 100, 200, 500, 1000
quantity	integer	Yes	Between 1 and 10

Example Request

POST /api/orders/epins
service_id=1&value=200&quantity=2

Example Response

{
  "success": true,
  "message": "Order completed successfully",
  "data": {
    "uuid": "e5f6a7b8-...",
    "reference": "EPIN-5E6F7A8B9C",
    "category_id": 5,
    "status": "completed",
    "amount": 400,
    "fee": 0,
    "total_amount": 400,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Fund Betting Account

POST /orders/betting

Tops up a betting platform account/wallet.

Parameter	Type	Required	Description
service_id	integer	Yes	Betting platform service id (category 6)
customer_id	string	Yes	Betting account id / username
amount	number	Yes	Funding amount

Example Request

POST /api/orders/betting
service_id=20&customer_id=my_betting_id&amount=1000

Example Response

{
  "success": true,
  "message": "Order completed successfully",
  "data": {
    "uuid": "f6a7b8c9-...",
    "reference": "BET-6F7A8B9C0D",
    "category_id": 6,
    "status": "completed",
    "meter_number": "my_betting_id",
    "amount": 1000,
    "fee": 0,
    "total_amount": 1000,
    "currency": "NGN",
    "provider_reference": "VTU-...",
    "error_message": null,
    "created_at": "2024-01-01 12:00:00",
    "completed_at": "2024-01-01 12:00:05"
  },
  "timestamp": "2024-01-01 12:00:00"
}

Errors

Status Code	Description
400 Bad Request	Invalid request or business rule violation (e.g. insufficient balance)
401 Unauthorized	Missing, invalid or revoked API token
403 Forbidden	Account not permitted, or KYC not yet verified
404 Not Found	Resource not found
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500/502/503	Server or upstream provider error

Rate Limiting: API requests are limited to 100 requests per hour per IP address. Rate limit headers are included in responses.

Vido API Documentation

Overview

Base URL

Response Format

Authentication

Balance & Catalogue

Wallet Balance

List Services

Example Request

List Data / TV Plans

List Electricity Discos

Orders

List Orders

Order Status

Buy Airtime

Example Request

Buy Data

Example Request

Cable TV Subscription

Example Request

Electricity Bill Payment

Example Request

Buy ePINs

Example Request

Fund Betting Account

Example Request

Errors