DEV Community: katorymnddev

Simplifying African Mobile Payments: Introducing the Pawapay Node.js SDK & Live Playground

katorymnddev — Mon, 19 Jan 2026 14:31:47 +0000

If you’ve ever tried to build a payment integration targeted at the African market, you know the landscape is… unique.

Credit cards aren't the primary driver. Mobile Money is king.

But integrating with MTN, Airtel, Vodafone, M-Pesa across multiple countries individually is a massive headache of fragmented APIs, varying documentation standards, and long compliance processes.

This is where Pawapay shines. It aggregates these massive mobile money providers into a single, unified API.

Today, I am thrilled to announce two major tools that make integrating Pawapay into your JavaScript/TypeScript stack faster than ever: the brand new, fully-typed Pawapay Node.js SDK, and an interactive Live Demo Playground.

This article is a surgical look at the "hows" and "whens" of using these new tools to handle payments in Africa.

The Problem with Raw HTTP Requests

While Pawapay’s REST API is clean, consuming raw REST APIs in a production Node.js environment quickly requires boilerplate. You have to handle:

Request signing and authentication headers.
Manual type definitions for request bodies and responses (if you use TypeScript).
Error handling normalization.
Retries and timeout logic.

We built the @katorymnd/pawapay-node-sdk to abstract this away, letting you focus on your business logic, not HTTP plumbing.

Key SDK Features:

🛡️ First-class TypeScript Support: Written in TypeScript for robust type definitions and Intellisense autocomplete.
⚡ Promise-based: Built for modern async/await workflows.
📦 Comprehensive: Covers the full spectrum of payments: Deposits (collections), Payouts (disbursements), Refunds, and account validation.

The Surgical "How-To": Using the SDK

Let's dissect a real-world scenario: An e-commerce checkout where a user in Ghana wants to pay using MTN Mobile Money.

Step 1: Installation and Setup

First, get the package into your project.

npm install @katorymnd/pawapay-node-sdk
# or
yarn add @katorymnd/pawapay-node-sdk
# or 
pnpm add @katorymnd/pawapay-node-sdk

Initialize the client with your credentials. In a real app, use environment variables.

//pawapay.js

const path = require('path');
const winston = require('winston');
require('dotenv').config(); 

// Load the SDK and destructure the public exports directly
// We use 'ApiClient' because that's the class name export
const { ApiClient, Helpers, FailureCodeHelper } = require('@katorymnd/pawapay-node-sdk');

// ========== LOGGING SETUP ==========
const logsDir = path.resolve(__dirname, '../logs');

const logger = winston.createLogger({
    format: winston.format.combine(
        winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
        winston.format.errors({ stack: true }),
        winston.format.json()
    ),
    transports: [
        new winston.transports.File({
            filename: path.join(logsDir, 'payment_success.log'),
            level: 'info',
            format: winston.format.combine(
                winston.format.timestamp(),
                winston.format.json()
            )
        }),
        new winston.transports.File({
            filename: path.join(logsDir, 'payment_failed.log'),
            level: 'error',
            format: winston.format.combine(
                winston.format.timestamp(),
                winston.format.json()
            )
        })
    ]
});

if (process.env.NODE_ENV !== 'production') {
    logger.add(new winston.transports.Console({
        format: winston.format.combine(
            winston.format.colorize(),
            winston.format.simple()
        )
    }));
}
// ========== END LOGGING SETUP ==========

class PawaPayService {
    /**
     * @param {Object} config - Optional configuration
     * @param {string} config.token - Custom API Token to override .env
     */
    constructor(config = {}) {
        // Prioritize ENV
        const activeToken = process.env.PAWAPAY_SANDBOX_API_TOKEN;

        // Debug log to confirm token is being used
        const maskedToken = activeToken ? `${activeToken.substring(0, 5)}...` : 'NONE';
        console.log(`[PawaPayService] Initializing with token: ${maskedToken}`);

        this.pawapay = new ApiClient({
            apiToken: activeToken,
            environment: 'sandbox', // or production
            licenseKey: process.env.KATORYMND_PAWAPAY_SDK_LICENSE_KEY, //it's required, and the SDK will not work if it is not defined
            sslVerify: false
        });
    }
    /**
     * Deposit money to a mobile money account
     * @param {Object} depositData - Deposit details
     * @param {string} apiVersion - 'v1' or 'v2'
     */
    async deposit(depositData, apiVersion = 'v1') {
        // Use the Helper directly from the SDK
        const depositId = Helpers.generateUniqueId();

        try {
            const {
                amount,
                currency,
                mno,
                payerMsisdn,
                description,
                metadata = []
            } = depositData;

            // 1. STRICT VALIDATION
            if (!amount || !mno || !payerMsisdn || !description || !currency) {
                const missingMsg = 'Validation failed - Missing required fields';
                logger.error(missingMsg, depositData);
                return { success: false, error: missingMsg };
            }

            // Validate Amount
            const amountRegex = /^\d+(\.\d{1,2})?$/;
            if (!amountRegex.test(amount) || parseFloat(amount) <= 0) {
                const msg = 'Invalid amount. Must be positive with max 2 decimals.';
                logger.error(msg, { amount });
                return { success: false, error: msg };
            }

            // Validate Description
            const descriptionRegex = /^[A-Za-z0-9 ]{1,22}$/;
            if (!descriptionRegex.test(description)) {
                const msg = 'Invalid description. Max 22 chars, alphanumeric only.';
                logger.error(msg, { description });
                return { success: false, error: msg };
            }

            logger.info('Initiating deposit', {
                depositId,
                amount,
                currency,
                mno,
                apiVersion
            });

            // 2. PROCESS DEPOSIT
            let response;

            if (apiVersion === 'v2') {
                response = await this.pawapay.initiateDepositV2(
                    depositId,
                    amount,
                    currency,
                    payerMsisdn,
                    mno, // provider
                    description, // customerMessage
                    null, // clientReferenceId
                    null, // preAuthorisationCode
                    metadata
                );
            } else {
                response = await this.pawapay.initiateDeposit(
                    depositId,
                    amount,
                    currency,
                    mno, // correspondent
                    payerMsisdn,
                    description, // statementDescription
                    metadata
                );
            }

            // 3. HANDLE RESPONSE
            if (response.status === 200 || response.status === 201) {
                logger.info('Deposit initiated successfully', { depositId, status: response.status });

                const statusCheck = await this.checkTransactionStatus(depositId, apiVersion);

                return {
                    success: true,
                    depositId,
                    transactionId: depositId,
                    reference: depositId,
                    status: statusCheck.status || 'SUBMITTED',
                    message: 'Deposit initiated successfully',
                    rawResponse: response,
                    statusCheck: statusCheck
                };
            } else {
                // 4. HANDLE ERRORS
                let errorMessage = 'Deposit initiation failed';
                let failureCode = 'UNKNOWN';

                if (response.response?.rejectionReason?.rejectionMessage) {
                    errorMessage = response.response.rejectionReason.rejectionMessage;
                } else if (response.response?.failureReason?.failureCode) {
                    failureCode = response.response.failureReason.failureCode;
                    // Use the SDK's built-in error helper
                    errorMessage = FailureCodeHelper.getFailureMessage(failureCode);
                } else if (response.response?.message) {
                    errorMessage = response.response.message;
                }

                logger.error('Deposit initiation failed', {
                    depositId,
                    error: errorMessage,
                    failureCode,
                    response: response.response
                });

                return {
                    success: false,
                    error: errorMessage,
                    depositId,
                    statusCode: response.status,
                    rawResponse: response
                };
            }

        } catch (error) {
            logger.error('System Error during deposit', {
                depositId,
                error: error.message,
                stack: error.stack
            });

            return {
                success: false,
                error: error.message || 'Internal processing error',
                depositId
            };
        }
    }

  /**
     * Check Status of ANY transaction (Deposit, Payout, Refund)
     * @param {string} transactionId - The ID to check
     * @param {string} apiVersion - 'v1' or 'v2'
     * @param {string} type - 'deposit', 'payout', 'refund', 'remittance'
     */
    async checkTransactionStatus(transactionId, apiVersion = 'v1', type = 'deposit') {
        try {
            let response;

            // Pass the 'type' to the SDK so it hits the correct endpoint (e.g., /payouts vs /deposits)
            if (apiVersion === 'v2') {
                response = await this.pawapay.checkTransactionStatusV2(transactionId, type);
            } else {
                response = await this.pawapay.checkTransactionStatus(transactionId, type);
            }

            logger.info(`Checking ${type} status`, { transactionId, status: response.status });

            if (response.status === 200) {
                let data;
                let status;

                // Normalize V1 (Array/Object) vs V2 (Object wrapper)
                if (apiVersion === 'v2') {
                    if (response.response?.status !== 'FOUND') {
                        return {
                            success: true,
                            status: 'PROCESSING',
                            transactionId,
                            message: 'Transaction processing'
                        };
                    }
                    data = response.response.data;
                    status = data?.status || 'UNKNOWN';
                } else {
                    // V1 legacy can be array [ { ... } ] or object
                    const raw = response.response;
                    data = Array.isArray(raw) ? raw[0] : raw;
                    status = data?.status || 'UNKNOWN';
                }

                return {
                    success: true,
                    status: status,
                    transactionId: transactionId,
                    data: data,
                    rawResponse: response
                };
            } else {
                return {
                    success: false,
                    error: `Status check failed with code ${response.status}`,
                    statusCode: response.status
                };
            }
        } catch (error) {
            logger.error('Status check error', { error: error.message });
            return {
                success: false,
                error: error.message || 'Status check failed'
            };
        }
    }

    validateToken(token) {
        if (!token || token.trim() === '') return { isValid: false, error: 'Token is required' };
        return { isValid: true, type: 'JWT', message: 'Valid token format' };
    }

    /**
     * Create a Payment Page Session
     * @param {Object} pageData - Payment details
     * @param {string} apiVersion - 'v1' or 'v2'
     */
    async initiatePaymentPage(pageData, apiVersion = 'v1') {
        const depositId = Helpers.generateUniqueId();

        try {
            const {
                amount,
                currency,
                payerMsisdn,
                description,
                returnUrl,
                metadata = [],
                country = 'UGA', // Default to Uganda for testing
                reason = 'Payment'
            } = pageData;

            // 1. STRICT VALIDATION
            if (!amount || !description || !currency || !returnUrl) {
                const missingMsg = 'Validation failed - Missing required fields (returnUrl is mandatory)';
                logger.error(missingMsg, pageData);
                return { success: false, error: missingMsg };
            }

            logger.info('Initiating Payment Page', {
                depositId,
                amount,
                apiVersion
            });

            // 2. PREPARE PAYLOAD & CALL SDK
            let response;

            // Normalize phone (remove +)
            const cleanMsisdn = payerMsisdn ? payerMsisdn.replace(/\D/g, '') : null;

            if (apiVersion === 'v2') {
                // V2 Payload Construction
                const v2Params = {
                    depositId,
                    returnUrl,
                    customerMessage: description,
                    amountDetails: {
                        amount: String(amount),
                        currency: currency
                    },
                    phoneNumber: cleanMsisdn,
                    country,
                    reason,
                    metadata
                };
                response = await this.pawapay.createPaymentPageSessionV2(v2Params);
            } else {
                // V1 Payload Construction
                const v1Params = {
                    depositId,
                    returnUrl,
                    amount: String(amount),
                    currency,
                    msisdn: cleanMsisdn,
                    statementDescription: description,
                    country,
                    reason,
                    metadata
                };
                response = await this.pawapay.createPaymentPageSession(v1Params);
            }

            // 3. HANDLE RESPONSE
            // Note: API returns 200/201 for success
            if (response.status >= 200 && response.status < 300) {
                const redirectUrl = response.response?.redirectUrl || response.response?.url;

                logger.info('Payment Page created', { depositId, redirectUrl });

                return {
                    success: true,
                    depositId,
                    redirectUrl,
                    message: 'Session created successfully',
                    rawResponse: response
                };
            } else {
                // 4. HANDLE ERRORS
                const errorMsg = response.response?.message || 'Failed to create payment session';

                logger.error('Payment Page creation failed', {
                    depositId,
                    error: errorMsg,
                    response: response.response
                });

                return {
                    success: false,
                    error: errorMsg,
                    depositId,
                    statusCode: response.status
                };
            }

        } catch (error) {
            logger.error('System Error during payment page creation', {
                depositId,
                error: error.message,
                stack: error.stack
            });

            return {
                success: false,
                error: error.message || 'Internal processing error',
                depositId
            };
        }
    }


