SDK Python

Le SDK Python alphapay enveloppe l’API REST AlphaPay (checkout, softpay, liens de paiement, clients, webhooks…) avec retry automatique (backoff exponentiel + gigue sur 429/5xx/erreur réseau), gestion d’idempotence et exceptions typées par cas d’erreur.

pip install alphapay

export ALPHAPAY_SECRET_KEY=sk_test_votre_cle   # sk_live_... en production

Chaque exemple ci-dessous est autonome : copiez-le, remplacez os.environ["ALPHAPAY_SECRET_KEY"] par votre clé et lancez-le avec python3.

1. Checkout (session hébergée)

Crée une page de paiement hébergée par AlphaPay et pré-remplie pour un client précis — l’usage le plus simple pour un e-commerce classique (redirigez le client vers checkout_url).

import os
from alphapay import AlphaPayClient

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def creer_checkout():
    session = alphapay.checkout_sessions.create(
        amount=5000,
        currency="XOF",
        description="Commande #1042",
        customer_email="client@exemple.com",
        customer_name="Ayaba Client",
        customer_phone="+22900000000",
        return_url="https://boutique.exemple.com/merci",
        metadata={"order_id": "1042"},
        idempotency_key=True,  # génère une clé unique — un retry réseau ne recrée pas de doublon
    )
    print("Redirigez le client vers :", session["checkout_url"])
    print("Slug (à stocker pour retrouver la session) :", session["slug"])
    return session

def suivre_checkout(id):
    session = alphapay.checkout_sessions.get(id)
    print("Statut :", session["status"])  # PENDING, PAID, EXPIRED, CANCELLED

def annuler_checkout(id):
    session = alphapay.checkout_sessions.cancel(id)
    print("Annulée :", session["status"] == "CANCELLED")

2. Softpay (encaissement direct)

Pousse directement une demande de paiement (USSD mobile money) sans page de checkout à afficher — utile pour une app où vous collectez déjà le numéro du client.

import os
from alphapay import AlphaPayClient, AlphaPayValidationError

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def encaisser():
    try:
        payment = alphapay.transactions.payin_initialize(
            amount=2500,
            currency="XOF",
            country="BJ",
            network="mtn_bj",  # cf. GET /networks/ pour la liste à jour
            description="Abonnement mensuel",
            customer={
                "email": "client@exemple.com",
                "first_name": "Ayaba",
                "last_name": "Client",
                "phone": "+22900000000",
            },
            idempotency_key=True,
        )
        print("Paiement initié :", payment["id"], payment["status"])

        # Sondez jusqu'à confirmation (push USSD confirmé/refusé côté client).
        result = alphapay.transactions.payin_verify(payment["id"])
        print("Statut final :", result["status"])
    except AlphaPayValidationError as err:
        print("Champs invalides :", err.field_errors)

# Réseaux à confirmation en 2 temps (ex. Wizall Sénégal, Coris Bénin).
def confirmer_otp(payment_id, otp):
    result = alphapay.transactions.payin_confirm_otp(payment_id, otp)
    print("Confirmé :", result["status"])

3. Lien de paiement

Un lien réutilisable (partageable sur WhatsApp, réseaux sociaux, etc.), avec ses propres champs personnalisés et suivi publicitaire.

import os
from alphapay import AlphaPayClient

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def creer_lien():
    link = alphapay.payment_links.create(
        name="Formation en ligne",
        description="Accès à vie à la formation",
        amount_type="FIXED",
        amount=15000,
        currency="XOF",
        facebook_pixel_id=os.environ.get("FACEBOOK_PIXEL_ID"),
        google_ads_id=os.environ.get("GOOGLE_ADS_ID"),
        custom_fields=[
            {"key": "email_formation", "label": "E-mail pour l'accès", "required": True},
        ],
    )
    print("Lien partageable :", link["url"])
    return link

# Ce que voit la page publique du lien — pas d'auth marchand nécessaire.
def consulter_lien_public(slug):
    public_link = alphapay.payment_links.get_public(slug)
    print(f"{public_link['name']} — {public_link.get('amount') or 'montant libre'} {public_link['currency']}")
    print("Utilisable :", public_link["is_usable"], public_link.get("unusable_reason") or "")

