Purchases

All purchase requests use POST /purchase with the appropriate payload. Every request must include a unique reference.

How to Generate a Reference

The reference is a unique string that you generate for each transaction. It identifies the transaction and can be used later to query its status viaGET /status.

⚠️

Reference Format Rules

Must be 12 characters or more.
The first 12 characters must be numeric.
The first 12 characters must be today's date and time in YYYYMMDDHHII format.
Date and time must be in Africa/Lagos (GMT+1) timezone.
Anything after the 12th character is optional and can be any alphanumeric string (e.g. a random suffix).
The reference must not have been used before.

Structure

YYYYMMDDHHII + [optional alphanumeric suffix]

Example: 202610051530HUt83ycveu

  YYYYMMDD   = 20261005  →  today's date (Africa/Lagos)
  HHII       = 1530      →  current hour and minute
  suffix     = HUt83ycveu  →  optional random string for uniqueness

More Examples

202610051530
202610051530ad8ef08acd8fc0f
2026100515304738492849
202610051530HUt83ycveu

How to Generate a Valid Reference

In your application code, build the reference like this:

// JavaScript / Node.js
function generateReference() {
  // Get current time in Lagos (GMT+1)
  const now = new Date();
  const lagos = new Date(now.getTime() + (60 * 60 * 1000)); // UTC+1

  const pad = (n) => String(n).padStart(2, '0');

  const YYYY = lagos.getUTCFullYear();
  const MM   = pad(lagos.getUTCMonth() + 1);
  const DD   = pad(lagos.getUTCDate());
  const HH   = pad(lagos.getUTCHours());
  const II   = pad(lagos.getUTCMinutes());

  // Optional random suffix for extra uniqueness
  const suffix = Math.random().toString(36).substring(2, 12);

  return `${YYYY}${MM}${DD}${HH}${II}${suffix}`;
}

// Example output: "202610051530hut83ycveu"

<?php
// PHP
function generateReference(): string
{
    $date = now('Africa/Lagos')->format('YmdHi');
    $suffix = bin2hex(random_bytes(5)); // 10 random hex chars
    return $date . $suffix;
}

// Example output: "2026100515308f3c9a1d7b"

# Python
import datetime, secrets

def generate_reference():
    # Africa/Lagos is UTC+1
    lagos = datetime.datetime.utcnow() + datetime.timedelta(hours=1)
    date_part = lagos.strftime("%Y%m%d%H%M")  # YYYYMMDDHHII
    suffix = secrets.token_hex(5)             # 10 random hex chars
    return date_part + suffix

# Example output: "2026100515308f3c9a1d7b"

Common Validation Errors

Reference	Why it fails
`abc123`	Less than 12 characters
`20261005`	Less than 12 characters
`20261005abcd`	First 12 characters are not numeric
`202610041530XYZ`	Date is not today (Africa/Lagos)
`202610052560XYZ`	Hour 25 / minute 60 is invalid

Buy Data

{
  "service_type": "data",
  "provider_code": "mtn",
  "package_code": "mtn-50mb-200",
  "recipient": "08011111111",
  "reference": "202610051530HUt83ycveu"
}

curl -X POST "https://app.wisesub.com.ng/api/partner/v1/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{\n  "service_type": "data",\n  "provider_code": "mtn",\n  "package_code": "mtn-50mb-200",\n  "recipient": "08011111111",\n  "reference": "202610051530HUt83ycveu"\n}'

{
  "success": true,
  "message": "Purchase successful",
  "data": {
    "reference": "202610051530HUt83ycveu",
    "amount": 197.00,
    "recipient": "08011111111",
    "service_type": "data",
    "package": "N200 200MB - 2 days",
    "commission": 3.00
  }
}

Buy Airtime

{
  "service_type": "airtime",
  "provider_code": "mtn",
  "recipient": "08011111111",
  "amount": 100.00,
  "reference": "202610051531ad8ef08acd8fc0f"
}

curl -X POST "https://app.wisesub.com.ng/api/partner/v1/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{\n  "service_type": "airtime",\n  "provider_code": "mtn",\n  "recipient": "08011111111",\n  "amount": 100.00,\n  "reference": "202610051531ad8ef08acd8fc0f"\n}'

{
  "success": true,
  "message": "Purchase successful",
  "data": {
    "reference": "202610051531ad8ef08acd8fc0f",
    "amount": 98.50,
    "recipient": "08011111111",
    "service_type": "airtime",
    "package": "₦100 Airtime",
    "commission": 1.50
  }
}

Buy Electricity

