Metadata-Version: 2.4
Name: sunny-payments
Version: 1.0.0
Summary: Official Sunny Payments Python SDK - Payment processing made simple
Author: Sunny Payments Team
License: MIT
Project-URL: Homepage, https://sunnypayments.com
Project-URL: Documentation, https://docs.sunnypayments.com
Project-URL: Repository, https://github.com/SunnyPayments/sunny-python
Project-URL: Issues, https://github.com/SunnyPayments/sunny-python/issues
Keywords: sunny,payments,payment-gateway,mpesa,mobile-money,kenya,africa,fintech
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: responses>=0.22.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"

# Sunny Payments Python SDK

The official Python SDK for [Sunny Payments](https://sunnypayments.com) - Payment processing made simple.

[![PyPI version](https://img.shields.io/pypi/v/sunny-payments.svg)](https://pypi.org/project/sunny-payments/)
[![Python versions](https://img.shields.io/pypi/pyversions/sunny-payments.svg)](https://pypi.org/project/sunny-payments/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install sunny-payments
```

## Quick Start

```python
from sunny import Sunny

# Initialize the client with your API key
sunny = Sunny("sk_live_your_api_key")

# Create a payment
payment = sunny.payments.create(
    amount=1000,
    currency="KES",
    source="mpesa",
    description="Order #12345"
)

print(payment["id"])  # pay_xxxxx
```

## Features

- ✅ **Payments** - Create, capture, refund, and manage payments
- ✅ **Customers** - Create and manage customer profiles
- ✅ **Refunds** - Process full and partial refunds
- ✅ **Webhooks** - Register endpoints and verify signatures
- ✅ **Bills** - Airtime, data, electricity, and utility payments
- ✅ **Type Hints** - Full type annotations included

## Usage Examples

### Payments

```python
# Create a payment
payment = sunny.payments.create(
    amount=5000,
    currency="KES",
    source="mpesa",
    metadata={"order_id": "12345"}
)

# Retrieve a payment
payment = sunny.payments.retrieve("pay_123")

# List payments
result = sunny.payments.list(limit=10)
for payment in result["data"]:
    print(payment["id"])

# Refund a payment
sunny.payments.refund("pay_123", amount=2500, reason="Customer request")
```

### Bill Payments

```python
# Purchase airtime
airtime = sunny.bills.purchase_airtime(
    phone_number="+254712345678",
    amount=100,
    network="safaricom"
)

# Get data bundles
bundles = sunny.bills.get_data_bundles("safaricom")

# Buy electricity tokens
electricity = sunny.bills.purchase_electricity(
    meter_number="12345678",
    amount=500,
    phone_number="+254712345678"
)
print(electricity["token"])  # KPLC token
```

### Webhooks

```python
from flask import Flask, request
from sunny.resources.webhooks import WebhooksResource

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_xxx"

@app.route("/webhooks/sunny", methods=["POST"])
def handle_webhook():
    payload = request.data
    signature = request.headers.get("x-sunny-signature")
    
    if not WebhooksResource.verify_signature(payload, signature, WEBHOOK_SECRET):
        return "Invalid signature", 400
    
    event = request.json
    
    if event["type"] == "payment.succeeded":
        # Handle successful payment
        pass
    
    return "OK", 200
```

## Error Handling

```python
from sunny import Sunny, AuthenticationError, ValidationError, RateLimitError

try:
    payment = sunny.payments.create(...)
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Validation error: {e.message}, field: {e.field}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
```

## License

MIT License - see [LICENSE](LICENSE) for details.
