Bill Payments API

Learn how to pay utility bills including electricity (LIGHT), water (NWSC), and TV subscriptions (DSTV/GOTV) using Marz Pay

API Overview

Base URL

https://wallet.wearemarz.com/api/v1

Authentication

API Key (Basic Auth)

Content Type

application/json

Overview

Bill Payments API allows you to pay utility bills directly through Marz Pay. The system supports multiple utilities including electricity, water, and TV subscriptions. All payments are processed in real-time through our payment provider.

Supported Utilities

  • LIGHT - Electricity bills (prepaid meters)
  • NWSC - Water bills (National Water and Sewerage Corporation)
  • DSTV - DSTV TV subscription payments
  • GOTV - GOTV TV subscription payments

API Base URL

All bill payment API requests should be made to the following base URL:

https://wallet.wearemarz.com/api/v1

API Endpoints

POST /bill-payment Initiate a bill payment
POST /bill-payment/verify Verify meter/account number
GET /bill-payment List bill payment transactions
GET /bill-payment/services Get available utilities and their requirements
GET /bill-payment/nwsc/areas Get available NWSC areas
GET /bill-payment/dstv/bouquet-codes Get available DSTV bouquet codes
GET /bill-payment/gotv/bouquet-codes Get available GOTV bouquet codes
GET /bill-payment/{reference} Get transaction details by reference

Authentication

All bill payment API requests require authentication using your API key in the Authorization header with Basic Auth format. 

Authorization: Basic YOUR_API_CREDENTIALS

Format: YOUR_API_CREDENTIALS = base64_encode("your_api_key:your_api_secret")

Verify Meter/Account Number

Before making a payment, you should verify the meter or account number to retrieve customer details and outstanding balance (if applicable).

Request

POST https://wallet.wearemarz.com/api/v1/bill-payment/verify

Request Body

LIGHT (Electricity)

{
  "utility_code": "LIGHT",
  "meter_number": "12345678901"
}

NWSC (Water)

{
  "utility_code": "NWSC",
  "meter_number": "12345678901",
  "area": "Kampala"
}

DSTV/GOTV

{
  "utility_code": "DSTV",
  "meter_number": "7039132763"
}

Note: Bouquet code is not required for verification. It will be returned in the response along with bouquet name and price.

Request Parameters

Parameter Type Required Description
utility_code string Yes Utility code: LIGHT, UMEME, NWSC, DSTV, or GOTV
meter_number string Yes Meter or account number
area string Required for NWSC NWSC area (e.g., Kampala, Entebbe)
bouquet_code string No For DSTV/GOTV verification: Not required (returned in response). For payment: Required.

Response (Success)

NWSC/LIGHT Response

{
  "status": "success",
  "message": "Meter/Account number verified successfully",
  "data": {
    "customer_details": {
      "customer_ref": "12345678901",
      "customer_name": "John Doe",
      "outstanding_balance": "5000.00",
      "area": "Kampala",
      "customer_type": "PREPAID",
      "last_payment_date": "2026-01-15",
      "last_payment_amount": "10000.00"
    },
    "utility_code": "NWSC",
    "meter_number": "12345678901"
  }
}

DSTV/GOTV Response

{
  "status": "success",
  "message": "Meter/Account number verified successfully",
  "data": {
    "customer_details": {
      "customer_ref": "7039132763",
      "smart_card_no": "7039132763",
      "customer_name": "John Doe",
      "bouquet_code": "PREE36",
      "bouquet_name": "Premium",
      "bouquet_price": "320000",
      "utility_code": "DSTV"
    },
    "utility_code": "DSTV",
    "meter_number": "7039132763"
  }
}

Note: For DSTV/GOTV, the verification response includes the current bouquet code, name, and price. When making a payment, you must use the exact bouquet price as the payment amount. You can also fetch all available bouquets with their prices and periods using the bouquet codes endpoint.

Initiate Bill Payment

Create a new bill payment transaction. The system will process the payment immediately and return the transaction status.

Request

POST https://wallet.wearemarz.com/api/v1/bill-payment

Request Body

LIGHT (Electricity)

{
  "reference": "550e8400-e29b-41d4-a716-446655440000",
  "utility_code": "LIGHT",
  "meter_number": "12345678901",
  "phone_number": "+256700000000",
  "amount": 10000,
  "customer_name": "John Doe",
  "email": "john@example.com"
}

