⚡ Electricity Vending

Purchase prepaid electricity tokens for any meter in Nigeria. Validate meters, purchase tokens, and track transactions.

Pricing

How It Works

1. Validate meter → Get customer name and meter details
2. Confirm with user → Show customer name before purchase
3. Purchase token → Charge your wallet, get token
4. Deliver token → Display to customer or send via notification

Step 1: Validate Meter

Always validate first to get customer details and confirm the meter exists.

{
  "meterNumber": "1234567890123"
}

{
  "success": true,
  "data": {
    "meterNumber": "1234567890123",
    "customerName": "John Doe",
    "customerAddress": "123 Main Street, Lagos",
    "meterType": "PREPAID",
    "disco": "IKEDC",
    "minimumAmount": 500,
    "maximumAmount": 500000
  }
}

Step 2: Purchase Token

Purchase electricity for the validated meter. Costs 0.5% of amount (minimum ₦5).

{
  "meterNumber": "1234567890123",
  "amount": 5000,
  "estateId": "est_abc123",
  "reference": "my-unique-ref-123"  // Optional idempotency key
}

{
  "success": true,
  "data": {
    "id": "txn_xyz789",
    "meterNumber": "1234567890123",
    "amount": 5000,
    "units": "25.5 kWh",
    "token": "1234-5678-9012-3456-7890",
    "customerName": "John Doe",
    "status": "SUCCESS",
    "reference": "VEN-20260323-ABC123",
    "createdAt": "2026-03-23T10:30:00Z"
  }
}

Request Fields

Code Example

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

async function purchaseElectricity(meterNumber, amount, estateId) {
  // Step 1: Validate meter
  const validateRes = await fetch(`${BASE_URL}/vending/validate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ meterNumber })
  });
  
  const meter = await validateRes.json();
  
  if (!meter.success) {
    throw new Error(meter.error.message);
  }
  
  console.log(`Customer: ${meter.data.customerName}`);
  
  // Step 2: Purchase token
  const purchaseRes = await fetch(`${BASE_URL}/vending/purchase`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meterNumber,
      amount,
      estateId,
      reference: `order-${Date.now()}`
    })
  });
  
  const result = await purchaseRes.json();
  
  if (result.success) {
    console.log(`Token: ${result.data.token}`);
    console.log(`Units: ${result.data.units}`);
    return result.data;
  } else {
    throw new Error(result.error.message);
  }
}

// Usage
purchaseElectricity('1234567890123', 5000, 'est_abc123');

Transaction History

List all vending transactions for your organization.

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

Webhooks

Receive notifications when vending events happen:

See Webhooks Guide for setup instructions.

Error Handling