Ce guide est écrit pour les personnes qui construisent leur application avec un outil d'IA (Lovable, Claude, Bolt, v0, GitHub Copilot Workspaces, etc.) et qui veulent accepter des paiements MonCash via MonCashConnect. Aucune connaissance de programmation préalable n'est requise — mais une seule erreur de sécurité peut vider votre compte. Lisez la section suivante en entier avant tout.

Ce que vous obtiendrez

• Une page de checkout MonCash branchée à votre application Lovable ou Claude
• Un webhook qui marque automatiquement vos commandes comme "payées"
• Une configuration sécurisée — vos clés ne sont jamais exposées ni dans le code public, ni dans l'historique de l'IA, ni dans votre dépôt Git

Prérequis

• Un compte MonCashConnect actif (créez-en un sur /auth)
• Un projet Lovable, Claude (Claude.ai), Bolt ou équivalent
• Un domaine où votre application est déployée (ou un tunnel ngrok pour les tests locaux — voir le guide webhook-testing)

La règle d'or

Ne tapez jamais votre clé secrète ou votre secret webhook dans une fenêtre de chat d'IA (Lovable, Claude, ChatGPT, Bolt, etc.).

Pourquoi ? Le contenu de votre chat avec l'IA est :

• Stocké côté serveur (Anthropic, Lovable, OpenAI, etc.) — pas chiffré pour vous
• Potentiellement visible par les ingénieurs support de la plateforme
• Parfois indexé par des outils internes d'analytics ou de fine-tuning
• Persisté dans l'historique du projet — accessible à tout collaborateur invité
• Sauvegardé dans des logs qui peuvent être exfiltrés en cas de fuite

Une clé qui apparaît une seule fois dans un chat doit être considérée comme compromise pour toujours. Révoquez-la immédiatement et générez-en une nouvelle.

Ce qui peut être public (sans danger)

Ce qui est secret (à ne JAMAIS coller dans un chat IA)

Toute la configuration vit sur la page Developer de votre tableau de bord. Voici exactement où cliquer :

Naviguer jusqu'à la page Developer

1. Allez sur moncashconnect.com et connectez-vous (lien Se connecter en haut à droite).
2. Une fois connecté, ouvrez le menu Tableau de bord.
3. Dans la barre latérale, cliquez sur Developer (icône clé). L'URL directe est moncashconnect.com/developer.
4. Vous voyez deux onglets : « Clés API » et « Projets ».

Créer un projet

Pour les intégrations sérieuses (avec un site déployé et un webhook), créez un Projet plutôt qu'une simple clé API. Un Projet regroupe :

1. Sur /developer, cliquez l'onglet « Projets ».
2. Cliquez le bouton « Nouveau projet » (en haut à droite de la liste).
3. Remplissez :
   • Nom : le nom de votre boutique / app.
   • URL du webhook : https://votre-site.com/api/moncash-webhook (vous configurerez cette route à l'étape 4 — laissez vide si vous ne savez pas encore).
   • Domaines autorisés : votre-site.com, www.votre-site.com (séparés par virgule).
4. Cliquez « Créer ».
5. UNE FOIS UNIQUEMENT, MonCashConnect vous affiche :
   • Votre clé secrète complète sk_proj_xxxxxxxxxxxxxxxx
   • Votre secret webhook complet whsec_xxxxxxxxxxxxxxxx
6. Cliquez les boutons « Copier » à côté de chaque valeur et collez-les dans un gestionnaire de mots de passe (1Password, Bitwarden, le trousseau macOS, etc.) — pas dans un fichier texte sur votre bureau, et surtout pas dans le chat avec l'IA.

Maintenant vous avez vos deux secrets dans votre gestionnaire de mots de passe. Il faut les rendre accessibles à votre code sans que la valeur transite par l'IA. La technique standard : les variables d'environnement.

Si vous utilisez Lovable

