Have you ever integrated our payment API into your product? Help us improve the developer experience for you and everyone by taking this short survey, get started here

Francophone mobile money

Hey👋. We recommend checking out the overview to understand the basics of direct charge first. This guide assumes you've read that.

If you're collecting money in francs (XAF or XOF), your customers can pay with mobile money services.

Process

  1. You call our API to create a charge, passing in the customer's mobile number.
  2. Your customer completes the payment by authorising it with their mobile money provider.

Initiating the payment

First, you'll need the customer's phone_number. Combine that with the rest of the payment details to create the payload and send to our charge Francophone mobile money endpoint. You'll need to specify amount, currency, email, country and a unique tx_ref.

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

Country codes

Only ISO 3166 Alpha-2 codes are supported as the country param. You can get a full list here. Possible values are CM (Cameroon), SN (Senegal), BF (Burkina Faso) and CI (Côte d'Ivoire).

// 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: '24709929220',
    amount: 1500,
    currency: 'XAF',
    email: 'JoeBloggs@acme.co',
    tx_ref: this.generateTransactionReference(),
}
flw.MobileMoney.franco_phone(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_franco"
    "phone_number" => '24709929220',
    "amount" => 1500,
    "currency" => 'XAF',
    "email" => 'JoeBloggs@acme.co',
    "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: '24709929220',
    amount: 1500,
    currency: 'XAF',
    email: 'JoeBloggs@acme.co',
    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_franco \
   --header 'Authorization: Bearer YOUR_SECRET_KEY' \
   --header 'content-type: application/json' \
   --data '{
     "phone_number": "24709929220",
     "amount": 1500,
     "currency": "XAF",
     "email": "JoeBloggs@acme.co",
     "tx_ref": "BJUYU399fcd43"
}'
Collecting XOF payments using Wave

For customers using Wave in Senegal and Côte d'Ivoire, please include network: wave in your request.

Handling the response

You'll get a response that looks like this:

{
  "status": "success",
  "message": "Charge initiated",
  "data": {
    "id": 2079825,
    "tx_ref": "MC-15852113s09v5050e8",
    "flw_ref": "YVOO069611620649860887",
    "device_fingerprint": "N/A",
    "amount": 1500,
    "charged_amount": 1500,
    "app_fee": 481.5,
    "merchant_fee": 0,
    "processor_response": "Transaction in progress",
    "auth_model": "AUTH",
    "currency": "XAF",
    "ip": "::ffff:10.63.255.131",
    "narration": "MerchantName",
    "status": "pending",
    "payment_type": "mobilemoneysn",
    "fraud_status": "ok",
    "charge_type": "normal",
    "created_at": "2021-05-10T12:30:57.000Z",
    "account_id": 732559,
    "customer": {
      "id": 843193,
      "phone_number": "237******20",
      "name": "Anonymous customer",
      "email": "user@flw.com",
      "created_at": "2021-05-10T12:30:56.000Z",
    }
  },
  "meta": {
    "authorization": {
      "mode": "callback",
      "redirect_url": null
    }
  }
}

The meta.authorization.mode field is "callback", which means the user needs to authorize with their mobile money service, and then we'll send you a webhook.

Completing the payment

To complete the payment, the customer authorizes it with their mobile money provider (for instance, via a push notification from the app).

Testing tip

In Test Mode, Francophone mobile money transactions are automatically completed after a few seconds.

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": "RWF",
    "charged_amount": 1500,
    "app_fee": 43.5,
    "merchant_fee": 0,
    "processor_response": "Approved",
    "auth_model": "MOBILEMONEY",
    "ip": "::ffff:10.30.86.54",
    "narration": "MerchantName",
    "status": "successful",
    "payment_type": "mobilemoneyrw",
    "created_at":"2021-05-07T09:48:13.000Z",
    "account_id": 732559,
    "meta": null,
    "customer":{
      "id": 841600,
      "name": "Anonymous Customer",
      "phone_number": "054709929220",
      "email": "JoeBloggs@acme.co",
      "created_at":"2021-05-07T09:48:13.000Z"
    }
  }

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

Loading...