    /**
 * Payout money to a mobile money account (Disbursement)
 * @param {Object} payoutData - Payout details
 * @param {string} apiVersion - 'v1' or 'v2'
 */
    async payout(payoutData, apiVersion = 'v1') {
        const payoutId = Helpers.generateUniqueId();

        try {
            // 1. EXTRACT DATA WITH FALLBACKS
            let {
                amount,
                currency,
                mno,            // Logic might send this
                provider,       // V2 logic might send this
                correspondent,  // V1 logic might send this
                recipientMsisdn,
                description,    // Direct description
                statementDescription, // V1 alternative
                customerMessage, // V2 alternative
                reason,         // Another possible field
                metadata = []
            } = payoutData;

            // 🛠️ FIX: Normalize the operator code
            // If 'mno' is undefined, use 'provider' (V2) or 'correspondent' (V1)
            const resolvedMno = mno || provider || correspondent;

            // ============================================================
            // SURGICAL FIX: Ensure 'description' is never missing
            // PawaPay API requires this field for both V1 and V2.
            // ============================================================
            const resolvedDescription = description
                || statementDescription
                || customerMessage
                || reason
                || 'Transaction Processing'; // Ultimate fallback

            // 2. STRICT VALIDATION & DEBUG LOGGING
            // We check specific fields to give a precise error message
            const missingFields = [];
            if (!amount) missingFields.push('amount');
            if (!resolvedMno) missingFields.push(`mno (looked for: mno, provider, correspondent)`);
            if (!recipientMsisdn) missingFields.push('recipientMsisdn');
            if (!resolvedDescription) missingFields.push('description');
            if (!currency) missingFields.push('currency');

            if (missingFields.length > 0) {
                const missingMsg = `Validation failed - Missing fields: [${missingFields.join(', ')}]`;

                // 🔍 DEBUG: Construct a detailed log entry for the error.log
                const debugPayload = {
                    ERROR_TYPE: 'PAYOUT_VALIDATION_ERROR',
                    PAYOUT_ID: payoutId,
                    API_VERSION: apiVersion,
                    MISSING: missingFields,
                    RESOLVED_MNO: resolvedMno || 'UNDEFINED (This is likely the issue)',
                    RESOLVED_DESCRIPTION: resolvedDescription || 'UNDEFINED',
                    RAW_RECEIVED: JSON.stringify(payoutData, null, 2) // Pretty print the full object
                };

                // Log to your system logger
                logger.error(missingMsg, debugPayload);

                // Return failure with details
                return {
                    success: false,
                    error: missingMsg,
                    debug: debugPayload // Return this so the frontend/controller can see it too
                };
            }

            // Assign the resolved values back to variables used in logic
            mno = resolvedMno;
            description = resolvedDescription; // 🚨 CRITICAL: Update the description variable

            // Validate Amount Format
            const amountRegex = /^\d+(\.\d{1,2})?$/;
            if (!amountRegex.test(amount) || parseFloat(amount) <= 0) {
                const msg = 'Invalid amount. Must be positive with max 2 decimals.';
                logger.error(msg, { amount, payoutId });
                return { success: false, error: msg };
            }

            logger.info('Initiating payout', {
                payoutId,
                amount,
                currency,
                mno,
                description, // Log the resolved description
                apiVersion
            });

            // 3. PROCESS PAYOUT
            let response;

            if (apiVersion === 'v2') {
                // V2 Payout
                response = await this.pawapay.initiatePayoutV2(
                    payoutId,
                    amount,
                    currency,
                    recipientMsisdn,
                    mno, // provider
                    description, // customerMessage - using the resolved description
                    metadata
                );
            } else {
                // V1 Payout
                response = await this.pawapay.initiatePayout(
                    payoutId,
                    amount,
                    currency,
                    mno, // correspondent
                    recipientMsisdn, // recipient address
                    description, // statementDescription - using the resolved description
                    metadata
                );
            }

            // 4. HANDLE RESPONSE
            if (response.status === 200 || response.status === 201 || response.status === 202) {
                logger.info('Payout initiated successfully', {
                    payoutId,
                    status: response.status,
                    description // Log successful description
                });

                const statusCheck = await this.checkTransactionStatus(payoutId, apiVersion);

                return {
                    success: true,
                    payoutId,
                    transactionId: payoutId,
                    status: statusCheck.status || 'SUBMITTED',
                    message: 'Payout initiated successfully',
                    rawResponse: response,
                    statusCheck: statusCheck
                };
            } else {
                // 5. HANDLE ERRORS
                let errorMessage = 'Payout initiation failed';
                let failureCode = 'UNKNOWN';

                if (response.response?.rejectionReason?.rejectionMessage) {
                    errorMessage = response.response.rejectionReason.rejectionMessage;
                } else if (response.response?.failureReason?.failureCode) {
                    failureCode = response.response.failureReason.failureCode;
                    errorMessage = FailureCodeHelper.getFailureMessage(failureCode);
                } else if (response.response?.message) {
                    errorMessage = response.response.message;
                }

                logger.error('Payout initiation failed', {
                    payoutId,
                    error: errorMessage,
                    failureCode,
                    response: response.response,
                    description // Log description even on failure
                });

                return {
                    success: false,
                    error: errorMessage,
                    payoutId,
                    statusCode: response.status,
                    rawResponse: response
                };
            }

        } catch (error) {
            logger.error('System Error during payout', {
                payoutId,
                error: error.message,
                stack: error.stack,
                inputData: JSON.stringify(payoutData) // Log input on crash too
            });

            return {
                success: false,
                error: error.message || 'Internal processing error',
                payoutId
            };
        }
    }


    /**
   * Initiate a Refund (Partial or Full)
   * @param {Object} refundData - Refund details
   * @param {string} apiVersion - 'v1' or 'v2'
   */
  async refund(refundData, apiVersion = 'v1') {
    const refundId = Helpers.generateUniqueId();

    try {
      const {
        depositId,
        amount,
        currency, // Required for V2
        reason,
        metadata = []
      } = refundData;

      // 1. STRICT VALIDATION
      if (!depositId || !amount) {
        const missingMsg = 'Validation failed - Missing required fields (depositId, amount)';
        logger.error(missingMsg, refundData);
        return { success: false, error: missingMsg };
      }

      // V2 Specific Validation
      if (apiVersion === 'v2' && !currency) {
        const msg = 'Validation failed - V2 Refunds require a currency code';
        logger.error(msg, refundData);
        return { success: false, error: msg };
      }

      // Validate Amount
      const amountRegex = /^\d+(\.\d{1,2})?$/;
      if (!amountRegex.test(amount) || parseFloat(amount) <= 0) {
        const msg = 'Invalid amount. Must be positive with max 2 decimals.';
        logger.error(msg, { amount });
        return { success: false, error: msg };
      }

      logger.info('Initiating refund', {
        refundId,
        depositId,
        amount,
        currency,
        apiVersion
      });

      // 2. PROCESS REFUND
      let response;

      if (apiVersion === 'v2') {
        // V2 Refund
        response = await this.pawapay.initiateRefundV2(
          refundId,
          depositId,
          amount,
          currency,
          metadata
        );
      } else {
        // V1 Refund
        response = await this.pawapay.initiateRefund(
          refundId,
          depositId,
          amount,
          metadata
        );
      }

      // 3. HANDLE RESPONSE
      // Refunds typically return 200/201/202
      if (response.status >= 200 && response.status < 300) {
        logger.info('Refund initiated successfully', { refundId, status: response.status });

        // Check status immediately (passing 'refund' as type is critical)
        const statusCheck = await this.checkTransactionStatus(refundId, apiVersion, 'refund');

        return {
          success: true,
          refundId,
          transactionId: refundId,
          depositId: depositId,
          status: statusCheck.status || 'SUBMITTED',
          message: 'Refund initiated successfully',
          rawResponse: response,
          statusCheck: statusCheck
        };
      } else {
        // 4. HANDLE ERRORS
        let errorMessage = 'Refund initiation failed';
        let failureCode = 'UNKNOWN';

        if (response.response?.rejectionReason?.rejectionMessage) {
          errorMessage = response.response.rejectionReason.rejectionMessage;
        } else if (response.response?.failureReason?.failureCode) {
          failureCode = response.response.failureReason.failureCode;
          errorMessage = FailureCodeHelper.getFailureMessage(failureCode);
        } else if (response.response?.message) {
          errorMessage = response.response.message;
        }

        logger.error('Refund initiation failed', {
          refundId,
          depositId,
          error: errorMessage,
          failureCode,
          response: response.response
        });

        return {
          success: false,
          error: errorMessage,
          refundId,
          statusCode: response.status,
          rawResponse: response
        };
      }

    } catch (error) {
      logger.error('System Error during refund', {
        refundId,
        depositId: refundData.depositId,
        error: error.message,
        stack: error.stack
      });

      return {
        success: false,
        error: error.message || 'Internal processing error',
        refundId
      };
    }
    }

}

module.exports = PawaPayService;

Step 2: Initiating a Deposit (Collection)

The user clicks "Pay Now". You need to trigger a mobile money prompt on their phone.

Instead of constructing a complex JSON fetch request, you call a typed method.

// test-sdk-deposit.js
const path = require('path');
// Ensure strict loading of the root .env file
require('dotenv').config({ path: path.resolve(__dirname, '../.env') });

const PawaPayService = require('./pawapayService');

/**
 * Run a full test of the PawaPay SDK integration (Deposits)
 */
