C2B, B2C and B2B flows

Core Transaction Types

Building upon the centralized API Gateway architecture discussed in the preceding section, we now transition to the functional layer of the Mpesa ecosystem: the core transaction types. While the API Gateway provides the infrastructure for secure communication, the operational integrity of any integration depends on a granular understanding of how funds move between participants—specifically, the distinction between customer-initiated and business-initiated flows. This section provides a comprehensive technical breakdown of these transaction types, their underlying state machines, and the operational requirements for successful implementation.

The Mpesa ecosystem categorizes transactions primarily based on the origin and destination of funds, specifically whether the participants are individual customers or registered businesses. This classification simplifies the design of financial services and ensures appropriate regulatory oversight and operational procedures for each type of interaction. The three fundamental transaction types are:

1. C2B (Customer-to-Business): Transactions where an individual Mpesa subscriber initiates a payment to a registered business. These are typically payments for goods, services, or bills.
2. B2C (Business-to-Customer): Transactions where a registered business initiates a disbursement of funds to an individual Mpesa subscriber. These often involve payroll, refunds, or promotional payouts.
3. B2B (Business-to-Business): Transactions where a registered business initiates a payment to another registered business within the Mpesa ecosystem. These are common for supplier payments, inter-company transfers, or distributor settlements.

Each of these transaction types serves distinct purposes and is governed by specific operational flows and API endpoints within the Daraja platform. Understanding these differences is not merely an academic exercise; it directly impacts the choice of integration method, the security considerations, and the reconciliation processes for any business operating with Mpesa.

C2B (Customer-to-Business) Transaction Flow

A Customer-to-Business (C2B) transaction in the Mpesa ecosystem refers to any financial transfer initiated by an individual Mpesa subscriber (the customer) with the intent of paying a registered business for goods, services, or obligations. The customer uses their Mpesa mobile menu or a business-triggered prompt to send funds directly from their Mpesa wallet to the business's Mpesa account.

The primary purpose of C2B transactions is to provide businesses with a convenient, secure, and widely accessible method for collecting payments from their customers. Before Mpesa, many transactions in Kenya and similar markets were cash-based, posing risks related to security, reconciliation, and accessibility, especially in rural areas. C2B mechanisms address these challenges by:

• Enhancing Convenience: Customers can pay anytime, anywhere, using their mobile phones, eliminating the need for physical cash or bank visits.
• Improving Security: Reduces the risk of theft associated with handling large amounts of cash.
• Streamlining Reconciliation: Digital records of transactions simplify accounting and auditing processes for businesses.
• Expanding Market Reach: Enables businesses to serve customers who may not have traditional bank accounts but possess mobile phones.

Within the Mpesa framework, there are two primary mechanisms for facilitating C2B payments, each designed for slightly different business contexts: Paybill and Buy Goods (Till Number).

1. Paybill

A Paybill number is a unique identifier assigned to businesses, organizations, or institutions that allows their customers to make payments directly into their Mpesa account. Paybill numbers are typically used for recurring payments, utility bills, school fees, rent, donations, and other structured payments where an "account number" or "reference" is often required to identify the specific customer or invoice.

The customer initiation flow for Paybill is as follows:

1. Customer Accesses Mpesa Menu: The customer navigates to the Mpesa menu on their mobile phone.
2. Selects "Lipa na Mpesa": This option, meaning "Pay with Mpesa" in Swahili, leads to payment services.
3. Chooses "Paybill": The customer selects the Paybill option.
4. Enters Business Number: The customer inputs the unique 6-digit Paybill number provided by the business (e.g., for an electricity company, a school, or a landlord).
5. Enters Account Number: Crucially, the customer then enters an "Account Number." This field is vital for the business to identify the specific customer or purpose of the payment (e.g., electricity meter number, student admission number, tenant ID, invoice number).
6. Enters Amount: The customer specifies the amount they wish to pay.
7. Enters Mpesa PIN: The customer enters their confidential Mpesa Personal Identification Number (PIN) to authorize the transaction.
8. Confirmation: Mpesa processes the transaction. The customer receives an SMS confirmation from Mpesa, and the business receives a notification (via SMS and/or Daraja API callback).