NWSC (Water)

{
  "reference": "550e8400-e29b-41d4-a716-446655440000",
  "utility_code": "NWSC",
  "meter_number": "12345678901",
  "area": "Kampala",
  "phone_number": "+256700000000",
  "amount": 50000,
  "customer_name": "John Doe",
  "email": "john@example.com"
}

DSTV/GOTV

{
  "reference": "550e8400-e29b-41d4-a716-446655440000",
  "utility_code": "DSTV",
  "meter_number": "7039132763",
  "bouquet_code": "PREE36",
  "phone_number": "+256700000000",
  "amount": 320000,
  "customer_name": "John Doe",
  "email": "john@example.com"
}

Important: The payment amount must exactly match the bouquet price. For example, if the bouquet price is UGX 320,000, the amount must be exactly 320000. Use the bouquet codes endpoint to get the exact price for each bouquet.

Request Parameters

Parameter Type Required Description
utility_code string Yes LIGHT, UMEME, NWSC, DSTV, or GOTV
meter_number string Yes Meter or account number
phone_number string Yes Phone number in format +256XXXXXXXXX
amount number Yes Payment amount in UGX (minimum: 1,000). For DSTV/GOTV, must match bouquet price exactly.
area string Required for NWSC NWSC area (e.g., Kampala, Entebbe)
bouquet_code string Required for DSTV/GOTV Bouquet code (e.g., PREE36, COMPE36). Use the /bill-payment/dstv/bouquet-codes or /bill-payment/gotv/bouquet-codes endpoint to get available codes with prices.
customer_name string No Customer name (optional)
email string No Customer email (optional)
reference string Yes Your unique transaction reference in UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000). Must be unique per business.

Response (Success)

{
  "status": "success",
  "message": "LIGHT bill payment successful!",
  "data": {
    "transaction": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "reference": "BP1234567890",
      "status": "completed",
      "provider_reference": "32686091830930101535"
    },
    "bill_payment": {
      "utility_code": "LIGHT",
      "meter_number": "12345678901",
      "customer_name": "John Doe",
      "amount": {
        "formatted": "10,000.00",
        "raw": 10000,
        "currency": "UGX"
      },
      "charge": {
        "formatted": "1,500.00",
        "raw": 1500,
        "currency": "UGX"
      },
      "total_amount": {
        "formatted": "11,500.00",
        "raw": 11500,
        "currency": "UGX"
      }
    },
    "timeline": {
      "initiated_at": "2026-02-11 14:30:00",
      "completed_at": "2026-02-11 14:30:05"
    }
  }
}

Status 1000 (Pending)

If the payment provider returns Status 1000, it means the transaction is successful but pending confirmation. The system will:

  1. Deduct the total amount from your balance immediately
  2. Set the transaction status to "pending"
  3. Wait 3 seconds and automatically check the final status
  4. Update the transaction to "completed" or "failed" based on the result
  5. Refund the money if the transaction fails

Get Available Services

Retrieve a list of available utilities and their requirements.

Request

GET https://wallet.wearemarz.com/api/v1/bill-payment/services

Response (Success)

{
  "status": "success",
  "data": {
    "available_utilities": [
      {
        "code": "LIGHT",
        "name": "LIGHT (Electricity)",
        "description": "Pay electricity bills for LIGHT (UMEME) prepaid meters",
        "required_fields": ["meter_number", "phone_number", "amount"],
        "optional_fields": ["customer_name", "email"]
      },
      {
        "code": "NWSC",
        "name": "NWSC (Water)",
        "description": "Pay water bills for NWSC",
        "required_fields": ["meter_number", "phone_number", "amount", "area"],
        "optional_fields": ["customer_name", "email"],
        "area_options": ["Kampala", "Entebbe", "Jinja", ...]
      },
      {
        "code": "DSTV",
        "name": "DSTV (TV Subscription)",
        "description": "Pay DSTV subscription bills",
        "required_fields": ["meter_number", "phone_number", "amount", "bouquet_code"],
        "optional_fields": ["customer_name", "email"],
        "bouquet_code_options": ["COMPACT", "PREMIUM", "CONFAM", ...]
      },
      {
        "code": "GOTV",
        "name": "GOTV (TV Subscription)",
        "description": "Pay GOTV subscription bills",
        "required_fields": ["meter_number", "phone_number", "amount", "bouquet_code"],
        "optional_fields": ["customer_name", "email"],
        "bouquet_code_options": ["COMPACT", "PREMIUM", "CONFAM", ...]
      }
    ]
  }
}

