API Reference

Complete documentation for all M-Pesa operations available in the Singularity Payments SDK.

Overview

The Singularity Payments SDK provides a type-safe, framework-agnostic way to integrate M-Pesa payments into your application. All operations are built on top of the @singularity-payments/core package with framework-specific adapters.

Available Operations

Payment Operations

STK Push

Initiate M-Pesa STK Push (Lipa Na M-Pesa Online) payments

C2B Payments

Customer to Business payments with validation and confirmation

B2C Payments

Send money from your business to customers

B2B Payments

Business to Business payment transfers

Transaction Management

Transaction Status

Query the status of any M-Pesa transaction

Account Balance

Check your M-Pesa business account balance

Reversals

Reverse completed transactions

Dynamic QR

Generate dynamic QR codes for payments

SDK Features

Configuration

Configure the SDK with your M-Pesa credentials

Callbacks & Webhooks

Handle M-Pesa callbacks and webhook events

Error Handling

Handle errors and edge cases gracefully

Rate Limiting

Built-in rate limiting and retry logic

Quick Example

import { MpesaClient } from "@singularity-payments/core";

const client = new MpesaClient({
  consumerKey: process.env.MPESA_CONSUMER_KEY,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET,
  passkey: process.env.MPESA_PASSKEY,
  shortcode: process.env.MPESA_SHORTCODE,
  environment: "sandbox",
  callbackUrl: "https://yourdomain.com/api/mpesa/callback",
});

// Initiate STK Push
const response = await client.stkPush({
  amount: 100,
  phoneNumber: "254712345678",
  accountReference: "INV-001",
  transactionDesc: "Payment for invoice",
});

Common Configuration

All SDK packages require the following M-Pesa credentials:

Field	Required	Description
`consumerKey`	✅	M-Pesa API consumer key
`consumerSecret`	✅	M-Pesa API consumer secret
`passkey`	✅	STK Push passkey
`shortcode`	✅	M-Pesa business shortcode
`environment`	✅	`"sandbox"` or `"production"`
`callbackUrl`	Recommended	URL for receiving callbacks
`initiatorName`	For B2C/B2B	Initiator username
`securityCredential`	For B2C/B2B	Encrypted security credential