A (relatively) Deep Dive into the Inner Workings of the popular M-Pesa Payment System in Kenya

1. M-Pesa System
&
Daraja APIs
A (Relatively) Deep Dive into
the Inner Workings
#AndelaWorkshop – 7th Nov. 2018

2. Mpesa ‘Logical Division’
MPesa
Identities
Access
Channels
Transaction
Types
Roles and
Permissions
Others

3. Identity Types
Identity Types
Service
Provider
Organizations
Agencies
Subscriber
• SP (Service Provider)
• System owner

4. Identity Types
Identity Types
Service
Provider
Organizations
Agencies
Subscriber
• Organizations (Merchants)
• Represents all business
identities having an account
on the system doing business
with the SP
• Identified by a 5-10 digit
shortcode (generally called
paybill) and an
organization/business name
• Can have child identities
under it, namely:
• Child paybills
• Till numbers

5. Identity Types
Identity Types
Service
Provider
Organizations
Agencies
Subscriber
• Agencies
• Represents Agents doing
business for the SP
• Also identified by a
shortcode

6. Identity Types
Identity Types
Service
Provider
Organizations
Agencies
Subscriber
• Subscribers
• Represents individual
customers on the system
• Identified by unique
MSISDNs/Phone numbers on
the system

7. Operator Types
User Types
SP Operator
Organization
Operator
Agents
Customer
• SP Operators
• Overall Lords of the
system

8. User Types
User Types
SP Operator
Organization
Operator
Agents
Customer
• Organization
Operators
• Unique per Organization
• Identified by a username
• Have control over
aspects of their
respective organization
only
• Capabilities are limited
to the roles assigned to
them

9. User Types
User Types
SP Operator
Organization
Operator
Agents
Customer
• Customers
• Unique system-wide
• Identified by the phone
number

10. Access Channels
Access
Channels
Web Handset API

11. Permissions, Roles
• Permissions determine all the possible operations on given
aspects of the system i.e. users, actions, transactions and
configurations.
• They follow the RBAC approach of access control
• Some permissions include:
o Viewing transactions
o Executing new transactions
o Reversal of transactions
o Creating users
o Disabling users
o Changing user details

12. Permissions, Roles
• Roles are groupings of permissions designed to
enable specific functionality for a specific user on
the system
• A user can have more than one role on a system
• Some roles are mutually exclusive i.e. cannot be
assigned to the same user at the same time
• Each role is tied to a specific Access channel
• Web roles cannot perform API requests and API
roles cannot log into the web portal
• Roles can be combined to overcome the above
restrictions (not recommended)

13. Permissions, Roles
• Well-known roles include:
o Business Administrator
o Business Manager
o Business Web Operator
o Set Org API Password
o Org Reversals Initiator
o Org B2C API Initiator
o Balance Query Org API
o Org B2B API Initiator

14. Transaction Types
Transaction
Types
Services
Command
IDs
Products
• Transaction Types are the actual
transaction flows possible on the system
• Transaction types are combined with the
business rules to control what transactions
are allowed for 3rd parties and how they are
executed
• All Services are derived from the transaction
types provided by the system
• Services are the main part of the business
rules. They determine why, how and who
will perform transactions and actions, and
how the money flows in the system
• You can only access Services granted by
the product assigned to your shortcode
• Access to Services is also limited by the role
assigned to the user, who must have
necessary permissions to use that Service

15. Transaction Types Cont’d
Transaction
Types
Services
Command
IDs
Products
• Products are the grouping of related Services
for a specific business case. These are part of
the business rules
• Products are assigned depending on business
use case, the main factor being the client
paying the business
• Most commonly known products are:
o Paybill Head Office
o Paybill Store
o Merchant Head Office Product
o Merchant Store
o Merchant Till
o Agent Products*
• Multiple services are reusable across products
• Command IDs are the unique identifiers for
Services for the API channel
• M-Pesa APIs are modeled after the Services,
and accessed via the Handset or API channels

16. M-Pesa Broker
• This is the primary interface between M-Pesa and the
world
• All access to M-Pesa from 3rd parties is via this system
• It is a SOAP/XML-based API (for tight security and strict
controls)
• Is the primary interface for the previous M-Pesa API
version
• Access depends on use-case:
o For transactions sourced from 3rd party to Safaricom, a VPN Tunnel is required
o For transactions sourced from Safaricom to 3rd Party, only a whitelist is required
• Main functions include:
o Store callback URLs for C2B transactions for registered clients
o Access control for all 3rd Party API callers
o Authenticate 3rd Party API callers

17. M-Pesa Accounts
Accounts
MMF/Working
A/C
Utility A/C
Float A/C Merchant A/C
Charges Paid
A/C
• MMF Account: typically
used for outgoing/debit
cash
• Utility: used for
incoming/credit cash
• Float: used by agents for
both debit and credit
cash
• Merchant: used by till
numbers for incoming
cash
• Charges Paid: used for all
charges to SP for all
transactions

18. M-Pesa Transaction
Flows
Transaction
Flows
Generic/B2C/B2B C2B STK Push

19. Resources
• Tutorial:
https://peternjeru.co.ke/safdaraja/ui/
• Developer Docs:
https://developer.safaricom.co.ke/docs
• Telegram: https://t.me/payments_api
• Slides:
o SpeakerDeck: https://speakerdeck.com/pmnjeru/m-pesa-system
o SlideShare: https://www.slideshare.net/secret/DTjyB654r1SJGs

20. Questions..?