# Crée une CheckoutSession one-shot à partir du lien (ex. depuis votre propre
# front public, sans jamais exposer la clé secrète côté client).
def payer_depuis_lien(slug):
    result = alphapay.payment_links.create_public_checkout(
        slug,
        customer={"email": "client@exemple.com", "first_name": "Ayaba", "last_name": "Client"},
        custom_field_values={"email_formation": "ayaba@exemple.com"},
    )
    print("Session créée :", result["checkout_url"])

def lister_liens():
    page = alphapay.payment_links.list(is_active=True)
    for link in page["results"]:
        print(link["name"], link["usage_count"], "utilisations")

4. Solde et grand livre

import os
from alphapay import AlphaPayClient, AlphaPayPermissionError

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def verifier_soldes():
    page = alphapay.balances.list()
    for balance in page["results"]:
        print(f"{balance['country']} ({balance['currency']}) : {balance['available_amount']} disponible")

def grand_livre():
    try:
        # ⚠️ Dashboard-only — lève AlphaPayPermissionError (403) via une clé API,
        # conservé ici pour documenter la forme réelle de l'endpoint.
        alphapay.balances.ledger_entries(country="BJ")
    except AlphaPayPermissionError:
        print("Grand livre détaillé : consultable uniquement depuis le dashboard.")

5. Clients (CRM)

import os
from alphapay import AlphaPayClient

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def gerer_client():
    # `country` est l'UUID d'un `geo.Country` côté API — PAS un code ISO2 ("BJ").
    country_id = "00000000-0000-0000-0000-000000000000"

    customer = alphapay.customers.create(
        email="client@exemple.com",
        full_name="Ayaba Client",
        phone="+22900000000",
        country=country_id,
    )

    alphapay.customers.update(customer["id"], phone="+22900000001")

    page = alphapay.customers.transactions(customer["id"], page_size=20)
    print(f"{len(page['results'])} transaction(s) pour ce client.")

    return customer

def lister_clients():
    page = alphapay.customers.list(search="ayaba")
    print([c["email"] for c in page["results"]])

6. Webhooks

Réception et vérification d’un webhook entrant (exemple avec Flask ; adaptez à votre framework au besoin — le principe ne change pas : toujours vérifier la signature sur le corps brut, avant tout json.loads).

import os
from flask import Flask, request
from alphapay import AlphaPayWebhookSignatureError, verify_signature

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["ALPHAPAY_WEBHOOK_SECRET"]

@app.post("/webhooks/alphapay")
def receive_webhook():
    try:
        event = verify_signature(
            payload=request.get_data(),  # corps BRUT, jamais déjà parsé en JSON
            signature=request.headers["X-Webhook-Signature"],
            timestamp=request.headers["X-Webhook-Timestamp"],
            secret=WEBHOOK_SECRET,
        )
    except AlphaPayWebhookSignatureError as err:
        print("Webhook rejeté :", err)
        return "signature invalide", 400

    if event["event"] == "payment.succeeded":
        print("Paiement réussi :", event["data"])
    elif event["event"] == "payment.failed":
        print("Paiement échoué :", event["data"])
    else:
        print("Événement reçu :", event["event"])

    return "ok", 200

Consultation en lecture (CRUD d’écriture réservé au dashboard) :

import os
from alphapay import AlphaPayClient

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def inspecter_webhooks():
    webhooks = alphapay.webhook_endpoints.list()
    for webhook in webhooks["results"]:
        print(webhook["url"], webhook.get("is_active"))

    logs = alphapay.webhook_endpoints.logs.list(status="FAILED")
    print(f"{len(logs['results'])} livraison(s) échouée(s).")

7. Reversements et transferts entre wallets

Ces deux ressources sont entièrement inaccessibles via clé API (403 dashboard_only sur toutes leurs méthodes, y compris en lecture) — elles ne peuvent être pilotées que depuis le dashboard AlphaPay par un compte utilisateur connecté. Elles restent dans le SDK pour documenter la forme réelle des endpoints, pas pour un usage serveur automatisé.

