Accepting mobile money in Flutter

Install

Flutter is served by the Dart and Flutter client. There is no Flutter-specific package, and this page does not pretend otherwise: what is below is that client, used the way Flutter is written.

flutter pub add ultraner

The snippets below are checked in CI against the API's own schemas. This client is not yet driven end to end against the sandbox the way the Node one is.

The Flutter trap

Never put an API key in the app bundle. A compiled binary is readable, and a key in it is public. Charge from your own server and have the app poll or listen for the result.

Taking a payment

Two things this shows that are easy to get wrong anywhere. The amount is in whole units for most African currencies, so 5000 TZS is five thousand shillings and not fifty. And provideris the network's provider code, not its brand name: Mixx by Yas is still Tigo on the wire.

// YOUR SERVER initiates the charge. The app never holds the key.
// The app asks your backend, which calls Ultraner:

Future<String> startPayment(String phone, int amount) async {
  final res = await http.post(
    Uri.parse('https://your-api.example.com/pay'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({'phone': phone, 'amount': amount}),
  );
  final body = jsonDecode(res.body);

  // A reference, not a result. The payer is about to see a prompt.
  return body['reference'] as String;
}

The response means the request was accepted, not that money moved. A mobile-money charge sends a prompt to the payer's handset and they may take a minute, or never answer. Which is why the next section is not optional.

Receiving the result

The webhook is how you learn a payment succeeded. Verify the signature over the raw bytes before trusting anything in the payload, acknowledge quickly, and do the work afterwards: a slow handler gets retried, and retries mean you will see the same event twice.

// The app cannot receive webhooks, so it waits on your backend, which does.
// Poll your own status endpoint, backing off, and stop on a terminal state.

Future<String> awaitResult(String reference) async {
  var delay = const Duration(seconds: 2);

  for (var attempt = 0; attempt < 10; attempt++) {
    await Future.delayed(delay);
    final res = await http.get(
      Uri.parse('https://your-api.example.com/payments/$reference'),
    );
    final status = jsonDecode(res.body)['status'] as String;

    // Terminal states. Anything else means keep waiting.
    if (status == 'success' || status == 'failed') return status;
    delay *= 2;
  }
  return 'pending';    // tell the user honestly, do not claim failure
}