PesaCast

Set up PesaCast in about fifteen minutes.

One Android phone that receives your M-PESA messages. Optionally, a computer to show them on.

What you need

  • An Android phone, version 8 or newer, with the SIM that receives the M-PESA messages. A spare one that stays plugged in is best.
  • A Mac or Windows computer, if you want payments on a desktop. Skip this if you only want the webhook.
  • For the one-command route: a USB cable and a computer with adb (Android platform-tools) and bash. On Windows, use Git Bash or WSL.

The steps

  1. Put the desktop app on the computer

    Download it from the releases page: the .dmg for Mac, the .exe or .msi for Windows. Skip this step for webhook-only setups.

  2. Turn on USB debugging on the phone

    Settings, About phone, tap Build number seven times. Then Developer options, USB debugging on. Plug the phone in and tap Allow on the prompt.

  3. Install PesaCast on the phone

    With the script, which downloads the app, checks it against its published checksum, installs it, grants the permissions a computer can grant, and checks the result:

    git clone https://github.com/davidamunga/pesacast
cd pesacast
scripts/setup-phone.sh --dry-run

    No git? Download the repository as a zip from GitHub and run the same commands in that folder.

    The dry run only prints what it would do. When it looks right:

    scripts/setup-phone.sh

    Prefer to do it by hand? The manual steps are the same commands, one at a time.

  4. Work down the setup checklist

    On the phone: Connect, then Setup checklist. It shows what is still missing, in order, and each item opens the right settings screen. The ones no computer can do for you are the SMS permission on some Android versions, battery saving, and your phone maker’s auto-start menu.

  5. Choose where payments go

    To the desktop: open the desktop app, Connect. For Wi-Fi, press “Find my phone”, then paste the pairing token shown on the phone. Bluetooth finds the phone on its own.

    To your server: follow the webhook guide. You can send the address and credentials from the computer instead of typing them on the phone.

  6. Run the test

    In the setup checklist, run the end-to-end test. It sends a clearly labelled test to everything that is switched on and tells you what worked. The desktop shows a fake test payment; the webhook gets a request marked as a test.

When it does not work

  • Payments arrive late, or stop after a while. The phone is putting PesaCast to sleep. Finish the battery and auto-start items in the checklist. See phones.
  • The SMS permission cannot be granted. On Android 13 and newer, open the app’s info screen, tap the three dots, and choose “Allow restricted settings”. Then allow SMS.
  • Play Protect asks about the app. It has not seen it before and it was not installed from a store. Choose the option that lets you continue. Do not turn Play Protect off.
  • The script says the checksum does not match. Do not install the file. Download again, or ask in an issue.

Undo it

scripts/setup-phone.sh --uninstall --yes

That removes the app and the settings the script changed.