Collect KES and UGX by mobile money

A mobile money collection asks one payer for one payment. You send the amount and the payer’s phone number. The payer gets a prompt on their phone, in Kenya on M-Pesa or in Uganda on MTN or Airtel, and once they approve it, Bitnob credits your company’s KES or UGX balance. The collection then closes. Collections don’t have their own endpoints. A collection is a virtual account created with rail: "mobile_money", so you create, fetch, list and test it with the virtual account endpoints.

How it works

Create the collection

Send the amount, network and payer’s phone number to Create virtual account with rail: "mobile_money". No customer or KYC is needed.

The payer approves the prompt

The payer’s phone shows a prompt for the exact amount. Nothing more is needed from you while the collection waits.

Your balance is credited

When the payer approves, Bitnob credits your KES or UGX balance, closes the collection and sends virtual_account.deposit.success.

Or the collection ends unpaid

If the payer doesn’t complete the payment, or doesn’t respond within about an hour, the collection closes unpaid and Bitnob sends virtual_account.collection.failed.

Networks and limits

Country	Currency	`network`	Payer phone number	Amount per collection
Kenya	KES	`MPESA`	`2547…` or `2541…`, 12 digits	KES 20 to KES 145,000
Uganda	UGX	`MTN` or `AIRTEL`	`2567…`, 12 digits	UGX 500 to UGX 4,000,000

List supported currencies returns the same details for each currency, including networks, phone_pattern, min_amount and max_amount, so you can validate input before you call the API. amount is an integer in base units, where 100 is 1 KES or 1 UGX. To collect KES 1,500, send 150000. UGX uses the same rule even though it has no minor unit in everyday use: UGX 20,000 is 2000000.

Create a collection

POST /api/virtual-accounts

{
  "reference": "col_ref_0001",
  "currency": "KES",
  "rail": "mobile_money",
  "amount": 150000,
  "network": "MPESA",
  "account_number": "254700000000",
  "account_name": "John Doe",
  "description": "Invoice 1042"
}

Field	Required	Notes
`reference`	Yes	Your unique reference for this collection. See Retries and references.
`currency`	Yes	`KES` or `UGX`.
`rail`	Yes	`mobile_money`. Leave it out and the request is treated as an NGN bank account.
`amount`	Yes	The exact amount to collect, in base units.
`network`	Yes	`MPESA` for KES. `MTN` or `AIRTEL` for UGX. Not case-sensitive.
`account_number`	Yes	The payer’s phone number, with or without the country code. It’s stored as digits with the country code.
`account_name`	No	The payer’s name.
`description`	No	A note for your own records, up to 255 characters. Returned as `metadata.description`.
`customer_id`	No	Links the collection to one of your customers, if you keep a record of the payer.
`country`	No	`KE` for KES or `UG` for UGX. Leave it out and it’s taken from the currency.
`lifetime`	No	Always `temporary` for a collection. Leave it out.

The response returns the collection with status: "active" while it waits for the payer:

{
  "success": true,
  "message": "Virtual account created successfully",
  "data": {
    "virtual_account": {
      "id": "00000000-0000-0000-0000-000000000001",
      "company_id": "00000000-0000-0000-0000-000000000002",
      "account_number": "254700000000",
      "account_name": "John Doe",
      "bank_name": "MPESA",
      "reference": "col_ref_0001",
      "currency": "KES",
      "status": "active",
      "account_alias": "John Doe",
      "lifetime": "temporary",
      "rail": "mobile_money",
      "country": "KE",
      "network": "MPESA",
      "expected_amount": "150000",
      "expires_at": "2026-10-30T10:00:00Z",
      "metadata": {
        "description": "Invoice 1042",
        "fees": "0"
      },
      "created_at": "2026-10-30T09:00:00Z",
      "updated_at": "2026-10-30T09:00:00Z"
    }
  },
  "timestamp": "2026-10-30T09:00:00.481Z"
}

Store id against your order. It’s the virtual_account_id on the deposit webhook, and the ID you pass to Get virtual account to check the collection. On a collection, some fields mean something different from an NGN bank account:

