Electricity Bill Payment API Token Vending

Endpoint

Send a POST request with the purchase details in the request body.

Production URL

https://pairgate.com/api/v1/electricity/purchase

Method POST

Test Endpoint

https://pairgate.com/api/v1/test/electricity/purchase

Authentication

This request requires a valid Bearer token.

Header	Value	Description
`Authorization`	`Bearer {token}`	Your unique API authorization token
`Content-Type`	`application/json`	Required for POST requests

Body Parameters

Required parameters marked below. Send them as JSON in the request body.

Parameter	Type	Required	Description
`provider_id`	string	Yes	Provider slug (e.g. `ikedc`, `eko`)
`amount`	float	Yes	Amount to purchase in Naira (minimum ₦1,000)
`meter_number`	string	Yes	Meter number (1–20 digits)
`meter_type`	integer	Yes	Meter type: `1` for prepaid, `2` for postpaid
`recipient_name`	string	No	Name to associate with the purchase (defaults to "Unknown Customer")
`reference`	string	Yes	Your unique reference for this transaction (8–100 characters)

Meter Types

Value	Description
`1`	Prepaid
`2`	Postpaid

Code Examples

Choose your preferred language below. Replace the parameters and YOUR_API_KEY with your actual values.

PHP (Laravel)

// Purchase Electricity
$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_API_KEY',
    'Content-Type' => 'application/json',
])->post('https://pairgate.com/api/v1/electricity/purchase', [
    'provider_id' => 'ikedc',
    'amount' => 5000,
    'meter_number' => '1234567890',
    'meter_type' => 1,
    'recipient_name' => 'John Doe',
    'reference' => 'my-electricity-order-001',
]);

$result = $response->json();

dd($result);

cURL

curl -X POST "https://pairgate.com/api/v1/electricity/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "ikedc",
    "amount": 5000,
    "meter_number": "1234567890",
    "meter_type": 1,
    "recipient_name": "John Doe",
    "reference": "my-electricity-order-001"
  }'

Node.js

const axios = require('axios');

const purchaseElectricity = async () => {
    try {
        const response = await axios.post(
            'https://pairgate.com/api/v1/electricity/purchase',
            {
                provider_id: 'ikedc',
                amount: 5000,
                meter_number: '1234567890',
                meter_type: 1,
                recipient_name: 'John Doe',
                reference: 'my-electricity-order-001'
            },
            {
                headers: {
                    'Authorization': 'Bearer YOUR_API_KEY',
                    'Content-Type': 'application/json'
                }
            }
        );
        
        console.log(response.data);
    } catch (error) {
        console.error(error.response?.data || error.message);
    }
};

purchaseElectricity();

Python

import requests
import json

url = "https://pairgate.com/api/v1/electricity/purchase"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "provider_id": "ikedc",
    "amount": 5000,
    "meter_number": "1234567890",
    "meter_type": 1,
    "recipient_name": "John Doe",
    "reference": "my-electricity-order-001"
}

try:
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String jsonBody = "{"
    + "\"provider_id\": \"ikedc\","
    + "\"amount\": 5000,"
    + "\"meter_number\": \"1234567890\","
    + "\"meter_type\": 1,"
    + "\"recipient_name\": \"John Doe\","
    + "\"reference\": \"my-electricity-order-001\""
    + "}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://pairgate.com/api/v1/electricity/purchase"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

try {
    HttpResponse response = client.send(request, 
        HttpResponse.BodyHandlers.ofString());
    
    System.out.println(response.body());
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
}

Example Request Body

{
  "provider_id": "ikedc",
  "amount": 5000,
  "meter_number": "1234567890",
  "meter_type": 1,
  "recipient_name": "John Doe",
  "reference": "my-electricity-order-001"
}

Response Format

Success Response (200)

Purchase accepted, token being generated:

{
  "code": 200,
  "status": "success",
  "data": {
    "status": true,
    "message": "Electricity purchase successful & processing.",
    "reference_code": "TRXEE20260615104818CQ3",
    "balance_before": 20000.00,
    "balance_after": 15000.00,
    "amount": 5000.00,
    "item": "Ikeja Electricity - IKEDC (PHCN)",
    "meter_number": "1234567890"
  }
}

Test Response (200)

{
  "code": 200,
  "status": "success",
  "data": {
    "test_mode": true,
    "message": "This is a test — no balance deducted.",
    "request": {
      "provider_id": "ikedc",
      "amount": 5000,
      "meter_number": "1234567890",
      "meter_type": 1,
      "recipient_name": "John Doe",
      "reference": "my-electricity-order-001"
    },
    "would_deduct": 5000.00,
    "balance": 20000.00
  }
}

Success Response Fields

Field	Type	Description
`status`	boolean	`true` if successful
`message`	string	Status description
`reference_code`	string	Your transaction reference for status checks
`balance_before`	float	Wallet balance before debit
`balance_after`	float	Wallet balance after debit
`amount`	float	Amount charged
`item`	string	Disco name
`meter_number`	string	Meter number

Webhook — Token Delivered

When the electricity token is generated, a webhook is sent to your configured URL. Ensure your webhook endpoint is set up to receive these POST notifications.

Webhook Payload

{
  "event": "electricity.purchase",
  "reference_code": "TRXEE20260615104818CQ3",
  "status": "successful",
  "message": "Electricity purchase completed.",
  "item": "Ikeja Electricity - IKEDC (PHCN)",
  "recipient": "1234567890",
  "amount": 5000.00,
  "pin": "1234-5678-9012-3456-7890",
  "completed_at": "2026-06-15T10:05:00+01:00"
}

Webhook Fields

Field	Type	Description
`event`	string	Purchase event type
`reference_code`	string	Your transaction reference
`status`	string	`successful` when the token is ready
`message`	string	Status description
`item`	string	Disco name
`recipient`	string	Meter number
`amount`	float	Amount charged
`pin`	string	The electricity token
`completed_at`	string	Timestamp when the token was generated

Error Responses

The following errors may occur when calling this endpoint.

Status	Code	Description
422	`Invalid provider`	Provider not found or inactive
422	`Minimum amount`	Amount is below ₦1,000
422	`Insufficient balance`	Wallet balance is too low
422	`Duplicate reference`	This reference has already been used
401	`Missing API key`	No Bearer token provided
401	`Invalid API key`	Token does not match any active key
403	`Suspended`	API key or account has been suspended
429	`Rate limited`	Too many requests

Electricity Purchase

Quick Summary