pawapay 1.0.0

Official Python SDK for PawaPay - African Payment Gateway

PawaPay Python SDK

Official Python library for the PawaPay API - Accept mobile money and card payments across Africa.

Features

• 🚀 Simple, intuitive API
• 💳 Mobile money payments (MTN, Vodafone, AirtelTigo)
• 🔒 Hosted checkout pages
• ✅ Transaction verification
• 🧪 Test mode support
• 📝 Type hints for better IDE support
• 🛡️ Comprehensive error handling

Installation

pip install pawapay

Quick Start

from pawapay import PawaPay

# Initialize with your API key
pay = PawaPay(api_key="sk_test_your_key_here")

# Charge mobile money
result = pay.momo.charge(
    amount=5000,        # GHS 50.00 (amount in pesewas)
    phone="0244123456",
    network="MTN",
    email="[e-mail]"
)

print(f"Payment Reference: {result['reference']}")
print(f"Status: {result['status']}")

Usage

Initialize Client

from pawapay import PawaPay

# Test mode (uses sk_test_ key)
pay = PawaPay(api_key="sk_test_your_key_here")

# Production mode (uses sk_live_ key)
pay = PawaPay(api_key="sk_live_your_key_here")

# Custom configuration
pay = PawaPay(
    api_key="sk_test_your_key_here",
    base_url="https://api.pawapay.com",  # Optional
    timeout=30  # Request timeout in seconds
)

Mobile Money Payments

Charge Mobile Money

# Charge MTN Mobile Money
result = pay.momo.charge(
    amount=5000,        # Amount in pesewas (GHS 50.00)
    phone="0244123456",
    network="MTN",      # MTN, VODAFONE, or AIRTELTIGO
    email="[e-mail]",
    reference="ORDER-123",  # Optional: Your unique reference
    metadata={          # Optional: Additional data
        "order_id": "12345",
        "customer_name": "John Doe"
    }
)

print(result)
# {
#     "success": True,
#     "reference": "UPY-2024-123456-GH",
#     "status": "success",
#     "message": "Payment successful"
# }

Verify Payment

# Verify transaction status
result = pay.momo.verify("UPY-2024-123456-GH")

if result['status'] == 'success':
    print("Payment confirmed!")
elif result['status'] == 'pending':
    print("Payment pending...")
else:
    print("Payment failed")

Hosted Checkout

Initialize Checkout Session

# Create checkout session
session = pay.checkout.initialize(
    amount=10000,       # GHS 100.00
    email="[e-mail]",
    callback_url="https://yoursite.com/payment/callback",
    metadata={
        "order_id": "12345",
        "product": "Premium Plan"
    }
)

print(f"Checkout URL: {session['checkout_url']}")
print(f"Access Code: {session['access_code']}")

# Redirect customer to checkout_url
# Customer completes payment on hosted page

Verify Checkout Payment

# After customer completes payment
result = pay.checkout.verify(session['reference'])

if result['status'] == 'success':
    # Payment successful - deliver product/service
    print(f"Amount paid: {result['amount']}")
    print(f"Customer: {result['email']}")

Transaction Management

List Transactions

# Get recent transactions
transactions = pay.transactions.list(limit=20)

for txn in transactions:
    print(f"{txn['reference']}: {txn['amount']} - {txn['status']}")

# Filter by status
successful = pay.transactions.list(status="success", limit=50)

# Filter by date range
from_date = pay.transactions.list(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

Get Single Transaction

# Get transaction details
txn = pay.transactions.get("UPY-2024-123456-GH")

print(f"Amount: {txn['amount']}")
print(f"Status: {txn['status']}")
print(f"Customer: {txn['email']}")
print(f"Network: {txn['network']}")
print(f"Date: {txn['createdAt']}")

Error Handling

from pawapay import PawaPay
from pawapay.exceptions import (
    AuthenticationError,
    InvalidRequestError,
    APIError,
    NetworkError
)

pay = PawaPay(api_key="sk_test_your_key_here")

try:
    result = pay.momo.charge(
        amount=5000,
        phone="0244123456",
        network="MTN",
        email="[e-mail]"
    )
    print("Payment successful!")
    
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    # Invalid API key
    
except InvalidRequestError as e:
    print(f"Invalid request: {e.message}")
    # Missing or invalid parameters
    
except APIError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.http_status}")
    # API returned an error
    
except NetworkError as e:
    print(f"Network error: {e.message}")
    # Connection timeout or network issue

Supported Networks

Network	Code	Country
MTN Mobile Money	MTN	Ghana
Vodafone Cash	VODAFONE	Ghana
AirtelTigo Money	AIRTELTIGO	Ghana

Test Mode

Use test API keys (starting with sk_test_) for development:

pay = PawaPay(api_key="sk_test_your_key_here")

# All transactions in test mode auto-succeed
result = pay.momo.charge(
    amount=5000,
    phone="0244123456",
    network="MTN",
    email="[e-mail]"
)
# Returns success immediately without real charge

API Reference

PawaPay Client

PawaPay(
    api_key: str,           # Required: Your API key
    base_url: str = None,   # Optional: Custom API URL
    timeout: int = 30       # Optional: Request timeout
)

Mobile Money

# Charge mobile money
pay.momo.charge(
    amount: int,                    # Required: Amount in pesewas
    phone: str,                     # Required: Phone number
    network: str,                   # Required: MTN, VODAFONE, AIRTELTIGO
    email: str,                     # Required: Customer email
    currency: str = "GHS",          # Optional: Currency code
    reference: str = None,          # Optional: Your reference
    metadata: dict = None           # Optional: Additional data
) -> dict

# Verify payment
pay.momo.verify(reference: str) -> dict

Checkout

# Initialize checkout
pay.checkout.initialize(
    amount: int,                    # Required: Amount in pesewas
    email: str,                     # Required: Customer email
    currency: str = "GHS",          # Optional: Currency code
    callback_url: str = None,       # Optional: Redirect URL
    metadata: dict = None           # Optional: Additional data
) -> dict

# Verify checkout payment
pay.checkout.verify(reference: str) -> dict

Transactions

# List transactions
pay.transactions.list(
    limit: int = 10,                # Optional: Number of results
    status: str = None,             # Optional: Filter by status
    start_date: str = None,         # Optional: From date (ISO)
    end_date: str = None            # Optional: To date (ISO)
) -> list

# Get transaction
pay.transactions.get(reference: str) -> dict

Requirements

• Python 3.7+
• requests >= 2.25.0

Development

# Clone repository
git clone https://github.com/pawapay/pawapay-python.git
cd pawapay-python

# Install dependencies
pip install -r requirements.txt

# Run tests
python -m pytest tests/

# Install in development mode
pip install -e .

Examples

See the examples directory for more usage examples:

• Basic mobile money payment
• Hosted checkout
• Transaction management
• Error handling
• Flask integration
• Django integration

Support

• 📧 Email: [e-mail]
• 📚 Documentation: https://docs.pawapay.com
• 🐛 Issues: https://github.com/pawapay/pawapay-python/issues

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

1.0.0 (2024-03-07)

• Initial release
• Mobile money payments support
• Hosted checkout pages
• Transaction management
• Comprehensive error handling
• Type hints support