PT EN

Pré-pago

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

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

meter_serialstring · opcional
account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · opcional
statusstring · obrigatório

um de active, suspended

vending_key_refstring · opcional
balance_centsinteger · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "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"
}

Listar contadores pré-pagos

Registos

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.

Parâmetros

statusstring · consulta · opcional

Optional enrollment status filter: active or suspended.

um de active, suspended

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Prepaid meters in the authenticated utility tenant

Mostrar atributos
dataarray of PrepaidMeter · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

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

meter_serialstring · opcional
account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · opcional
statusstring · obrigatório

um de active, suspended

vending_key_refstring · opcional
balance_centsinteger · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · opcional
next_cursorstring · opcional
total_countinteger · opcional

Erros 401 · 403

Permissões business:prepaid:read · Funções: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

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

Tornar um contador pré-pago

Registos

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.

Corpo application/json

meter_idstring · obrigatório
tariff_idstring · opcional
vending_key_refstring · opcional

Devolve

201 Meter enrolled as prepaid

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

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

meter_serialstring · opcional
account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · opcional
statusstring · obrigatório

um de active, suspended

vending_key_refstring · opcional
balance_centsinteger · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões business:prepaid:manage · Funções: 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"
}'
Resposta 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"
}

Obter um contador pré-pago

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Prepaid meter in the authenticated utility tenant

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

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

meter_serialstring · opcional
account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · opcional
statusstring · obrigatório

um de active, suspended

vending_key_refstring · opcional
balance_centsinteger · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 401 · 403 · 404

Permissões business:prepaid:read · Funções: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

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

Suspender ou retomar um contador pré-pago

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the prepaid meter enrollment to update.

Corpo application/json

statusstring · obrigatório

um de active, suspended

Devolve

200 Updated prepaid meter

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
meter_idstring · obrigatório
meter_holder_namestring · opcional

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

meter_serialstring · opcional
account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

tariff_idstring · opcional
statusstring · obrigatório

um de active, suspended

vending_key_refstring · opcional
balance_centsinteger · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões business:prepaid:manage · Funções: 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"
}'
Resposta 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"
}

Listar movimentos do saldo pré-pago

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the prepaid meter enrollment whose wallet is listed.

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Wallet entries for the prepaid meter

Mostrar atributos
dataarray of PrepaidWalletEntry · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
prepaid_meter_idstring · obrigatório
kindstring · obrigatório

um de credit, debit

amount_centsinteger · obrigatório
balance_after_centsinteger · obrigatório
referencestring · obrigatório
descriptionstring · opcional
created_atstring (date-time) · obrigatório
has_moreboolean · opcional
next_cursorstring · opcional
total_countinteger · opcional

Erros 401 · 403

Permissões business:prepaid:read · Funções: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

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

Calcular o volume para um valor

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

amount_centsinteger · obrigatório

Devolve

200 Amount converted to water volume

Mostrar atributos
litresinteger · obrigatório
net_centsinteger · obrigatório
sanitation_centsinteger · obrigatório
tax_centsinteger · obrigatório
remainder_centsinteger · obrigatório
currencystring · obrigatório
tariff_idstring · obrigatório

Erros 400 · 401 · 403 · 404

Permissões business:prepaid:read · Funções: 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
}'
Resposta 200
{
  "litres": 1,
  "net_cents": 1,
  "sanitation_cents": 1,
  "tax_cents": 1,
  "remainder_cents": 1,
  "currency": "MZN",
  "tariff_id": "tar_2gW5z8815MeLds61bycBrS8bPMC"
}

Listar vendas de água pré-paga

Registos

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.

Parâmetros

statusstring · consulta · opcional

Optional vend status filter: pending_payment, issued or failed.

um de pending_payment, issued, failed

prepaid_meter_idstring · consulta · opcional

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

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Vends in the authenticated utility tenant

Mostrar atributos
dataarray of PrepaidVend · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
prepaid_meter_idstring · obrigatório
meter_idstring · obrigatório
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

statusstring · obrigatório

um de pending_payment, issued, failed

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

Erros 401 · 403

Permissões business:prepaid:read · Funções: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/prepaid/vends" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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
}

Vender água pré-paga ao balcão

Registos

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.

Corpo application/json

prepaid_meter_idstring · obrigatório
amount_centsinteger · obrigatório
methodstring · opcional
idempotency_keystring · obrigatório

Devolve

201 Vend created

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
prepaid_meter_idstring · obrigatório
meter_idstring · obrigatório
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

statusstring · obrigatório

um de pending_payment, issued, failed

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

Erros 400 · 401 · 403 · 404 · 409 · 503

Permissões business:prepaid:vend · Funções: 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"
}'
Resposta 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"
}

Obter uma venda de água pré-paga

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the vend (prefixed vnd_).

Devolve

200 Vend in the authenticated utility tenant

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
prepaid_meter_idstring · obrigatório
meter_idstring · obrigatório
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

statusstring · obrigatório

um de pending_payment, issued, failed

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

Erros 401 · 403 · 404

Permissões business:prepaid:read · Funções: admin, analyst, billing_clerk, customer_service, finance, operations, owner, viewer

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

Descarregar o recibo de uma venda

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the issued vend whose receipt is rendered.

layoutstring · consulta · opcional · predefinição a4

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

um de a4, mobile

Devolve

200 Vend receipt PDF

Erros 401 · 403 · 404

Permissões business:prepaid:read · Funções: 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_..."
Resposta 200

Vend receipt PDF