M-Pesa APIs: Comprehensive Guide to Steps and Available Options

Available M-Pesa API Options

Safaricom offers several distinct M-Pesa API products tailored to different business needs:

1. Lipa Na M-Pesa Online (STK Push)

This API allows businesses to initiate payment requests on behalf of customers. A prefilled pop-up notification appears on the customer's M-Pesa menu, allowing them to complete the transaction by entering only their PIN. This approach significantly reduces friction in the payment process.

2. Customer-to-Business (C2B) API

The C2B API incorporates an optional payment validation step for Paybill transactions, allowing payment recipients (merchants) to confirm whether to accept incoming payments or not. This prevents situations where customers send payment to the correct Paybill number but enter the wrong account, reducing reversal requests.

3. Business-to-Customer (B2C) API

The B2C API enables seamless outward payment processing via API, including employee salary disbursements and payments to merchants that accept M-Pesa payments, removing the manual process of generating payments files, formatting them, uploading via web portal, and requiring approval from different users. This feature is ideal for payroll processing and promotional payouts.

4. Business-to-Business (B2B) API

This API facilitates direct payments between businesses, allowing organizations to transfer funds from their paybill accounts to other business accounts without manual intervention.

5. Payment Validation and Confirmation APIs

These endpoints enable real-time payment verification, ensuring merchants can validate transaction parameters including account numbers, amounts, and sender information before accepting payments.

6. Payment Reversal API

M-Pesa supports secure payment reversal automation, allowing merchants to handle situations where services cannot be rendered after payment has been received.

7. Account Balance Query

Merchants can query their Till or Paybill account balance on demand using this API.

8. Transaction Status Query

This endpoint allows merchants to check the status of any STK push or transaction on demand.

Getting Started: Step-by-Step Implementation

Step 1: Obtain a Paybill or Till Number

Before accessing any APIs, you need an M-Pesa business account with either a Paybill or Till (BuyGoods) number. You can request one through:

• The M-Pesa for Business portal
• Email: [email protected]
• Phone: Dial *234# from your Safaricom line

For Till numbers, the self-onboarding process typically takes 24-48 working hours. For Paybill numbers, you may need to visit a Safaricom shop with company documentation.

Step 2: Prepare Required Documentation

Required documents include your company's KRA PIN certificate, a copy of company CR12 (validity 90 days), a scanned certificate of registration, front and back scanned copies of directors' IDs or passports, an M-Pesa Authorization form signed by two directors, directors' KRA PIN certificates, and bank details. Ensure all business names match across KRA, bank, and registration documents to avoid delays.

Step 3: Create a Safaricom Developer Account

Visit the Safaricom Daraja Portal (developer.safaricom.co.ke) and register for an account. This is where you'll manage your API applications and credentials.

Step 4: Create an M-Pesa Business Administrator Account

After obtaining your shortcode, create a business administrator username that will be used for API access. You'll need to submit a duly filled and signed administrator form (signed by at least two directors) along with supporting documentation to Safaricom.

Email your request to [email protected] with:

• Completed Business Administrator Form
• Company registration certificate
• Copies of director IDs
• Subject line: "Request for Mpesa Portal Login"

Safaricom typically responds within 24-48 hours with your portal credentials.

Step 5: Log In to the M-Pesa Portal (G2)

Once you receive credentials, log in to the M-Pesa Business Dashboard, change your default password, and create additional user roles (Business Manager or Assistant) as needed. For Till numbers, you'll need to create a child account under your store number, as the head office number doesn't receive callbacks.

Step 6: Create and Configure Your Daraja Application

In the Daraja Portal:

• Click "Add a New App"
• Give your application a name
• Select the APIs you need (C2B, Lipa Na M-Pesa Online, B2C, B2B, etc.)
• Click "Create App"

Step 7: Generate API Credentials

You'll receive:

• Consumer Key: Used for authentication
• Consumer Secret: Used with the Consumer Key for authentication
• Initiator Name: Your M-Pesa account username authorized to make transactions
• Initiator Password: Used for encrypting sensitive requests

Step 8: Set Up Callback URLs

For sandbox testing, you need to register:

• Validation URL: Where M-Pesa sends transaction details for verification
• Confirmation URL: Where M-Pesa sends transaction confirmation
• Results URL: For receiving B2C payment results

These must be publicly accessible HTTPS endpoints on your server.

Step 9: Conduct Sandbox Testing

Use the sandbox environment (https://sandbox.safaricom.co.ke) to test your integration thoroughly before going live. Test all payment flows, callback handling, and error scenarios.

Step 10: Request Production Access

Once sandbox testing is complete, prepare a formal request letter on your company letterhead containing:

• Your use case and business requirements
• Testing results and volume projections
• Security measures implemented
• Callback URLs for production
• Your business administrator details

Submit this to [email protected] or [email protected]. Safaricom will review your application, verify your use case, and provide production credentials along with IP whitelisting information.

Key Integration Considerations

Authentication

All API requests require an access token generated using your Consumer Key and Secret. This token expires after approximately one hour and must be regenerated for each new session.

Security

When making B2C or other sensitive requests, encrypt your Initiator Password using Safaricom's public key. Never expose your credentials in client-side code.

Callback Handling

Implement robust callback handlers to process transaction responses from M-Pesa. These must be able to receive JSON data, parse it, and store transaction information in your database for reconciliation.

Error Handling

Design your system to handle various scenarios including failed transactions, timeouts, network issues, and customer-initiated cancellations.

Recent Infrastructure Improvements

The new M-Pesa Core expanded capacity from 4,500 to 6,000 transactions per second at launch, with potential to scale up to 12,000 transactions as demand grows, and introduced an active-active architecture across multiple hosting sites guaranteeing higher resilience and minimal service interruption.

These improvements ensure that M-Pesa APIs can handle high transaction volumes reliably, making them suitable for large-scale enterprise implementations.