Metadata-Version: 2.4
Name: geniuspay
Version: 1.2.2
Summary: SDK Django pour GeniusPay - paiements Mobile Money en Afrique
Author-email: eliottkenan <eliottkenan@email.ci>
License: MIT
Project-URL: Homepage, https://github.com/eliottkenan/django-geniuspay
Keywords: django,geniuspay,mobile-money,wave,afrique
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: requests>=2.28
Dynamic: license-file

# GeniusPay Django SDK

Un SDK Django robuste, sécurisé et "Plug-and-Play" pour intégrer facilement l'API GeniusPay dans vos projets.

## Ce que ce SDK fait pour vous
- **Paiements :** Création, récupération et listage avec gestion complète de l'autorouting et des gateways (Wave, Paystack, CinetPay, PawaPay...).
- **Webhooks Sécurisés :** Réception automatique des webhooks avec vérification cryptographique (`HMAC-SHA256`) et protection anti-rejeu.
- **Base de Données Automatique :** Sauvegarde transparente de chaque transaction et mise à jour de son statut dans votre base de données locale.
- **Signaux Django :** Plus besoin de créer des vues pour traiter les paiements, connectez-vous simplement aux signaux natifs (`payment_success`, `payment_failed`).
- **Panneau d'Administration :** Visualisez l'historique de vos paiements GeniusPay directement dans votre espace Django Admin.

---

## 1. Installation & Configuration

Installez le package et ajoutez `'geniuspay'` à vos applications installées :

```python
# settings.py
INSTALLED_APPS = [
    # ...
    'geniuspay',
]

# Configurez vos clés GeniusPay
GENIUSPAY = {
    "API_KEY": "pk_live_xxxx",
    "API_SECRET": "sk_live_xxxx",
    "WEBHOOK_SECRET": "whsec_xxxx", # Obligatoire pour sécuriser les webhooks
}
```

Appliquez les migrations pour créer la table de suivi des transactions :
```bash
python manage.py makemigrations geniuspay
python manage.py migrate
```

## 2. Recevoir des Webhooks (La magie des Signaux)

Le SDK s'occupe de la sécurité et de la mise à jour en base de données. Vous n'avez qu'à exposer la route et écouter le signal.

**Dans votre `urls.py` principal :**
```python
from django.urls import path, include

urlpatterns = [
    # ...
    path('geniuspay/', include('geniuspay.urls')), 
    # Votre URL webhook sera : https://votre-site.com/geniuspay/webhook/
]
```

**Dans n'importe quel fichier de votre projet (ex: `signals.py` ou `views.py`) :**
```python
from django.dispatch import receiver
from geniuspay.signals import payment_success, payment_failed

@receiver(payment_success)
def valider_commande(sender, transaction, raw_event, **kwargs):
    print(f"Le paiement {transaction.reference} de {transaction.amount} {transaction.currency} a réussi !")
    # Mettez à jour votre panier, envoyez un email au client, etc.

@receiver(payment_failed)
def annuler_commande(sender, transaction, raw_event, **kwargs):
    print(f"Le paiement {transaction.reference} a échoué.")
```

## 3. Initier un Paiement

C'est aussi simple que d'instancier le client.

```python
from geniuspay.client import GeniusPayClient

def payer_commande(request):
    client = GeniusPayClient()
    
    payment = client.payments.create(
        amount=5000,
        description="Achat de chaussures",
        customer={"name": "Jean Dupont", "phone": "+22500000000"},
        success_url="https://monsite.com/merci",
        # gateway="wave"  # Optionnel : Laissez vide pour l'autorouting de GeniusPay !
    )
    
    # Redirigez l'utilisateur vers la page de paiement sécurisée
    return redirect(payment.checkout_url)
```

## 4. Lister les Opérateurs (Providers)

Si vous construisez votre propre interface, vous pouvez lister dynamiquement les opérateurs disponibles.

```python
client = GeniusPayClient()
providers = client.providers.list(country="CI", gateway="pawapay")

for p in providers:
    print(p.name) # ex: Orange Money, MTN Mobile Money...
```

## 5. Gestion des Erreurs

Le SDK expose des exceptions propres pour vous faciliter la vie :
`GeniusPayNetworkError`, `GeniusPayAuthError`, `GeniusPayValidationError`, `GeniusPayWebhookError`.