async function testSDKConnection() {
    console.log('\n========================================');
    console.log('🧪 PAWAPAY SDK DEPOSIT TEST (With Status Check)');
    console.log('========================================\n');

    const service = new PawaPayService();

    // 1. Validate Token Format
    console.log(' Step 1: Validating API Token...');
    const testToken = process.env.PAWAPAY_SANDBOX_API_TOKEN;
    const validation = service.validateToken(testToken);

    if (!validation.isValid) {
        console.error(' Token Validation Failed:', validation);
        return;
    }
    console.log(' Token looks valid:', validation.type);

    // Common Test Data (Uganda MTN Sandbox)
    const commonData = {
        amount: '1000',
        currency: 'UGX',
        mno: 'MTN_MOMO_UGA',
        payerMsisdn: '256783456789', // Valid Sandbox Payer
        description: 'SDK Integration Test'
    };

    // --- 2. Test V1 Deposit ---
    console.log('\n Step 2: Testing V1 Deposit...');
    try {
        const v1Result = await service.deposit({
            ...commonData,
            description: 'V1 Test Payment'
        }, 'v1');

        if (v1Result.success) {
            console.log(' V1 Initiation Success:', {
                depositId: v1Result.depositId,
                status: v1Result.status
            });

            // WAIT AND CHECK
            console.log(' Waiting 5 seconds for V1 propagation...');
            await new Promise(r => setTimeout(r, 5000));

            console.log(' Checking V1 Status...');
            const statusCheck = await service.checkTransactionStatus(
                v1Result.depositId,
                'v1',
                'deposit'
            );

            console.log(` Final V1 Status: [ ${statusCheck.status} ]`);
            if (statusCheck.status === 'FAILED') {
                console.warn(`   Reason: ${statusCheck.data?.failureReason?.failureMessage || 'Unknown'}`);
            }

        } else {
            console.error(' V1 Failed:', v1Result.error);
        }
    } catch (error) {
        console.error(' V1 Exception:', error.message);
    }

    // --- 3. Test V2 Deposit ---
    console.log('\n Step 3: Testing V2 Deposit...');
    try {
        const v2Result = await service.deposit({
            ...commonData,
            description: 'V2 Test Payment',
            metadata: [
                { orderId: "ORD-SDK-TEST" },
                { customerId: "test-user@example.com", isPII: true }
            ]
        }, 'v2');

        if (v2Result.success) {
            console.log(' V2 Initiation Success:', {
                depositId: v2Result.depositId,
                status: v2Result.status
            });

            // WAIT AND CHECK
            console.log(' Waiting 5 seconds for V2 propagation...');
            await new Promise(r => setTimeout(r, 5000));

            console.log(' Checking V2 Status...');
            const statusCheck = await service.checkTransactionStatus(
                v2Result.depositId,
                'v2',
                'deposit'
            );

            console.log(` Final V2 Status: [ ${statusCheck.status} ]`);
            if (statusCheck.status === 'FAILED') {
                // V2 failure messages are nested in 'data' usually
                const msg = statusCheck.data?.failureReason?.failureMessage || 'Unknown';
                console.warn(`   Reason: ${msg}`);
            }

        } else {
            console.error(' V2 Failed:', v2Result.error);
        }
    } catch (error) {
        console.error(' V2 Exception:', error.message);
    }

    console.log('\n SDK Testing Complete');
    process.exit(0);
}

// Run test if called directly
if (require.main === module) {
    testSDKConnection().catch(console.error);
}

module.exports = { testSDKConnection };

Why this is better surgically:
Notice the Intellisense. You cannot accidentally send a numeric amount when a string is required, or forget the currency field. The TypeScript definitions catch these errors before you deploy.

Step 3: The Critical Part-Handling Webhooks

Mobile money payments are asynchronous. The code above initiates the request, but the user might take 30 seconds to enter their PIN on their phone.

You cannot rely on the immediate response to confirm payment. You must rely on ID confirmation / Webhooks. Always check the authenticity of any process - in this case, you need to check the depositID returned for confirmation.
Note: Webhook logic is not implemented.

The SDK helps you define the structure of the data you will receive, and this //pawapay.js example is exactly what the SDK needs to work as it should. So if you run the test using node, the transaction will go through as expected.

The Game Changer: The Live Demo Playground

Documentation is great. SDKs are helpful. But nothing beats actually pressing a button and seeing what happens.

We realized that developers often spend hours just setting up a sandbox environment to make that very first successful API call.

We decided to kill that friction.

Introducing the Pawapay Live Playground.

👉 [https://katorymnd.dev/pawapay-demo/nodejs/]

The playground allows you to interact with the sandbox API directly from your browser without writing a single line of code.

Use the playground to:

Test Provider Availability: Instantly see which mobile money providers are online in which countries in the sandbox.
Simulate Flows: Trigger a deposit and see the exact JSON structure returned by the API.
Debug Parameters: Not sure if the phone number format for Zambia is correct? Try it in the playground first. If it works there, you know your code inputs are wrong.
View Payload Structures: Copy-paste request and response payloads directly from the playground into your unit tests.

The "Whens": Use Cases for this SDK

When should you reach for the @katorymnd/pawapay-node-sdk?

E-commerce Platforms (Node.js Backends): If you are building a custom shop using NestJS, Express, or Fastify targeting Africa, this is your payment layer.
Gig Economy & Marketplaces: You need to collect money from customers (Deposits) and automatically pay out your vendors/drivers/freelancers at the end of the week (Payouts). The SDK handles bulk payouts seamlessly.
SaaS Subscription Collection: While mobile money isn't always ideal for recurring billing, it's perfect for prepaid "top-up" models for service access.

Wrap Up

Payments in Africa are growing exponentially, and developer tooling needs to keep up. We built the Node.js SDK and the Playground to treat developer experience as a first-class citizen in the Pawapay ecosystem.

We want you to spend less time reading docs and debugging HTTP headers, and more time building your product.

Ready to dive in?

🎮 Try the Live Playground: https://katorymnd.dev/pawapay-demo/nodejs/
💾 Get the SDK on NPM: npm i @katorymnd/pawapay-node-sdk
📖 Read the Docs & Source: https://github.com/katorymnd/pawapay-node-sdk

If you try it out, please open an issue on GitHub with feedback or feature requests. We are actively iterating on this!

I Built a Mental Ritual That Doesn’t Explain Itself

katorymnddev — Tue, 16 Sep 2025 09:56:05 +0000

I didn’t build an app to solve your anxiety.

I built it to sit beside you - quietly - while you say out loud what you’ve been holding in silence.

Clean My Mind doesn’t ask for your name.

It doesn’t track your mood trends.

It doesn’t sell your thoughts to advertisers.

It asks only one thing:

Type it. Then let it go.

You open the page.

You pick a feeling from a simple menu: 😔 Low, 😡 Frustrated, 🤔 Meh.

You type one sentence — under 280 characters or 60 words — about what’s weighing on you.

Then you tap “Release & Clarify.”

And then… nothing happens.

No spinning loader.

No pop-up.

No “Here’s what we think you should do.”

Just… a response.

Gentle.

Personal.

Unprompted.

Sometimes it feels like a whisper.

Sometimes like a hand on your shoulder.

Sometimes it gives you space to breathe -without telling you to.

You don’t know how it chose that tone.

You don’t need to.

Because the magic isn’t in the mechanism.

It’s in the permission.

🛠️ The Tech? Barely There - But It’s Intentional

Under the hood, it’s vanilla JavaScript - no frameworks, no bundlers.

The UI, the mood selector, the character counter, the export generators - all run entirely in your browser.

Your entries never leave this browser unless you choose to export them.

They live in localStorage.

Turn on Privacy Mode, and they vanish when you close the tab.

There is no traditional backend storing your thoughts.

But there is a lightweight API endpoint:

/api/clean-my-mind/status

It returns this:

{
  "ok": true,
  "has_license": true,
  "remaining": 1,
  "expires_at": null
}

That’s it.

No user ID.

No IP address.

No analytics.

Just a number:

How many times can you release today?

And if it says zero?

You see this:

“Tap Check status first to confirm your Remaining value. If it shows zero, buy a small bundle.”

No pressure.

No upsell.

Just clarity.

The “magic link” login?

It binds your email to a cryptographically unique device key — derived from your browser’s ECDSA public key.

No passwords. No sessions. No cookies tracking you across devices.

You don’t log in.

You arrive.

When you pay $1 for a request, $5 for an export, or $15/month for unlimited exports -

it happens through PawaPay or Pesapal.

Direct. Local. No credit card stored.

No recurring billing.

The server only verifies payment.

It never sees your thought.

Your mind stays yours.

🌱 The Real Innovation: Silence as Design

I removed every label.

No “Soothe Mode.”

No “Advice Engine.”

No “Tweet Generator.”

Why?

Because labeling the response turns healing into a product feature.

What matters isn’t whether it reads like a journal entry or a to-do list.

What matters is that it met you where you were.

Maybe you typed:

“I’m tired of pretending I’m okay.”

And what came back wasn’t advice.

It was this:

You don’t have to be okay right now. Just being here is enough.

Or maybe you wrote:

“I keep overthinking everything.”

And the reply was simply:

Stop. Breathe. One breath. Then move.

No explanation.

No theory.

No psychology jargon.

Just presence.

And that’s the point.

We are so used to tools that analyze us -

that we’ve forgotten what it feels like to be held.

Clean My Mind doesn’t analyze.

It holds.

🔒 Privacy Isn’t a Feature. It’s the Foundation.

I’ve seen apps that promise “mental wellness” -then monetize your vulnerability.

Clean My Mind has zero telemetry.

No heatmaps.

No session recording.

No behavioral tracking.

Even the export function?

PDFs and Word files are generated entirely in-browser.

Nothing leaves your device unless you choose to save or share it.

You control what stays.

You control what goes.

And if you lose your phone?

Start again.

No password reset.

No account recovery.

No panic.

Just open the browser.

Type your email.

Receive the link.

Arrive.

Again.

💰 Monetization Without the Mess

People ask: “How do you make money?”

I don’t sell attention.

I sell permission to pause.

$1 per ritual (request)
$5 for one export
$15/month for unlimited exports

All paid directly via mobile money or card — no Stripe, no PayPal, no hidden fees.

You see the price.

You decide.

You pay.

No trials that auto-renew.

No “premium” tiers.

No dark patterns.

And if you can’t afford it?

You still get two free requests.

No questions asked.

Because peace shouldn’t be a luxury.

🧭 Why This Matters More Than Your Next SaaS

We live in a world that tells us:

“Fix yourself. Optimize. Improve. Scale.”

But healing isn’t a sprint.

It’s a breath.

Clean My Mind doesn’t scale.

It stays.

It doesn’t optimize for retention.

It optimizes for returning - not because it hooked you,

but because it gave you something you couldn’t find anywhere else:

A place where you don’t have to explain yourself.

You don’t need to justify your sadness.

You don’t need to frame your anger as “productivity blockers.”

You don’t need to turn your grief into a blog post.

You just need to say it - and know that someone (even if it’s code) heard you.

And responded -

not with advice -

but with space.

✨ Final Thought: Sometimes, the Most Radical Thing Is Doing Nothing

You don’t need another tool.

You need a moment.

A quiet pause.

A place where your thoughts are allowed to be heavy - without being fixed.

Clean My Mind isn’t perfect.

It doesn’t understand trauma.

It doesn’t diagnose depression.

It won’t cure anything.

But it remembers this:

You don’t have to fix everything to be okay.

You just have to be here.

So go ahead.

Open the page.

Type one sentence.

Tap “Release & Clarify.”

Wait.

Listen.

And when it responds…

Let it be enough.
—

👉 Try it: https://katorymnd.com/clean-my-mind/

(No signup. No tracking. No catch.)

Docs/Issue: https://github.com/katorymnd/clean-my-mind

—

You’ve carried this long enough.

Now - let it go.

Syncronaut: Smarter Syncing for a Busy Digital World

katorymnddev — Sat, 23 Aug 2025 10:07:16 +0000

In today’s world, where our lives are split between multiple folders, drives, and devices, keeping files safe and in sync is more than a technical chore-it’s survival. Anyone who has ever lost a project to a crash, overwritten the wrong folder, or fumbled with unreliable backup tools knows the frustration.

That’s exactly why I created Syncronaut-a simple, powerful, and flexible file synchronization app for Windows (with Linux builds in sight), designed for speed, reliability, and peace of mind.

Whether you’re a student managing assignments, a freelancer juggling client files, or a business user who just wants backups that work, Syncronaut is here to quietly take the stress away.

What Is Syncronaut?

Syncronaut is a desktop application built with Electron.js and PowerShell magic under the hood. At its heart, it’s a file synchronization and backup tool that gives you control over how your files are copied, mirrored, or updated.

Unlike other tools that try to be overly complicated or limited, Syncronaut focuses on three main sync modes-clear, powerful, and practical:

Fast Mode – for quick updates using Robocopy (or rsync under Linux). Perfect when you just need the latest changes mirrored without delay.
Legacy Mode – a reliable, step-by-step copy process, ensuring full compatibility even with stubborn directories.
Mirror Mode - your “cosmic twin” option. It ensures two folders (source and destination) stay identical-additions, deletions, and updates are reflected on both sides.

Think of it like this: Fast when you’re in a hurry, Legacy when you want careful backups, Mirror when you want clones.

How Syncronaut Works

At first launch, Syncronaut greets you with a clean, straightforward UI. Here’s the simple journey:

Choose Your Source and Destination
Select the folder you want to back up (say, D:\Projects) and where it should sync (e.g., E:\Backups or even a network drive).
Pick Your Mode
Decide: Fast, Legacy, or Mirror. The app shows you what each means in plain language, so even non-technical users feel confident.
Sync and Watch Progress
Hit Start Sync and Syncronaut gives you a clear log of what’s happening-files being copied, updated, skipped, or deleted. No black-box mystery.
Enjoy Peace of Mind
Once set, you can re-run syncs anytime-or schedule them with your OS tools.

Behind the scenes, Syncronaut leans on proven technologies like Robocopy (on Windows) and rsync (on Linux) but wraps them in a friendly, modern interface.

Licensing & Activation

Syncronaut comes in two flavors:

Free Edition – try it, sync with it, see the speed. Perfect for personal or light use.
Pro Edition – unlocks advanced features, unlimited usage, and premium support. Activation is handled with a PawaPay and Pesapal-powered license system, where each license is tied to a device.

This means you only pay once per device, no hidden subscriptions, no lock-in. Just fair use.

Why Syncronaut Stands Out

Plenty of sync tools exist, but here’s where Syncronaut shines:

User-Friendly, Not Overwhelming – No cryptic flags or terminal commands, but still the same power.
Flexible Modes – You decide how files are handled—speed, careful copy, or exact mirror.
Modern UI – Built with Electron.js, it looks and feels like a proper desktop app.
Built for Developers & Everyday Users – Whether you’re a coder syncing projects or a photographer backing up images, it adapts to you.
Transparent Logs – Every action is visible; no wondering “did it actually back up?”

GitHub and Open Development

The code lives proudly on GitHub:
👉 https://github.com/katorymnd/syncronaut

There, you’ll find:

Releases (portable .exe and installer versions).
Issues & Discussions where the community can help shape future versions.

Transparency is part of Syncronaut’s DNA—users can see what’s happening, report bugs, or even build features.

The Homepage

The official homepage puts everything in one place:

Download Links (Installer .exe and Portable .exe)
SHA256 Checksums for verifying file integrity
License Page for Pro activation and upgrades
Docs & Guides (installation, usage, troubleshooting)

The idea is simple: you don’t have to hunt. Everything is one click away.

Real-World Uses

Freelancers: Sync client work between laptop and external drive.
Businesses: Mirror project folders to a shared network drive for teamwork.
Students: Back up assignments automatically before exams.
Developers: Keep Git repos mirrored locally and on a backup disk.
Photographers/Artists: Copy heavy media folders quickly without risking missed files.

Roadmap & Future Plans

Syncronaut isn’t standing still. Some of the things I’m planning include:

Linux/macOS support (beyond Windows).
Scheduling syncs inside the app (not just via OS).
Cloud hooks (Google Drive, S3, etc.).
Smarter conflict resolution (detecting changed files on both sides).

Every release inches closer to making Syncronaut not just a sync tool but a backup companion you can rely on daily.

Final Thoughts

We live in a digital age where data is everything. Losing it can mean lost work, lost memories, even lost income. That’s why I built Syncronaut—not just as a technical experiment, but as a tool for peace of mind.

For the curious, the developers, the cautious, and the everyday users-Syncronaut is here to help you sync smarter, not harder.

So go ahead, explore it on GitHub, try it out for free, and if it makes your digital life smoother, consider upgrading to Pro.

Because in the end, files deserve a reliable journey—and Syncronaut is the pilot.

👉 GitHub: https://github.com/katorymnd/syncronaut
👉 Homepage:
Syncronaut

Seamless Transition: pawaPay PHP SDK Now Supports V1 and V2 Side-by-Side

katorymnddev — Tue, 12 Aug 2025 15:06:15 +0000

In the fast-moving world of fintech, upgrading APIs is often a painful, time-consuming process. Developers face tough decisions:

Do we fully switch to the new version and risk breaking existing integrations?
Or do we stay on the old version and miss out on new features?

With the latest release of the pawaPay PHP SDK (v4.4.0), we decided to break that cycle. Instead of forcing a single upgrade path, we’ve introduced dual-version support, allowing V1 and V2 to run side-by-side, instantly switchable.

Why This Matters

Zero downtime – You can keep using your existing V1 or default integration while testing V2 in parallel.
Gradual migration – Move specific endpoints to V2 at your own pace.
One codebase, both worlds – No need to maintain separate SDK installations.

What’s New in v4.4.0

Dual-version support – V1 remains the default, V2 can be enabled with a simple configuration switch.
Hosted Payment Page integration – Works with both V1 and V2 for quick payment collection via redirect.
Improved configuration structure – Separate active_conf_v1.json and active_conf_v2.json for clarity.
Updated MNO availability – Separate JSONs for each version.
Refined API client – Enhanced to handle both versions with minimal code changes.

Example: Switching Between V1 and V2


// API version switch, default v1
$apiVersion  = getenv('PAWAPAY_API_VERSION') ?: 'v1'; // switch v1 or v2

Hosted Payment Page in Action

<?php

declare(strict_types=1);

header('Content-Type: application/json');

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;
use Katorymnd\PawaPayIntegration\Utils\Helpers;
use Katorymnd\PawaPayIntegration\Utils\Validator;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Whoops\Run;
use Whoops\Handler\PrettyPageHandler;

// Dev error page
$whoops = new Run();
$whoops->pushHandler(new PrettyPageHandler());
$whoops->register();

// .env
$dotenv = Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

// Environment / token / SSL / API version
$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
// Choose API version: 'v1' or 'v2'
$apiVersion  = getenv('PAWAPAY_API_VERSION') ?: 'v1';   // Change to v1 or v2
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    echo json_encode(['success' => false, 'errorMessage' => 'API token not found for the selected environment.']);
    exit;
}

