Passerelle de paiement

La passerelle de paiement est le point unique par lequel kuploy-cloud encaisse. Elle réunit sous une même configuration le mobile money (Orange Money, MTN MoMo, KULU), les cartes (Visa, Mastercard, Amex via Stripe), ainsi qu'Apple Pay, Google Pay et Link. Disponible à partir de l'offre Business.

Deux choses, une seule fonctionnalité

La passerelle de paiement recouvre à la fois :

• la façon dont vos organisations vous règlent leur abonnement d'instance. Tous les canaux — paiement par carte Stripe comme mobile money — passent par la même passerelle ;
• un service « Payment Gateway » que vos organisations peuvent ajouter à leurs projets, pour que leurs propres applications encaissent des paiements.

La facturation de plateforme, celle que vous réglez à kuploy.app, reste sur Stripe en direct, sans passer par la passerelle, et n'est pas concernée.

Une seule source de vérité

Depuis cette version, kuploy-cloud ne gère plus directement les clés Stripe. Votre clé secrète Stripe et votre secret de signature de webhook vivent sur un enregistrement de prestataire au sein de votre déploiement epay-gateway, et non sur la page /admin/stripe de kuploy-cloud. Celle-ci subsiste pour les exploitants en transition et sera retirée.

Avant de commencer

• Votre abonnement d'exploitant doit être au moins sur l'offre Business chez kuploy.app. Les offres inférieures ne voient ni les pages d'administration de la passerelle, ni le type de service.
• Choisissez le mode de fonctionnement qui vous convient — géré (sans configuration, hébergé par la plateforme) ou BYO (votre propre déploiement epay-gateway, pour la souveraineté de vos données). Détails ci-dessous.

La documentation dédiée à epay-gateway

Ce qu'est ePay, comment obtenir un compte marchand, quelles devises vos canaux encaissent et ce que vos clients voient au moment de payer sont décrits dans ePay. Sa référence complète, marchand et administration — architecture, greffons de prestataires, API de gestion, moteur d'abonnements, exploitation — se trouve sur docs.epay.kuploy.app (connexion requise). Les deux modes empruntent la même passerelle ; seule change la personne qui l'exploite.

Où va l'argent ?

kuploy-cloud ne détient jamais de fonds. Voir Où atterrit l'argent.

Les deux modes

Vous choisissez le mode géré ou le mode BYO depuis un unique interrupteur, dans Admin → Payment Gateway. Vous pouvez en changer à tout moment.

	Géré	BYO
Qui exploite la passerelle	La plateforme (nous)	Vous
Identifiants	Créés automatiquement à la synchronisation de licence	Vous les saisissez dans l'interface d'administration
Branchement des webhooks	Automatique	Automatique, à l'enregistrement
Souveraineté des données	Infrastructure partagée	Entièrement de votre côté
À qui cela convient	À la plupart des exploitants	Aux secteurs réglementés et aux contraintes de conformité

Le mode géré est celui par défaut pour les nouveaux exploitants Business et au-delà. Le mode BYO est un retrait volontaire, pour quand vos identifiants de paiement doivent résider sur votre propre infrastructure.

Étape 1 — choisir un mode dans l'administration

1. Connectez-vous à votre tableau de bord kuploy-cloud comme administrateur de plateforme.
2. Ouvrez Admin → Payment Gateway.
3. En haut s'affiche une carte Mode. Activez le mode géré, ou laissez-le désactivé pour le mode BYO — un clic dans les deux cas.

Le mode géré

Cliquez sur Enable managed. À la synchronisation de licence suivante — toutes les heures par défaut, ou immédiatement si vous cliquez sur Retry Sync depuis le tableau de bord d'administration — la plateforme crée pour vous un compte marchand sur la passerelle partagée, et votre page d'administration bascule en lecture seule, avec la mention « Connected via managed-mode (license sync) ». Rien d'autre à faire.

Une fois le compte créé, la plateforme envoie au propriétaire du compte une invitation au portail marchand — l'arrière-boutique de la passerelle, où vous consultez vos transactions, votre reversement et le renouvellement de vos clés. Ouvrez-le pour définir un mot de passe, puis servez-vous ensuite du lien Open merchant portal qui apparaît sur cette page. Invitation perdue ou jamais reçue ? Cliquez sur Resend portal invite.

