Connect permet à votre application d'exécuter des payouts MonCash sortants depuis le solde HTG d'un utilisateur MonCashConnect. Modèle mental : MonCashConnect est à un produit de remise ce qu'un réseau de cartes est à un commerçant. Votre application connaît à qui appartient l'argent et pourquoi ; MCC valide la source de fonds, vérifie la limite, et confirme que le rail a accepté.

Qui possède quoi

RFC 6749 authorization-code flow avec authentification client HTTP Basic. Pas de refresh tokens. Codes uniques à usage unique, valides 60 secondes ; access tokens valides 30 jours.

1. Authorize

GET https://moncashconnect.com/connect/authorize
    ?response_type=code
    &client_id=<public_client_id>
    &redirect_uri=<exact match de callback_url>
    &scope=<scopes séparés par espace>
    &state=<opaque, contrôlé par le partenaire>

L'utilisateur signe in s'il ne l'est pas déjà, voit l'écran de consentement, choisit un plafond journalier, clique Autoriser. L'UX par défaut est gateway-only (requires_user_approval = false) ; l'utilisateur peut opter pour une seconde couche d'approbation, mais votre application ne doit pas en dépendre.

Sur approbation → redirect vers redirect_uri?code=<raw>&state=<state>. Sur refus → redirect vers redirect_uri?error=access_denied&state=<state>.

2. Échange du code contre un token

POST https://api.moncashconnect.com/v1/oauth-token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<raw>
&redirect_uri=<exact match de l'authorize redirect_uri>

{
  "access_token": "<43 caractères URL-safe>",
  "token_type":   "Bearer",
  "expires_in":   2592000,
  "scope":        "payout.request"
}

3. Scopes

Corps canonique

Parsing tolérant. Toute clé JSON hors de la liste canonique ci-dessus est lue et écartée. Pas de validation, pas d'erreur, pas de stockage, pas d'écho. Garantie de compatibilité pour partenaires migrant depuis v3.

Réponse

201 Created pour une nouvelle requête, 200 OK sur replay idempotent (matched external_reference) avec is_replay: true.

{
  "id":                          "5c715691-2953-4a35-8f72-ff817aefeb12",
  "status":                      "auto_approved",
  "amount_htg":                  1000,
  "currency":                    "HTG",
  "recipient_moncash_number_last4": "4567",
  "external_reference":          "smoke-stage6-1778177771",
  "is_sandbox":                  false,
  "is_replay":                   false,
  "created_at":                  "2026-05-07T18:16:13.131436+00:00",
  "expires_at":                  null
}

Idempotence — différence avec /pay-create

Les replays sont matchés sur (user_connected_app_id, external_reference). Un deuxième POST avec le même external_reference retourne l'état courant du payout original (200 OK, is_replay: true). Le corps du replay n'est pas consulté — les champs que vous auriez modifiés sont ignorés. Pour un retry avec des champs différents, générez un nouvel external_reference.

Requiert le scope payout.status.read. Retourne la même forme que la partner-view (cf. §webhooks) pour tout payout créé précédemment sur cette connexion.

Réalité opérationnelle — confirmation de livraison asynchrone

Limites de débit Connect

Valeurs de statut sur le fil

Tous les statuts terminaux sont stables — une fois atteints, MCC ne changera plus le statut.

Horodatage de completed

Le occurred_at du webhook reflète quand MCC a marqué la ligne comme complétée, pas nécessairement quand la livraison MonCash réelle s'est produite. En cas de confirmation différée, les deux peuvent être à plusieurs heures d'écart. Traitez completed comme autoritatif pour l'état, pas comme un horodatage de livraison à la seconde près.

MCC POST des événements signés HMAC vers l'URL configurée dans connected_apps.webhook_url.

En-têtes envoyés

Vérification de la signature

import crypto from "node:crypto";

// Lisez le corps en bytes bruts AVANT toute désérialisation
const rawBody  = Buffer.from(await req.text(), "utf8");
const sigHdr   = req.headers["x-mcc-signature"]; // "t=...,v1=..."
const eventId  = req.headers["x-mcc-event-id"];

const parts = Object.fromEntries(
  sigHdr.split(",").map((p) => p.split("=")),
);
const ts = parts.t, v1 = parts.v1;

if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
  throw new Error("timestamp drift");
}

const expected = crypto
  .createHmac("sha256", process.env.MCC_WEBHOOK_SECRET)
  .update(`${ts}.${rawBody.toString("utf8")}`)
  .digest("hex");

if (!crypto.timingSafeEqual(
  Buffer.from(expected, "hex"),
  Buffer.from(v1, "hex"),
)) throw new Error("bad signature");

// Dédupliquez sur eventId avant de traiter
if (await alreadyProcessed(eventId)) return res.sendStatus(200);

Événements

Exemple de payload

{
  "event_id": "f8e2d1c0-1234-5678-9abc-def012345678",
  "event_type": "external_payout.completed",
  "occurred_at": "2026-05-07T18:16:13Z",
  "data": {
    "id": "5c715691-2953-4a35-8f72-ff817aefeb12",
    "external_reference": "smoke-stage6-1778177771",
    "status": "completed",
    "amount_htg": 1000,
    "currency": "HTG",
    "recipient_moncash_number_last4": "4567",
    "recipient_name": "Camy Peter",
    "is_sandbox": false,
    "created_at": "2026-05-07T18:14:02Z",
    "updated_at": "2026-05-07T18:16:13Z",
    "delivery_confirmed_at": "2026-05-07T18:16:13Z",
    "delivery_failed_at": null,
    "failure_reason": null
  }
}

Vocabulaire de failure_reason

Quand data.status = "failed", ce champ porte l'une de :

Sémantique de livraison

• At-least-once. Une 2xx du partenaire stoppe les retries ; sinon retry exponentiel jusqu'à un cap d'attempts.
• Livraison hors-ordre possible. Triez par occurred_at si vous suivez les transitions ; traitez data.status comme autoritatif.
• Dédupliquez sur event_id. Même id = même événement, même si le payload diffère entre tentatives.
• Réception idempotente. Traiter deux fois le même event_id doit produire le même résultat.

Le fil donne le statut, pas la latence. Voici ce qui est normal et ce qui ne l'est pas.

SLA happy-path typique

Que faire si un payout reste à submitting ≥ 30 min

• N'annulez pas, ne réessayez pas. Les fonds sont déjà débités du solde MCC de l'utilisateur ; le payout sera complété (via admin_manual si nécessaire) ou remboursé.
• Affichez "en cours" côté UX, pas "échoué". Le statut sur le fil reste non-terminal jusqu'à résolution.
• Contactez le support MCC avec le external_reference si la latence dépasse votre fenêtre tolérable. Le support vérifiera indépendamment et confirmera la livraison si elle a bien eu lieu.

Toutes les erreurs renvoient un objet JSON avec un champ error (code machine-stable) et un champ error_description (humain).

{
  "error":             "insufficient_scope",
  "error_description": "Token lacks 'payout.request' scope"
}