> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dancity.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Electricity

> Validate a meter number and vend electricity tokens

## Overview

Electricity purchases follow a two-step flow:

1. **Validate** the meter number to confirm it's active and retrieve the customer name
2. **Buy** units (prepaid token) or pay a postpaid bill

Supported DISCOs include IKEDC, EKEDC, AEDC, PHEDC, and others.

## Authentication

Both endpoints require your merchant API key **and** the `channel: API` header.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API
```

***

## Step 1 — Validate meter

```
POST /api/v1/electricity/validate
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `meterNumber` | string | ✓ | Customer's meter number |
| `billerCode` | string | ✓ | From [Get products](https://docs.dancity.app/api-reference/catalog/get-api-products.md) (e.g. `"EKEDC"`) or display name (e.g. `"Eko Electricity"`) |
| `amount` | number | ✓ | Intended vend amount in NGN (for pricing context) |
| `meterType` | string | ✓ | `"prepaid"` or `"postpaid"` |

```bash cURL theme={null}
curl -sS -X POST "https://api.dancity.app/api/v1/electricity/validate" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "meterNumber": "45012345678",
    "billerCode": "EKEDC",
    "amount": 2000,
    "meterType": "prepaid"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/electricity/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
    channel: "API",
  },
  body: JSON.stringify({
    meterNumber: "45012345678",
    billerCode: "EKEDC",
    amount: 2000,
    meterType: "prepaid",
  }),
});
const { data } = await res.json();
console.log(data.customerName); // display to user
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/electricity/validate",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={
        "meterNumber": "45012345678",
        "billerCode": "EKEDC",
        "amount": 2000,
        "meterType": "prepaid",
    },
)
customer_name = res.json()["data"]["customerName"]
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "Validation successful",
  "data": {
    "customerName": "Jane Doe"
  }
}
```

> [!NOTE]
>
> Always show `customerName` to the user before proceeding to purchase — it confirms the meter number is correct.

***

## Step 2 — Buy electricity token

```
POST /api/v1/electricity/buy
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `meterNumber` | string | ✓ | Same number used in validation |
| `billerCode` | string | ✓ | From [Get products](https://docs.dancity.app/api-reference/catalog/get-api-products.md) (e.g. `"EKEDC"`) |
| `meterType` | string | ✓ | `"prepaid"` or `"postpaid"` |
| `amount` | number | ✓ | Vend amount in NGN (minimum ₦500) |
| `customerName` | string | ✓ | Name returned from validation |
| `address` | string | ✓ | Customer's address |
| `customerRef` | string | | Your internal reference ID |
| `saveAsBeneficiary` | boolean | | Save meter as beneficiary |
| `promocode` | string | | Discount promo code |

```bash cURL theme={null}
curl -sS -X POST "https://api.dancity.app/api/v1/electricity/buy" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "meterNumber": "45012345678",
    "billerCode": "EKEDC",
    "meterType": "prepaid",
    "amount": 2000,
    "customerName": "Jane Doe",
    "address": "12 Lekki Phase 1, Lagos",
    "customerRef": "ELEC-REF-001"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/electricity/buy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
    channel: "API",
  },
  body: JSON.stringify({
    meterNumber: "45012345678",
    billerCode: "EKEDC",
    meterType: "prepaid",
    amount: 2000,
    customerName: "Jane Doe",
    address: "12 Lekki Phase 1, Lagos",
    customerRef: "ELEC-REF-001",
  }),
});
const data = await res.json();
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/electricity/buy",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={
        "meterNumber": "45012345678",
        "billerCode": "EKEDC",
        "meterType": "prepaid",
        "amount": 2000,
        "customerName": "Jane Doe",
        "address": "12 Lekki Phase 1, Lagos",
        "customerRef": "ELEC-REF-001",
    },
)
print(res.json())
```

### Sample response (prepaid)

```json theme={null}
{
  "success": true,
  "message": "Electricity purchase processed",
  "data": {
    "transactionId": "TXN-2025-XXXXX",
    "token": "1234-5678-9012-3456-7890",
    "amount": 2000,
    "meterNumber": "45012345678"
  }
}
```

> [!TIP]
>
> For prepaid meters, the `token` field in the response is the recharge token to give the customer. Store it with the transaction record.

***

## Full purchase flow

```
1. Collect meterNumber, meterType, billerCode from user

2. POST /api/v1/electricity/validate  { meterNumber, billerCode, amount, meterType }
   → confirm customerName

3. Show customerName to user → user confirms

4. POST /api/v1/electricity/buy
   → send meterNumber, billerCode, meterType, amount, customerName, address
```

> [!WARNING]
>
> The minimum vend amount is **₦500**. Requests below this threshold return a `400` validation error.

## Next steps

* [Transactions: verify purchase status](https://docs.dancity.app/guides/transactions.md)
* [Webhooks: receive token delivery confirmation](https://docs.dancity.app/guides/webhook.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.