⚡ Vending (Venshack)

Purchase prepaid electricity tokens for meters registered to your Venshack organization. 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": {
    "success": true,
    "meterNumber": "1234567890123",
    "customerName": "John Doe",
    "customerAddress": "123 Main Street, Lagos",
    "meterType": "SINGLE_PHASE",
    "message": "Meter validated successfully"
  }
}

Step 2: Purchase Token

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)
  "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,
    "customerName": "John Doe",
    "externalRef": "my-order-123",
    "message": "Token purchase successful"
  }
}

Request Fields

Code Example

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

async function purchaseElectricity(meterNumber, amountInKobo) {
  // 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: amountInKobo,
      externalRef: `order-${Date.now()}`
    })
  });
  
  const result = await purchaseRes.json();
  
  if (result.success) {
    console.log(`Token: ${result.data.token}`);
    console.log(`Units: ${result.data.units} kWh`);
    return result.data;
  } else {
    throw new Error(result.error.message);
  }
}

// Usage - 50000 kobo = ₦500
purchaseElectricity('1234567890123', 50000);

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 how to receive and verify webhook events.

Error Handling