// Logging
$log = new Logger('pawaPayLogger');
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_success.log', \Monolog\Level::Info));
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_failed.log',  \Monolog\Level::Error));

// Client (version-aware)
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify, $apiVersion); 

// Inputs
$depositId            = Helpers::generateUniqueId();
$returnUrl            = isset($_POST['returnUrl']) ? trim($_POST['returnUrl']) : 'https://example.com/paymentProcessed';
$statementDescription = isset($_POST['statementDescription']) ? trim($_POST['statementDescription']) : 'ProjectPayment123';
$amount               = isset($_POST['amount']) ? trim($_POST['amount']) : '15000';
$currency             = isset($_POST['currency']) ? strtoupper(trim($_POST['currency'])) : 'UGX'; 
$msisdn               = isset($_POST['msisdn']) ? preg_replace('/\D/', '', trim($_POST['msisdn'])) : '256753456789';
$language             = isset($_POST['language']) ? strtoupper(trim($_POST['language'])) : 'EN';
$country              = isset($_POST['country']) ? strtoupper(trim($_POST['country'])) : 'UGA';
$reason               = isset($_POST['reason']) ? trim($_POST['reason']) : 'Project payment';
$metadata             = [];

// metadata can be JSON string or array
$metadataRaw = $_POST['metadata'] ?? '';

try {
    // Validate description (4–22)
    $statementDescription = Validator::validateStatementDescription($statementDescription);

    // Validate amount if provided
    if ($amount !== '') {
        $amount = Validator::symfonyValidateAmount($amount);
    }

    // Parse/validate metadata
    if ($metadataRaw !== '' && $metadataRaw !== null) {
        if (is_string($metadataRaw)) {
            $decoded = json_decode($metadataRaw, true);
            if (json_last_error() !== JSON_ERROR_NONE || !is_array($decoded)) {
                throw new InvalidArgumentException('Invalid metadata JSON.');
            }
            $metadata = $decoded;
        } elseif (is_array($metadataRaw)) {
            $metadata = $metadataRaw;
        } else {
            throw new InvalidArgumentException('Unsupported metadata format.');
        }
        if (!empty($metadata) && method_exists(Validator::class, 'validateMetadataItemCount')) {
            Validator::validateMetadataItemCount($metadata);
        }
    }

    // Build params once; client will adapt to v1/v2
    $params = [
        'depositId'            => $depositId,
        'returnUrl'            => $returnUrl,
        // V1 name; client maps to V2 'customerMessage' automatically
        'statementDescription' => $statementDescription,
        // V1 fields:
        'amount'               => $amount,
        'msisdn'               => $msisdn,
        // Common
        'language'             => $language,
        'country'              => $country,
        'reason'               => $reason,
        'metadata'             => $metadata,
    ];

    // If currency also provided, client will send amountDetails for V2 automatically
    if ($currency !== '') {
        $params['currency'] = $currency;
    }

    // Call auto (routes to v1 or v2)
    $resp = $pawaPayClient->createPaymentPageSessionAuto($params); // << UPDATED

    if (in_array($resp['status'], [200, 201], true)) {
        $redirectUrl = $resp['response']['redirectUrl'] ?? null;

        if ($redirectUrl) {
            $log->info('Payment Page session created', [
                'depositId'   => $depositId,
                'redirectUrl' => $redirectUrl,
                'response'    => $resp['response'],
            ]);

            echo json_encode([
                'success'     => true,
                'depositId'   => $depositId,
                'redirectUrl' => $redirectUrl,
                'version'     => $apiVersion, // helpful to surface
            ]);
            exit;
        }

        $log->error('No redirectUrl in successful response', ['depositId' => $depositId, 'response' => $resp['response']]);
        echo json_encode(['success' => false, 'errorMessage' => 'No redirectUrl returned by API.']);
        exit;
    }

    // Non-success HTTP status
    $log->error('Failed to create Payment Page session', ['depositId' => $depositId, 'response' => $resp]);
    echo json_encode([
        'success'      => false,
        'errorMessage' => 'Failed to create Payment Page session.',
        'status'       => $resp['status'] ?? null,
        'raw'          => $resp['response'] ?? null,
        'version'      => $apiVersion,
    ]);
    exit;
} catch (Throwable $e) {
    $log->error('Error creating Payment Page session', [
        'depositId' => $depositId,
        'error'     => $e->getMessage(),
        'trace'     => $e->getTraceAsString(),
    ]);

    echo json_encode(['success' => false, 'errorMessage' => $e->getMessage()]);
    exit;
}

