Paiement en ligne en Côte d’Ivoire : les enjeux d’intégration API

Encaisser en ligne en Côte d’Ivoire, c’est faire parler une application avec un ou plusieurs prestataires de paiement. Le client paie par monnaie électronique, par carte ou par un autre instrument proposé par le prestataire. L’application n’est en général pas connectée directement à chaque opérateur. Elle appelle une API d’encaissement, puis elle attend un statut. Cette page décrit les enjeux d’intégration de cette API. Elle ne donne pas de part de marché, de volume ni de tarif.

Le franc CFA d’Afrique de l’Ouest (XOF) est la monnaie du pays. Les services de paiement de l’Union économique et monétaire ouest-africaine relèvent du cadre de la BCEAO. Le détail des agréments et des obligations se vérifie auprès de la BCEAO et des contrats de chaque prestataire. Il ne se déduit pas d’un article technique.

Les acteurs, sans les confondre

L’application appartient au marchand ou à la plateforme qui vend. Le prestataire de paiement expose l’API : agrégateur, établissement, ou opérateur de monnaie électronique selon le contrat signé. Le client détient l’instrument, par exemple un compte de monnaie électronique auprès d’un opérateur présent sur le marché ivoirien, ou une carte. La banque ou l’opérateur qui tient le compte du client n’est pas l’application du marchand. L’API se place entre l’application et le prestataire. Elle ne dispense pas du contrat commercial ni de l’agrément lorsque celui-ci est requis.

Plusieurs instruments coexistent. Les API qui les encaissent ne sont pas interchangeables. Une demande de débit sur monnaie électronique, une demande de paiement par carte et un virement vers un bénéficiaire n’ont ni les mêmes champs, ni les mêmes délais, ni les mêmes statuts. Les regrouper derrière une façade unique est possible. Cette façade doit conserver le type d’opération. L’effacer oblige à deviner, au moment du rapprochement, ce qui a été demandé.

La demande et l’appel retour

Une demande d’encaissement part de l’application vers l’API du prestataire. La réponse immédiate accuse souvent réception. Elle ne dit pas toujours que l’argent est passé. Le client confirme sur son téléphone, sa banque ou une page hébergée par le prestataire. Le résultat définitif arrive plus tard, par un appel retour vers une URL de l’application, ou par une consultation de statut que l’application doit lancer elle-même. Les deux mécanismes se prévoient. Un prestataire peut envoyer l’appel retour en retard, le répéter, ou ne pas l’envoyer.

L’URL d’appel retour est un endpoint d’API à part entière. Elle authentifie l’émetteur, en général par une signature ou un secret prévu au contrat, elle répond vite, et elle ne fait pas le traitement long dans la requête HTTP. Le traitement, mise à jour de la commande et écriture comptable, suit dans une file. Répondre lentement conduit le prestataire à réessayer, donc à livrer le même événement plusieurs fois.

Idempotence et statut inconnu

Chaque demande porte un identifiant choisi par l’application, unique pour une tentative d’encaissement donnée. Le prestataire le renvoie dans les statuts et les appels retour. Si le délai est dépassé et que l’application ne sait pas si la demande a été acceptée, elle interroge le statut avec cet identifiant. Elle ne relance pas une nouvelle demande avec un nouvel identifiant : ce serait un second encaissement possible. Elle ne relance pas non plus la même demande en aveugle si le contrat ne garantit pas l’idempotence.

Trois états suffisent à concevoir l’application : accepté, refusé, inconnu. L’inconnu n’est pas un échec. C’est l’absence de réponse fiable. La commande reste en attente, le client est informé que la confirmation n’est pas arrivée, et un traitement reprend le dossier jusqu’à un statut ferme ou jusqu’à la règle métier de clôture écrite à l’avance. Inventer un quatrième état « probablement payé » dans l’interface crée des livraisons sans encaissement confirmé.

Rapprochement

