WariMCP

WariMCP is an MCP (Model Context Protocol) server that gives AI agents and REST clients a unified interface to West African payment providers. It exposes 10 providers through a single API — payments, payouts, refunds, webhooks — with FedaPay as the recommended primary and Hub2 as the recommended secondary. Runs as an MCP stdio server (for Claude/Cursor/Windsurf), an Express HTTP API, or both simultaneously.

Quick Start

git clone https://github.com/Bigabou007-dev/warimcp.git
cd warimcp
npm install
cp .env.example .env   # edit with your credentials
npm run db:migrate      # set up PostgreSQL schema
npm run db:seed-api-key # generate your first API key
npm run dev             # starts MCP + HTTP on port 3000

Requires Node >= 22 and PostgreSQL 16+.

Providers

10 providers are available in the codebase. The recommended production setup is FedaPay + Hub2.

Provider	Key	Region	Methods	Currencies	Status
FedaPay	fedapay	CI, SN, BJ, TG, BF, ML, NE, GW	MTN, Orange, Moov, Wave, Card	XOF, XAF, GNF	Recommended Primary — live keys, true aggregator
Hub2	hub2	CI, SN, ML, BF, TG, BJ, NE, CM	Mobile Money	XOF, XAF	Recommended Secondary — pending sandbox access
CinetPay	cinetpay	CI, SN, ML, BF, TG, BJ + 6 more	Mobile Money, Card, Wallet	XOF, XAF, CDF, GNF	Requires RCCM
Wave	wave	CI, SN, ML, BF, UG, TZ	Wave wallet	XOF	Requires RCCM
Flutterwave	flutterwave	CI, SN, NG, GH, KE + 4 more	Mobile Money, Card, Bank	XOF, XAF, NGN, GHS, KES, USD, EUR	Available
KKiaPay	kkiapay	CI, SN, BJ, BF, ML, TG, NE, GW	MTN, Orange, Wave, Card	XOF, XAF	Available
Moneroo	moneroo	CI, SN, BJ, BF + 10 more	MTN, Orange, Wave, Moov, Card, Bank	XOF, XAF, GNF, CDF, NGN, GHS, KES, USD, EUR	Available
MTN MoMo	mtn	CI, GH, UG, RW, BJ, CM, CG	MTN Mobile Money	EUR	Available
PAPSS	papss	CI, KE, NG, GH	Bank Transfer	XOF, KES, NGN, GHS	Future
Mock	mock	All	All	All	Testing only

Set WARIMCP_MODE=mock to route all providers through the mock provider (no API keys needed).

API Endpoints

All payment/payout endpoints require an X-Api-Key header. Generate keys with npm run db:seed-api-key.

Method	Path	Auth	Description
GET	/health	No	Health check
GET	/api/v1/providers	No	List all providers and their config status
POST	/api/v1/payments/initiate	Yes	Initiate a payment (returns checkout URL)
GET	/api/v1/payments/:id	Yes	Verify payment status
POST	/api/v1/payments/:id/refund	Yes	Full or partial refund
GET	/api/v1/payments	Yes	List transactions (filterable by provider, status)
POST	/api/v1/payment-links	Yes	Generate a shareable payment link
POST	/api/v1/payouts/initiate	Yes	Disburse to mobile money or bank
GET	/api/v1/payouts/:id	Yes	Verify payout status
POST	/api/v1/webhooks/:provider	No	Inbound webhook receiver (signature-verified)

MCP Tools

When registered as an MCP server, WariMCP exposes these tools to AI agents:

Tool	Description
list_providers	List all providers, their config status, and supported rails
initiate_payment	Start a payment via any provider — returns a checkout URL
verify_payment	Check the status of a payment by transaction ID
refund_payment	Issue a full or partial refund
list_transactions	List recent transactions with provider/status filters
generate_payment_link	Create a shareable payment link
initiate_payout	Disburse funds to a mobile money wallet or bank account
verify_payout	Check the status of a payout

MCP Registration

