Purchase Utility Bill

Pays a utility bill (e.g. electricity) for a previously verified meter. On success, data.token / data.unit carry the prepaid token, if applicable.

Body (JSON):

The meter number comes from the verification. On SUCCESS, data.token is the prepaid token and data.unit the units (kWh) as returned by the provider (may be absent/null for postpaid). The duplicate response for this endpoint returns the full stored transaction record (different shape from the other purchase endpoints).

Purchase outcomes (shared flow):

• 200 data.status: "SUCCESS" — delivered.
• 200 data.status: "PENDING" with message ... purchase is being confirmed. Do not retry; check the transaction status. — provider outcome unknown; you have been debited and not refunded. Poll Fetch Single VTU Transaction; do not resend.
• 400 ... purchase failed. Your balance has been refunded. — provider definitively rejected; safe to retry with a new idempotencyKey.
• 409 Duplicate request in flight — another request with the same idempotencyKey is being processed.
• 200 Duplicate request — returning existing transaction — the idempotencyKey was already used; the original transaction is returned and nothing is charged.

Your settlement balance must be strictly greater than the amount (balance <= amount is rejected as insufficient).

Error format: body validation failures (Joi) return { "status": "error", "message": "Validation error", "details": [ ... ] }; all other errors return { "success": false, "message": "..." }. Money fields (amount, fee) are Prisma Decimals and are serialized as strings (e.g. "1000").