Get the SDK

The full source code and examples are available on GitHub:
🔗 pawaPay PHP SDK – GitHub Repository

Introducing the Pesapal PHP SDK: Simplify Your Payment Integration

katorymnddev — Sat, 23 Nov 2024 11:42:01 +0000

Integrating payment solutions into your PHP applications just got a whole lot easier. We are thrilled to announce the release of our Pesapal PHP SDK, a robust and user-friendly library designed to streamline your interaction with the Pesapal payment gateway.

🌟 Why Pesapal PHP SDK?

Pesapal is a leading payment platform in Africa, offering secure and reliable payment processing for businesses of all sizes. However, integrating Pesapal's API directly can be time-consuming and complex. Our SDK abstracts the intricacies of the API, providing a clean and intuitive interface for developers.

Key Features

Easy Authentication: Simplifies OAuth authentication with Pesapal.
Seamless Payment Integration: Quickly initiate payments and handle callbacks.
Transaction Management: Easily check transaction statuses and process refunds.
PSR-4 Compliant: Follows PHP-FIG standards for autoloading.
Extensive Documentation: Well-documented methods and examples to get you started.

🚀 Getting Started

Installation

Install the SDK via Composer:

composer require katorymnd/pesapal-php-sdk

Requirements

PHP 8.0 or higher
Composer
Pesapal Merchant Account

Configuration

Initialize the client with your Pesapal credentials:

require 'vendor/autoload.php';

use Katorymnd\PesapalPhpSdk\Api\PesapalClient;
use Katorymnd\PesapalPhpSdk\Config\PesapalConfig;

$consumerKey = 'YOUR_CONSUMER_KEY';
$consumerSecret = 'YOUR_CONSUMER_SECRET';

// Initialize PesapalConfig and PesapalClient
$configPath = __DIR__ . '/../pesapal_dynamic.json';
$config = new PesapalConfig($consumerKey, $consumerSecret, $configPath);
$environment = 'sandbox';
$sslVerify = false; // Enable SSL verification for production


$pesapal = new PesapalClient($config, $environment, $sslVerify);

💳 Initiating a Payment

Here's how you can initiate a payment with minimal code:

use Katorymnd\PesapalPhpSdk\Utils\PesapalHelpers;

$merchantReference = PesapalHelpers::generateMerchantReference();
$notificationId = 'adbd39cc-a48e-4789-b42b-79ad8deb32df';  // Replace with actual notification ID from IPN registration

// Define the order data as an associative array for the POST request
$paymentDetails= [
    "id" => $merchantReference,
    "currency" => "USD",
    "amount" => 100.00,
    "description" => "Payment for invoice " . $merchantReference,
    "callback_url" => "https://www.example.com/payment-callback",
    "notification_id" => $notificationId,
    "redirect_mode" => "PARENT_WINDOW",
    "cancellation_url" => "https://www.example.com/payment-cancel",
    "billing_address" => [
        "phone_number" => "0700000000",
        "email_address" => "john.doe@example.com",
        "country_code" => "UG",
        "first_name" => "John",
        "middle_name" => "",
        "last_name" => "Doe",
        "line_1" => "123 Example Street",
        "line_2" => "",
        "city" => "Kampala",
        "state" => "KMP",
        "postal_code" => 256
    ]
];

// Obtain a valid access token
    $accessToken = $clientApi->getAccessToken();
    if (!$accessToken) {
        throw new PesapalException('Failed to obtain access token');
    }

// Submit order request to Pesapal
    $response = $clientApi->submitOrderRequest($orderData);

if ($response['status'] === 200 && isset($response['response']['redirect_url'])) {
        $redirectUrl = $response['response']['redirect_url'];
        $orderTrackingId = $response['response']['order_tracking_id'];

} else {
    // Handle errors
    $response['response']['error']
}

🔍 Checking Transaction Status

To check the status of a transaction:

use Katorymnd\PesapalPhpSdk\Exceptions\PesapalException;

// Obtain a valid access token
    $accessToken = $clientApi->getAccessToken();
    if (!$accessToken) {
        throw new PesapalException('Failed to obtain access token');
    }

 // Get the transaction status
    $response = $clientApi->getTransactionStatus($orderTrackingId);

if ($response['status'] === 200 && isset($response['response'])) {
        $transactionStatusData = $response['response'];
}

💰 Processing Refunds

Issue a refund with ease:


// Prepare refund data with user-provided values
$refundData = [
    'confirmation_code' => '7323605385336397404011', // the code is received by  checking the transaction status
    'amount' => 50.00,
    'username' => 'John Doe',
    'remarks' => 'Customer Requested Refund'
];

try {
    // Request Refund
    $refundResponse = $clientApi->requestRefund($refundData);

    if ($refundResponse['status'] === 200 && isset($refundResponse['response'])) {
        $refundDataResponse = $refundResponse['response'];

        // Add refund response to the output
        $responseData['refund_response'] = $refundDataResponse;
    } else {
        $errorMessage = $refundResponse['response']['error']['message'] ?? 'Unknown error occurred while requesting a refund.';
        throw new PesapalException($errorMessage);
    }
} catch (PesapalException $e) {
    // Add the error to the response
    $responseData['refund_error'] = [
        'error' => $e->getMessage(),
        'details' => $e->getErrorDetails(),
    ];
}

🧪 Testing and Development

We have included a comprehensive test suite to ensure the reliability of the SDK. To run the tests:

vendor/bin/phpunit

📄 Documentation

For detailed information on all available methods and features, please refer to our GitHub repository.

🤝 Contributing

We welcome contributions from the community! Feel free to submit issues, fork the repository, and make pull requests.

📦 Package Distribution

The SDK is available on Packagist, making it easy to include in your projects via Composer.

🛠️ Continuous Integration

We have set up continuous integration using GitHub Actions to ensure that every update maintains the highest quality standards.

🎉 Conclusion

The Pesapal PHP SDK is designed to save you time and effort, allowing you to focus on building great applications without worrying about the complexities of payment integration. We are excited to see what you build with it!

📫 Stay in Touch

GitHub: github.com/katorymnd/pesapal-php-sdk
Packagist: packagist.org/packages/katorymnd/pesapal-php-sdk

Exploring Pawapay Deposits, Refunds, and Payouts: A Hands-On Preview

katorymnddev — Thu, 07 Nov 2024 18:08:50 +0000

Exploring Pawapay Deposits, Refunds, and Payouts: A Hands-On Preview

Hello everyone! 👋

I'm excited to share a sneak peek of our latest integration with Pawapay—a mobile payment solution that streamlines deposits, refunds, and payouts. In the accompanying video, you'll see these features in action, including validation processes and the success responses from the Pawapay Mobile API.

But first, let's dive into what Pawapay offers and how it can elevate your application's payment capabilities.

📖 What is Pawapay?

Pawapay is a leading mobile money payment gateway in Africa, enabling businesses to transact seamlessly across various mobile networks and countries. With a single API, you can:

Accept deposits from users' mobile money accounts.
Process refunds efficiently.
Initiate payouts to users or vendors.

🚀 Getting Started with Pawapay Integration

Before we jump into the functionalities, ensure you've set up your Pawapay account and obtained your API credentials.

# Install the pawaPay PHP SDK via composer
composer require katorymnd/pawa-pay-integration

Authentication

Authenticate your API requests using your API key:

// Set the environment and SSL verification based on the production status
$environment = getenv('ENVIRONMENT') ?: 'sandbox'; // Default to sandbox if not specified
$sslVerify = $environment === 'production';  // SSL verification true in production

// Dynamically construct the API token key
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';

// Get the API token based on the environment
$apiToken = $_ENV[$apiTokenKey] ?? null;

💰 Deposits

Depositing funds into your application is straightforward.

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Generate a unique deposit ID using a helper method (UUID v4)
$depositId = Helpers::generateUniqueId();

// Prepare metadata if needed (up to 10 items allowed)
$metadata = [];

try {
    // Step 1: Validate the amount using Symfony validation and custom validation
    $validatedAmount = Validator::symfonyValidateAmount($amount);  // Symfony Validator for amount

    // Step 2: Use the Validator to check if the description is valid (alphanumeric and length)
    $validatedDescription = Validator::validateStatementDescription($description);

    // Step 3: Validate the number of metadata items only if metadata is provided
    if (!empty($metadata)) {
        Validator::validateMetadataItemCount($metadata);
    }

    // Step 4: Initiate the deposit using the submitted details
    $response = $pawaPayClient->initiateDeposit(
        $depositId,
        $validatedAmount,
        $currency,
        $mno,
        $payerMsisdn,
        $validatedDescription,
        $metadata
    );

    if ($response['status'] === 200) {
        // Log initiation success
        $log->info('Deposit initiated successfully', [
            'depositId' => $depositId,
            'response' => $response['response']
        ]);

        // Proceed to check the transaction status
        $statusResponse = $pawaPayClient->checkTransactionStatus($depositId, 'deposit');

        if ($statusResponse['status'] === 200) {
            $depositInfo = $statusResponse['response'][0]; // Get the deposit info
            $depositStatus = $depositInfo['status'];

            if ($depositStatus === 'COMPLETED') {
                // Log successful deposit
                $log->info('Deposit completed successfully', [
                    'depositId' => $depositId,
                    'response' => $depositInfo
                ]);

                // Send success response back to JavaScript
                echo json_encode([
                    'success' => true,
                    'transactionId' => $depositId,
                    'message' => 'Payment processed successfully.'
                ]);
            } elseif ($depositStatus === 'FAILED') {
                // Deposit failed
                $failureReason = $depositInfo['failureReason'];
                $failureCode = $failureReason['failureCode'];
                $failureMessage = FailureCodeHelper::getFailureMessage($failureCode);

                $log->error('Deposit failed', [
                    'depositId' => $depositId,
                    'failureCode' => $failureCode,
                    'failureMessage' => $failureMessage,
                    'response' => $depositInfo
                ]);

                // Send error response back to JavaScript
                echo json_encode([
                    'success' => false,
                    'errorMessage' => 'Payment failed: ' . $failureMessage
                ]);
            } else {
                // Deposit is pending or in another state
                $log->info('Deposit is in state: ' . $depositStatus, [
                    'depositId' => $depositId,
                    'response' => $depositInfo
                ]);

                // Send pending response back to JavaScript
                echo json_encode([
                    'success' => false,
                    'errorMessage' => 'Payment is processing. Please wait and check your account.'
                ]);
            }
        } else {
            // Failed to retrieve deposit status
            $log->error('Failed to retrieve deposit status', [
                'depositId' => $depositId,
                'response' => $statusResponse
            ]);
            echo json_encode([
                'success' => false,
                'errorMessage' => 'Unable to retrieve deposit status.'
            ]);
        }
    } else {
        // Log initiation failure
        $log->error('Deposit initiation failed', [
            'depositId' => $depositId,
            'response' => $response
        ]);

        // Send error response back to JavaScript
        echo json_encode([
            'success' => false,
            'errorMessage' => 'Payment initiation failed: ' . $response['response']['message']
        ]);
    }
} catch (Exception $e) {
    // Catch validation errors and display the message
    $errorMessage = "Validation Error: " . $e->getMessage();

    // Log the validation error
    $log->error('Validation error occurred', [
        'depositId' => $depositId,
        'error' => $errorMessage
    ]);

    // Send error response back to JavaScript
    echo json_encode([
        'success' => false,
        'errorMessage' => $errorMessage
    ]);
}

