Guide de démarrage rapide

Ce guide vous apprendra les bases de l’utilisation de la bibliothèque Faso Arzeka Payment en quelques minutes.

Prérequis

Avant de commencer, assurez-vous d’avoir :

  1. Installé la bibliothèque (voir Installation)

  2. Obtenu vos identifiants API Arzeka : - Username - Password - Merchant ID - Hash Secret

Deux façons d’utiliser la bibliothèque

Il existe deux approches principales pour utiliser cette bibliothèque :

  1. Fonctions de convenance (recommandé pour débuter)

  2. Instance de classe (plus de flexibilité)

Option 1 : Fonctions de convenance

Cette approche est la plus simple pour démarrer rapidement.

Authentification

from fasoarzeka import authenticate

# S'authentifier pour obtenir un token
auth = authenticate(
    username="votre_username",
    password="votre_password",
    base_url="https://pwg-test.fasoarzeka.com/"
)

print(f"Token : {auth['access_token']}")
print(f"Type : {auth['token_type']}")
print(f"Expire dans : {auth['expires_in']} secondes")

Initier un paiement

from fasoarzeka import initiate_payment

# Préparer les données du paiement
payment_data = {
    "amount": 1000,  # Montant en FCFA (minimum 100)
    "merchant_id": "MERCHANT_123",
    "additional_info": {
        "first_name": "Jean",
        "last_name": "Dupont",
        "mobile": "22670123456"  # Format : indicatif + numéro
    },
    "mapped_order_id": "ORDER-2026-001",  # ID unique de votre commande
    "hash_secret": "votre_hash_secret",
    "link_for_update_status": "https://votresite.com/webhook",
    "link_back_to_calling_website": "https://votresite.com/retour"
}

# Initier le paiement
response = initiate_payment(payment_data)

print(f"ID du paiement : {response['mappedOrderId']}")
print(f"URL de redirection : {response['url']}")
print(f"QR Code pour paiement : {response['qrcode']}")

Vérifier le statut d’un paiement

from fasoarzeka import check_payment

# Vérifier le statut avec l'ID de commande
status = check_payment("ORDER-2026-001")

print(f"Statut : {status['status']}")
print(f"Montant : {status['amount']} FCFA")
print(f"Date : {status['orderDate']}")

Exemple complet

from fasoarzeka import authenticate, initiate_payment, check_payment

# 1. S'authentifier
auth = authenticate("votre_username", "votre_password")
print(f"✅ Authentifié ! Token valide {auth['expires_in']}s")

# 2. Initier un paiement
payment_data = {
    "amount": 1000,
    "merchant_id": "MERCHANT_123",
    "additional_info": {
        "first_name": "Jean",
        "last_name": "Dupont",
        "mobile": "22670123456"
    },
    "mapped_order_id": "ORDER-2026-001",
    "hash_secret": "votre_secret",
    "link_for_update_status": "https://exemple.com/webhook",
    "link_back_to_calling_website": "https://exemple.com/retour"
}

response = initiate_payment(payment_data)
print(f"✅ Paiement initié : {response['url']}")

# 3. Vérifier le statut (après que l'utilisateur ait payé)
import time
time.sleep(5)  # Attendre quelques secondes
status = check_payment("ORDER-2026-001")
print(f"✅ Statut : {status['status']}")

Option 2 : Instance de classe

Cette approche offre plus de contrôle et est recommandée pour les applications en production.

Utilisation avec Context Manager

Le context manager gère automatiquement l’ouverture et la fermeture de la session :

from fasoarzeka import ArzekaPayment

with ArzekaPayment(base_url="https://pwg-test.fasoarzeka.com/") as client:
    # 1. S'authentifier
    auth = client.authenticate("votre_username", "votre_password")

    # 2. Initier un paiement
    response = client.initiate_payment(
        amount=1000,
        merchant_id="MERCHANT_123",
        additional_info={
            "first_name": "Jean",
            "last_name": "Dupont",
            "mobile": "22670123456"
        },
        mapped_order_id="ORDER-2026-001",
        hash_secret="votre_secret",
        link_for_update_status="https://exemple.com/webhook",
        link_back_to_calling_website="https://exemple.com/retour"
    )

    print(f"Paiement initié : {response['url']}")

    # 3. Vérifier le statut
    status = client.check_payment("ORDER-2026-001")
    print(f"Statut : {status['status']}")

Utilisation sans Context Manager

Si vous préférez gérer manuellement le cycle de vie du client :

from fasoarzeka import ArzekaPayment

# Créer le client
client = ArzekaPayment(base_url="https://pwg-test.fasoarzeka.com/")

try:
    # S'authentifier
    auth = client.authenticate("votre_username", "votre_password")

    # Faire des opérations
    response = client.initiate_payment(...)

finally:
    # Toujours fermer le client
    client.close()

Gestion des erreurs

La bibliothèque fournit des exceptions personnalisées pour différents types d’erreurs.

Exceptions disponibles

