📋 Vue d'ensemble

L'API PayFisc permet aux banques et partenaires financiers d'integrer le systeme de paiement des taxes et impots. Construite avec Go (Fiber v3) pour des performances elevees et une securite maximale.

Base URLhttps://dev-api-mpako.com
ProtocoleHTTPS obligatoire
FormatJSON (application/json)
AuthJWT Bearer Token
EncodingUTF-8
Rate Limit100 req/min par IP
Note : Tous les endpoints de paiement necessitent un token JWT obtenu via /api/auth/login.

🔄 Flux de paiement

1. Login
→
2. Initialiser
→
3. Confirmer
ou
3. Annuler

Le partenaire s'authentifie, initialise un paiement, puis confirme ou annule. Alternativement, le partenaire peut notifier lui-meme via le callback /api/paiement/callback pour declencher une confirmation automatique. Un webhook est envoye apres chaque confirmation ou annulation.

1. Login
→
2. Initialiser
→
3a. Confirmer
ou
3b. Callback
ou
3c. Annuler

🔐 Authentification

POST /api/auth/login

Authentifie un partenaire bancaire et retourne un token JWT.

Corps de la requete

{
    "bank_id": "BANK_001",
    "api_key": "votre-cle-api-secrete"
}

Parametres

  • bank_idstringrequis— Identifiant unique de la banque partenaire
  • api_keystringrequis— Cle API secrete fournie lors de l'inscription

Verifications effectuees

1IP autorisee (whitelist)
2User-Agent autorise
3Identifiants valides (comparaison timing-safe)
4Compte actif et non suspendu
5Cle API non expiree
6Permissions suffisantes
7Limites de transactions respectees

Reponse succes — 200

{
    "status": "success",
    "message": "Authentification reussie",
    "data": {
        "token": "eyJhbGciOi...",
        "expires_at": "2026-04-18 22:30:00",
        "bank_name": "Banque Partenaire",
        "bank_id": "BANK_001",
        "permissions": ["process_payments"],
        "limits": {
            "daily": 10000000,
            "monthly": 100000000,
            "min_amount": 100,
            "max_amount": 5000000
        }
    }
}

Exemple cURL

curl -X POST https://dev-api-mpako.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "BANK_001",
    "api_key": "votre-cle-api-secrete"
  }'

🚀 Initialiser un paiement

POST /api/paiement/initialiser JWT requis

Cree un paiement en attente valide 1 heure. Le comportement varie selon la combinaison taxe_id + province_id.

Structure generale de la requete

  • taxe_idintegerrequis— ID de la taxe
  • province_idintegerrequis— ID de la province
  • criteres.telephonestringrequis— Numero de telephone (10 chiffres max). Les 3 premiers chiffres doivent obligatoirement être l'un des prefixes : 080, 081, 082, 083, 084, 085, 089, 090, 097, 098, 099 — obligatoire pour toutes les taxes
  • criteres.typestringoptionnel*— Categorie tarifaire (obligatoire pour le peage)
Combinaisons supportees : Seules les paires taxe_id + province_id ci-dessous sont actives. Toute autre combinaison retourne TAXE_PROVINCE_NOT_SUPPORTED.

✂ Taxe d'assainissement — taxe_id: 23 & province_id: 31

Recherche le contribuable par numero de telephone, recupere ses factures impayees/en retard. Le champ type est ignore.

{
    "taxe_id": 23,
    "province_id": 31,
    "criteres": {
        "telephone": "0891234567"
    }
}

Reponse — contribuable existant connu

{
    "status": "success",
    "message": "Paiement initialise avec succes",
    "data": {
        "reference_paiement": "PAY-20260514-ABC123",
        "taxe": { "id": 23, "nom": "Taxe d'assainissement", "description": "..." },
        "taux": { "id": 1, "nom": "Taux standard", "valeur": 5.00 },
        "contribuable": {
            "id": 42,
            "reference": "CONTRIB-2026-001",
            "nom": "KABONGO",
            "prenom": "Jean",
            "telephone": "0891234567"
        },
        "factures": [
            {
                "id": 101,
                "reference": "FACT-2026-001",
                "montant": 15000.00,
                "periode_debut": "2026-01-01",
                "periode_fin": "2026-03-31",
                "date_echeance": "2026-03-31",
                "statut": "impayee"
            }
        ],
        "montant_total": 15000.00,
        "province_id": 31,
        "date_expiration": "2026-05-14 23:30:00"
    }
}

