paystack-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@paystack-mcp list my recent Paystack transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
paystack-mcp
MCP connector for the Paystack API aimed at the Accounts Team bots: Payment Matcher, Invoice Desk, Collections Desk, and Billing Support.
Paystack's official MCP (@paystack/mcp-server) is a public preview. It exposes two generic tools and rejects sk_live_ at startup. This connector is built for production use with live keys, but only after an explicit opt-in, and it still refuses to move money unless two further switches are on.
Read-only by default. Writes are dry-run previews until confirm: true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Nothing is retried.
Setup
cd paystack
npm ci
npm run buildstdio (what a Grok Bot or other MCP client launches):
{
"mcpServers": {
"paystack": {
"command": "node",
"args": ["/absolute/path/paystack/dist/index.js"],
"env": {
"PAYSTACK_SECRET_KEY": "sk_test_..."
}
}
}
}Put the secret in the MCP client's env block, not in chat. Leave the write and money switches unset until the owner has said yes.
Related MCP server: paystack-mcp-server
Environment
Variable | Required | Default | Purpose |
| yes |
| |
| no | off | Must be the exact string |
| no |
| Origin only. |
| no | off | Exact |
| no | off | Exact |
| no | 60 | Local cap. Paystack |
| no | 20000 | Per request. |
| no | 0 | Cache GET responses. Payments stay uncached unless you set this. |
| no | Contact string in the User-Agent. | |
| no |
|
|
| no | 3000 | HTTP listen port when transport is |
1, yes, and TRUE do not enable a switch.
Live keys
sk_test_…is accepted with no extra flag.sk_live_…is refused unlessPAYSTACK_ALLOW_LIVE_KEY=true.pk_…is refused. A public key is not a secret.If
PAYSTACK_BASE_URLis loopback (127.0.0.0/8,localhost, or::1), ansk_live_key is refused even when the opt-in is set. A live key is never sent to a mock.A non-https base URL is refused unless the host is loopback.
The default base URL is fixed at https://api.paystack.co. Test and live modes are selected by the key, which is how Paystack works.
Safety model
Every operation is tagged read, write, or money in spec/api-inventory.json. The generator emits a distinct TypeScript type for each. A money operation carries moneyGate: "PAYSTACK_ALLOW_MONEY_MOVEMENT". requireMoneyCheck rejects a money operation that does not have that brand, and a write or read operation is not assignable to the money type.
Risk | When a request is sent |
read | Immediately. Includes |
write |
|
money | Both of the write conditions, plus |
Confirm false or omitted is a preview (blocked: false). A missing env switch is a preview with blocked: true.
What counts as money
These debit, refund, or pay out, so they are money:
POST /transaction/charge_authorizationPOST /transaction/partial_debitPOST /refundPOST /transfer,POST /transfer/finalize_transfer,POST /transfer/bulk
POST /transaction/initialize does not debit by itself. It creates a charge flow (an authorization URL the customer can pay). That is money movement, so initialize is money and needs PAYSTACK_ALLOW_MONEY_MOVEMENT.
Creating or notifying a payment request does not debit a saved card. Those stay write. Resolving a dispute as merchant-accepted can cause Paystack to refund the customer. That action stays write, because the refund is the dispute outcome rather than POST /refund. The preview says so. Treat it as financially sensitive.
Amounts, currency, idempotency
Amounts are positive integers in the subunit Paystack expects. This connector does not convert major units.
Currency | Unit to send |
NGN | kobo (100 = 1 NGN) |
GHS | pesewas (100 = 1 GHS) |
ZAR, KES, USD, EGP | minor unit (100 = 1 major) |
XOF | ISO 4217 has no minor unit. Pass the positive integer Paystack shows for XOF. Confirm it on the dashboard before a money call. |
Currency is one of NGN, GHS, ZAR, KES, USD, XOF, EGP.
List endpoints accept perPage, page, use_cursor, next, and previous where Paystack paginates that way. perPage and page are integers from 1 to 200.
Paystack dedupes charges and transfers with the reference you send. Pass a new reference for a new attempt and reuse it if you are retrying the same one. This connector does not invent an Idempotency-Key header; Paystack's documented idempotency for these calls is reference.
Redaction
The secret key is stripped from logs, errors, and previews in exact, percent-encoded, JSON-escaped, and Authorization: Bearer forms. Authorization codes, signatures, OTPs, BVNs, document numbers, and webhook secrets are removed. Bank and card account numbers in responses are masked to the last four digits. The webhook tool never returns the key or the digest.
Tools
Twelve tools. Eleven talk to Paystack. paystack_webhook stays on the machine.
Tool | Actions (risk) |
| list, fetch, verify, timeline, totals, export (read); initialize, charge_authorization, partial_debit (money) |
| list, fetch (read); create, update, validate, set_risk_action (write) |
| list, fetch, verify, totals (read); create, update, notify, finalize, archive (write). Paystack calls these payment requests. |
| list, transactions (read) |
| list, fetch (read); create (money) |
| list, fetch, transaction, export (read); update, evidence, resolve (write) |
| list, fetch, verify (read); initiate, finalize, bulk (money) |
| list, fetch (read); create, update, delete (write) |
| balance, ledger (read) |
| banks, resolve_account, countries, states (read); verify_account (read lookup, |
| subaccounts, plans, subscriptions, products, payment pages, list and fetch only (read) |
| verify_signature (local). HMAC-SHA512 of the raw body with the secret key, constant-time compare to |
set_risk_action takes allow (whitelist) or deny (blacklist). Banks accept country=ghana and type=mobile_money for MoMo.
Examples
Payment Matcher, twice-daily feed. Reads only:
{ "action": "list", "perPage": 50, "page": 1, "status": "success", "currency": "GHS" }Tool: paystack_transactions. Then verify on the reference, paystack_settlements list, and paystack_balance balance. For a MoMo credit, paystack_lookups banks with country ghana and type mobile_money.
Invoice Desk, draft a payment request. First call omits confirm and returns a preview. After the owner says yes, and only if PAYSTACK_ALLOW_WRITES=true:
{
"action": "create",
"confirm": true,
"customer": "CUS_example",
"amount": 15000,
"currency": "GHS",
"description": "Repair job 104, balance after deposit"
}Tool: paystack_invoices. 15000 pesewas is 150 GHS.
Collections Desk, prepare a refund and do not send it. With the money switch off, confirm: true still previews:
{ "action": "create", "confirm": true, "transaction": "1001", "amount": 5000, "currency": "GHS" }Tool: paystack_refunds. The preview names PAYSTACK_ALLOW_MONEY_MOVEMENT when that switch is off. Dispute reads use paystack_disputes list so chasing can stop.
Billing Support, after an identity check that this connector does not perform. Reads only:
{ "action": "fetch", "code": "CUS_example" }Tool: paystack_customers, then paystack_invoices fetch and paystack_transactions verify. This bot does not refund and does not call money actions.
Webhook check, no network:
{
"action": "verify_signature",
"raw_body": "{\"event\":\"charge.success\"}",
"signature": "<hex from x-paystack-signature>"
}Tool: paystack_webhook.
Coverage and exclusions
spec/api-inventory.json is hand-written from the Paystack API reference and the endpoint table in PaystackOSS/paystack-python. Purposes are original wording. node scripts/gen-operations.mjs --check (part of npm run ci) regenerates src/operations.ts and paystack.routes.json and fails if they drift.
Mapped: 64 routes (42 read, 15 write, 7 money). Excluded: 56 routes, including the interactive charge API (PIN, OTP, card data), bulk charge, dedicated virtual accounts, splits, subscription and plan writes, transfer OTP disable, and product or page writes. The full list with reasons is in the inventory.
There is no single-settlement fetch in the PaystackOSS Python endpoint table. List settlements and GET /settlement/{id}/transaction are mapped.
Comparison
Server | Tools | Live keys | Confirm gate | Money gate |
PaystackOSS/paystack-mcp-server ( |
| Rejects | No | No |
kohasummons/paystack-mcp (MIT) | Named tools for products, customers, transactions (initialize, verify, fetch, list, charge, partial debit, totals, export), and bank, country, and state lists. |
| No | No |
samaxbytez/paystack-mcp ( | README claims 121 tools across transactions, charges, transfers, refunds, and disputes. | Accepts | No | No |
README describes ten future tools and human-in-the-loop writes. The published note says the surface is still landing. | Not a finished server to depend on. | Claimed, not shipped as a complete server | Claimed |
This connector trades breadth for gates: scoped actions, a live-key opt-in, a separate money switch, previews, and tests. It is not a wrapper around the official preview server.
Development
npm run cici is typecheck, lint, Vitest, build, and node scripts/gen-operations.mjs --check.
The live check does not call Paystack. See LIVE-CHECK.md.
/workspace/tools/paystack/start.sh
PAYSTACK_MOCK_PORT=$(cat /workspace/tools/paystack/mock.port) npm run live-check
/workspace/tools/paystack/stop.shProvenance
Inventory and wording are original, checked against Paystack's public API reference (retrieved 18 Nov 2026) and the PaystackOSS paystack-python endpoint table. No Paystack source is vendored. Official MCP behavior is from the Paystack MCP docs and the PaystackOSS/paystack-mcp-server README.
License
MIT. See LICENSE.
Available Tools
12 toolspaystack_balanceCRead-only
paystack_balance. Actions: balance (read), ledger (read). Read-only. Amounts are positive integers in subunits.
Inputs: action (required), to, from, next, +6 more.
paystack_catalogCRead-only
paystack_catalog. Actions: list_subaccounts (read), fetch_subaccount (read), list_plans (read), fetch_plan (read), list_subscriptions (read), fetch_subscription (read), list_products (read), fetch_product (read), list_pages (read), fetch_page (read). Read-only. Amounts are positive integers in subunits.
Inputs: action (required), id, code, next, +7 more.
paystack_customersBDestructive
paystack_customers. Actions: list (read), fetch (read), create (write), update (write), validate (write), set_risk_action (write). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), to, bvn, code, +19 more.
paystack_disputesADestructive
paystack_disputes. Actions: list (read), fetch (read), transaction (read), export (read), update (write), evidence (write), resolve (write). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), id, to, from, +16 more.
paystack_invoicesBDestructive
paystack_invoices. Actions: list (read), fetch (read), create (write), update (write), verify (read), notify (write), finalize (write), archive (write), totals (read). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), id, to, from, +15 more.
paystack_lookupsCRead-only
paystack_lookups. Actions: banks (read), resolve_account (read), countries (read), states (read), verify_account (read). Read-only. Amounts are positive integers in subunits.
Inputs: action (required), next, page, type, +13 more.
paystack_recipientsBDestructive
paystack_recipients. Actions: list (read), fetch (read), create (write), update (write), delete (write). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), to, code, from, +13 more.
paystack_refundsADestructive
paystack_refunds. Actions: list (read), fetch (read), create (money). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), id, to, from, +12 more.
paystack_settlementsCRead-only
paystack_settlements. Actions: list (read), transactions (read). Read-only. Amounts are positive integers in subunits.
Inputs: action (required), id, to, from, +8 more.
paystack_transactionsBDestructive
paystack_transactions. Actions: list (read), fetch (read), verify (read), timeline (read), totals (read), export (read), initialize (money), charge_authorization (money), partial_debit (money). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), id, to, from, +20 more.
paystack_transfersADestructive
paystack_transfers. Actions: list (read), fetch (read), verify (read), initiate (money), finalize (money), bulk (money). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.
Inputs: action (required), to, otp, code, +16 more.
paystack_webhookARead-onlyIdempotent
Verify an x-paystack-signature header locally. HMAC-SHA512 of the raw body with the configured secret key, compared in constant time. No network call. The key is never returned.
Inputs: action (required), raw_body (required), signature.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Tools are cleanly partitioned by resource domain (transactions, transfers, refunds, customers, disputes, etc.), so an agent can map intent to tool easily. There is minor overlap where 'verify' appears in transactions, invoices, transfers, and lookups, and where catalog bundles subscriptions/plans/products/pages/subaccounts, but descriptions make the target clear.
Every tool follows the same paystack_<resource> snake_case convention with a consistent prefix. The action-level verbs (list, fetch, create, update, verify) are applied uniformly inside each tool, giving a predictable structure throughout.
Twelve resource-grouped tools sit squarely in the well-scoped range, and each earns its place by covering a distinct Paystack domain. The grouping into action-dispatched tools keeps the count compact without omitting major areas.
Core money and lifecycle flows are covered: transactions, transfers, refunds, invoices, recipients, disputes, settlements, customers, plus webhook signature verification. The main gap is that paystack_catalog is read-only, so plans, products, pages, subaccounts, and subscriptions cannot be created or updated, and payment-page creation is absent.
Maintenance
Related MCP Connectors
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Nigeria payments for AI agents — bank transfer / USSD via Paystack. Never holds funds.
Connect AI agents to bank accounts, transactions, balances, and investments.
Stripe payments for AI agents. Create links, verify, manage customers.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with multiple payment providers (Stripe, Paystack) through a unified API. Supports payment initialization, verification, refunds, customer management, and invoicing without requiring knowledge of specific provider implementations.2-

paystack-mcp-serverofficial
AlicenseAqualityDmaintenanceEnables AI assistants to interact with the full range of Paystack APIs, allowing operations like transaction management, customer creation, and payments through natural language.294 npm56MIT- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to accept payments, verify transactions, and manage customers via Paystack API through natural language.MIT
- AlicenseBqualityDmaintenanceEnables AI agents to manage Paystack payments, products, customers, and transactions through natural language.289MIT