{
  "service_type": "electricity",
  "provider_code": "ikeja",
  "meter_number": "1111111111111",
  "meter_type": "prepaid",
  "amount": 1000,
  "phone": "08012345678",
  "reference": "2026100515324738492849"
}

curl -X POST "https://app.wisesub.com.ng/api/partner/v1/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{\n  "service_type": "electricity",\n  "provider_code": "ikeja",\n  "meter_number": "1111111111111",\n  "meter_type": "prepaid",\n  "amount": 1000,\n  "phone": "08012345678",\n  "reference": "2026100515324738492849"\n}'

{
  "success": true,
  "message": "Purchase successful",
  "data": {
    "reference": "2026100515324738492849",
    "amount": 995.00,
    "recipient": "1111111111111",
    "service_type": "electricity",
    "package": "Electricity Payment",
    "token": "26362054405982757802",
    "units": "79.9 kWh",
    "customer_name": "N/A",
    "commission": 5.00
  }
}

Buy Cable TV

{
  "service_type": "cabletv",
  "provider_code": "dstv",
  "package_code": "dstv-padi",
  "decoder_number": "1212121212",
  "phone": "08012345678",
  "subscription_type": "renewal",
  "reference": "202610051533Xy7bNk29pl"
}

curl -X POST "https://app.wisesub.com.ng/api/partner/v1/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{\n  "service_type": "cabletv",\n  "provider_code": "dstv",\n  "package_code": "dstv-padi",\n  "decoder_number": "1212121212",\n  "phone": "08012345678",\n  "subscription_type": "renewal",\n  "reference": "202610051533Xy7bNk29pl"\n}'

{
  "success": true,
  "message": "Purchase successful",
  "data": {
    "reference": "202610051533Xy7bNk29pl",
    "amount": 1836.13,
    "recipient": "1212121212",
    "service_type": "cabletv",
    "package": "DStv Padi N1,850",
    "commission": 13.87
  }
}

Buy WAEC Result Checker PIN

Purchase PINs to check WAEC results. Use provider_code: "result-checker". The optional quantity field allows buying multiple PINs at once.

{
  "service_type": "education",
  "provider_code": "result-checker",
  "package_code": "waecdirect",
  "recipient": "08011111111",
  "quantity": 2,
  "reference": "202610051534Kp92mNq7rT"
}

curl -X POST "https://app.wisesub.com.ng/api/partner/v1/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{\n  "service_type": "education",\n  "provider_code": "result-checker",\n  "package_code": "waecdirect",\n  "recipient": "08011111111",\n  "quantity": 2,\n  "reference": "202610051534Kp92mNq7rT"\n}'

{
  "success": true,
  "message": "Purchase successful",
  "data": {
    "reference": "202610051534Kp92mNq7rT",
    "amount": 1500.00,
    "recipient": "08011111111",
    "service_type": "education",
    "package": "WASSCE",
    "cards": [
      {
        "Serial": "WRN123456790",
        "Pin": "098765432112"
      },
      {
        "Serial": "WRN123456791",
        "Pin": "098765432113"
      }
    ],
    "commission": 300.00
  }
}

Buy WAEC Registration PIN

Purchase registration PINs for WAEC examinations. Useprovider_code: "registration".

{
  "service_type": "education",
  "provider_code": "registration",
  "package_code": "waec-registraion",
  "recipient": "08011111111",
  "quantity": 1,
  "reference": "202610051535Bv48sLx2wZ"
}

curl -X POST "https://app.wisesub.com.ng/api/partner/v1/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{\n  "service_type": "education",\n  "provider_code": "registration",\n  "package_code": "waec-registraion",\n  "recipient": "08011111111",\n  "quantity": 1,\n  "reference": "202610051535Bv48sLx2wZ"\n}'

{
  "success": true,
  "message": "Purchase successful",
  "data": {
    "reference": "202610051535Bv48sLx2wZ",
    "amount": 14360.00,
    "recipient": "08011111111",
    "service_type": "education",
    "package": "WASSCE for Private Candidates - Second Series (2019)",
    "tokens": ["0100070365657400875"],
    "purchased_code": "Token: 0100070365657400875",
    "commission": 90.00
  }
}

💡

Test Numbers:
- Data/Airtime recipient: 08011111111
- Electricity prepaid meter: 1111111111111
- Electricity postpaid meter: 1010101010101
- DSTV decoder: 1212121212
- WAEC packages are available in the sandbox; use any valid package code from /packages.
- Commission: The commission field shows your earnings on that transaction.