Prepaid

Base URL: $CONSUMER_API

The object

idstring · required
tenant_idstring · required
meter_idstring · required
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · optional
statusstring · required

one of active, suspended

vending_key_refstring · optional
balance_centsinteger · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC",
  "status": "active",
  "vending_key_ref": "vending key ref",
  "balance_cents": 125000,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List the consumer's prepaid meters

Logs

GET /prepaid/meters

Pages the prepaid meters on accounts where the caller has the payment permission, across tenants unless X-Tenant-ID selects one. An empty page is returned when the caller has no such account. Pagination uses limit and after.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Prepaid meters linked to the consumer's authorized accounts

Show attributes
dataarray of PrepaidMeter · required
Show child attributes
idstring · required
tenant_idstring · required
meter_idstring · required
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · optional
statusstring · required

one of active, suspended

vending_key_refstring · optional
balance_centsinteger · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · optional
next_cursorstring · optional
total_countinteger · optional

Errors 401 · 403

curl -X GET "$CONSUMER_API/prepaid/meters" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_holder_name": "Ana Matsinhe",
      "meter_serial": "meter serial",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC",
      "status": "active",
      "vending_key_ref": "vending key ref",
      "balance_cents": 125000,
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

List the consumer's purchases

Logs

GET /prepaid/vends

Pages the prepaid purchases (vends) on accounts where the caller has the payment permission, with their status and issued tokens. An empty page is returned when the caller has no such account. Pagination uses limit and after.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Prepaid purchases linked to the consumer's authorized accounts

Show attributes
dataarray of PrepaidVend · required
Show child attributes
idstring · required
tenant_idstring · required
prepaid_meter_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

statusstring · required

one of pending_payment, issued, failed

amount_centsinteger · required
net_centsinteger · optional
sanitation_centsinteger · optional
tax_centsinteger · optional
remainder_centsinteger · optional
litresinteger · optional
currencystring · optional
tariff_idstring · optional
tokenstring · optional
token_providerstring · optional
token_is_dev_stubboolean · required
payment_session_idstring · optional
payment_idstring · optional
methodstring · optional
phonestring · optional
idempotency_keystring · required
receipt_numberstring · optional
created_bystring · optional
failure_reasonstring · optional
issued_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · optional
next_cursorstring · optional
total_countinteger · optional

Errors 401 · 403

curl -X GET "$CONSUMER_API/prepaid/vends" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "pre_2x1uSLlwWbxIwLhQCpjuwX3YGNn",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "prepaid_meter_id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "status": "pending_payment",
      "amount_cents": 125000,
      "net_cents": 1,
      "sanitation_cents": 1,
      "tax_cents": 1,
      "remainder_cents": 1,
      "litres": 1,
      "currency": "MZN",
      "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC",
      "token": "token",
      "token_provider": "token provider",
      "token_is_dev_stub": true,
      "payment_session_id": "pay_2DxUipfYyfRuqNn2cZf00RTYqB3",
      "payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
      "method": "method",
      "phone": "+258841234567",
      "idempotency_key": "idempotency key",
      "receipt_number": "REC-2026-000142",
      "created_by": "created by",
      "failure_reason": "failure reason",
      "issued_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Buy prepaid water by mobile money

Logs

POST /prepaid/purchases

Buy prepaid water by mobile money; the token is issued after settlement

Starts a prepaid purchase (vend) for a meter on one of the caller's accounts: the vend is created pending payment and a payment session is started for amount_cents, and the token is issued once the payment is confirmed. amount_cents and idempotency_key are required, and repeating a key returns the existing vend. Returns 404 for a meter outside the caller's scope, 409 when the meter is not active, and 503 when token generation or the payment provider is unavailable.

Body application/json

prepaid_meter_idstring · required
amount_centsinteger · required
phonestring · optional
methodstring · optional
idempotency_keystring · required

Returns

201 Purchase started; payment settlement and token issuance may still be pending

Show attributes
idstring · required
tenant_idstring · required
prepaid_meter_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

statusstring · required

one of pending_payment, issued, failed

