Documentation API

Intégrez MonCash en quelques minutes

MonCashConnect est une API REST simple pour accepter des paiements MonCash dans votre application, votre site WordPress ou votre SaaS — sans gérer OAuth, jetons ou la complexité du SDK officiel.

Chaque requête est authentifiée avec une clé API par projet. Les webhooks signés garantissent l'intégrité des notifications de paiement.

HMAC-SHA256

Webhooks fiables

REST + JSON

URL de base

https://<votre-projet>.supabase.co/functions/v1

Authentification

Créez un projet dans Développeur → Projets pour obtenir une clé secrète. Préfixe : sk_proj_

bash

curl -H "Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxx" \
     https://<votre-projet>.supabase.co/functions/v1/pay-balance

Ne partagez jamais votre clé secrète. En cas de fuite, révoquez-la depuis le tableau Développeur.

Créer un paiement

POST

/functions/v1/pay-create

Crée une transaction et renvoie une URL de paiement à présenter à votre client.

Paramètres (JSON)

Nom	Type	Description
amount*	integer	Montant en HTG (entier, 1 à 1 000 000)
referenceId*	string	Identifiant unique [a-zA-Z0-9-_], 100 car. max
returnUrl*	string	URL HTTPS de retour après paiement
customerName	string	Nom du client (optionnel)
customerEmail	string	Email du client (optionnel)

bash

curl -X POST https://<projet>.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://votre-site.com/merci",
    "customerName": "Jean Dupont",
    "customerEmail": "jean@example.com"
  }'

Réponse (200)

json

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

Vérifier le statut

GET

/functions/v1/pay-status?referenceId=order_12345

bash

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

json

{
  "reference": "order_12345",
  "status": "completed",
  "amount": 500,
  "netAmount": 485,
  "completedAt": "2026-05-05T14:21:18.000Z",
  "moncashTransactionId": "MC-987654321"
}

Statuts possibles : pending, completed, failed, refunded.

Solde & retraits

GET

/functions/v1/pay-balance

Renvoie le solde HTG disponible et le plafond journalier de retrait selon votre plan.

json

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

Les retraits se demandent depuis la page Retraits et sont approuvés par notre équipe avant envoi MonCash.

Webhooks

Configurez une URL de webhook dans votre projet pour recevoir les notifications de paiement en temps réel. Chaque requête est signée avec HMAC-SHA256.

En-têtes envoyés

Nom	Type	Description
X-MCC-Signature	string	sha256=<hex_hmac>
X-MCC-Timestamp	string	Timestamp Unix de l'envoi
Content-Type	string	application/json

Payload

json

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

Vérification (Node.js)

import crypto from "node:crypto";

function verifyMccWebhook(rawBody, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rejetez tout webhook dont la signature est invalide ou dont le timestamp dépasse 5 minutes. Renvoyez un statut 2xx pour confirmer la réception ; sinon nous réessayons.

Codes d'erreur

Nom	Type	Description
400	Bad Request	Paramètre invalide ou manquant
401	Unauthorized	Clé API absente ou invalide
403	Forbidden	Origine non autorisée ou compte suspendu
404	Not Found	Transaction introuvable
409	Conflict	referenceId déjà utilisé pour ce projet
429	Too Many Requests	Limite de débit atteinte (60/min/clé)
502	Bad Gateway	Erreur passerelle de paiement — réessayez

Prêt à intégrer ?

Créez un projet et obtenez vos clés API en moins d'une minute.