🛣 Taxe de Peage — taxe_id: 36 & province_id: 31

Paiement anonyme : aucun compte contribuable n'est requis. Le montant est determine automatiquement selon la categorie tarifaire fournie dans criteres.type (1 passage).

  • criteres.typestringrequis— Categorie tarifaire du vehicule (ex: «Moto», «Voiture»)
  • criteres.telephonestringrequis— Numero de telephone (10 chiffres max). Les 3 premiers chiffres doivent obligatoirement être l'un des prefixes : 080, 081, 082, 083, 084, 085, 089, 090, 097, 098, 099
{
    "taxe_id": 36,
    "province_id": 31,
    "criteres": {
        "type": "Moto",
        "telephone": "0891234567"
    }
}

Reponse — contribuable anonyme

Les champs id, nom et prenom du contribuable sont null (paiement anonyme). La facture est generee a la volee, son id est aussi null.

{
    "status": "success",
    "message": "Paiement initialise avec succes",
    "data": {
        "reference_paiement": "PAY-20260514-XYZ789",
        "taxe": { "id": 36, "nom": "Taxe de peage", "description": "..." },
        "taux": { "id": 3, "nom": "Taux peage standard", "valeur": 100.00, "description": "Tarif unitaire peage" },
        "contribuable": {
            "id": null,
            "reference": "CONTRIB-20260514-R4T8",
            "nom": null,
            "prenom": null,
            "telephone": "0891234567"
        },
        "factures": [
            {
                "id": null,
                "reference": "FACT-20260514-K9P2",
                "montant": 2500.00,
                "periode_debut": "2026-05-14",
                "periode_fin": "2026-05-14",
                "date_echeance": "2026-05-14",
                "statut": "impayee"
            }
        ],
        "montant_total": 2500.00,
        "province_id": 31,
        "date_expiration": "2026-05-14 15:00:00"
    }
}
Tarif peage : Le tarif est recherche parmi les categories actives de la province 31. Si le type fourni ne correspond a aucune categorie active, l'erreur TARIFF_NOT_FOUND est retournee.
Expiration : Tout paiement initialise expire apres 1 heure et passe en statut annule.

✅ Confirmer un paiement

POST /api/paiement/confirmer JWT requis

Confirme un paiement initialise. Cree les enregistrements de paiement, la repartition beneficiaires, et met a jour les factures dans une transaction atomique.

Flux de traitement

Valider ref.
→
Verifier expiration
→
BEGIN TX
→
Creer paiement
→
Repartir
→
COMMIT

Parametres

  • reference_paiementstringrequis— Reference obtenue lors de l'initialisation
  • methode_paiementstringrequis— mobile_money | banque | especes

Corps de la requete

{
    "reference_paiement": "PAY-20260418-ABC123",
    "methode_paiement": "mobile_money"
}

Reponse succes — 200

{
    "status": "success",
    "message": "Paiement confirme avec succes",
    "data": {
        "reference_paiement": "PAY-20260418-ABC123",
        "paiement_id": 256,
        "montant_total": 15000.00,
        "methode_paiement": "mobile_money",
        "nombre_factures": 1,
        "taux": {
            "id": 1,
            "nom": "Taux standard",
            "valeur": 5.00
        },
        "repartition": [
            {
                "beneficiaire_id": 1,
                "nom": "Tresor Public",
                "numero_compte": "CD001-00012345",
                "type_part": "pourcentage",
                "valeur_part": 60,
                "montant": 9000.00
            },
            {
                "beneficiaire_id": 2,
                "nom": "Province",
                "numero_compte": "CD002-00054321",
                "type_part": "pourcentage",
                "valeur_part": 40,
                "montant": 6000.00
            }
        ],
        "date_paiement": "2026-04-18 14:35:22"
    }
}