What happens here?

Validation: The API validates the phone number and amount.
Initiation: A deposit request is sent to the user's mobile money account.
Response: You receive a transaction ID and status.

🔄 Refunds

Processing refunds is just as simple.

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Retrieve and sanitize form data
$depositId = isset($_POST['depositId']) ? trim($_POST['depositId']) : '';
$amount = isset($_POST['amount']) ? trim($_POST['amount']) : '';

// Retrieve metadata fields from the form
$metadataFieldNames = isset($_POST['metadataFieldName']) ? $_POST['metadataFieldName'] : [];
$metadataFieldValues = isset($_POST['metadataFieldValue']) ? $_POST['metadataFieldValue'] : [];
$metadataIsPII = isset($_POST['metadataIsPII']) ? $_POST['metadataIsPII'] : [];

// Ensure that metadata fields are arrays
$metadataFieldNames = is_array($metadataFieldNames) ? $metadataFieldNames : [$metadataFieldNames];
$metadataFieldValues = is_array($metadataFieldValues) ? $metadataFieldValues : [$metadataFieldValues];
$metadataIsPII = is_array($metadataIsPII) ? $metadataIsPII : [$metadataIsPII];

// Construct metadata array
$metadata = [];
for ($i = 0; $i < count($metadataFieldNames); $i++) {
    $fieldName = trim($metadataFieldNames[$i]);
    $fieldValue = trim($metadataFieldValues[$i]);
    $isPII = isset($metadataIsPII[$i]) ? true : false;

    // Skip empty metadata fields
    if ($fieldName === '' || $fieldValue === '') {
        continue;
    }

    $metadataItem = [
        'fieldName' => $fieldName,
        'fieldValue' => $fieldValue,
    ];

    if ($isPII) {
        $metadataItem['isPII'] = true;
    }

    $metadata[] = $metadataItem;
}

// Function to validate UUID (version 4)
function isValidUUIDv4($uuid)
{
    return preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i', $uuid);
}

// Function to validate email
function isValidEmail($email)
{
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}

// Prepare the request payload (keeping it as provided)
$refundId = Helpers::generateUniqueId();  // Generate a valid UUID for the refundId
// Note: The depositId is obtained from the form
// The amount is obtained from the form
// Metadata is constructed from the form inputs

try {
    // Validate required fields
    if (empty($depositId) || empty($amount)) {
        throw new Exception('Missing required fields: Deposit ID and Refund Amount are required.');
    }

    // Validate Deposit ID
    if (!isValidUUIDv4($depositId)) {
        throw new Exception('Invalid Deposit ID format. It must be a valid UUID version 4.');
    }

    // Validate Refund Amount
    if (!is_numeric($amount) || floatval($amount) <= 0) {
        throw new Exception('Invalid Refund Amount. It must be a positive number.');
    }

    // Validate Metadata
    // Ensure predefined metadata fields are modified
    $predefinedMetadata = [
        'orderId' => 'ORD-123456789',
        'customerId' => 'customer@email.com'
    ];

    foreach ($metadata as $meta) {
        if (array_key_exists($meta['fieldName'], $predefinedMetadata)) {
            if ($meta['fieldValue'] === $predefinedMetadata[$meta['fieldName']]) {
                throw new Exception("Please update the pre-filled {$meta['fieldName']} value before submitting.");
            }

            // Additional validation for customerId
            if ($meta['fieldName'] === 'customerId' && !isValidEmail($meta['fieldValue'])) {
                throw new Exception("Please enter a valid email address for customerId.");
            }
        }
    }

    // Validate metadata count (maximum 10)
    if (count($metadata) > 10) {
        throw new Exception('You cannot add more than 10 metadata fields.');
    }

    // Prepare the data payload
    $data = [
        'refundId' => $refundId,
        'depositId' => $depositId,
        'amount' => floatval($amount),
        'metadata' => $metadata
    ];

    // Initiate the refund using ApiClient
    $response = $pawaPayClient->initiateRefund($refundId, $depositId, floatval($amount), $metadata);

    // Check the API response status
    if ($response['status'] === 200) {
        // Log refund initiation success
        $log->info('Refund initiated successfully', [
            'refundId' => $refundId,
            'depositId' => $depositId,
            'amount' => $amount,
            'metadata' => $metadata,
            'response' => $response['response']
        ]);

        // Now check the refund status
        try {
            $statusResponse = $pawaPayClient->checkTransactionStatus($refundId, 'refund');

            if ($statusResponse['status'] === 200) {
                // Log refund status retrieval success
                $log->info('Refund status retrieved successfully', [
                    'refundId' => $refundId,
                    'statusResponse' => $statusResponse['response']
                ]);

                // Send success response back to the client with refund status
                echo json_encode([
                    'success' => true,
                    'refundId' => $refundId,
                    'message' => 'Refund initiated and status retrieved successfully.',
                    'refundStatus' => $statusResponse['response']
                ]);
            } else {
                // Log failure to retrieve refund status
                $log->error('Failed to retrieve refund status', [
                    'refundId' => $refundId,
                    'statusResponse' => $statusResponse
                ]);

                // Send response indicating refund initiation success but unable to retrieve status
                echo json_encode([
                    'success' => true,
                    'refundId' => $refundId,
                    'message' => 'Refund initiated successfully, but unable to retrieve refund status.',
                    'error' => 'Unable to retrieve refund status.'
                ]);
            }
        } catch (Exception $e) {
            // Log the error
            $log->error('Error occurred while checking refund status', [
                'refundId' => $refundId,
                'error' => $e->getMessage()
            ]);

            // Send response indicating refund initiation success but error in retrieving status
            echo json_encode([
                'success' => true,
                'refundId' => $refundId,
                'message' => 'Refund initiated successfully, but an error occurred while retrieving refund status.',
                'error' => $e->getMessage()
            ]);
        }
    } else {
        // Log initiation failure
        $log->error('Refund initiation failed', [
            'refundId' => $refundId,
            'depositId' => $depositId,
            'amount' => $amount,
            'metadata' => $metadata,
            'response' => $response
        ]);

        // Extract error message from response
        $errorMessage = isset($response['response']['message']) ? $response['response']['message'] : 'Unknown error occurred.';
        echo json_encode([
            'success' => false,
            'errorMessage' => 'Refund initiation failed: ' . $errorMessage
        ]);
    }
} catch (Exception $e) {
    // Catch validation errors and return the message
    $errorMessage = $e->getMessage();

    // Log the error
    $log->error('Error occurred during refund initiation', [
        'refundId' => $refundId,
        'depositId' => $depositId,
        'amount' => $amount,
        'metadata' => $metadata,
        'error' => $errorMessage
    ]);

    // Send error response back to the client
    echo json_encode([
        'success' => false,
        'errorMessage' => $errorMessage
    ]);
}

Key Points:

Partial Refunds: You can refund any amount up to the original transaction amount.
Validation: The API checks if the transaction is eligible for a refund.

📤 Payouts

Send payouts to users or vendors effortlessly.

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Get the raw POST data (JSON) sent from the JavaScript fetch request
$data = json_decode(file_get_contents('php://input'), true);

if ($data) {
    // Access the form data in the $data array
    $recipientsData = isset($data['recipients']) ? $data['recipients'] : [];

    $responses = []; // To collect responses for each recipient

    foreach ($recipientsData as $index => $recipientData) {
        try {
            // Prepare recipient data
            $recipient = [
                'payoutId' => Helpers::generateUniqueId(), // Generate a unique payout ID for each recipient
                'amount' => $recipientData['amount'],
                'currency' => $recipientData['currency'],
                'correspondent' => $recipientData['correspondent'],
                'recipientMsisdn' => $recipientData['recipientMsisdn'],
                'statementDescription' => $recipientData['statementDescription'],
            ];

            // Prepare metadata if available
            $metadata = isset($recipientData['metadata']) ? $recipientData['metadata'] : [];

            // Validate the amount using Symfony validation
            $validatedAmount = Validator::symfonyValidateAmount($recipient['amount']);

            // Validate the description for each recipient
            $validatedDescription = Validator::validateStatementDescription($recipient['statementDescription']);

            // Initiate the payout for each recipient
            $initiateResponse = $pawaPayClient->initiatePayout(
                $recipient['payoutId'],
                $validatedAmount,
                $recipient['currency'],
                $recipient['correspondent'],
                $recipient['recipientMsisdn'],
                $validatedDescription,
                $metadata
            );

            // Simulate a short delay
            sleep(2); // Reduced delay for better performance

            // Check the payout status
            $statusResponse = $pawaPayClient->checkTransactionStatus($recipient['payoutId'], 'payout');

            // Prepare the final response based on the payout status
            if ($statusResponse['status'] === 200 && isset($statusResponse['response'][0]['status']) && $statusResponse['response'][0]['status'] === 'COMPLETED') {
                // Payout completed successfully
                $responses[] = [
                    'recipientMsisdn' => $recipient['recipientMsisdn'],
                    'success' => true,
                    'details' => sprintf(
                        'Payout of %s %s to %s was completed successfully with Payout ID: %s.',
                        $validatedAmount,
                        $recipient['currency'],
                        $recipient['recipientMsisdn'],
                        $recipient['payoutId']
                    ),
                    'response' => $statusResponse['response']
                ];
                $log->info('Payout completed successfully', [
                    'payoutId' => $recipient['payoutId'],
                    'response' => $statusResponse['response']
                ]);
            } else {
                // Payout failed
                $failureReason = $statusResponse['response'][0]['failureReason']['failureMessage'] ?? 'Unknown error';
                $responses[] = [
                    'recipientMsisdn' => $recipient['recipientMsisdn'],
                    'success' => false,
                    'details' => sprintf(
                        'Payout of %s %s to %s failed with Payout ID: %s. Reason: %s.',
                        $validatedAmount,
                        $recipient['currency'],
                        $recipient['recipientMsisdn'],
                        $recipient['payoutId'],
                        $failureReason
                    ),
                    'error' => $failureReason
                ];
                $log->error('Payout failed', [
                    'payoutId' => $recipient['payoutId'],
                    'error' => $failureReason
                ]);
            }

        } catch (Exception $e) {
            // Catch validation errors and display the message
            $responses[] = [
                'recipientMsisdn' => $recipientData['recipientMsisdn'],
                'success' => false,
                'details' => sprintf(
                    'Payout of %s %s to %s failed during processing. Reason: %s.',
                    $recipientData['amount'],
                    $recipientData['currency'],
                    $recipientData['recipientMsisdn'],
                    $e->getMessage()
                ),
                'error' => $e->getMessage()
            ];
            // Log the error if payoutId is set, else log with recipient info
            $log->error('Payout processing error', [
                'recipientMsisdn' => $recipientData['recipientMsisdn'],
                'error' => $e->getMessage()
            ]);
        }
    }

    // Summarize the outcome of all payout attempts
    $successfulCount = count(array_filter($responses, fn ($item) => $item['success']));
    $failedCount = count($responses) - $successfulCount;

    // Return the responses as JSON
    $response = [
        'success' => $failedCount === 0,
        'message' => sprintf(
            'Payout processing completed. %d successful and %d failed.',
            $successfulCount,
            $failedCount
        ),
        'responses' => $responses,
        'total_recipients' => count($recipientsData)
    ];

    echo json_encode($response, JSON_PRETTY_PRINT);

} else {
    // Handle the error (if no data received)
    $response = [
        'success' => false,
        'message' => 'No data received.'
    ];
    echo json_encode($response, JSON_PRETTY_PRINT);
}