While the customer initiates the transaction via their phone, businesses integrate with the Daraja API to receive real-time notifications and to offer a more streamlined payment experience. Businesses register a Validation URL and a Confirmation URL with Safaricom via the C2B Register URL endpoint. The Validation URL is an endpoint on the business's server that Mpesa calls before completing a C2B transaction. This allows the business to validate the transaction details (e.g., check if the account number is valid, if the amount is correct for a specific bill). The business can accept or reject the transaction at this stage. This is a synchronous call. The Confirmation URL is an endpoint that Mpesa calls after a C2B transaction has been successfully completed. This provides the business with the final transaction details, including the Mpesa Transaction ID, amount, sender's phone number, and the account number provided by the customer. This is an asynchronous callback.

STK Push (Sim Tool Kit Push) is a business-triggered mechanism that prompts the customer to complete a C2B transaction. Instead of the customer navigating through the Mpesa menu, the business's application (e.g., an e-commerce website, a mobile app) initiates an STK Push request via the Daraja API. The flow is:

1. The customer selects Mpesa as a payment option on a business's platform.
2. The business's system sends an STK Push request to the Daraja API, including the customer's phone number, amount, Paybill/Till number, and a transaction description.
3. Daraja sends a prompt directly to the customer's phone (a pop-up on their SIM Toolkit menu), asking them to enter their Mpesa PIN to authorize the payment.
4. Once the customer enters their PIN, the transaction is processed.
5. The business receives a confirmation callback to a registered Callback URL (similar to the C2B Confirmation URL) indicating the success or failure of the transaction.

STK Push significantly improves the user experience by reducing the number of manual steps for the customer and minimizing errors in entering details like the Paybill number or amount. It effectively makes a customer-initiated payment feel business-initiated from the customer's perspective, though the final authorization always rests with the customer's PIN entry.

2. Buy Goods (Till Number)

A Till Number is another unique identifier for businesses, primarily used by retail merchants, small vendors, and service providers for direct point-of-sale payments. Unlike Paybill, Till Numbers are generally used for immediate purchases of goods or services where an "account number" or detailed reference is less critical, or the reference is simply the item purchased.

The customer initiation flow for Buy Goods is:

1. Customer Accesses Mpesa Menu: Similar to Paybill, the customer navigates to the Mpesa menu.
2. Selects "Lipa na Mpesa":
3. Chooses "Buy Goods and Services": The customer selects this option.
4. Enters Till Number: The customer inputs the unique 6-digit Till Number displayed by the merchant.
5. Enters Amount: The customer specifies the amount to pay for the goods/services.
6. Enters Mpesa PIN: The customer enters their Mpesa PIN to authorize the transaction.
7. Confirmation: Mpesa processes the transaction. Both the customer and the merchant receive SMS confirmations. The merchant's system, if integrated, also receives a Daraja API callback.

The integration pattern for Buy Goods is very similar to Paybill for receiving confirmations. Businesses register a Confirmation URL to receive transaction details in real-time. STK Push can also be used with Till Numbers to prompt customers for payment, especially in online retail scenarios.

Step-by-step C2B Flow (General)

1. Customer Decision: Customer decides to pay a business using Mpesa.
2. Initiation: Customer accesses Mpesa menu on their phone, selects "Lipa na Mpesa," then either "Paybill" or "Buy Goods."
3. Input Details: Customer enters the business's Paybill/Till number, the specific account/reference number (for Paybill), and the amount.
4. Authorization: Customer enters their Mpesa PIN to authorize the payment.
5. Mpesa Processing: Mpesa verifies the customer's balance, processes the transaction, and debits the customer's Mpesa account.
6. Validation (for Paybill with Validation URL): If the business has a Validation URL, Mpesa sends a synchronous request to it. The business system responds to either accept or reject the transaction based on its internal logic.
7. Confirmation:
   • Customer receives an SMS confirming the transaction.
   • Business receives an SMS notification.
   • Business's registered Confirmation URL (or Callback URL for STK Push) receives an asynchronous HTTP POST request from Daraja containing all transaction details (Mpesa Transaction ID, amount, sender, account number, etc.).