❌ Annuler un paiement

POST /api/paiement/annuler JWT requis

Annule un paiement (en attente ou confirme). Si confirme, supprime atomiquement les enregistrements, remet les factures en "impayee", et decremente les compteurs.

Corps de la requete

{
    "reference_paiement": "PAY-20260418-ABC123"
}

Reponse succes — 200

{
    "status": "success",
    "message": "Paiement annule avec succes",
    "data": {
        "reference_paiement": "PAY-20260418-ABC123",
        "status": "annule"
    }
}

📞 Callback partenaire entrant

POST /api/paiement/callback SIGNATURE HMAC

Endpoint public (pas de JWT requis) que le partenaire bancaire utilise pour notifier l'API d'un paiement effectue de son cote. Si le statut est succes et que le paiement est en attente, la confirmation est automatique.

Securite : Si un secret_webhook est configure pour le partenaire, le header X-Webhook-Signature est obligatoire et doit etre valide. Un hash invalide retourne INVALID_SIGNATURE (HTTP 401).

Headers requis

Content-Type: application/json
X-Webhook-Signature: <hmac-sha256-hex(body, secret_webhook)>
# Optionnel si bank_id est dans le body :
X-Bank-ID: BANK_001

Format JSON — a respecter strictement

  • reference_paiementstringrequis— Reference obtenue lors de l'initialisation (PAY-...)
  • bank_idstringrequis— Identifiant du partenaire bancaire
  • statutstringrequis— succes ou echec
  • transaction_idstringrequis— Identifiant unique de la transaction cote partenaire
  • montantnumberrequis— Montant effectivement debite (float, > 0)
  • methode_paiementstringrequis— mobile_money | banque | especes
  • metadataobjectoptionnel— Donnees libres (logs, transaction interne, etc.)

Corps de la requete

{
    "reference_paiement": "PAY-20260514-XYZ789",
    "bank_id": "BANK_001",
    "statut": "succes",
    "transaction_id": "TXN-2026-00987",
    "montant": 2500.00,
    "methode_paiement": "mobile_money",
    "metadata": {
        "operateur": "Airtel Money",
        "numero_msisdn": "0891234567"
    }
}

Reponse succes — 200

{
    "status": "success",
    "message": "Callback recu et paiement confirme automatiquement",
    "data": {
        "reference_paiement": "PAY-20260514-XYZ789",
        "statut": "succes",
        "message": "Callback recu et paiement confirme automatiquement"
    }
}

Calcul de la signature HMAC-SHA256

# Exemple en bash :
BODY='{"reference_paiement":"PAY-...", ...}'
SECRET="votre-secret-webhook"
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://dev-api-mpako.com/api/paiement/callback \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -H "X-Bank-ID: BANK_001" \
  -d "$BODY"

Ce qui est enregistre apres reception du callback

ChampDescription
reference_paiementReference du paiement partenaire
bank_idIdentifiant de la banque
statutsucces | echec | en_attente
transaction_idID cote partenaire
montantMontant notifie
methode_paiementMode de paiement
metadata_jsonDonnees libres JSON
signature_valide1 si HMAC verifie, 0 sinon
ipIP source du callback
date_receptionHorodatage reception
date_traitementHorodatage confirmation (si auto)

💚 Health Check

GET /health

Verifie l'etat de l'API et de la connexion a la base de donnees.

{
    "status": "ok",
    "service": "MPAKO API",
    "version": "2.1.0",
    "database": "ok",
    "uptime": "2026-04-18T14:00:00Z"
}

🔔 Webhooks (Callbacks)

Apres chaque confirmation ou annulation, le systeme envoie automatiquement une notification HTTP POST vers l'URL webhook configuree pour le partenaire.

Configuration webhook

ChampDescription
url_webhook_confirmationURL appelee apres confirmation
url_webhook_annulationURL appelee apres annulation
secret_webhookCle HMAC-SHA256 pour signer les payloads

