Prepaid

Base URL: $BUSINESS_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 prepaid meters

Logs

GET /prepaid/meters

Returns one cursor-paginated page (limit, after) of the tenant's meters enrolled for prepaid vending, with each one's linked account, tariff, status and wallet balance. Requires the business:prepaid:read permission.

Parameters

statusstring · query · optional

Optional enrollment status filter: active or suspended.

one of active, suspended

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 in the authenticated utility tenant

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

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_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
}

Flag a meter as prepaid

Logs

POST /prepaid/meters

Enrolls an existing meter for prepaid vending and returns the enrollment with status active and 201. The body needs meter_id and accepts an optional tariff_id and vending_key_ref. The meter must exist and be linked to an account (400 otherwise), and a meter that is already prepaid returns 409. Requires the business:prepaid:manage permission and records an audit entry.

Body application/json

meter_idstring · required
tariff_idstring · optional
vending_key_refstring · optional

Returns

201 Meter enrolled as prepaid

Show 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

Errors 400 · 401 · 403 · 404 · 409

Permissions business:prepaid:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/prepaid/meters" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC",
  "vending_key_ref": "vending key ref"
}'
Response 201
{
  "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"
}

Get a prepaid meter with its wallet balance

Logs

GET /prepaid/meters/{id}

Returns one prepaid enrollment with its meter serial, account, customer, tariff, status and current wallet balance. Requires the business:prepaid:read permission, and returns 404 when the enrollment does not exist.

Parameters

idstring · path · required

ID of the prepaid meter enrollment (prefixed ppm_), not the underlying meter ID.

Returns

200 Prepaid meter in the authenticated utility tenant

Show 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

Errors 401 · 403 · 404

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/prepaid/meters/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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"
}

Suspend or resume a prepaid meter

Logs

POST /prepaid/meters/{id}/status

Sets the enrollment status to the status in the body and returns the updated enrollment. Only active and suspended are accepted (400 otherwise), and a suspended meter cannot be vended to. Requires the business:prepaid:manage permission.

Parameters

idstring · path · required

ID of the prepaid meter enrollment to update.

Body application/json

statusstring · required

one of active, suspended

Returns

200 Updated prepaid meter

Show 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

Errors 400 · 401 · 403 · 404 · 409

Permissions business:prepaid:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/prepaid/meters/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Response 200
{
  "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 wallet ledger entries

Logs

GET /prepaid/meters/{id}/wallet

Returns one cursor-paginated page (limit, after) of the credit and debit movements in a prepaid meter's wallet. Each vend posts a credit for the payment and a debit for the water bought, both referencing the vend ID. Requires the business:prepaid:read permission.

Parameters

idstring · path · required

ID of the prepaid meter enrollment whose wallet is listed.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Wallet entries for the prepaid meter

Show attributes
dataarray of PrepaidWalletEntry · required
Show child attributes
idstring · required
tenant_idstring · required
prepaid_meter_idstring · required
kindstring · required

one of credit, debit

amount_centsinteger · required
balance_after_centsinteger · required
referencestring · required
descriptionstring · optional
created_atstring (date-time) · required
has_moreboolean · optional
next_cursorstring · optional
total_countinteger · optional

Errors 401 · 403

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/prepaid/meters/{id}/wallet" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "pre_24ShbkKHdq8hdqoB3UOtLw493Kq",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "prepaid_meter_id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
      "kind": "credit",
      "amount_cents": 125000,
      "balance_after_cents": 125000,
      "reference": "REF-2026-000142",
      "description": "Leitura confirmada no local.",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Convert an amount to water volume with the tariff

Logs

POST /prepaid/meters/{id}/quote

Converts the amount_cents in the body into the largest whole number of litres it buys under the meter's tariff, without taking payment or issuing a token. The quote accounts for volume already vended this month, and a first purchase in the month includes the period's fixed charge. It returns the litres, the net, sanitation and tax split, and the remainder. A non-positive amount, or one too small to buy any water, returns 400. Requires the business:prepaid:read permission.

Parameters

idstring · path · required

ID of the prepaid meter enrollment to price the purchase for.

Body application/json

amount_centsinteger · required

Returns

200 Amount converted to water volume

Show attributes
litresinteger · required
net_centsinteger · required
sanitation_centsinteger · required
tax_centsinteger · required
remainder_centsinteger · required
currencystring · required
tariff_idstring · required

Errors 400 · 401 · 403 · 404

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X POST "$BUSINESS_API/prepaid/meters/{id}/quote" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 125000
}'
Response 200
{
  "litres": 1,
  "net_cents": 1,
  "sanitation_cents": 1,
  "tax_cents": 1,
  "remainder_cents": 1,
  "currency": "MZN",
  "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC"
}

List vending transactions

Logs

GET /prepaid/vends

Returns one cursor-paginated page (limit, after) of the tenant's prepaid vends, from counter sales and customer purchases, with each vend's amount, litres, token and status. Requires the business:prepaid:read permission.

Parameters

statusstring · query · optional

Optional vend status filter: pending_payment, issued or failed.

one of pending_payment, issued, failed

prepaid_meter_idstring · query · optional

Optional prepaid meter enrollment ID; only vends for that meter are returned.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Vends in the authenticated utility tenant

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

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_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
}

Vend at the counter

Logs

POST /prepaid/vends

Vend at the counter (token issued only by a configured generator)

Takes a counter payment and issues the token in one step, then returns the vend with 201. The body needs prepaid_meter_id, amount_cents and an idempotency_key, and method defaults to cash. Repeating a key returns the existing vend. The payment is recorded only after the token generator reports it is ready; then the wallet is credited and debited, the token is minted and the sale is posted to the ledger. A suspended meter returns 409, an unavailable token generator returns 503, and a failure after recording marks the vend failed. Requires the business:prepaid:vend permission.

Body application/json

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

Returns

201 Vend created

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

Permissions business:prepaid:vend · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/prepaid/vends" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "prepaid_meter_id": "pre_2RtGgr5UObHqSN9K4rD24l9KoHf",
  "amount_cents": 125000,
  "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 vend

Logs

GET /prepaid/vends/{id}

Returns one vend with its status, amount, litres, token (when issued), charge breakdown, payment ID, receipt number and failure reason (when failed). Requires the business:prepaid:read permission, and returns 404 when the vend does not exist.

Parameters

idstring · path · required

ID of the vend (prefixed vnd_).

Returns

200 Vend in the authenticated utility tenant

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

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_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 vend receipt PDF

Logs

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

Renders the vend's receipt as a PDF and returns it as an attachment. Receipts exist only for issued vends: a pending or failed vend, or a deployment without receipt rendering, returns 404. Requires the business:prepaid:read permission.

Parameters

idstring · path · required

ID of the issued 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 Vend receipt PDF

Errors 401 · 403 · 404

Permissions business:prepaid:read · Roles: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

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

Vend receipt PDF