Concepts

Request-response cycle

In short: Daraja answers every request twice. First an instant "accepted", then the real result, later, at your callback URL.

Background readingThese chapters explain why Daraja works the way it does. Where they disagree with the skills, trust the skills: they are kept current and tested.

Request-Response Cycle

Building upon the transactional flow established in the previous section, where the customer’s authorization and the business’s validation logic define the initial parameters of a payment, we must now examine the underlying communication architecture that facilitates these movements. The Mpesa Daraja platform, Safaricom's developer-facing API gateway, facilitates programmatic interaction with the Mpesa mobile money ecosystem through a sophisticated request-response cycle. A fundamental aspect of integrating with Daraja is understanding its request-response cycle, which often involves both synchronous and asynchronous communication patterns. This dual-phase approach is critical for ensuring system responsiveness, transaction reliability, and scalability within a high-volume financial processing environment. This section will meticulously trace an API call from a developer's server to Safaricom and back, detailing the synchronous and asynchronous phases, defining key concepts, and grounding the explanation in real-world production contexts.

The Dual Nature of Daraja's Request-Response Cycle

When a developer's application initiates a transaction or query through the Daraja API, the interaction is not always a simple, single request-response exchange. Instead, many critical Mpesa operations, particularly those involving financial movements or external system interactions, employ a two-stage communication model: an immediate synchronous response followed by a later asynchronous callback. This design addresses the inherent complexities of distributed transaction processing, network latencies, and the need for immediate feedback on request reception while deferring the final outcome until all internal processes are complete.

Synchronous Response: Immediate Acknowledgment

A synchronous response refers to the immediate feedback an API client receives from the server after making a request. In the context of Daraja, this response is delivered over the same HTTP connection that initiated the request. Its primary purpose is to acknowledge receipt of the request and provide an initial status regarding its validity and whether it has been accepted for processing. This immediate response is crucial for the requesting application to understand if its request was syntactically correct, authenticated, and initially accepted by the Daraja gateway.

Why it exists: The synchronous response serves several vital functions. Firstly, it provides instant validation feedback. If a request is malformed, lacks proper authentication credentials, or contains invalid parameters, the Daraja API can immediately reject it and inform the client. This prevents unnecessary processing of invalid requests. Secondly, it offers an immediate confirmation that the request has reached the Daraja system and has been queued for further processing. This allows the client application to proceed without blocking indefinitely, improving user experience and system responsiveness. However, it is paramount to understand that a successful synchronous response (e.g., an "Accepted" status) does not signify the final success or failure of the underlying Mpesa transaction. It merely confirms that the request has been successfully handed over to Safaricom's internal systems for execution.

How it works step by step:

Client Initiates Request: The developer's server constructs an HTTP POST request (e.g., for an STK Push, B2C payment, or C2B Register URL) with the necessary JSON payload and authentication headers.
Request Sent to Daraja: This request is sent over the internet to the Daraja API endpoint.
Daraja Gateway Receives and Validates: The Daraja API gateway receives the request. It performs initial checks:
- Authentication: Verifies the provided access token.
- Authorization: Checks if the authenticated application has permission to perform the requested operation.
- Syntax and Schema Validation: Ensures the JSON payload conforms to the expected structure and data types.
- Basic Business Rule Validation: Performs quick checks, such as ensuring mandatory fields are present.
Immediate Response Generation: Based on these initial validations, Daraja generates a synchronous HTTP response.
- If any validation fails, an error response (e.g., HTTP 400 Bad Request, 401 Unauthorized, 403 Forbidden) is returned immediately, often with a specific error code and message.
- If all initial validations pass, Daraja returns an HTTP 200 OK status, typically with a JSON payload indicating that the request has been accepted for processing. This payload often includes a ConversationID and sometimes an OriginatorConversationID or CheckoutRequestID (for STK Push).
Client Receives Response: The developer's server receives this immediate response. The application should parse this response to determine if the request was initially accepted or rejected.

Key Identifier: ConversationID The ConversationID is a unique identifier generated by the Daraja API for each successful synchronous request. It acts as a crucial correlation token, linking the initial request made by the developer's application to the subsequent internal processing within Safaricom's systems. While the ConversationID is returned in the synchronous response, it is primarily used internally by Safaricom for tracking. For external correlation by the developer, other IDs like OriginatorConversationID (a unique ID generated by the client for their request) or CheckoutRequestID (specific to STK Push) are more commonly used to match the final asynchronous callback to the originating request. However, the ConversationID is a fundamental concept representing the unique lifecycle of a request within the Daraja ecosystem.

Asynchronous Callback: Final Transaction Status

An asynchronous callback is a mechanism where, instead of providing the final result immediately, the Daraja API initiates a separate, new HTTP request back to a pre-configured URL on the developer's server once the underlying Mpesa transaction has completed its processing. This callback delivers the definitive status of the transaction (success, failure, timeout, etc.) along with detailed transaction parameters.

Why it exists: The asynchronous callback mechanism is essential for several reasons:

Long-Running Processes: Mpesa transactions can involve multiple internal systems, network hops, and even human interaction (e.g., customer PIN entry for STK Push). These processes are not instantaneous and can take several seconds or even minutes. Holding open an HTTP connection for such durations is impractical and inefficient for both the client and the server.
Decoupling: It decouples the request initiation from the result delivery. The client doesn't need to wait actively; it can process the immediate acknowledgment and then handle the final result when it arrives.
Reliability: Callbacks are often designed with retry mechanisms. If the developer's server is temporarily unavailable when Daraja attempts to send a callback, Daraja's system will typically retry sending the notification for a defined period, enhancing delivery reliability.
Scalability: By not keeping connections open, Daraja can handle a much higher volume of concurrent requests, as resources are freed up quickly after sending the synchronous acknowledgment.