{
  "mcpServers": {
    "warimcp": {
      "command": "node",
      "args": ["/path/to/warimcp/dist/index.js"],
      "env": {
        "WARIMCP_TRANSPORT": "stdio",
        "DATABASE_URL": "postgresql://warimcp:yourpass@localhost:5432/warimcp",
        "FEDAPAY_SECRET_KEY": "sk_live_..."
      }
    }
  }
}

Security

• Helmet with Content-Security-Policy (default-src 'self', no inline scripts)
• Timing-safe HMAC verification for CinetPay and Wave webhooks (crypto.timingSafeEqual)
• HMAC-SHA256 signed webhook relay — outbound relays include X-WariMCP-Signature header
• API key auth with SHA-256 hashed storage, per-key permissions, and per-key rate limits
• Token bucket rate limiting — 60 req/min default per API key
• Error sanitization — provider errors are caught and rewritten; internal details never leak to clients
• Non-root Docker user — container runs as dedicated warimcp user (UID 1001)
• Zod validation on all inputs with strict schemas (amount bounds, phone format, UUID checks)

No Custody (Bring Your Own Keys)

WariMCP holds no funds and ships no credentials. It only instructs licensed payment service providers; money settles directly into the account that the keys belong to — never an intermediary account. Each operator runs their own instance with their own PSP credentials and is the merchant of record, responsible for their own licensing and regulatory compliance.

An earlier "manual payment collection" feature (which routed funds into a personal mobile-money account with SMS reconciliation) was removed in 2026-06 as incompatible with this no-custody posture. Do not reintroduce custody of third-party funds.

Configuration

All configuration is via environment variables (see .env.example):

# Mode: mock | sandbox | live
WARIMCP_MODE=mock

# Transport: stdio | http | both
WARIMCP_TRANSPORT=both
WARIMCP_PORT=3000

# Database
DATABASE_URL=postgresql://warimcp:changeme@localhost:5432/warimcp

# Primary — FedaPay
FEDAPAY_SECRET_KEY=
FEDAPAY_PUBLIC_KEY=

# Secondary — Hub2
HUB2_API_KEY=

# Other providers (configure as needed)
CINETPAY_API_KEY=
CINETPAY_SITE_ID=
WAVE_API_KEY=
WAVE_WEBHOOK_SECRET=
FLUTTERWAVE_SECRET_KEY=
FLUTTERWAVE_PUBLIC_KEY=
KKIAPAY_PUBLIC_KEY=
KKIAPAY_PRIVATE_KEY=
KKIAPAY_SECRET=
MONEROO_SECRET_KEY=
MTN_MOMO_COLLECTION_SUBSCRIPTION_KEY=
MTN_MOMO_API_USER=
MTN_MOMO_API_KEY=
MTN_MOMO_ENVIRONMENT=sandbox
MTN_MOMO_CALLBACK_URL=
PAPSS_API_KEY=

# Webhooks
WARIMCP_WEBHOOK_BASE_URL=
WARIMCP_RELAY_SECRET=

Docker Deployment

# Set DB_PASSWORD in .env, then:
docker compose up -d

Runs two containers on the npm_proxy network:

• warimcp — Node 22 Alpine, non-root, 512 MB limit, health-checked at /health
• warimcp_db — PostgreSQL 16 Alpine, 256 MB limit, persistent volume

The HTTP transport is used in Docker (WARIMCP_TRANSPORT=http). For MCP stdio access, run the server directly with node dist/index.js.

Roadmap

Phase 1 (current): FedaPay as primary aggregator + Hub2 as secondary. All 10 provider adapters implemented. No-custody, bring-your-own-keys posture.

Phase 2: CinetPay + Wave activation once RCCM is filed. Full webhook verification for all active providers. Automatic provider fallback (FedaPay -> Hub2 -> CinetPay).

Phase 3: PAPSS pan-African corridor (CI to KE/NG/GH). Multi-currency settlement. Bulk payouts.

License

MIT