๐How to Get Your Daraja API Initiator Password

If you're integrating Safaricom M-Pesa's Daraja API for (B2C, B2B, Transaction Status, Reversals) you'll need an Initiator Password.
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.
Ask the Business Administrator ๐คต๐ฟ to Log In They should go to the M-Pesa Org Portal and log in with their credentials.
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 ๐
- 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
Subscribe to my newsletter
Read articles from Coiled Coder directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
