Payments

The Payments API allows you to collect money from customers through various channels.

Payment Types

Mobile Money

Airtel Money, M-Pesa, Mixx by Yas, Halotel. Customer receives USSD push to authorize.

Payment Flow

Create Payment Intent `POST /v1/payments` with payment type and amount.

Customer Completes Payment USSD push sent to customer's phone to

authorize.

Receive Webhook `payment.completed` or `payment.failed` sent to your

webhook URL.

Verify Status (Optional) `GET /v1/payments/{reference}` to confirm

payment status.

API Endpoints

Endpoint	Method	Description
`/v1/payments`	POST	Create payment intent
`/v1/payments`	GET	List all payments
`/v1/payments/{reference}`	GET	Get payment status
`/v1/payments/{reference}/push`	POST	Trigger USSD push
`/v1/payments/balance`	GET	Get account balance
`/v1/payments/search`	GET	Search payments

Payment Status

Status	Description
`pending`	Payment created, awaiting customer action
`completed`	Payment successful, funds received
`failed`	Payment failed (declined, timeout, etc.)
`voided`	Payment cancelled before completion
`expired`	Payment expired (4 hour timeout)

Payments expire after 4 hours if not completed. Create a new payment if the customer wants to retry.

Supported Currencies

Currency	Code	Minimum Amount	Format
Tanzanian Shilling	`TZS`	500	Integer (smallest unit)

Only TZS is supported. Other currencies (USD, EUR, KES, etc.) will return a 400 validation error.

List Payments

Retrieve all payments for your account with pagination.

GET /v1/payments?limit=20&offset=0
Authorization: Bearer <api_key>

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (max 100)
`offset`	integer	0	Pagination offset

Response

{
  "status": "success",
  "code": 200,
  "data": {
    "items": [
      {
        "amount": {
          "currency": "TZS",
          "value": 500
        },
        "api_version": "2026-01-25",
        "channel": {
          "provider": "airtel",
          "type": "mobile_money"
        },
        "completed_at": "2026-01-25T00:50:44.105159Z",
        "created_at": "2026-01-25T00:47:50.243311Z",
        "customer": {
          "email": "customer@email.com",
          "first_name": "Customer",
          "last_name": "Name",
          "phone": "+255781000000"
        },
        "external_reference": "S20388368013",
        "id": "672ad0e0-f95b-46b8-a91a-09490351055b",
        "metadata": {
          "order_id": "ORD-12345"
        },
        "object": "payment",
        "payment_type": "mobile",
        "reference": "6a490816-799b-4fc9-b9b6-2ec67c54e17e",
        "settlement": {
          "fees": { "currency": "TZS", "value": 9 },
          "gross": { "currency": "TZS", "value": 500 },
          "net": { "currency": "TZS", "value": 491 }
        },
        "status": "completed"
      }
    ],
    "total": 81,
    "limit": 20,
    "offset": 0
  }
}

Get Payment Status

Retrieve the current status of a payment by its reference.

GET /v1/payments/{reference}
Authorization: Bearer <api_key>

Response

{
  "status": "success",
  "code": 200,
  "data": {
    "amount": {
      "currency": "TZS",
      "value": 500
    },
    "api_version": "2026-01-25",
    "channel": {
      "provider": "airtel",
      "type": "mobile_money"
    },
    "completed_at": "2026-01-25T00:50:44.105159Z",
    "created_at": "2026-01-25T00:47:50.243311Z",
    "expires_at": "2026-01-25T04:47:50.159178Z",
    "object": "payment",
    "payment_type": "mobile",
    "reference": "6a490816-799b-4fc9-b9b6-2ec67c54e17e",
    "status": "completed"
  }
}

Get Account Balance

Retrieve your current account balance.

GET /v1/payments/balance
Authorization: Bearer <api_key>

Response

{
  "status": "success",
  "code": 200,
  "data": {
    "api_version": "2026-01-25",
    "available": {
      "currency": "TZS",
      "value": 6943
    },
    "balance": {
      "currency": "TZS",
      "value": 6943
    },
    "object": "balance"
  }
}

Search Payments

Search for payments by reference.

GET /v1/payments/search?reference={payment_reference}
Authorization: Bearer <api_key>

Query Parameters

Parameter	Type	Description
`reference`	string	Payment reference to search

Idempotency

Always use the Idempotency-Key header to prevent duplicate payments when retrying failed requests.

POST /v1/payments
Idempotency-Key: order-12345-attempt-1

Keys must be 30 characters or fewer — longer keys will return a 500 PAY_001 error
Keys are valid for 24 hours
Same key + same request body = returns cached response
Same key + different body = returns error

Mobile Money

On this page