Automate any USSD Service on Android

Part II: Use the Result of a USSD Session in Your App

Note: This is the second half of a two part example. We recommend you check out part one first, especially if you’re just getting started with Hover.

In part one we looked at how to automate a USSD Send Money transaction with the Hover SDK. For many types of USSD sessions, especially a financial transaction like Send Money, you also want to know whether or not the payment was successful, and to access details like the confirmation number and amount paid. In this post we’ll explore how to use Hover’s parsers to access important details from a confirmation SMS message.

What are Hover parsers?
Many mobile operators including Vodacom Tanzania send confirmation details asynchronously in an SMS message, like this:

A typical confirmation SMS for a Send Money transaction

Parsers allow the SDK to structure this information and make it available to your app. Instead of asking your users to pay and send you a confirmation code, you can match users and transactions from within your app.

Create a new parser
From the Hover dashboard:

1. Click on your action and then click “NEW PARSER”.
2. Select the status you want the SDK to automatically assign to transactions that receive this particular confirmation message. You can choose from Successful, Failed, or Pending.
3. Name the category for this type of message, e.g. “Insufficient balance”, or “Incorrect PIN”.
4. Select whether the message is a USSD message or SMS.

Now we’ll write a Java regular expression that will match the SMS text, and use named capturing groups to identify the values we care about. Let’s look more carefully at a sample confirmation message (with some sensitive data removed):

5JC4XXXXXXX Confirmed. Tsh100,000.00 sent to 255765555555 - USER NAME on 12/10/18 at 4:15 PM. New M-Pesa balance is Tsh14,500.00.

For the purposes of this example, let’s say we want to access the confirmation code, amount paid, and user’s balance from this SMS. First we write regular expressions for each of the strings we want:

1. The confirmation code is an 11 character string that could be capital letters or digits: [A-Z,0–9]{11}
2. The amount and balance can each be any combination of digits, commas and dots: [0–9\,\.]+

Then we write a single regular expression that matches the confirmation SMS, and use our two regex above in named capturing groups:

(?<confirmCode>[A-Z,0-9]{11})\sConfirmed\.\sTsh(?<amount>[0-9\,\.]+)\ssent.*M-Pesa\sbalance\sis[\s]*Tsh(?<balance>[0-9\,\.]+)[\.]

Notice that we use valid Java identifiers for named groups — this will be important in the next step. It’s often helpful to copy the exact text of the confirmation SMS into a Java regular expression tester (at Hover we like Regex Planet), but any Java-compatible regex editor should work.

Paste this regular expression into the “Regex” field of your new parser. For “SMS Sender’s Number”, enter the sender ID exactly as it appears on a phone, here “M-PESA”. Click save, then head back to your IDE. You can read more about Hover parsers and regular expressions in the docs.

3. Use the parsed result
Finally, we’ll implement a BroadcastReceiver to access the data we’ve parsed from the SMS. First add the receiver to your Android Manifest:

<receiver
     android:name=".TransactionReceiver"
     android:enabled="true"
     android:exported="false">
     <intent-filter>
         <action 
          android:name="your.package.name.CONFIRMED_TRANSACTION"/>
     </intent-filter>
</receiver>

Then create the receiver:

public class TransactionReceiver extends BroadcastReceiver {
  public TransactionReceiver() { }
@Override
  public void onReceive(Context context, Intent intent) {
    String uuid = intent.getStringExtra("uuid");
    if (intent.hasExtra("transaction_extras")) {
      HashMap t_extras = (HashMap)intent
        .getSerializableExtra("transaction_extras");
      if (t_extras.containsKey("confirmCode"))
        String confirmationCode = t_extras.get("confirmCode");
      if (t_extras.containsKey("amount"))
        String confirmationCode = t_extras.get("amount");    
      if (t_extras.containsKey("balance"))
         String balance = t_extras.get("balance");
    }
  }
}

When an incoming SMS matches the regular expression and sender ID from the parser in the previous step, the TransactionReceiver receives an intent broadcast by the Hover SDK. This intent contains several useful extras, including a serialized HashMap extra called transaction_extras. Each key in the HashMap is one of the named capturing groups in the regular expression above. You can use this information to confirm a transaction and update your user, confirm a purchase, or do any other business logic.

A successful match also means that the status of the transaction will change from “pending” to “confirmed” in the Hover dashboard. See the docs for more information, including the full list of extras sent to the TransactionReceiver.

If you’ve read this far you understand how to automate a USSD session with Hover, and then use data from the result in your app’s code. Regular expressions can be cumbersome and not every Hover app needs parsers, but they can help you access session details that aren’t otherwise available programmatically. We’re excited to allow developers to maintain end to end control over the user interface of an app, even when integrating services that are only available via USSD.

Don’t have a Hover account? Sign up and get started for free.