DocumentationRecipesAPI ReferencesSupportBlog
Documentation

Uganda Mobile Money

Learn about Mobile Money support in Uganda

Suggest Edits

📘

Getting Started

We recommend checking out the introductory section to understand the basics of direct charge first. This guide assumes you’ve read that.


If you're collecting money in UGX, your customers can pay with Uganda mobile money services.

The Process

This involves the following steps:

  1. You call our API to create a charge and pass in the customer's mobile number and network.
  2. Your customer completes the payment by authorizing it with their mobile money provider.

Initiating the Payment

First, you'll need the customer's mobile money phone_number and network (either "MTN" or "AIRTEL").

Combine that with the rest of the payment details to create the payload and send it to our charge Uganda mobile money endpoint. You'll need to specify amount, currency, email and a unique tx_ref.

You can also specify more details, such as the customer's fullname, a previously-generated voucher, and custom meta information. See the endpoint documentation for details.

// Install with: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);
const payload = {
    phone_number: '054709929220',
    network: "MTN",
    amount: 1500,
    currency: 'UGX',
    email: '[email protected]',
    tx_ref: this.generateTransactionReference(),
}
flw.MobileMoney.uganda(payload)
    .then(console.log)
    .catch(console.log);

// Install with: composer require flutterwavedev/flutterwave-v3

$flw = new \Flutterwave\Rave(getenv('FLW_SECRET_KEY'));
// Set `PUBLIC_KEY` as an environment variable
$mobileMoneyService = new \Flutterwave\MobileMoney();
$payload = [
    "type" => "mobile_money_uganda"
    "phone_number" => '25454709929220',
    "network" => "MTN",
    "amount" => 1500,
    "currency" => 'UGX',
    "email" => '[email protected]',
    "tx_ref" => $this->generateTransactionReference(),
];
$response = $mobileMoneyService->mobilemoney($payload);
print_r($response);

# Install with: gem install flutterwave_sdk

require 'flutterwave_sdk'

flw = Flutterwave.new(ENV["FLW_PUBLIC_KEY"], ENV["FLW_SECRET_KEY"], ENV["FLW_ENCRYPTION_KEY"])
charge = MobileMoney.new(flw)
payload = {
    phone_number: '054709929220',
    network: "MTN",
    amount: 1500,
    currency: 'UGX',
    email: '[email protected]',
    tx_ref: generate_transaction_reference,
}
response = charge.initiate_charge payload
print response

curl --request POST \
   --url https://api.flutterwave.com/v3/charges?type=mobile_money_uganda \
   --header 'Authorization: Bearer YOUR_SECRET_KEY' \
   --header 'content-type: application/json' \
   --data '{
     "phone_number": "054709929220",
     "network": "MTN",
     "amount": 1500,
     "currency": "UGX",
     "email": "[email protected]",
     "tx_ref": "BJUYU399fcd43"
}'

Handling the Response

You'll get a response that looks like this:

{
  "status": "success",
  "message": "Charge initiated",
  "meta": {
    "authorization": {
      "redirect": "https://ravemodal-dev.herokuapp.com/captcha/verify/144:16cbc719bf66ded37d5522de185f6a58",
      "mode": "redirect"
    }
  }
}

The meta.authorization object contains the details needed to complete the transaction. The mode is "redirect", meaning you should redirect your customer to the provided URL to complete the payment.

Completing the Payment

To complete the payment, the customer authorizes it with their mobile money provider using the provided redirect URL.

🧪

Testing Tip

In Test Mode, you can complete the transaction by visiting the returned redirect URL and entering 123456 as the OTP.

When the payment is completed, we'll send you a webhook notification. Here's what the payload looks like:

{
  "event": "charge.completed",
  "data": {
    "id": 2073992,
    "tx_ref": "BJUYU399fcd43",
    "flw_ref": "flwm3s4m0c1620380894041",
    "device_fingerprint": "N/A",
    "amount": 1500,
    "currency": "UGX",
    "charged_amount": 1500,
    "app_fee": 45,
    "merchant_fee": 0,
    "processor_response": "Approved",
    "auth_model": "MOBILEMONEY",
    "ip": "::ffff:10.30.86.54",
    "narration": "MerchantName",
    "status": "successful",
    "payment_type": "mobilemoneygh",
    "created_at":"2021-05-07T09:48:13.000Z",
    "account_id": 732559,
    "meta": null,
    "customer":{
      "id": 841600,
      "name": "Anonymous Customer",
      "phone_number": "054709929220",
      "email": "[email protected]",
      "created_at":"2021-05-07T09:48:13.000Z"
    }
  }
}

In your webhook handler, you can then verify the payment and credit your customers with whatever they paid for. See our guide to transaction verification for details.

Updated about 1 month ago