Utility purchases

Buy airtime and data for a mobile number.

You can buy airtime and data for any mobile number in Ghana, paid from your wallet or by the customer over mobile money.

What you can buy

List the products on sale now:

GET /v1/utility-products

{
  "items": [
    {
      "id": "mtn-airtime",
      "category": "airtime",
      "network": "mtn",
      "name": "MTN airtime",
      "kind": "flexi",
      "min": "1.00",
      "max": "500.00",
      "currency": "GHS",
      "delivery": "verified"
    },
    {
      "id": "telecel-data-1gb",
      "category": "data",
      "network": "telecel",
      "name": "1GB",
      "kind": "fixed",
      "price": "10.00",
      "currency": "GHS",
      "validity": "30 days",
      "delivery": "unverified"
    }
  ]
}

The values above only show the shape. Read the list rather than hard-coding product IDs.

• The list has airtime and data only.
• MTN data is sold as flexi data. MTN’s named bundles are not offered.
• Ismart Global products are not offered.
• ECG and other meter products are not on sale yet.
• Telecel and AirtelTigo products show delivery: unverified. None has been confirmed delivered yet, so check the first ones you sell.

Amounts and fees

• A fixed product is sold at its price. Send that as the amount.
• A flexi product is sold at any amount from min to max.
• Airtime starts at GHS 1.00.
• The fee is added on top of the amount. You pay the amount plus the fee.

Ask for the fee before you buy:

GET /v1/fee-quotes/utilities?productId=mtn-airtime&amount=10.00&currency=GHS

{
  "productId": "mtn-airtime",
  "amount": "10.00",
  "currency": "GHS",
  "fee": "0.20",
  "gross": "10.20"
}

gross is what you pay. A quote holds nothing. The purchase prices again when it runs.

Buy

POST /v1/utility-purchases
Idempotency-Key: 6c1f0e2a-airtime-1

{
  "reference": "airtime-1001",
  "productId": "mtn-airtime",
  "amount": "10.00",
  "currency": "GHS",
  "beneficiary": { "msisdn": "233244123456" },
  "funding": { "type": "wallet" }
}

• reference is yours, and unique for each purchase. See Idempotency and references.
• beneficiary.msisdn is the number that receives the airtime or data, in 233 form.
• currency is GHS. No other currency is sold.

A 202 means the purchase was accepted. It has not been delivered yet:

{
  "reference": "airtime-1001",
  "status": "accepted",
  "product": { "id": "mtn-airtime", "category": "airtime", "network": "mtn", "name": "MTN airtime" },
  "beneficiary": { "msisdn": "233244123456" },
  "amount": "10.00",
  "currency": "GHS",
  "fee": "0.20",
  "gross": "10.20",
  "funding": { "type": "wallet" },
  "createdAt": "2026-10-04T10:00:00Z"
}

Funding

funding.type says who pays.

• wallet. The total is taken from your wallet. If the sale fails, it goes back to your wallet. Do not send a payer.
• collection. The customer pays. They get a mobile money prompt for the total and approve it on their phone. Nothing is sold until they have paid. If the sale then fails, they are refunded in full.

{
  "type": "collection",
  "payer": { "provider": "mtn", "msisdn": "233244000111" }
}

payer.provider is mtn or telecel.

Statuses

outcome_unknown means we could not tell whether the airtime or data was sent. The money stays held and nothing is sold again. iSmartPay finds out and moves the purchase on.

Follow a purchase with webhooks, or poll GET /v1/utility-purchases/{reference}. Treat any status you do not know as still in progress.

Permissions

Webhooks

Subscribe an endpoint to these events in the console:

data is the purchase as it stood when the event was sent. It does not carry the beneficiary’s number or the payer. Fetch the purchase by reference when you need them. See Webhooks.

If your webhook endpoints were set up before utility purchases arrived, edit or add an endpoint in the console once. Until then, these events are not sent to your business, and they do not appear in GET /v1/events.

Errors

As well as the common errors, a purchase or quote can be refused with: