# Vend electricity

> Buy electricity for a meter, prepaid or postpaid.

Source: https://useroutegate.com/docs/api/public/vendElectricity

`POST /api/v1/bills/electricity`

Send `network` (the disco), `meter_number` and `amount_kobo`, at least ₦1,000 (`100000`). The product follows `meter_type`, `prepaid` when it is left out, or name it with `product_code`. [Verify the meter](/docs/api/public/verifyBill) first to show the customer's name before they pay. When the vend succeeds, the provider's token, units and receipt number are added to `metadata`.

Authenticate with a bearer API key: `rg_test_` in test mode, `rg_live_` in live.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | yes | Created once per order and resent unchanged on every retry of it. See [idempotency](/docs/concepts/idempotency). At most 128 characters. |
| `wait` | query | integer | no | Long-poll up to this many seconds for a final state; capped by the server. The answer is still `202`, so read `status`. The server stops waiting in time to answer before the request's own deadline, whatever you ask for. |

## Body

| Field | Type | Description |
| --- | --- | --- |
| `network` | string | Disco code such as ikedc, ekedc, aedc. |
| `biller` | string | Alias for network. |
| `product_code` | string | Optional product code (e.g. IKEDC-PREPAID) |
| `meter_number` | string | Electricity meter number. |
| `account_number` | string | Alias for meter_number. |
| `destination` | string | Alias for meter_number. |
| `phone_number` | string | Customer phone number to receive token. |
| `meter_type` | string | Prepaid or postpaid. One of `prepaid`, `postpaid`. |
| `amount_kobo` | integer | Amount in kobo. At least 100000. |
| `amount` | integer | Alias for amount_kobo. At least 100000. |
| `client_reference` | string | At most 128 characters. |
| `metadata` | object | Up to 20 string values of your own, returned on the transaction and its webhooks. `route`, `plan_name`, `product_id`, `delivered_mb`, `requested_mb` and `partial` are Routegate's and are replaced. |

A field that is not in this table is refused with `400 VALIDATION_FAILED`.

## Request

```bash
curl -X POST https://api.useroutegate.com/api/v1/bills/electricity \
  -H "Authorization: Bearer $ROUTEGATE_API_KEY" \
  -H "Idempotency-Key: ord-00044" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "ikedc",
    "product_code": "IKEDC-PREPAID",
    "meter_type": "prepaid",
    "meter_number": "45031234567",
    "amount_kobo": 500000,
    "phone_number": "+2348012345678",
    "client_reference": "ord-00044"
  }'
```

## Response

`202`

```json
{
  "success": true,
  "code": "OK",
  "message": "Transaction accepted",
  "data": {
    "id": "01a0d8df-a6b8-7c3e-9f21-4b6d8e0a2c57",
    "reference": "txn_01a0d8dfa6b87d10a3e54c2b9f86d1e4",
    "client_reference": "ord-00044",
    "mode": "test",
    "status": "queued",
    "product_code": "IKEDC-PREPAID",
    "network": "ikedc",
    "service": "electricity",
    "destination": "450******67",
    "amount_kobo": 500000,
    "price_kobo": 500000,
    "metadata": {
      "meter_number": "45031234567",
      "meter_type": "prepaid",
      "phone_number": "+2348012345678",
      "plan_name": "Ikeja Electric Prepaid",
      "product_id": "00000000-0000-7000-8000-000000001101",
      "route": "provider"
    },
    "created_at": "2026-09-25T14:02:11Z"
  }
}
```

`status` is `queued` in this answer. It moves through `processing`, and `pending` when a channel has not confirmed, to `successful` or `failed`; `reversed` and `refunded` are in the enum but nothing sets them. The outcome arrives as a [webhook](/docs/concepts/webhooks) naming this `reference`.

## Error

`402` `WALLET_INSUFFICIENT_FUNDS`: The wallet's available balance does not cover the price. Nothing was created: fund the wallet, then send the order with a new `Idempotency-Key`. Every code is in [errors](/docs/concepts/errors).

```json
{
  "success": false,
  "data": null,
  "message": "Insufficient wallet balance: available balance (0.00 NGN) is less than required amount (5000.00 NGN)",
  "code": "WALLET_INSUFFICIENT_FUNDS"
}
```

## Give this to your coding agent

Read `https://useroutegate.com/docs/api/public/vendElectricity.md` and implement this call. Create the `Idempotency-Key` once per order and resend the same key and the same body on every retry of it. Treat `202` as accepted, with `status` `queued`, and take the final state from the webhook. Amounts are integers in kobo.