Prepaid and postpaid electricity: design the right API flow
Handle prepaid tokens and postpaid account payments correctly, validate meter type during checkout and give customers a receipt that matches the purchase.
Already registered? Open API settings and follow the business-access steps. Sandbox purchases do not deliver real services.
Reviewed
An electricity receipt needs to answer a different question for each customer. A prepaid customer needs the recharge token when it is available. A postpaid customer needs confirmation of the account payment. A shared screen that always says 'Your token is ready' creates confusion for postpaid payments and unresolved prepaid orders.
Carry meter type through the whole order
Select the correct electricity product, collect the meter number and verify the intended meter type. Keep identifiers as strings and use the type confirmed for that target. A product can have no fixed meter type in its catalogue record, so the absence of that attribute is not permission to assume prepaid.
Store the confirmed target and meter type with the order. Use them again when building the purchase request and rendering its receipt. Do not derive the type later from the presence or absence of a token: the token might be delayed, missing from the channel you checked, or inappropriate for that order.
| Order | Pending receipt | Completed receipt |
|---|---|---|
| Prepaid | Payment is processing; preserve the order reference | Purchase status plus the issued token when received |
| Postpaid | Payment is processing; preserve the order reference | Payment confirmation for the verified account |
| Uncertain meter type | Ask the customer to correct or confirm the target | Do not submit a purchase until the target is established |
Give tokens a separate delivery state
Keep financial status and token delivery status separately in your own application. A successful prepaid transaction whose token has not reached your receipt should go into token recovery, not trigger another electricity purchase.
The current integration guidance uses data.object.token from the signed completion webhook for prepaid delivery. Do not assume the production REST transaction response supplies a token. The token recovery guide explains what to retain and what to investigate when delivery is missing.
Only show a token to the authorized customer for that order. Keep it out of public analytics, search URLs and shared screenshots. Reopening a receipt should read the existing order and token record without submitting another payment.
Test both customer journeys
In the sandbox, the documented electricity fixtures distinguish successful prepaid and postpaid scenarios. They simulate outcomes; they do not establish what a real meter accepts. For pending-failure tests, let the configured transition run: the sandbox query action currently forces a pending transaction to successful.
Check that the postpaid receipt never asks for a recharge token, that a pending prepaid receipt never fabricates one, and that a late webhook updates the original order once. Also check an edited meter type between verification and submission. That mismatch should be caught by your checkout before a biller receives the purchase.