This guide is written for people building their application with an AI tool (Lovable, Claude, Bolt, v0, GitHub Copilot Workspaces, etc.) who want to accept MonCash payments through MonCashConnect. No prior programming knowledge is required — but a single security mistake can drain your account. Read the next section in full before doing anything else.

What you'll end up with

• A MonCash checkout page wired to your Lovable or Claude application
• A webhook that automatically marks your orders as "paid"
• A secure setup — your keys are never exposed in public code, in the AI chat history, or in your Git repository

Prerequisites

• An active MonCashConnect account (create one at /auth)
• A Lovable, Claude (Claude.ai), Bolt or equivalent project
• A domain where your application is deployed (or an ngrok tunnel for local testing — see the webhook-testing guide)

The golden rule

Never type your secret key or your webhook secret into an AI chat window (Lovable, Claude, ChatGPT, Bolt, etc.).

Why? The contents of your AI chat are:

• Stored server-side (Anthropic, Lovable, OpenAI, etc.) — not end-to-end encrypted
• Potentially visible to the platform's support engineers
• Sometimes indexed by internal analytics or fine-tuning tooling
• Persisted in the project history — accessible to any invited collaborator
• Backed up in logs that can be exfiltrated in case of a breach

A key that appears even once in a chat must be considered compromised forever. Revoke it immediately and generate a new one.

What can be public (safe)

What is secret (NEVER paste into an AI chat)

All configuration lives on the Developer page of your dashboard. Here's exactly where to click:

Navigate to the Developer page

1. Go to moncashconnect.com and sign in (Sign in link at the top right).
2. Once signed in, open the Dashboard menu.
3. In the sidebar, click Developer (key icon). The direct URL is moncashconnect.com/developer.
4. You'll see two tabs: "API Keys" and "Projects".

Create a project

For serious integrations (with a deployed site and a webhook), create a Project rather than just an API key. A Project bundles:

1. On /developer, click the "Projects" tab.
2. Click the "New project" button (top right of the list).
3. Fill in:
   • Name: the name of your shop / app.
   • Webhook URL: https://your-site.com/api/moncash-webhook (you'll configure this route in step 4 — leave it blank if you don't know yet).
   • Allowed domains: your-site.com, www.your-site.com (comma-separated).
4. Click "Create".
5. ONLY ONCE, MonCashConnect shows you:
   • Your full secret key sk_proj_xxxxxxxxxxxxxxxx
   • Your full webhook secret whsec_xxxxxxxxxxxxxxxx
6. Click the "Copy" buttons next to each value and paste them into a password manager (1Password, Bitwarden, the macOS keychain, etc.) — not into a text file on your desktop, and especially not into the AI chat.

You now have your two secrets in your password manager. You need to make them available to your code without the value going through the AI. The standard technique: environment variables.

If you use Lovable

1. In your Lovable project, click the ⚙️ Settings icon (or the gear icon depending on your version).
2. Look for the "Environment Variables" or "Secrets" section.
3. Click "Add a variable".
4. Create these two variables (one at a time):
   envCopier

   MCC_SECRET_KEY=sk_proj_VOTRE_CLE_SECRETE_ICI
   MCC_WEBHOOK_SECRET=whsec_VOTRE_SECRET_WEBHOOK_ICI

5. Save. Lovable redeploys automatically. The values are encrypted at rest and injected into process.env at runtime.

If you use Claude to generate code that you host elsewhere

Claude generates the code, but you deploy it (Vercel, Netlify, Cloudflare, etc.). Never hardcode the key inside the generated code. Instead, add the same two variables in your host's environment panel:

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

Here's a copy-paste-ready prompt for Lovable. Notice that the key appears nowhere — we just tell Lovable to use the environment variable.

Prompt — Checkout (payment)

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)

Run this prompt after the checkout works, to add automatic confirmation:

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").

If you use Claude (claude.ai) to generate code that you then paste into your project, here's the prompt to use. Same principle: the key never appears in the chat.

Prompt — Generate the code (Next.js example)

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.

Once the code is generated

1. Copy each file into your local project.
2. Create .env.local at the root and add your real keys (from your password manager):
   envCopier

   MCC_SECRET_KEY=sk_proj_VOTRE_CLE
   MCC_WEBHOOK_SECRET=whsec_VOTRE_SECRET

3. Make sure .env.local is in your.gitignore.
4. Run npm run dev and test locally with an ngrok tunnel (see /guides/webhook-testing).
5. For production, add the same variables in your host's dashboard (Vercel, Netlify, etc.).

Now that your application has a working /api/moncash/webhook route, you need to tell MonCashConnect where to send it.

1. Go back to moncashconnect.com/developer.
2. Click the "Projects" tab.
3. Click the "⋯" (three dots) to the right of your project, then "Edit".
4. In Webhook URL, paste the full URL: for example https://my-shop.com/api/moncash/webhook.
5. Make sure Allowed domains contains the domain your client page will call /api/moncash/create from.
6. Click "Save".

Test before going to production

On the /developer page, at the bottom, there's a "Webhook Tester" section. You can send a test event to your URL, check that your code answers 200, and inspect the received signature. Use this before pushing to production.

To test locally (without deploying), use ngrok or cloudflared as explained in /guides/webhook-testing.

Tick every box before announcing your integration to real users:

If a key leaks

1. Go immediately to moncashconnect.com/developer.
2. "Projects" tab → ⋯ → "Rotate keys"(or delete and recreate the project).
3. Copy the new key and the new secret.
4. Update the environment variables at your host.
5. Redeploy. The old key is revoked immediately — any future request using it fails with 401.
6. If you see suspicious payments or withdrawals, contact support at support@moncashconnect.com.