> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahelpay.ml/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> SDK Python pour SahelPay

# Python SDK

Le SDK Python officiel pour intégrer SahelPay dans vos applications Python, Django ou Flask.

## Installation

```bash theme={null}
pip install sahelpay
```

<Note>
  En attendant la publication sur PyPI, clonez le repo GitHub :

  ```bash theme={null}
  git clone https://github.com/dione24/sahelpay-sdks.git
  cd sahelpay-sdks/python
  pip install -e .
  ```
</Note>

## Configuration

```python theme={null}
from sahelpay import SahelPay

sahelpay = SahelPay('sk_test_xxx')
```

## Créer un lien de paiement

```python theme={null}
link = sahelpay.payment_links.create(
    title='Commande #123',
    price=5000,
    redirect_url='https://votre-site.com/checkout/return'
)

# Rediriger le client
redirect(link.url)
```

## Vérifier le statut

```python theme={null}
payment = sahelpay.payments.retrieve('txn_abc123')

print(payment.status)  # 'PENDING', 'SUCCESS', 'FAILED'
print(payment.amount)
```

## Vérifier un webhook

```python theme={null}
from sahelpay import SahelPay

sahelpay = SahelPay('sk_test_xxx', webhook_secret='whsec_xxx')

# Flask
@app.route('/webhooks/sahelpay', methods=['POST'])
def webhook():
    raw_body = request.get_data(as_text=True)
    signature = request.headers.get('X-SahelPay-Signature')

    is_valid = sahelpay.webhooks.verify(raw_body, signature)

    if not is_valid:
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json

    if event['event'] == 'payment.success':
        # Mettre à jour la commande
        pass

    return jsonify({'received': True})
```

## Django View

```python theme={null}
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from sahelpay import SahelPay
import json

sahelpay = SahelPay(settings.SAHELPAY_SECRET_KEY)

@csrf_exempt
def webhook(request):
    raw_body = request.body.decode('utf-8')
    signature = request.headers.get('X-SahelPay-Signature')

    is_valid = sahelpay.webhooks.verify(raw_body, signature)

    if not is_valid:
        return JsonResponse({'error': 'Invalid signature'}, status=401)

    event = json.loads(raw_body)

    if event['event'] == 'payment.success':
        # Mettre à jour la commande
        pass

    return JsonResponse({'received': True})
```

## Méthodes de paiement

| Méthode        | Description    | Pays              |
| -------------- | -------------- | ----------------- |
| `ORANGE_MONEY` | Orange Money   | Mali, Sénégal, CI |
| `WAVE`         | Wave           | Mali, Sénégal, CI |
| `MOOV`         | Moov Money     | Mali, Bénin, Togo |
| `CARD`         | Carte bancaire | Tous              |

```python theme={null}
payment = client.payments.create(
    amount=5000,
    provider='ORANGE_MONEY',  # ou WAVE, MOOV, CARD
    customer_phone='+22370123456',
    description='Commande #123'
)

# Informations de routing (automatique)
print(payment.gateway_used)    # Identifiant technique interne
print(payment.routing_reason)  # Explication du routing choisi
```

<Note>
  SahelPay utilise un **Smart Routing** automatique. Vous spécifiez la méthode de paiement (ex: `ORANGE_MONEY`) et SahelPay choisit le meilleur gateway en interne.
</Note>

## Capabilities

```python theme={null}
from sahelpay import has_capability, get_methods_with_capability

# Vérifier si Orange Money supporte les payouts
has_capability('ORANGE_MONEY', 'payouts')  # True

# Lister les méthodes avec QR code natif
get_methods_with_capability('qr_code')  # ['WAVE']
```

## Paiement par Carte

Pour les paiements par carte, `customer_name` et `customer_email` sont **requis** :

```python theme={null}
payment = client.payments.create(
    amount=10000,
    provider='CARD',
    customer_phone='+22370123456',
    customer_name='Mamadou Diallo',       # Requis
    customer_email='mamadou@example.com', # Requis
    return_url='https://votre-site.com/checkout/return'
)
```