Connect lets your application execute outbound MonCash payouts from the HTG balance of a MonCashConnect user. Mental model: MonCashConnect is to a remittance product what a card network is to a merchant. Your app knows whose money it is and why; MCC validates the source of funds, checks the limit, and confirms the rail accepted.

Who owns what

RFC 6749 authorization-code flow with HTTP Basic client authentication. No refresh tokens. Codes are single-use, valid for 60 seconds; access tokens are valid for 30 days.

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>

The user signs in if they aren't already, sees the consent screen, picks a daily cap, clicks Authorize. The default UX is gateway-only (requires_user_approval = false); the user can opt into a second approval layer, but your application must not depend on it.

On approval → redirect to redirect_uri?code=<raw>&state=<state>. On refusal → redirect to redirect_uri?error=access_denied&state=<state>.

2. Exchange the code for a 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

Canonical body

Tolerant parsing. Any JSON key outside the canonical list above is read and discarded. No validation, no error, no storage, no echo. Compatibility guarantee for partners migrating from v3.

Response

201 Created for a new request, 200 OK on an idempotent replay (matched external_reference) with 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
}

Idempotency — difference vs. /pay-create

Replays are matched on (user_connected_app_id, external_reference). A second POST with the same external_reference returns the current state of the original payout (200 OK, is_replay: true). The replay body is not consulted — any fields you may have modified are ignored. To retry with different fields, generate a new external_reference.

Requires the payout.status.read scope. Returns the same shape as the partner-view (cf. §webhooks) for any payout previously created on this connection.

Operational reality — asynchronous delivery confirmation

Connect rate limits

Status values on the wire

All terminal statuses are stable — once reached, MCC will not change the status again.

Timestamp of completed

The webhook's occurred_at reflects when MCC marked the row as completed, not necessarily when the actual MonCash delivery happened. When confirmation is delayed, the two can be several hours apart. Treat completed as authoritative for state, not as a to-the-second delivery timestamp.

MCC POSTs HMAC-signed events to the URL configured in connected_apps.webhook_url.

Headers sent

Signature verification

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);

Events

Example 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
  }
}

failure_reason vocabulary

When data.status = "failed", this field carries one of:

Delivery semantics

• At-least-once. A 2xx from the partner stops retries; otherwise exponential retry up to an attempts cap.
• Out-of-order delivery is possible. Sort by occurred_at if you track transitions; treat data.status as authoritative.
• Deduplicate on event_id. Same id = same event, even if the payload differs between attempts.
• Idempotent reception. Processing the same event_id twice must produce the same result.

The wire gives you status, not latency. Here's what's normal and what isn't.

Typical happy-path SLA

What to do if a payout stays at submitting ≥ 30 min

• Don't cancel, don't retry. The funds are already debited from the user's MCC balance; the payout will be completed (via admin_manual if needed) or refunded.
• Show "in progress" on the UX, not "failed". The status on the wire stays non-terminal until resolution.
• Contact MCC support with the external_reference if the latency exceeds your tolerable window. Support will verify independently and confirm the delivery if it did occur.

All errors return a JSON object with an error field (machine-stable code) and an error_description field (human-readable).

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