mpesajs/dist/stkpush.d.ts

A Node.js SDK for seamless integration with M-Pesa payment gateway, providing easy-to-use methods for handling transactions, payments, and API interactions

import { Auth } from './auth';
/**
 * Response interface for successful STK Push transactions.
 *
 * @interface StkPushResponse
 * @property {string} MerchantRequestID - Unique identifier for the merchant request
 * @property {string} CheckoutRequestID - Unique identifier for the checkout/payment request
 * @property {string} ResponseCode - Response code from M-Pesa API (0 indicates success)
 * @property {string} ResponseDescription - Description of the response status
 * @property {string} CustomerMessage - Message that can be displayed to the customer
 */
interface StkPushResponse {
    MerchantRequestID: string;
    CheckoutRequestID: string;
    ResponseCode: string;
    ResponseDescription: string;
    CustomerMessage: string;
}
/**
 * STK Push  implementation for M-Pesa payment integration.
 *
 * This class provides functionality to initiate mobile money payment requests to users
 * via the Safaricom M-Pesa STK Push API. It handles authentication, request validation,
 * rate limiting, and error management for M-Pesa payment processing.
 *
 * @class StkPush
 */
export declare class StkPush {
    private auth;
    private baseUrl;
    private readonly rateLimiter;
    /**
     * Creates an instance of the StkPush class.
     *
     * @param {Auth} auth - The authentication instance for generating M-Pesa API tokens
     * @param {boolean} sandbox - Whether to use the sandbox (testing) environment
     *                           (defaults to environment variable or true)
     */
    constructor(auth: Auth, sandbox?: boolean);
    /**
     * Validates the phone number format for M-Pesa transactions.
     *
     * @private
     * @param {string} phoneNumber - The customer phone number to validate
     * @throws {ValidationError} If phone number format is invalid
     */
    private validatePhoneNumber;
    /**
     * Validates that the transaction amount is positive.
     *
     * @private
     * @param {number} amount - The transaction amount to validate
     * @throws {ValidationError} If amount is not greater than 0
     */
    private validateAmount;
    /**
     * Validates that the callback URL uses HTTPS protocol.
     *
     * @private
     * @param {string} callbackUrl - The callback URL to validate
     * @throws {ValidationError} If URL does not use HTTPS protocol
     */
    private validateCallbackUrl;
    /**
     * Validates that the account reference does not exceed maximum length.
     *
     * @private
     * @param {string} accountReference - The account reference to validate
     * @throws {ValidationError} If account reference exceeds 12 characters
     */
    private validateAccountReference;
    /**
     * Validates that the transaction description does not exceed maximum length.
     *
     * @private
     * @param {string} transactionDesc - The transaction description to validate
     * @throws {ValidationError} If transaction description exceeds 13 characters
     */
    private validateTransactionDesc;
    /**
     * Validates all input parameters for an STK Push request.
     *
     * @private
     * @param {string} businessShortCode - The business short code
     * @param {string} passkey - The passkey for generating the password
     * @param {number} amount - The transaction amount
     * @param {string} phoneNumber - The customer's phone number
     * @param {string} callbackUrl - The callback URL for transaction result
     * @param {string} accountReference - The account reference
     * @param {string} transactionDesc - The transaction description
     * @throws {ValidationError} If any parameter fails validation
     */
    private validateInputs;
    /**
     * Generates the secure password required for STK Push API requests.
     *
     * The password is generated by concatenating the business short code, passkey, and timestamp,
     * then applying SHA-256 hashing and Base64 encoding.
     *
     * @private
     * @param {string} businessShortCode - The business short code
     * @param {string} passkey - The passkey provided by M-Pesa
     * @param {string} timestamp - The transaction timestamp
     * @returns {string} The generated Base64-encoded password
     */
    private generatePassword;
    /**
     * Initiates an STK Push transaction to request payment from a customer.
     *
     * This method handles the entire STK Push process:
     * - Validates all input parameters
     * - Generates the required security credentials
     * - Obtains an access token for the M-Pesa API
     * - Creates and sends the API request with proper rate limiting
     * - Handles success and error responses
     *
     * The method uses environment variables for optional parameters if not explicitly provided.
     *
     * @param {number} amount - The amount to be paid
     * @param {string} transactionDesc - Description of the transaction (max 13 chars)
     * @param {string} accountReference - Reference for the transaction (max 12 chars)
     * @param {string} [businessShortCode] - The business short code (defaults to env var)
     * @param {string} [passkey] - The passkey for password generation (defaults to env var)
     * @param {string} [phoneNumber] - The customer's phone number (defaults to env var)
     * @param {string} [callbackUrl] - The callback URL for results (defaults to env var)
     * @returns {Promise<StkPushResponse>} A promise resolving to the M-Pesa API response
     * @throws {ValidationError} If any input parameter is invalid
     * @throws {NetworkError} If there are connectivity issues
     * @throws {StkPushError} If the M-Pesa API returns an error
     * @throws {MpesaError} For other failures during the process
     */
    sendStkPush(amount: number, transactionDesc: string, accountReference: string, businessShortCode?: string, passkey?: string, phoneNumber?: string, callbackUrl?: string): Promise<StkPushResponse>;
}
export {};