Monnify DevKit

The missing developer toolkit for Monnify: scaffold, test, and debug payment integrations from your terminal. Sandbox only, by design.

Built for the APIConf Lagos 2026 × Monnify Developer Challenge.

Why

Testing a Monnify webhook handler today means: deploy your server or set up a tunnel, complete a real checkout in the browser, wait for the webhook, dig through logs, repeat. And when signature verification fails, nothing tells you why.

This CLI collapses that loop to one command.

Install

npm install -g monnify-devkit

Or run without installing: npx monnify-devkit <command>

Quickstart

monnify login     # prompts for your keys; the secret is masked, never in shell history
monnify banks     # confirm everything works

Fire a correctly signed fake payment webhook at your local handler. No deploy, no checkout, no waiting:

monnify trigger SUCCESSFUL_TRANSACTION --forward-to http://localhost:3000/webhooks --amount 5000

Don't have a handler yet? Scaffold one with signature verification done right:

monnify init my-app
cd my-app && npm install
MONNIFY_SECRET_KEY=<your sandbox secret> npm start

Commands

| Command | Purpose | |---|---| | login / logout / whoami | Manage sandbox credentials (stored with 600 permissions, verified live) | | init [dir] | Scaffold an Express app with a signature-verifying webhook handler | | banks | List supported banks and codes | | testcards | Show sandbox test cards (no-OTP, OTP, 3DS, failing) without leaving the terminal | | resolve <account> <bank-code> | Look up an account name before sending money to it | | explain <error or code> | Look up any Monnify error (D05, R2, "duplicate reference") and get the meaning plus the fix, from the official error reference | | transfer <amount> --to --bank --source | Sandbox payout with a name-checked destination and a confirmation prompt | | transfer-status <ref> / balance <wallet> | Track transfers and check wallet balance | | tx list / tx get <ref> | Query sandbox transactions | | pay <amount> | Create a real sandbox payment, get the checkout URL | | trigger <event> --forward-to <url> | Send a simulated, correctly-signed webhook to your handler | | listen [--forward-to <url>] [--tunnel] [--verbose] | Local receiver: print events, verify signatures, forward. --tunnel exposes it publicly so real sandbox webhooks reach your laptop (works best with cloudflared installed; falls back to localtunnel); --verbose prints full payloads | | replay [--last N \| --id <id>] | Re-send stored events to test your idempotency handling | | verify <file> [--against <sig>] | Debug signature mismatches, with likely-cause diagnosis | | events | Show the local event delivery log |

Most read commands accept --json for machine-readable output, and every command documents its full flags via monnify <command> --help.

trigger supports all 13 event types Monnify documents: collections, rejected/underpayment, offline payments, disbursements (success, failed, reversed), refunds, settlements, mandate updates, wallet activity, and low-balance alerts. Run monnify trigger --list for the catalog, and override any payload field with --override key=value.

How signing works

Monnify signs webhooks with HMAC-SHA512 over the raw request body bytes, hex-encoded, in the monnify-signature header. The most common integration bug is verifying against a re-serialized body instead of the raw bytes. monnify verify detects exactly that case and tells you.

Every simulated webhook this tool sends is signed with your own sandbox secret using the same scheme, so your handler's verification code is exercised for real.

Payload shapes follow Monnify's webhook event docs, and the signing scheme plus SUCCESSFUL_TRANSACTION shape have been validated against a real captured sandbox webhook (delivered via listen --tunnel, signature verified). Real card-payment events carry two extra fields, cardDetails (masked PAN, bin, expiry) and paymentScope. Simulate them with --override if your handler depends on them.

Safety

• Sandbox only: the base URL is hard-coded and login rejects non-MK_TEST_ keys
• Credentials live in ~/.monnify/config.json (permissions 600), never in the repo or your shell history
• The webhook simulator runs entirely on your machine

Development

npm install
npm test            # vitest: signing golden vectors, payload builders
npm run typecheck
npm run dev -- <command>

Roadmap

Refund and direct-debit commands, bulk transfers, bills payment, production mode behind an explicit opt-in flag.

Team

Built by Tawakalt Raheem and Taofiq Aiyelabegan for the APIConf Lagos 2026 Monnify Developer Challenge.

License

MIT