Intégrer Tchin dans Bubble (sans code)

Ce guide vous montre, pas à pas, comment encaisser des paiements Mobile Money dans une application Bubble.io sans écrire une seule ligne de code. Le principe est le même que pour n'importe quelle passerelle : votre app appelle l'API Tchin pour créer un paiement, redirige le client vers la page de paiement hébergée, puis reçoit la confirmation par webhook. La même méthode s'applique à la plupart des outils no‑code disposant d'un connecteur HTTP (Adalo, Glide, WeWeb, FlutterFlow…), les libellés d'options changent simplement de nom.

💡 Vous n'avez besoin d'aucun serveur : le plugin natif API Connector de Bubble suffit pour appeler l'API, et un Backend Workflow Bubble sert de récepteur de webhook.

Vue d'ensemble

Vous allez configurer quatre choses dans Bubble :

1. Le plugin API Connector avec vos deux clés d'authentification.
2. Un appel « Créer un paiement » (POST /payments) qui renvoie une payment_url.
3. Un workflow de bouton « Payer » qui appelle l'API puis redirige le client (« Go to an external website »).
4. Un Backend Workflow qui reçoit le webhook de confirmation et met votre commande à jour.

Prérequis

• Un compte Tchin vérifié et une application créée dans votre tableau de bord (menu API), afin d'obtenir votre clé publique (tchin_pk_…) et votre clé privée (tchin_sk_…).
• Une application Bubble sur un plan permettant les Backend Workflows (nécessaire pour recevoir le webhook).

🔒 Ne collez jamais votre clé privée dans un élément visible de la page (texte, champ, workflow front-end). Elle ne doit vivre que dans les en‑têtes du plugin API Connector, dont les appels partent côté serveur de Bubble.

Étape 1 — Configurer l'authentification (API Connector)

L'API Tchin s'authentifie par deux en‑têtes HTTP présents sur chaque requête : TCHIN-PUBLIC-KEY et TCHIN-PRIVATE-KEY. Dans Bubble, on les déclare une seule fois comme en‑têtes partagés (shared headers) du connecteur.

1. Ouvrez l'onglet Plugins de votre app, puis Add plugins et installez API Connector (édité par Bubble).
2. Cliquez sur Add another API et nommez cette API Tchin.
3. Dans Authentication, choisissez « Private key in header ». Ce mode indique à Bubble que les clés sont secrètes et doivent être envoyées uniquement depuis le serveur, jamais exposées au navigateur.
4. Renseignez les en‑têtes partagés ci‑dessous. Ils s'appliqueront automatiquement à tous les appels de cette API.

# Onglet Plugins → API Connector → Add another API
# Nom de l'API : Tchin
# Authentication : Private key in header
# Ajoutez ces 3 « Shared headers » (partagés par tous les appels) :

Key                    Value
--------------------   ------------------------------
TCHIN-PUBLIC-KEY       tchin_pk_xxxxxxxx
TCHIN-PRIVATE-KEY      tchin_sk_xxxxxxxx
Content-Type           application/json

⚠️ Si les clés sont absentes ou erronées, l'API répond 401 Unauthorized. Si votre compte est suspendu, elle répond 403 Forbidden. Vérifiez d'abord vos deux en‑têtes en cas d'erreur d'authentification.

Étape 2 — Créer l'appel « Créer un paiement »

Toujours dans l'API Tchin du connecteur, cliquez sur Add another call et configurez‑le comme suit. Cet appel crée un paiement et vous renvoie l'URL de la page de paiement hébergée.

# Nouvel appel dans l'API « Tchin »
Name         : Créer un paiement
Use as        : Action        (déclenché dans un workflow)
Data type     : JSON
Method        : POST
URL           : https://tchin.tech/api/v1/payments

# Onglet « Body » — Body type : JSON
# Cochez « Include headers in the detected data » n'est pas requis.

Sélectionnez Body type : JSON et collez le corps ci‑dessous. Les montants sont des entiers en FCFA (XOF ; XAF au Cameroun), sans décimales, avec un minimum de 100.

{
  "amount": 5000,
  "description": "Commande #1234",
  "env": "live",
  "return_url": "https://monapp.com/merci",
  "callback_url": "https://monapp.com/version-live/api/1.1/wf/tchin_webhook"
}

Rendre le montant dynamique

Pour que le montant vienne de vos données (panier, commande…), remplacez les valeurs fixes par des paramètres dynamiques Bubble en les entourant de chevrons < >. Bubble crée alors un champ à remplir dans le workflow.

{
  "amount": <amount>,
  "description": "<description>",
  "env": "live",
  "return_url": "https://monapp.com/merci",
  "callback_url": "https://monapp.com/version-live/api/1.1/wf/tchin_webhook"
}

Décochez la case « Private » à côté de amount et description pour pouvoir les renseigner dans vos workflows. Laissez « Private » coché sur vos clés d'en‑tête.

Initialiser l'appel

Cliquez sur Initialize call. Bubble exécute une requête de test et lit la structure de la réponse. Vous devez obtenir un objet contenant payment_url :

{
  "success": true,
  "token": "a1b2c3d4e5f6",
  "payment_url": "https://tchin.tech/pay/a1b2c3d4e5f6",
  "env": "live"
}

✅ Une fois l'appel initialisé, Bubble connaît les champs token, payment_url et env. Vous pourrez y faire référence dans vos workflows via « Result of step 1's… ».

Étape 3 — Le workflow du bouton « Payer »

Sur la page où le client valide sa commande, ajoutez un bouton Payer et créez son workflow (Start/Edit workflow → When Button Payer is clicked).

