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 (operation listMeters), business:prepaid:manage (enrollPrepaidMeter), business:prepaid:read (quotePrepaidVend, getPrepaidVend, getPrepaidVendReceipt) and business: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 with token_is_dev_stub set to true. Where no generator is installed, the vend returns 503 before 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.

bash
curl -sS "$BUSINESS_API/meters?limit=5" \
  -H "Authorization: Bearer $API_KEY"

2. Enroll the meter as prepaid#

bash
curl -sS -X POST "$BUSINESS_API/prepaid/meters" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"meter_id":"mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA"}'
json
{
  "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.

bash
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}'
json
{
  "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.

bash
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"}'
json
{
  "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#

bash
curl -sS "$BUSINESS_API/prepaid/vends/vnd_2pM6sW1zKc8YqB4nDf7tXh3rLuG/receipt.pdf?layout=mobile" \
  -H "Authorization: Bearer $API_KEY" -o receipt.pdf

Errors to handle#

  • 409 with code CONFLICT: the meter is suspended. POST $BUSINESS_API/prepaid/meters/{id}/status with {"status":"active"} resumes it.
  • 503 with code INTEGRATION_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 failed and failure_reason says which step broke; read it with GET $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:

bash
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.

Next steps#