Notes:

Multiple Currencies: Support for various African currencies.
Compliance: Automatically handles compliance and regulatory requirements.

✅ Success Responses

Understanding the API responses is crucial for seamless integration.

Deposit Success Response:

 // Send success response back to JavaScript
                echo json_encode([
                    'success' => true,
                    'transactionId' => $depositId,
                    'message' => 'Payment processed successfully.'
                ]);

Refund Success Response:

 // Send success response back to the client with refund status
                echo json_encode([
                    'success' => true,
                    'refundId' => $refundId,
                    'message' => 'Refund initiated and status retrieved successfully.',
                    'refundStatus' => $statusResponse['response']
                ]);

Payout Success Response:

// Summarize the outcome of all payout attempts
    $successfulCount = count(array_filter($responses, fn ($item) => $item['success']));
    $failedCount = count($responses) - $successfulCount;

    // Return the responses as JSON
    $response = [
        'success' => $failedCount === 0,
        'message' => sprintf(
            'Payout processing completed. %d successful and %d failed.',
            $successfulCount,
            $failedCount
        ),
        'responses' => $responses,
        'total_recipients' => count($recipientsData)
    ];

    echo json_encode($response, JSON_PRETTY_PRINT);

These responses help you update your application's state and notify users accordingly.

🎥 Watch It in Action!

The video at the top showcases all these features with live validation and API interactions. You'll see how deposits, refunds, and payouts work seamlessly, along with the success responses from Pawapay.

🔗 Useful Links

🌟 Conclusion

Integrating Pawapay opens up a world of possibilities for handling mobile money transactions in your application. I hope this post and the accompanying video provide valuable insights into what you can achieve.

Feel free to reach out or leave a comment—let's build something amazing together!

Simplifying Mobile Money Integration in PHP with the pawaPay SDK

katorymnddev — Sun, 20 Oct 2024 18:54:50 +0000

Integrating mobile money into your PHP applications can feel like walking a tightrope between convenience and complexity. From managing payment gateways to ensuring security across multiple countries, it’s easy to get overwhelmed. But with the pawaPay SDK, those challenges melt into the background, replaced by a straightforward, elegant solution that turns complexity into simplicity. The SDK bridges the gap between your business and Africa’s vast mobile money ecosystem, handling the intricate details so you can focus on what matters most—building and growing your business.

The Common Challenges of Mobile Money Integration

Before we dive into how the pawaPay SDK simplifies the process, it's essential to understand the hurdles developers face when integrating mobile money payments:

Fragmentation Across Providers

Mobile money operates across various platforms, each with its unique APIs and protocols. This fragmentation makes it difficult to create a unified experience, especially when targeting multiple African countries.
Security and Fraud Prevention

Payment systems are prime targets for fraud, and ensuring a secure, reliable transaction flow can be incredibly time-consuming. Developers need to implement robust security measures to protect both their business and customers.
Scalability Issues

Handling a few payments is one thing; handling thousands or millions across different countries with varying mobile operators is a different beast altogether. Building a system that can scale efficiently without performance drops is a key challenge.
Error Handling

Payments can fail for a multitude of reasons—network issues, insufficient funds, or operator errors. Managing these failures and providing useful feedback to both developers and end-users is critical.

How the pawaPay SDK Simplifies the Process

The pawaPay SDK was designed with developers in mind, offering solutions to each of these challenges through an intuitive interface that abstracts the complex logic and operations involved in mobile money payments. Here’s how:

1. Unified API Across Providers and Countries

One of the standout features of the pawaPay SDK is its ability to integrate with all major mobile money operators across Africa. Instead of writing custom code for each operator, developers use a single, unified API that handles all interactions behind the scenes. Whether you're working with MTN in Ghana or Safaricom in Kenya, the SDK takes care of the integration, allowing you to focus on your application logic without worrying about the intricacies of individual providers.

With pawaPay’s SDK scalable infrastructure, expanding into new markets becomes less about rewriting code and more about adjusting configuration. The SDK's flexibility ensures you can easily add more countries and operators as your business grows.

2. Built-In Security Features

Security is not something you want to leave to chance when handling payments. The pawaPay SDK includes robust security features, such as data encryption, secure token handling, and fraud detection mechanisms. It helps shield your transactions from bad actors, reducing the likelihood of fraud and ensuring your customers' data remains secure.

Additionally, the SDK supports fast settlements with no chargebacks, ensuring peace of mind for your business. By relying on pawaPay SDK’s secure infrastructure, you save time that would otherwise be spent on complex security implementations and compliance issues.

3. Effortless Scalability

The pawaPay SDK is built with scalability at its core. Whether you’re processing a few payments or scaling to millions of transactions daily, the SDK ensures that your payment operations remain smooth and efficient. By abstracting away much of the complexity involved in managing high-volume transactions, pawaPay allows you to focus on growth without worrying about system bottlenecks.

4. Simplified Error Handling with Monolog

Handling errors in payment transactions can be tricky, but the pawaPay SDK makes this process far easier. It comes with built-in error handling powered by Monolog, one of the most reliable logging libraries available. This means that whether there’s a network disruption or a failed payment, the SDK provides detailed logs and actionable insights to resolve issues quickly.

The SDK also ensures that you get real-time feedback on transaction statuses, enabling your application to respond dynamically and improving the overall user experience. By streamlining error handling, pawaPay SDK removes much of the frustration associated with debugging payment issues.

A Developer-Friendly Experience

Beyond solving the major challenges of mobile money integration, the pawaPay SDK offers a developer-friendly experience that reduces friction at every turn. Installation is straightforward, and thorough documentation is available to guide you through every step. With pre-configured functions, developers can easily create deposits, refunds, payouts and monitor payments without having to dive deep into complex code.

The sandbox environment allows you to simulate transactions, ensuring your integration works flawlessly before going live. This feature alone saves hours of time that would otherwise be spent troubleshooting.

Conclusion

Integrating mobile money payments into PHP applications can feel daunting, but the pawaPay SDK takes the heavy lifting out of the process. By addressing the common challenges—fragmentation, security, scalability, and error handling—the SDK transforms what was once a complex task into a seamless experience. With its unified API, built-in security, scalability, and comprehensive error handling, pawaPay SDK empowers businesses to connect with Africa’s growing mobile money ecosystem effortlessly.

For PHP developers, the pawaPay SDK isn’t just a tool—it’s a solution that removes barriers, giving you the freedom to build, innovate, and grow without getting bogged down by the technicalities of mobile money integration.

Developing Progressive Web Apps (PWAs) with SvelteKit

katorymnddev — Wed, 18 Sep 2024 15:48:53 +0000

Progressive Web Apps (PWAs) have become a game-changer in the world of web development, combining the best of web and mobile apps. PWAs offer fast, reliable, and engaging experiences that work offline and can be installed on devices just like native applications.

In this tutorial, I'll walk you through building a PWA using SvelteKit, a modern framework for building highly optimized web applications. SvelteKit's server-side rendering (SSR) and static site generation (SSG) make it an excellent choice for PWAs.

Why SvelteKit for PWAs?

SvelteKit offers a powerful combination of simplicity and performance. With SvelteKit:

Simplicity: The reactive, component-based structure of SvelteKit makes it easy to build web apps.
Performance: Svelte compiles your code to highly optimized JavaScript, leading to fast load times and minimal overhead.
PWA Features: With SvelteKit, you can easily configure service workers and other PWA functionalities.

Step 1: Setting Up a New SvelteKit Project

First, let's create a new SvelteKit project.

Install Node.js: Make sure you have Node.js installed on your machine. You can download it here.
Create a new SvelteKit project:

   npm create svelte@latest my-pwa-app
   cd my-pwa-app
   npm install

Run the project:

   npm run dev

This will start a development server and open the default SvelteKit project in your browser. You should see the "Welcome to SvelteKit" page.

Step 2: Setting Up the PWA Manifest

A PWA requires a web app manifest file, which provides metadata about your app (such as the name, icons, and theme colors). Let’s add this to your SvelteKit project.

Create a manifest.json file in the static/ directory:

   {
     "name": "My PWA App",
     "short_name": "PWA App",
     "description": "A Progressive Web App built with SvelteKit",
     "start_url": "/",
     "display": "standalone",
     "background_color": "#ffffff",
     "theme_color": "#ff3e00",
     "icons": [
       {
         "src": "/icons/icon-192x192.png",
         "sizes": "192x192",
         "type": "image/png"
       },
       {
         "src": "/icons/icon-512x512.png",
         "sizes": "512x512",
         "type": "image/png"
       }
     ]
   }

Add some icons to your project by placing them inside a static/icons/ folder. You can generate icons of different sizes using tools like Real Favicon Generator.
In your src/routes/__layout.svelte, link the manifest and add meta tags for mobile and theme color:

   <head>
     <link rel="manifest" href="/manifest.json" />
     <meta name="theme-color" content="#ff3e00" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
   </head>

Step 3: Configuring Service Workers

A service worker enables your app to work offline by caching essential assets. Let’s configure it in SvelteKit.

Install the vite-plugin-pwa plugin:

   npm install vite-plugin-pwa --save-dev

Modify your vite.config.js to register the service worker:

   import { defineConfig } from 'vite';
   import { sveltekit } from '@sveltejs/kit/vite';
   import { VitePWA } from 'vite-plugin-pwa';

   export default defineConfig({
     plugins: [
       sveltekit(),
       VitePWA({
         registerType: 'autoUpdate',
         manifest: {
           name: 'My PWA App',
           short_name: 'PWA App',
           theme_color: '#ff3e00',
           icons: [
             {
               src: '/icons/icon-192x192.png',
               sizes: '192x192',
               type: 'image/png'
             },
             {
               src: '/icons/icon-512x512.png',
               sizes: '512x512',
               type: 'image/png'
             }
           ]
         },
         workbox: {
           runtimeCaching: [
             {
               urlPattern: /^https:\/\/fonts\.googleapis\.com\//,
               handler: 'CacheFirst',
               options: {
                 cacheName: 'google-fonts-stylesheets'
               }
             },
             {
               urlPattern: /^https:\/\/fonts\.gstatic\.com\//,
               handler: 'CacheFirst',
               options: {
                 cacheName: 'google-fonts-webfonts',
                 expiration: {
                   maxEntries: 30,
                   maxAgeSeconds: 60 * 60 * 24 * 365
                 }
               }
             }
           ]
         }
       })
     ]
   });

Add offline caching strategies by configuring runtime caching for specific assets, such as fonts or API responses.
When you rebuild your project (npm run build), the service worker will be generated automatically and registered in your app.

Step 4: Testing and Deploying Your PWA

You can now test your PWA features, including offline capabilities and installability.

Test the PWA in Chrome:
- Open Chrome DevTools.
- Go to the "Application" tab and look for the "Service Workers" section to verify that the service worker is active.
- You can also check the "Manifest" section to see if the PWA manifest is recognized.
Deploy the app:
- Deploy your app on platforms like Vercel, Netlify, or any static hosting provider.
- Once deployed, you can test the installation process by visiting your app on mobile and using the "Add to Home Screen" feature.

