# 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"
```

✓ Checkpoint: the response holds a `data` array, and each meter shows its `id` and the account it belongs to.

## 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"
}
```

✓ Checkpoint: the HTTP status is `201`, the `id` starts with `ppm_` and `status` is `active`. Every prepaid operation from here on takes this enrollment `id`, not the meter's own `id`. Enrolling the same meter again returns `409`.

## 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"
}
```

✓ Checkpoint: `litres` is above zero, and `net_cents`, `sanitation_cents`, `tax_cents` and `remainder_cents` add up to the amount you sent. An amount too small to buy any water returns `400`.

## 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"
}
```

✓ Checkpoint: the HTTP status is `201`, `status` is `issued` and `token` holds the code the customer keys into the meter. Check `token_is_dev_stub` before you show it: a test token does nothing on a real meter. The `remainder_cents` stays in the wallet and counts towards the next purchase.

## 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
```

✓ Checkpoint: `receipt.pdf` is a PDF file. `layout` takes `a4` (the default) or `mobile`; a vend in `pending_payment` or `failed` has no receipt and returns `404`.

## 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

- [Receive payments through any connector](/docs/guides/receive-payments)
- [Build the resident app, with mobile money purchases](/docs/guides/resident-app)
- [Listen for events with webhooks](/docs/guides/listen-webhooks)
- [Retry requests safely](/docs/getting-started/idempotency)
- [Every prepaid operation in the Business API reference](/docs/api/business)

