Hover is a developer friendly Android SDK which makes it easy to accept in-app payments from users on any mobile money system that uses USSD.

This  guide will cover integrating Hover into your existing app to accept  payments. We will integrate a mobile money payment method, install the  Hover SDK into an app, and process the payment confirmation. If you  don’t already have an app you can fork our sample starter app.

The prerequisites are fairly basic:

  • You can set up an account to receive the money. This can be any type of account: phone number, merchant till, or pay bill. If you have a  working SIM that can send and receive money then you are good to go, no  special agreement with the operator required!
  • The mobile money provider has a USSD or SIM Toolkit menu system.
  • You  have an app that is installed via the Play Store or APK download. It  can be native Java or Kotlin, React, Flutter or other cross platform  framework. PWAs and basic mobile sites won’t work.

That’s  it! Once the Hover SDK is integrated into your app you can start the  payment flow when the user clicks a button, receives a notification, or  any other trigger you choose. The user will be asked to confirm the  details (such as amount and recipient) and enter their PIN, much like  they would for a credit card or Paypal purchase.

Set up your in-app payments

We  are going to set up a simple example of users in Tanzania buying a pair  of shoes using Vodacom mobile money. We have a working Vodacom Tanzania  SIM card registered on MPESA and a simple native Android app. When a  user clicks a purchase button it will start the transaction with Hover  and then our app will show them a confirmation if their purchase is  successful.

Integrate the mobile money service

We are going to need a Hover account, so we sign-up for free and confirm our email. Once in the dashboard we need to add our app which will give us an API key we use later:

The package name must match the applicationId in the app’s app/build.gradle.  You can leave the webhook blank. Next we need to create an “action”  which is an end-to-end USSD flow. Our action will be Vodacom to Vodacom  send money. Click the Actions tab:

Then click “+ New Action”:

We will name our action “Vodacom Tanzania Payment” and select the correct country and network:

Now  we need to know what the USSD flow is on Vodacom in Tanzania. Since we  have the SIM card we use our phone app to dial its short-code *150*00# and  then go through the steps to complete a payment. Since we are just  getting started, we are going to accept money directly to our phone  number. Later, if we decide to sign-up for pay bill we can change this  configuration and it will automatically update for all our users without  them having to update their app.

This is the flow for sending money to a Vodacom phone number from Vodacom TZ:

So we enter this flow in our form:

Note  that we are essentially hard-coding the recipient number (ourselves)  here. We won’t be able to change it at run-time in our app, but we can  change it by updating this configuration. However, we have made the  amount a variable so that we can change it at run-time based on the  product that the user is purchasing.

After saving we are ready to write some code!

Add payments to our app

First let’s install Hover in our app. We need to add the Hover repo to our root build.gradle repositories:

allprojects {    
	repositories {        
		...        
		mavenCentral()
		maven { url "http://maven.usehover.com/releases" 
	}      
   } 
}

Then add the SDK to our app-level build.gradle

dependencies:dependencies {    
	...    
	implementation 'com.hover:android-sdk:1.4.3'
}

Next we grab our Hover API key from the Hover dashboard:

And add it to our app Android Manifest:

<application>
    ...
    <meta-data         
        android:name="com.hover.ApiKey"
        android:value="ab00804f31a1722837a225804c585213" /> 
</application>

Finally, we initialize Hover when our app is launched so that it can set up and download our configuration:

import com.hover.sdk.api.Hover; 
...  public class MainActivity extends AppCompatActivity { 
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);   
        ...
        Hover.initialize(this);  
    }  
 
    ...
}

Now we are ready to run our first transaction.

Making a purchase

Our  example app is just a simple e-commerce app with a list items and a  purchase button for each. If this were a real service we would obviously  need a shopping cart and delivery location information. Here is our  interface:

When a user clicks one of the buy now buttons the following function is called:

public void makeHoverRequest(View button) {
   // Get the price from your data model, not your view!
    View item = (View) button.getParent();
    String price = ((TextView) item.findViewById(R.id.price)).getText();
    price = price.replaceAll(",", "");   Intent i = new HoverParameters.Builder(this)
      .request("ff568a4e")
      .extra("amount", price)
      .buildIntent();
   startActivityForResult(i, 0);
}

We  pull the price information from the view and use it to make a Hover  request. Hover shows the following screens to the user to get their  permission:

Once  confirmed, the phone shows a processing screen while it contacts the  USSD service, and when it is finished our app gets a callback with  information about the transaction. We don’t yet know if the payment is  successful. For that we need to process the SMS receipt.

Processing payment receipt

To  automatically process orders before distributing our products we need  to confirm that the user’s payment is successful. For this head back to  the Hover dashboard and create a parser. This parser uses a regular  expression to check that the response message is in fact a payment  confirmation and get vital details from it, such as receipt number.

In the action detail view click New Parser:

This parser is a success parser to confirm payment, so set the details as shown below. Later we  may want to improve our app’s UX by creating failure parsers that check  different failure cases and show user friendly messages.

If  we take a look in our Android logcat we can see that the Hover SDK has  helpfully logged the SMS that we received in response to our test  payment from a moment ago.

After copying over the sender we need to really get our hands dirty and write that regular expression. Regex Planet is a great tool for this. Let’s copy our SMS message into the Input 1  field and check the `CASE_INSENSITIVE` and `DOTALL` boxes since the SDK  uses those.

The  regular expression needs to be unique enough that it isn’t going to  match messages other than the one we want and it needs to account for  the various variables. Please see our upcoming post on writing regex for  more pointers. Ultimately this is what we come up with:

When  we run it in Regex Planet we especially want to make sure that the  `matches()` box says “Yes” and that each of the `group()` boxes matches  the whole variable value from the message. It is easy to accidentally  lose some or most of a variable, and instead only get one or two  characters.

Now we can copy the regex back into our parser form and save it.

To  use it in our app we implement the BroadcastReceiver which will fire  when the confirmation SMS comes in. Add it to the manifest:

<receiver  
    android:name=".TransactionReceiver"
    android:enabled="true"
    android:exported="false">
    <intent-filter>   
        <action
            android:name="com.hover.example.ecommerce.CONFIRMED_TRANSACTION"/>  
    </intent-filter> 
</receiver>

And then create it:

public class TransactionReceiver extends BroadcastReceiver {
   public TransactionReceiver() { }

   @Override
   public void onReceive(Context context, Intent i) {
      Transaction t = Transaction.getByUuid(i.getStringExtra("uuid"), context);
      if (t != null) {
         t.status = i.getStringExtra("status");
         t.updateTimestamp = i.getLongExtra("update_timestamp", Utils.now());
         t.save(context);
      }
      openActivity(context, i);
   }

   private void openActivity(Context c, Intent receivedIntent) {
      i = new Intent(i);
      i.setClass(c, PurchaseDetailActivity.class);
      i.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_SINGLE_TOP);
      i.putExtra(Transaction.UUID, receivedIntent.getStringExtra("uuid");
      c.startActivity(i);
   }

Back  on our test device we need to make sure that Hover.initialize() is  called again so that it downloads our new parser. With instant run,  Android Studio often shortcuts this and prevents the update, so we are  just going to uninstall and re-install our app on our test device.  Finally we run our test purchase and wait for confirmation via SMS…

And success! We have made our first in-app purchase using mobile money.


Unlike other in-app payment systems that take up to 30%, you keep 100% of the money from these transactions. Note: Mobile money operator’s fees still apply. You pay Hover a simple monthly amount based on the total number of transactions your users make.

If you have any questions or would like to be featured in a future case study please reach out to us at support@usehover.com