Getting Started

The pawaPay Node.js SDK is an enterprise-grade wrapper that simplifies mobile money operations. It handles validation, logging, and version-aware API calls out of the box.

Active Environment:

Current: environment: "sandbox"

Surgical Handshake: In production mode, the SDK requires an SSL-verified connection and validates your PAWAPAY_SDK_LICENSE_DOMAIN binding before authorizing the ApiClient.

Version Comparison: v1 vs v2

The SDK is version-aware. Depending on your choice, the internal payload structure changes to match pawaPay's standards:

Legacy (v1)
Uses correspondent and msisdn fields. Best for simple integrations.
description → statementDescription

Modern (v2)
Uses provider and MMO structure. Supports advanced metadata and tracking.
description → customerMessage

Implementation Logic


                    const client = new ApiClient({

                      apiToken: process.env.PAWAPAY_SANDBOX_API_TOKEN,

                      environment: "sandbox",

                      apiVersion: "v2",

                      sslVerify: false,

                      licenseKey: process.env.KATORYMND_PAWAPAY_SDK_LICENSE_KEY

                    });

Installation & Core Setup

The @katorymnd/pawapay-node-sdk comes pre-configured with all necessary production dependencies. Installing the SDK automatically satisfies requirements for logging, validation, and API communication.

Terminal


                    # Using NPM

                    npm install @katorymnd/pawapay-node-sdk


                    # Using PNPM (Recommended for v10+)

                    pnpm add @katorymnd/pawapay-node-sdk

SDK Bundle Insights

The following core dependencies are bundled and initialized during the installation of the sdk:

Winston (^3.18.3)
Handles surgical logging for payment_success.log and payment_failed.log.

Joi (^18.0.1)
Used for schema validation of amount, MSISDN, and currency before API dispatch.

Axios (^1.12.2)
Managed HTTP client for secure v1/v2 handshakes with pawaPay servers.

Libphonenumber-js
Ensures payer MSISDNs are valid for African mobile network operators.

Recommended Project Structure

To ensure logs and environment variables are mapped correctly, align your project as follows:

my-app/

                ├── logs/              # Auto-generated: Success & Error logs

                ├── src/

                │   └── payments/    # Your custom pawaPay logic

                ├── .env              # Contains your Master Keys & License

                └── package.json      # Includes @katorymnd/pawapay-node-sdk

Engine Requirement: Ensure you are running Node.js >= 14.0.0 and pnpm >= 8.0.0 for optimal performance.

License Activation & Domain Binding

Activation is a one-time surgical handshake that unlocks production API access and enterprise features. The @katorymnd/pawapay-node-sdk utilizes a Dual-Locking system to ensure license integrity.

Dual-Locking Security: Your license is cryptographically bound to both the Domain Name and a unique Server Fingerprint. If you move your installation to a new server, a transfer or removal is required.

Step-by-Step Validation

1. Locate Credentials Retrieve your 32-character LICENSE_KEY and LICENSE_SECRET. These are generated upon successful checkout.

2. Configure Environment Input your keys into your .env. The SDK automatically extracts these during ApiClient initialization.

3. TOFU Handshake The SDK uses Trust-On-First-Use. On the first run, it captures your server_fingerprint and installation_imprint, locking the key to your specific hardware.

4. Heartbeat Sync The SDK sends a background heartbeat to /api/appLicense/heartbeat to maintain activation health and check for remote suspensions.

Licensing Error Codes (API Response)

When an activation or validation request fails, the API returns a valid: false or activated: false response with one of the following reasons:

fingerprint_mismatch
Security Lock: This domain is already bound to a different server fingerprint or installation imprint.

limit_reached
Threshold Met: All allowed activation slots for this licenseKey are currently in use.

activation_required
Fresh Key: The license exists but hasn't undergone the initial activate-domain handshake yet.

expired
Validity End: The valid_until timestamp has passed. Production traffic is now blocked.

license_revoked
Admin Action: License suspended due to non-payment, refund, or policy violation.

not_found
Missing Record: The provided licenseKey does not exist in the Katorymnd database.

Environment Configuration

The @katorymnd/pawapay-node-sdk uses a strictly decoupled configuration model. We recommend managing your credentials via a .env file at the project root to ensure security and portability.

Security Warning: Never commit your .env file to version control. Ensure .env is added to your .gitignore to prevent leaking Master Keys or License Secrets.

