Sell prepaid credit
Enroll a meter as prepaid, price an amount in litres and sell credit at the counter, with the STS token and the receipt number in one response.
What you will build#
A complete counter sale through the Business API. You pick a meter that is already linked to an account, enroll it for prepaid vending, ask for a quote to see how many litres the money buys, and record the sale. That one call records the payment, credits and debits the meter's wallet, mints the token and posts the sale to the ledger. Last, you download the PDF receipt to hand to the customer.
Purchases that residents make themselves with mobile money take a different route (POST $CONSUMER_API/prepaid/purchases): the vend starts in pending_payment and the token is issued only once the payment is confirmed. The resident app guide covers that flow.
Prerequisites#
- A sandbox and a test key with these scopes:
business:meters:read(operationlistMeters),business:prepaid:manage(enrollPrepaidMeter),business:prepaid:read(quotePrepaidVend,getPrepaidVend,getPrepaidVendReceipt) andbusiness:prepaid:vend(createPrepaidVend). - A meter linked to an account that has a tariff. A meter with no account is refused with
400. - A deployment that can mint STS tokens. In the development environment the server installs a test generator whose tokens start with
DEV-STUB-and come withtoken_is_dev_stubset totrue. Where no generator is installed, the vend returns503before any money is taken.
1. Find the meter#
List the utility's meters and note the id (it starts with mtr_) of one that carries an account_id.
curl -sS "$BUSINESS_API/meters?limit=5" \
-H "Authorization: Bearer $API_KEY"
2. Enroll the meter as prepaid#
curl -sS -X POST "$BUSINESS_API/prepaid/meters" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"meter_id":"mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA"}'
{
"id": "ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"meter_id": "mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA",
"meter_serial": "04112233445",
"account_id": "act_2nF7cJ4pVb9RtK2xLw6qHm3sZyE",
"account_number": "CTA-000044",
"customer_id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
"tariff_id": "trf_2mC9xL3kRb7NwT5vQp1hYd8gFsJ",
"status": "active",
"balance_cents": 0,
"created_at": "2026-11-19T09:12:04Z",
"updated_at": "2026-11-19T09:12:04Z"
}
3. Get a quote#
The quote turns the amount into the largest whole number of litres it buys under the meter's tariff. It counts the volume already sold this month, and the first purchase of the month includes the period's fixed charge. Nothing is charged and no token is minted.
curl -sS -X POST "$BUSINESS_API/prepaid/meters/ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD/quote" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount_cents":50000}'
{
"litres": 1850,
"net_cents": 39830,
"sanitation_cents": 3980,
"tax_cents": 6070,
"remainder_cents": 120,
"currency": "MZN",
"tariff_id": "trf_2mC9xL3kRb7NwT5vQp1hYd8gFsJ"
}
4. Sell at the counter#
The body needs prepaid_meter_id, amount_cents (1 to 100000000) and idempotency_key. method is optional and defaults to cash. Whatever the method, cash included, it must be one of the payment methods available to the utility, which GET $BUSINESS_API/payment-methods lists. Sending the same idempotency_key again returns the existing vend instead of charging twice.
curl -sS -X POST "$BUSINESS_API/prepaid/vends" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"prepaid_meter_id":"ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD","amount_cents":50000,"idempotency_key":"counter-0419-a7"}'
{
"id": "vnd_2pM6sW1zKc8YqB4nDf7tXh3rLuG",
"prepaid_meter_id": "ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD",
"meter_id": "mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA",
"account_id": "act_2nF7cJ4pVb9RtK2xLw6qHm3sZyE",
"status": "issued",
"amount_cents": 50000,
"net_cents": 39830,
"sanitation_cents": 3980,
"tax_cents": 6070,
"remainder_cents": 120,
"litres": 1850,
"currency": "MZN",
"token": "DEV-STUB-9F3A61C2-NAO-E-TOKEN-STS",
"token_provider": "dev-stub",
"token_is_dev_stub": true,
"payment_id": "pay_2pM6sX4bNd2ZrC8kEg5vYj7tMwH",
"method": "cash",
"idempotency_key": "counter-0419-a7",
"receipt_number": "RCP-000318",
"issued_at": "2026-11-19T09:14:37Z",
"created_at": "2026-11-19T09:14:36Z",
"updated_at": "2026-11-19T09:14:37Z"
}
5. Download the receipt#
curl -sS "$BUSINESS_API/prepaid/vends/vnd_2pM6sW1zKc8YqB4nDf7tXh3rLuG/receipt.pdf?layout=mobile" \
-H "Authorization: Bearer $API_KEY" -o receipt.pdf
Errors to handle#
409withcodeCONFLICT: the meter is suspended.POST $BUSINESS_API/prepaid/meters/{id}/statuswith{"status":"active"}resumes it.503withcodeINTEGRATION_UNAVAILABLE: no token generator is ready, and nothing was charged.- If the payment cannot be recorded (for example, a method the utility has not set up), or the token cannot be minted after it, the vend is marked
failedandfailure_reasonsays which step broke; read it withGET $BUSINESS_API/prepaid/vends/{id}.
Test it#
Open the sandbox dashboard at Prepaid. The sale shows up under Sales with its litres and the Token column, the meter shows up under Meters with its wallet balance, and the Receipt button in the sale detail downloads the same PDF. The payment the vend records fires a payment.received event. To watch it reach your local server:
gotactl webhooks listen --events payment.received --forward-to http://localhost:3000/hook
--events limits which event types are forwarded and --forward-to names the local URL that receives the POSTs. You can also check the sale from the CLI with gotactl api GET business:/prepaid/vends -f status=issued.