Developer APIs provided by services like Stripe and PayPal make it easy for online services to accept payments via credit cards and bank accounts, but not via mobile money systems like M-Pesa. Some mobile money systems may offer their own APIs, while others don’t have developer APIs at all, or have APIs that are only available for large businesses.
If you want to accept payments from a mobile money system and there’s no API available, you can scrape the SMS receipts. There are just three easy steps:
- Forward SMS receipts from your phone to your server
- Extract the relevant data from the SMS receipt
- Match the payment with the correct user and credit their account
1. Forward SMS receipts from your phone to your server
When anyone sends you a mobile money payment, the mobile network will send your phone a SMS receipt. Your online service needs this receipt to know that someone has paid you.
To forward SMS receipts from your phone to your server, you can use the Telerivet Gateway Android app together with the Telerivet Webhook API.
If you don’t have an Android phone already, get an Android phone and install the SIM card associated with your mobile money account. Then install the Telerivet Gateway Android app on your phone. Finally, configure the Webhook API to forward incoming SMS messages to a URL on your server.
Of course, this method requires your business to have a presence in the country where you’re accepting payments – it doesn’t help accept or transmit mobile payments internationally, since your business still needs to register for a mobile money account, and the funds stay in the mobile money account until you withdraw them.
2. Extract the relevant data from the SMS receipt
Each mobile money system uses a different format for their SMS receipts.
Here’s an anonymized example receipt (in Swahili) from Tigo Pesa in Tanzania:
Tigopesa: Salio jipya ni Tsh 67,676. Umepokea Tsh 16,000 kutoka kwa JOHN SMITH, 0730000000. 06/10/2014 11:59 AM, kumbukumbu no. PP141006.1159.B00001. Tigo Pesa inakulipa mteja wake faida kulingana na wastani wa salio lako la kila siku. Faida nyingine italipwa mwezi wa 10, 2014. Pata zaidi na Tigo Pesa TU.
It contains several pieces of data:
Current Balance: Tsh 67,676
Amount Received: Tsh 16,000
Payee Name: John Smith
Payee Phone Number: 0730000000
Transaction Time: 6 October 2014, 11:59 AM (East Africa Time)
Transaction ID: PP141006.1159.B00001
In order for your online service to process a user’s payment, the most important information is the amount received and the transaction ID.
Extracting this information will likely involve writing regular expressions to match the particular format of SMS receipts generated by the mobile money service.
In the case of receiving funds via Tigo Pesa, we first make sure to only consider SMS messages from the sender ID “Tigopesa”.
(You may want to test if your mobile network allows other people to send spoofed SMS messages with the same the sender ID as their mobile money system. If so, you could prevent spoofed SMS receipts by keeping track of your current balance, and verifying that the balance in the SMS receipt is correct.)
To extract the amount received, we can use this regular expression:
Umepokea\W+Tsh\W*([\d\,\.]*\d)
Note: You may also want to take special care to avoid letting someone falsify their payment amount by changing their registered name to “Umepokea Tsh 1,000,000”.
To extract the transaction ID, we can use this regular expression:
kumbukumbu no\W+(\w{8}\.\d{4}\.\w{5,}\b)
While SMS receipt formats are typically relatively stable, mobile money systems sometimes change the format or wording of the receipts.
At this point, your service still doesn’t know which user account should be credited for the payment. (You might be able to figure it out from the payee name and phone number, but that’s unreliable.)
Instead, just store the transaction ID and payment amount in your database, so that it’s available in the next step.
3. Match the payment with the correct user and credit their account
Finally, you need to match the receipt with the correct user of your online service, so you can credit the correct account.
Some mobile money systems, including Tigo Pesa, have systems for businesses that allow customers to enter a reference number for their account when sending a bill payment. But this type of bill payment system is sometimes only available to large businesses. When someone sends money to your phone number, they probably won’t be able to send a reference number.
In this case, you can simply prompt the user to enter the transaction ID in your application, like in the example below:
The customer knows this transaction ID because the mobile money system sent the customer their own SMS receipt containing the same transaction ID:
Tigopesa: Salio jipya ni Tsh 118,006. Hamisho la fedha kwenda kwa EXAMPLE INC limekamilika; 0731110000; Kiasi Tsh. 16,000; Ada Tsh. 350;kumbukumbu no. PP141006.1159.B00001. Tigo Pesa inakulipa mteja wake faida kulingana na wastani wa salio lako la kila siku. Faida nyingine italipwa mwezi wa 10, 2014. Pata zaidi na Tigo Pesa TU.
When the customer enters a transaction ID in your application, your application can check your database for that transaction ID. If it matches, then credit the user with the payment amount associated with that transaction ID. (Be sure to prevent people from reusing the same transaction ID multiple times.)
If the customer enters a transaction ID that doesn’t match your database, it could be because you haven’t received the SMS receipt yet, or because the customer made a typo (often it can be hard to tell the difference between the digit zero and the letter O, or the letters I and L and the digit 1).
In this case, we suggest storing the transaction ID entered by the customer in your database and notifying someone on your team to look into the transaction. If there was a typo, you can record the payment manually; if the receipt was delayed, your system can process the payment manually whenever the receipt is received.