Get NWSC Areas

Retrieve a list of available NWSC areas for water bill payments.

Request

GET https://wallet.wearemarz.com/api/v1/bill-payment/nwsc/areas

Response (Success)

{
  "status": "success",
  "data": {
    "utility_code": "NWSC",
    "utility_name": "NWSC (Water)",
    "areas": ["Kampala", "Entebbe", "Jinja", "Mukono", ...],
    "count": 9,
    "description": "Available areas for NWSC water bill payments"
  }
}

Get Bouquet Codes

Retrieve available bouquet codes for DSTV or GOTV subscriptions with full details including price and subscription period.

Request

GET https://wallet.wearemarz.com/api/v1/bill-payment/dstv/bouquet-codes
GET https://wallet.wearemarz.com/api/v1/bill-payment/gotv/bouquet-codes

Response (Success)

{
  "status": "success",
  "data": {
    "utility_code": "DSTV",
    "utility_name": "DSTV (TV Subscription)",
    "bouquet_codes": ["PREE36", "COMPE36", "COFAME36", ...],
    "bouquet_details": [
      {
        "code": "PREE36",
        "name": "Premium",
        "price": "320000",
        "description": "DStv Premium combines the best entertainment from",
        "pay_tv_code": "DSTV",
        "period": 1,
        "period_label": "1 Month"
      },
      {
        "code": "COMPE36",
        "name": "Compact",
        "price": "120000",
        "description": "Normal Dstv Compact Bouquet",
        "pay_tv_code": "DSTV",
        "period": 1,
        "period_label": "1 Month"
      },
      {
        "code": "COMP7DE36",
        "name": "DStv Compact 7D",
        "price": "39000",
        "description": "DStv Compact Bouquet 7D E36",
        "pay_tv_code": "DSTV",
        "period": 7,
        "period_label": "7 Days"
      },
      ...
    ],
    "count": 37,
    "description": "Available bouquet codes for DSTV subscription payments",
    "source": "static_data"
  }
}

Bouquet Details Fields

  • code - Bouquet code (e.g., "PREE36", "COMPE36")
  • name - Bouquet name (e.g., "Premium", "Compact")
  • price - Bouquet price in UGX (string format)
  • description - Bouquet description
  • pay_tv_code - TV provider code ("DSTV" or "GOTV")
  • period - Subscription period in numeric format (1 = 1 month, 7 = 7 days, 3 = 3 months, 12 = 12 months)
  • period_label - Human-readable period (e.g., "1 Month", "7 Days", "3 Months", "12 Months")

Get Transaction Details

Retrieve details of a specific bill payment transaction using its reference number.

Request

GET https://wallet.wearemarz.com/api/v1/bill-payment/{reference}

Response (Success)

{
  "status": "success",
  "data": {
    "transaction": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "reference": "BP1234567890",
      "status": "completed",
      "provider_reference": "32686091830930101535",
      "amount": {
        "formatted": "10,000.00",
        "raw": 10000,
        "currency": "UGX"
      },
      "charge": {
        "formatted": "1,500.00",
        "raw": 1500,
        "currency": "UGX"
      },
      "total_amount": {
        "formatted": "11,500.00",
        "raw": 11500,
        "currency": "UGX"
      },
      "bill_payment": {
        "utility": "LIGHT",
        "utility_code": "LIGHT",
        "meter_number": "12345678901",
        "customer_name": "John Doe",
        "area": null,
        "package": null
      },
      "created_at": "2026-02-11 14:30:00",
      "updated_at": "2026-02-11 14:30:05"
    }
  }
}

List Bill Payment Transactions

Retrieve a paginated list of your bill payment transactions with optional filtering.

Request

GET https://wallet.wearemarz.com/api/v1/bill-payment

Query Parameters

