Safaricom MPESA ​

By default, you can accept payments in Powerlynx using the Safaricom MPESA. Safaricom MPESA is supported only in Kenya.

To set up the Safaricom MPESA integration in Powerlynx, ensure that under Config/System/Localization, you've selected Kenya as your country.

Configuration ​

In order to connect Powerlynx with your MPESA account you need to open the developers MPESA account, navigate to the Home page and find the "My Apps" section. Find the app you want to connect to Powerlynx and take these values (you'll need to insert them in the module config in Powerlynx):

You need to obtain the "Consumer key" and "Consumer secret" values from MPESA:

You will also need your shortcode — the Pay Bill number allocated to your organization, through which it receives customer payments.

Additionally, you need to know your "Lipa Na Mpesa Online Passkey."

It is recommended to reach out to MPESA API support to clarify which credentials to use with the Powerlynx app. They will provide guidance if you are unsure.

Now it's time to insert them into the corresponding fields:

You need to fill in the "Consumer Key," "Consumer Secret," "Short Code," and "Lipa Na Mpesa Online Key" with the values previously taken from your MPESA account accordingly.

In the "Environment" field, select the environment you use in your MPESA app: "Production" (the default) or "Sandbox" for testing.

Pay attention to the "Location" filter — you can configure your MPESA account as the default for the system (all locations will use this account which means all payments collected on all locations will go to this account), or you can select a specific location and link your account only with that location. Using this method, you can connect different MPESA accounts to different locations in Powerlynx.

Once all these fields are configured, press the "Apply" button to save the configuration. Next, you need to register the callback URLs for your Powerlynx account in MPESA. To do this, click the "Register" button and wait for the result. If everything went well, you should see the following result:

You should see some values for the registered URLs, and a "Re-register" button in case you ever need to register them again. Until the URLs are registered, the block reads "Registering callback URLs is required before using M-Pesa". Keep them registered: this is how Safaricom reports the M-Pesa transaction ID and your paybill balance to Powerlynx. Now we can proceed to the next step.

Enable Payment Gateway for a Location ​

The next crucial step is to enable Safaricom MPESA for a specific location. Navigate to Locations, select the desired location, and open the "Payment Gateways" tab. From there, enable Safaricom MPESA for this location:

If it's disabled, your clients will not have the option to pay with MPESA.

Buying a voucher with Safaricom MPESA ​

Now, your customers can buy a voucher on a splash page using Safaricom MPESA:

The customer doesn't leave Powerlynx to pay — the payment is approved on their phone:

1. The customer clicks the "Safaricom MPESA" option. If Powerlynx doesn't have a phone number on file for them, they are asked for their M-Pesa number first.
2. The customer sees a "payment pending" page, and Safaricom sends an M-Pesa payment prompt to their phone. The prompt shows the customer's Powerlynx customer ID as the account reference.
3. The customer enters their M-Pesa PIN. Once Safaricom confirms the payment, the pending page moves on and their internet access starts.

If Safaricom refuses to send the prompt, the customer sees an error straight away instead of the pending page. If the customer cancels the prompt or the payment fails, the payment is marked as failed with the reason Safaricom gave.

Finding an M-Pesa payment ​

Under Finance/Payments, the Description of a Safaricom MPESA payment reads M-Pesa transaction ID: … — the reference your customer quotes when asking about a payment, and the one you find in your M-Pesa portal. The payments list can be searched by it, so when a customer quotes their transaction ID, you can find the payment right away.

Opening the payment shows two more values: Field #1 holds your paybill balance after the payment (when Safaricom reported it), and Field #2 holds the checkout request ID — the reference Safaricom's API support asks for if you need to raise a question about a payment.

If Powerlynx confirmed the payment by asking Safaricom rather than from its notification, the transaction ID may not be known; the description then reads M-Pesa receipt unavailable - checkout …, naming the checkout request ID instead.

Networking: Walled Garden ​

Another crucial step is to configure the allow list of hosts on your hotspot. For instance, if you've connected a Mikrotik hotspot using this manual, you now need to add a list of allowed hosts related to Safaricom MPESA. You can find more about Mikrotik Walled Garden here.

To do this, you should access your router (in my case, Mikrotik), open the Terminal, and run this command with the list of hosts you wish to allow:

/ip hotspot walled-garden
add dst-host=*.powerlynx.app

/ip hotspot walled-garden
add dst-host=*.powerlynx.app

It might be useful to visit our forum, especially this topic, to discuss all questions related to the walled garden.