Field	On a collection
`account_number`	The payer’s phone number, as digits with the country code.
`bank_name`	The mobile money network.
`expected_amount`	The amount the payer is prompted for, in base units, as a string.
`expires_at`	When an unpaid collection stops waiting for the payer.
`failure_reason`	Why the collection ended unpaid. Only set when it did.

Rules for a collection

One payment. A collection takes one payment and then closes. Create a new collection for the next payment.
The exact amount. The payer must pay exactly the amount requested.
About an hour to pay. A collection that isn’t paid by expires_at closes unpaid, with failure_reason set and a virtual_account.collection.failed webhook.
No cancel. There is no endpoint to cancel a collection. An unpaid one ends on its own when it expires.

Collection statuses

`status`	Meaning
`active`	Waiting for the payer to approve the prompt.
`closed`	Finished. If `failure_reason` is empty the payer paid and your balance was credited. If it’s set, the collection ended unpaid.
`failed`	The prompt couldn’t be sent to the payer. Nothing was collected.

Retries and references

reference is your idempotency key. Sending the same reference again while the collection is still active returns the original collection with 201, and the payer is not prompted again. Retry a timed-out create with the same reference, never a new one, or the payer can get two prompts. Once a collection has closed or failed, its reference can’t be used again. Sending it returns 409 DUPLICATE_REFERENCE. Use a new reference to ask the same payer again.

Test in sandbox

In sandbox no prompt reaches a phone. Finish the collection yourself with Simulate deposit, choosing how the payer answers with outcome:

POST /api/virtual-accounts/{id}/simulate-deposit

{
  "outcome": "success"
}

`outcome`	What happens
`success`, or no body	Credits the full `expected_amount` to your balance, closes the collection and sends `virtual_account.deposit.success`.
`failed`	Credits nothing, closes the collection with `failure_reason` set and sends `virtual_account.collection.failed`. The response has `transaction: null` and an empty `new_balance`.

A collection can only be simulated once, while it’s active. Simulating one that has already finished returns 400. Collections have no hourly simulation cap.

Getting access

Collections are switched on per company, and per currency. Until they’re enabled for you, a create returns 403 FEATURE_NOT_ENABLED. Contact Bitnob to have KES or UGX collections enabled.

When something fails

403 FEATURE_NOT_ENABLED

Collections, or collections in that currency, aren’t enabled on your account. The detail names which, for example The UGX mobile money collections feature is currently not available.

400 with amount, network or account_number in details

A required collection field is missing or empty. amount, network and account_number are all required when rail is mobile_money.

amount must be between …

amount is outside the limits for the currency. The message gives the range in major and base units, for example amount must be between 20 and 145000 KES (base units 2000 to 14500000).

network must be one of …

The network isn’t one the currency takes. Use MPESA for KES, and MTN or AIRTEL for UGX.

account_number must be a Kenya (or Uganda) mobile number

The phone number doesn’t match the country’s format. Check it against phone_pattern from List supported currencies.

Currency must be KES or UGX for mobile_money

NGN is only available as a bank account. Leave rail out to create an NGN virtual account.

409 DUPLICATE_REFERENCE

The reference belongs to a collection that has already closed or failed, or to an NGN bank account. Use a new reference.

422 PROCESSING_ERROR

The prompt couldn’t be sent and the collection is left failed. Retry with a new reference.

Get started

Bitcoin

Stablecoins

Trading

Payouts

Card issuing

Virtual accounts

Collect KES and UGX by mobile money

How it works

Networks and limits

Create a collection

Rules for a collection

Collection statuses

Retries and references

Test in sandbox

Getting access

When something fails

​How it works

​Networks and limits

​Create a collection

​Rules for a collection

​Collection statuses

​Retries and references

​Test in sandbox

​Getting access

​When something fails

How it works

Networks and limits

Create a collection

Rules for a collection

Collection statuses

Retries and references

Test in sandbox

Getting access

When something fails