Authentification

Vue d’ensemble

L’authentification est la première étape obligatoire pour utiliser l’API Faso Arzeka Payment. Elle permet d’obtenir un token d’accès JWT (JSON Web Token) nécessaire pour effectuer toutes les opérations ultérieures.

Fonctionnement

Le processus d’authentification suit ce schéma :

Envoi des identifiants : Vous envoyez votre username et password à l’API
Validation : L’API vérifie vos identifiants
Génération du token : En cas de succès, l’API génère un token JWT
Utilisation du token : Vous utilisez ce token pour toutes vos requêtes suivantes

Note

Les tokens JWT ont une durée de validité limitée (généralement 3600 secondes / 1 heure). Après expiration, vous devez vous réauthentifier.

Méthodes d’authentification

Il existe deux façons de s’authentifier avec cette bibliothèque.

Méthode 1 : Fonction de convenance `authenticate()`

C’est la méthode la plus simple pour une authentification rapide.

Signature

def authenticate(
    username: str,
    password: str,
    base_url: str = DEFAULT_BASE_URL
) -> Dict[str, Any]

Paramètres

Paramètre	Type	Description
`username`	`str`	Votre identifiant utilisateur Arzeka (obligatoire)
`password`	`str`	Votre mot de passe Arzeka (obligatoire)
`base_url`	`str`	URL de base de l’API (optionnel, défaut : environnement de test)

Valeur de retour

La fonction retourne un dictionnaire contenant :

Champ	Type	Description
`access_token`	`str`	Token JWT pour authentifier les requêtes suivantes
`token_type`	`str`	Type de token, généralement `"Bearer"`
`expires_in`	`int`	Durée de validité du token en secondes

Exemple d’utilisation

from fasoarzeka import authenticate

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

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

# Extraire le token pour utilisation ultérieure
token = auth['access_token']

Méthode 2 : Méthode de classe `ArzekaPayment.authenticate()`

Cette méthode est intégrée à la classe ArzekaPayment et met automatiquement à jour le token du client.

Signature

def authenticate(
    self,
    username: str,
    password: str
) -> Dict[str, Any]

Paramètres

Paramètre	Type	Description
`username`	`str`	Votre identifiant utilisateur Arzeka
`password`	`str`	Votre mot de passe Arzeka

Valeur de retour

Retourne le même dictionnaire que la fonction de convenance, mais met également à jour :

self._token : Le nouveau token d’accès
self._expires_at : Timestamp d’expiration du token
self._username : Username stocké pour réauthentification automatique
self._password : Password stocké pour réauthentification automatique

Exemple d’utilisation

from fasoarzeka import ArzekaPayment

# Créer le client sans token
with ArzekaPayment(token="") as client:
    # S'authentifier
    auth = client.authenticate("votre_username", "votre_password")

    print(f"✅ Authentifié ! Token valide {auth['expires_in']}s")

    # Le client utilise maintenant automatiquement le token
    response = client.initiate_payment(
        amount=1000,
        merchant_id="MERCHANT_123",
        # ... autres paramètres
    )

Exemples pratiques

Exemple 1 : Workflow complet (Authentification + Paiement)

from fasoarzeka import authenticate, initiate_payment

# 1. S'authentifier pour obtenir le token
auth = authenticate("user@example.com", "password123")
token = auth['access_token']

print(f"✅ Token obtenu, valide pendant {auth['expires_in']} secondes")