amount_centsinteger · required
net_centsinteger · optional
sanitation_centsinteger · optional
tax_centsinteger · optional
remainder_centsinteger · optional
litresinteger · optional
currencystring · optional
tariff_idstring · optional
tokenstring · optional
token_providerstring · optional
token_is_dev_stubboolean · required
payment_session_idstring · optional
payment_idstring · optional
methodstring · optional
phonestring · optional
idempotency_keystring · required
receipt_numberstring · optional
created_bystring · optional
failure_reasonstring · optional
issued_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409 · 503

curl -X POST "$CONSUMER_API/prepaid/purchases" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "prepaid_meter_id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
  "amount_cents": 125000,
  "phone": "+258841234567",
  "method": "method",
  "idempotency_key": "idempotency key"
}'
Response 201
{
  "id": "pre_2x1uSLlwWbxIwLhQCpjuwX3YGNn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "prepaid_meter_id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "status": "pending_payment",
  "amount_cents": 125000,
  "net_cents": 1,
  "sanitation_cents": 1,
  "tax_cents": 1,
  "remainder_cents": 1,
  "litres": 1,
  "currency": "MZN",
  "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC",
  "token": "token",
  "token_provider": "token provider",
  "token_is_dev_stub": true,
  "payment_session_id": "pay_2DxUipfYyfRuqNn2cZf00RTYqB3",
  "payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
  "method": "method",
  "phone": "+258841234567",
  "idempotency_key": "idempotency key",
  "receipt_number": "REC-2026-000142",
  "created_by": "created by",
  "failure_reason": "failure reason",
  "issued_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a purchase, reconciling it if payment has settled

Logs

GET /prepaid/vends/{id}

Returns one prepaid purchase on an account in the caller's scope, including the token once issued. When the vend is still pending payment, the call first checks its payment session and settles the vend if a confirmation was missed, so polling this call moves a paid vend forward. Vends outside the caller's scope return 404.

Parameters

idstring · path · required

Identifier of the prepaid vend to return.

Returns

200 Purchase linked to the consumer's authorized accounts

Show attributes
idstring · required
tenant_idstring · required
prepaid_meter_idstring · required
meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

statusstring · required

one of pending_payment, issued, failed

amount_centsinteger · required
net_centsinteger · optional
sanitation_centsinteger · optional
tax_centsinteger · optional
remainder_centsinteger · optional
litresinteger · optional
currencystring · optional
tariff_idstring · optional
tokenstring · optional
token_providerstring · optional
token_is_dev_stubboolean · required
payment_session_idstring · optional
payment_idstring · optional
methodstring · optional
phonestring · optional
idempotency_keystring · required
receipt_numberstring · optional
created_bystring · optional
failure_reasonstring · optional
issued_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 401 · 403 · 404

curl -X GET "$CONSUMER_API/prepaid/vends/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "pre_2x1uSLlwWbxIwLhQCpjuwX3YGNn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "prepaid_meter_id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "status": "pending_payment",
  "amount_cents": 125000,
  "net_cents": 1,
  "sanitation_cents": 1,
  "tax_cents": 1,
  "remainder_cents": 1,
  "litres": 1,
  "currency": "MZN",
  "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC",
  "token": "token",
  "token_provider": "token provider",
  "token_is_dev_stub": true,
  "payment_session_id": "pay_2DxUipfYyfRuqNn2cZf00RTYqB3",
  "payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
  "method": "method",
  "phone": "+258841234567",
  "idempotency_key": "idempotency key",
  "receipt_number": "REC-2026-000142",
  "created_by": "created by",
  "failure_reason": "failure reason",
  "issued_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Download the purchase receipt PDF

Logs

GET /prepaid/vends/{id}/receipt.pdf

Renders the PDF receipt of a prepaid purchase on an account in the caller's scope. A receipt exists only after the token has been issued; a vend in any other status returns 404. The locale (pt-MZ or en-US) and layout=mobile query parameters control language and page size.

Parameters

idstring · path · required

Identifier of the issued prepaid vend whose receipt is rendered.

layoutstring · query · optional · default a4

Page format. mobile is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.

one of a4, mobile

Returns

200 Purchase receipt PDF

Errors 401 · 403 · 404

curl -X GET "$CONSUMER_API/prepaid/vends/{id}/receipt.pdf" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Purchase receipt PDF