Intégrez MonCash en moins de 5 minutes. Voici le flux minimal de bout en bout.

curl -X POST https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-create \
  -H "Authorization: Bearer sk_proj_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "referenceId": "order_001",
    "returnUrl": "https://votresite.com/merci"
  }'

const { paymentUrl } = await res.json();
// Côté serveur (Express, Next.js, etc.)
res.redirect(paymentUrl);

import { constructEvent, MonCashError } from "@moncashconnect/sdk";

// Express — lire le corps brut AVANT JSON.parse
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = constructEvent(
      req.body,
      req.headers["x-mcc-signature"],
      req.headers["x-mcc-timestamp"],
      process.env.MCC_WEBHOOK_SECRET,
    );
    if (event.event === "payment.completed") {
      // Créditez la commande dans votre base de données
    }
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof MonCashError) return res.status(err.statusCode).send(err.message);
    res.sendStatus(500);
  }
});

Chaque projet possède une clé secrète unique préfixée sk_proj_. Passez-la dans l'en-tête Authorization de chaque requête.

curl -H "Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-balance

Domaines autorisés (CORS)

Si vous configurez des domaines autorisés sur votre projet, les requêtes provenant d'autres origines seront rejetées avec un 403. Laissez la liste vide pour autoriser toutes les origines (usage serveur uniquement).

Crée une transaction en attente et renvoie une URL de paiement MonCash. Redirigez votre client vers cette URL. La transaction expire après 15 minutes.

Paramètres (JSON body)

curl -X POST https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-create \
  -H "Authorization: Bearer sk_proj_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "referenceId": "order_12345",
    "returnUrl": "https://votresite.com/merci",
    "customerName": "Jean Dupont",
    "customerEmail": "jean@example.com"
  }'

Réponse (200)

{
  "paymentUrl": "https://pay.bazik.io/c/abc123...",
  "reference":  "order_12345",
  "expiresAt":  "2026-05-05T15:30:00.000Z"
}

Reprise sûre avec Idempotency-Key

Une requête /pay-create qui échoue (erreur réseau, timeout, 502 passerelle) peut avoir déjà créé la transaction. Pour rendre les retries sûrs, ajoutez l'en-tête Idempotency-Key avec une chaîne unique par tentative logique (UUID, hash de commande, etc.) : un second appel avec la même clé et le même corps renvoie l'URL de paiement d'origine au lieu de créer un doublon.

Réponses possibles avec Idempotency-Key

curl -X POST https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-create \
  -H "Authorization: Bearer sk_proj_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345-attempt-1" \
  -d '{ "amount": 500, "referenceId": "order_12345", "returnUrl": "https://votresite.com/merci" }'

Interrogez le statut d'une transaction par son referenceId. Utile après la redirection du client ou pour un polling de secours si le webhook n'est pas configuré.

curl -H "Authorization: Bearer sk_proj_xxxx" \
  "https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-status?referenceId=order_12345"

Réponse (200)

{
  "reference":            "order_12345",
  "status":               "completed",
  "amount":               500,
  "netAmount":            485,
  "completedAt":          "2026-05-05T14:21:18.000Z",
  "failedAt":             null,
  "failureReason":        null,
  "bazikOrderId":         "BZK-987654321",
  "moncashTransactionId": "MC-123456789",
  "createdAt":            "2026-05-05T14:05:00.000Z"
}

Renvoie le solde HTG de votre compte marchand MonCashConnect — c'est-à-dire le total des paiements acceptés qui se sont décantés, moins les retraits déjà effectués. Cet endpoint ne renvoie aucune information sur un client ou un paiement particulier ; il sert à automatiser les retraits vers MonCash via votre tableau de bord.

curl -H "Authorization: Bearer sk_proj_xxxx" \
  "https://hvlmeoqyxaguzcujpmit.supabase.co/functions/v1/pay-balance"

