Developer documentation
Integrate billing, payments, readings, webhooks and the CLI with Gota.
What the API gives you
- API keys in any contextCreate sk_live_ and sk_test_ keys as a utility, on the platform or as a resident. Each key does only what that context and its scopes allow.
- Signed webhooksEvery event arrives signed with the Standard Webhooks headers, with retries and a per-resource sequence to drop anything that arrives out of order.
- A command-line toolgotactl signs in with a device code, lists and creates resources, forwards webhooks to your machine and triggers sandbox events.
Start paths
- QuickstartFrom sign-up to the first API call and the first webhook, in a sandbox.
- API ReferenceEach resource on its own page, with the request and response side by side.
- WebhooksThe events, their shared envelope and how to verify the signature.
- Test dataThe sandbox's magic values: payments that confirm, fail or stay pending.
Try it out
Three requests to a fresh sandbox and exactly what it answered. Replace $API_KEY with your sk_test_ key.
See the available APIs
curl
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog"Response 200
{
"linkset": [
{
"anchor": "$AUTH_API",
"title": "auth",
"service-desc": [
{
"href": "https://api.gota.umbeluzi.com/api/openapi.json",
"type": "application/openapi+json"
}
]
},
{
"anchor": "$PUBLIC_API",
"title": "public",
"service-desc": [
{
"href": "https://api.gota.umbeluzi.com/api/openapi.json",
"type": "application/openapi+json"
}
]
}
]
}List the sandbox customers
curl
curl -sS "$BUSINESS_API/customers?limit=2" \
-H "Authorization: Bearer $API_KEY"Response 200
{
"data": [
{
"id": "cus_3MLupmhWdRajYPwnuUOCwY7VqsZ",
"tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
"customer_type": "individual",
"category": "residential",
"display_name": "Ana Macuácua",
"phone": "+258841234567",
"status": "active",
"created_at": "2026-11-20T02:39:13.451136081Z",
"updated_at": "2026-11-20T02:39:13.451136081Z"
},
{
"id": "cus_3MLupXLzxDoMCAhiGCB689k3qgC",
"tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
"customer_type": "individual",
"category": "residential",
"display_name": "Amélia Tivane",
"tax_number": "460227018",
"phone": "+258 85 672 5953",
"status": "active",
"created_at": "2026-11-20T02:39:11.239879973Z",
"updated_at": "2026-11-20T02:39:11.239879973Z"
}
],
"has_more": true,
"next_cursor": "Y3VzXzNNTHVwWEx6eERvTUNBaGlHQ0I2ODlrM3FnQ3wxNzk1MTQyMzUxMjM5ODc5OTcz"
}List the sandbox invoices
curl
curl -sS "$BUSINESS_API/invoices?limit=2" \
-H "Authorization: Bearer $API_KEY"Response 200
{
"data": [
{
"id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs",
"tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
"invoice_number": "INV-000001",
"customer_id": "cus_3MLupXLzxDoMCAhiGCB689k3qgC",
"customer_name": "Amélia Tivane",
"account_id": "act_3MLupRAJjSkkg1T21gBKzpndUDy",
"account_number": "CTA-000006",
"account_holder_name": "Amélia Tivane",
"meter_id": "mtr_3MLupRNareSGQFb5tCdIn2sFADB",
"meter_serial": "SBX-000006",
"meter_holder_name": "Amélia Tivane",
"billing_run_id": "brn_3MLupmBaXwUyEBlr6MCrLMt1zgR",
"consumption_id": "cns_3MLupmUHQGbfw7nmdsJqFUYkCKN",
"from_reading_id": "rdg_3MLupXENzCHX1WPilsZUIwvxuZG",
"to_reading_id": "rdg_3MLupZ3zPlljlF180HEM2tgJb1h",
"period_start": "2026-10-01T00:00:00Z",
"period_end": "2026-10-31T23:59:59Z",
"consumption_m3": 35.657,
"tariff_version_id": "trf_3MLupQ79WCC5xzEodl02RHsXwBg",
"subtotal_cents": 265913,
"sanitation_cents": 26591,
"tax_cents": 46801,
"total_cents": 339305,
"balance_cents": 339305,
"amount_due_cents": 339305,
"currency": "MZN",
"status": "open",
"due_date": "2026-11-20T23:59:59Z",
"issued_at": "2026-11-20T02:39:13.072064739Z",
"line_items": [
{
"id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs_1",
"invoice_id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs",
"description": "Taxa fixa de abastecimento de água",
"description_code": "invoice_line.fixed_fee",
"quantity": 1,
"unit_price_cents": 15000,
"total_cents": 15000,
"line_type": "fixed_meter_charge",
"charge_code": "FIXED"
},
{
"id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs_2",
"invoice_id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs",
"description": "Volumetric Consumption Tier 1 (0.00m³ - 10.00m³)",
"description_code": "invoice_line.volumetric_tier",
"description_params": {
"from": "0.00",
"tier": "1",
"to": "10.00"
},
"quantity": 10,
"unit_price_cents": 4500,
"total_cents": 45000,
"line_type": "volumetric_tier",
"tier_number": 1
}
],
"created_at": "2026-11-20T02:39:13.072064739Z",
"updated_at": "2026-11-20T02:39:13.072064739Z"
},
{
"id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo",
"tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
"invoice_number": "INV-000002",
"customer_id": "cus_3MLupXETe6jSTPyDGaYZPNzj0YE",
"customer_name": "Secretaria Distrital de Boane",
"account_id": "act_3MLupSdoc4uILPMUUM0WWqlzsTE",
"account_number": "CTA-000004",
"account_holder_name": "Secretaria Distrital de Boane",
"meter_id": "mtr_3MLupQYsW7RiRoVzivFDhR15KTv",
"meter_serial": "SBX-000004",
"meter_holder_name": "Secretaria Distrital de Boane",
"billing_run_id": "brn_3MLupmBaXwUyEBlr6MCrLMt1zgR",
"consumption_id": "cns_3MLupgPG006La1dPeg0gIB0Q3bJ",
"from_reading_id": "rdg_3MLupVHHYyQsx1CpyFcyds4XW4l",
"to_reading_id": "rdg_3MLupauGBbBrC1Z4RO7nDyEqv7O",
"period_start": "2026-10-01T00:00:00Z",
"period_end": "2026-10-31T23:59:59Z",
"consumption_m3": 27.216,
"tariff_version_id": "trf_3MLupJ2e6kvjlShUEHaoNP38kuV",
"subtotal_cents": 264120,
"sanitation_cents": 26412,
"tax_cents": 46485,
"total_cents": 337017,
"balance_cents": 337017,
"amount_due_cents": 337017,
"currency": "MZN",
"status": "open",
"due_date": "2026-11-20T23:59:59Z",
"issued_at": "2026-11-20T02:39:13.072064739Z",
"line_items": [
{
"id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo_1",
"invoice_id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo",
"description": "Taxa fixa de abastecimento de água",
"description_code": "invoice_line.fixed_fee",
"quantity": 1,
"unit_price_cents": 60000,
"total_cents": 60000,
"line_type": "fixed_meter_charge",
"charge_code": "FIXED"
},
{
"id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo_2",
"invoice_id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo",
"description": "Volumetric Consumption Tier 1 (0.00m³ - 0.00m³)",
"description_code": "invoice_line.volumetric_tier",
"description_params": {
"from": "0.00",
"tier": "1"
},
"quantity": 27.216,
"unit_price_cents": 7500,
"total_cents": 204120,
"line_type": "volumetric_tier",
"tier_number": 1
}
],
"created_at": "2026-11-20T02:39:13.072064739Z",
"updated_at": "2026-11-20T02:39:13.072064739Z"
}
],
"has_more": true,
"next_cursor": "inv_3MLupmbvp22M0CycHOsOHdGFHYo"
}