Automate any USSD Service on Android

A Step by Step Example with the Hover SDK

This is part one of a two-part post. Check out part two when you’re done here.

Suppose you’re an Android developer distributing an app in Tanzania, and you want your customers to be able to pay for goods or services offered through your app. For mobile money users (e.g. Airtel Money, Vodacom M-Pesa, etc.), a common approach is to provide instructions to leave your app, open the dialer, and pay via USSD. For example here’s a screenshot from Jumia Food, a food delivery service in Rwanda:

The user experience of a USSD payment leaves a lot to be desired:

The eight steps of a USSD payment on Vodacom Tanzania. It includes six USSD steps, a phone number from memory and an SMS confirmation.

Users have to write down or remember arbitrary numbers, and restart the process if they make a typo or the USSD session times out. This is inconvenient at best and can be insurmountable for people with disabilities. As a developer you give up control of the user experience. Even when mobile operators offer an Android mobile money app alongside USSD, users still have to leave your app and you often have no way of programmatically detecting whether the transaction was successful.

We built the Hover Android SDK to help you work around these issues. We’ll use Send Money on Vodacom M-Pesa as an example, but you can use a similar approach to automate any USSD-based service on any mobile operator in the world. If you don’t have your own app but have experience with Android development, our sample apps on Github are a good starting point for this example or your own experiments.

1. Create an action
An action represents a path through the USSD menus of a specific mobile operator, bank, or 3rd party, in this case Send Money on Vodacom Tanzania. Actions are how you configure the SDK to navigate USSD menus on an end user’s Android device.

To begin, sign up for a Hover account or log in to your existing one. From the dashboard, or the welcome screen if it’s a new account, click “New action” and give your action a name. For this example we’ll call it “Send money”. Select the country and mobile operator, then enter the root code, i.e. the string a user would dial to initiate the USSD session: *150*00#

2. Add steps
Next, add steps to your action. Each step corresponds to a screen in the USSD session shown in the screenshots above. Hover currently supports three types of steps:

• Choose a number from a menu
• Enter a variable at runtime
• Prompt the user for their PIN

The steps for our Send Money action are shown in the screenshot below. We start with a number type step to choose 1 for Send Money, followed by two variable type steps for the amount and recipient phone number, then insert the user’s PIN and finally select 1 to confirm. You will use the variable names, here “phoneNumber” and “amount”, to provide values for these steps from your application code. When an action contains a PIN step, the user is prompted to enter their PIN when the action is run on the device. The PIN is encrypted using the Android Keystore system, only stored for the duration of the USSD session, and never leaves the user’s device. It is not sent to Hover and can’t be seen by your application code.

Click “Save”, and take note of the action ID to use when you integrate the SDK in step 4. See our docs for more information about actions, steps and pin storage with Hover.

3. Install the Hover SDK in your app
Return to your Hover dashboard and click “New app”. Give your app a name for your reference, it won’t be shown to end users, and enter the package name exactly as it appears in AndroidManifest.xml. Click “Save” and take note of your API Token. Follow the instructions in our getting started guide to install the Hover SDK with Maven. Make sure to add a call to `Hover.initialize()` so the SDK downloads your new action.

4. Add the action to your app
Now the good part, actually running the USSD session from your app. You’ll usually want to call the Hover SDK in response to a user action, like tapping a button that says “Pay now”, scanning a QR code or tapping an NFC tag, etc. Your code should look something like this:

Button button = (Button) findViewById(R.id.pay_now_button);
button.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        Intent i = new HoverParameters.Builder(getApplicationContext())
        .request("YOUR_ACTION_ID")
        .extra(“phoneNumber”, “PHONE_NUMBER_VALUE”)
        .extra(“amount”, “AMOUNT_VALUE”)
        .buildIntent();
    startActivity(i);
    }
});

Replace YOUR_ACTION_ID with the action ID from step 2 above. PHONE_NUMBER_VALUE and AMOUNT_VALUE can be set in your application code or provided by end users through a UI which you create. All extras are Strings.

Now compile and run your app. When you trigger the onClickListener above you’ll be prompted for several run time permissions that Hover requires, which on most devices only needs to be done once per install. Read more about Hover permissions in the docs.

If all goes well you’ll be prompted for your PIN, and then see a progress spinner while Hover runs a USSD session in the background. You’ll receive a confirmation message shortly.

5. Next steps
That’s not quite all you can do with Hover. In a follow-up post we’ll show how to use `startActivityForResult` to understand whether the USSD session completed successfully. We’ll also demonstrate how to use Hover’s parsers to receive the result of the session, and return important information like confirmation codes and account balances to your app. If you can’t wait you can always read about parsers in the docs.

We’ve demonstrated a Send Money transaction, but this approach can be used to automate any USSD action you can think of. If you have questions about Hover or want feedback on an app idea, please send us an email at support@usehover.com. We’re always happy to talk with developers and others interested in using Hover, and we’re excited to see what you build.