{
  "balanceHtg":      12500,
  "withdrawableHtg":  5000,
  "dailyCapHtg":      5000,
  "usedTodayHtg":        0
}

Les retraits se demandent depuis la page Retraits du tableau de bord et sont approuvés avant envoi MonCash.

Configurez une URL webhook dans votre projet pour recevoir les événements de paiement en temps réel. MonCashConnect envoie un POST signé HMAC-SHA256 à votre URL dès qu'un paiement est finalisé par MonCash.

En-têtes envoyés

Événements

{
  "event": "payment.completed",
  "reference": "order_12345",
  "amount": 500,
  "status": "completed",
  "completedAt": "2026-05-05T14:21:18.000Z"
}

{
  "event": "payment.failed",
  "reference": "order_12345",
  "amount": 500,
  "status": "failed",
  "completedAt": null
}

Vérification de la signature

Lisez le corps brut (req.body en Buffer) avant tout JSON.parse(). Rejetez toute requête dont la signature est invalide ou dont le timestamp dépasse 5 minutes.

# Générer une signature de test en local
SECRET="whsec_votre_secret_webhook"
BODY='{"event":"payment.completed","reference":"test_001","amount":500,"status":"completed","completedAt":"2026-05-05T14:21:18.000Z"}'
TS=$(date +%s)
SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/.*= //')"

curl -X POST https://votresite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-MCC-Signature: $SIG" \
  -H "X-MCC-Timestamp: $TS" \
  -d "$BODY"

Politique de retry

Si votre endpoint ne répond pas avec un 2xx dans les 10 secondes, MonCashConnect enregistre l'échec et planifie une nouvelle tentative après 60 secondes. Assurez-vous que votre handler est idempotent — il peut recevoir le même événement plusieurs fois.

Des SDKs officiels couvrent les trois langages principaux. Chaque SDK inclut la gestion des erreurs, la vérification HMAC des webhooks et des types TypeScript / annotations Python.

import { MonCashClient } from "@moncashconnect/sdk";

const client = new MonCashClient(
  process.env.MCC_SECRET_KEY
);

const payment = await client.createPayment(
  500, "order_001",
  { returnUrl: "https://site.ht/merci" }
);
res.redirect(payment.paymentUrl);

from moncashconnect import MonCashClient
import os

client = MonCashClient(
  os.environ["MCC_SECRET_KEY"]
)

payment = client.create_payment(
  500, "order_001",
  return_url="https://site.ht/merci"
)
# redirect(payment["paymentUrl"])

use MonCashConnect\Client;

$client = new Client(
  $_ENV['MCC_SECRET_KEY']
);

$payment = $client->createPayment(
  500, 'order_001',
  ['returnUrl' => 'https://site.ht/merci']
);
header('Location: '.$payment['paymentUrl']);

Guides par framework

Frais détaillés

Pourquoi un abonnement existe alors ?

L'abonnement (Pro, Business, Lifetime) débloque deux choses uniquement : plus d'un projet API sur votre compte, et des plafonds journaliers plus élevés sur les retraits. Tant que vous tenez sur un seul projet et le plafond Free, vous n'avez aucune raison de payer. Voir les plans →

Les limites s'appliquent par clé secrète de projet et par adresse IP. Un dépassement retourne un 429 Too Many Requests.

En cas de dépassement répété, implémentez un backoff exponentiel avec jitter entre les tentatives. Évitez le polling intensif sur pay-status — préférez les webhooks pour les confirmations en temps réel.

Toutes les erreurs renvoient un objet JSON { "error": "message" }.

Codes d'erreur structurés (réponse 400)

Au-delà des codes HTTP, certaines réponses 400 incluent un champ code machine-lisible. Utilisez-le pour brancher la logique côté client.

Exemple de réponse d'erreur

{
  "error": "referenceId already exists for this project",
  "code":  "duplicate_reference"
}

Le champ code est stable ; le champ error est destiné aux humains et peut être traduit ou reformulé.