Pour revenir en arrière : Disable managed. Les identifiants gérés sont effacés à la synchronisation suivante ; les services de paiement actifs de vos organisations restent en service pendant un bref délai de grâce, puis sont démontés.

Le mode BYO

Laissez la carte Mode dans son état par défaut, le mode géré désactivé. Le formulaire d'identifiants situé en dessous devient actif. Renseignez :

• Gateway URL — l'URL publique de votre déploiement epay-gateway (par exemple https://pay.votreentreprise.com) ;
• Merchant Code — l'identifiant marchand de l'exploitant, depuis la console d'administration de la passerelle ;
• Admin API Key — une clé d'API créée sur votre passerelle (voir docs.epay.kuploy.app/admin/api-keys) ;
• Merchant Key — le secret HMAC qui signe les webhooks.

Cliquez sur Save Configuration. kuploy-cloud vérifie la connectivité avant d'enregistrer : une URL erronée ou une clé révoquée échouent bruyamment. Tous les secrets sont stockés chiffrés.

L'URL de webhook se branche toute seule

Vous n'avez d'URL de webhook à configurer nulle part. À l'enregistrement en mode BYO, ou à la première création en mode géré, kuploy-cloud indique à votre passerelle où livrer les événements — l'URL se déduit de l'APP_URL de votre instance et se met à jour automatiquement si vous changez de domaine. La page d'administration affiche la valeur en cours, pour vérification.

Étape 2 — les webhooks Stripe (mode BYO uniquement)

En mode géré, cette étape est prise en charge pour vous. En mode BYO, faites pointer le point de réception de webhook de votre tableau de bord Stripe vers votre passerelle, et non vers kuploy-cloud :

https://<hote-de-votre-passerelle>/api/webhooks/stripe/<codeMarchand>

La passerelle vérifie la signature de Stripe, normalise l'événement et le relaie à kuploy-cloud. Voir la documentation d'intégration Stripe d'epay-gateway pour le détail.

Les événements qui parviennent à votre instance

kuploy-cloud traite ces événements, et les mêmes dans les deux modes :

Événement	Ce que fait kuploy-cloud
customer.subscription.created / updated	Crée ou met à jour l'abonnement de l'organisation et synchronise les quotas du cluster.
customer.subscription.deleted	Résilie l'abonnement et bascule sur votre offre par défaut.
invoice.payment_succeeded	Lève le statut d'impayé si l'organisation était en relance.
invoice.payment_failed	Marque l'organisation comme impayée, pour déclencher vos règles de relance.

Des événements à la forme de ceux de Stripe

epay-gateway émet des événements à la forme de ceux de Stripe, de sorte que le même code en aval traite les deux sources. Le champ metadata.externalReference rattache chaque événement à l'organisation concernée, au sein de votre instance kuploy-cloud.

Étape 3 — ce que vos organisations voient au moment de payer

Dès que l'un des deux modes est actif, vos organisations disposent d'un sélecteur Payment method sur /account/billing. La liste dépend des canaux activés sur votre passerelle — cartes via Stripe, mobile money, tout ce que la passerelle prend en charge : les nouveaux prestataires apparaissent donc tout seuls à mesure que votre plateforme en ajoute. Aucun nom de prestataire n'est codé en dur dans l'interface.

Le sélecteur regroupe les canaux selon qui encaisse : les canaux directs de l'exploitant — vos propres contrats de prestataires — au-dessus des canaux de la plateforme, ceux de la plateforme de paiement, les premiers portant une pastille direct. Le regroupement n'apparaît que si vous avez les deux sortes. Les canaux s'affichent sous la marque et le logo de leur prestataire, plutôt que sous le nom interne de la ligne, et une pastille Sandbox signale un canal de test — bon à savoir, car un canal de test et un canal de production du même prestataire sont autrement indiscernables dans la liste.

