Intégrer le paiement de factures dans votre application : le guide de l'intégrateur

En bref

• Le paiement de factures est l'un des services les plus fréquents d'une application financière : électricité, eau, télécom, services publics et autres créances.
• L'API de Chari Money couvre le parcours de bout en bout : créanciers, créances, formulaire dynamique, impayés, aperçu, confirmation, statut, reçu et webhooks.
• Trois règles d'or : construire le formulaire à partir de la réponse de l'API, ne jamais présenter un échec avant la notification finale, et toujours afficher la référence de règlement sur le reçu.
• Pour un commerçant qui veut simplement régler ses propres factures, le parcours est déjà prêt dans le portail d'une plateforme de paiement : pas besoin d'intégration.

---

Pourquoi intégrer le paiement de factures

Payer une facture revient chaque mois. Pour une application, c'est une raison d'être ouverte régulièrement, bien plus qu'un paiement ponctuel. C'est aussi un service attendu dans un wallet : un solde qu'on ne peut pas utiliser pour ses factures reste un solde à moitié utile.

Notre article sur le paiement de factures en ligne au Maroc présente le service côté utilisateur. Ici, nous nous plaçons du côté de l'équipe technique qui l'intègre dans une application, une super-app ou un réseau d'agents, sous sa propre marque, avec le module de services à valeur ajoutée de Chari Money.

Une précision avant de commencer : si vous êtes un commerçant qui veut seulement régler ses propres factures depuis l'argent de ses ventes, vous n'avez rien à intégrer. ChariPay, la plateforme de paiement opérée par Chari Money, permet de payer ses factures depuis son compte de paiement directement dans son portail.

Les prérequis

Avant le premier appel, trois éléments doivent être réunis :

1. Une clé API de sandbox valide, envoyée dans l'en-tête Chari-Api-Key, avec un identifiant de requête unique dans C-Request-Id pour le traçage.
2. Le module de paiement de factures activé pour votre compte partenaire par l'équipe Chari Money. Sans activation, les appels échouent.
3. Un utilisateur final existant, identifié par son numéro de téléphone au format international, et du float de test pour les opérations débitrices.

Le guide pas à pas, avec les requêtes et les réponses d'exemple, figure dans la documentation de l'API. Cet article en explique la logique et les pièges.

Le parcours en six étapes

1. Lister les créanciers

L'API renvoie les créanciers actifs auxquels votre compte a accès, filtrés selon votre contrat. Chaque créancier porte un code à quatre chiffres que vous réutiliserez. La liste étant relativement stable, un cache de quelques heures côté partenaire est acceptable.

2. Lister les créances

Un créancier peut exposer plusieurs créances, chacune correspondant à un type de service : facture, frais de raccordement, taxe... Le code de créance tient toujours sur deux positions.

3. Construire le formulaire d'identification

C'est l'étape la plus souvent mal faite. Pour chaque couple créancier et créance, l'API renvoie la liste des champs à afficher : libellé, type, format, tailles minimale et maximale, caractère obligatoire ou facultatif. Votre écran doit être construit à partir de cette réponse, jamais codé en dur, sinon il cassera à l'arrivée d'un nouveau créancier. Les champs de type « libellé » sont du texte d'aide statique : affichez-les, mais ne les renvoyez jamais dans la requête suivante.

4. Consulter les impayés

Vous envoyez les valeurs saisies par l'utilisateur. Attention au nom de la propriété attendue dans la requête, qui diffère de celui des réponses : le guide de l'API le signale explicitement. Cet appel ouvre la transaction et renvoie une référence à 12 chiffres à conserver pour la confirmation ; l'association reste valable sept jours calendaires.

La réponse liste les articles impayés : créance, frais, éléments obligatoires, timbre. Certains paramètres techniques à libellé vide ne doivent jamais être montrés au client.

5. Prévisualiser, puis confirmer

L'utilisateur choisit de tout régler ou de sélectionner certains articles : le paiement partiel est supporté. Vous pouvez d'abord valider le corps de la requête avec l'appel d'aperçu, qui accepte exactement le même corps que la confirmation sans exécuter le paiement. Puis vous confirmez.

Deux réponses demandent une attention particulière. Un code indiquant une transaction déjà traitée doit être traité comme un succès : affichez le reçu. Et certains codes renvoyés par le canal digital ne sont pas des échecs définitifs : la transaction reste autorisée et sa résolution finale arrive par webhook.

6. Suivre la transaction et délivrer le reçu

Le statut d'une transaction se lit à partir de sa référence ; il renvoie aussi l'identifiant d'opération Chari Money, qui permet de télécharger le fichier du reçu. Le reçu doit mentionner la référence de règlement renvoyée à la confirmation. L'historique paginé des paiements de l'utilisateur est également disponible.

Écouter les webhooks

Le paiement de factures est en partie asynchrone. Le module émet quatre événements : paiement confirmé, annulé, remboursé ou échoué. Les notifications arrivent en POST avec l'en-tête X-Api-Key, la clé secrète que vous fournissez à Chari Money.

Répondez 200 OK en moins de cinq secondes. Tout code non 2xx déclenche une nouvelle tentative : après 1 minute, 5 minutes, 30 minutes, 60 minutes, puis toutes les six heures jusqu'à 72 heures au total. Votre traitement doit donc être idempotent : la même notification peut arriver plus d'une fois.

Les erreurs à prévoir

• 401 : la clé d'API n'est pas autorisée ; vérifiez l'en-tête et l'environnement, les clés étant propres à chacun.
• Paramètre manquant : un champ requis manque, numéro de téléphone, créancier, créance ou tableau des valeurs saisies.
• Aucune facture à payer : la consultation ne trouve pas d'impayé, ce qui n'est pas une erreur technique ; prévoyez un message clair.
• Champ requis absent : un champ obligatoire du formulaire dynamique n'a pas été envoyé.

Construire l'expérience utilisateur

Une bonne intégration se juge à l'écran. Affichez le nom du client renvoyé avec les impayés pour qu'il confirme qu'il s'agit bien de son contrat. Montrez le détail des articles et le total avant la confirmation. Après le paiement, affichez immédiatement le reçu avec la référence de règlement, et gardez-le accessible dans l'historique.

Le paiement de factures se combine naturellement avec les recharges télécom et les vouchers, qui suivent le même modèle d'aperçu puis de confirmation. Pour un projet qui démarre, notre guide pour lancer une fintech au Maroc aide à choisir l'ordre des services.

Côté commerçant : encaisser plutôt que payer

Une application qui permet à ses utilisateurs de payer leurs factures ne doit pas être confondue avec un commerçant qui veut se faire payer les siennes. Une école, un cabinet ou une boutique qui facture ses clients a besoin de l'inverse : envoyer une demande de paiement. Pour cela, ChariPay propose des liens de paiement, à partager par lien, QR code, e-mail ou WhatsApp, sans intégration.

Prochaine étape

Pour activer le module de paiement de factures en sandbox, consultez la documentation de l'API partenaire et demandez votre accès depuis la page de la documentation. Pour un lancement en production, l'ajout du paiement de factures se prépare comme un cas d'usage à part entière, avec l'équipe Chari Money.