---
title: "Make airtime purchases via a sub account"
method: POST
path: "/v1/bill/topup/{subAccountId}"
tags: ["Airtime and Data Vending"]
deprecated: true
---

# Make airtime purchases via a sub account

`POST /v1/bill/topup/{subAccountId}`

## Request

- Base URL: `https://api.nomba.com`
- URL: `https://api.nomba.com/v1/bill/topup/{subAccountId}`
- Auth: HTTP bearer

> **Deprecated.**

**Deprecated.** This endpoint is deprecated and will be removed in a future release. Use `POST /v2/bill/topup/{subAccountId}` instead.

## Path parameters

- `subAccountId` string, uuid, required

## Headers

- `accountId` string, uuid, required

## Request body

- AirtimePurchaseRequest
  - `amount` number, double, required: The airtime amount to be purchased
  - `phoneNumber` string, required: Recipient phone number
  - `network` 'GLO' | 'MTN' | '9MOBILE' | 'AIRTEL', required: Recipient network (telco). It can also come as lowercased values e.g. glo, mtn etc.
  - `merchantTxRef` string, required: Merchant Transaction Identifier reference (Unique to merchant) This is an idempotency key and must be unique per transaction.
  - `senderName` string: A name to describe the sender of the airtime

## Response `200`

OK - your request was successful.

- object
  - `code` string, required: Response Code
  - `description` string, required: Response description
  - `data` AirtimePurchaseResponse, required
    - `amount` number, double, required: The airtime amount to be purchased
    - `timeCreated` string, date-time, required: The Date and Time of transaction creation
    - `type` string, required: The classification for this type of transaction
    - `meta` object: Extra information about this transaction
    - `status` 'SUCCESS' | 'PROCESSING', required: The status of this transaction. `SUCCESS` means it completed; `PROCESSING` means it is still being processed — listen for the webhook or requery the transaction for the final status.
    - `id` string: The unique ID of the transaction, e.g. `API-TOPUP-A6950-8c060b7c-4155-4e33-a846-101b49229c33`. Use it to requery the transaction.

## Other responses

- `400`: The request body sent by merchant did not pass the validation checks
- `401`: The access_token provided to access the resource is missing or invalid.
- `403`: The client does not have the permissions to access this resource
- `404`: The record that the client is trying to access does not exist.
- `429`: The client has maxed out the number of calls within a time period on this resource.
- `500`: Downstream system error.
- `default`: Resource not available

## Changes

- **2026-11-03** `278a25dccfe5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nomba/apis/vendor-api/changes/v1/bill/topup/:subAccountId/post.md)

---

[API](https://skmtc.dev/nomba/apis/vendor-api.md) - [All operations](https://skmtc.dev/nomba/apis/vendor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nomba/apis/vendor-api/revisions/278a25dccfe5?raw)