n8n-nodes-mpesa-daraja

This package provides n8n nodes to interact with the Safaricom M-Pesa Daraja API 3.0. Automate mobile payments, account balance checks, transaction status queries, and webhook handling for payment callbacks.

Table of Contents

• Prerequisites
• Installation
• Credentials Setup
• Nodes
  • M-Pesa Node
  • M-Pesa Trigger Node
• Operations
• Examples
• Resources
• License

Prerequisites

Before using this integration, you need:

• An active n8n instance (self-hosted or cloud)
• A Safaricom developer account at developer.safaricom.co.ke
• M-Pesa API credentials (Consumer Key and Consumer Secret)
• For production: Till/Paybill number and security credentials

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Select Install
3. Enter n8n-nodes-mpesa-daraja
4. Agree to the risks and select Install
5. Restart n8n to load the new nodes

Manual Installation

For self-hosted n8n instances:

cd /path/to/n8n/installation
npm install n8n-nodes-mpesa-daraja
# Restart n8n

Credentials Setup

Creating M-Pesa API Credentials

1. Go to your n8n instance
2. Navigate to Credentials > New
3. Search for "M-Pesa API" and select it
4. Fill in the following fields:

Field	Description
Consumer Key	Your app's consumer key from Safaricom developer portal
Consumer Secret	Your app's consumer secret from Safaricom developer portal
Environment	Select Sandbox for testing or Production for live transactions

5. Click Create to save

Getting Credentials from Safaricom

1. Visit developer.safaricom.co.ke
2. Log in or create an account
3. Go to My Apps
4. Create a new app or select an existing one
5. Copy the Consumer Key and Consumer Secret

Nodes

M-Pesa Node

The M-Pesa node allows you to perform various operations with the M-Pesa API.

Node Type: Action

Credentials Required: M-Pesa API

M-Pesa Trigger Node

The M-Pesa Trigger node listens for webhook callbacks from M-Pesa when transactions complete.

Node Type: Trigger

Credentials Required: None (uses webhooks)

Operations

STK Push (Lipa na M-Pesa)

Initiate mobile payment prompts directly to customer phones.

Operations:

• Initiate: Send an STK Push prompt to a customer's phone
• Query Status: Check the status of an STK Push transaction

Use Cases:

• E-commerce checkout flows
• Service payment collection
• Subscription renewals

C2B (Customer to Business)

Register and simulate customer payments to your business.

Operations:

• Register URL: Register validation and confirmation URLs for C2B transactions
• Simulate: Test C2B transactions in sandbox environment

Use Cases:

• Till/Paybill payment automation
• Real-time payment validation
• Payment confirmation handling

B2C (Business to Customer)

Send money from your business to customers.

Operations:

• Payment Request: Disburse funds to customer mobile wallets

Use Cases:

• Salary payments
• Customer refunds
• Promotional payouts
• Affiliate commissions

B2B (Business to Business)

Transfer funds between business accounts.

Operations:

• Payment Request: Send payments to other businesses

Use Cases:

• Supplier payments
• Inter-company transfers
• Bulk disbursements

Account Operations

Manage your M-Pesa account.

Operations:

• Balance: Check your M-Pesa account balance
• Transaction Status: Query the status of any transaction
• Reversal: Reverse a completed transaction

Use Cases:

• Automated balance monitoring
• Transaction reconciliation
• Error correction workflows

Identity

Verify customer information.

Operations:

• Check ATI: Verify subscriber status via IMSI

Pull API

Query transaction history.

Operations:

• Register URL: Register callback URL for pull transactions
• Query: Retrieve transaction history for a date range

M-Pesa Trigger Events

The trigger node supports the following webhook events:

Event	Description	Triggered When
Payment Received	C2B confirmation callback	Customer pays to your Till/Paybill
STK Push Completed	Lipa na M-Pesa callback	STK Push transaction completes (success/failure)
B2C Completed	Business to Customer callback	B2C disbursement completes
B2B Completed	Business to Business callback	B2B payment completes
Reversal Completed	Transaction reversal callback	Reversal request completes
Account Balance Completed	Balance query callback	Account balance check completes
Transaction Status Completed	Status query callback	Transaction status check completes

Trigger Options

• Only Successful Transactions: Filter to trigger only on successful transactions (ResultCode = 0)
• Normalize Output: Transform callback payloads into a consistent format across all event types

Examples

Example 1: Process STK Push Payment

1. Add M-Pesa Trigger node
2. Select event: "STK Push Completed"
3. Enable "Only Successful Transactions"
4. Copy the webhook production URL
5. Use this URL when initiating STK Push via M-Pesa node
6. Add your business logic nodes (e.g., update database, send confirmation email)

Example 2: Check Account Balance

1. Add M-Pesa node
2. Select Resource: "Account"
3. Select Operation: "Balance"
4. Fill in required fields:
   • Initiator Name
   • Security Credential
   • Party A (your shortcode)
   • Queue Timeout URL
   • Result URL (use M-Pesa Trigger webhook URL)
5. Execute the workflow

Example 3: Automated Daily Balance Report

1. Add Schedule Trigger (daily at 9 AM)
2. Add M-Pesa node for Account Balance
3. Add M-Pesa Trigger for balance callback
4. Add Email node to send balance report
5. Activate workflow

Resources

• Safaricom Developer Portal
• M-Pesa Daraja API Documentation
• n8n Documentation
• n8n Community Forum

License

MIT

Support

For issues or feature requests, please visit the GitHub repository and open an issue.