1. Étape 1 — action Plugins → Tchin → Créer un paiement. Renseignez amount (par exemple Current cell's Commande's total) et description. Fournissez votre callback_url (voir étape 4).
2. Étape 2 — action Navigation → Go to an external website. Dans le champ Destination, insérez la valeur dynamique Result of step 1's payment_url.

Au clic, Bubble crée le paiement puis redirige le navigateur du client vers la page de paiement Tchin. Le client y choisit son pays et son opérateur, saisit son numéro et paie. Vous n'avez rien à coder côté paiement.

💡 Astuce : à l'étape 1, ajoutez aussi une action « Create a new thing » (ou « Make changes to a thing ») pour enregistrer le token (Result of step 1's token) avec votre commande. Vous pourrez ainsi rapprocher le webhook de la bonne commande.

Le retour du client

Après le paiement (réussi ou annulé), Tchin renvoie le client sur votre return_url (ou sur la page d'origine si vous n'en avez pas fourni), en ajoutant deux paramètres à l'URL :

Dans Bubble, vous pouvez lire ces paramètres via Get data from page URL → path/parameter pour afficher un message « Merci » ou « Paiement annulé ».

⚠️ Le retour navigateur sert uniquement à l'affichage : le client peut fermer son onglet avant d'y revenir. Pour valider et livrer une commande, fiez‑vous toujours au webhook (étape 4).

Étape 4 — Recevoir le webhook (Backend Workflow)

Le webhook est la source de vérité : c'est la notification serveur‑à‑serveur qui confirme réellement le paiement. Dans Bubble, on le reçoit avec un Backend Workflow (API Workflow).

1. Allez dans Settings → API et cochez « Enable Workflow API and backend workflows ».
2. Ouvrez l'éditeur Backend workflows (menu déroulant des pages, en haut à gauche).
3. Créez un nouveau API Workflow nommé tchin_webhook.
4. Dans ses réglages, cochez « Detect request data » et « This workflow can be run without authentication » (Tchin appelle ce point d'entrée sans session Bubble).
5. Content type : choisissez Detect data. Tchin envoie du application/x-www-form-urlencoded.

Voici les données que Tchin envoie à votre workflow. Utilisez le bouton « Detect data » de Bubble en déclenchant un paiement de test : Bubble apprend automatiquement la liste des champs.

# Tchin envoie un POST (application/x-www-form-urlencoded).
# Toutes les valeurs sont regroupées sous la clé "data".
# Bubble les détecte automatiquement (bouton « Detect data »).

data[status]          = completed        # ou failed / cancelled / pending
data[reference]       = a1b2c3d4e5f6     # = le token du paiement
data[hash]            = 7f3b…            # SHA-512 de VOTRE clé privée
data[response_code]   = 00               # 00 = succès, sinon 1001
data[amount]          = 5000
data[fee]             = 250              # commission Tchin
data[net]             = 4750             # montant crédité (amount - fee)
data[currency]        = XOF
data[country]         = SN
data[method]          = wave-senegal
data[method_name]     = Wave
data[mode]            = live             # ou test
data[customer][name]  = Awa Diop
data[customer][email] = awa@exemple.com
data[customer][phone] = 771234567

Les actions du workflow

1. Vérifier l'origine — le champ data hash est le SHA‑512 de votre clé privée. Idéalement, recalculez ce hash et comparez‑le pour n'accepter que les vraies notifications Tchin. Bubble ne calcule pas de SHA‑512 nativement : utilisez un plugin de hachage, ou un petit API Workflow serveur, ou renforcez la sécurité par un jeton secret dans l'URL du webhook.
2. Retrouver la commande — faites un Search for Commandes dont le champ token = data reference.
3. Mettre à jour — si data status = completed et que la commande n'est pas déjà payée, marquez‑la payée et déclenchez la livraison / la confirmation.

Enfin, l'URL publique de ce Backend Workflow est de la forme :

https://votre-app.com/version-live/api/1.1/wf/tchin_webhook

C'est exactement cette URL que vous placez dans le champ callback_url de l'étape 2. En phase de test, utilisez la variante /version-test/.

🔁 Idempotence : un même paiement peut, rarement, déclencher plusieurs appels. Avant d'agir, vérifiez que la commande n'est pas déjà marquée payée, pour ne pas livrer deux fois.

Étape 5 (optionnel) — Vérifier un paiement à la demande

En complément du webhook, vous pouvez interroger l'état d'un paiement depuis Bubble avec son token, par exemple pour rafraîchir un écran de suivi.

# Appel optionnel pour vérifier un paiement depuis Bubble
Name    : Statut d'un paiement
Use as   : Action  (ou Data selon votre besoin)
Method   : GET
URL      : https://tchin.tech/api/v1/payments/<token>/status

# Réponse : { "success": true, "status": "completed", "amount": 5000, ... }
# status = pending | completed | failed | cancelled

Passer en production

Commencez toujours en mode test avant d'encaisser de vrais paiements :

• Mettez "env": "test" dans le corps de l'appel et payez avec le compte de test de votre tableau de bord (menu API → « Compte test »). Aucun argent réel n'est déplacé et votre solde n'est pas crédité.
• Tchin envoie tout de même un webhook de test (mode: test), ce qui vous permet de valider tout le parcours de bout en bout.
• Quand tout fonctionne, passez "env": "live" et pointez callback_url vers l'URL /version-live/ de votre Backend Workflow.

Récapitulatif

Configurez l'API Connector avec vos deux clés en « Private key in header » → créez l'appel Créer un paiement (POST /payments) → au clic « Payer », appelez l'API puis Go to an external website avec la payment_url → recevez la confirmation dans un Backend Workflow et validez la commande via le webhook. Pour les détails de l'API, consultez Encaissement et Webhooks.