Headers envoyes

POST {url_webhook}
Content-Type: application/json
X-Webhook-Event: confirmation | annulation
X-Webhook-Timestamp: 2026-04-18T14:35:22Z
X-Webhook-Signature: hmac-sha256-hex-signature

Payload — Confirmation

{
    "event": "confirmation",
    "timestamp": "2026-04-18T14:35:22Z",
    "data": {
        "reference_paiement": "PAY20260418143500AB1CD",
        "paiement_id": 256,
        "montant_total": 15000.00,
        "methode_paiement": "mobile_money",
        "nombre_factures": 1,
        "repartition": [...],
        "date_paiement": "2026-04-18 14:35:22"
    }
}

Payload — Annulation

{
    "event": "annulation",
    "timestamp": "2026-04-18T14:40:10Z",
    "data": {
        "reference_paiement": "PAY20260418143500AB1CD",
        "status": "annule"
    }
}
Asynchrone : Les webhooks sont non-bloquants. Si l'URL echoue, le paiement reste confirme/annule. Timeout : timeout_api du partenaire (defaut 30s).

📊 Compteurs & Suspension

Compteurs automatiques

A chaque confirmation/annulation, les compteurs du partenaire sont mis a jour :

CompteurConfirmationAnnulation
total_transactions+1-1
total_montant+montant-montant

Suspension de compte

Quand un partenaire est suspendu (suspendu = 1), l'authentification retourne :

{
    "status": "error",
    "code": "ACCOUNT_SUSPENDED",
    "message": "Compte suspendu: Facture impayee depuis le 01/03/2026"
}

💰 Combinaisons taxe + province supportees

taxe_idprovince_idNomcriteres.typeContribuable
2331 Taxe d'assainissement Ignore Existant (par telephone)
2631 Taxe de Peage Requis — categorie tarifaire exacte (ex : Moto, Voiture) Anonyme (id=null, nom=null)

D'autres combinaisons seront ajoutees progressivement.

⚠️ Codes d'erreur

Toutes les erreurs suivent le format unifie :

{
    "status": "error",
    "code": "CODE_ERREUR",
    "message": "Description lisible"
}

Authentification

CodeHTTPDescription
AUTH_FAILED401Identifiants invalides ou compte inactif
ACCOUNT_SUSPENDED403Compte suspendu (raison indiquee)
INVALID_TOKEN401Token JWT invalide ou expire
INVALID_SESSION401Session invalide, reconnexion requise
INSUFFICIENT_PERMISSIONS403Permissions insuffisantes
IP_NOT_AUTHORIZED403Adresse IP non autorisee
USER_AGENT_NOT_AUTHORIZED403User-Agent non autorise

Paiement

CodeHTTPDescription
UNAUTHORIZED_PAYMENT403Paiement non associe a votre partenaire
INVALID_REQUEST400Corps de requete invalide (JSON malformate)
MISSING_PARAMETERS400Parametres requis manquants (taxe_id, province_id, etc.)
MISSING_TELEPHONE400Le champ criteres.telephone est obligatoire
INVALID_TELEPHONE400Telephone invalide : chiffres uniquement, 10 max, prefixe obligatoire parmi 080 081 082 083 084 085 089 090 097 098 099
MISSING_TYPE400criteres.type obligatoire pour taxe_id:36 (peage)
TAXE_PROVINCE_NOT_SUPPORTED400Combinaison taxe_id + province_id non geree
INVALID_PAYMENT_STATUS400Statut incompatible avec l'action
INVALID_PAYMENT_DATA400Donnees du paiement incompletes
PAYMENT_EXPIRED400Paiement expire (+1 heure)
ALREADY_CANCELLED400Paiement deja annule
AMOUNT_TOO_LOW400Montant sous le minimum autorise
AMOUNT_TOO_HIGH400Montant au-dessus du maximum autorise
NO_BENEFICIARIES400Aucun beneficiaire configure pour cette taxe/province
TAXE_NOT_FOUND404Taxe non trouvee ou inactive
TARIFF_NOT_FOUND404Tarif peage non trouve (type ou province invalide)
CONTRIBUABLE_NOT_FOUND404Contribuable non trouve pour ce telephone
NO_UNPAID_INVOICES404Aucune facture impayee pour ce contribuable
PAYMENT_NOT_FOUND404Paiement non trouve avec cette reference

