While building Frappoint, this was the hardest challenge I had to overcome. Instead of defining static duration’s for every available service and provider, I needed scheduling to be “alive” to adapt whenever new services, providers, or resources were added. I wanted the system to evolve with changes instead of freezing or breaking down.

The Problem

• Services have different duration’s ( e.g., haircut (30m) vs. hair treatment (60m)).

• Providers have individual schedules and varying services they offer.

• Logical Resources to be used when offering the service (e.g., clippers, massage tables).

• Avoiding the possibility of double-booking is critical.

• Reducing manual scheduling to reduce manual errors and overhead

Traditional scheduling approaches (static tables and manual blocks) weren't flexible enough. I needed a system that could dynamically calculate availability in real-time.

Introducing Slots

The concept that helped me crack this problem was simple but powerful: slots.

Think of them as dynamic time units that combine:

1. Service Durations - Every service has a duration, which for me I went with a uniformity of minutes
2. Provider Allocation - Each provider has a timeline (e.g., Shift 9 AM - 5 PM) and a set of services they can perform.
3. Service Unit / Resources - Logical shared resource for performing the service (Clippers for haircut and such)

Combining these three we get a slot, a bookable time unit.

It defines when the service can be performed, who can perform the it and what resources are required.

These slots are then split into chunks of (10, 15, 30 mins depending on your setup) that can be combined into a single booked unit for a client. This approach ensures:

• Providers are never double-booked.
• Resources are allocated efficiently.
• Availability automatically adapts as services or providers are added or removed.

How It Works in Practice

Imagine a haircut service (30 minutes) offered by Jane and John:

Jane and John's slots are calculated dynamically, so if Jane is already booked at 9:30 that slot disappears from the list of available bookings.

Lessons Learned

Working on this feature taught me to:

• Think in units of time, not just appointments. Breaking schedules into slots to make everything more flexible.
• Separate concerns. Services, providers, and resources each have their own logic.

So let’s investigate and see what they are, how they are used and what they represent ☕️.

What are API Credentials and Why are they Important❓️

Think of it like this:

When you log in to a website e.g., Hashnode, you use your email and password.

When your app logs in to Safaricom, it uses the Consumer Key(email) and Consumer Secret(password).

These are used as security mechanisms to authenticate (identify your app) and authorize (prove that it has permission) to access the Safaricom M-Pesa services on your behalf.

In the case of Daraja API (M-Pesa), the API credentials usually include:

• Consumer Key (username/email)

• Consumer Secret (password)

They are used to:

• Authenticate your app — so safaricom knows who’s calling their services

• Get access tokens — which are temporary “passes/tickets” that let your app make secure requests

• Protect the system — only authorized apps can trigger requests e.g., STK Push.

🧪 In Sanbox (Testing):

They help you test M-Pesa operations without using real money. It’s safe for developers to experiment and build.

💵 In Production (Live):

They allow real money transactions. Since money is involved they are tightly controlled and require approval before use.

📝 Important

• Keep them secret (never share or expose them publicly).

• Store them securely (in .env variables or secret managers).

• They are per app — generate separate credentials for each shortcode/application.

🔍️ How do we Get These Credentials

1️⃣ Sign up for a Safaricom Developer Account

Whether you’re testing or going live, everything starts here:

1. Head over to https://developer.safaricom.co.ke

2. Click Sign Up (or Login if you already have an account)

3. Fill in your details — KYC (Know Your Customer) process

4. Once you’re in, you’re now officiall a Safaricom developer 🎊

2️⃣ Get Sandbox Credentials

This is the staging area, here you get to play around, test your code/app, break stuff (safely), and make sure everything works before going live.

1. In the developer portal, go to My Apps

2. Click Create a new app

3. Give your app a name e.g., My App :)

4. Create App

A new application is created and you’ll see the Consumer Key and Consumer Secret in the app.

Use these credentials to move around funds, don’t worry any money you spend on sandbox will be reimbursed.

3️⃣ Apply for Production Credentials

Now you’re confident in your integration (or no callback requests from sandbox is now getting on your nerves 😠), it’s time to go live and make real transactions.

🖐🏿 Hold your horses, confirm if you have these:

1. A registered Company

2. Registered Shortcode (Paybill or Till Number)

3. Access to M-Pesa Org Portal (will be sent to your after registering shortcode)

🟩 Confirmed the above, here’s what you need to do:

1. In the developer portal click the Go Live tab

2. You’ll be asked to provide a few things:

   • Organization Short Code

   • Organization name

   • M-Pesa Username

3. Safaricom will review your app manually — this can take a few hours to a few days.

If everything checks out, you’ll be issued Prod-App which will contain live credentials — 🤝🏾 welcome to the big leagues.

