⚡ Disco Electricity Vending

Purchase prepaid tokens or pay postpaid bills for any supported distribution company meter. Disco vending is its own API collection — no Venshack meter registration is required, and it is separate from Vending (Venshack).

Supported DISCOs

Common utility aliases such as IKEDC, EKEDC, AEDC and PHEDC are accepted and normalized to their canonical codes.

Pricing

How It Works

1. Validate meter → Confirm the meter and get the customer name
2. Confirm with user → Show the customer name before purchase
3. Purchase → Charge your wallet and receive the token, or a pending reference
4. Requery → If the transaction is pending, requery the reference until it resolves

Step 1: Validate Meter

Always validate first to confirm the meter and show the customer name.

{
  "meterNumber": "1234567890123",
  "disco": "IKEJA",
  "meterCategory": "PREPAID"
}

{
  "success": true,
  "data": {
    "success": true,
    "meterNumber": "1234567890123",
    "customerName": "John Doe",
    "meterType": "PREPAID",
    "disco": "IKEJA",
    "meterCategory": "PREPAID",
    "message": "Meter validated successfully"
  }
}

Step 2: Purchase Token / Pay Bill

Purchase electricity for the validated meter. Costs ₦50 for amounts under ₦10,000, 0.5% above.

{
  "meterNumber": "1234567890123",
  "amount": 50000,  // Amount in kobo (50000 = ₦500)
  "disco": "IKEJA",
  "meterCategory": "PREPAID",
  "phone": "08012345678",  // Optional but recommended
  "externalRef": "my-order-123"  // Optional - your reference
}

{
  "success": true,
  "data": {
    "success": true,
    "token": "1234-5678-9012-3456-7890",
    "units": 25.5,
    "meterNumber": "1234567890123",
    "amount": 50000,
    "reference": "202603231430abc123",
    "customerName": "John Doe",
    "disco": "IKEJA",
    "meterCategory": "PREPAID",
    "message": "Token purchased successfully"
  }
}

{
  "success": true,
  "data": {
    "success": false,
    "meterNumber": "1234567890123",
    "amount": 50000,
    "reference": "202603231430abc123",
    "errorCode": "PENDING",
    "disco": "IKEJA",
    "meterCategory": "PREPAID",
    "message": "Transaction is being processed. Use the reference to requery for the final status."
  }
}

Step 3: Requery a Pending Transaction

Pass the reference from the original purchase. Requery is free and safe to call repeatedly.

{
  "reference": "202603231430abc123"
}

The response uses the same shape as a purchase: a delivered transaction returns the token, while a still-processing one returns errorCode: "PENDING" again.

Postpaid Meters

Set meterCategory to POSTPAID to pay a postpaid bill. There is no token for postpaid payments; a successful response returns the payment reference and message: "Payment completed successfully".

Request Fields

Sandbox Test Cases

TEST API keys (vk_test_) return deterministic sandbox values and never call a live electricity provider.

Amounts below 50000 kobo (₦500) fail with MIN_AMOUNT in sandbox. Requery resolves any sandbox PENDING reference successfully. Sandbox requests are free but still appear in your API call logs; webhooks are not sent for TEST calls.

Code Example

const API_KEY = 'vk_prod_xxxxxxxxxxxxx';
const BASE_URL = 'https://api-developers.venshack.io/v1';

async function purchaseDiscoElectricity({
  meterNumber,
  amountInKobo,
  disco,          // e.g. 'IKEJA'
  meterCategory,  // 'PREPAID' | 'POSTPAID'
  phone
}) {
  // Step 1: Validate meter
  const validateRes = await fetch(`${BASE_URL}/disco-vending/validate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ meterNumber, disco, meterCategory })
  });

  const meter = await validateRes.json();

  if (!meter.success) {
    throw new Error(meter.error.message);
  }

  console.log(`Customer: ${meter.data.customerName}`);

  // Step 2: Purchase
  const purchaseRes = await fetch(`${BASE_URL}/disco-vending/purchase`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meterNumber,
      amount: amountInKobo,
      disco,
      meterCategory,
      ...(phone ? { phone } : {}),
      externalRef: `order-${Date.now()}`
    })
  });

  let result = await purchaseRes.json();

  // Step 3: Pending transactions are resolved by requery
  if (result.data?.errorCode === 'PENDING') {
    const reference = result.data.reference;

    for (let attempt = 0; attempt < 3; attempt++) {
      await new Promise((resolve) => setTimeout(resolve, 2000));

      const requeryRes = await fetch(`${BASE_URL}/disco-vending/requery`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ reference })
      });

      result = await requeryRes.json();
      if (result.data?.errorCode !== 'PENDING') break;
    }
  }

  if (result.data?.success) {
    console.log(`Token: ${result.data.token}`);
    console.log(`Units: ${result.data.units} kWh`);
    return result.data;
  }

  throw new Error(result.data?.message || result.error?.message);
}

// 50000 kobo = ₦500
purchaseDiscoElectricity({
  meterNumber: '1234567890123',
  amountInKobo: 50000,
  disco: 'IKEJA',
  meterCategory: 'PREPAID',
  phone: '08012345678'
});

Transaction History

List DISCO vending transactions for your organization. Transactions include disco, meterCategory and reference fields.

GET /v1/disco-vending/transactions?page=1&limit=20&meterNumber=1234567890123

Query Token

{
  "token": "12345678901234567890"
}

Webhooks

DISCO vending emits the same vending.completed and vending.failed events as Venshack vending, with meterType: "DISCO" plus disco and meterCategory in the payload. Pending transactions do not emit vending.failed; they emit vending.completed once requery confirms delivery. See the Webhooks Guide for how to receive and verify webhook events.

Error Handling