momo-payments

Mobile Money payments with momo-mcp

This skill teaches you how to drive the momo-mcp MCP server: a single integration to collect and send Mobile Money payments on MTN MoMo across 12 African markets.

Prerequisite

The momo-mcp MCP server must be installed and configured (API keys in its .env). Setup instructions: https://github.com/Tahsine/momo-mcp. This skill assumes its four tools are already available to you.

The 4 tools

Tool	Use it to
request_payment	Collect money from a customer (request-to-pay). Customer confirms with their PIN.
disburse_payment	Send money to someone (refund, salary, payout). Fund outflow — annotated destructiveHint.
check_payment_status	Read the final status of a payment or transfer.
validate_account	Check a number has an active Mobile Money account before paying it.

All tools return a JSON dict. Success → {"ok": true, ...}. Failure → {"ok": false, "error": {...}} (never a raw exception — see Errors). You must inspect ok before acting on the result.

Core flow: collecting a payment

request_payment is asynchronous. It returns immediately with status: "PENDING" and a reference_id; the customer then confirms with their PIN on their phone. You must poll check_payment_status to learn the outcome.

request_payment(phone_number, amount, currency, external_id, country)
    -> {"ok": true, "reference_id": "...", "status": "PENDING", ...}

   (customer confirms with PIN — seconds to minutes)

check_payment_status(reference_id, kind="collection", country)
    -> status: "PENDING"  |  "SUCCESSFUL"  |  "FAILED"

Rules of thumb:

1. Never tell the user a payment succeeded right after request_payment — it is only PENDING.
2. Poll with check_payment_status until the status is SUCCESSFUL or FAILED. Space calls out (e.g. every 5–10s); do not hammer the endpoint.
3. When sending money out, set kind="disbursement". With the default kind="auto", the server tries collection then disbursement (one extra round-trip on 404).
4. Pass the same country to check_payment_status as you used when creating the payment.