Two emails will be shared with you i.e., one containing Passkey and some information on your live application, the other containing live/prod api urls.

☝🏿One More Thing — ( Security Credentials)

For some APIs (i.e., B2C), you’ll also need to generate a Security Credential to encrypt sensitive data, which is generated from Initiator Password.

Don’t worry I got you — How to Get Initiator Name and Password

💭 Final Thoughts

• Use sandbox to test everything first — it’s a lifesaver.

• Keep your credentials secret — don’t commit them to GitHub!

• Set up a public server or tunnel (ngrok) for your callbacks during testing.

• Read the docs.

For many of you like me, getting this password feels like unlocking a secret level in a game. It's one of those security layers provided by Safaricom that isn't handed to you by default, and the steps to get it aren't always clearly documented.

Let's walk through how to understand what it is, who manages it, and how to get it -- all from the M-Pesa Org Portal.

📘Prerequisites

Before we begin, ensure you have the following:

* A registered Paybill/Till with M-Pesa

* Access to the M-Pesa Business Portal https://org.ke.m-pesa.com/

🔑 What is the Initiator Password?

\> The Initiator Password is a sensitive credential used in M-Pesa APIs that perform transactions, such as transferring funds to customers or other businesses.

It is not the same as your consumer secret (used in standard Daraja authentication) nor is it the web portal password for logging in.

The Initiator Password is: * Tied to a specific Initiator Name (a type of user/operator on your shortcode) * Used in API requests as the SecurityCredential parameter * That is after being encrypted using Safaricom's public security certificate

👤Who Is the API Operator / Initiator?

Good question. To understand this first we need to understand user roles in the M-Pesa Business Org Portal.

We'll have a look at the 3 main operators: * Business Administrator * Business Manager * Business Web Operator (API Operator)

🤵🏿 1. Business Administrator

This is the person/user who signed up for the short code. Safaricom creates this user when the shortcode is first registered.

The primary role of this user is to manage other users(operators) within the organization. * Creating and managing all other users * Assigning roles and permissions * Resetting passwords and unlocking accounts

\> They are essentially the gatekeepers of the entire M-Pesa org account.

📊 2. Business Manager

This is the user who: * Approves transactions * Monitors balances * Accesses statements.

\> He'll play a crucial part later don't forget about him.

🌐 3. Business Web Operator (API Operator / Initiator)

This is the user we are more interested in today. They are responsible for API integrations and once created, they become known as: the Initiator 👻

• Provides a layer of authentication

• Can initiate API transactions (B2C, B2B, Reversal, etc.)

• Cannot log in to the web portal (API-only access)

This Initiator Name + Password combo is what the Daraja API expects for secure operations.

🛠️ How to Get the Initiator Password.

1. Ask the Business Administrator 🤵🏿 to Log In They should go to the M-Pesa Org Portal and log in with their credentials.

2. Create two Operators (Business Manager 📊, Web Operator🌐)

• Go to Operator Management

• Create a new user with the role: Business Manager

• Assign them appropriate roles: Add them later

• Repeat the process but role is: Business Web Operator

• Assign them appropriate roles: Add them later

The Business Manager and Web Operator roles cannot belong to a single user.

Something interesting to note here is the Set Password section of the Web Operator is greyed out and the operator is in a Pending State. Weird right 🙃

3. To activate the Web API Operator

• Log in as the Business Manager

• Access the Operators tab

• Select the Web Operator

• Set the password for the Operator

The set password is now a green hue (enabled) The Business Manager is primarily responsible for setting the initiator password. Note: the password should be limited to specific special characters (#, &, %, $) other characters are not accepted as special 😏 including @

Now we have the Initiator Password. What next 🤷🏿

🔒 Encrypting the Initiator Password

Step 1: Using the Daraja Developer Portal Test Credentials:

• Select environment (Production) for live credentials

• Enter your Initiator Password

• Click Generate

• Easy peesy now you have your Security Credential

Step: 2: Using Code Download the public certificate (available on the Daraja Developer Portal) to encrypt the password.

Follow the provided guide on the Daraja Developer Portal to figure out how to encrypt it.

✅ Final Notes

• Always encrypt the Initiator Password before using it in a transaction request

• Never hardcode the raw password in your source code

• If the password is lost, the Admin must reset it via the Org Portal

🙋🏿 Still Confused?

If you're unsure whether you're using the right initiator Name, or if your password keeps giving "The Initiator information is invalid" errors -- double-check:

• The user role and permissions

• The shortcode being used

• The encryption process

You can also contact Safaricom M-Pesa Business Support via: m-pesabusiness@safaricom.co.ke

Or Safaricom API Team via: apisupport@safaricom.co.ke

References:

[1]: Daraja API portal B2C
[2]: M-Pesa Business Channels and Portals
[3]: M-Pesa Business