Référence API

Cette page fournit la documentation complète de toutes les classes, méthodes et fonctions disponibles.

Classes principales

ArzekaPayment

Classe principale pour interagir avec l’API Faso Arzeka.

from fasoarzeka import ArzekaPayment

client = ArzekaPayment(
    token="",
    base_url="https://pwg-test.fasoarzeka.com/",
    timeout=30,
    max_retries=3,
    verify_ssl=True
)

Paramètres du constructeur

Paramètre	Type	Défaut	Description
`token`	`str`	`""`	Token d’authentification (peut être vide si vous appelez `authenticate()`)
`base_url`	`str`	Test URL	URL de base de l’API
`timeout`	`int`	`30`	Timeout des requêtes en secondes
`max_retries`	`int`	`3`	Nombre maximum de tentatives en cas d’échec
`verify_ssl`	`bool`	`True`	Vérifier les certificats SSL

Méthodes

authenticate()

Authentifie l’utilisateur et obtient un token d’accès.

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

Paramètres:

username (str) : Nom d’utilisateur Arzeka
password (str) : Mot de passe Arzeka

Retour: Dictionnaire avec access_token, token_type, expires_in

Exceptions:

ArzekaAuthenticationError : Échec de l’authentification
ArzekaConnectionError : Problème de connexion
ArzekaAPIError : Erreur API

Exemple:

auth = client.authenticate("username", "password")
print(auth['access_token'])

initiate_payment()

Initialise un nouveau paiement.

def initiate_payment(
    self,
    amount: int,
    merchant_id: str,
    additional_info: Dict[str, str],
    hash_secret: str,
    link_for_update_status: str,
    link_back_to_calling_website: str,
    mapped_order_id: Optional[str] = None,
    order_description: Optional[str] = None
) -> Dict[str, Any]

Paramètres:

amount (int) : Montant en FCFA (minimum 100)
merchant_id (str) : Identifiant marchand
additional_info (dict) : Informations client (first_name, last_name, mobile)
hash_secret (str) : Clé secrète pour le hash
link_for_update_status (str) : URL du webhook
link_back_to_calling_website (str) : URL de retour
mapped_order_id (str, optionnel) : ID de commande personnalisé
order_description (str, optionnel) : Description de la commande

Retour: Dictionnaire avec mappedOrderId, url, qrcode, status

Exceptions:

ArzekaValidationError : Données invalides
ArzekaAuthenticationError : Token expiré ou invalide
ArzekaAPIError : Erreur API
ArzekaConnectionError : Problème de connexion

Exemple:

response = client.initiate_payment(
    amount=1000,
    merchant_id="MERCHANT_123",
    additional_info={
        "first_name": "Jean",
        "last_name": "Dupont",
        "mobile": "22670123456"
    },
    hash_secret="secret",
    link_for_update_status="https://example.com/webhook",
    link_back_to_calling_website="https://example.com/return"
)

check_payment()

Vérifie le statut d’un paiement.

def check_payment(self, mapped_order_id: str) -> Dict[str, Any]

Paramètres:

mapped_order_id (str) : ID de la commande

Retour: Dictionnaire avec mappedOrderId, status, amount, orderDate, etc.

Exceptions:

ArzekaAuthenticationError : Token expiré ou invalide
ArzekaAPIError : Erreur API (404 si commande introuvable)
ArzekaConnectionError : Problème de connexion

Exemple:

status = client.check_payment("ORDER-2026-001")
print(status['status'])

is_token_valid()

Vérifie si le token est encore valide.

def is_token_valid(self, margin_seconds: int = 60) -> bool

Paramètres:

margin_seconds (int) : Marge de sécurité en secondes (défaut : 60)

Retour: True si le token est valide, False sinon

Exemple:

if client.is_token_valid():
    print("Token valide")

get_token_expiry_info()

Obtient des informations détaillées sur l’expiration du token.

def get_token_expiry_info(self) -> Dict[str, Any]

Retour: Dictionnaire avec is_valid, expires_at, seconds_remaining, etc.

Exemple:

info = client.get_token_expiry_info()
print(f"Expire dans {info['minutes_remaining']:.1f} minutes")

close()

Ferme la session et libère les ressources.

def close(self) -> None

Exemple:

client.close()

Ou utilisez un context manager :

with ArzekaPayment() as client:
    # ... utiliser le client
    pass
# close() appelé automatiquement

Fonctions de convenance

authenticate()

Fonction pour s’authentifier rapidement.

from fasoarzeka import authenticate

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

Paramètres:

username (str) : Nom d’utilisateur
password (str) : Mot de passe
base_url (str, optionnel) : URL de l’API

Retour: Dictionnaire d’authentification

Exemple:

auth = authenticate("username", "password")
token = auth['access_token']

initiate_payment()

Fonction pour initier un paiement rapidement.

from fasoarzeka import initiate_payment

def initiate_payment(payment_data: Dict[str, Any]) -> Dict[str, Any]

Paramètres:

payment_data (dict) : Dictionnaire contenant tous les paramètres du paiement

Retour: Dictionnaire de réponse

Exemple:

response = initiate_payment({
    "amount": 1000,
    "merchant_id": "MERCHANT_123",
    # ... autres paramètres
})

check_payment()

Fonction pour vérifier un paiement rapidement.

from fasoarzeka import check_payment

def check_payment(mapped_order_id: str) -> Dict[str, Any]

Paramètres:

mapped_order_id (str) : ID de la commande

Retour: Dictionnaire de statut

Exemple:

status = check_payment("ORDER-2026-001")

Utilitaires

Module fasoarzeka.utils

format_msisdn()

Formate un numéro de téléphone au format requis.

from fasoarzeka.utils import format_msisdn

def format_msisdn(phone: str) -> str

Paramètres:

phone (str) : Numéro de téléphone à formater

Retour: Numéro formaté (sans espaces, +, etc.)

Exemple:

phone = format_msisdn("+226 70 12 34 56")
# Retourne: "22670123456"

validate_phone_number()

Valide un numéro de téléphone.

from fasoarzeka.utils import validate_phone_number

def validate_phone_number(phone: str) -> bool

Paramètres:

phone (str) : Numéro à valider

Retour: True si valide, False sinon

Exemple:

if validate_phone_number("22670123456"):
    print("Numéro valide")

generate_hash()

Génère un hash pour sécuriser les transactions.

from fasoarzeka.utils import generate_hash

def generate_hash(
    mapped_order_id: str,
    amount: int,
    hash_secret: str
) -> str

Paramètres:

mapped_order_id (str) : ID de commande
amount (int) : Montant
hash_secret (str) : Clé secrète

Retour: Hash calculé

Exemple:

hash_value = generate_hash("ORDER-001", 1000, "secret")

Voir aussi

Exceptions : Toutes les exceptions disponibles
Bonnes pratiques : Bonnes pratiques d’utilisation
Guide de démarrage rapide : Guide de démarrage rapide