> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bleeprs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Purchase Electricity
> Purchase electricity token for a meter
## Overview
Purchase an electricity token for a validated meter. The token will be generated instantly and can be used to recharge the meter.
## Request Body
Validated meter number.
Electricity provider `productCode` from the electricity catalog.
Meter type, such as `PREPAID` or `POSTPAID`.
Electricity amount in Naira.
Customer phone number for the transaction.
## Response Fields
Reference to store for reconciliation, support, and requerying pending transactions.
Electricity token for successful prepaid purchases.
Units returned for successful electricity purchases, when available.
Receipt number returned for successful purchases, when available.
Commission earned on the purchase, in Naira.
## Status Codes
| Code | Meaning |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` | Purchase completed successfully. Token details are returned in `data`. |
| `202` | Purchase accepted but not yet confirmed. Wait at least 2 minutes, then call [Requery Transaction](/api-reference/endpoint/requeryvendingtransaction) to confirm the final status. |
| `400` | The request could not be processed. Common causes: invalid payload, insufficient balance, or the purchase was declined by the provider. If the wallet was debited, it is automatically refunded. |
| `429` | Another purchase for the same meter and amount is already in progress. Retry after a short delay or with a different amount. |
## Notes
* Validate the meter before purchase and let the customer confirm the returned details.
* Use the minimum and maximum amount returned by the electricity catalog.
* The `vendType` must match the customer's meter type.
* If the API returns `gatewayStatus: "01"` or an accepted pending response, wait at least 2 minutes before calling [Requery Transaction](/api-reference/endpoint/requeryvendingtransaction).
* Successful prepaid purchases include token details in the response data.
## OpenAPI
````yaml POST /purchaseElectricity
openapi: 3.0.3
info:
title: Bleeprs API Specification 0.1
version: 1.0.0
contact: {}
servers:
- url: https://api.bleeprs.com/api
security:
- bearerAuth: []
paths:
/purchaseElectricity:
post:
tags:
- Vending
summary: Purchase Electricity
description: >-
Purchase electricity for a validated meter. Successful prepaid purchases
return token details.
operationId: purchaseElectricity
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: number
description: Amount of electricity to purchase (in Naira)
example: 1500
meter:
type: string
description: The validated electricity meter number
example: '12345678910'
phone:
type: string
description: Customer phone number for the transaction
example: '08000000000'
disco:
type: string
description: >-
Electricity provider productCode returned by the
ElectricityList endpoint
example: IKEJA_ELECTRIC
vendType:
type: string
description: Meter type
enum:
- PREPAID
- POSTPAID
example: PREPAID
required:
- amount
- meter
- phone
- disco
- vendType
responses:
'200':
description: Successfully Processed
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '00'
gatewayMessage:
type: string
example: Successfully Processed
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: object
properties:
token:
type: string
example: 1234 5678 9101 1121 3141
units:
type: number
example: 24.5
receiptNo:
type: string
example: RCPT123456789
commission:
type: number
example: 25
'202':
description: Transaction Pending
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '01'
gatewayMessage:
type: string
example: Transaction Pending
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: object
nullable: true
description: >-
No additional data is returned while the transaction is
pending.
'400':
description: >-
The request could not be processed. Common causes: invalid payload,
insufficient balance, or the purchase was declined by the provider.
If the wallet was debited, it is automatically refunded.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '88'
gatewayMessage:
type: string
example: Unsucessfull
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: string
example: No active NGN vending account found
'429':
description: >-
Another purchase for the same meter and amount is already in
progress. Retry after a short delay or with a different amount.
content:
application/json:
schema:
type: object
properties:
gatewayStatus:
type: string
example: '88'
gatewayMessage:
type: string
example: Unsucessfull
requestReference:
type: string
example: bpr_req_a1b2c3d4e5f6
data:
type: string
example: >-
Transaction in progress for this meter and amount. Please
wait.
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````