Skip to main content

PurchaseResponse

referencestring

The Plustive transaction reference. Store this.

Example: PLS-9KQ2M7P3XR
statusstring

Processing settles asynchronously - poll Get a transaction or wait for a webhook.

Possible values: [Success, Failed, Processing]

providerReferencestringnullable

Upstream provider reference, when available.

priceChargedinteger<int64>

Amount debited from your wallet, in kobo.

Example: 27000
balanceinteger<int64>

Your wallet balance after this purchase, in kobo.

Example: 4973000
tokenstringnullable

Provider-delivered token/PIN for services that vend one (electricity prepaid token, education PIN). Null for data, airtime and cable TV.

idempotentReplayboolean

true when this purchase reused a clientReference that already had a transaction: the original transaction is returned unchanged - no new vend and no extra charge. A replay also carries the Idempotent-Replay: true response header. false (or absent) for a fresh purchase.

Default value: false
deliveredDetails objectnullable

What the upstream disco or biller reported it delivered, beyond the token: the meter/account holder's name and address, the units credited, and the utility's own receipt number. These are the fields a customer expects on a power receipt.

Every field is optional, and the whole object is null when nothing was reported: every data and airtime purchase, any purchase still Processing, and any biller that does not report them. Reported today for prepaid electricity.

customerNamestringnullable

The meter or account holder's name, exactly as the disco holds it.

Example: Muraina Tamilola .
customerAddressstringnullable

The service address the disco holds for this meter.

Example: NO 9, ROAD 19 BASHORUN HOUSING ESTATE AKOBO ESTATE IBADAN OYO,
unitsnumbernullable

Units credited by this vend (kWh for electricity). Fractional.

Example: 2.3
utilityReceiptstringnullable

The utility's own receipt number for this vend, for disputes raised directly with the disco.

Example: 110-0000079801709
failureReasonstringnullable

On a Failed purchase, the human-readable reason it failed - e.g. an electricity vend refused because the amount was below the meter's declared minimum (the message names that minimum, matching the minimumPurchase this meter returns from /electricity/verify). Null on non-failed statuses and when no reason was recorded; show your own generic copy then.

Example: This meter requires a minimum purchase of NGN22,521.25, but NGN10,000.00 was requested.
PurchaseResponse
{
  "reference": "PLS-9KQ2M7P3XR",
  "status": "Success",
  "providerReference": "string",
  "priceCharged": 27000,
  "balance": 4973000,
  "token": "string",
  "idempotentReplay": false,
  "deliveredDetails": {
    "customerName": "Muraina Tamilola .",
    "customerAddress": "NO 9, ROAD 19 BASHORUN HOUSING ESTATE AKOBO ESTATE IBADAN OYO,",
    "units": 2.3,
    "utilityReceipt": "110-0000079801709"
  },
  "failureReason": "This meter requires a minimum purchase of NGN22,521.25, but NGN10,000.00 was requested."
}