Parameter Type Required Description
status string No Filter by status: pending, completed, failed
utility_code string No Filter by utility: LIGHT, NWSC, DSTV, GOTV
start_date string No Start date (YYYY-MM-DD)
end_date string No End date (YYYY-MM-DD)
reference string No Search by reference (partial match)
meter_number string No Search by meter/account number
page integer No Page number (default: 1)
per_page integer No Items per page (default: 15, max: 100)

Pricing

Transaction Fee

Each bill payment transaction incurs a fixed service charge of UGX 1,500 per transaction, in addition to the payment amount.

Payment Amount

UGX 10,000

Service Charge

UGX 1,500

Total Amount Deducted

UGX 11,500

Important

Ensure your account balance is sufficient to cover both the payment amount and the service charge. The system will check your balance before processing the transaction.

Fee Structure

Utility Type Service Charge Minimum Payment
LIGHT (Electricity) UGX 1,500 UGX 1,000
NWSC (Water) UGX 1,500 UGX 1,000
DSTV UGX 1,500 UGX 1,000
GOTV UGX 1,500 UGX 1,000

Prerequisites

You must have an active Bill Payments service subscription

Your business account must have sufficient balance (amount + charge)

Your business account must not be frozen

For NWSC payments, you must provide a valid area

For DSTV/GOTV payments, you must provide a valid bouquet code

Best Practices

1. Verify Before Paying

Always verify the meter/account number before initiating a payment. This ensures the account exists and retrieves customer details. For DSTV/GOTV, verification returns the current bouquet code, name, and price, which you can use for payment.

2. Provide Unique UUID Reference

Always provide a unique UUID reference for each transaction. The reference must be in UUID v4 format (e.g., 550e8400-e29b-41d4-a716-446655440000) and must be unique per business. The system will validate the format and check for duplicates.

3. Transaction Status

The system processes payments immediately and returns a completed transaction status. If the payment provider returns status 1000 (pending), the system automatically checks the final status and returns completed. You can also check the status later using the transaction reference.

4. Store Transaction References

Save the transaction reference returned in the response. Use it to check transaction status or retrieve details later.

5. Use Webhooks

Set up webhooks to receive real-time notifications when bill payment transactions are completed or fail.

5. Fetch Bouquet Details

Use the bouquet codes endpoints to get all available bouquets with their prices and subscription periods. Always use the exact bouquet price as the payment amount for DSTV/GOTV payments.

6. DSTV/GOTV Payment Amount Validation

For DSTV and GOTV payments, the payment amount must exactly match the bouquet price. The system validates this and returns an error if the amounts don't match. Always fetch the bouquet details first to get the exact price.

Error Responses

Insufficient Balance

{
  "status": "error",
  "message": "Insufficient balance. Required: UGX 11,500.00, Available: UGX 5,000.00",
  "error_code": "INSUFFICIENT_BALANCE"
}

Service Not Subscribed

{
  "status": "error",
  "message": "Bill Payments service is not subscribed. Please subscribe first.",
  "error_code": "SERVICE_NOT_SUBSCRIBED"
}

Validation Error

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "reference": ["Reference is required and must be a valid UUID format."],
    "area": ["Area is required for NWSC payments."],
    "bouquet_code": ["Bouquet code is required for DSTV payments."]
  }
}

Invalid Reference Format

{
  "status": "error",
  "message": "Reference must be a valid UUID format (e.g., 123e4567-e89b-12d3-a456-426614174000).",
  "error_code": "INVALID_REFERENCE_FORMAT"
}

Duplicate Reference

{
  "status": "error",
  "message": "This reference has already been used.",
  "error_code": "DUPLICATE_REFERENCE"
}

Amount Mismatch (DSTV/GOTV)

{
  "status": "error",
  "message": "Payment amount (UGX 150,000.00) does not match the bouquet price (UGX 320,000.00). Please pay exactly UGX 320,000.00 for Premium (1 Month).",
  "error_code": "AMOUNT_MISMATCH",
  "data": {
    "bouquet_code": "PREE36",
    "bouquet_name": "Premium",
    "bouquet_price": 320000,
    "payment_amount": 150000,
    "period": 1,
    "period_label": "1 Month",
    "required_amount": 320000
  }
}

Verification Failed

{
  "status": "error",
  "message": "Failed to verify meter/account number",
  "error_code": "VERIFICATION_FAILED",
  "data": {
    "status_code": 101,
    "status_description": "GENERAL ERROR"
  }
}
Chat on WhatsApp