Conclusion

By following these steps, you've built a fully functional Progressive Web App using SvelteKit! You've seen how to integrate PWA features such as the app manifest and service workers into your SvelteKit project. PWAs are a great way to create fast, reliable, and engaging user experiences that work offline and feel like native apps.

The Future of Freelancing: Decentralized Networks and Blockchain-Powered Platforms

katorymnddev — Wed, 28 Aug 2024 13:49:42 +0000

The freelance economy has seen significant growth in recent years, with more professionals opting for the flexibility and autonomy it offers. However, traditional freelance platforms often come with their own set of challenges, such as high fees, payment delays, and a reliance on centralized systems that can limit freedom. As technology evolves, we are beginning to see the emergence of a new model that could revolutionize the freelance industry: decentralized freelance networks powered by blockchain technology.

What are Decentralized Freelance Networks?

Decentralized freelance networks are platforms that operate on blockchain technology, removing the need for intermediaries like traditional freelance marketplaces. In these networks, freelancers and clients can connect directly, negotiate terms, and execute agreements without the need for a third party. Payments are handled via smart contracts, ensuring transparency, security, and efficiency.

How Blockchain Empowers Freelancers

Blockchain technology offers several key advantages for freelancers:

Instant Payments: One of the most significant benefits of blockchain is the ability to facilitate instant payments through cryptocurrencies. Smart contracts automatically release funds once the agreed-upon work is completed, eliminating payment delays.
Lower Fees: Traditional freelance platforms often charge high fees for their services. Decentralized networks can significantly reduce or even eliminate these fees, allowing freelancers to keep more of their earnings.
Greater Autonomy: Decentralized platforms are not controlled by any single entity. This means freelancers have greater control over their work, contracts, and payments, without the risk of being subject to arbitrary changes in platform policies.
Global Reach: Blockchain is inherently global, enabling freelancers to work with clients from anywhere in the world without worrying about currency exchange issues or cross-border payment complications.

The Role of Smart Contracts

Smart contracts are self-executing agreements with the terms of the contract directly written into code. In a decentralized freelance network, smart contracts ensure that once the conditions of the contract are met, payment is automatically released to the freelancer. This system minimizes disputes, enhances trust, and speeds up the payment process.

Potential Challenges and Considerations

While the potential for decentralized freelance networks is promising, there are still challenges to consider:

Adoption: Widespread adoption of blockchain and decentralized networks will take time. Freelancers and clients need to be educated on how to use these platforms and understand the benefits they offer.
Regulation: As with any new technology, there are regulatory concerns. Governments and financial institutions are still figuring out how to regulate cryptocurrencies and blockchain technology, which could impact the growth of decentralized freelance networks.
Technical Barriers: While blockchain technology is becoming more accessible, there is still a technical learning curve. Freelancers and clients who are not tech-savvy may find it challenging to navigate these platforms initially.

The Future of Freelancing

Decentralized freelance networks represent a bold new direction for the gig economy. By leveraging blockchain technology, these platforms offer greater transparency, efficiency, and autonomy for freelancers. As more professionals seek alternatives to traditional work structures, decentralized networks could become a significant force in the freelance market.

As we look to the future, it's clear that technology will continue to shape and redefine the way we work. Decentralized freelance networks have the potential to empower freelancers like never before, creating a more equitable and efficient marketplace for talent.

Conclusion

The rise of decentralized freelance networks powered by blockchain technology could transform the freelance industry, offering benefits such as instant payments, lower fees, and greater autonomy. While there are challenges to overcome, the potential for these networks to create a more transparent and efficient freelance ecosystem is undeniable. As the freelance economy continues to grow, embracing these new technologies could pave the way for a more decentralized, equitable future.

Feel free to share your thoughts on this topic in the comments below, or connect with me if you’d like to discuss how blockchain technology is shaping the future of freelancing!

Streamline Your Coding Workflow with Remote File Sync for VS Code

katorymnddev — Tue, 27 Aug 2024 14:24:10 +0000

In the fast-paced world of software development, efficiency is key. The tools we use can make or break our workflow, and having the right extensions in your IDE can significantly boost productivity. Remote File Sync for VS Code is one such extension that can transform the way you manage files across remote servers and cloud storage directly within Visual Studio Code.

Why Remote File Sync?

Remote File Sync is designed to bridge the gap between your local development environment and remote servers. It eliminates the need for external FTP clients or complex command-line operations by integrating file synchronization directly into VS Code. This means you can manage, edit, and sync files across multiple platforms without ever leaving your editor.

Core Features

1. Multiple Protocol Support

Remote File Sync supports various protocols, including SFTP, FTP, SSH, WebDAV, and Google Drive. Whether you're working with traditional servers or modern cloud storage, this extension has the flexibility to handle your needs.

2. Real-Time Synchronization

With real-time synchronization, changes made to local files are immediately reflected on the remote server. This ensures that your work is always up-to-date, reducing the chances of version conflicts and making collaboration easier.

3. Efficient Connection Management

The extension uses connection pooling to manage FTP clients, optimizing resources and improving the speed and reliability of file transfers. This feature is particularly useful when working with large files or multiple connections.

4. User-Friendly Interface

Remote File Sync integrates seamlessly into the VS Code interface, offering a clean and intuitive file management experience. The sync panel allows you to view and manage your remote file tree, initiate uploads or downloads, and monitor sync status—all from within the editor.

5. Customizable Sync Settings

Every developer has a unique workflow, and Remote File Sync accommodates all. By automated syncing control, the extension is configured to match your workflow perfectly.

How to Get Started

Getting started with Remote File Sync is straightforward. You can install the extension from the Visual Studio Code Marketplace and set up your remote connections within minutes. The extension's documentation provides detailed guidance to help you configure your setup and start syncing files right away.

Who Can Benefit?

This extension is ideal for web developers, DevOps engineers, and anyone who regularly interacts with remote servers or cloud storage. By bringing remote file management into VS Code, Remote File Sync allows you to streamline your workflow, reduce context switching, and stay focused on coding.

Conclusion

Incorporating Remote File Sync into your development toolkit can have a profound impact on your productivity. By simplifying remote file management and integrating it directly into VS Code, this extension allows you to focus on what really matters—writing great code. Whether you're deploying code, managing a server, or collaborating with a team, Remote File Sync is the tool you need to keep your workflow smooth and efficient.

🚀 Introducing Remote File Sync for VS Code: Your Ultimate Tool for Seamless File Management

katorymnddev — Mon, 26 Aug 2024 19:05:14 +0000

Managing remote files can be a hassle, especially when you're working on multiple projects spread across different servers and cloud storage platforms. But what if there was a way to streamline your workflow and synchronize files effortlessly within your favorite code editor? Introducing Remote File Sync for VS Code – the extension designed to make your life easier!

🛠️ What is Remote File Sync?

Remote File Sync is a powerful VS Code extension that allows you to sync and manage files between your local machine and remote servers or cloud storage providers like FTP, SFTP, SSH, WebDAV, and Google Drive – all without leaving your editor. Whether you're a developer, system administrator, or just someone who works with remote files, this tool is designed with you in mind.

✨ Key Features

Multi-Protocol Support: Seamlessly connect to FTP, SFTP, SSH, WebDAV, and Google Drive.
Automatic File Synchronization: Keep your files up-to-date without the hassle of manual syncing.
VS Code Workspace Integration: Work on your projects directly within VS Code, with full integration into your workspace.

🎯 Why Choose Remote File Sync?

Remote File Sync is built to be lightweight, fast, and reliable. With its seamless integration into VS Code, you can focus on coding while it handles the file management for you. No more switching between apps or manually transferring files – just pure productivity!

🛠️ Getting Started

Getting started with Remote File Sync is a breeze. You can find the extension on the VS Code Marketplace. Installation is just a click away, and you'll be up and running in no time!

📚 Tutorials and Guides

Need help getting started or looking for advanced tips? Check out our detailed tutorials and guides:

Getting Started with Remote File Sync: A beginner's guide to installation and setup.
How to Configure FTP, SFTP, SSH, and WebDAV: Step-by-step instructions for each protocol.
Configuring Google Drive: Learn how to integrate Google Drive with your VS Code setup.
Using the Sync Panel: Discover how to monitor and manage file sync in real-time.
Common Troubleshooting Tips: Solutions to common issues.

💡 Get Involved

We’re always looking for feedback. If you have suggestions or want to report an issue, head over to our GitHub repository. We’d love to hear from you!

🚀 Ready to Supercharge Your Workflow?

Don’t let remote file management slow you down. Download Remote File Sync for VS Code today and experience seamless file synchronization like never before.

Get It Now

Boost Engagement with Katorymnd Reaction Process Plugin

katorymnddev — Sat, 13 Jul 2024 06:31:16 +0000

Engaging your audience is crucial for any website's success, and reactions to content can significantly enhance user interaction. The Katorymnd Reaction Process Plugin for WordPress is designed to help you do just that. In this article, we'll dive into what this plugin offers, how it works, and how you can get started with it to boost your website's engagement.

What is the Katorymnd Reaction Process Plugin?

The Katorymnd Reaction Process Plugin is a powerful tool for WordPress websites that allows visitors to react to your content with a variety of emotions. This plugin provides a simple and intuitive way for users to express their feelings about your posts, making your content more interactive and engaging.

Key Features

Multiple Reaction Options: Users can choose from a range of reactions, such as like, love, wow, sad, and angry.
Customizable Design: The plugin is highly customizable, allowing you to match the reaction icons and colors to your website's theme.
Real-time Analytics: Track which reactions are most popular on your posts and understand your audience better.
User-Friendly Interface: Easy to install and set up, even for those with minimal technical skills.
Mobile Responsive: Ensures that reactions look great on all devices, from desktops to smartphones.

Why Use the Katorymnd Reaction Process Plugin?

Engagement is key to keeping visitors on your site and encouraging them to return. By offering a way for users to react to your content, you:

Increase Interaction: Visitors are more likely to engage with your content if they can quickly react to it.
Gather Feedback: Understand what type of content resonates most with your audience.
Boost SEO: Increased engagement can lead to higher search engine rankings.

How to Install and Use the Plugin

Download the Plugin:
- Visit the WordPress plugin repository or search for "Katorymnd Reaction Process Plugin" directly from your WordPress dashboard.
Install the Plugin:
- From your WordPress dashboard, go to Plugins > Add New.
- Search for "Katorymnd Reaction Process Plugin."
- Click "Install Now" and then "Activate."
Configure the Plugin:
- After activation, go to Settings > Katorymnd Reactions.
- Customize the reaction icons, colors, and positions as per your website's design.
Add Reactions to Your Posts:
- Edit any post or page where you want to enable reactions.
- In the post editor, you'll find the option to add reaction buttons.

Tips for Maximizing Engagement

Encourage Interaction: Prompt your readers to react to your content at the end of each post.
Analyze Data: Regularly check the analytics provided by the plugin to see which reactions are most common and tailor your content accordingly.
Stay Updated: Keep the plugin updated to benefit from new features and improvements.

The Katorymnd Reaction Process Plugin is a must-have tool for any WordPress site looking to boost user engagement. Its easy installation, customization options, and insightful analytics make it a valuable addition to your website. Download the plugin today and enhance your audience's interaction with your content.