Integrate MonCash in under 5 minutes. Here is the minimal end-to-end flow.

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();
// Server-side (Express, Next.js, etc.)
res.redirect(paymentUrl);

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

// Express — read the raw body BEFORE 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") {
      // Credit the order in your database
    }
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof MonCashError) return res.status(err.statusCode).send(err.message);
    res.sendStatus(500);
  }
});

Each project has a unique secret key prefixed with sk_proj_. Pass it in the Authorization header of every request.

curl -H "Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://api.moncashconnect.com/v1/pay-balance

Allowed domains (CORS)

If you configure allowed domains on your project, requests from other origins will be rejected with a 403. Leave the list empty to allow all origins (server-side use only).

Creates a pending transaction and returns a MonCash payment URL. Redirect your customer to this URL. The transaction expires after 15 minutes.

Parameters (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"
  }'

Response (200)

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

Safe retries with Idempotency-Key

A /pay-create request that fails (network error, timeout, 502 gateway) may have already created the transaction. To make retries safe, add the Idempotency-Key header with a string that is unique per logical attempt (UUID, order hash, etc.): a second call with the same key and the same body returns the original payment URL instead of creating a duplicate.

Possible responses with 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" }'

Query the status of a transaction by its referenceId. Useful after the customer redirect or for fallback polling if the webhook is not configured.

curl -H "Authorization: Bearer sk_proj_xxxx" \
  "https://api.moncashconnect.com/v1/pay-status?referenceId=order_12345"

Response (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"
}

Returns the HTG balance of your MonCashConnect merchant account — that is, the total of accepted payments that have settled, minus withdrawals already made. This endpoint returns no information about any particular customer or payment; it is used to automate withdrawals to MonCash from your dashboard.

curl -H "Authorization: Bearer sk_proj_xxxx" \
  "https://api.moncashconnect.com/v1/pay-balance"

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

Withdrawals are requested from the Withdrawals page of the dashboard and are approved before being sent to MonCash.

There are several ways to send money from MonCashConnect. Choose the right one for your needs:

Automate payments to your users (API)

Sends funds from your merchant balance to any MonCash number. Your MonCashConnect account acts as a shared pool: you collect payments from your users, then redistribute to each of them — manage their individual balance in your own database.

Parameters (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"
  }'

Response (201)

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

Idempotency

Pass a unique referenceId or the Idempotency-Key header to make retries safe. A second call with the same identifier returns 409 duplicate_reference instead of creating a duplicate.

Confirmation webhook

MonCashConnect sends an HMAC-SHA256-signed POST to your webhook URL as soon as the payout is settled. The signature is verified exactly as for pay-in webhooks (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"
}

Payout-specific error codes

Automatic withdrawals (no code)

No coding needed to automate your own withdrawals. On the Withdrawals page, enable automatic payments: choose a saved withdrawal number, set a "Send when balance reaches" threshold (minimum 100 HTG), and an optional cap per payment. As soon as your balance crosses the threshold, MonCashConnect sends automatically to that number, with a minimum delay of 30 minutes between two sends. Same network fees as for a manual withdrawal.

Configure a webhook URL in your project to receive payment events in real time. MonCashConnect sends an HMAC-SHA256-signed POST to your URL as soon as a payment is finalized by MonCash.

Headers sent

Events

{
  "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
}

Signature verification

Read the raw body (req.body as a Buffer) before any JSON.parse(). Reject any request whose signature is invalid or whose timestamp is more than 5 minutes old.

# Generate a test signature locally
SECRET="whsec_your_webhook_secret"
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://yoursite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-MCC-Signature: $SIG" \
  -H "X-MCC-Timestamp: $TS" \
  -d "$BODY"

Retry policy

If your endpoint does not respond with a 2xx within 10 seconds, MonCashConnect records the failure and schedules a new attempt after 60 seconds. Make sure your handler is idempotent — it may receive the same event several times.

Official SDKs cover the three main languages. Each SDK includes error handling, HMAC verification of webhooks, and TypeScript types / Python annotations.

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 by framework

Detailed fees

So why does a subscription exist?

The subscription (Pro, Early Visionary Pass) unlocks only two things: more than one API project on your account, and higher daily caps on withdrawals. As long as you stay on a single project and the Free cap, you have no reason to pay. See the plans →

Limits apply per project secret key and per IP address. Exceeding them returns a 429 Too Many Requests.

In case of repeated overruns, implement an exponential backoff with jitter between attempts. Avoid intensive polling on pay-status — prefer webhooks for real-time confirmations.

Hosted pages (deposit QR & invoices)

The payment pages hosted by MonCashConnect — the QR-code deposit page and the invoice settlement page — are loaded by your customer's browser, not by your server. They have their own limits, applied per IP address and per public token; exceeding them also returns a 429 Too Many Requests with a Retry-After: 60 header.

These limits protect the hosted pages against abuse; they do not affect your server calls authenticated with an sk_proj_ key.

All errors return a JSON object { "error": "message" }.

Structured error codes (400 response)

Beyond HTTP codes, some 400 responses include a machine-readable code field. Use it to branch your client-side logic.

Example error response

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

The code field is stable; the error field is meant for humans and may be translated or reworded.