Metadata-Version: 2.4
Name: pawapay
Version: 1.0.0
Summary: Official Python SDK for PawaPay - African Payment Gateway
Home-page: https://github.com/pawapay/pawapay-python
Author: PawaPay
Author-email: support@pawapay.com
Project-URL: Bug Reports, https://github.com/pawapay/pawapay-python/issues
Project-URL: Documentation, https://docs.pawapay.com
Project-URL: Source, https://github.com/pawapay/pawapay-python
Keywords: pawapay payment gateway africa mobile money momo payments api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PawaPay Python SDK

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

[![PyPI version](https://badge.fury.io/py/pawapay.svg)](https://badge.fury.io/py/pawapay)
[![Python Versions](https://img.shields.io/pypi/pyversions/pawapay.svg)](https://pypi.org/project/pawapay/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
pip install pawapay
```

## Quick Start

```python
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="customer@example.com"
)

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

## Usage

### Initialize Client

```python
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

```python
# 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="customer@example.com",
    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

```python
# 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

```python
# Create checkout session
session = pay.checkout.initialize(
    amount=10000,       # GHS 100.00
    email="customer@example.com",
    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

```python
# 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

```python
# 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

```python
# 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

```python
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="customer@example.com"
    )
    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:

```python
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="test@example.com"
)
# Returns success immediately without real charge
```

## API Reference

### PawaPay Client

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

### Mobile Money

```python
# 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

```python
# 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

```python
# 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

```bash
# 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](examples/) directory for more usage examples:

- [Basic mobile money payment](examples/basic_momo.py)
- [Hosted checkout](examples/checkout.py)
- [Transaction management](examples/transactions.py)
- [Error handling](examples/error_handling.py)
- [Flask integration](examples/flask_app.py)
- [Django integration](examples/django_view.py)

## Support

- 📧 Email: support@pawapay.com
- 📚 Documentation: https://docs.pawapay.com
- 🐛 Issues: https://github.com/pawapay/pawapay-python/issues

## License

MIT License - see [LICENSE](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