from fasoarzeka import (
    ArzekaPaymentError,         # Exception de base
    ArzekaValidationError,      # Erreur de validation des données
    ArzekaAuthenticationError,  # Erreur d'authentification
    ArzekaAPIError,             # Erreur retournée par l'API
    ArzekaConnectionError,      # Erreur de connexion réseau
    ArzekaTimeoutError         # Timeout de la requête
)

Exemple avec gestion d’erreurs

from fasoarzeka import (
    ArzekaPayment,
    ArzekaValidationError,
    ArzekaAuthenticationError,
    ArzekaAPIError,
    ArzekaConnectionError
)

with ArzekaPayment() as client:
    try:
        # S'authentifier
        auth = client.authenticate("username", "password")

        # Initier un paiement
        response = client.initiate_payment(
            amount=1000,
            merchant_id="MERCHANT_123",
            additional_info={
                "first_name": "Jean",
                "last_name": "Dupont",
                "mobile": "22670123456"
            },
            mapped_order_id="ORDER-2026-001",
            hash_secret="secret",
            link_for_update_status="https://exemple.com/webhook",
            link_back_to_calling_website="https://exemple.com/retour"
        )

        print(f"✅ Succès : {response['url']}")

    except ArzekaAuthenticationError as e:
        print(f"❌ Échec de l'authentification : {e}")

    except ArzekaValidationError as e:
        print(f"❌ Données invalides : {e}")

    except ArzekaAPIError as e:
        print(f"❌ Erreur API (code {e.status_code}) : {e}")
        print(f"Détails : {e.response_data}")

    except ArzekaConnectionError as e:
        print(f"❌ Erreur de connexion : {e}")

Fonctionnalités utiles

Formatage des numéros de téléphone

from fasoarzeka.utils import format_msisdn, validate_phone_number

# Formater un numéro (retire espaces, +, etc.)
phone = format_msisdn("+226 70 12 34 56")
print(phone)  # "22670123456"

# Valider un numéro
is_valid = validate_phone_number("22670123456")
print(is_valid)  # True

Génération du Hash

from fasoarzeka.utils import generate_hash

hash_value = generate_hash(
    mapped_order_id="ORDER-2026-001",
    amount=1000,
    hash_secret="votre_secret"
)
print(f"Hash : {hash_value}")

Configuration du Logging

import logging
from fasoarzeka import ArzekaPayment

# Activer les logs détaillés
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Les requêtes et réponses seront loggées
with ArzekaPayment() as client:
    client.authenticate("username", "password")

Exemples pratiques

Exemple 1 : Paiement simple

from fasoarzeka import authenticate, initiate_payment

# Authentifier
auth = authenticate("username", "password")

# Préparer et envoyer le paiement
response = initiate_payment({
    "amount": 1000,
    "merchant_id": "MERCHANT_123",
    "additional_info": {
        "first_name": "Marie",
        "last_name": "Kaboré",
        "mobile": "22670123456"
    },
    "mapped_order_id": "ORDER-001",
    "hash_secret": "secret",
    "link_for_update_status": "https://shop.com/webhook",
    "link_back_to_calling_website": "https://shop.com/success"
})

# Rediriger l'utilisateur vers l'URL de paiement
print(f"Redirigez vers : {response['url']}")

Exemple 2 : Vérification périodique du statut

import time
from fasoarzeka import check_payment

order_id = "ORDER-001"
max_attempts = 10

for attempt in range(max_attempts):
    status = check_payment(order_id)

    if status['status'] == 'COMPLETED':
        print("✅ Paiement réussi !")
        break
    elif status['status'] == 'FAILED':
        print("❌ Paiement échoué")
        break
    else:
        print(f"⏳ En attente... (tentative {attempt + 1}/{max_attempts})")
        time.sleep(5)  # Attendre 5 secondes

Exemple 3 : Application web Flask

from flask import Flask, request, redirect, jsonify
from fasoarzeka import ArzekaPayment

app = Flask(__name__)
client = ArzekaPayment()

@app.route('/payer', methods=['POST'])
def create_payment():
    # Authentifier si nécessaire
    if not client.is_token_valid():
        client.authenticate("username", "password")

    # Récupérer les données du formulaire
    data = request.json

    # Initier le paiement
    response = client.initiate_payment(
        amount=data['amount'],
        merchant_id="MERCHANT_123",
        additional_info={
            "first_name": data['first_name'],
            "last_name": data['last_name'],
            "mobile": data['mobile']
        },
        mapped_order_id=data['order_id'],
        hash_secret="votre_secret",
        link_for_update_status="https://votresite.com/webhook",
        link_back_to_calling_website="https://votresite.com/success"
    )

    # Retourner l'URL de paiement
    return jsonify({
        'payment_url': response['url'],
        'order_id': response['mappedOrderId']
    })

@app.route('/webhook', methods=['POST'])
def webhook():
    # Recevoir la notification de paiement
    data = request.json
    order_id = data.get('mappedOrderId')

    # Vérifier le statut
    status = client.check_payment(order_id)

    # Mettre à jour votre base de données
    # ...

    return jsonify({'status': 'received'})

if __name__ == '__main__':
    app.run(debug=True)

Prochaines étapes

Maintenant que vous maîtrisez les bases, explorez :