Documentation

Understanding M-PESA Shortcodes

Learn about Head Office Shortcodes, Paybill numbers, and Till numbers

What is a Head Office Shortcode?

The Head Office (HO) Shortcode is the primary shortcode registered with Safaricom for your M-PESA business account. It serves as the parent identifier for your payment collection setup on the Daraja API.

Paybill Numbers

For Paybill numbers, the Head Office Shortcode and the Paybill number are the same. When you register a Paybill with Safaricom, the number you receive (e.g., 123456) is both:

The Head Office Shortcode (used for API configuration)
The customer-facing Paybill number (what customers use to pay)

Till Numbers

For Till numbers, the Head Office Shortcode and Till number are different. A Till setup consists of:

Head Office Shortcode: The parent shortcode assigned to your organization (e.g., 5000000). This is used for API configuration and is not visible to customers.
Till Number: The customer-facing number (e.g., 123456) that customers use when making payments via "Buy Goods and Services".

When configuring a Till in InvoiceIQ, you need to provide both the Head Office Shortcode and the Till Number so that payments can be correctly processed and reconciled.

Daraja Setup Guide

How to go live with your M-PESA shortcode

To take your shortcode live on the Safaricom Daraja API, you must have a registered Safaricom Paybill or Till number, and a Safaricom M-Pesa organization portal account. The process involves two main stages: preparation and submitting the "Go Live" request on the Daraja Portal.

Prerequisites

Active Paybill/Till Number: You must have a registered M-Pesa Paybill or Till number from Safaricom.
M-Pesa Organization Portal Access: You need an administrator account with a "Business Manager" role on the M-Pesa Organization Portal.

Go Live Steps

Log in to the Daraja Portal: Access your account on the Safaricom Developer Portal.
Navigate to "Go Live": Click on the "Go Live" option in the side-menu.
Fill in Organization Details: A form will appear where you must provide your organization's information.
- Verification Type: Select "Shortcode".
- Organization Shortcode: Enter your actual Paybill or Till number.
- Organization Name: Enter the exact name of your registered company as it appears on the M-Pesa Organization Portal (it is sometimes best to use a single word version if the official name has spaces, as per some reports).
- M-Pesa User Name: Enter the username of the M-Pesa Organization Portal user with the Business Manager role that was sent to your email during the admin creation process. The email address used by Safaricom is M-PESABusiness@safaricom.co.ke. If you have not received this email from them, reach out to them for more information as to why.
- Accept Terms and Conditions: Read and agree to the terms and conditions.
- Enter OTP: An OTP (One-Time Password) will be sent to the contact number associated with the Business Manager user on the organization portal. Enter this OTP to verify your request.
- Receive Live Credentials: Once your application is reviewed and approved by Safaricom (usually within 1-3 working days), you will receive new production credentials via email. These include:
  - A new Consumer Key and Consumer Secret for your live app.
  - A live Passkey (for STK Push).

← Back to onboarding