Bubble

Connectez votre application Bubble.io au checkout hébergé lomi.. Le client paie sur une page lomi. sécurisée (redirection ou fenêtre intégrée) ; vos Things Bubble se mettent à jour automatiquement quand le paiement réussit.

Pour qui est ce guide

Créateurs no-code : il vous faut seulement une application Bubble, un compte lomi. et cette page. Les actions serveur choisissent le bon hôte d’API à partir de votre clé ; aucune URL de base à configurer.

Produits associés

Clés API : Tableau de bord → Développeurs → Clés API
Webhooks : Webhooks du tableau de bord — abonnez-vous à PAYMENT_SUCCEEDED et REFUND_COMPLETED
Checkout hébergé : Checkout, où le client paie après redirection
Widget d’intégration : Widget d’intégration, alternative pour un bouton sur une page Bubble

Avant de commencer

Prérequis	Détails
Application Bubble	Tout plan payant qui prend en charge les extensions installées
Version d’API du plugin	4 (dans l’onglet Shared du plugin)
Devise de la boutique	XOF, USD ou EUR
Compte lomi.	En créer un gratuitement
HTTPS	Les applications Bubble sont en HTTPS par défaut (requis pour les webhooks et les URL de retour)

Étape 1, Récupérer vos clés d’API lomi.

Connectez-vous à dashboard.lomi.africa.
Ouvrez Paramètres → Jetons d’accès (ou Développeurs → Clés d’API).
Copiez votre clé secrète de test (lomi_sk_test_…) ; vous la collerez dans Bubble à l’étape 3.
Depuis Développeurs → Webhooks, vous copierez aussi un secret de signature (whsec_…) à l’étape 6.

Gardez le mode Test activé pendant l’intégration. Voir Clés d’API.

Étape 2, Ajouter l’extension lomi. dans Bubble

Dans l’éditeur Bubble, ouvrez l’onglet Plugins → Add plugins.
Installez lomi. (ou, pour une version privée, synchronisez le dépôt lomiafrica/bubble depuis Plugins → Version → Synchronize with GitHub).
Ouvrez l’onglet Shared du plugin et vérifiez que la version d’API est 4.

Étape 3, Saisir vos clés

Ouvrez Plugins → lomi. dans votre application et remplissez les champs par environnement :

Champ	Développement (test)	Production (live)
Clé secrète d’API	`lomi_sk_test_…`	`lomi_sk_live_…`
Secret de webhook	`whsec_…` (endpoint de test)	`whsec_…` (endpoint live)

Les actions serveur choisissent sandbox.api.lomi.africa ou api.lomi.africa selon le préfixe de la clé ; aucun hôte à définir.

Étape 4, Construire le workflow de paiement

Sur votre bouton Payer, exécutez ces actions dans l’ordre :

Create checkout session (serveur) : renseignez amount (XOF en francs entiers ; USD/EUR en unités majeures), currency_code, et vos success_url / cancel_url. Renseignez bubble_thing_type et bubble_thing_id pour que le webhook retrouve le bon Thing ensuite.
Mark checkout redirect (client) : à appeler avant la redirection (l’élément lomi. Pay button le fait pour vous).
Redirect to checkout (client) avec le checkout_url renvoyé à l’étape 1, ou placez l’élément lomi. Pay button et liez son Checkout URL à ce résultat.

Chaque session créée ainsi est marquée integration_source: bubble automatiquement.

Étape 5, Compléter ou abandonner sur la page de succès

Sur votre page success_url :

Lisez session_id depuis l’URL de la page (Get data from page URL).
Exécutez Complete if paid avec ce session_id.
Si paid vaut yes, marquez votre Thing comme payé et affichez la confirmation.
Si paid vaut no, exécutez Abandon checkout. Un retour navigateur après redirection déclenche aussi lomi:checkout-abandon (géré nativement) ; aucune configuration supplémentaire n’est nécessaire pour la récupération de panier.

Étape 6, Connecter les webhooks

Les webhooks confirment le paiement même si le client ferme l’onglet avant de revenir.

Exposez un workflow backend en tant qu’endpoint POST API dans Bubble.
Dans ce workflow, exécutez Verify and parse webhook avec le corps brut et l’en-tête X-Lomi-Signature.
Branchez sur PAYMENT_SUCCEEDED → marquez le Thing payé (de façon idempotente pour qu’un doublon soit sans effet).
Branchez sur REFUND_COMPLETED → marquez le Thing remboursé.
Dans dashboard.lomi.africa → Développeurs → Webhooks, ajoutez l’URL de votre endpoint Bubble, activez PAYMENT_SUCCEEDED et REFUND_COMPLETED, puis recollez le secret de signature dans Plugins → lomi..

Étape 7, Faire un paiement de test

Prévisualisez votre application et cliquez sur le bouton Payer.
Vous êtes envoyé vers lomi. Checkout (sandbox tant que votre clé de test est utilisée).
Payez avec la carte de test 4242 4242 4242 4242 (date future, CVC au choix). Voir Paiements sandbox.
Vérifiez que la page de succès affiche paid = yes et que votre Thing est marqué payé.
Si le Thing reste impayé, vérifiez que le secret de webhook correspond et que PAYMENT_SUCCEEDED est activé sur votre endpoint.

Passer en production

Quand vous êtes prêt pour des paiements réels :

Basculez votre application sur sa version live et utilisez les champs de clé Production.
Collez votre clé secrète live et votre secret de webhook live (créez un endpoint de webhook live dans le tableau de bord pointant vers votre URL Bubble live).
Effectuez un petit paiement réel et vérifiez que le Thing se complète.

Voir aussi Vérifier les paiements.

Remboursements, mode intégré et référence

Remboursements : depuis le tableau de bord ; le webhook REFUND_COMPLETED met à jour votre Thing.

Mode intégré : réglez le lomi. Pay button (ou Open checkout embed) sur embed pour garder le client dans votre application ; écoutez oncomplete ou l’événement window lomi:checkout-complete. Cela réutilise le widget d’intégration.

En-têtes de webhook : X-Lomi-Event, X-Lomi-Signature (HMAC-SHA256 hex du corps brut). Détails : Traiter les webhooks et Webhooks.

Pour les développeurs

GitHub, la construction des assets d’intégration et les détails d’API sont documentés séparément :

Hub e‑commerce, contrat d’API partagé
dépôt bubble, source de l’extension et docs/SETUP.md
Chaîne d’assets d’intégration : construire l’IIFE @lomi./embed, puis lancer scripts/build-assets.mjs (contributeurs uniquement)

Bubble

Sur cette page