OresamSub API
VERSION 2.0
Built for digital-service businesses

One API.
Every transaction.

Connect your website to OresamSub with a predictable API for data, airtime, cable TV, electricity, wallet balance and transaction reconciliation.

https://oresamsub.com/api/v2

From token to first purchase

Every plan and price comes from your OresamSub account. Never hard-code plan prices.

1

Get a token

Generate your API token from your account and keep it on your server.

2

Sync plans

Fetch the catalogue and store the returned external plan IDs.

3

Submit safely

Send a unique reference, then reconcile it if your request times out.

Authentication

Send the token as a Bearer credential. API tokens must never be placed in browser JavaScript, URLs or public repositories.

Server-side only. Requests to OresamSub should originate from your application server, not directly from a customer’s browser.

Endpoints

GET/api/v2/catalogue

Returns active public data, airtime, cable and electricity plans at your account’s current price.

GET/api/v2/wallet

Returns your available main-wallet balance in NGN.

POST/api/v2/validate-customer

Validates a cable smartcard/IUC or electricity meter and returns a validation reference that remains valid for 10 minutes.

POST/api/v2/buy-service

Purchases data, airtime, cable or electricity through one consistent endpoint. Cable and electricity require a recent validation reference.

GET/api/v2/transactions/{reference}

Returns only a transaction owned by the authenticated business. Successful electricity responses include the meter token when supplied by the provider.

Cable and electricity flow

Both services use the same two endpoints: validate the customer first, then submit the purchase with the returned validation_reference.

Cable TV

Validate a smartcard or IUC before subscription.

Step 1 · Validate customer
POST/api/v2/validate-customer
{
  "service": "cable",
  "plan_id": 2101,
  "customer_number": "1234567890"
}
Step 2 · Buy cable plan
POST/api/v2/buy-service
{
  "service": "cable",
  "plan_id": 2101,
  "customer_number": "1234567890",
  "validation_reference": "VAL-EXAMPLE",
  "reference": "ORDER-10003"
}

Electricity

Validate a meter before purchasing units.

Step 1 · Validate customer
POST/api/v2/validate-customer
{
  "service": "electricity",
  "plan_id": 3101,
  "customer_number": "01234567890"
}
Step 2 · Buy electricity
POST/api/v2/buy-service
{
  "service": "electricity",
  "plan_id": 3101,
  "customer_number": "01234567890",
  "amount": 5000,
  "validation_reference": "VAL-EXAMPLE",
  "reference": "ORDER-10004"
}
Validation references expire after 10 minutes. They are locked to the authenticated business, selected plan and customer number.

Response examples

Formatted examples of the stable JSON envelope your integration should handle.

Success responses

GET /api/v2/catalogue200 SUCCESS
{
  "success": true,
  "message": "Catalogue fetched successfully.",
  "data": [{"id": 1201, "service": "data", "name": "1GB Monthly", "network": "MTN", "price": 450}],
  "meta": null,
  "errors": null
}
GET /api/v2/wallet200 SUCCESS
{
  "success": true,
  "message": "Wallet fetched successfully.",
  "data": {"currency": "NGN", "available_balance": 12500.50},
  "meta": null,
  "errors": null
}
POST /api/v2/validate-customer200 SUCCESS
{
  "success": true,
  "message": "Customer validated successfully.",
  "data": {
    "validation_reference": "VAL-EXAMPLE",
    "customer_name": "Test Customer",
    "address": "Ibadan",
    "expires_at": "2026-08-04T14:10:00+01:00"
  },
  "meta": null,
  "errors": null
}
POST /api/v2/buy-service200 SUCCESS
{
  "success": true,
  "message": "Transaction processed successfully.",
  "data": {
    "reference": "ORDER-10004",
    "status": "successful",
    "service": "electricity",
    "customer_number": "01234567890",
    "amount": 5000,
    "token": "1234-5678-9012"
  },
  "meta": null,
  "errors": null
}
GET /api/v2/transactions/{reference}200 SUCCESS
{
  "success": true,
  "message": "Transaction fetched successfully.",
  "data": {"reference": "ORDER-10001", "status": "successful", "service": "data", "customer_number": "08030000000", "amount": 450},
  "meta": null,
  "errors": null
}

Failure responses

Invalid or missing API token401 FAILED
{
  "success": false,
  "message": "Authentication failed. Provide a valid Bearer API token.",
  "data": null,
  "meta": null,
  "errors": {"authentication": ["The supplied API token is invalid."]}
}
Invalid request information422 FAILED
{
  "success": false,
  "message": "Please check the provided information.",
  "data": null,
  "meta": null,
  "errors": {"customer_number": ["Provide a valid Nigerian mobile number."]}
}
Expired bill validation422 FAILED
{
  "success": false,
  "message": "The validation reference is invalid, expired or does not match this purchase.",
  "data": null,
  "meta": null,
  "errors": {"validation_reference": ["Validate the customer again before purchasing."]}
}
Reference already used for different details409 CONFLICT
{
  "success": false,
  "message": "This reference has already been used for a different transaction.",
  "data": null,
  "meta": null,
  "errors": {"reference": ["Use a new unique reference."]}
}
Transaction reference not found404 NOT FOUND
{
  "success": false,
  "message": "Transaction not found.",
  "data": null,
  "meta": null,
  "errors": {"reference": ["No transaction matches this reference."]}
}

Safe retries and references

Create a unique reference for every customer order. If a connection times out, query the transaction endpoint before retrying.

Submitting the same reference with the same purchase details returns the existing transaction. Reusing it with different details returns 409 Conflict.

Public statuses are pending, processing, successful, failed and reversed.