1. Dans votre projet Lovable, cliquez l'icône ⚙️ Paramètres (ou l'icône engrenage selon votre version).
2. Cherchez la section « Environment Variables » ou « Secrets ».
3. Cliquez « Ajouter une variable ».
4. Créez ces deux variables (une par une) :
   envCopier

   MCC_SECRET_KEY=sk_proj_VOTRE_CLE_SECRETE_ICI
   MCC_WEBHOOK_SECRET=whsec_VOTRE_SECRET_WEBHOOK_ICI

5. Sauvegardez. Lovable redéploie automatiquement. Les valeurs sont chiffrées au repos et injectées dans process.env au runtime.

Si vous utilisez Claude pour générer du code que vous hébergez ailleurs

Claude génère du code, mais c'est vous qui le déployez (Vercel, Netlify, Cloudflare, etc.). Ne mettez jamais la clé en dur dans le code généré. À la place, ajoutez les mêmes deux variables dans le panneau d'environnement de votre hôte :

# .gitignore
.env
.env.local
.env.*.local

Voici un prompt prêt à copier-coller dans Lovable. Notez que la clé n'apparaît nulle part — on dit juste à Lovable d'utiliser la variable d'environnement.

Prompt — Checkout (paiement)

Ajoute une intégration de paiement MonCash via MonCashConnect.

**Côté serveur (Edge Function ou API Route) :**
- Crée une route POST `/api/moncash/create` qui reçoit { amount, orderId, returnUrl }.
- Appelle `https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-create` avec :
  - Header: `Authorization: Bearer ${process.env.MCC_SECRET_KEY}`
  - Body JSON: { amount, referenceId: orderId, returnUrl }
- Si la réponse est 201, renvoie au client le champ `paymentUrl`.
- Si erreur, renvoie l'erreur structurée (champ `error` + `code`).
- **N'expose JAMAIS `MCC_SECRET_KEY` côté client. Lis-la uniquement depuis process.env.**

**Côté client :**
- Sur le bouton "Payer", fais un POST à `/api/moncash/create` avec
  { amount: total_en_HTG_entier, orderId: id_de_la_commande, returnUrl: window.location.origin + "/merci" }.
- À la réception de `paymentUrl`, redirige le navigateur avec window.location.href = paymentUrl.

