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

curl -X POST https://api.moncashconnect.com/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://api.moncashconnect.com/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://api.moncashconnect.com/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.moncashconnect.com/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://api.moncashconnect.com/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://api.moncashconnect.com/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,
  "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://api.moncashconnect.com/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.

Il existe plusieurs façons d'envoyer de l'argent depuis MonCashConnect. Choisissez la bonne selon votre besoin :

Automatiser les paiements vers vos utilisateurs (API)

Envoie des fonds depuis votre solde marchand vers n'importe quel numéro MonCash. Votre compte MonCashConnect agit comme un pool commun : vous encaissez les paiements de vos utilisateurs, puis redistribuez vers chacun d'eux — gérez leur solde individuel dans votre propre base de données.

Paramètres (JSON body)

curl -X POST https://api.moncashconnect.com/v1/payout-create \
  -H "Authorization: Bearer sk_proj_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-user42-2026-06-24" \
  -d '{
    "amount": 5000,
    "moncashNumber": "50912345678",
    "referenceId": "payout-user42-2026-06-24"
  }'

Réponse (201)

{
  "status": "success",
  "payout": {
    "reference":                "wd_123",
    "status":                   "queued",
    "amount_htg":               5000,
    "fee_htg":                  250,
    "net_htg":                  5000,
    "recipient_account_masked": "509****1234"
  }
}

Idempotence

Passez un referenceId unique ou l'en-tête Idempotency-Key pour rendre les retries sûrs. Un second appel avec le même identifiant retourne 409 duplicate_reference au lieu de créer un doublon.

Webhook de confirmation

MonCashConnect envoie un POST signé HMAC-SHA256 à votre URL webhook dès que le payout est réglé. La signature se vérifie exactement comme pour les webhooks pay-in (X-MCC-Signature: sha256=…, X-MCC-Timestamp).

{
  "event": "payout.completed",
  "reference": "wd_123",
  "amount": 5000,
  "status": "completed",
  "recipient_account_masked": "509****1234",
  "completedAt": "2026-06-24T16:21:18.000Z",
  "failureReason": null
}

{
  "event": "payout.failed",
  "reference": "wd_124",
  "amount": 5000,
  "status": "failed",
  "recipient_account_masked": "509****5678",
  "completedAt": null,
  "failureReason": "recipient_account_not_found"
}

Codes d'erreur spécifiques aux payouts

Retraits automatiques (sans code)

Pas besoin de coder pour automatiser vos propres retraits. Sur la page Retraits, activez les paiements automatiques : choisissez un numéro de retrait enregistré, indiquez « Envoyer quand le solde atteint » un seuil (minimum 100 HTG), et un plafond optionnel par paiement. Dès que votre solde franchit le seuil, MonCashConnect envoie automatiquement vers ce numéro, avec un délai minimum de 30 minutes entre deux envois. Mêmes frais réseau que pour un retrait manuel.

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, Early Visionary Pass) 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.

Pages hébergées (QR de dépôt & factures)

Les pages de paiement hébergées par MonCashConnect — la page de dépôt par QR code et la page de règlement de facture — sont chargées par le navigateur de votre client, pas par votre serveur. Elles possèdent leurs propres limites, appliquées par adresse IP et par jeton public ; un dépassement retourne également un 429 Too Many Requests avec un en-tête Retry-After: 60.

Ces limites protègent les pages hébergées contre les abus ; elles n'affectent pas vos appels serveur authentifiés par clé sk_proj_.

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é.