¶ Safaricom M-PESA
- Overview
- Installation
- Settings
- Payment process
- Safaricom M-PESA account
- M-PESA web portal
- Logs
- Troubleshoot
¶ Overview
Safaricom M-PESA is a Splynx add-on which allows customers to pay via Safaricom platform.
¶ Installation
The add-on can be installed in two methods: via the CLI or the Web UI of your Splynx server.
To install the Safaricom M-PESA add-on via CLI, the following commands can be used:
sudo apt-get update
sudo apt-get install splynx-safaricom-mpesa
To install it via the Web UI:
Navigate to Config → Integrations → Add-ons:
Locate or search for the splynx-safaricom-mpesa add-on and click on the Install icon in the Actions column, you be presented with a window to confirm or cancel the installation. Click on the OK, confirm button to begin the installation process:
¶ Settings
After the installation process has completed, you should configure the add-on.
Navigate to Config → Integrations → Modules list:
Locate or search for the splynx_addon_safaricom_mpesa item and click on the
(Edit) icon in the Actions column:
The general configuration of the Safaricom M-PESA integration module can be viewed and edited here. Double check if Entry points status for portal option is enabled and API domain (with the last slash) value is set correctly. API key, API secret - the default auto-generated values. Do not change this unless entirely necessary.
- Mpesa credentials: Consumer Key/Secret, Short code, Lipa Na Mpesa Online Passkey and (Initiator) Security Credential - please register your M-PESA account. After registration, you can obtain these values from MPESA.
Common settings:
- Splynx url - the URL of your Splynx server (without the last slash);
- Payment method ID - select the payment method for payments that will be made. By default the new method will be created - M-PESA Paybill;
- Search customer by - what field (Invoice number, Login) will be used to search for the customer in Splynx (during payment);
- Check Debt amount - the toggle allows to enable/disable to check whether the payment amount is sufficient for paying the debt. If enabled and the customer's account balance is less than 0, the payment amount must be equal to or larger than the customer's debt;
- Minimum payment amount - Minimum payment's amount (no less than 0). The payment amount must be larger than this value;
- Payment statement grouping - Group of payment statements by (
Finance → Payment Statements → History)MonthorDay'; - Convert received funds to USD - convert received payment from MPESA (Kenyan shilling) to USD. Enable if you use USD currency in Splynx;
- USD to KES exchange rate - the current Splynx internal dollar exchange rate of the KES;
- Create payment on - you can create a payment on Validation, Confirmation, Validation/Confirmation or both. Some options should be used with care as they can process payments without confirmation from MPESA.
The configuration of add-on Entry points can be found in Config → Integrations → Modules list, next to the splynx_addon_safaricom_mpesa module item in the Actions column.
Click on the 
(Edit entry points) icon. More information about the Modules list can be found here.
By using Entry points, you can enable add-on features which can allow customers to pay for (proforma) invoices, add money to the balance from the Dashboard etc.
Register your URLs under Config → Integrations → Safaricom M-PESA after successfully configuring the add-on:
¶ Payment process
In this example, the customer pays via SIM menu
- Business no. – MPESA short code (Paybill Number). This is the same value as
Config → Integrations → Safaricom M-PESA → Short code.
- Account no. – the value that will be sent to Splynx, it depends on the item (Invoice number, M-PESA Phone, Login) which can be selected in
Config → Integrations → Safaricom M-PESA → Search customer by. According to this value, the customer will be found.
After making a payment, the customer receives an SMS:
All customer personal information related to their bank account is stored encrypted in the database.
Their payments will appear in Splynx:
The customer can pay from the Customer Portal with confirmation on cell phone under Finance → Documents or from the Dashboard under the Unpaid invoices section:
You can also top up the balance from the Dashboard:
¶ Safaricom M-PESA account
Paybill Application
Here are the requirements to use Paybill - https://www.safaricom.co.ke/personal/m-pesa/lipa-na-m-pesa/paybill
NOTE: Splynx supports only the Paybill option as the payment option and does not support a Till Number.
After the Paybill application and approval, you need a developers' account from the official M-Pesa Daraja Portal in order to integrate the customers to the business API (Customer to Business - C2B).
Daraja Portal
This is the official M-Pesa Portal that is used to host your application. You need to register an account either as an individual or as a company. Follow this link to sign up on the Portal.
Create a test app in Sandbox
Sandbox is a testing environment. You can use it to test your app before going to production.
The Safaricom M-PESA add-on uses a C2B API. Documentation gives a brief description how to test this C2B API- https://developer.safaricom.co.ke/docs.
Create an app by adding the app name and select product (C2B).
The App contains the following tabs:
- Keys – add-on configuration requires a Consumer Key and Secret from this tab;
- Products – shows the approval status of your application API products.
- Details – the details tab gives you a summary of your app and the terms and conditions.
The sandbox app is just used to test API calls, made for each different scenario. Test results are put into test case documents, which are excel documents that can be downloaded from the M-PESA portal.
(Safaricom doesn’t really validate these test cases but it’s important to fill in “Success” results for Authentication, c2b simulation, registering callbacks and reversal)
Production mode
This step involves moving your application into production.
- After the on-going process, a new app is created with new credentials.
- We use these live credentials to configure the M-PESA add-on in Splynx.
- Note that after add-on module configuration for production mode, Splynx will register your callback URLs automatically.
Requirements:
-
Test cases results – this is an excel document with results from your test scenarios.
-
Shortcode – this is the Paybill number you are using.
-
Business Admin/business manager – these are admin users, with Business Administrator or Business Manager roles on the M-PESA portal.
Operator
¶ M-PESA web portal
This is another M-PESA portal, where your app is hosted. It can be found on the website - https://org.ke.m-pesa.com.
Note: From 30th September 2021, Safaricom discontinues the need for installation of an M-PESA digital certificate on the computers as a requirement to access the M-PESA organization portal. This would be replaced with a 6-digit One Time Password (OTP), for each user login that has been in use and confirmed to provide additional security over the user’s password by ensuring that only authorized users can log in. This decision was made to retire the Internet Explorer which is coming to the end of its life and is the only browser that supports certificates.
From now henceforth, no new certificates will be issued. The expired ones will not be renewed either.
¶ Logs
M-PESA add-on logs can be found in Administration → Logs:
In M-PESA Logs the full payment statistic records can be viewed:
¶ Troubleshoot
Important
-
any request made to M-Pesa support team should be sent via the email used in the Paybill application process;
-
M-Pesa will not take into action any request sent to them without verifying ownership of the Paybill Number;
-
every Email sent must include the Paybill Number and Organization Name as registered during application.
Requests to M-PESA support team
External Validation
-
External Validation is disabled by default; this means that M-Pesa is incharge of validating all payments requests to your Paybill.
-
M-Pesa servers will accept any payments request, as long as the MSISDN (phone number) is allowed to use M-Pesa services.
-
This means that no transaction details are sent to the Splynx server.
-
To enable external Validation, you are required to send a request to m-pesabusiness@safaricom.co.ke. The email letter should be sent from the email address used to create the account on the Daraja Portal.
Business manager / administrator
-
To create a Business Manager / administrator you need a logging credentials to access https://org.ke.m-pesa.com.
-
It is required to send an email to M-Pesa support requesting creation of a System admin.
-
The Email should be in form of a scanned letter on the company letter head, signed by two signatories and bearing the organization stamp.
-
Also attach the administrator’s scanned ID copy on both sides.
-
The letter should have the following details:
-
Organization Name
-
Organization Short code
-
First Name
-
Middle Name
-
Last Name
-
Id type (National Id, passport)
-
Id/pp Number
-
Nationality
-
Date of Birth
-
Phone number
-
Administrators User Name
-
Email
The request should be sent to m-pesabusiness@safaricom.co.ke.
Re-registering callbacks
-
After URL registration, it’s important to note that you cannot re-register new ones without deleting the previous.
-
Since there is no API to delete callback URLs, you are required to write an official letter to M-PESA support team requesting them to delete the URLs.
-
The letter should be on the company letter head and should include:
-
Old URLs you want to delete
-
The new URLs you need to register
-
Shortcode – Paybill Number
Please send your request to m-pesabusiness@safaricom.co.ke.