Callback

CodeHTTPDescription
INVALID_SIGNATURE401Signature X-Webhook-Signature HMAC invalide
CALLBACK_STORAGE_ERROR500Erreur stockage du callback en base
CALLBACK_ERROR500Erreur systeme traitement callback

Limites & systeme

CodeHTTPDescription
DAILY_LIMIT_EXCEEDED429Limite journaliere atteinte
MONTHLY_LIMIT_EXCEEDED429Limite mensuelle atteinte
PARTNER_MAINTENANCE503Partenaire en maintenance
SYSTEM_ERROR500Erreur systeme interne

🔒 Securite

JWT HS256Tokens signes HMAC-SHA256, verification stricte de l'algorithme
Timing-SafeComparaison en temps constant des cles API (crypto/subtle)
CSPRNGReferences generees avec crypto/rand
SQL Injection100% requetes parametrees, zero concatenation
Rate LimitingLimitation par IP avec nettoyage auto
IP WhitelistRestriction par IP par partenaire
User-Agent CheckFiltrage optionnel du User-Agent
Headers securisesX-Content-Type-Options, X-Frame-Options, CSP, HSTS
Transactions SQLOperations atomiques avec ROLLBACK auto
Pool de connexionsMax 25 open, 10 idle, recyclage 5 min
Body Limit1 MB max par requete
Webhook HMACPayloads signes HMAC-SHA256
Production : Configurez JWT_SECRET avec une cle aleatoire de 64+ caracteres. Utilisez HTTPS exclusivement. Restreignez les IP autorisees par partenaire.
MPAKO API — Documentation v2.1

MPAKO Paiement API v2.1

API de paiement des taxes et impôts via partenaires bancaires

Base URL : https://votre-domaine.com
Content-Type : application/json
Authentification : JWT Bearer Token

Flux de paiement

1. Login
→
2. Initialiser
→
3. Confirmer
ou
3. Annuler

Le partenaire s'authentifie d'abord, puis initialise un paiement (recherche du contribuable et des factures impayées), et enfin confirme ou annule le paiement.

1. Authentification

POST /api/auth/login

Corps de la requête

{
    "bank_id": "BANK_001",
    "api_key": "votre-cle-api-secrete"
}

Réponse (200)

{
    "status": "success",
    "message": "Authentification réussie",
    "data": {
        "token": "eyJhbGciOi...",
        "expires_at": "2025-01-15 14:30:00",
        "bank_name": "Banque Partenaire",
        "bank_id": "BANK_001",
        "permissions": ["process_payments"],
        "limits": {
            "daily": 10000000,
            "monthly": 100000000,
            "min_amount": 100,
            "max_amount": 5000000
        }
    }
}

2. Initialiser un paiement

POST JWT /api/paiement/initialiser

Recherche le contribuable par téléphone, récupère les factures impayées/en retard, et crée un paiement en attente.

Corps de la requête

{
    "taxe_id": 23,
    "province_id": 1,
    "telephone": "0891234567"
}
ChampTypeRequisDescription
taxe_idintOuiID de la taxe (ex: 23 = Assainissement)
province_idintOuiID de la province
telephonestringOuiNuméro de téléphone (10 chiffres max, prefixe obligatoire : 080, 081, 082, 083, 084, 085, 089, 090, 097, 098, 099)

Réponse (201)

