dexchangepay (Python)

SDK officiel Python pour l'API DEXPAY - Paiements Mobile Money pour l'Afrique de l'Ouest.

Compatible avec Django, Flask, FastAPI et tout projet Python 3.8+.

Installation

pip install dexchangepay
# ou
poetry add dexchangepay

Démarrage rapide

from dexpay import DexPay

dexpay = DexPay(
    api_key="pk_test_xxx",     # Votre clé publique
    api_secret="sk_test_xxx",  # Votre clé secrète
)

# Créer une session de paiement
session = dexpay.checkout_sessions.create({
    "reference": "ORDER_123",
    "item_name": "Premium Plan",
    "amount": 10000,  # 10 000 XOF
    "currency": "XOF",
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/cancel",
    "webhook_url": "https://example.com/webhook",
})

# Rediriger le client vers la page de paiement
print(session["data"]["payment_url"])

Checkout Sessions

Créer une session

session = dexpay.checkout_sessions.create({
    "reference": "ORDER_123",
    "item_name": "Abonnement Premium",
    "amount": 10000,
    "currency": "XOF",
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/cancel",
    "webhook_url": "https://example.com/webhook",
    "metadata": {"user_id": "123", "plan": "premium"},
    "expires_at": "2025-12-31T23:59:59Z",  # Optionnel
    "client_support_fee": True,  # Optionnel - frais à la charge du client
})

Récupérer une session

# Par ID
session = dexpay.checkout_sessions.retrieve("session_id")

# Par référence
session = dexpay.checkout_sessions.retrieve_by_reference("ORDER_123")

Lister les sessions

sessions = dexpay.checkout_sessions.list({"page": 1, "limit": 10})

Créer une tentative de paiement

attempt = dexpay.checkout_sessions.create_payment_attempt(
    "ORDER_123",
    {
        "payment_method": "MOBILE_MONEY",
        "operator": "wave",  # wave, orange_money, mtn, moov
        "countryISO": "SN",  # SN, CI, ML, BF, etc.
        "customer": {
            "name": "Jean Dupont",
            "phone": "+221771234567",
            "email": "jean@example.com",
        },
    },
)

print(attempt["data"]["payment_url"])

Payouts (Retraits)

payout = dexpay.payouts.create({
    "amount": 10000,
    "currency": "XOF",
    "destination_phone": "+221771234567",
    "destination_details": {
        "operator": "wave",
        "countryISO": "SN",
        "recipient_name": "Jean Dupont",
    },
    "metadata": {"invoice_id": "INV_123"},
})

print(payout["reference"])  # PO_20251228_XXXXXX
print(payout["status"])     # PENDING, PROCESSING, COMPLETED, FAILED

# Récupérer, lister
dexpay.payouts.retrieve("payout_id")
dexpay.payouts.list({"page": 1, "limit": 10, "status": "COMPLETED"})

Remboursements

# Rembourser la dernière transaction réussie d'une session
refund = dexpay.checkout_sessions.refund("ORDER_123")
print(refund["status"])  # success

Balances

res = dexpay.balances.list()
print(res["data"][0]["balance"], res["data"][0]["currency"])

Providers

# Providers de collecte (paiement)
payment = dexpay.payment_providers.list({"provider_country": "SN"})

# Providers de retrait (payout)
payout = dexpay.payout_providers.list()

Products

# Produit ponctuel
product = dexpay.products.create({
    "name": "T-Shirt",
    "price": 5000,
    "currency": "XOF",
    "type": "ONE_TIME",
})

# Produit récurrent
plan = dexpay.products.create({
    "name": "Premium Plan",
    "price": 10000,
    "currency": "XOF",
    "type": "RECURRING",
    "billing_period": "MONTHLY",
})

dexpay.products.list({"page": 1, "limit": 10, "type": "RECURRING", "is_active": True})
dexpay.products.update("prod_123", {"price": 15000, "is_active": False})

Customers

customer = dexpay.customers.create({
    "name": "Jean Dupont",
    "email": "jean@example.com",
    "phone": "+221771234567",
    "country": "SN",
    "metadata": {"source": "website"},
})

