Daraja Agent KitUnder the hood
Data structures, state transitions, security and scale.
Under the Hood: Data Structures and State Transitions
Every transaction within Mpesa is a stateful operation, progressing through various stages from initiation to completion or failure.
Transaction Identifiers:
OriginatorConversationID: A unique identifier generated by the business when initiating a B2C or B2B transaction. It is the primary key for tracking requests and correlating them with asynchronous callbacks.Conversation ID: A unique identifier generated by Daraja for each API interaction. It is returned in the synchronous response and included in subsequent asynchronous callbacks, allowing Safaricom to trace the lifecycle of an API request.Mpesa Transaction ID: The globally unique identifier for a completed financial transaction. It is generated only when funds are successfully moved and is the canonical reference for reconciliation.
State Transitions:
- Initiated: The transaction begins via customer action or API request.
- Pending: For business-initiated transactions, the transaction may enter a pending state while Mpesa performs internal checks.
- Validated: For C2B transactions with a
Validation URL, the transaction pauses while the business's system validates the request. - Processing: Mpesa debits the sender and credits the recipient, ensuring atomicity.
- Completed/Success: The transaction is finalized, and callbacks are sent.
- Failed: If any step fails, the transaction is marked as failed, and no funds are moved.
- Reversed: A completed transaction is undone, creating a new reversal transaction.
Security, Performance, and Scalability Considerations
Security
- API Authentication (OAuth 2.0): Daraja uses OAuth 2.0 for authentication. Businesses must obtain a short-lived access token by providing a consumer key and secret. These tokens must be securely stored and refreshed.
SecurityCredentialEncryption: For B2C and B2B transactions, theSecurityCredentialmust be encrypted using Daraja's public certificate to prevent plain-text transmission.- IP Whitelisting: Safaricom enforces IP whitelisting for both API requests and callbacks. Businesses must register their static public IP addresses with Safaricom.
- HTTPS/TLS Encryption: All communication with Daraja API endpoints occurs over HTTPS, ensuring data in transit is encrypted.
Performance
- Asynchronous Processing: Business applications must be designed to handle asynchronous callbacks. Using message queues to decouple callback reception from processing logic is a best practice.
- Rate Limiting: Businesses must implement client-side rate limiting and exponential backoff for retries to stay within Daraja's TPS limits.
- Latency: Network latency can affect the perceived speed of transactions. Hosting integration servers geographically close to Safaricom's infrastructure and optimizing network paths are recommended.
Scalability
- Callback Infrastructure: Callback endpoints must be stateless and highly scalable, deployed behind load balancers, and optimized for quick processing.
- Database Performance: Scalable database design, including appropriate indexing and query optimization, is essential for handling high volumes of transaction data.
- System Resilience: Redundancy at all levels (servers, load balancers, etc.) and designing for failure (retries, circuit breakers, dead-letter queues) are critical for maintaining service reliability.
The Mpesa ecosystem, powered by the Daraja platform, offers a sophisticated mobile money solution that has revolutionized financial transactions. A deep understanding of its core transaction types—C2B, B2C, and B2B—is a strategic imperative for any business seeking to integrate with this platform. By meticulously addressing the security, performance, and scalability considerations, businesses can build robust, efficient, and trustworthy Mpesa integrations that can handle current demands and scale for future growth. The Daraja platform acts as the bridge, but the strength and reliability of this bridge depend entirely on the foundational understanding and meticulous execution of its core transaction types.
References and Resources
- Safaricom Daraja API Documentation: The official and most authoritative source for Mpesa integration. It provides detailed API specifications, authentication guides, and examples for all transaction types.
- Safaricom Business M-PESA for Business: Information on M-PESA services tailored for businesses, including Paybill and Till numbers.
- M-PESA Paybill and Buy Goods Information: Details on how customers use these services.