{
    "status": "success",
    "message": "Paiement initialisé avec succès",
    "data": {
        "reference_paiement": "PAY-20250115-ABC123",
        "taxe": {
            "id": 23,
            "nom": "Taxe d'assainissement",
            "description": "Taxe pour l'assainissement urbain"
        },
        "taux": {
            "id": 1,
            "nom": "Taux standard",
            "valeur": 5.00,
            "description": "Taux par défaut"
        },
        "contribuable": {
            "id": 42,
            "reference": "CONTRIB-2025-001",
            "nom": "KABONGO",
            "prenom": "Jean",
            "telephone": "0891234567"
        },
        "factures": [
            {
                "id": 101,
                "reference": "FACT-2025-001",
                "montant": 15000.00,
                "periode_debut": "2025-01-01",
                "periode_fin": "2025-03-31",
                "date_echeance": "2025-03-31",
                "statut": "impayee"
            }
        ],
        "montant_total": 15000.00,
        "province_id": 1,
        "site_id": 5,
        "date_expiration": "2025-01-15 15:30:00"
    }
}
Taux : L'objet taux contient le taux applicable pour la combinaison province/taxe. Il peut être null si aucun taux n'est configuré.
Expiration : Le paiement initialisé expire après 1 heure. Passé ce délai, il sera automatiquement marqué comme annulé.

3. Confirmer un paiement

POST JWT /api/paiement/confirmer

Confirme un paiement initialisé : crée les enregistrements de paiement, la répartition bénéficiaires, et met à jour les factures à "payée".

Corps de la requête

{
    "reference_paiement": "PAY-20250115-ABC123",
    "methode_paiement": "mobile_money"
}
ChampTypeRequisDescription
reference_paiementstringOuiRéférence obtenue lors de l'initialisation
methode_paiementstringOuimobile_money, banque, ou especes

Réponse (200)

{
    "status": "success",
    "message": "Paiement confirmé avec succès",
    "data": {
        "reference_paiement": "PAY-20250115-ABC123",
        "paiement_id": 256,
        "montant_total": 15000.00,
        "methode_paiement": "mobile_money",
        "nombre_factures": 1,
        "taux": {
            "id": 1,
            "nom": "Taux standard",
            "valeur": 5.00,
            "description": "Taux par défaut"
        },
        "repartition": [
            {
                "beneficiaire_id": 1,
                "nom": "Trésor Public",
                "numero_compte": "CD001-00012345",
                "type_part": "pourcentage",
                "valeur_part": 60,
                "montant": 9000.00
            },
            {
                "beneficiaire_id": 2,
                "nom": "Province",
                "numero_compte": "CD002-00054321",
                "type_part": "pourcentage",
                "valeur_part": 40,
                "montant": 6000.00
            }
        ],
        "date_paiement": "2025-01-15 14:35:22"
    }
}

4. Annuler un paiement

POST JWT /api/paiement/annuler

Annule un paiement (en attente ou confirmé). Si confirmé, supprime physiquement les paiements et répartitions créés, remet les factures en statut "impayée", et décrémente les compteurs du partenaire.

Corps de la requête

{
    "reference_paiement": "PAY-20250115-ABC123"
}

Réponse (200)

{
    "status": "success",
    "message": "Paiement annulé avec succès",
    "data": {
        "reference_paiement": "PAY-20250115-ABC123",
        "status": "annule"
    }
}

5. Health Check

GET /health 
{
    "status": "ok",
    "service": "MPAKO Paiement API",
    "version": "2.0.0",
    "database": "ok",
    "uptime": "2025-01-15T14:00:00Z"
}

Codes d'erreur