# Rechercher
dexpay.customers.list({"email": "jean@example.com"})
dexpay.customers.list({"phone": "+221771234567"})

Subscriptions

subscription = dexpay.subscriptions.create({
    "customer_id": "cus_123",
    "product_id": "prod_456",
    "metadata": {"referral_code": "ABC123"},
})

dexpay.subscriptions.update("sub_123", {"status": "PAUSED"})
dexpay.subscriptions.cancel("sub_123")

Gestion des erreurs

from dexpay import DexPay, DexPayError

try:
    session = dexpay.checkout_sessions.create({...})
except DexPayError as error:
    print("Code:", error.code)
    print("Message:", error.message)
    print("Status:", error.status_code)

Intégration frameworks

Django

# settings.py
DEXPAY_API_KEY = os.environ["DEXPAY_API_KEY"]
DEXPAY_API_SECRET = os.environ["DEXPAY_API_SECRET"]

# views.py
import json
from django.conf import settings
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from dexpay import DexPay

dexpay = DexPay(api_key=settings.DEXPAY_API_KEY, api_secret=settings.DEXPAY_API_SECRET)

@csrf_exempt
def webhook(request):
    event = json.loads(request.body)
    if event["type"] == "checkout.completed":
        ...  # Marquer la commande comme payée
    return JsonResponse({"received": True})

Flask

from flask import Flask, request, jsonify
from dexpay import DexPay

app = Flask(__name__)
dexpay = DexPay(api_key="pk_live_xxx", api_secret="sk_live_xxx")

@app.post("/webhook")
def webhook():
    event = request.get_json()
    if event["type"] == "checkout.completed":
        ...
    return jsonify(received=True)

FastAPI

from fastapi import FastAPI, Request
from dexpay import DexPay

app = FastAPI()
dexpay = DexPay(api_key="pk_live_xxx", api_secret="sk_live_xxx")

@app.post("/webhook")
async def webhook(request: Request):
    event = await request.json()
    if event["type"] == "checkout.completed":
        ...
    return {"received": True}

Webhooks

Évènements envoyés par DEXPAY (POST JSON sur votre webhook_url) :

Évènement	Description
checkout.completed	Paiement réussi
checkout.failed	Paiement échoué
payout.completed	Payout réussi
payout.failed	Payout échoué
subscription.created	Abonnement créé
subscription.cancelled	Abonnement annulé

Configuration avancée

# Production (défaut)
dexpay = DexPay(api_key="pk_live_xxx", api_secret="sk_live_xxx")

# Sandbox (test)
dexpay = DexPay(api_key="pk_test_xxx", api_secret="sk_test_xxx", sandbox=True)

# Personnalisée
dexpay = DexPay(
    api_key="pk_live_xxx",
    api_secret="sk_live_xxx",
    base_url="https://api.dexpay.africa/api/v1",  # Override URL
    timeout=60,  # 60 secondes
)

URLs de l'API

Environnement	URL
Production	https://api.dexpay.africa/api/v1
Sandbox	https://api-sandbox.dexpay.africa/api/v1

Devises supportées

Code	Devise
XOF	Franc CFA BCEAO (Sénégal, Côte d'Ivoire, Mali, Burkina Faso, etc.)
XAF	Franc CFA BEAC (Cameroun, Gabon, Congo, etc.)
GNF	Franc Guinéen

Opérateurs supportés

Opérateur	Code	Pays
Wave	wave	SN, CI, ML, BF
Orange Money	orange_money	SN, CI, ML, BF, GN
MTN	mtn	CI, BF
Moov	moov	CI, BF

Développement

pip install -e ".[dev]"
pytest          # Lancer les tests
mypy dexpay     # Vérification de types

Support

• 📧 Email: support@dexpay.africa
• 📖 Documentation: https://docs.dexpay.africa
• 🐙 GitHub: https://github.com/DEXCHANGE-GROUP/dexpay-python
• 🐛 Issues: https://github.com/DEXCHANGE-GROUP/dexpay-python/issues

License

MIT © DEXCHANGE GROUP