**Stocke la commande en BDD avec status="awaiting_payment" AVANT la redirection.**
La confirmation finale viendra par webhook (je l'ajouterai ensuite).

**Référence officielle :** docs sur https://moncashconnect.com/docs (section "Créer un paiement").

Prompt — Webhook (confirmation)

Lancez ce prompt après que le checkout fonctionne, pour ajouter la confirmation automatique :

Ajoute un webhook qui marque une commande comme payée quand MonCashConnect
confirme le paiement.

- Crée une route POST `/api/moncash/webhook` qui reçoit un POST de MCC.
- **Lis le corps brut (raw body) AVANT toute désérialisation JSON.**
- Récupère ces headers :
  - `x-mcc-signature` (format: "sha256=<hex>")
  - `x-mcc-timestamp` (epoch en secondes)
- Vérifie HMAC-SHA256 du corps brut avec process.env.MCC_WEBHOOK_SECRET ;
  rejette en 401 si signature invalide.
- Rejette en 401 si abs(now - timestamp) > 300 secondes.
- Sinon parse le JSON :
  - { event: "payment.completed", reference, amount, status, completedAt }
  - { event: "payment.failed",    reference, amount, status, completedAt }
- Trouve la commande par `reference === orderId` et mets à jour son status.
- **Réponds 200 toujours, même si la commande a déjà été marquée.**
  Les retries de MCC doivent être idempotents.

**N'expose pas process.env.MCC_WEBHOOK_SECRET côté client.**

**Référence officielle :** https://moncashconnect.com/docs (section "Webhooks").

Si vous utilisez Claude (claude.ai) pour générer du code que vous collez ensuite dans votre projet, voici le prompt à utiliser. Même principe : la clé n'apparaît jamais dans le chat.

Prompt — Génère le code (Next.js exemple)

J'ai un projet Next.js App Router. Génère le code complet pour accepter
des paiements MonCash via l'API MonCashConnect.

**Contraintes de sécurité (impératives) :**
- Mes secrets sont dans process.env.MCC_SECRET_KEY et process.env.MCC_WEBHOOK_SECRET.
- Ne mets JAMAIS de valeur en dur. Ne demande pas la valeur de mes clés.
- Ne crée pas de variable NEXT_PUBLIC_* pour ces clés.

**Ce que je veux :**

1. `app/api/moncash/create/route.ts` :
   - POST { amount: number, orderId: string, returnUrl: string }
   - Appelle https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-create avec Bearer + body JSON.
   - Retourne { paymentUrl } ou { error, code }.

2. `app/api/moncash/webhook/route.ts` :
   - Force `export const runtime = "nodejs"` (pas Edge).
   - Lis le corps avec await req.text() (jamais req.json() avant vérif HMAC).
   - Récupère X-MCC-Signature (format "sha256=<hex>") et X-MCC-Timestamp.
   - Vérifie HMAC-SHA256(raw_body, MCC_WEBHOOK_SECRET) en temps constant.
   - Vérifie |now - timestamp| ≤ 300s.
   - Parse l'événement et appelle ma fonction handleEvent(event) (laisse-la TODO).
   - Renvoie 200 toujours sur succès, 401 sur signature invalide.

3. `components/PayButton.tsx` :
   - Composant client avec un bouton "Payer X HTG".
   - Au clic : POST vers /api/moncash/create, puis window.location.href = paymentUrl.
   - Gère l'état loading + l'affichage d'erreur si le serveur renvoie un `error`.

Référence : https://moncashconnect.com/docs (section "Créer un paiement" et "Webhooks").
Donne-moi le code complet, prêt à coller, en TypeScript strict.

Une fois le code généré

1. Copiez chaque fichier dans votre projet local.
2. Créez .env.local à la racine et ajoutez vos vraies clés (depuis votre gestionnaire de mots de passe) :
   envCopier

   MCC_SECRET_KEY=sk_proj_VOTRE_CLE
   MCC_WEBHOOK_SECRET=whsec_VOTRE_SECRET

3. Vérifiez que .env.local est dans votre.gitignore.
4. Lancez npm run dev et testez localement avec un tunnel ngrok (voir /guides/webhook-testing).
5. Pour la prod, ajoutez les mêmes variables dans le dashboard de votre hôte (Vercel, Netlify, etc.).

Maintenant que votre application a une route /api/moncash/webhook fonctionnelle, il faut dire à MonCashConnect où l'envoyer.

1. Retournez sur moncashconnect.com/developer.
2. Cliquez l'onglet « Projets ».
3. Cliquez les « ⋯ » (trois points) à droite de votre projet, puis « Modifier ».
4. Dans URL du webhook, collez l'URL complète : par exemple https://mon-shop.com/api/moncash/webhook.
5. Vérifiez que Domaines autorisés contient le domaine d'où votre page client va appeler /api/moncash/create.
6. Cliquez « Sauvegarder ».

Tester avant la mise en prod

Sur la page /developer, en bas, il y a une section « Webhook Tester ». Vous pouvez y envoyer un événement de test à votre URL, voir si votre code répond 200, et inspecter la signature reçue. Utilisez ça avant de pousser en production.

Pour tester en local (sans déployer), utilisez ngrok ou cloudflared comme expliqué dans /guides/webhook-testing.

Cochez chaque case avant d'annoncer votre intégration aux utilisateurs réels :

En cas de fuite de clé

1. Allez immédiatement sur moncashconnect.com/developer.
2. Onglet « Projets » → ⋯ → « Rotater les clés »(ou supprimez puis recréez le projet).
3. Copiez la nouvelle clé et le nouveau secret.
4. Mettez à jour les variables d'environnement chez votre hôte.
5. Redéployez. L'ancienne clé est immédiatement révoquée — toute requête future qui l'utilise échoue avec 401.
6. Si vous voyez des paiements ou retraits suspects, contactez le support sur support@moncashconnect.com.