How it works step by step:

Internal Processing: After sending the synchronous response, Daraja's internal systems proceed to execute the requested Mpesa transaction. This might involve:
- Queueing the request for processing by the Mpesa core system.
- Interacting with customer accounts (debiting/crediting).
- Sending notifications to end-users (e.g., STK Push prompt).
- Waiting for user input (e.g., PIN entry).
- Updating transaction ledgers.
Transaction Completion: Once the Mpesa transaction reaches a final state (success, failure, cancellation, timeout), Daraja's backend system prepares the final transaction details.
Callback Request Generation: Daraja constructs an HTTP POST request containing the final transaction status and details in a JSON payload.
Callback Sent to Developer's URL: This request is sent to the callback URL (also known as a validation URL or confirmation URL, depending on the API call) that the developer configured when initiating the transaction or registering their service.
Developer Server Receives Callback: The developer's server, acting as a webhook receiver, listens for incoming POST requests on the specified callback URL.
Developer Server Processes Callback: The application on the developer's server:
- Receives the JSON payload.
- Parses the transaction details (e.g., ResultCode, ResultDesc, TransactionID, Amount, MSISDN).
- Uses a correlation ID (like CheckoutRequestID for STK Push or OriginatorConversationID for B2C/C2B) to match this callback to the original request initiated by the application.
- Updates its internal database with the final transaction status.
- Responds to Daraja with an HTTP 200 OK status to acknowledge successful receipt of the callback. If the developer's server responds with anything other than 200 OK, Daraja might retry sending the callback.

The Dual Nature of Daraja's Request-Response Cycle

Synchronous Response: Immediate Acknowledgment

How it works step by step:

Client Initiates Request: The developer's server constructs an HTTP POST request (e.g., for an STK Push, B2C payment, or C2B Register URL) with the necessary JSON payload and authentication headers.

Request Sent to Daraja: This request is sent over the internet to the Daraja API endpoint.

Daraja Gateway Receives and Validates: The Daraja API gateway receives the request. It performs initial checks:

Authentication: Verifies the provided access token.
Authorization: Checks if the authenticated application has permission to perform the requested operation.
Syntax and Schema Validation: Ensures the JSON payload conforms to the expected structure and data types.
Basic Business Rule Validation: Performs quick checks, such as ensuring mandatory fields are present.

Immediate Response Generation: Based on these initial validations, Daraja generates a synchronous HTTP response.

If any validation fails, an error response (e.g., HTTP 400 Bad Request, 401 Unauthorized, 403 Forbidden) is returned immediately, often with a specific error code and message.
If all initial validations pass, Daraja returns an HTTP 200 OK status, typically with a JSON payload indicating that the request has been accepted for processing. This payload often includes a ConversationID and sometimes an OriginatorConversationID or CheckoutRequestID (for STK Push).

Client Receives Response: The developer's server receives this immediate response. The application should parse this response to determine if the request was initially accepted or rejected.

Asynchronous Callback: Final Transaction Status

Why it exists: The asynchronous callback mechanism is essential for several reasons:

Long-Running Processes: Mpesa transactions can involve multiple internal systems, network hops, and even human interaction (e.g., customer PIN entry for STK Push). These processes are not instantaneous and can take several seconds or even minutes. Holding open an HTTP connection for such durations is impractical and inefficient for both the client and the server.

Decoupling: It decouples the request initiation from the result delivery. The client doesn't need to wait actively; it can process the immediate acknowledgment and then handle the final result when it arrives.

Reliability: Callbacks are often designed with retry mechanisms. If the developer's server is temporarily unavailable when Daraja attempts to send a callback, Daraja's system will typically retry sending the notification for a defined period, enhancing delivery reliability.

Scalability: By not keeping connections open, Daraja can handle a much higher volume of concurrent requests, as resources are freed up quickly after sending the synchronous acknowledgment.

How it works step by step:

Internal Processing: After sending the synchronous response, Daraja's internal systems proceed to execute the requested Mpesa transaction. This might involve:

Queueing the request for processing by the Mpesa core system.
Interacting with customer accounts (debiting/crediting).
Sending notifications to end-users (e.g., STK Push prompt).
Waiting for user input (e.g., PIN entry).
Updating transaction ledgers.

Transaction Completion: Once the Mpesa transaction reaches a final state (success, failure, cancellation, timeout), Daraja's backend system prepares the final transaction details.

Callback Request Generation: Daraja constructs an HTTP POST request containing the final transaction status and details in a JSON payload.

Callback Sent to Developer's URL: This request is sent to the callback URL (also known as a validation URL or confirmation URL, depending on the API call) that the developer configured when initiating the transaction or registering their service.

Developer Server Receives Callback: The developer's server, acting as a webhook receiver, listens for incoming POST requests on the specified callback URL.

Developer Server Processes Callback: The application on the developer's server:

Receives the JSON payload.
Parses the transaction details (e.g., ResultCode, ResultDesc, TransactionID, Amount, MSISDN).
Uses a correlation ID (like CheckoutRequestID for STK Push or OriginatorConversationID for B2C/C2B) to match this callback to the original request initiated by the application.
Updates its internal database with the final transaction status.
Responds to Daraja with an HTTP 200 OK status to acknowledge successful receipt of the callback. If the developer's server responds with anything other than 200 OK, Daraja might retry sending the callback.