API reference

Purchase electricity

Purchase electricity. Request fields, response examples and integration guidance.

POST /purchases/electricity

Example request

Server-side HTTP request

curl --request POST \
  --url "https://api.strongmb.ng/v1/purchases/electricity" \
  --header "Authorization: Bearer $STRONGMB_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
  "meter_number": "0123456789",
  "meter_type": "prepaid",
  "product_code": "smb_ked_pre",
  "amount": 2400,
  "reference": "SMB202609160001",
  "phone": "0123456789",
  "email": "[email protected]",
  "verify_token": "Ri8zQkZNaHpXcCsyckJDUzBPSUZkUXVFTWxJbk9VRFY2aDlqTWdUZjFyST0="
}'

// Server-side Node.js 22+; never expose your key in a browser.
async function main() {
  const response = await fetch("https://api.strongmb.ng/v1/purchases/electricity", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STRONGMB_API_KEY}`,
      Accept: "application/json",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
  "meter_number": "0123456789",
  "meter_type": "prepaid",
  "product_code": "smb_ked_pre",
  "amount": 2400,
  "reference": "SMB202609160001",
  "phone": "0123456789",
  "email": "[email protected]",
  "verify_token": "Ri8zQkZNaHpXcCsyckJDUzBPSUZkUXVFTWxJbk9VRFY2aDlqTWdUZjFyST0="
}),
    signal: AbortSignal.timeout(30000)
  });
  const result = await response.json();
  console.log(response.status, result);
  // For purchases, inspect data.status before showing a receipt.
}
main().catch(console.error);

<?php
// Requires the PHP cURL extension.
$client = curl_init('https://api.strongmb.ng/v1/purchases/electricity');
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('STRONGMB_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "meter_number": "0123456789",
  "meter_type": "prepaid",
  "product_code": "smb_ked_pre",
  "amount": 2400,
  "reference": "SMB202609160001",
  "phone": "0123456789",
  "email": "[email protected]",
  "verify_token": "Ri8zQkZNaHpXcCsyckJDUzBPSUZkUXVFTWxJbk9VRFY2aDlqTWdUZjFyST0="
}',
]);
$raw = curl_exec($client);
if ($raw === false) {
    throw new RuntimeException(curl_error($client));
}
$status = curl_getinfo($client, CURLINFO_HTTP_CODE);
curl_close($client);
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
print_r(['http_status' => $status, 'response' => $result]);
// For purchases, inspect data.status before showing a receipt.

require 'net/http'
require 'json'

uri = URI('https://api.strongmb.ng/v1/purchases/electricity')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
http.open_timeout = 10
http.read_timeout = 30
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer ' + ENV.fetch('STRONGMB_API_KEY')
request['Accept'] = 'application/json'
request['Content-Type'] = 'application/json'
request.body = '{
  "meter_number": "0123456789",
  "meter_type": "prepaid",
  "product_code": "smb_ked_pre",
  "amount": 2400,
  "reference": "SMB202609160001",
  "phone": "0123456789",
  "email": "[email protected]",
  "verify_token": "Ri8zQkZNaHpXcCsyckJDUzBPSUZkUXVFTWxJbk9VRFY2aDlqTWdUZjFyST0="
}'
begin
  response = http.request(request)
  result = JSON.parse(response.body)
  puts({ http_status: response.code, response: result }.to_json)
rescue StandardError => error
  warn error.message
end
# Reconcile an uncertain purchase before retrying.

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError

headers = {
    "Authorization": "Bearer " + os.environ["STRONGMB_API_KEY"],
    "Accept": "application/json",
    "Content-Type": "application/json",
}
payload = {'meter_number': '0123456789',
 'meter_type': 'prepaid',
 'product_code': 'smb_ked_pre',
 'amount': 2400,
 'reference': 'SMB202609160001',
 'phone': '0123456789',
 'email': '[email protected]',
 'verify_token': 'Ri8zQkZNaHpXcCsyckJDUzBPSUZkUXVFTWxJbk9VRFY2aDlqTWdUZjFyST0='}
body = json.dumps(payload).encode("utf-8")
request = Request(
    "https://api.strongmb.ng/v1/purchases/electricity",
    data=body, headers=headers, method="POST"
)
try:
    with urlopen(request, timeout=30) as response:
        result = json.load(response)
        print(response.status, result)
except HTTPError as error:
    print(error.code, error.read().decode("utf-8"))
except URLError as error:
    print("Network error:", error.reason)
# Reconcile an uncertain purchase before retrying.

Purchases a prepaid token or pays a postpaid bill. Requires a valid verify_token from the meter validation step.

Request Body

Field	Type	Required	Description
meter_number	string	Required	The customer's meter number
meter_type	string	Required	`prepaid` or `postpaid`
product_code	string	Required	Product code from `/products/electricity`
amount	number	Required	Amount in Naira to purchase. Must be at or above the plan's `min_amount`
reference	string	Required	Your unique transaction reference. a-zA-Z0-9 only, 10–255 characters
verify_token	string	Required	The token returned from `/customer-validation/electricity`
phone	string	Optional	Customer phone number for purchase notifications, including prepaid token details.
email	string	Optional	Customer email address for purchase notifications, including prepaid token details.

Request Example

JSON Payload

{
  "meter_number": "0123456789",
  "meter_type": "prepaid",
  "product_code": "smb_ked_pre",
  "amount": 2400,
  "reference": "SMBD0113s53pafsslsdsdkdsdFdAdssdC9",
  "phone": "0123456789",
  "email": "[email protected]",
  "verify_token": "Ri8zQkZNaHpXcCsyckJDUzBPSUZkUXVFTWxJbk9VRFY2aDlqTWdUZjFyST0="
}

JSON — 201 Successful

{
  "status": true,
  "message": "Transaction completed successfully.",
  "data": {
    "status": "successful",
    "type": "electricity",
    "meter_type": "prepaid",
    "provider": "kedco",
    "title": "₦2,400 Subscription",
    "recipient": "0123456789",
    "recipient_name": null,
    "fee": "0.00",
    "reference": "SMBD0113s53pafsslsdsdkdsdFdAdssdC9",
    "date": "2026-08-08 01:11:26",
    "currency": "NGN",
    "balance_before": "683772.55",
    "balance_after": "681372.55",
    "amount": "2400.00",
    "amount_subscribe": "2400.00"
  },
  "metadata": { "code": "TRANSACTION_SUCCESSFUL", "timestamp": 1786147888, "trace_id": "AA28782686" }
}

JSON — 200 Processing

{
  "status": true,
  "message": "Electricity subscription is being processed.",
  "data": {
    "status": "processing",
    "type": "electricity",
    "meter_type": "prepaid",
    "provider": "kedco",
    "title": "₦2,400 Subscription",
    "recipient": "0123456789",
    "recipient_name": null,
    "fee": "0.00",
    "reference": "SMBD0113s53pafsslsdsddsdFdAdssdC9",
    "date": "2026-08-09 23:50:06",
    "currency": "NGN",
    "balance_before": "645688.55",
    "balance_after": "643288.55",
    "amount": "2400.00",
    "amount_subscribe": "2400.00"
  },
  "metadata": { "code": "ERR_TRANSACTION_PROCESSING", "timestamp": 1786315811, "trace_id": "70019BFD79" }
}

JSON — 200 Failed (refunded)

{
  "status": false,
  "message": "Your transaction has failed, amount has been refunded to your wallet.",
  "data": {
    "status": "failed",
    "type": "electricity",
    "meter_type": "prepaid",
    "provider": "kedco",
    "title": "₦2,400 Subscription",
    "recipient": "0123456789",
    "fee": "0.00",
    "reference": "SMBD0113s53pafssdsddkjsd9",
    "date": "2026-08-09 23:51:02",
    "currency": "NGN",
    "amount_subscribe": "2400.00"
  },
  "metadata": { "code": "ERR_TRANSACTION_FAILED", "timestamp": 1786315867, "trace_id": "EB97885F82" }
}

JSON — 409 Duplicate Reference

{
  "status": false,
  "message": "Reference already exist. Please use a unique reference.",
  "data": null,
  "metadata": { "code": "ERR_REFERENCE_ALREADY_EXISTS", "timestamp": 1786315900, "trace_id": "3C1D2E4F5A" }
}

JSON — 402 Insufficient Balance

{
  "status": false,
  "message": "Insufficient wallet balance.",
  "data": null,
  "metadata": { "code": "ERR_INSUFFICIENT_BALANCE", "timestamp": 1786315920, "trace_id": "4D2E3F5A6B" }
}

Response Codes

Code	HTTP	Meaning
TRANSACTION_SUCCESSFUL	201	Purchase complete. For prepaid, query the transaction by reference to retrieve the token and units. For postpaid, no token is required.
ERR_TRANSACTION_PROCESSING	200	Transaction submitted, pending provider confirmation. Poll by `reference`.
ERR_TRANSACTION_FAILED	200	Transaction attempted but failed. Amount automatically refunded to wallet.
ERR_REFERENCE_ALREADY_EXISTS	400	This reference is already used. Each transaction must have a unique reference.
ERR_INSUFFICIENT_BALANCE	402	Wallet balance is too low. Fund your wallet and retry.

The verify_token is single-use and expires. Always verify the meter immediately before purchasing — do not cache and reuse tokens across separate purchase attempts.

Understand the request fields

Field	Integration guidance
`meter_number`	The electricity meter identifier. Use the same value for validation and purchase.
`meter_type`	Use prepaid or postpaid as supported by the selected product and customer meter.
`product_code`	An exact identifier from the matching product list, not a provider name or an identifier from a different API.
`amount`	Amount in Nigerian naira, not kobo. Check the current product price and minimum before submitting.
`reference`	Your saved identifier for this intended purchase. Use 10–255 letters or digits. Duplicate references are rejected.
`verify_token`	The opaque customer-validation token. Send it unchanged for the same customer. Validate again if the customer number changes.

Handle the purchase result

Show a receipt only for a successful outcome. Keep processing transactions pending. Reconcile failed or timed-out purchases before another attempt.

Transaction lifecycle · Troubleshoot errors

Response fields and types

Expand an object to explore its fields. [] indicates an array item. Error responses may return data: null.

Field path	JSON type	Meaning and handling
`status`	boolean	Request-level success flag. Check the HTTP status and metadata code as well; a successful API request is not by itself proof of purchase fulfillment.
`message`	string	Human-readable description of the result. Use metadata.code for programmatic error handling instead of parsing this text.
`data`	null \| object	Response data. Check the result before reading nested fields; an error may return null or validation details.
`data.status`	string	Purchase outcome: successful, processing or failed. Use this field rather than the top-level status flag to decide whether a purchase completed.
`data.type`	string	Service or transaction type, for example data, airtime, electricity or cable TV.
`data.meter_type`	string	Meter category used for electricity validation or purchase, such as prepaid or postpaid.
`data.provider`	string	Provider identifier associated with the purchased service.
`data.title`	string	Short display title for the transaction receipt.
`data.recipient`	string	Phone number, meter or customer identifier for the purchase. Compare it with the intended recipient.
`data.recipient_name`	null \| string	Customer name when available. A null value means the response does not provide a name.
`data.fee`	string	Additional fee reported for the purchase.
`data.reference`	string	Reference supplied when creating the purchase. Save it and use the same value for transaction verification.
`data.date`	string	Transaction date/time string returned for display.
`data.currency`	string	Currency code, such as NGN for Nigerian naira.
`data.balance_before`	string	Wallet balance before this transaction, as reported by the API.
`data.balance_after`	string	Wallet balance after this transaction, as reported by the API.
`data.amount`	string	Amount debited from your wallet for this purchase, in the indicated currency.
`data.amount_subscribe`	string	Electricity subscription amount reported in the response; read it together with the final debited amount and any fee.
`metadata`	object	Diagnostic information about the response.
`metadata.code`	string	Machine-readable result code. Use it to distinguish validation, authentication and service errors.
`metadata.timestamp`	integer	Unix timestamp in seconds associated with the response.
`metadata.trace_id`	string	Correlation identifier for troubleshooting. Retain it with a redacted request when contacting support.

Always check metadata.code; do not rely on HTTP status alone. See response codes and recommended handling.

Test your integration Use the sandbox test values and examples.

Questions? Let’s work through them.

Having an issue or need help with your integration? Join the Strongmb Slack community to ask questions and get assistance from our team and other developers.

Keep API keys and customer details private when sharing examples.

Experiencing a service issue? Check Strongmb’s service status for incident updates.

Join our Slack community