CodeHTTPDescription
AUTH_FAILED401Identifiants invalides ou compte inactif
ACCOUNT_SUSPENDED403Compte suspendu (la raison est indiquée dans le message)
INVALID_TOKEN401Token JWT invalide ou expiré
INVALID_SESSION401Session invalide, reconnexion requise
INSUFFICIENT_PERMISSIONS403Permissions insuffisantes
IP_NOT_AUTHORIZED403Adresse IP non autorisée
USER_AGENT_NOT_AUTHORIZED403User-Agent non autorisé
UNAUTHORIZED_PAYMENT403Paiement non associé à votre partenaire
INVALID_REQUEST400Corps de requête invalide
MISSING_PARAMETERS400Paramètres requis manquants
TAXE_NOT_SUPPORTED400Taxe non supportée pour le paiement partenaire
INVALID_PAYMENT_STATUS400Statut du paiement incompatible avec l'action
INVALID_PAYMENT_DATA400Données du paiement incomplètes
PAYMENT_EXPIRED400Paiement expiré (plus d'1 heure)
ALREADY_CANCELLED400Paiement déjà annulé
AMOUNT_TOO_LOW400Montant inférieur au minimum autorisé
AMOUNT_TOO_HIGH400Montant supérieur au maximum autorisé
NO_BENEFICIARIES400Aucun bénéficiaire configuré
TAXE_NOT_FOUND404Taxe non trouvée ou inactive
CONTRIBUABLE_NOT_FOUND404Contribuable non trouvé avec ce téléphone
NO_UNPAID_INVOICES404Aucune facture impayée trouvée
PAYMENT_NOT_FOUND404Paiement non trouvé avec cette référence
DAILY_LIMIT_EXCEEDED429Limite journalière de transactions atteinte
MONTHLY_LIMIT_EXCEEDED429Limite mensuelle de transactions atteinte
PARTNER_MAINTENANCE503Partenaire en maintenance
SYSTEM_ERROR500Erreur système interne

6. Webhooks (Callbacks)

Après chaque confirmation ou annulation de paiement, le système envoie automatiquement une notification HTTP POST vers l'URL webhook configurée pour le partenaire.

Configuration

ChampDescription
url_webhook_confirmationURL appelée après confirmation d'un paiement
url_webhook_annulationURL appelée après annulation d'un paiement
secret_webhookClé secrète HMAC-SHA256 pour signer les payloads

Format du webhook

POST {url_webhook}
Content-Type: application/json
X-Webhook-Event: confirmation | annulation
X-Webhook-Timestamp: 2026-04-18T14:35:22Z
X-Webhook-Signature: hmac-sha256-hex-signature

Corps — Webhook de confirmation

{
    "event": "confirmation",
    "timestamp": "2026-04-18T14:35:22Z",
    "data": {
        "reference_paiement": "PAY20260418143500AB1CD",
        "paiement_id": 256,
        "montant_total": 15000.00,
        "methode_paiement": "mobile_money",
        "nombre_factures": 1,
        "repartition": [...],
        "date_paiement": "2026-04-18 14:35:22"
    }
}

Corps — Webhook d'annulation

{
    "event": "annulation",
    "timestamp": "2026-04-18T14:40:10Z",
    "data": {
        "reference_paiement": "PAY20260418143500AB1CD",
        "status": "annule"
    }
}

Vérification de la signature

Si secret_webhook est configuré, le header X-Webhook-Signature contient la signature HMAC-SHA256 (hex) du corps JSON. Vérifiez-la côté partenaire pour vous assurer que l'appel provient bien de MPAKO.

Comportement : Les webhooks sont envoyés de manière asynchrone (non-bloquante). Si l'URL n'est pas configurée ou si l'appel échoue, le paiement reste confirmé/annulé. Le timeout HTTP respecte le timeout_api du partenaire (défaut: 30s).

7. Compteurs & Suspension

Compteurs automatiques

À chaque confirmation de paiement, les compteurs du partenaire sont automatiquement mis à jour :

Ces compteurs permettent un reporting rapide sans recalcul coûteux.

Suspension de compte

Quand un compte partenaire est suspendu (suspendu = 1), l'authentification retourne :

{
    "status": "error",
    "code": "ACCOUNT_SUSPENDED",
    "message": "Compte suspendu: Facture impayée depuis le 01/03/2026"
}

La raison_suspension est incluse dans le message pour informer clairement le partenaire de la cause du blocage (ex: "Ordre de la BCEAO", "Facture impayée", "Non-conformité").

Sécurité

Taxes supportées

taxe_idNomStatut
23Taxe d'assainissementActif
36Taxe de PeageActif

D'autres taxes seront ajoutées progressivement. Chaque taxe peut avoir une logique métier spécifique.

Contact : Pour obtenir vos identifiants partenaire ou signaler un problème, contactez l'équipe technique.