๐Ÿ”How to Get Your Daraja API Initiator Password

Coiled CoderCoiled Coder
4 min read

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.

  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 ๐Ÿ™ƒ

  1. 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

0
Subscribe to my newsletter

Read articles from Coiled Coder directly inside your inbox. Subscribe to the newsletter, and don't miss out.

Written by

Coiled Coder
Coiled Coder