Un canal incapable d'encaisser la devise facturée s'affiche désactivé, avec la raison (doesn't support GNF), plutôt que d'échouer au niveau de la passerelle ; si aucun ne le peut, votre client voit un message l'invitant à vous contacter.

Les canaux que vous n'avez pas activés n'apparaissent pas du tout, et ce filtrage se fait dans kuploy-cloud, et non sur la passerelle : celle-ci renvoie bien la ligne inactive, et c'est votre instance qui l'écarte avant de composer la liste. Concrètement, désactiver un canal dans l'administration de votre passerelle prend effet immédiatement pour vos clients — sans version de kuploy-cloud à publier, sans redémarrage. Il en va de même d'un canal appartenant à un autre marchand : il n'est jamais divulgué ici, puisqu'il n'est pas payable par votre compte marchand.

Lorsqu'une organisation confirme un changement d'offre, son navigateur rejoint le guichet de paiement de la passerelle — voir Ce que voient vos clients. Le client règle, la passerelle renvoie un événement d'abonnement à votre instance, et l'offre de l'organisation passe à active.

Voir le guide développeur du service composable de passerelle de paiement pour la vue d'ensemble dont disposent les développeurs de vos organisations.

Finance — votre livre de paiements

Admin → Finance est une vue en lecture seule des paiements qui transitent par votre propre compte marchand sur la passerelle — celui qui encaisse les abonnements que vos organisations vous règlent. Elle reprend ce que vous verriez sur la console d'administration de la passerelle, sans quitter kuploy-cloud.

• Overview — les totaux (transactions, payées, échouées, en attente) sur une fenêtre récente, le volume encaissé par devise — les canaux mobile money couvrent le GNF, le XOF, l'USD… — et les prestataires rencontrés.
• Transactions — une liste filtrable et paginée, par prestataire et par statut ; cliquez sur une ligne pour en voir le détail complet.

La fenêtre est un nombre de transactions récentes — jusqu'à 200 — et non une période calendaire.

Le volume encaissé : ce qui vous revient réellement

Qu'un paiement aboutisse sur la passerelle ne signifie pas que l'argent vous parvient. Un marchand peut détenir son propre accord avec un prestataire, auquel cas ses paiements se règlent directement sur son compte, et la passerelle les exclut délibérément du reversement de plateforme — vous les reverser reviendrait à payer deux fois. Le volume encaissé se scinde donc en deux pour chaque devise :

Ligne	Signification
platform	L'argent que vous recevez et reversez. C'est votre chiffre d'affaires.
processed, settled directly to merchant	Passé par une ligne de prestataire appartenant à un marchand. De l'argent bien réel, bien traité sur votre passerelle — mais qui est allé à ce marchand, pas à vous.

Un chiffre qui baisse après une mise à niveau n'est pas une perte de recettes

Les versions antérieures additionnaient toutes les transactions payées, et comptaient donc comme vôtre le volume appartenant aux marchands. Si votre volume encaissé baisse la première fois que vous ouvrez cette page après une mise à niveau, rien n'a changé quant à l'argent — seulement quant à la part qui vous est correctement attribuée. C'est l'ancien chiffre, plus élevé, qui était faux.

La répartition se décide transaction par transaction, selon le propriétaire de la ligne de prestataire enregistré au moment du paiement, et non selon le nom du prestataire : un même canal — om-webpay, par exemple — peut exister à la fois comme ligne de plateforme et comme ligne appartenant à un marchand. La valeur est figée au moment de la transaction : changer plus tard la propriété d'un prestataire ne réécrit jamais l'historique.

Une ligne platform à 0 est normale sur une instance dont le compte marchand n'a aucune ligne de prestataire de plateforme : tous les paiements y passent par des lignes appartenant au marchand. Cela signifie « rien de l'argent de cette fenêtre n'était à vous à reverser », et non que la page est cassée.

Deux limites à bien avoir en tête :

• Elle ne montre que votre propre livre. La passerelle est une plateforme partagée qui héberge les comptes marchands de nombreux exploitants ; les vues Finance sont restreintes à votre code marchand, et vous ne voyez donc jamais que vos propres transactions.
• Elle ne montre pas les livres de vos organisations (niveau 3). Lorsqu'une de vos organisations utilise le service composable de passerelle de paiement, elle dispose de son propre compte marchand : les paiements de ses clients se règlent à elle, pas à vous. Ces transactions constituent son livre privé et sont délibérément absentes de votre vue Finance. Pour aider une organisation sur un paiement précis, passez par la prise d'identité d'administrateur afin de le consulter dans son contexte.

Finance est conditionnée comme le reste des paiements : elle apparaît lorsque votre licence kuploy.app accorde la passerelle de paiement et qu'une connexion à celle-ci est configurée. Remboursements, annulations et toute action d'écriture restent sur la passerelle elle-même — Finance est en lecture seule.

Le service composable « Payment Gateway »

Vos organisations peuvent ajouter un service Payment Gateway à leurs projets, exactement comme elles ajoutent une application, une base de données ou un service Compose. Voir le guide développeur de la passerelle de paiement pour le parcours côté utilisateur.

Chaque organisation qui utilise ce service obtient son propre compte marchand : reversements et rapprochements distincts par organisation, de sorte que le chiffre d'affaires de l'une n'est jamais confondu avec celui d'une autre, ni avec celui de votre propre compte d'abonnements. La plateforme crée et entretient ces comptes marchands pour vous ; vous n'avez rien à faire organisation par organisation.

Les événements de paiement du compte marchand d'une organisation sont livrés à votre instance kuploy-cloud, vérifiés à la signature avec la clé propre à cette organisation, puis relayés vers l'URL de webhook qu'elle a configurée dans les réglages de son service.

Réservé au mode géré

Le service composable par organisation n'existe qu'en mode géré. En mode BYO, vous exploitez un seul compte marchand sur votre propre passerelle, qui ne peut pas émettre de reversements distincts par organisation : le type de service « Payment Gateway » n'est donc pas proposé à vos organisations tant que vous n'êtes pas passé en mode géré. Votre propre facturation, des organisations vers vous, fonctionne dans les deux modes.

État et supervision

kuploy.app comme votre tableau de bord kuploy-cloud affichent une ligne Payment Gateway sur leur page /status :

• kuploy.app/status suit l'instance partagée d'epay-gateway. Si elle passe au rouge, le paiement est dégradé pour tous les exploitants Business et au-delà, pas seulement pour vous.
• Le /status de votre kuploy-cloud sonde la même passerelle avec votre propre connexion marchand. Il n'est au vert que si votre licence accorde la passerelle de paiement et que votre configuration d'administration passe un test de connectivité réel. Les exploitants Free et Pro, et ceux qui n'ont pas terminé leur mise en place, ne voient pas cette ligne du tout.

Lisez les deux ensemble : si kuploy.app indique que la passerelle fonctionne mais que votre propre page la dit en panne, le problème vient de votre configuration — URL erronée, clé révoquée. Commencez par Admin → Payment Gateway → Test Connection.

Changer de mode, renouveler, démonter

• Passer de géré à BYO, ou l'inverse : basculez l'interrupteur de la carte Mode. En passant en BYO, renseignez vos propres identifiants de passerelle. En passant en géré, attendez un cycle de synchronisation, le temps que la plateforme crée votre compte.
• Renouveler des identifiants BYO : saisissez les nouvelles valeurs et enregistrez. Les anciennes sont remplacées d'un bloc.
• Tout désactiver : désactivez le mode géré et cliquez sur Reset dans le formulaire BYO. L'interface de passerelle de paiement disparaît des tableaux de bord de vos organisations. Les comptes marchands existants sont supprimés en douceur, avec un délai de grâce pour les abonnements actifs.

Changer l'URL de votre instance

Un compte marchand géré est épinglé à l'origine avec laquelle il a été enregistré — le schéma et l'hôte sur lesquels répondait votre instance au moment de sa mise en service. Déplacez votre console vers un autre hôte, et les paiements sont rejetés par un 400 qui nomme l'origine attendue par la passerelle, jusqu'à ce que la synchronisation de licence rattrape le changement.

Ce rejet est délibéré. L'autre solution serait de relayer des événements d'argent vers un hôte que votre instance ne sert plus.

• Un chemin différent sur la même origine ne pose aucun problème. Seule l'origine est épinglée.
• Cela se répare à la synchronisation suivante — toutes les heures par défaut, ou tout de suite avec Retry Sync, depuis le tableau de bord d'administration. Faites-le dans le cadre du changement de domaine, et non après : la fenêtre se referme alors sur rien.
• Les comptes marchands BYO ne sont pas épinglés. Un compte que vous avez vous-même intégré depuis la console d'administration de la passerelle n'est pas concerné.

Donc, lorsque vous déplacez la console vers un nouveau domaine, cliquez sur Retry Sync aussitôt après, et faites un paiement d'essai avant de considérer le déménagement comme terminé.

Dépannage

• La carte Mode indique « Managed mode — enabled » mais les identifiants manquent — l'appel de création est en cours, ou a échoué. Laissez-lui une minute ; si cela persiste, votre offre de licence n'accorde peut-être pas la passerelle de paiement. Vérifiez dans Admin → License.
• Je n'ai pas reçu l'invitation au portail marchand (mode géré) — regardez d'abord dans vos indésirables : elle vient de l'expéditeur de la plateforme. Puis cliquez sur Resend portal invite, dans Admin → Payment Gateway. Le bouton renvoie l'invitation, qu'un accès existe déjà ou non.
• « Not configured » en mode BYO — l'enregistrement n'a pas abouti. Revérifiez l'URL de la passerelle et la clé d'administration avec Test Connection.
• Les webhooks arrivent mais les événements semblent ignorés — la vérification de signature est stricte. Voir la documentation des signatures de webhook d'epay-gateway pour la formule HMAC.
• Les paiements renvoient soudain un 400 d'origine incohérente — votre instance répond sur un hôte autre que celui avec lequel son compte marchand géré a été enregistré, en général juste après un changement de domaine. L'erreur nomme l'origine attendue par la passerelle. Cliquez sur Retry Sync, depuis le tableau de bord d'administration ; voir Changer l'URL de votre instance.
• Les organisations ne voient aucun moyen de paiement — vérifiez qu'au moins un prestataire est activé sur votre passerelle. En mode géré, la liste des prestataires est gérée par la plateforme ; en mode BYO, configurez-les dans la console d'administration de votre passerelle.
• Le service « Payment Gateway » ne peut pas être créé — la fonctionnalité dépend de l'indicateur de licence, de la configuration de la passerelle et de l'activation du mode géré, puisque les comptes marchands par organisation n'existent qu'en géré. En mode BYO, ce type de service n'est pas proposé à vos organisations.

Confidentialité et frontières des données

• Mode BYO : les identifiants de paiement et les secrets marchands ne quittent jamais votre instance kuploy-cloud — ils résident chiffrés dans votre propre base. Les fonds se règlent sur les comptes que vous avez ouverts directement auprès de vos prestataires.
• Mode géré : les identifiants sont créés et détenus sur l'infrastructure de la plateforme ; votre kuploy-cloud reçoit et conserve le secret marchand qui vous est propre, ainsi qu'une clé d'administration étroitement limitée, qui ne peut toucher que votre propre compte marchand et rien de plus. Lorsque vos organisations utilisent le service composable, le secret marchand de chacune est également synchronisé et conservé chiffré au repos, limité à cette organisation ; il sert à vérifier ses événements de paiement avant qu'ils ne soient relayés à son application. Un renouvellement de clé côté passerelle se répare de lui-même à la synchronisation suivante. Les fonds se règlent sur les comptes que l'administrateur de la plateforme a déclarés, pour votre compte, auprès des greffons de prestataires de la passerelle partagée.
• La plateforme ne remonte à kuploy.app, lors de la synchronisation de licence, que des indicateurs agrégés : nombre de transactions, volume total — exprimé dans les unités mineures de la devise de référence de la passerelle — nombre de comptes marchands actifs, et liste des prestataires actifs. Aucun identifiant de client, aucun montant par transaction, aucun numéro de téléphone ne remonte.
• Désactiver la passerelle de paiement — par un retour à une offre inférieure, par l'interrupteur, ou par une réinitialisation BYO — interrompt immédiatement cette remontée agrégée.