import os
from alphapay import AlphaPayClient, AlphaPayPermissionError

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def tenter_reversement():
    try:
        alphapay.settlements.create(
            country="BJ", requested_amount=10000, payout_method="mtn_bj", idempotency_key=True,
        )
    except AlphaPayPermissionError:
        print("Reversement : dashboard uniquement, pas via clé API.")

def tenter_transfert_wallet():
    try:
        alphapay.wallet_transfers.create(from_country="BJ", to_country="CI", from_amount=5000)
    except AlphaPayPermissionError:
        print("Transfert entre wallets : dashboard uniquement, pas via clé API.")

8. Clés API et whitelist IP

api_keys.list/create/get/revoke/delete sont dashboard-only (403 via clé API — une clé compromise ne doit pas pouvoir en créer d’autres). Seule .ip_whitelist fonctionne via clé API, et elle est requise pour les payouts.

import os
from alphapay import AlphaPayClient

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def gerer_whitelist():
    entry = alphapay.api_keys.ip_whitelist.create(
        ip_address="203.0.113.42",
        label="Serveur de production",
    )

    alphapay.api_keys.ip_whitelist.update(entry["id"], status="ACTIVE")

    page = alphapay.api_keys.ip_whitelist.list()
    print([f"{e['ip_address']} ({e['status']})" for e in page["results"]])

9. Gestion des erreurs

Toutes les erreurs API héritent de AlphaPayError — vérifiez le type le plus spécifique d’abord.

import os
from alphapay import (
    AlphaPayClient,
    AlphaPayAuthenticationError,
    AlphaPayConnectionError,
    AlphaPayError,
    AlphaPayIdempotencyError,
    AlphaPayNotFoundError,
    AlphaPayPermissionError,
    AlphaPayRateLimitError,
    AlphaPayServerError,
    AlphaPayValidationError,
)

alphapay = AlphaPayClient(os.environ["ALPHAPAY_SECRET_KEY"])

def appel_securise():
    try:
        return alphapay.checkout_sessions.get("id-inexistant")
    except AlphaPayNotFoundError:
        print("Session introuvable.")
    except AlphaPayValidationError as err:
        print("Erreurs par champ :", err.field_errors)
    except AlphaPayAuthenticationError:
        print("Clé API invalide ou manquante.")
    except AlphaPayPermissionError as err:
        print("Action réservée au dashboard :", err.error_code)  # ex. "dashboard_only"
    except AlphaPayIdempotencyError:
        print("Idempotency-Key déjà utilisée avec un payload différent.")
    except AlphaPayRateLimitError as err:
        print(f"Trop de requêtes, réessayez dans {err.retry_after or 'quelques'}s.")
    except AlphaPayServerError:
        print("Erreur côté AlphaPay — déjà retentée automatiquement.")
    except AlphaPayConnectionError:
        print("Impossible de joindre l'API (réseau/DNS/timeout).")
    except AlphaPayError as err:
        print(f"{err.status} {err.error_code or ''}: {err}")
    return None

Le client retente déjà automatiquement (backoff exponentiel + gigue) sur 429/5xx/erreur réseau — configurable via max_retries au constructeur du client. Les erreurs ci-dessus ne surviennent donc qu’après épuisement de ces tentatives automatiques.

Prise en main

SDKs & Intégration

Sommaire

1. Checkout (session hébergée)

2. Softpay (encaissement direct)

3. Lien de paiement

4. Solde et grand livre

5. Clients (CRM)

6. Webhooks

7. Reversements et transferts entre wallets

8. Clés API et whitelist IP

9. Gestion des erreurs

​Sommaire

​1. Checkout (session hébergée)

​2. Softpay (encaissement direct)

​3. Lien de paiement

​4. Solde et grand livre

​5. Clients (CRM)

​6. Webhooks

​7. Reversements et transferts entre wallets

​8. Clés API et whitelist IP

​9. Gestion des erreurs

Sommaire

1. Checkout (session hébergée)

2. Softpay (encaissement direct)

3. Lien de paiement

4. Solde et grand livre

5. Clients (CRM)

6. Webhooks

7. Reversements et transferts entre wallets

8. Clés API et whitelist IP

9. Gestion des erreurs