Phoenix API Platform

Mobile Money API · Uganda

How to choose and integrate a Mobile Money API in Uganda

A Mobile Money API connects your application to payment operations such as collections and withdrawals. Choose a provider based on the operators and flows you need, transparent fees, test access and reliable transaction-status checks—not an unsupported “best gateway” claim.

CollectionsWithdrawalsNode.js exampleUganda

What should you compare in a Uganda payment gateway?

Before integrating any payment gateway, check which Mobile Money operators and account types are available to your business, whether you need customer collections, merchant payouts or both, and what the provider charges. Also confirm onboarding requirements, settlement timelines, test credentials, production approval, transaction limits and the support process for pending or disputed payments.

MTN Mobile Money and Airtel Money integrations may have different operator requirements and availability. Confirm current operator support and production access directly with your payment provider; availability can depend on your account and configuration.

Short answer: Phoenix exposes separate REST API operations for collections and withdrawals. Live transactions require production access, the appropriate API-key permissions and enabled provider configuration. Confirm current operator availability and fees in your Phoenix workspace before launch.

Collections and withdrawals are different flows

A collection asks a customer to authorize a payment to your business. A withdrawal (also called a payout or disbursement) sends money to a recipient. They use separate Phoenix endpoints and permissions, and withdrawals require sufficient wallet funds for the principal and configured charges.

A successful HTTP response does not mean the customer's payment is complete. Phoenix returns HTTP 202 when it accepts a collection request for processing. Reconcile the transaction status using the returned external reference and the status endpoint. Do not mark an order paid based only on the initial response, a browser redirect or an unverified notification.

Example: create a collection from Node.js

Use a production API key with the mobile_money:collections:create permission. Keep the key in a server-side environment variable. The example uses Phoenix's production API origin; set PHOENIX_API_BASE_URL if your account has a different API base URL.

import { randomUUID } from 'node:crypto';

const apiBase = process.env.PHOENIX_API_BASE_URL
  || 'https://phoenixapiplatform.onrender.com';
const apiKey = process.env.PHOENIX_MOBILE_MONEY_API_KEY;
if (!apiKey) throw new Error('Missing Phoenix API key');

const response = await fetch(
  `${apiBase}/v1/mobile-money/collections`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': randomUUID(),
    },
    body: JSON.stringify({
      phoneNumber: '+256785151142',
      amountMinor: 12500,
    }),
  },
);

if (!response.ok) {
  throw new Error(`Phoenix request failed: HTTP ${response.status}`);
}

const result = await response.json();
console.log('Track this reference:', result.data.externalId);

For a retry after a network timeout, reuse the same idempotency key and the same request body. Generate a new key only for a new payment attempt. Use the exact integer amount expected by the API and check the current minimums and limits for your account.

Check transaction status and protect your integration

After creating a collection, retrieve its current provider status with GET /v1/mobile-money/collections/{externalId}. The API key must also have the mobile_money:transactions:read permission. For withdrawals, Phoenix provides POST /v1/mobile-money/withdrawals and GET /v1/mobile-money/withdrawals/{externalId}.

  • Store API keys in server-side secrets, never browser JavaScript or mobile app bundles.
  • Grant keys only the service permissions your backend needs.
  • Use idempotency keys to prevent duplicate operations when retrying.
  • Reconcile final provider status before fulfilling an order or reporting a payout.
  • Check current fees, live-transaction enablement and operator coverage before production launch.

When Phoenix may fit

Phoenix may suit teams that want Mobile Money collection and withdrawal routes alongside SMS and transactional email in one developer workspace. Its API key permissions separate transaction creation from status reads, while asynchronous requests can be checked by external reference. Compare the platform against your operator, settlement, pricing and compliance requirements before choosing it.

See the Phoenix API Platform, then review the SMS and email integration guides for related backend workflows.