8. Business System Update: The business's system processes the callback, updates its internal ledgers, and confirms the payment internally.

B2C (Business-to-Customer) Transaction Flow

A Business-to-Customer (B2C) transaction involves a registered business initiating a transfer of funds from its Mpesa account to an individual Mpesa subscriber's wallet. These are typically disbursements rather than collections. B2C transactions are designed to enable businesses to efficiently and securely distribute funds to a large number of individual recipients, such as payroll, refunds, promotional payouts, loan disbursements, and emergency relief.

B2C transactions are exclusively initiated by businesses through the Daraja API. There is no direct customer-initiated action for B2C. The flow is:

1. Business System Request: The business's application (e.g., payroll system, e-commerce platform) constructs a B2C API request.
2. Daraja API Call: The business sends an authenticated HTTP POST request to the Daraja B2C endpoint. This request includes:
   • InitiatorName: The username of the Mpesa account initiating the transaction.
   • SecurityCredential: An encrypted password for the initiator.
   • CommandID: Specifies the type of B2C transaction (e.g., BusinessPayment, SalaryPayment, PromotionPayment).
   • Amount: The value to be disbursed.
   • PartyA: The shortcode (Paybill or Till number) of the business initiating the payment.
   • PartyB: The 10-digit Mpesa phone number of the recipient customer.
   • Remarks: A short description for the transaction.
   • QueueTimeOutURL: An endpoint where Daraja sends a callback if the transaction times out or fails before processing.
   • ResultURL: An endpoint where Daraja sends the final transaction status (success or failure).
3. Mpesa Processing: Daraja receives the request, authenticates the business, checks the business's Mpesa account balance, and processes the disbursement.
4. Confirmation:
   • The recipient customer receives an SMS notification that they have received funds from the business.
   • The business receives an asynchronous callback to its registered ResultURL (and potentially QueueTimeOutURL) with the final status of the transaction, including the Mpesa Transaction ID, Conversation ID, and OriginatorConversationID.

B2B (Business-to-Business) Transaction Flow

A Business-to-Business (B2B) transaction involves a registered business initiating a transfer of funds from its Mpesa account to another registered business's Mpesa account. These transactions facilitate inter-business payments within the Mpesa ecosystem, such as supplier payments, distributor payments, and inter-company transfers.

Like B2C, B2B transactions are exclusively initiated by businesses through the Daraja API. The flow is:

1. Business System Request: The initiating business's application constructs a B2B API request.
2. Daraja API Call: The business sends an authenticated HTTP POST request to the Daraja B2B endpoint. This request includes:
   • Initiator: The username of the Mpesa account initiating the transaction.
   • SecurityCredential: An encrypted password for the initiator.
   • CommandID: Specifies the type of B2B transaction (e.g., BusinessTransfer, BusinessBuyGoods).
   • Amount: The value to be transferred.
   • SenderIdentifierType: The type of identifier for the sending business (e.g., 4 for Paybill, 2 for Till Number).
   • RecieverIdentifierType: The type of identifier for the receiving business.
   • PartyA: The shortcode (Paybill or Till number) of the sending business.
   • PartyB: The shortcode (Paybill or Till number) of the receiving business.
   • AccountReference: A reference for the transaction, often an invoice number or internal identifier.
   • Remarks: A short description for the transaction.
   • QueueTimeOutURL: An endpoint for timeout/failure callbacks.
   • ResultURL: An endpoint for final transaction status callbacks.
3. Mpesa Processing: Daraja receives the request, authenticates the initiating business, checks its balance, and processes the transfer to the receiving business's Mpesa account.
4. Confirmation:
   • Both the sending and receiving businesses receive SMS notifications of the transaction.
   • The initiating business receives an asynchronous callback to its registered ResultURL (and potentially QueueTimeOutURL) with the final status, Mpesa Transaction ID, Conversation ID, and OriginatorConversationID.