Les conventions communes
Le contrat API doit décrire les routes, l’authentification, les montants, les statuts, les erreurs, les limites et les notifications. Les fiches de cette bibliothèque constituent une base d’alignement avec l’implémentation existante.
Adresse et environnements
https://api.kelyko.invalid est une adresse d’exemple volontairement non opérationnelle. Remplacer cet hôte uniquement par l’URL d’environnement confirmée par l’équipe. Cette page ne conclut ni à l’existence ni à l’absence d’un sandbox Kelyko.
Objets principaux
Marchands, magasins, demandes de paiement, liens, bénéficiaires, transactions et reversements. Les comptes logiciels organisent le service ; les comptes financiers réels et leur titulaire relèvent du dispositif partenaire.
Une exécution asynchrone
Une requête acceptée peut précéder le résultat final. Distinguer création, traitement en cours, résultat confirmé et issue inconnue. Les statuts pending, success et error sont présents dans la référence fournisseur ; leur correspondance avec les statuts Kelyko doit être explicite.
Solde et disponibilité
Le net dû au marchand est suivi dans quatre compartiments exclusifs : en attente, disponible, réservé et retenu. Un paiement confirmé n’est pas nécessairement immédiatement mobilisable. Un transfert de compartiment ne crée pas une nouvelle recette.
Montants et unités
Le référentiel utilise notamment amountCents. L’unité technique doit être vérifiée : ne pas envoyer 10 000 en supposant qu’il s’agit de 10 000 XOF. Valider les conversions, la devise, les bornes et l’arrondi avec l’API réelle.
Sorties et financement
Avant une demande de reversement, vérifier les droits, le bénéficiaire, les limites et le disponible incluant les frais. Réserver le débit total, constater le résultat et rapprocher la preuve externe. La liquidité réelle ne découle pas du seul affichage du portail.
Couverture
Les moyens activés dépendent du marchand et du dispositif partenaire. La carte et PI-SPI conservent leurs circuits distincts. Une méthode présente dans un catalogue n’est pas nécessairement ouverte en production.