Getting Started

The pawaPay Python SDK is a fully typed, asynchronous wrapper powered by a native core for industrial-grade performance and security. It handles the heavy lifting of mobile money integration so you can focus on building your product.

🐍 Python 3.8+ async/await VM Core
Active Environment:
Current: 'environment': 'sandbox'
🔒 Surgical Handshake: The SDK requires an SSL-verified connection and validates your KATORYMND_PAWAPAY_SDK_LICENSE_KEY via HMAC-SHA256 signature before unlocking VM bytecode.

Quick Start Code

import asyncio
import os
from src.api.ApiClient import ApiClient

async def main():
    config_dict = {
        'api_token': os.getenv("PAWAPAY_SANDBOX_API_TOKEN"),
        'environment': "sandbox",
        'api_version': "v2",
        'ssl_verify': True,
        'license_key': os.getenv("KATORYMND_PAWAPAY_SDK_LICENSE_KEY")
    }

    client = ApiClient(config_dict)

if __name__ == "__main__":
    asyncio.run(main())

Installation & Core Setup

The katorymnd-pawapay-python-sdk package comes with a specialized setup command to initialize the secure core and generate your local bytecode signature.

Terminal (Ubuntu/Linux/Windows) # 1. Install the SDK package
pip install katorymnd-pawapay-python-sdk

# 2. Run the secure initial setup (Generates the "Soul")
katorymnd-pawapay-setup

SDK Dependencies

The following core dependencies are utilized in our stack:

FastAPI & Uvicorn
High-performance web frameworks for handling incoming payment webhooks and API routing.
Maturin
Compiles the encrypted transaction logic and opcodes to secure native binaries.
asyncio / aiohttp
Native async/await support for high-performance concurrent pawaPay requests.

Recommended Project Structure

After running katorymnd-pawapay-setup, align your project as follows:

pawapay-folder/
├── .pawapay-imprint         # The "Soul" - Server locking signature
├── .venv/                   # Your isolated workspace
├── src/
│   └── utils/vm/          # Encrypted logic (opcodes.json, bytecode.bin)
├── .env                    # Contains your Domain & Master License
├── errorlogs.txt           # Surgical traceback logs
└── main.py                 # FastAPI Server entry point

License Activation & Domain Binding

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

🔐 Native Domain Locking: 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.
🐍 License Key: Required 🔑 Secret Key: Required

Step-by-Step Validation

1. Acquire License Key Retrieve your cryptographically signed LICENSE_KEY generated by the Katorymnd master admin.
2. Configure Environment Add the license to your .env file. Do not use dummy fallbacks. The environment must strictly match the signature.
3. Generate The Imprint Run katorymnd-pawapay-setup to create the .pawapay-imprint file alongside your server's randomized instruction sets.
4. Runtime Validation Upon instantiating the ApiClient, validator splits the payload, verifies the HMAC signature, and checks the domain before unlocking endpoints.

Licensing Error Codes

DomainMismatchError
Security Lock: The PAWAPAY_SDK_LICENSE_DOMAIN in your .env does not match the signed payload inside the license key.
SignatureInvalidError
Tampering Detected: The key was modified or generated with an invalid master secret. Core logic execution halted.

Environment Configuration

The katorymnd-pawapay-python-sdk expects explicit `.env` file credentials. We use the python-dotenv package to load these natively.

⚠️ Security Warning: Ensure .env is added to your root.

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
KATORYMND_PAWAPAY_SDK_LICENSE_KEY=your_key_here
PAWAPAY_SDK_LICENSE_DOMAIN=your_domain_here
PAWAPAY_SDK_LICENSE_SECRET=your_key_here

Variable Definitions

api_token
Pulled directly from your environment variables via os.getenv() in your config dictionary.
PAWAPAY_SDK_LICENSE_DOMAIN
Must perfectly match the domain the license was generated for by the Admin generator.
environment
Pass 'sandbox' or 'production' in the config_dict to instruct the SDK on which endpoint to target.

Troubleshooting & Diagnostics

If your application encounters a fatal error, check the surgical errorlogs.txt generated in your project root. It will capture complete Tracebacks.

1. Common System Errors

NameError: name 'Config' is not defined
Cause: Using an outdated initialization class.
Fix: Switch to passing a config_dict directly to the ApiClient.
502 Bad Gateway (Nginx/Apache)
Cause: The background Uvicorn service has crashed.
Fix: Run sudo journalctl -u pawapay-python.service -n 50 to view the daemon logs.

2. API Rejections

These errors occur during the initiate_deposit() phase.

INVALID_PARAMETER
Message: Customer message length should not be greater than 22.
Fix: Keep your statement description concise.
INVALID_PHONE_NUMBER
Message: The phone number format is invalid.
Fix: Ensure the MSISDN follows the correct format (e.g., 25678...).

Support & Technical Assistance

If you encounter challenges during the integration, our engineering team is available to assist you. To ensure the fastest resolution, please follow the diagnostic steps below.

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:

• SDK Version: Output of pip show katorymnd-pawapay-python-sdk.
• Environment: Sandbox or Production.
• Correlation ID: The depositId or transactionId from your scripts.
• Error Logs: Snippet from your errorlogs.txt.
• Python Version: Output of python --version.

🐍 "Empowering African fintech through surgical Python engineering."