Required Variables (.env)

# PawaPay API Configuration


                    PAWAPAY_SANDBOX_API_TOKEN=your_sandbox_api_token_here

                    PAWAPAY_PRODUCTION_API_TOKEN=your_production_api_token_here

# Katorymnd SDK Licensing (Required for Production and sandbox)


                    KATORYMND_PAWAPAY_SDK_LICENSE_KEY=your_sdk_license_key_here

                    PAWAPAY_SDK_LICENSE_DOMAIN=your-licensed-domain.com

                    PAWAPAY_SDK_LICENSE_SECRET=your_sdk_license_secret_here

Variable Definitions

PAWAPAY_ENV
Set to sandbox for testing or production for live money. The SDK automatically selects the corresponding token.

LICENSE_SECRET
A secondary cryptographic key used to prevent "License Spoofing" during the domain handshake.

LICENSE_DOMAIN
The canonical domain name (e.g., your-domain.com) where the SDK is authorized to run.

Production Handshake Logic

When environment = "sandbox", //change `production/sandbox`, the SDK executes a POST /validate request to the Katorymnd API. If the environment variables do not match the surgical record in the database, the ApiClient will throw a fingerprint_mismatch exception and halt execution.

Troubleshooting & Diagnostics

The @katorymnd/pawapay-node-sdk utilizes the FailureCodeHelper utility to normalize various MNO responses. Check your logs/payment_failed.log for these specific rejection and failure codes.

1. Licensing & Connection Errors

fingerprint_mismatch
Cause: Server hardware/imprint changed.
Fix: Contact Support for assistance.

AUTHENTICATION_ERROR
Cause: Your PAWAPAY_API_TOKEN is invalid or expired.
Fix: Verify the token in your pawaPay dashboard matches your .env.

ECONNREFUSED
Cause: Firewall blocking port 443.
Fix: Whitelist katorymnd.com and pawapay.io api.

2. Initiation Rejections (v1 / v2)

These errors occur during the initiateDeposit phase if the request parameters are malformed or unauthorized.

INVALID_AMOUNT
Message: The amount is not valid for this provider.
Fix: Ensure the amount is a positive number with max 2 decimal places.

AMOUNT_OUT_OF_BOUNDS
Message: The amount is outside provider limits.
Fix: Check the specific MNO (MTN/Airtel) min/max transaction limits.

INVALID_PHONE_NUMBER
Message: The phone number format is invalid.
Fix: Ensure the MSISDN follows the E.164 format (e.g., 2567...).

3. Processing Failures

These codes are returned after a successful initiation, typically when the MNO or the Payer rejects the transaction.

INSUFFICIENT_BALANCE
Cause: Payer has reached their wallet limit or has insufficient funds.
Fix: Transaction is terminal. Ask the customer to top up.

PAYMENT_NOT_APPROVED
Cause: Customer cancelled the USSD prompt or timed out.
Fix: Ask the customer to keep their phone unlocked and retry.

PAYMENT_IN_PROGRESS
Cause: Payer already has an active USSD prompt pending.
Fix: Wait for the previous transaction to expire before retrying.

Debugging Hint: The FailureCodeHelper automatically aliases legacy V1 codes (like AMOUNT_TOO_SMALL) to their V2 equivalents (AMOUNT_OUT_OF_BOUNDS) for consistent logging.

Support & Technical Assistance

If you encounter challenges during the integration of the @katorymnd/pawapay-node-sdk, our engineering team is available to assist you. To ensure the fastest resolution, please follow the diagnostic steps below before reaching out.

GitHub Issues

For core SDK bugs, performance regressions, or feature requests.

→ Open Issue

Email Support

For integration logic, private server debugging, or licensing help.

→ Email Engineering

Ticket Checklist

When requesting technical support, please include the following data to skip the triage phase:

• SDK Version: Found in package.json (e.g., v1.1.0).
• Environment: Sandbox or Production.
• Correlation ID: The depositId or transactionId from your logs.
• Error Object: A copy of the JSON response from payment_failed.log.
• Node Version: Output of node -v.

Guaranteed Response Times

Standard Support
Included with Starter and Pro licenses. Responses within 24-48 business hours.

Priority Support
Included with Agency and Enterprise licenses. Direct channel access within 6-12 hours.

"Empowering African fintech through surgical engineering."