Guide d'Intégration - API Airtel Money

1. 🔑 Authentification (Obtention du Token)

Toutes les requêtes vers l'API Airtel nécessitent un Bearer Token obtenu via l'authentification OAuth 2.0.

Endpoint

Méthode	URL de Base	Endpoint
`POST`	`https://openapiuat.airtel.africa`	`/auth/oauth2/token`

Requête (cURL)

curl -X POST 'https://openapiuat.airtel.africa/auth/oauth2/token' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-d '{
    "client_id": "VOTRE_CLIENT_ID",
    "client_secret": "VOTRE_CLIENT_SECRET",
    "grant_type": "client_credentials"
}'

Utilisation du Token

Le token reçu dans la réponse doit être inclus dans l'en-tête Authorization de toutes les requêtes subséquentes :

Authorization: Bearer VOTRE_ACCESS_TOKEN

2. 🔒 Chiffrement des Données (PIN Encryption)

Pour des raisons de sécurité, le PIN de l'utilisateur dans les requêtes de Disbursement ou Cash-In doit être chiffré via la clé publique RSA fournie par Airtel.

Étapes du Chiffrement :

Récupérer la Clé Publique RSA : GET /v1/rsa/encryption-keys.
Chiffrer le PIN : Utiliser la clé publique RSA pour chiffrer le PIN de l'utilisateur.
Soumettre : Le résultat chiffré doit être envoyé dans le champ pin du corps de la requête.

3. 💵 Catégories d'API et Transactions Clés

A. Collection (Paiements Entrants)

Fonctionnalité	Méthode	Endpoint	Rôle
Paiement USSD Push	`POST`	`/merchant/v2/payments/`	Initie un paiement, l'utilisateur est invité à valider sur son mobile.
Remboursement	`POST`	`/standard/v2/payments/refund`	Rembourse une transaction existante (nécessite l'ID Airtel Money).

Headers Spécifiques (Sécurité) : Les requêtes de transaction nécessitent les en-têtes de sécurité x-signature (HMAC-SHA256) et x-key.

B. Disbursement (Paiements Sortants)

Utilisé pour les transferts de fonds de l'opérateur vers les utilisateurs (B2C ou B2B). Nécessite le PIN chiffré.

Paiements: POST /standard/v3/disbursements
Statut: GET /standard/v3/disbursements/{id}

4. 🔗 Fonctionnalités Supplémentaires

A. Webhooks (Callbacks) : Confirmation Asynchrone

Les callbacks sont des notifications asynchrones envoyées par Airtel pour vous informer du statut final de vos transactions (prêts, paiements).

Vérification HMAC Essentielle: Vous devez impérativement vérifier l'en-tête x-signature reçu dans le callback via l'algorithme HMAC-SHA256 (voir exemple de code dans le tableau détaillé) pour garantir que les données sont authentiques.

B. KYC et Solde

User KYC Enquiry: Vérifie les informations d'identité associées à un numéro de téléphone (`GET /standard/v2/users/{msisdn}`).
Balance Enquiry: Vérifie le solde du compte de l'opérateur avant un décaissement (`GET /standard/v1/users/balance`).

5. 🌍 Notes Importantes sur l'Environnement

Environnement UAT/Production: Remplacez l'URL de test (`https://openapiuat.airtel.africa`) par l'URL de production lors du déploiement.
Headers Régionaux: X-Country (ex: UG, ZM) et X-Currency (ex: UGX, ZMW) sont obligatoires pour définir le contexte de la transaction.

Guide d'Intégration de l'API Airtel Money