You are implementing MonCashConnect (MCC) sandbox payments on this project.

MCC is a Stripe-style payment gateway for MonCash (Haiti's mobile money). Sandbox mode lets us test the full payment flow without moving any real money. When we're ready, the same code goes live by swapping two env values — no code change required.

The user will provide three pieces of info. Ask for them before writing code. Do not invent placeholders.

- DOMAIN: the merchant's domain (e.g. mamasoil.shop). It becomes the Origin header on the call to MCC, and must already be in MCC's "Allowed domains" list (the user adds it in the MCC dashboard).
- MCC_SECRET: starts with `sk_test_proj_`. From MCC dashboard → Developer → Projets → "Régénérer les clés de test" modal.
- MCC_WEBHOOK_SECRET: the test webhook secret from the same modal.

== MCC API contract ==

1) Create a payment — your backend → MCC
   POST https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-create
   Headers:
     Authorization: Bearer <MCC_SECRET>
     Origin: https://<DOMAIN>      ← MUST match Allowed domains exactly. Server-side fetch does not set Origin automatically; set it manually.
     Content-Type: application/json
   Body:
     {
       "amount": <integer HTG, 1 to 1_000_000>,
       "referenceId": "<unique id you generate, UUID is fine>",
       "returnUrl": "https://<DOMAIN>/checkout/return",
       "customerEmail": "optional@example.com",   ← OMIT (not empty string) if absent
       "customerName": "optional"                  ← OMIT if absent
     }
   Response 200:
     { paymentUrl, reference, expiresAt, livemode: false }
   Redirect the browser to paymentUrl. In sandbox it's the MCC simulator (3-button page); in live it's the real MonCash URL.

2) Receive webhook — MCC → your backend
   POST <your webhook endpoint, the URL the user will set in MCC project settings>
   Headers:
     X-MCC-Signature: sha256=<hex>
     X-MCC-Timestamp: <unix seconds>
     Content-Type: application/json
   Body:
     {
       event: "payment.completed" | "payment.failed" | "payment.cancelled",
       reference: "<the referenceId you sent earlier>",
       amount: <integer HTG>,
       status: "completed" | "failed" | "cancelled",
       completedAt: <ISO8601 or null>,
       livemode: false              ← present on sandbox only; ABSENT on live (do NOT gate with === true)
     }

   Verification (CRITICAL):
     a. Read the body as RAW BYTES first (e.g. req.text() in Deno, raw req in Express). Do NOT parse JSON before verifying — re-serializing reorders keys and breaks HMAC.
     b. Compute expected = "sha256=" + hex(HMAC-SHA256(MCC_WEBHOOK_SECRET, rawBody))
     c. Compare to X-MCC-Signature header. Reject with 401 if mismatch.
     d. Only AFTER verifying, JSON.parse(rawBody) and dispatch on event.
   Handle ALL three event types. Returning non-200 on any of them causes MCC to retry forever.
   Return 200 with any short body on success.

3) Poll status (webhook fallback) — your return page → MCC, no auth
   GET https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-status?reference=<referenceId>
   Response: { reference, status, amount, ... }
   Use this from the customer's /checkout/return page, polling every 3 seconds for up to 90 seconds, in case the webhook is delayed.

== Files to create ==

1. Backend endpoint `create-mcc-payment` (or your stack's equivalent)
   Calls MCC pay-create with MCC_SECRET. Must handle CORS preflight (OPTIONS → 204 with CORS headers).

2. Backend endpoint `mcc-webhook`
   Receives, verifies HMAC, dispatches on event. Uses raw body for HMAC, parses JSON only after verifying.

3. Frontend "Pay with MonCash" button on the checkout page
   Calls create-mcc-payment with the amount, then window.location = paymentUrl.

4. Frontend `/checkout/return` page
   Reads ?reference, ?error, ?cancelled from the query string. Polls pay-status every 3s up to 30 attempts (90s total) as the webhook fallback. Shows success / failed / cancelled / timeout state to the customer.

5. Two environment variables on the backend
   MCC_SECRET           = sk_test_proj_<...>      (sandbox value for now)
   MCC_WEBHOOK_SECRET   = <test webhook secret>
   Use GENERIC names (no _TEST_) so the live swap is a value change, not a code change.

6. The MCC project's "Webhook URL" field (the user sets this in MCC dashboard) must point at your deployed mcc-webhook endpoint.

== Critical gotchas ==

- Origin header MUST be set on the server-side fetch to MCC. Browsers add it automatically; servers do not.
- Raw body for HMAC verify, never the parsed-then-restringified payload.
- All three webhook event types (completed / failed / cancelled) must be handled — non-200 = infinite retry.
- `livemode` is `false` on sandbox payloads and ABSENT on live. Never gate logic with `livemode === true`.
- CORS preflight on create-mcc-payment — return CORS headers on OPTIONS, not just on POST.
- Omit customerEmail / customerName if absent; do not send empty string.
- amount is integer HTG between 1 and 1,000,000. Recommended test value: 100.

== Out of scope (do NOT do these) ==

- Live mode. Implement sandbox only. Live is one env swap later, not a code change.
- The merchant's own order persistence / inventory / fulfillment logic. Hand them the payment.completed event and let them wire it.
- Translating "Sandbox" to French if generating French copy. It's the product feature name and stays English (like Stripe).

== When done ==

Give the user:
1. The two env vars they need to set + the webhook URL they need to paste into the MCC project.
2. A 4-step test plan: open the simulator URL returned from pay-create, click Pay success on the MCC simulator, verify webhook arrives in your logs + your /checkout/return resolves to "completed".
3. A one-line note: going live = swap MCC_SECRET to sk_proj_<...> + MCC_WEBHOOK_SECRET to the live webhook secret, no code change.

{
  "amount": 100,
  "referenceId": "<your-unique-id>",
  "returnUrl": "https://YOUR-DOMAIN/checkout/return",
  "customerEmail": "optional@example.com",
  "customerName": "optional"
}

{
  "paymentUrl": "https://moncashconnect.com/sim/<reference>?p=<short>",
  "reference": "<your-unique-id>",
  "expiresAt": "2026-01-01T00:00:00Z",
  "livemode": false
}

{
  "event": "payment.completed" | "payment.failed" | "payment.cancelled",
  "reference": "<your-unique-id>",
  "amount": 100,
  "status": "completed" | "failed" | "cancelled",
  "completedAt": "2026-01-01T00:00:00Z" | null,
  "livemode": false
}

MCC_SECRET = sk_test_proj_<your-test-secret>
MCC_WEBHOOK_SECRET = <your-test-webhook-secret>