Le rapprochement compare trois listes : les demandes émises par l’application, les statuts reçus, et le relevé ou le fichier que le prestataire fournit pour les opérations réglées. Ces listes ne coïncident pas à la minute. Un paiement accepté le soir peut apparaître sur le relevé le lendemain. Une opération acceptée puis annulée selon les règles du prestataire doit se voir des deux côtés. Le journal technique conserve l’identifiant, le montant, la devise XOF, l’horodatage, le type d’opération et le statut, pas le secret d’API et pas l’intégralité des données du client.

Les écarts se traitent par une file de cas, pas par une correction manuelle dans la base sans trace. Un montant différent entre la demande et le statut est une alerte, pas un arrondi silencieux. Les frais, lorsqu’ils existent, sont ceux du contrat. Les coder en dur d’après une brochure produit des écarts de rapprochement dès que le contrat change.

Secrets, environnements et temps de réponse

Le prestataire fournit en général un environnement de test et un environnement réel, avec des clés différentes. Les URL et les clés de test ne se déploient pas en production par une variable oubliée. Les secrets restent dans un coffre, distincts par environnement. Les journaux d’application ne les impriment pas, y compris lors d’une erreur de signature : on journalise l’échec de vérification, pas le secret comparé.

Les délais se fixent des deux côtés. L’application abandonne une connexion trop longue vers le prestataire, puis elle passe la demande en statut inconnu et elle interroge. Le endpoint d’appel retour répond dans un délai court. Les pages de paiement que le client voit, lorsqu’elles sont hébergées par le prestataire, ont leurs propres expirations. Les recopier dans un texte d’interface comme si elles étaient garanties produit des consignes fausses.

Place d’une passerelle API

Une passerelle devant l’application peut authentifier les appelants internes, limiter le débit et journaliser les accès à l’API d’encaissement que l’on expose à ses propres services. Elle ne signe pas à la place du prestataire, et elle ne transforme pas un statut inconnu en succès. Si plusieurs canaux, site, caisse, application mobile, appellent le même service d’encaissement, la passerelle est un point de contrôle utile. Le choix du produit se fait selon les critères du comparatif d’API management, pas selon le secteur du paiement.

Les données de carte, lorsqu’elles transitent par l’application, relèvent de contraintes propres, souvent évitées en laissant la saisie sur la page du prestataire. Cet article ne décrit pas une mise en conformité. Il signale que le chemin des données de carte se décide dans le contrat et dans l’architecture, avant d’écrire le client HTTP.

EDO Pay

Technocify conçoit EDO Pay, présenté sur la page projet comme une plateforme de paiement digitale. La fiche EDO Pay s’arrête à ce périmètre. Elle ne publie pas de liste d’opérateurs raccordés, ni de volumes, ni de noms de clients. Cet article n’en ajoute pas. Les enjeux décrits ici, identifiant de demande, appel retour, statut inconnu et rapprochement, sont ceux que l’on traite lorsqu’on construit une telle plateforme, quel que soit le prestataire retenu par contrat.

Ce que Technocify peut prendre en charge

L’audit lit le contrat d’API disponible : opérations, signatures, environnements, délais, fichiers de relevé. La conception fixe les états de la demande, l’idempotence et le contenu du journal. La mise en œuvre raccorde l’environnement de test, puis le réel, avec une bascule explicite des secrets. Le run surveille les statuts inconnus qui s’accumulent et les écarts de rapprochement.

Les équipes Technocify s’appuient sur une pratique de l’intégration et des API depuis 2009. Nos consultants sont certifiés WSO2 API Manager Practitioner V4 (2023), WSO2 API Manager Developer V3 (2021), MuleSoft Developer V4 (2022), Workato Automation Pro I, II, III (2025, valides jusqu’en 2027) et ITIL V4 (2020). Ces certifications ne sont pas un agrément de paiement. Voir À propos. Les pages plateformes API et cloud et interopérabilité décrivent le cadre d’ingénierie.