# 2. Utiliser le token dans les opérations suivantes
# (Le token est automatiquement utilisé par les fonctions de convenance)
response = initiate_payment({
    "amount": 1000,
    "merchant_id": "MERCHANT_123",
    "additional_info": {
        "first_name": "Jean",
        "last_name": "Dupont",
        "mobile": "22670123456"
    },
    "mapped_order_id": "ORDER-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']}")

Exemple 2 : Authentification intégrée avec la classe

from fasoarzeka import ArzekaPayment

# Le client s'authentifie et met à jour son token automatiquement
with ArzekaPayment() as client:
    # S'authentifier
    auth = client.authenticate("user@example.com", "password123")

    print(f"Token type: {auth['token_type']}")
    print(f"Expires in: {auth['expires_in']}s")

    # Faire plusieurs opérations avec le même client
    response1 = client.initiate_payment(...)
    response2 = client.check_payment("ORDER-001")
    response3 = client.initiate_payment(...)

Exemple 3 : Gestion des erreurs d’authentification

from fasoarzeka import authenticate, ArzekaAuthenticationError

try:
    auth = authenticate("user@example.com", "wrong_password")
    print(f"✅ Authentification réussie")

except ArzekaAuthenticationError as e:
    print(f"❌ Échec de l'authentification : {e}")
    # Gérer l'erreur : afficher un message, demander de réessayer, etc.

Exemple 4 : Authentification avec configuration depuis l’environnement

import os
from fasoarzeka import authenticate

# Lire les identifiants depuis les variables d'environnement
username = os.getenv('ARZEKA_USERNAME')
password = os.getenv('ARZEKA_PASSWORD')
base_url = os.getenv('ARZEKA_BASE_URL', 'https://pwg-test.fasoarzeka.com/')

# Vérifier que les identifiants sont définis
if not username or not password:
    raise ValueError("Variables ARZEKA_USERNAME et ARZEKA_PASSWORD requises")

# S'authentifier
auth = authenticate(username, password, base_url)
print(f"✅ Authentification réussie")

Exemple 5 : Client long-running avec réauthentification

import time
from fasoarzeka import ArzekaPayment

client = ArzekaPayment()
client.authenticate("username", "password")

# Application qui tourne longtemps
while True:
    try:
        # Vérifier si le token est toujours valide
        if not client.is_token_valid():
            print("⚠️ Token expiré, réauthentification...")
            client.authenticate("username", "password")

        # Faire des opérations
        status = client.check_payment("ORDER-001")
        print(f"Statut : {status['status']}")

        # Attendre avant la prochaine vérification
        time.sleep(300)  # 5 minutes

    except KeyboardInterrupt:
        print("Arrêt du client")
        client.close()
        break

Gestion du stockage des identifiants

Pourquoi stocker les identifiants ?

La bibliothèque stocke automatiquement votre username et password lors de l’authentification. Cela permet la réauthentification automatique lorsque le token expire.

client = ArzekaPayment()

# À l'authentification, les credentials sont stockés
client.authenticate("username", "password")
# → self._username = "username"
# → self._password = "password"
# → self._token = "eyJhbGciOiJIUz..."
# → self._expires_at = 1709564421

# Plus tard, si le token expire, réauthentification automatique
response = client.initiate_payment(...)
# → Vérifie is_token_valid()
# → Si expiré, réauthentifie avec les credentials stockés
# → Puis fait la requête

Sécurité des identifiants

Danger

Important : Les identifiants sont stockés en mémoire pendant la durée de vie du client.

✅ Sécurisé : Stockage en mémoire uniquement (non persisté sur disque)
⚠️ Attention : Ne pas logger ou afficher les identifiants
⚠️ Attention : Utiliser HTTPS en production
✅ Recommandé : Utiliser des variables d’environnement

Bonnes pratiques de sécurité

import os
from fasoarzeka import ArzekaPayment

# ✅ BON : Lire depuis les variables d'environnement
client = ArzekaPayment()
client.authenticate(
    os.getenv('ARZEKA_USERNAME'),
    os.getenv('ARZEKA_PASSWORD')
)

# ❌ MAUVAIS : Hard-coder les identifiants dans le code
client.authenticate("username", "password")  # Ne pas faire ça !

Variables d’environnement

Définir les variables d’environnement :

Bash / Zsh :

export ARZEKA_USERNAME="votre_username"
export ARZEKA_PASSWORD="votre_password"
export ARZEKA_BASE_URL="https://pwg-test.fasoarzeka.com/"

Fichier .env :

ARZEKA_USERNAME=votre_username
ARZEKA_PASSWORD=votre_password
ARZEKA_BASE_URL=https://pwg-test.fasoarzeka.com/

Puis avec python-dotenv :

from dotenv import load_dotenv
import os
from fasoarzeka import authenticate

# Charger les variables depuis .env
load_dotenv()

# Utiliser les variables
auth = authenticate(
    os.getenv('ARZEKA_USERNAME'),
    os.getenv('ARZEKA_PASSWORD'),
    os.getenv('ARZEKA_BASE_URL')
)

Référence des erreurs d’authentification

Exception `ArzekaAuthenticationError`

Cette exception est levée en cas d’échec d’authentification.

Causes possibles

Identifiants incorrects

# Username ou password invalide
auth = authenticate("wrong_user", "wrong_pass")
# → ArzekaAuthenticationError: Authentication failed

Compte verrouillé ou désactivé

# Compte bloqué par l'administrateur
auth = authenticate("locked_user", "password")
# → ArzekaAuthenticationError: Account locked

Problème réseau

# Impossible de joindre l'API
auth = authenticate("user", "pass")
# → ArzekaConnectionError: Connection failed

Gestion des erreurs

from fasoarzeka import (
    authenticate,
    ArzekaAuthenticationError,
    ArzekaConnectionError
)

max_retries = 3

for attempt in range(max_retries):
    try:
        auth = authenticate("username", "password")
        print("✅ Authentification réussie")
        break

    except ArzekaAuthenticationError as e:
        print(f"❌ Authentification échouée : {e}")
        # Ne pas réessayer si les identifiants sont incorrects
        break

    except ArzekaConnectionError as e:
        print(f"⚠️ Erreur de connexion (tentative {attempt+1}/{max_retries})")
        if attempt < max_retries - 1:
            time.sleep(2)  # Attendre avant de réessayer

Résolution des problèmes courants

Problème : « Token expired »

Cause : Vous tentez d’utiliser un token expiré.

Solution : Réauthentifiez-vous ou utilisez la réauthentification automatique.

# Solution manuelle
if not client.is_token_valid():
    client.authenticate("username", "password")

# Solution automatique (recommandé)
# La bibliothèque gère automatiquement la réauthentification
response = client.initiate_payment(...)  # Auto re-auth si nécessaire

Problème : « Invalid credentials »

Cause : Username ou password incorrect.

Solution : Vérifiez vos identifiants.

# Vérifier que les variables d'environnement sont correctement définies
import os
print(f"Username: {os.getenv('ARZEKA_USERNAME')}")
# Ne jamais print le password !

Problème : SSL Certificate Error

Cause : Problème de certificat SSL.

Solution : Mettre à jour les certificats ou désactiver la vérification (uniquement en test).

# En environnement de test seulement
client = ArzekaPayment(verify_ssl=False)

Prochaines étapes

Maintenant que vous maîtrisez l’authentification, explorez :

Réauthentification automatique : Réauthentification automatique
Validation des tokens : Validation et vérification des tokens
Paiements : Guide complet des paiements
Bonnes pratiques : Bonnes pratiques de sécurité

Authentification

Vue d’ensemble

Fonctionnement

Méthodes d’authentification

Méthode 1 : Fonction de convenance authenticate()

Signature

Paramètres

Valeur de retour

Exemple d’utilisation

Méthode 2 : Méthode de classe ArzekaPayment.authenticate()

Signature

Paramètres

Valeur de retour

Exemple d’utilisation

Exemples pratiques

Exemple 1 : Workflow complet (Authentification + Paiement)

Exemple 2 : Authentification intégrée avec la classe

Exemple 3 : Gestion des erreurs d’authentification

Exemple 4 : Authentification avec configuration depuis l’environnement

Exemple 5 : Client long-running avec réauthentification

Gestion du stockage des identifiants

Pourquoi stocker les identifiants ?

Sécurité des identifiants

Bonnes pratiques de sécurité

Variables d’environnement

Référence des erreurs d’authentification

Exception ArzekaAuthenticationError

Causes possibles

Gestion des erreurs

Résolution des problèmes courants

Problème : « Token expired »

Problème : « Invalid credentials »

Problème : SSL Certificate Error

Prochaines étapes

Méthode 1 : Fonction de convenance `authenticate()`

Méthode 2 : Méthode de classe `ArzekaPayment.authenticate()`

Exception `ArzekaAuthenticationError`