PT EN

Pré-pago

URL base: $CONSUMER_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

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.

Parâmetros

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 linked to the consumer's authorized accounts

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

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

Listar compras de água pré-paga

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Prepaid purchases linked to the consumer's authorized accounts

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

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

Comprar água pré-paga

Registos

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.

Corpo application/json

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

Devolve

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

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

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"
}'
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 compra de água pré-paga

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Identifier of the prepaid vend to return.

Devolve

200 Purchase linked to the consumer's authorized accounts

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

curl -X GET "$CONSUMER_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 compra

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Identifier of the issued prepaid 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 Purchase receipt PDF

Erros 401 · 403 · 404

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

Purchase receipt PDF